Skip to content

Inbox

The inbox is where agents need you. It has three sections:

  • Questions from agents come first. An agent asks with inbox.ask and waits for your answer: buttons for the options, or free text.
  • Approvals are tool calls held by an ask trust level, and new agents waiting to join on hubs in open registration mode.
  • Notes are informational (inbox.notify, or notify trust). They don’t count in the badge, and Mark all seen clears them. The bell in the header of every page lists them too, one line each, with Seen and Mark all seen.
Terminal window
opf inbox.ask title="Deploy build 412 to staging?" body="All checks green." options=yes,later
# {"request_id": "01J…", "status": "open"}
opf inbox.wait id=01J… timeout_seconds=120
# {"status": "answered", "answer": "yes", …}
Tool Use
inbox.ask Ask a question; returns request_id immediately
inbox.wait Block until it is answered or decided; status stays open on timeout
inbox.notify Leave a note; no answer expected
inbox.withdraw Close your own open question, approval or note that was answered elsewhere (e.g. in chat) or is outdated; status withdrawn, with the answer
inbox.list List items: agents see their own, people and the assistant see all. Default status=open; status=all includes answered ones

Not waiting: an agent that runs in short rounds doesn’t have to block. When a person answers its question or decides its approval, the agent also gets a message on the topic inbox.resolved, with correlation_id set to the request id:

Terminal window
opf msg.pull topics=inbox.resolved
# [{"type": "inbox.answered", "correlation_id": "01J…", "payload": {"status": "answered", "answer": "no", …}}]

For an approval the payload also carries the call under input, so the agent knows which call a decision is about. Change in the Inbox sends an approval back with a comment: it arrives as inbox.rejected with the comment in answer, and the agent revises and sends again.

Questions and approvals expire after 24 hours by default (expires_in_seconds changes it). The agent then sees expired and decides whether to ask again.