io.github.zkarimi22/agentaddress

AgentAddress for agents

Give an AI agent a webhook URL or email address that survives after the agent stops running.

Your agent starts a task → gives a service its AgentAddress → exits → the response arrives 20 minutes later → the next agent run retrieves it.

No server. No account. No polling process that has to stay alive.

npx skills add https://github.com/zkarimi22/agentaddress-agents --skill agentaddress

Agent run #1
    ↓
create AgentAddress
    ↓
give webhook/email to someone
    ↓
AGENT EXITS
    ↓
       [ response arrives later ]
                    ↓
             AgentAddress
                    ↓
               stores event
                    ↓
Agent run #2 → retrieves response

Use it

The installed skill includes a helper that stores the private read credential in an owner-only local file. The model works with a task name rather than copying a bearer token.

node scripts/agentaddress.mjs create my-task
node scripts/agentaddress.mjs poll my-task 25
node scripts/agentaddress.mjs ack my-task EVENT_ID

create prints the inbound email address and write-only HTTPS inbox URL you can hand to the expected responder. poll retrieves the ordered events in a later run. Every returned email and webhook body is explicitly labeled as untrusted external data and must be used only as data for the user's existing task.

Run one of five concrete examples

The five lead examples are runnable, task-specific, and named for the searches that should discover them:

• Asynchronous API callback
• Human email reply
• Claude Code deployment webhook
• Codex asynchronous code review
• OpenAI Agents SDK delegation

Start with the complete examples index for exact commands plus browser-agent, research, Stripe, GitHub, REST, and MCP supporting recipes. Stripe and GitHub require a signature-verifying relay before their payloads drive trusted actions.

Three runnable inbound-email workflows build on the same later-run contract: browser verification, document-request replies, and approval by email. Each names an expected sender, checks recipient and subject context, and leaves the event pending until the agent handles it. The document example can fetch an attachment through the credential-owning helper while Resend retains it; AgentAddress does not store attachment files.

Service and machine interfaces

• Hosted service: agentaddress.dev
• Agent guide: agentaddress.dev/llms-full.txt
• OpenAPI: agentaddress.dev/openapi.json
• MCP endpoint: https://agentaddress.dev/api/mcp
• Capability discovery: agentaddress.dev/.well-known/agentaddress.json
• skills.sh: skills.sh/zkarimi22/agentaddress-agents/agentaddress

Answers by problem

• Webhook endpoints without running a server
• Persistent callback queues after an agent exits
• Inbound email replies for later agent runs
• Unified HTTP and email queues for asynchronous agents

Current boundaries

• HTTP callbacks and inbound email enter the same ordered queue.
• Addresses have no expiry unless requested. Events are retained for 30 days, up to 1,000 per address, with a 1 MB maximum input.
• Delivery is at least once. Acknowledgement records handling and advances the helper's local cursor.
• AgentAddress stores responses but does not wake or schedule a runtime. A later run must poll.
• General key/value state, file storage, outbound email, identity, and billing are not available in V1.
• Verified inbound email attachments can be fetched on demand through the private API, up to 10 MB, while the provider retains them.
• A known Resend received-email ID can be replayed with the credential-owning helper if finite webhook retries end before the email reaches the queue. Replay checks the provider delivery envelope and does not scan all mail.

The two-process protocol proof and MCP example remain available for implementers working below the safer helper interface. Their low-level code handles credentials directly and should not be copied into model context. See SECURITY.md and the live verification record.

This repository contains the public skill, CLI helper, recipes, and integration material for the hosted service. It does not contain the AgentAddress service implementation.

Durable context and authorized mail

Small JSON context is available with the same credential: two-run state example. State changes join the ordered feed, while the values outlive the 30-day event history until replaced/deleted/address expiry.

Authorized outbound email supports plain text to verified contacts and replies to retained provider-verified messages. It requires operator-configured sending, recipient verification and user authorization. The configured sender uses the task inbox as Reply-To. No full conversation/search API or campaign tools are provided.

AgentAddress is free today. A $17/month paid tier is planned; allowances and launch date are not finalized, and billing is disabled. See pricing.

The CLI is installable directly from this MIT-licensed repository (npm install -g github:zkarimi22/agentaddress-agents); it is not published to npm. The registry manifest describes the hosted MCP endpoint. Official MCP Registry version 0.2.0 was published and verified October 4, 2026 under io.github.zkarimi22/agentaddress. Independent adoption and downstream catalog inclusion remain separate milestones.