A2A Mesh
TypeScript runtime and operational toolkit for building and operating Agent2Agent (A2A) systems: runtime lifecycle, registry-backed discovery, persistence, observability, secure MCP interoperability, CLI workflows, and conformance tooling.
=22.22.1 <25" />
Roadmap ·
Maturity report ·
OpenSSF evidence ·
Security assurance case
A2A Mesh is an independent TypeScript runtime and toolkit for the Agent2Agent (A2A) protocol. It is not an official Google, Linux Foundation, or a2aproject package.
Why A2A Mesh?
A2A Mesh is a TypeScript runtime and operational toolkit for building and operating A2A systems. It complements the official A2A SDKs with registry-backed discovery, task persistence, observability, security boundaries, MCP interoperability, CLI workflows, and conformance tooling.
The repository already runs loopback-only live interoperability checks with the official JavaScript and Python SDKs in both client/server directions. See Official SDK interoperability for the pinned versions, verified flows, and CI evidence.
Trust and Supply Chain
A2A Mesh keeps public trust evidence in docs/security/trust-evidence.md and release package verification evidence in docs/release/package-verification.md. The trust-related README badges link to workflow-backed signals: CI, docs, security, OpenSSF Scorecard, OpenSSF readiness, npm package metadata, license, and package-manager constraints. The DeepWiki badge is a documentation navigation link, not a project trust signal.
What It Provides
- A2A server runtime and client SDK for Agent Cards, JSON-RPC messages, tasks, artifacts, and status transitions.
- Registry components for local discovery and health polling.
- Adapters for OpenAI, Anthropic, LangChain, Google ADK, LlamaIndex, and CrewAI HTTP bridge flows when the optional peer dependency is installed.
- CLI commands for validation, discovery, sending messages, registry export/import, monitoring tasks, benchmarking, diagnostics, and scaffolding.
- MCP bridge, WebSocket transport, gRPC transport, and testing helper packages for repository-verified workflows.
- Runnable examples for authenticated servers, streaming, push notifications, registry tenancy, WebSocket, gRPC, MCP bridge, adapter templates, OpenAI-compatible providers, and a multi-agent registry discovery mesh.
Install
A2A Mesh publishes its supported stable release on the npm latest dist-tag. Unqualified package
references resolve that stable release. The historical alpha dist-tag remains available for older
prerelease builds but is not the recommended install channel. For repeatable automation, pin the
exact version currently reported by npm view @a2amesh/runtime@latest version.```bash
pnpm add @a2amesh/runtime
PowerShell:```powershell
pnpm add @a2amesh/runtime
Quickstart
Published stable package (0.18.2, verified 10 October 2026)
The current npm latest package supports the custom agent scaffold.
This flow was tested in a fresh directory, without cloning this repository:```bash
pnpm dlx @a2amesh/create-a2amesh@latest my-agent --adapter custom
cd my-agent
npm install
npm run build
npm run dev
PowerShell:```powershell
pnpm dlx @a2amesh/create-a2amesh@latest my-agent --adapter custom
Set-Location my-agent
npm install
npm run build
npm run dev
npm install is intentional for this published scaffold: pnpm 11 rejects
its unapproved esbuild lifecycle script. This custom scaffold does
not contain a pnpm verify command.
Prepared source 0.19.0 (not yet on npm)
The new credential-free production-demo generates two A2A agents,
registry discovery, SQLite persistence and bounded MCP verification. It exists
in source but is not supported by npm latest=0.18.2. After the
guarded 0.19.0 release is published and its registry metadata verified:```bash
pnpm dlx @a2amesh/create-a2amesh@0.19.0 my-demo --template production-demo
cd my-demo
pnpm install
cp .env.example .env
pnpm dev
In another terminal:
pnpm verify
PowerShell (after publication):```powershell
pnpm dlx @a2amesh/create-a2amesh@0.19.0 my-demo --template production-demo
Set-Location my-demo
pnpm install
Copy-Item .env.example .env
pnpm dev
# Separate terminal:
pnpm verify
This is release-candidate documentation, not a claim that 0.19.0
can currently be installed from npm.
CLI Examples```bash
a2amesh validate ./agent-card.json
a2amesh discover http://127.0.0.1:3000
a2amesh init demo-agent --adapter custom
a2amesh send http://127.0.0.1:3000 "hello"
a2amesh task status http://127.0.0.1:3000 task-123
a2amesh health http://127.0.0.1:3000 --timeout-ms 1000 --json
a2amesh conformance http://127.0.0.1:3000 --protocol-version 1.0 --json
a2amesh conformance-badge report.json --output badge.svg
a2amesh registry export --url http://127.0.0.1:3099 --output ./registry-export.json
a2amesh registry import --url http://127.0.0.1:3099 --input ./registry-export.json
a2amesh export-card http://127.0.0.1:3000 --output ./agent-card.json
a2amesh monitor http://127.0.0.1:3000 --cycles 3
a2amesh benchmark http://127.0.0.1:3000 --requests 25 --concurrency 5
a2amesh release-check
a2amesh doctor --json
a2amesh replay ./task-123.cassette.jsonl
a2amesh trust sign ./agent-card.json --key ./signing-key.pem --key-id my-key --output ./agent-card.signed.json
a2amesh trust verify ./agent-card.signed.json --trusted-key my-key:./public-key.pem
PowerShell:```powershell
a2amesh validate .\agent-card.json
a2amesh discover http://127.0.0.1:3000
a2amesh init demo-agent --adapter custom
a2amesh send http://127.0.0.1:3000 "hello"
a2amesh task status http://127.0.0.1:3000 task-123
a2amesh health http://127.0.0.1:3000 --timeout-ms 1000 --json
a2amesh conformance http://127.0.0.1:3000 --protocol-version 1.0 --json
a2amesh conformance-badge report.json --output badge.svg
a2amesh registry export --url http://127.0.0.1:3099 --output .\registry-export.json
a2amesh registry import --url http://127.0.0.1:3099 --input .\registry-export.json
a2amesh export-card http://127.0.0.1:3000 --output .\agent-card.json
a2amesh monitor http://127.0.0.1:3000 --cycles 3
a2amesh benchmark http://127.0.0.1:3000 --requests 25 --concurrency 5
a2amesh release-check
a2amesh doctor --json
a2amesh replay .\task-123.cassette.jsonl
a2amesh trust sign .\agent-card.json --key .\signing-key.pem --key-id my-key --output .\agent-card.signed.json
a2amesh trust verify .\agent-card.signed.json --trusted-key my-key:.\public-key.pem
Agent Plugin
The repository owns a product-level alpha plugin for safe endpoint validation, approved task operations, and bounded MCP consumption. The public @a2amesh/mcp package now provides the a2amesh-mcp stdio server command, while .mcp.json, Codex, VS Code, and OpenCode examples remain read-only by default. See Agent plugin plan for installation, upgrade, rollback, workflow support, and the separate catalog activation process.
Package List
| Package | Purpose |
|---|---|
@a2amesh/protocol |
Protocol types, Agent Card, Task, Message, Artifact, JSON schemas, compatibility fixtures. |
@a2amesh/runtime |
A2A client/server runtime, task lifecycle, streaming, push, auth hooks, storage, telemetry hooks. |
@a2amesh/registry |
Agent discovery, health, trust score, signed cards, registry API. |
@a2amesh/mcp |
Secure A2A ↔ MCP bridge plus the standalone a2amesh-mcp stdio server. |
@a2amesh/cli |
CLI binary a2amesh. |
@a2amesh/create-a2amesh |
Project scaffolder. |
A2A Protocol Compatibility
The implementation targets Agent2Agent protocol v1.0.0. See Compatibility for the supported Node.js, package, protocol, transport, optional peer, and deprecation policy matrix.
Security Defaults
- Public HTTP server mode must use authentication unless it is bound to loopback.
- A2A server and registry HTTP routes apply a per-client request limit by default.
- Remote fetches and callback URLs pass SSRF policy helpers.
- CORS and WebSocket origin checks fail closed when configured.
- CLI and bridge code avoid printing full auth headers or concrete secret values.
- Release publishing is owner-triggered only and uses npm Trusted Publishing/OIDC.
Supported Adapters And Transports
| Surface | Status | Verification |
|---|---|---|
| OpenAI adapter | Supported | Unit tests with fake provider objects. |
| Anthropic adapter | Supported | Unit tests with fake provider objects. |
| LangChain adapter | Supported | Unit tests with fake runnables. |
| Google ADK adapter | Supported | Unit and streaming tests. |
| LlamaIndex adapter | Supported | Unit tests with fake provider objects. |
| CrewAI HTTP bridge | Supported | Unit tests with local fetch mocks. |
| SSE streaming | Supported | Unit and integration tests. |
| WebSocket transport | Supported | Package tests. |
| gRPC transport | Kept as package surface | Build and package checks; see compatibility notes. |
| MCP bridge | Supported | Mapping tests. |
Documentation
- Install
- Compatibility
- Release process
- Dependency update policy
- Release integrity state machine
Docs site: https://oaslananka.github.io/a2amesh/
Contributing
See CONTRIBUTING.md for setup, validation, and pull request guidance.
Run pnpm run verify before submitting changes.
License
Apache-2.0. See LICENSE.
Repository maturity and governance
This repository is maintained as a professional open-source project. See the maturity and contribution documents for the current operating model:
- Repository maturity report
- Contributing guide
- Governance
- Maintainers
- Roadmap
- Security policy
- Support policy
- OpenSSF evidence
