@reaatech/agent-handoff-transport
Status: Pre-1.0 — APIs may change in minor versions. Pin to a specific version in production.
Transport layer implementations for delivering handoffs between agents. Includes MCP (tool-call-based), A2A (HTTP POST with retry), and a transport factory with health-check caching and priority-based auto-selection.
Installation
npm install @reaatech/agent-handoff-transport
# or
pnpm add @reaatech/agent-handoff-transportFeature Overview
- MCPTransport — handoffs via MCP
accept_handofftool calls with connection validation via ping - A2ATransport — handoffs via HTTP POST with exponential backoff retry and full jitter
- TransportFactory — priority-based auto-selection with 30-second TTL health cache
- Pluggable clients — inject your own
MCPClientorHttpClientimplementation - Payload limits — 10 MB (MCP) and 50 MB (A2A) max payload enforcement
- Snake-case mapping — MCP transport converts camelCase payload to expected snake_case args
Quick Start
import {
MCPTransport,
A2ATransport,
TransportFactory,
} from '@reaatech/agent-handoff-transport';
// MCP transport
const mcpTransport = new MCPTransport({
async callTool(params) {
return { accepted: true, responseCode: 200 };
},
async ping(serverId) { /* noop */ },
});
// A2A transport with auth
const a2aTransport = new A2ATransport({
async get(url) { return { status: 200 }; },
async post(url, body) { return { status: 200, data: body }; },
}, { authHeaders: { 'x-api-key': 'sk-abc123' } });
// Auto-select best transport
const factory = new TransportFactory([mcpTransport, a2aTransport]);
const transport = factory.getTransport(agentCapabilities);
// Returns highest-priority healthy transport for the agentExports
Transports
| Export | Priority | Protocol | Description |
|---|---|---|---|
MCPTransport | 1 | MCP | Tool-call-based handoffs via accept_handoff |
A2ATransport | 2 | HTTP | RESTful handoffs with retry and health checks |
MCPTransport
new MCPTransport(client: MCPClient)MCPClient Interface
| Method | Description |
|---|---|
callTool(params) | Invoke accept_handoff tool with snake_case payload |
ping(serverId) | Validate connection to MCP server |
The transport converts HandoffPayload to snake_case MCP tool-call arguments and parses the response. Connection validation uses ping. Max payload: 10 MB.
A2ATransport
new A2ATransport(client: HttpClient, options?: A2ATransportOptions)HttpClient Interface
| Method | Description |
|---|---|
get(url) | Health check via GET {endpoint}/health |
post(url, body) | Send handoff via POST {endpoint}/handoffs |
A2ATransportOptions
| Property | Type | Default | Description |
|---|---|---|---|
authHeaders | Record<string, string> | {} | Custom headers added to all requests |
Uses withRetry from @reaatech/agent-handoff for network errors and 5xx responses. Exponential backoff with full jitter. Max payload: 50 MB.
TransportFactory
new TransportFactory(transports: TransportLayer[], healthTtlMs?: number)| Method | Description |
|---|---|
getTransport(agent, preferred?) | Select transport by user preference or auto-detect |
registerTransport(transport) | Add a new transport layer |
unregisterTransport(name) | Remove a transport by name |
checkHealth(agent) | Pre-warm health cache for an agent |
getRegisteredTransports() | List all registered transport names |
Auto-selection: returns the highest-priority transport whose validateConnection returns true. Health results are cached with a 30-second TTL. Pass preferred: 'mcp' or preferred: 'a2a' to override auto-selection.
Related Packages
@reaatech/agent-handoff— Core types, errors,withRetry@reaatech/agent-handoff-validation— Payload validation used by the factory@reaatech/agent-handoff-protocol— Full orchestration layer