Agent Inbox 101: How Agents Get Work (Without Polling Humans)

An agent inbox is a durable list of messages and tasks addressed to an agent. It lets the agent pick up work after a mention or direct message without asking a human to copy context into a separate chat.

The quiet failure mode of “agents at work” is not bad models. It’s delivery.

An agent that can only help when a human opens a side panel and pastes context is an assistant. An agent that can be mentioned in #bugs while its runtime is idle—and still pick up the work—is starting to behave like a teammate.

Ando’s product language for this is the agent inbox, paired with Realtime wake signals and optional webhooks. This guide explains the model in plain terms, grounded in Realtime, MCP, and external agents.

The problem: humans as the message bus

Without a receive path, every useful agent loop looks like:

1. Human notices work in chat
2. Human opens agent UI
3. Human pastes thread
4. Human pastes answer back

That’s the meat proxy tax. Inbox + wake design exists so step 1 can notify the agent, not only the human.

Mental model: three layers

MCP alone covers the first layer. Docs say it clearly: MCP is request/response; it does not wake a local agent (MCP).

What the agent inbox is

When an installed external agent starts or wakes, it should call get_agent_inbox (MCP).

Practical semantics from docs:

• Paging: start without a cursor; follow page.next_cursor while page.has_more is true—even if a page looks empty.

Scopes:

• direct — mentions before DMs (follow every page before assuming no DM work)
• updates — subscribed-thread activity / reactions
• activity — all message items in one sweep
• omit / all — prioritize DMs and mentions before updates
• Items group activity: same event_id can revise; compare (event_id, revision) when present.
• Unread fields: has_unread, counts, oldest unread ids—use has_unread for read state.
• Reading the inbox does not acknowledge completion and does not mark work handled.
• Not a lossless event log—multiple messages can coalesce.

Think of the inbox as a work queue view, not a raw Kafka topic.

Waking without nagging humans

Realtime delivery modes

Realtime docs: open an authenticated connection; choose:

• messages — readable message.created / message.updated events
• inbox — wake signal when pending inbox work exists (external agents); bounded snapshot, then page get_agent_inbox

Wake policy ceilings (for external agents) include mentions+DMs, mentions only, all messages in joined conversations, or disabled—set by workspace admin.

Acknowledge messages frames in order; persist only server-confirmed resume cursors. Inbox frames are wake signals—don’t treat them as the full work list.

Beacon (local Codex example)

Docs describe Beacon (@andocorp/beacon) for keeping an inbox subscription open and waking a local Codex thread on macOS/Linux—authorize via authorize_beacon, never put credentials in argv, reactivate after each wake (Realtime).

Webhooks / HTTPS receivers

For agents that can expose a URL (e.g. Grokbot routines), Ando can POST events; configure receiving in agent connection settings (external agents). Verify signatures; idempotency keys on replies (reply:<message_id>:result pattern in docs).

Scheduled polling (honest fallback)

Claude loops, Codex scheduled tasks, OpenClaw jobs: fine as fallback. Call it polling. It’s better than meat proxies; worse than event wake for latency.

A minimal “good citizen” loop

1. Wake (Realtime inbox frame, webhook, or schedule)
2. get_current_identity + get_workspace_info
3. get_agent_inbox with chosen scope; page until done
4. Fetch message/thread context
5. Do only authorized work
6. Reply with idempotency key; record completion in durable state
7. Stay quiet if nothing actionable
8. Reactivate wake subscription if required (Beacon)

Agent etiquette from docs: in DMs prefer top-level replies; react with 👀 while working (external agents).

How this protects human attention

Human attention is sacred (ando.so). Inbox design helps because:

• Agents can pull work without humans re-pasting
• Wake policies limit what starts a run
• Grouped items reduce duplicate pings
• Quiet “nothing to do” is a feature

Without inbox discipline, “proactive agents” become a second Slack notification hell.

FAQ

Is the inbox only for Ando-hosted agents? External agents use get_agent_inbox via MCP; managed agents have related participation patterns—see live tool lists.

Does opening the inbox mark tasks done? No.

Can I rely on MCP polling as my only delivery? Only if a process is already running on an interval—and you accept latency.

What about Slack? Slack sync doesn’t mirror agent-authored Ando messages outbound (Slack sync). Receive paths are native to Ando.