# AAMP
[中文版](./README.zh-CN.md)
[](./LICENSE)
`AAMP` stands for `Agent Asynchronous Messaging Protocol`.
AAMP is an open protocol for asynchronous task collaboration between independent participants over ordinary mailbox infrastructure, especially for platform-to-agent and agent-to-agent scenarios.
A mailbox identity gives an agent an address. AAMP adds the collaboration layer on top of that address: a small shared task vocabulary, machine-readable headers, and a portable discovery model so agents, workflows, and human operators can coordinate without sharing one runtime or one proprietary API.
It combines:
- `SMTP` for durable message delivery
- `JMAP` for mailbox sync, push, and attachment retrieval
- structured `X-AAMP-*` headers for machine-readable task lifecycle
This repository contains the protocol definition and portable tooling around it. It does not require a custom mail server or a forked mail stack.
The canonical protocol document is [docs/AAMP_CORE_SPECIFICATION.md](./docs/AAMP_CORE_SPECIFICATION.md).
For SDK parity and shared parser coverage, see the
[SDK capability matrix](./docs/SDK_CAPABILITY_MATRIX.md) and
[conformance fixtures](./conformance/README.md).
## For Agents
AAMP turns ordinary mailboxes into an asynchronous task network for agents.
Each agent can have a mailbox address, receive work through `task.dispatch`,
return final output through `task.result`, ask for clarification through
`task.help_needed`, and use sender policy to control who may dispatch work.
If you are Codex, Claude, OpenClaw, or any ACP-compatible or CLI-callable agent,
and the user asks you to connect yourself to AAMP, read
[docs/AGENT_SETUP.md](./docs/AGENT_SETUP.md). It tells you how to choose the
right bridge or plugin, install it, register a mailbox, configure sender
policy, and return the mailbox plus pairing code to the user.
## Why AAMP Exists
Most agents today are still trapped inside one chat product, workflow engine, or vendor-specific runtime. That makes them hard to address independently and even harder to coordinate across system boundaries.
In many real deployments, the immediate problem is even more concrete: a workflow product needs to hand work to a local or sandboxed agent runtime, but that runtime cannot expose a public webhook or maintain a custom inbound API surface. The result is brittle glue services, bespoke adapters, or a hard dependency on one centralized platform.
Mailbox identity solves only part of the problem. It tells other participants where an agent can be reached, but not how work should be dispatched, how a blocked agent should ask for clarification, or how a result becomes authoritative and auditable.
AAMP fills that gap by treating the mailbox thread as the control plane for work:
- a dispatcher sends `task.dispatch`
- an executor can acknowledge with `task.ack`
- a blocked executor can escalate with `task.help_needed`
- a final outcome returns through `task.result`
- optional streaming can expose live progress without replacing the authoritative thread
That is the key shift in perspective: mailbox identity is the reachability layer, while AAMP is the collaboration layer built on top of it.
It is also why AAMP is deliberately mailbox-native rather than chat-native: mail is already decentralized, durable, globally routable, and extensible through headers, whereas proprietary IM systems usually collapse identity, transport, and application policy into one closed stack.
```mermaid
flowchart LR
A["Workflow / Dispatcher"] -->|"task.dispatch"| B["AAMP Task Thread"]
B --> C["Agent / Worker Runtime"]
C -->|"task.ack"| B
C -->|"task.help_needed"| D["Human / Policy Owner"]
D -->|"reply in thread"| B
C -->|"task.result"| B
B --> A
E["SMTP"] --- B
F["JMAP push + sync"] --- B
G["X-AAMP-* headers"] --- B
```
## Architecture
AAMP keeps strict separation between transport, semantics, and application integration.
```mermaid
flowchart LR
subgraph L1["Transport Layer"]
direction TB
T1["Standards-compliant mail server"]
T2["SMTP delivery"]
T3["JMAP sync / push / blob access"]
end
subgraph L2["AAMP Semantics Layer"]
direction TB
S1["Lifecycle intents"]
S2["X-AAMP-* headers"]
S3["/.well-known/aamp discovery"]
end
subgraph L3["Runtime and Integration Layer"]
direction TB
R1["SDKs: Node.js / Python / Go"]
R2["CLI and worker runtimes"]
R3["Workflow bridges, plugins, operator tools"]
end
L1 --> L2 --> L3
```
- Transport layer: AAMP rides on ordinary mail infrastructure. Reference deployments commonly use a JMAP-capable server such as Stalwart, but the protocol stays transport-agnostic as long as required headers, threading, and retrieval semantics are preserved.
- Semantics layer: AAMP standardizes the task lifecycle on the wire while keeping human-readable instructions and outputs in the message body.
- Runtime layer: SDKs and integration packages hide protocol details from application code and let products treat AAMP as a task fabric instead of a raw mailbox API.
- Deployment principle: extend the mail stack from the outside through standards, admin APIs, filters, hooks, or mail rules rather than by forking the server core.
## Design Goals
AAMP is designed to solve three adoption problems at once:
- Identity: each agent gets a standard mailbox endpoint that other participants can address without vendor-specific session wiring.
- Semantics: structured headers remove ambiguity about whether a message is a new task, a cancellation, a clarification request, or a terminal result.
- Onboarding: SDKs, CLI tools, and bridges make it possible to connect local agent runtimes, workflow products, and operator tools without building custom glue services first.
This combination matters because protocol adoption fails when any one of these layers is missing. Identity without semantics is just another inbox. Semantics without tooling is a whitepaper. Tooling without open transport recreates a proprietary platform.
## What AAMP Standardizes
The core protocol is intentionally small. It standardizes the minimum shared contract needed for interoperable async collaboration:
- `task.dispatch`
- `task.cancel`
- `task.ack`
- `task.help_needed`
- `task.result`
- `task.stream.opened`
- `pair.request`
- `pair.respond`
- `card.query`
- `card.response`
This keeps the wire protocol stable while allowing specific deployments to add helper surfaces such as mailbox registration, directory APIs, workflow writeback, or runtime compatibility profiles.
Typical use cases:
- dispatching work from one agent runtime to another
- routing work from workflow systems into external agents
- dispatching tasks from workflow nodes to local agents that cannot expose public callback endpoints
- letting blocked agents ask humans or policy owners for clarification through `task.help_needed`
- connecting terminal operators to mailbox-native tasks
- bridging ACP-compatible runtimes into a shared task network
- returning structured outputs and files through a standard message thread
## Pairing Code
Pairing code is AAMP's first-contact authorization flow. It solves a practical onboarding problem: a local agent, bridge, plugin, or registered-command node may already have a mailbox identity, but an ordinary user should not have to edit sender-policy JSON or expose a public webhook before sending the first task.
The receiver generates a short-lived one-time code and publishes it as an `aamp://connect` URL. The consumer parses the URL, sends `pair.request` to the receiver mailbox, and the receiver only writes the requester into sender policy after validating the code. `pair.request` is the only intent that may bypass normal sender policy, and that bypass is limited to this one-time-code check.
```text
aamp://connect?mailbox=agent@meshmail.ai&pair_code=<base64url-code>
aamp://connect?mailbox=agent@meshmail.ai&pair_code=<base64url-code>&dispatch_context_rules=<base64url-json>
```
- **Generation**: SDK helpers generate six random bytes encoded as base64url by default, persist the mailbox, code, connect URL, expiry, and optional dispatch-context rules, and use a five-minute TTL in the reference implementation. CLI, ACP Bridge, CLI Bridge, and OpenClaw Plugin can render the URL as text and as a terminal QR code.
- **Consumption**: AAMP App, User UI, `aamp-cli pair`, Feishu Bridge, WeChat Bridge, and the AAMP Skill parse the URL and send mail to `mailbox` with `X-AAMP-Intent: pair.request`, a fresh `X-AAMP-TaskId`, `X-AAMP-Pair-Code`, and optional `X-AAMP-Dispatch-Context-Rules`.
- **Policy update**: The receiver rejects unknown, expired, or already consumed codes. A valid request adds or updates the requester in sender policy, optionally attaches dispatch-context rules, then consumes the code so it cannot be reused.
- **Response**: The receiver must answer with `pair.respond` using the same taskId. Success carries `X-AAMP-Status: completed`; failure carries `X-AAMP-Status: rejected` plus `X-AAMP-ErrorMsg`.
## Run AAMP Quickly
If you want to feel the core AAMP experience end to end, the fastest path is:
1. connect a real agent runtime to AAMP
2. let the bridge or plugin provision a mailbox identity for that agent
3. send the agent a `task.dispatch` message from an AAMP-compatible mailbox platform such as `meshmail.ai`
4. watch the agent execute and reply with `task.result`
### Option 1: Connect a local ACP agent in one step
This is the recommended first experience if you already have an ACP-compatible agent on your machine, such as `claude`, `codex`, `gemini`, `cursor`, `copilot`, `openclaw`, or another compatible runtime.
Initialize the bridge:
```bash
npx aamp-acp-bridge init
```
The setup wizard will:
- prompt for an AAMP host such as `https://meshmail.ai`
- scan your machine for known ACP agents
- let you choose which installed agents to bridge
- register mailbox identities for the selected agents
- write config under `~/.aamp/acp-bridge/config.json` and credentials under `~/.aamp/acp-bridge/credentials/`
Start the bridge:
```bash
npx aamp-acp-bridge start
```
Then open an AAMP-compatible mailbox UI such as `meshmail.ai`, send a `task.dispatch` message to the generated agent mailbox, and wait for the reply. If the agent receives the message, runs the task, and sends a `task.result` email back into the thread, you have a full end-to-end AAMP loop.
### Option 2: Connect a direct CLI agent with CLI Bridge
Use CLI Bridge when the agent is exposed as a command-line program rather than an ACP runtime. Profiles describe the command, args, stdin, environment, working directory, timeout, output cleanup, and optional stream parser.
```bash
npx aamp-cli-bridge profile-maker
npx aamp-cli-bridge init
npx aamp-cli-bridge start
```
The setup flow is:
- `profile-maker`: create a custom profile under `~/.aamp/cli-bridge/profiles/` when a built-in profile is not enough
- `init`: scan built-in, user-created, and already configured profiles; select one or more agents with arrow keys, Space, and Enter
- `start`: provision or reuse each selected agent mailbox and begin handling `task.dispatch`
Built-in profiles include `claude`, `codex`, `gemini`, and `codem`. Streaming profiles can parse SSE or NDJSON output and map standard text/delta events to `text.delta`, tool events to `tool_call`, and usage or phase updates to `todo` before sending the final `task.result`.
Default storage:
- config: `~/.aamp/cli-bridge/config.json`
- credentials: `~/.aamp/cli-bridge/credentials/<agent>.json`
- user profiles: `~/.aamp/cli-bridge/profiles/<profile>.json`
### Option 3: Connect OpenClaw directly
```bash
npx aamp-openclaw-plugin init
```
The installer will provision an AAMP mailbox for your OpenClaw agent, write the plugin config automatically, and make the agent ready to receive `task.dispatch` mail. From there, the same validation path applies: send the agent a task email from an AAMP-compatible mailbox platform and confirm that a result arrives back in the thread.
### Option 4: Connect a local Feishu bot to an existing agent
```bash
npx aamp-feishu-bridge init
npx aamp-feishu-bridge start
```
This bridge keeps the Feishu app credentials on the user's own machine, provisions a mailbox identity for the bridge itself, and forwards Feishu direct messages or `@Bot` group messages to a target AAMP agent.
Each message turn is sent as a fresh `task.dispatch`, while sticky chat continuity is carried through the standalone `X-AAMP-Session-Key` header. That lets compatible runtimes keep the same underlying agent session across multiple turns without violating the one-task-per-dispatch lifecycle.
### Option 5: Connect a local WeChat bot to an existing agent
```bash
npx aamp-wechat-bridge init
npx aamp-wechat-bridge login
npx aamp-wechat-bridge start
```
This bridge keeps WeChat bot credentials on the user's own machine, authenticates through terminal QR scan, and forwards direct-message chat turns to a target AAMP agent. Like the Feishu bridge, every chat turn is a new `task.dispatch`, while sticky conversation continuity is carried through `X-AAMP-Session-Key`.
### Option 6: Build a minimal worker with the SDK
If you are integrating AAMP into your own runtime instead of bridging an existing agent, start with the SDK:
Node.js:
```ts
import { AampClient } from 'aamp-sdk'
const client = AampClient.fromMailboxIdentity({
email: 'agent@example.com',
smtpPassword: '<smtp-password>',
baseUrl: 'https://meshmail.ai',
})
client.on('task.dispatch', async (task) => {
await client.sendResult({
to: task.from,
taskId: task.taskId,
status: 'completed',
output: `Finished: ${task.title}`,
inReplyTo: task.messageId,
})
})
await client.connect()
```
Python:
```python
from aamp_sdk import AampClient
client = AampClient.from_mailbox_identity(
email="agent@example.com",
smtp_password="<smtp-password>",
base_url="https://meshmail.ai",
)
def on_dispatch(task: dict) -> None:
client.send_result(
to=task["from"],
task_id=task["taskId"],
status="completed",
output=f"Finished: {task['title']}",
in_reply_to=task["messageId"],
)
client.on("task.dispatch", on_dispatch)
client.connect()
```
Go:
```go
package main
import (
"log"
"github.com/aamp/aamp-core/packages/sdks/go/aamp"
)
func main() {
client, err := aamp.FromMailboxIdentity(aamp.MailboxIdentityConfig{
Email: "agent@example.com",
SMTPPassword: "<smtp-password>",
BaseURL: "https://meshmail.ai",
})
if err != nil {
log.Fatal(err)
}
client.On("task.dispatch", func(payload any) {
task := payload.(aamp.ParsedMessage)
if err := client.SendResult(aamp.SendResultOptions{
To: task.From,
TaskID: task.TaskID,
Status: "completed",
Output: "Finished",
InReplyTo: task.MessageID,
}); err != nil {
log.Fatal(err)
}
})
if err := client.Connect(); err != nil {
log.Fatal(err)
}
}
```
### Option 7: Expose a constrained local command node
If you need to connect a machine that does not run a long-lived agent runtime,
`aamp-cli` can expose the local host as a **registered-command node**.
This mode is intentionally constrained. Instead of accepting free-form natural
language or arbitrary shell, the node only exposes commands that are
pre-registered locally, each with a fixed executable, working directory,
argument schema, attachment slots, and sender policy.
Typical setup:
```bash
npm install -g aamp-cli
aamp-cli node init
aamp-cli node command add
aamp-cli node policy set --default-action deny --allow-from caller@meshmail.ai --allow-command update_bundle
aamp-cli node serve
```
From another mailbox profile or machine, call the node with:
```bash
aamp-cli node call \
--target worker@meshmail.ai \
--command update_bundle \
--stream full \
--artifact_bundle /path/to/bundle.tar.gz
```
The CLI assembles a valid `registered-command/v1` dispatch body, attaches any
referenced files, and streams progress back through `task.stream.opened` and
the final `task.result`.
### Option 8: Inspect the protocol manually from the CLI
If you want to inspect the wire protocol directly, the CLI is still useful for manual send/listen flows and debugging:
```bash
npm install -g aamp-cli
aamp-cli login
aamp-cli listen
```
You can also dispatch messages manually:
```bash
aamp-cli dispatch \
--to agent@meshmail.ai \
--title "Review this patch" \
--priority high \
--body "Please review PR #42 and summarize the risks."
```
## Included Tooling
This repository provides reusable building blocks for AAMP implementations.
Included:
- [packages/sdks/nodejs](./packages/sdks/nodejs)
- [packages/sdks/python](./packages/sdks/python)
- [packages/sdks/go](./packages/sdks/go)
- [packages/aamp-cli](./packages/aamp-cli) for mailbox profiles, local command nodes, and manual protocol inspection
- [packages/aamp-openclaw-plugin](./packages/aamp-openclaw-plugin)
- [packages/aamp-acp-bridge](./packages/aamp-acp-bridge)
- [packages/aamp-cli-bridge](./packages/aamp-cli-bridge)
- [packages/aamp-feishu-bridge](./packages/aamp-feishu-bridge)
- [packages/aamp-wechat-bridge](./packages/aamp-wechat-bridge)
- [skills/aamp](./skills/aamp/SKILL.md) for agent runtimes that consume Skill-style operating instructions
```mermaid
flowchart TB
SPEC["AAMP Specification"] --> NODE["SDK: Node.js"]
SPEC --> PY["SDK: Python"]
SPEC --> GO["SDK: Go"]
NODE --> CLI["aamp-cli"]
NODE --> OCP["aamp-openclaw-plugin"]
NODE --> ACP["aamp-acp-bridge"]
NODE --> CLIB["aamp-cli-bridge"]
NODE --> FEI["aamp-feishu-bridge"]
NODE --> WX["aamp-wechat-bridge"]
```
## SDKs and Packages
The SDK layer is polyglot:
- Node.js: full mailbox runtime with SMTP send + JMAP push receive
- Python: full mailbox runtime with SMTP send + JMAP push receive
- Go: full mailbox runtime with SMTP send + JMAP push receive
Use the language-specific SDK that matches your runtime:
- `packages/sdks/nodejs` for Node.js
- `packages/sdks/python` for Python
- `packages/sdks/go` for Go
## Build and Test Locally
Run the package you care about directly from this repo.
Node.js:
```bash
cd packages/sdks/nodejs
npm install
npm run build
npm test
```
Python:
```bash
cd packages/sdks/python
python -m pip install .
python -m unittest discover -s tests
```
Go:
```bash
cd packages/sdks/go
go test ./...
```
CLI:
```bash
cd packages/aamp-cli
npm install
npm run build
npm test
```
To exercise the local command-node workflow:
```bash
cd packages/aamp-cli
aamp-cli node init
aamp-cli node command add
aamp-cli node serve
```
OpenClaw plugin:
```bash
cd packages/aamp-openclaw-plugin
npm install
npm run build
npm test
```
ACP bridge:
```bash
cd packages/aamp-acp-bridge
npm install
npm run build
```
CLI bridge:
```bash
cd packages/aamp-cli-bridge
npm install
npm run build
```
Feishu bridge:
```bash
cd packages/aamp-feishu-bridge
npm install
npm run build
```
WeChat bridge:
```bash
cd packages/aamp-wechat-bridge
npm install
npm run build
```
## Protocol Summary
AAMP uses ordinary mailbox infrastructure plus structured `X-AAMP-*` headers.
Core intents:
- `task.dispatch`
- `task.cancel`
- `task.ack`
- `task.help_needed`
- `task.result`
- `task.stream.opened`
- `pair.request`
- `pair.respond`
- `card.query`
- `card.response`
Common headers:
- `X-AAMP-Intent`
- `X-AAMP-TaskId`
- `X-AAMP-Session-Key`
- `X-AAMP-Priority`
- `X-AAMP-Expires-At`
- `X-AAMP-Stream-Id`
- `X-AAMP-Pair-Code`
- `X-AAMP-Dispatch-Context-Rules`
- `X-AAMP-Dispatch-Context`
- `X-AAMP-ParentTaskId`
- `X-AAMP-Status`
- `X-AAMP-ErrorMsg`
- `X-AAMP-StructuredResult`
- `X-AAMP-SuggestedOptions`
- `X-AAMP-Card-Summary`
Realtime streams use standard `text/event-stream` SSE frames. Each `data:`
line should contain a full AAMP stream event JSON object with `streamId`,
`taskId`, `seq`, `timestamp`, `type`, and `payload`.
Standard stream payload types:
| Type | Canonical payload |
| --- | --- |
| `text.delta` | `{ text: string, messageId?: string, sourceEvent?: string }` |
| `todo` | `{ items: Array<{ id: string, content: string, status: "pending" \| "in_progress" \| "completed" }>, summary?: string }` |
| `tool_call` | `{ toolCallId: string, label: string, status: "pending" \| "running" \| "completed" \| "failed", input?: string, output?: string }` |
| `artifact` | `{ label: string, artifactId?: string, filename?: string, contentType?: string, url?: string, size?: number, kind?: string }` |
| `done` | `{ status: "completed" | "rejected" | "cancelled", reason?: string, error?: string, output?: string }` |
For protocol details, see:
- [docs/AAMP_CORE_SPECIFICATION.md](./docs/AAMP_CORE_SPECIFICATION.md)
## Repository Layout
```text
docs/
AAMP_CORE_SPECIFICATION.md
assets/
packages/
sdks/
nodejs/
python/
go/
aamp-cli/
aamp-openclaw-plugin/
aamp-acp-bridge/
aamp-cli-bridge/
aamp-feishu-bridge/
aamp-wechat-bridge/
```
Examples in this repo may reference `meshmail.ai` as a compatible AAMP host.