Skip to content
· 8 min LIVE

Agents Can Finally Talk To Us - And We Built the Inbox That Proves What Was Said

EPIC-228 Agent Interaction Core, live on agentbadge.xyz: a durable inbox where external agents - anonymous, API-key, or DID-signed - submit idempotent requests that a human operator classifies, answers, or rejects. Bound sessions, terminal-state 409s, per-actor-before-global rate limits, and one append-only event log with PUBLIC (agent) and INTERNAL (attributed) projections.

AB
AgentBadge Team
Agency for the Agentic Web
Agents Can Finally Talk To Us - And We Built the Inbox That Proves What Was Said
🤖 For AI agents: Machine-readable: JSON Markdown llms.txt Agent Guide

Conversations with agents used to evaporate in chat channels. EPIC-228 ships an interaction core: POST /api/v1/agent/interaction + idempotency-key returns {requestId, statusUrl, sessionId}, requests move PENDING_REVIEW→IN_REVIEW→ANSWERED|REJECTED with 409 on terminal replay, idempotent replays bind actor AND canonical payload (409 actor_mismatch / 422 payload_mismatch), sessions are actor-bound isess_* ids, and every mutation lands in one transaction with an append-only event - PUBLIC projection for the agent, INTERNAL with full attribution for operators. Verified through two Arc Studio rounds plus a probe-bot confirmation that caught a %00-in-path 500 that only existed on Postgres.

The problem: conversations with agents evaporate

For a junior: our platform already lets agents pay for API calls, sign receipts, and read verified knowledge. But when an agent wants something a static endpoint can't give - "is this capability stable?", "your contract says X, is that right?", "I found a bug" - the answer used to be a human watching a chat channel. No persistence, no id, no proof of what was asked or answered, and no way for the agent to check back later.

This is part of the Arc campaign series. Previous published episode: a knowledge base that says "I don't know" instead of guessing (EPIC-229). This article is EPIC-228: the layer underneath it - how an agent's request gets in, gets threaded, and gets a human answer.

We wanted a real inbox. Not a chat, not a ticket system bolted on the side - a first-class API object an agent can hold onto: submit, receive an id, poll it, get a typed outcome.

The interaction lifecycle - a POST with an idempotency-key lands as PENDING_REVIEW, an operator moves it to IN_REVIEW, then it forks to ANSWERED or REJECTED; replays of terminal rows get 409; a side lane shows the append-only log split into PUBLIC and INTERNAL events

One row, one log, terminal states that stay terminal.

What shipped: one row, one log, three doors in

For a junior: think registered mail, not email. The agent submits a request with an idempotency-key; the server returns a requestId, a statusUrl, and a sessionId. The request then moves PENDING_REVIEW → IN_REVIEW → ANSWERED, with REJECTED as the honest terminal alternative. Retrying a finished request gets a 409, not a re-run.

Three properties carry the design:

  • Three identity tiers, one inbox. Anonymous agents get in through the same door as API-key holders and DID-signed agents - but their budgets differ. Rate admission checks the per-actor bucket before the global one, so a flood of rotating anonymous keys can't starve identified traffic, and a cheap IP lane runs before the expensive DID signature verification, not after.
  • Idempotency that means something. Replaying a key returns the original row - but only if the actor and the canonicalized payload match. Same key, different actor: 409 actor_mismatch. Same key, different body: 422 payload_mismatch. A changed session context is a changed payload.
  • Sessions are bound, not claimable. The server mints isess_* ids; a client-supplied session id can only be re-joined by the actor that started it. Squatting a server-prefixed id is refused; session fixation across actors doesn't join.

The replay verdict table - same key plus same actor plus same payload returns the original row, a different actor gets 409 actor_mismatch, a different payload gets 422 payload_mismatch, a changed session context is also a mismatch, and no key at all is a 400

The replay verdict table - what "idempotent" actually means here.

Three identity lanes feeding one inbox - a grey anonymous silhouette with a slow gauge, a robot with an API key at medium speed, and a passport-badged DID agent on the widest lane

One door, three budgets.

A vertical thread of four request cards sharing one glowing session-id tag, with a ledger strip on the right marking entries PUBLIC in green and INTERNAL in amber

A session thread, and the two projections of its log.

The human half: an operator console, not a magic responder

This is the honest part: nobody auto-answers. A human operator sees a FIFO queue at /admin/interactions, classifies each request against a closed vocabulary (intent, signal type, topics, demand signals, knowledge-gap flag), then responds or rejects. Classification is a vocabulary-validated patch - blank form fields mean keep, never erase; tri-state flags get an explicit marker so "unchecked" really means false.

Mutations are guarded the same way the public side is: an expired request returns 410 to the operator exactly as it does to the agent (no split-brain), a terminal request refuses re-mutation with 409, and every state change lands in one transaction alongside its append-only event - no row that says ANSWERED without the event that proves it.

Two views of the same truth

Every request produces append-only events - but there are two projections. The agent polling statusUrl sees PUBLIC events with its status and the answer, nothing else: no operator identity, no fingerprint, no internals. The operator sees the INTERNAL stream with full attribution - who classified what, when, and with which patch. The same append-only log serves both; the projection decides what's safe to show.

The older /api/requests/* inbox isn't orphaned either: it keeps answering with Deprecation/Sunset headers, enforces the same tenant isolation as the v1 route, and stamps its rows channel: "legacy" so the queue shows where a request actually came from.

What the audit cycle found - including in the auditor

Two rounds of Arc Studio review came back with zero Critical but six High and around nineteen Medium findings - rate-limit ordering, idempotency binding, DID pre-throttling, cursor pagination, session fixation, projection leaks. All remediated and re-verified.

The more interesting story is the confirmation round. Our deterministic probe-bot re-ran the whole attack surface and found three different species of bug:

  1. A real server bug on prod. %00 in a request id passed the local memory store as a clean 404 - and crashed the Postgres driver into a 500 in production. Fixed with a regex gate before the store layer, same class as an earlier ledger fix. This is exactly the kind of bug only a live probe run catches.
  2. A reflection bug. Our structured 404 echoed the raw request path into the JSON body - and into HTML unescaped. Removed and escaped.
  3. Hollow tests. The bot's own scenario contracts sent the wrong field names to admin mutations, which silently failed while deduplicated rows made the run green. An earlier "150/150 pass" had been partially empty for the lifecycle flows. Fixed the contracts - and now the flow actually submits, classifies, responds, and polls to ANSWERED.

We count the third category as the best find of the cycle: a regression suite that can't regress isn't a safety net, it's a prop.

Honest residuals

Operator review is intentionally human - auto-answering from verified knowledge is the next epic's job, not this one's. Anonymous and DID-signed reads are capability-URL: the unguessable request id is the read credential, documented as such. And rate limits are real on prod - our own probe runs get throttled, which we take as the feature working.

For AI agents: the interaction surface is public: POST https://agentbadge.xyz/api/v1/agent/interaction with a required idempotency-key header and a JSON body (type, text, optional context) returns {requestId, status, statusUrl, sessionId} - poll statusUrl or GET /api/v1/agent/requests/:id for the public projection. Anonymous and API-key identities are accepted; DID-signed requests get a higher budget. A 429 means retry later, not failed.

Read the arc: counterparty trust on x402 · verified knowledge for agents · agent commerce · agent trust layers · A2A settlement