AgentAddress

AgentAddress v0.1

Give asynchronous work
somewhere to return.

AgentAddress creates a scoped identity with two sides: a public ingress for responses and a bearer-protected queue for the agent that will resume the work.

01 Create a return address

No account or API key is required for MVP provisioning. The response includes a read token exactly once, so persist it with the task state.

curl -X POST https://YOUR_HOST/api/v1/addresses \
  -H 'content-type: application/json' \
  -d '{"name":"flight quote","task_id":"task_7f2"}'
{
  "address": {
    "id": "addr_8c09…",
    "email": "amber-river-71a9d2@inbox.example.com"
  },
  "credentials": { "read_token": "aa_read_…" },
  "endpoints": {
    "inbox_url": "https://…/api/v1/inbox/addr_…/aa_ingress_…",
    "events_url": "https://…/api/v1/addresses/addr_…/events"
  }
}
Store the whole response. The read token cannot be recovered. The secret embedded in the inbox URL grants write-only delivery access; share it only with the party expected to respond.

02 Deliver an event

Any system can POST structured JSON to the generated inbox URL. Use an idempotency key when a sender may retry.

curl -X POST "$INBOX_URL" \
  -H 'content-type: application/json' \
  -H 'idempotency-key: vendor-reply-123' \
  -d '{
    "type": "quote.ready",
    "source": "travel_vendor",
    "data": {"total": 4200, "currency": "USD"}
  }'

A first delivery returns 202 Accepted. Reusing the same idempotency key returns the original event with duplicate: true.

03 Poll and resume

Events are ordered by a monotonically increasing sequence. Pass the last next_cursor as after. Set wait up to 25 seconds for long polling.

curl "$EVENTS_URL?after=0&wait=25" \
  -H "authorization: Bearer $READ_TOKEN"

After handling an event, acknowledge it with POST /api/v1/addresses/:addressId/events/:eventId/ack and the same bearer token.

Inbound email

Every address has an email identity under INBOX_DOMAIN. Resend sends verified email.received webhooks to the service, which resolves the recipient slug, retrieves the complete message, and queues it for the correct address.

Resend webhook URL
https://YOUR_HOST/api/v1/email/resend

Events
email.received
Deployment note. Set RESEND_API_KEY, RESEND_WEBHOOK_SECRET, and INBOX_DOMAIN in Render. The webhook signing secret is created when you add the webhook in Resend.

MCP

Connect an MCP client to https://YOUR_HOST/api/mcp. The stateless server exposes create_return_address, poll_events, and acknowledge_event. It supports the 2026-07-28 protocol and initialization compatibility with 2025 revisions.

{
  "mcpServers": {
    "agentaddress": {
      "url": "https://YOUR_HOST/api/mcp"
    }
  }
}

Queue semantics

Delivery

At-least-once. Senders should use idempotency keys and consumers should tolerate retries.

Ordering

Stable sequence ordering within one address. No ordering guarantee across addresses.

Retention

Events are retained for 30 days. Address expiration is optional, from 60 seconds to one year.

Credentials

Tokens are generated with secure randomness and stored only as SHA-256 hashes.