Skip to main content

Connecting Agents

Your agent does not work alone. This guide covers how to discover other agents, call their capabilities, and integrate MCP tool servers so your runtime can reach peers and external tools through one mental model.

Discovering Agents

AgentDiscovery fetches and caches A2A agent cards from each peer’s /.well-known/agent-card.json endpoint. Use it to inspect names, skills, and metadata before you open a live connection.
Notes
  • Cards are cached for 60 seconds by default. Pass a different TTL in milliseconds (for example new AgentDiscovery(30_000) for 30s), or 0 to disable caching.
  • Batch: discover_all([url1, url2]) resolves many agents in parallel; failed URLs are skipped and only successful cards are returned.
  • Force refresh: discover(url, true) bypasses the cache for that URL once.
  • Manual invalidation: invalidate(url) or invalidate_all() when you know a peer redeployed.
RemoteAgent.connect() always fetches a fresh agent card for the connection itself; discovery caching is only for your own lookups.

Calling Remote Agents

RemoteAgent sends tasks to any A2A agent: natural-language messages, streaming responses, or structured capability calls.
Notes
  • Auth: RemoteAgent.connect(url, jwt) adds Authorization: Bearer <jwt> on requests when the peer requires it.
  • Streaming: for await (const event of billing.send_stream('...')) { ... } yields A2A stream events (messages, tasks, status and artifact updates).
  • Session forwarding: pass { session_id, tenant_id } as the third argument to invoke_capability when the remote agent should run in an existing session context.
  • Advanced: send_stream_message accepts a full A2A Message (see MessageBuilder).
Trace context propagates across RemoteAgent calls via W3C traceparent when telemetry is enabled (see Telemetry & tracing).

MCP Integration

Register MCP tool servers as agent capabilities so the mesh and other agents can invoke them like any other skill. The SDK spawns the server as a child process, runs the MCP handshake, and maps each tool to a capability.
Notes
  • Call register_mcp before expose() or start() so discovered tools appear on the agent card.
  • Each MCP tool becomes a capability named {prefix}_{tool_name}. By default, prefix is the server name with hyphens replaced by underscores (for example chrome-devtoolschrome_devtools_navigate).
  • Custom prefix: third argument { tool_prefix: 'browser' }browser_<tool>.
  • Environment: { command: '...', args: [...], env: { API_KEY: '...' } } is merged with process.env for the child.
  • Cleanup: agent.close() or agent.stop() tears down MCP child processes.
For more patterns (filesystem, GitHub, ordering with define_capability), see MCP integration.

Full example: coordinator agent

A short coordinator discovers two peers, checks their cards, then invokes structured capabilities and returns a combined payload.

See also