Skip to main content
The A2A toolset connects your agent to a remote agent running as an A2A (Agent-to-Agent) server. The remote agent appears as a named tool that the local agent can call to delegate tasks. This is similar to the handoff tool, but configured as a toolset rather than through the handoffs list.

​
Configuration

toolsets:
  - type: a2a
    name: research_agent
    url: "http://localhost:8080/a2a"

​
Options

​
name
string
required
Tool name for the remote agent. This is how the local agent refers to it in tool calls.
​
url
string
required
The A2A server endpoint URL.

​
Example agent

agent.yaml
agents:
  root:
    model: openai/gpt-4o
    description: Coordinator that delegates to a remote specialist
    instruction: |
      When the user asks research questions, delegate to the research_agent.
      Synthesize its findings into a clear answer.
    toolsets:
      - type: a2a
        name: research_agent
        url: "http://research-service:8080/a2a"
      - type: think

​
Connecting to multiple remote agents

You can add multiple A2A toolsets to connect to several remote agents:
agent.yaml
agents:
  coordinator:
    model: openai/gpt-4o
    description: Coordinator with multiple remote specialists
    instruction: Delegate tasks to the appropriate specialist.
    toolsets:
      - type: a2a
        name: code_reviewer
        url: "http://code-review-service/a2a"
      - type: a2a
        name: security_scanner
        url: "http://security-service/a2a"
      - type: think
The remote agent must be running as an A2A server. See A2A Protocol for how to start an agent as an A2A server using docker agent serve a2a.

​
A2A vs. handoff

a2a toolsethandoffs list
Agent locationRemote (separate process or machine)Local (same config file)
Configurationtoolsets entryhandoffs list on the agent
Control flowReturns result to callerTransfers conversational ownership

Handoff

Transfer conversation control between local agents.

A2A protocol

Serve and consume A2A-compatible agents.

Transfer task

Delegate tasks to local sub-agents.

Multi-agent

Multi-agent architecture patterns.

Build docs developers (and LLMs) love

Get started for freeTalk to us