Multi-Agent Protocol (MAP)

A JSON-RPC based protocol for observing, coordinating, and routing messages within multi-agent AI systems.

Overview

Unlike protocols designed for single-agent interaction (ACP) or peer-to-peer agent delegation (A2A), MAP provides a window into a multi-agent system with visibility into its internal structure, agent relationships, and message flows.

MAP provides a standardized way for:

• Clients to observe and interact with agent systems (with configurable visibility)
• Agents to communicate, form hierarchies, and join scopes
• Systems to federate and route messages across boundaries

Protocol Landscape

Protocol	Relationship	Visibility	Primary Use
MCP	Agent → Tool	N/A	Tool invocation
ACP	Client → Agent	Opaque	Single-agent sessions
A2A	Agent → Agent (peer)	Opaque	Cross-org delegation
MAP	Client → System	Transparent	Internal orchestration

Packages

Package	Description
@multi-agent-protocol/sdk	TypeScript SDK for MAP

Quick Start

npm install @multi-agent-protocol/sdk

import { ClientConnection, createStreamPair } from '@multi-agent-protocol/sdk';

// Connect to a MAP server
const client = new ClientConnection(stream, { name: 'My Client' });
await client.connect();

// Subscribe to events
const subscription = await client.subscribe({
  eventTypes: ['agent.registered', 'agent.state.changed'],
});

for await (const event of subscription) {
  console.log(event.type, event.data);
}

Features

Core:

• Real-time streaming - Subscribe to events with backpressure support
• Auto-reconnection - Exponential backoff with subscription restoration
• Permission system - 4-layer access control (system, participant, scope, agent)
• Causal ordering - Events released in dependency order
• Agent registry & structure - Observe agents, relationships, and lifecycle (the "transparent window")

Staging extensions (optional, capability-negotiated — see the consolidation plan):

• Persistent identity - Stable agent identity across sessions (DID:key, SPIFFE, DID:web)
• Federation - Connect multiple MAP systems with envelope-based routing
• Mail, tasks, trajectory, workspace, credentials, resources, ACP tunneling - domain capabilities

MAP is consolidating around a small machinery core plus separately-versioned extensions. See docs/14-consolidation-plan.md and the extension registry for current stability and ownership.

Documentation

Schema

The protocol schema is defined in schema/:

• schema.json - Complete JSON Schema for all MAP message types
• meta.json - Method metadata, tiers, and error codes

Repository Structure

multi-agent-protocol/
├── docs/                   # Design specifications
├── schema/                 # JSON Schema and metadata
│   ├── schema.json         # Protocol message schemas
│   └── meta.json           # Method tiers and error codes
└── ts-sdk/                 # TypeScript SDK implementation
    ├── src/                # Source code
    └── docs/               # SDK-specific docs (gap analysis)

Development

# Install dependencies
npm install

# Build SDK
npm run build -w ts-sdk

# Run tests
npm test -w ts-sdk

# Type check
npm run typecheck -w ts-sdk

Protocol Methods

The protocol currently defines 59 methods across three tiers: 11 core, 15 structure, 33 extension. By stability label: 38 stable, 21 staging.

The consolidation plan (docs/14-consolidation-plan.md) recuts this to a 23-method machinery core plus separately-versioned extensions. The counts above are generated from schema/meta.json by scripts/method-counts.mjs; CI fails if they drift.

Core (Required): map/connect, map/disconnect, map/auth/refresh, map/send, map/subscribe, map/unsubscribe, map/agents/list, map/agents/get, plus map/session/* (slated to become the sessions extension)

Structure (Recommended): Agent lifecycle (register, spawn, unregister, update, stop, suspend, resume), scope management (scopes/create, join, leave, …), and structure/graph

Extensions (Optional, capability-negotiated): mail, tasks, trajectory, workspace, resources, credentials, federation, steering (map/inject), and ACP tunneling. Stability and ownership per the extension registry.

Persistent Agent Identity

MAP supports stable agent identities that persist across sessions, connections, and delegation chains. Identity is separate from capability (what you can do) and transient AgentId (which instance you are).

Supported identity standards:

• W3C DID:key (did:key:z6Mk...) - Self-certifying Ed25519 keypair identities
• CNCF SPIFFE (spiffe://trust-domain/path) - Workload/attested identities
• W3C DID:web (did:web:domain:path) - Domain-anchored decentralized identities

Key features:

• Agent resumption - reconnect and resume a previous agent by matching persistentId
• Pluggable identity verification via IdentityVerifier hook
• Progressive trust through W3C Verifiable Credential endorsements
• Identity propagation through spawn and federation
• Credential audit trail with persistentId

License

MIT

Authors

Created and maintened by the sudocode team.