Agent Doorbell

Routing and destinations

Retained inboxes and agent handoffs

Read retained messages independently of wakeups, track each reader, and link explicitly routed replies between agents.

When to use it

Use retained inboxes for a planner, builder, and reviewer handoff, independent specialist reviews, or recovery after a notification was consumed.

Example

A planner publishes a request to the builder. The builder reads it, saves a result, and publishes to the reviewer with replyTo set to the request message ID. The reviewer sends a correlated result to the planner. Each step routes by recipient and keeps its own retry key.

Set it up

  1. Connect agents with notifiers:read. Publishing additionally requires messages:publish; configuration writes require configuration:write and approval of the complete proposal.
  2. Discover named agents with list_agent_addresses. Read retainedInboxId for each activated address; receiver.destinationId identifies its separate notification queue or webhook receiver.
  3. If an agent is missing, follow Set up your first agent: save a draft, intentionally test its receiver, and approve activation. Empty external inputs are enough for direct named messages.
  4. Send with send_agent_message using to, text, and a stable idempotencyKey. Keep messageId from the receipt. inboxEntryCount records admission; intentCount records notification work. Reading retained content does not depend on notification delivery.
  5. Call read_retained_inbox with inboxId, a stable reader name, and after: 0 to resume that reader. Reading changes no progress. Process the returned entries in order and save durable results or recovery work.
  6. Call advance_retained_reader with the last position you actually handled. Continue with nextPosition for more pages. Never advance to highWater merely because it was returned; new arrivals or a page limit can leave unread messages below it.
  7. For a reply, call reply_agent_message with replyTo set to the available canonical parent ID and to set to the next approved agent. Doorbell inherits conversationId; correlation never chooses a recipient.
  8. For competing workers, receive_agent_message leases the address's notification. Acknowledge after durable handling. Retained reads remain independent and do not acknowledge or consume that lease.

Important limits

  • Messages expire seven days from acceptance; reading, notification delivery, or another inbox membership does not extend that lifetime. Revocation, erasure, or removal can make content unavailable sooner.
  • Reader names, sender labels, and recipients are customer-wide conventions, not private identities or access controls. Named readers do not claim work exclusively.
  • Use different reader names when every specialist must see the same message. Use notification leases when workers compete for one task. A lease, publish, reader advance, and acknowledgment are separate transactions, so duplicate effects remain possible.
  • Pausing an address preserves source capture, inbox membership, and retained content. Fresh save and activation resumes future notifications without replaying skipped arrivals. Source revocation blocks disclosure; regrant does not resurrect cancelled work or scrubbed content.
  • Rule edits apply to future arrivals. Backfill needs a bounded preview and approved commit, with notifications off by default. Notification replay is a separate authorized occurrence. Publication retries do neither.

Troubleshooting

  • If gap is true, inspect unavailableReason and missing positions. Expiry is one cause; revoked, erased, removed, or unavailable content can also cause a gap. Record the gap before explicitly deciding whether to skip it.
  • If another reader sees different progress, compare inboxId and reader. To browse earlier content without resuming saved progress, omit reader and provide an explicit after position.
  • If a reply has no inbox match, inspect its explicit recipient and source route. replyTo and conversationId provide correlation, not return routing or automatic workflow completion.
Technical reference

Planner, builder, reviewer: activate three named agents. Each receiver saves its work, sends the next explicitly addressed handoff with replyTo, then advances only the handled inbox position. Stop after the reviewer reports to the planner; Doorbell does not detect the workflow's end.

Coordinator, finance, security: use separate reader names to inspect one address's retained inbox independently. Each specialist sends a separately keyed result to the coordinator. The coordinator tracks required results and decides when reviews are complete; Doorbell provides no automatic join.

Dispatcher, worker, backup: workers share one named MCP receiver. One leases a signal; the backup cannot claim it while held. After a crash before acknowledgment, the backup can lease eligible work after expiry, fetch canonical content, deduplicate effects, and finish. A crash after acknowledgment does not requeue the signal.

get_retained_configuration is inspection, not a second setup interface. Configure inputs, capture, and notifications through save_agent_address. The Messages view browses retained inboxes and accepted publications without consuming notifications.

{
  "inboxId": "<retained-inbox-id>",
  "reader": "reviewer",
  "after": 0,
  "limit": 20
}
Open Agent Doorbell