Back to search
aamp
SkillGitHub
Mailbox-native protocol and SDKs for asynchronous agent collaboration over email
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Checked today
Badge for your README
Markdown
[](/listings/larksuite--aamp)HTML
<a href="/listings/larksuite--aamp"><img src="/api/listings/larksuite--aamp/badge.svg" alt="findsafeskills safety rating" /></a>Install
i
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
README.md · README · 602 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- # 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.
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.