Asap Protocol

ASAP: Async Simple Agent Protocol

✨ From agents, for agents. Delivering reliability, as soon as possible.

> A production-ready protocol for agent-to-agent communication and task coordination.

Quick Info: v2.5.1 | Apache 2.0 | Python 3.13+ | [Documentation](docs/index.md) | [Changelog](CHANGELOG.md)

> 📦 Install — asap-protocol on PyPI (Python) · @asap-protocol/client on npm (TypeScript)

🚀 Live now our agentic marketplace — browse agents, register yours, request verification.

Why ASAP?

Multi-agent systems hit three walls that point-to-point agent protocols often leave open:

1. Connection sprawl — pairwise HTTP does not scale as orchestrators fan out.
2. State drift — long workflows stall without durable task state and resumability.
3. Fragmentation — delegation, artifacts, and MCP tool calls end up in incompatible layers.

ASAP answers with a schema-first protocol and reference SDKs in Python and TypeScript:

• Resumable orchestration — task state machine, snapshot store, SSE streaming, and built-in trace_id / correlation_id.
• One typed envelope — tasks, MCP tool execution, and artifact exchange on the same JSON Schema contract.
• Production trust — Ed25519 signed manifests, Host/Agent JWTs, constrained capabilities, OAuth2, opt-in WebAuthn — plus the MCP Auth Bridge (v2.5.0) for scoped native tools/call.
• Ecosystem-ready — agentic marketplace, Lite Registry, edge-AI discovery, OpenAPI import, and framework adapters ([Python & npm](#framework-ecosystem)).

Plain HTTP between two agents is enough for the simplest cases. ASAP is built for multi-agent orchestration, stateful workflows, and governed capability access in production — see [documentation](docs/index.md) and the feature table below.

Key Features

| Area | Highlights | Docs | | --- | --- | --- | | Stateful orchestration | Task state machine, snapshotting, resumable workflows | [State management](docs/state-management.md) | | Schema-first | Pydantic v2 + JSON Schema for cross-agent interchange | [API reference](docs/api-reference.md) | | Async-native | asyncio + httpx; sync and async handlers | [Transport](docs/transport.md) | | MCP integration | Tool execution and coordination in one envelope (Mode B) | [MCP integration](docs/mcp-integration.md) | | MCP Auth Bridge | Opt-in Agent JWT + capability grants on native stdio MCP tools/call (Mode A) | [MCP Auth Bridge](docs/adapters/mcp-auth-bridge.md) | | Observability | trace_id and correlation_id for debugging | [Observability](docs/observability.md) | | Security | OAuth2/JWT, Ed25519 manifests, mTLS, rate limiting | [Security](docs/security.md) | | Identity & capabilities | Host/Agent JWTs, constrained grants, approval flows, opt-in WebAuthn | [Capabilities](docs/capabilities/index.md) | | Streaming & wire protocol | SSE /asap/stream, JSON-RPC batch, ASAP-Version negotiation | [Transport](docs/transport.md) | | Adoption tools | OpenAPI adapter, @asap-protocol/client, auto-registration, escalation | [Migration (v2.2 → v2.3)](docs/migration.md#upgrading-from-v22x-to-v230) | | Edge-AI discovery | Hardware/inference manifests, registry mirror, marketplace filters | [ShellClaw guide](docs/guides/shellclaw-registry.md) | | Framework adapters (npm) | @asap-protocol/mastra and @asap-protocol/openai-agents tool bridges | [Mastra](docs/integrations/mastra.md) · [OpenAI Agents](docs/integrations/openai-agents.md) | | Economics | Usage metering, delegation tokens, SLA breach alerts | [Audit log](docs/audit.md) |

Full overview and upgrade paths: [docs/index.md](docs/index.md).

Framework Ecosystem

ASAP meets agents where they run — optional Python extras, npm tool bridges, and protocol-native MCP.

| Runtime | Integrations | Docs | | --- | --- | --- | | Python | LangChain, CrewAI, LlamaIndex, PydanticAI, SmolAgents, OpenClaw (pip install "asap-protocol[extra]"); Vercel AI SDK router; MCP; MCP Auth Bridge; A2H | [OpenClaw](docs/guides/openclaw-integration.md) · [Vercel AI SDK](docs/guides/vercel-ai-sdk.md) · [MCP](docs/mcp-integration.md) · [MCP Auth Bridge](docs/adapters/mcp-auth-bridge.md) | | TypeScript (npm) | @asap-protocol/client (Vercel AI / OpenAI / Anthropic adapters), @asap-protocol/mastra, @asap-protocol/openai-agents | [TypeScript SDK](docs/sdks/typescript.md) · [Mastra](docs/integrations/mastra.md) · [OpenAI Agents](docs/integrations/openai-agents.md) |

Installation

We recommend using uv for dependency management:

uv add asap-protocol

Or with pip:

pip install asap-protocol

TypeScript (npm, 2.4.1 — unchanged for v2.5.1; @asap-protocol/mcp-auth HTTP middleware still deferred):

• @asap-protocol/client — [SDK docs](docs/sdks/typescript.md)
• @asap-protocol/mastra — [docs](docs/integrations/mastra.md) · [demo](apps/example-mastra/README.md)
• @asap-protocol/openai-agents — [docs](docs/integrations/openai-agents.md) · [demo](apps/example-openai-agents/README.md)

npm install @asap-protocol/client@2.4.1
npm install @asap-protocol/mastra@2.4.1 @asap-protocol/client @mastra/core zod
npm install @asap-protocol/openai-agents@2.4.1 @asap-protocol/client @openai/agents zod

Python v2.5.1 (code quality patch): uv add asap-protocol or pip install asap-protocol==2.5.1 — see [Migration (v2.5.0 → v2.5.1)](docs/migration.md#upgrading-from-v250-to-v251).

Quick Start

Run the demo (echo agent + coordinator in one command):

uv run python -m asap.examples.run_demo

Build your first agent [here](docs/tutorials/first-agent.md) — server setup, client code, step-by-step (~15 min).

[19 examples](src/asap/examples/README.md): orchestration, state migration, MCP, OAuth2, WebSocket, resilience.

Testing

uv run pytest -n auto --tb=short

With coverage (separate run — do not combine with -n auto):

uv run pytest --tb=short --cov=asap --cov-report=term-missing --cov-fail-under=85

Testing Guide (structure, fixtures, property/load/chaos tests). Contributing (dev setup, CI).

Compliance Harness

Validate that your agent follows the ASAP protocol:

uv add "asap-compliance>=1.3.0"
pytest --asap-agent-url https://your-agent.example.com -m asap_compliance

For MCP Auth Bridge stdio gates (mcp-auth-bridge profile), use asap-compliance 1.3.0+ with asap-protocol 2.5.0+ — published on PyPI via tag v2.5.0.1.

See Compliance Testing Guide for handshake, schema and state machine validation.

Documentation

Learn

• [Docs](docs/index.md) | [API Reference](docs/api-reference.md)
• [MCP Auth Bridge](docs/adapters/mcp-auth-bridge.md) — v2.5.0 opt-in JWT + capability grants for native stdio MCP
• [TypeScript client SDK](docs/sdks/typescript.md) — @asap-protocol/client (identity, capabilities, streaming, adapters)
• Tutorials — First agent to production checklist
• Migration from A2A/MCP
• Raw Fetch (non-Python) — Fetch registry.json and revokedagents.json with curl/fetch; implement your own client.

Deep Dive

• State Management | Best Practices: Failover & Migration | Error Handling
• Transport | Security | Security Model (OAuth2 trust, Custom Claims)
• Identity Signing | Compliance Testing | Migration v1.1 to v1.2 | mTLS
• Observability | Testing

Decisions & Operations

• ADRs — 19 Architecture Decision Records
• Tech Stack — Rationale for Python, Pydantic, Next.js choices
• Deployment | Troubleshooting

Release

• Changelog | PyPI listing — https://pypi.org/project/asap-protocol/ (install: pip install asap-protocol)

CLI

asap --version                                    # Show version
asap list-schemas                                 # List JSON schemas
asap export-schemas                               # Export schemas to disk
asap validate-schema payload.json                 # Validate JSON against a schema
asap compliance-check --url https://agent.example # Remote Compliance Harness v2
asap audit export --store memory --format json    # Export audit log (stdout)
asap keys generate -o key.pem                     # Ed25519 keypair
asap manifest sign -k key.pem manifest.json       # Sign agent manifest
asap delegation create -d  -s read -k key.pem --delegator 
asap trace  --log-file asap.log         # Visualize request flow from logs

See [docs/cli.md](docs/cli.md) for delegation tokens, schema validation, trace visualization, REPL, and full flag reference. Run asap --help for your installed version.

Version History

High-level only — see Changelog and the docs index for full notes.

| Version | What shipped | | :-- | :-- | | v2.5.1 | Code quality patch — behavior-preserving refactor (transport/server, client, websocket, SQLite storage, auth, integrations) + six correctness/security fixes (atomic revoke_cascade, usage_events DDL, unified Host-JWT verifier, WS now enforces OAuth2, OpenAPI handler cleanup, client correlation_id binding). Deprecated import paths removed in v2.6.0. See [CHANGELOG](CHANGELOG.md#251---2026-06-25) and [Migration (v2.5.0 → v2.5.1)](docs/migration.md#upgrading-from-v250-to-v251) | | v2.5.0.1 | Compliance publish — GitHub Release v2.5.0.1 · PyPI asap-compliance 1.3.0 (mcp-auth-bridge profile; requires asap-protocol>=2.5.0). No asap-protocol API change. See [CHANGELOG](CHANGELOG.md#2501---2026-06-24) | | v2.5.0 | MCP Auth Bridge — GitHub Release v2.5.0 · opt-in protect_server for stdio MCP; Agent JWT + capability grants; reference example examples/mcp_auth_bridge/. See [CHANGELOG](CHANGELOG.md#250---2026-06-24) and [Migration (v2.4.1 → v2.5.0)](docs/migration.md#upgrading-from-v241-to-v250) | | v2.4.1 | Security hardening — OAuth2 iss/aud, fail-closed identity binding, web SSRF/redirect fixes, dependency bumps. See [CHANGELOG](CHANGELOG.md#241---2026-06-14) and [Migration (v2.4.0 → v2.4.1)](docs/migration.md#upgrading-from-v240-to-v241) | | v2.4.0 | Edge-AI discovery — optional hardware / inference manifest fields, registry mirror, marketplace filters, @asap-protocol/client@2.4.0, ShellClaw onboarding docs. See [CHANGELOG](CHANGELOG.md#240---2026-05-24) and [Migration (v2.3.x → v2.4.0)](docs/migration.md#upgrading-from-v23x-to-v240) | | v2.3.1 | npm TS patch — GitHub Release v2.3.1 · @asap-protocol/mastra, @asap-protocol/openai-agents, @asap-protocol/client@2.3.1 (additive adapter exports). Python 2.3.0 unchanged. See CHANGELOG and Migration (v2.3.0 → v2.3.1) | | v2.3.0 | OpenAPI Adapter ([openapi]) · TypeScript client (@asap-protocol/client) · Auto-Registration · Capability escalation · ASAP HTTP challenge — see CHANGELOG and Migration | | v2.2.1 | Opt-in WebAuthn (asap-protocol[webauthn]) · asap compliance-check & asap audit export · stricter ResolvedAgent.run() · AuditChainBroken · pinned security deps | | v2.2 | Per-runtime identity & capability auth · SSE POST /asap/stream · ASAP-Version · JSON-RPC batch · tamper-evident audit · async state stores · Compliance Harness v2 | | v2.1.1 | Patch: JWT allowlist · SQLite async bridge · optional Redis rate limits · web SSRF hardening | | v2.1 | MarketClient · framework extras (LangChain, CrewAI, LlamaIndex, …) · registry UX | | v2.0 | Marketplace web app · Lite Registry (GitHub Pages) · IssueOps · OAuth · verification flow | | v1.3 | asap delegation create / revoke | | v1.2 | Ed25519 manifests · trust levels · optional mTLS · Compliance Harness | | v1.1 | OAuth2 · WebSocket · discovery (well-known + Lite Registry) · SQLite state · webhooks |

🔭 What's Next?

The agentic marketplace and Lite Registry are live. The v2.5.x train focuses on interop and adoption:

• v2.5.2 — enterprise/workflow adapter spikes
• Distribution loop — homepage templates, starter kits, and lightweight adoption metrics
• @asap-protocol/mcp-auth (npm) — HTTP/SSE MCP middleware
• Formal spec track (v2.5.3+) — introspection, privacy, cross-protocol interop on the path to v3.0 economy

See the v2.5 roadmap PRD and ADR index.

Contributing

Community feedback and contributions are essential for ASAP Protocol's evolution. We're working on improvements and your input helps shape the fu

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: adriannoes
• Source: adriannoes/asap-protocol
• License: Apache-2.0
• Homepage: https://asap-protocol.com

Install and usage instructions live in the source repository linked above.