A2A Transport

This guide explains how to enable and use the A2A Transport in AgentVisor, allowing other A2A-compatible agents to discover and interact with your agents.

Terminology: This guide covers the A2A Transport — exposing your AgentVisor agents via Google's Agent-to-Agent Protocol to external A2A clients. This allows other agents to discover and interact with your agents using a standardized protocol.

Note: A2A Transport allows external agents to call your agents. To have your agents call external A2A agents, see the A2A Gateway.

Overview

A2A Transport implements Google's Agent-to-Agent Protocol, enabling:

• Agent interoperability: Standard protocol for agent-to-agent communication
• Capability discovery: Other agents can discover what your agents can do
• Task management: Asynchronous task creation, monitoring, and cancellation

Enabling A2A Transport

Configuration

Enable A2A Transport in your agentvisor.yaml:

api:
  listen_addr: ":8090"
  
  openapi:
    enabled: true   # OpenAPI/REST (keep enabled for full functionality)
  a2a:
    enabled: true   # Enable A2A transport

Or via environment variable:

export AGENTVISOR_API_A2A_ENABLED=true

Agent Card Discovery

What is an Agent Card?

An Agent Card is a JSON document that describes your agent's capabilities, authentication requirements, and how to interact with it. A2A clients fetch this card to understand what your agent can do.

Agent Card Location

AgentVisor serves the Agent Card at the well-known URL:

GET /.well-known/agent-card.json

Example response:

{
  "name": "AgentVisor",
  "description": "Secure AI agent runtime with policy-based access control",
  "url": "http://localhost:8090/a2a",
  "version": "1.0.0",
  "capabilities": {
    "streaming": true,
    "pushNotifications": false
  },
  "defaultInputModes": ["text"],
  "defaultOutputModes": ["text"],
  "skills": [
    {
      "id": "chat",
      "name": "chat",
      "description": "General conversation and Q&A"
    }
  ]
}

The name, description, and other card-level fields default to the values shown above; override them via a2a.agent_card in mav-agent-config.yaml (see Enriching A2A Agent Cards). When api.auth.enabled is set, the card also includes securitySchemes and security (see Agent Card Security Schemes below).

Skills Mapping

AgentVisor maps each registered agent to an A2A skill:

AgentVisor Concept	A2A Concept
Agent	Skill
Agent description	Skill description
Thread	Context (contextId)
Run	Task

A2A Protocol Operations

Task Management

The A2A protocol uses JSON-RPC 2.0 for all operations. Key methods:

message/send

Create a new task or continue an existing conversation:

curl -X POST http://localhost:8090/a2a \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": "1",
    "method": "message/send",
    "params": {
      "message": {
        "role": "user",
        "parts": [{"type": "text", "text": "Hello, how can you help me?"}]
      }
    }
  }'

tasks/get

Retrieve the status and result of a task:

curl -X POST http://localhost:8090/a2a \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": "2",
    "method": "tasks/get",
    "params": {
      "id": "<task-id>"
    }
  }'

tasks/list

List tasks for a context:

curl -X POST http://localhost:8090/a2a \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": "3",
    "method": "tasks/list",
    "params": {
      "contextId": "<context-id>"
    }
  }'

tasks/cancel

Cancel a running task:

curl -X POST http://localhost:8090/a2a \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": "4",
    "method": "tasks/cancel",
    "params": {
      "id": "<task-id>"
    }
  }'

Task State Mapping

AgentVisor maps run statuses to A2A task states:

AgentVisor Run Status	A2A Task State
running	working
interrupted	input_required
completed	completed
error	failed
cancelled	canceled

Streaming

For real-time task updates, use message/stream:

curl -X POST http://localhost:8090/a2a \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": "5",
    "method": "message/stream",
    "params": {
      "message": {
        "role": "user",
        "parts": [{"type": "text", "text": "Generate a long response"}]
      }
    }
  }'

To subscribe to updates for an existing task instead of starting a new one, use tasks/subscribe with {"id": "<task-id>"}.

The response will be a Server-Sent Events stream with task updates.

Interoperating with Other A2A Agents

Calling External A2A Agents

To have your agents communicate with external A2A-compatible agents, use the A2A Gateway. The gateway provides:

• Managed connections with credential injection
• Policy enforcement on all A2A operations
• Connection pooling for multi-tenant environments
• Both Python SDK and LangChain integration

See the A2A Gateway guide for configuration and usage details.

Discovery Flow

When another A2A agent wants to interact with yours:

1. Fetches /.well-known/agent-card.json to discover capabilities
2. Authenticates using configured security schemes
3. Sends message/send to create tasks
4. Polls tasks/get or subscribes via tasks/subscribe for updates

Authentication

Bearer Token Authentication

Enable OIDC authentication for A2A Transport:

api:
  auth:
    enabled: true
    oidc_issuer: "https://auth.example.com"
    oidc_audience: "agentvisor"
  a2a:
    enabled: true

A2A clients must include the bearer token:

curl -X POST http://localhost:8090/a2a \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '...'

Agent Card Security Schemes

When api.auth.enabled is set with an oidc_issuer, the Agent Card advertises the supported authentication methods via securitySchemes and security:

{
  "securitySchemes": {
    "oidc": {
      "type": "openIdConnect",
      "openIdConnectUrl": "https://auth.example.com/.well-known/openid-configuration"
    },
    "bearer": {
      "type": "http",
      "scheme": "bearer"
    }
  },
  "security": [
    {"oidc": []}
  ]
}

The bearer scheme is advertised for clients that already hold an OIDC-issued bearer token, but only oidc is listed as required in security.

TLS Configuration

For production deployments:

api:
  listen_addr: ":8090"
  tls:
    enabled: true
    cert_file: "/path/to/server.crt"
    key_file: "/path/to/server.key"
  a2a:
    enabled: true

Troubleshooting

Agent Card not found

Ensure A2A Transport is enabled:

curl http://localhost:8090/.well-known/agent-card.json

If you get a 404, verify:

1. api.a2a.enabled: true in configuration
2. The server has restarted after config change

Task creation fails

1. Check server logs for error details
2. Verify the message format matches A2A specification
3. Ensure authentication is properly configured

Streaming not working

1. Verify the client sends Accept: text/event-stream
2. Check that no proxy is buffering the response
3. Ensure the agent supports streaming output

Protocol References

• A2A Protocol Specification
• A2A GitHub Repository

See Also

• API Transports Overview - Understanding all transport types
• MCP Transport - Alternative protocol for MCP clients
• Gateways Overview - How agents access external services
• Configuration Reference - Full configuration options