How to Use A2A Agents#

A2A Protocol is an open standard that defines how two agents can communicate with each other. It covers both the serving and consumption aspects of agent interaction.

In this guide, you will learn how to build an A2A agent with the A2AAgent class from the pyagentspec package.

Basic Usage#

To get started with an A2A agent, you need the URL of the remote server agent you wish to connect to. Once you have this information, creating your A2A agent is straightforward and can be done in just a few lines of code:

from pyagentspec.a2aagent import A2AAgent, A2AConnectionConfig, A2ASessionParameters

# Define the URL endpoint of the remote server agent to connect
# Replace "<IP ADDRESS>" with the actual IP address or hostname of the server agent
SERVER_AGENT_URL = "<IP ADDRESS>"

# Define the connection configuration with timeout and paths to SSL/TLS certificates
# This ensures a secure connection to the remote server agent
a2aconnection_config = A2AConnectionConfig(
    name="connection_config",
    timeout=30,  # Connection timeout in seconds
    key_file="/path/to/client/key.pem",    # Path to client private key
    cert_file="/path/to/client/cert.pem",  # Path to client certificate for SSL/TLS
    ssl_ca_cert="/path/to/ca/cert.pem"     # Path to CA certificate for server verification
)

# Define session parameters for controlling communication behavior
# These settings help manage session timeouts and retry mechanisms for reliability
a2asession_params = A2ASessionParameters(
    timeout=60, # Timeout in seconds for polling responses from the server
    poll_interval=2, # Polling time interval in seconds
    max_retries=3, # Maximum number of retries on connection or request failure
)

# Create an A2A Agent instance to communicate with the specified server agent's URL
a2a_agent = A2AAgent(
    name="Test A2A Agent",
    agent_url=SERVER_AGENT_URL,
    connection_config=a2aconnection_config,
    session_parameters=a2asession_params
)

Note that the A2AAgent is an extension of RemoteAgent in Agent Spec, which is considered an AgenticComponent. It follows that A2A agents can be used in AgentNodes inside Agent Spec flows.

Agent Spec Serialization#

You can export the agent configuration using the AgentSpecSerializer.

from pyagentspec.serialization import AgentSpecSerializer

serialized_assistant = AgentSpecSerializer().to_json(a2a_agent)

Here is what the Agent Spec representation will look like ↓

Click here to see the assistant configuration.
{
    "component_type": "A2AAgent",
    "id": "f48c79a1-ca6e-4281-b1b0-c8e602ec50e9",
    "name": "Test A2A Agent",
    "description": null,
    "metadata": {},
    "inputs": [],
    "outputs": [],
    "agent_url": "<IP ADDRESS>",
    "connection_config": {
        "timeout": 30.0,
        "headers": null,
        "verify": true,
        "key_file": "/path/to/client/key.pem",
        "cert_file": "/path/to/client/cert.pem",
        "ssl_ca_cert": "/path/to/ca/cert.pem"
    },
    "session_parameters": {
        "timeout": 60.0,
        "poll_interval": 60.0,
        "max_retries": 3
    },
    "agentspec_version": "26.1.0"
}

Recap#

This how-to guide covered how to define an A2A Agent in Agent Spec.

Below is the complete code from this guide.
 1from pyagentspec.a2aagent import A2AAgent, A2AConnectionConfig, A2ASessionParameters
 2
 3# Define the URL endpoint of the remote server agent to connect
 4# Replace "<IP ADDRESS>" with the actual IP address or hostname of the server agent
 5SERVER_AGENT_URL = "<IP ADDRESS>"
 6
 7# Define the connection configuration with timeout and paths to SSL/TLS certificates
 8# This ensures a secure connection to the remote server agent
 9a2aconnection_config = A2AConnectionConfig(
10    name="connection_config",
11    timeout=30,  # Connection timeout in seconds
12    key_file="/path/to/client/key.pem",    # Path to client private key
13    cert_file="/path/to/client/cert.pem",  # Path to client certificate for SSL/TLS
14    ssl_ca_cert="/path/to/ca/cert.pem"     # Path to CA certificate for server verification
15)
16
17# Define session parameters for controlling communication behavior
18# These settings help manage session timeouts and retry mechanisms for reliability
19a2asession_params = A2ASessionParameters(
20    timeout=60, # Timeout in seconds for polling responses from the server
21    poll_interval=2, # Polling time interval in seconds
22    max_retries=3, # Maximum number of retries on connection or request failure
23)
24
25# Create an A2A Agent instance to communicate with the specified server agent's URL
26a2a_agent = A2AAgent(
27    name="Test A2A Agent",
28    agent_url=SERVER_AGENT_URL,
29    connection_config=a2aconnection_config,
30    session_parameters=a2asession_params
31)

Next Steps#

Now that you have learned how to build A2A Agents, you can proceed to How to Use the WayFlow Runtime to Execute Agent Spec and How to Execute Agent Spec Across Frameworks.