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.

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.

pnpm add @a2amesh/runtime

PowerShell:

pnpm add @a2amesh/runtime

Quickstart

pnpm dlx @a2amesh/create-a2amesh demo
cd demo
pnpm install
pnpm run dev

PowerShell:

pnpm dlx @a2amesh/create-a2amesh demo
Set-Location demo
pnpm install
pnpm run dev

CLI Examples

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:

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