A2A Connections

August 30, 2026 · View on GitHub

This document describes the Agent-to-Agent (A2A) connection functionality that allows the CLI to connect to A2A server agents using the ADK (Agent Development Kit) client.

Overview

The A2A connection feature enables:

  • Communication between the CLI client and A2A server agents via URL
  • Task submission with streaming responses
  • Agent querying for server information
  • Simple agent-to-agent communication patterns

Architecture

Current Architecture

CLI Client → A2A Agent (Connection via URL)

The CLI connects to A2A agents using their URL endpoints through the ADK client library.

Usage

Using the /agents Shortcut

The /agents shortcut provides command-line interface for managing A2A agent configurations:

List A2A Agents

/agents list

This displays a list of all configured A2A agents showing:

  • Agent name
  • URL endpoint
  • OCI container image (if configured)
  • Run locally status (enabled/disabled)
  • Model configuration
  • Enabled/disabled status

Add an Agent

/agents add my-agent http://localhost:8081 --run --model openai/gpt-4

Options:

  • --oci IMAGE: Specify OCI container image
  • --artifacts-url URL: Artifacts download URL
  • --run: Run the agent locally
  • --model MODEL: Model to use for the agent
  • --environment KEY=VALUE: Environment variables

Remove an Agent

/agents remove my-agent

Using the A2A Tools

The A2A functionality is exposed through multiple tools that can be used in conversations:

A2A_SubmitTask Tool - Submit a Task

The A2A_SubmitTask tool submits tasks to A2A agents:

Submit a task to analyze this code

The LLM will use the A2A_SubmitTask tool:

{
  "agent_url": "http://localhost:8081",
  "task_description": "Analyze the code in the current repository for potential security issues"
}

Optional metadata can be included:

{
  "agent_url": "http://localhost:8081",
  "task_description": "Review pull request for best practices",
  "metadata": {
    "pull_request_id": "123",
    "focus_areas": ["security", "performance"]
  }
}

A2A_QueryAgent Tool - Get Agent Information

The A2A_QueryAgent tool gets information from A2A agents:

Query the agent at localhost:8081 for its capabilities

{
  "agent_url": "http://localhost:8081"
}

A2A_QueryTask Tool - Query Task Status

The A2A_QueryTask tool queries the status and result of a specific A2A task:

Check the status of task task-456 from the agent at http://localhost:8081

{
  "agent_url": "http://localhost:8081",
  "context_id": "context-123",
  "task_id": "task-456"
}

Important: When you submit a task via A2A_SubmitTask, it automatically monitors the task in the background. Only use A2A_QueryTask to:

  1. Check tasks from previous conversations
  2. Check tasks submitted outside this session
  3. Get detailed results AFTER you receive a completion notification

Background Task Visualisation

While a remote A2A task is running in the background, the CLI shows a live, sticky status bar pinned just above the input box (below the scrollable conversation viewport). It is always visible regardless of where you've scrolled the conversation, so you never lose sight of in-flight delegations.

A typical bar looks like:

… conversation viewport (scrollable) …
─────────────────────────────────────────────
◓ Agent(weather-agent=working...)
> _   (input)

The line updates in place as the task progresses through its lifecycle: submitted → working → completed / failed / cancelled.

On successful completion, the indicator expands to a tree-style block showing the usage and execution_stats JSON taken from the remote task's metadata (populated by ADK ≥ 0.19.0 agents that have EnableUsageMetadata enabled - the default). usage reports token consumption; execution_stats reports iterations, messages, tool calls, and failed tool calls:

✓ Agent(weather-agent=completed)
  ├── usage={"prompt_tokens":156,"completion_tokens":89,"total_tokens":245}
  └── execution_stats={"iterations":2,"messages":4,"tool_calls":1,"failed_tools":0}

Either or both branches are omitted if the remote agent doesn't emit the corresponding metadata (older ADK versions, or EnableUsageMetadata=false). Failures follow the same layout with an additional error: … branch.

On failure:

✗ Agent(weather-agent=failed: connection refused)

The indicator auto-removes itself 5 seconds after the task reaches a terminal state (completed, failed, or cancelled), keeping the bar tidy while still giving you time to glance at the usage / error.

Multiple concurrent tasks each get their own line in the bar (one line per task, lexicographically ordered by task ID for stability), so a single assistant turn that submits several A2A tasks shows independent progress lines side-by-side without any reordering between renders.

Notes:

  • The indicator is purely a UI element - it is not persisted with the conversation. Reloading a session will not bring back indicators for tasks that have already completed.
  • If the remote agent does not attach metadata.usage (older ADK versions, or EnableUsageMetadata=false), the completed line omits the usage=... suffix.
  • For a full historical record of past tasks, use A2A_QueryTask or the in-session task management view.

Tool Implementation Details

A2A_SubmitTask Tool

  • Name: A2A_SubmitTask
  • Parameters:
    • agent_url (required): URL of the A2A agent
    • task_description (required): Description of the task to perform
    • metadata (optional): Additional task metadata as key-value pairs
  • Returns: Task result with ID, status, and response content
  • Behavior: Submits task and waits for streaming completion

A2A_QueryAgent Tool

  • Name: A2A_QueryAgent
  • Parameters:
    • agent_url (required): URL of the A2A agent to query
  • Returns: Agent card information with capabilities and configuration
  • Behavior: Retrieves agent metadata for discovery and validation

A2A_QueryTask Tool

  • Name: A2A_QueryTask
  • Parameters:
    • agent_url (required): URL of the A2A agent server
    • context_id (required): Context ID for the task
    • task_id (required): ID of the task to query
  • Returns: Complete task object including status, artifacts, and message data
  • Behavior: Queries task status and returns detailed information. Cannot be used while background polling is active for the same agent.

A2A Integration

A2A Tool Configuration

Note: The /agents shortcut is used for agent configuration management, while the A2A tools below are used for runtime interaction with configured agents.

A2A tools are configured in the a2a.tools section of your configuration:

a2a:
  enabled: true  # Enable A2A functionality
  cache:
    enabled: true  # Enable agent card caching
    ttl: 300       # Cache TTL in seconds
  task:
    status_poll_seconds: 5       # Background task polling interval
    polling_strategy: "exponential"  # Polling strategy
    initial_poll_interval_sec: 2     # Initial poll interval
    max_poll_interval_sec: 60        # Maximum poll interval
    backoff_multiplier: 2.0          # Backoff multiplier
    completed_task_retention: 5      # Number of completed tasks to retain
  tools:
    query_agent:
      enabled: true         # Enable A2A_QueryAgent tool
      require_approval: false  # Whether approval is required
    query_task:
      enabled: true         # Enable A2A_QueryTask tool
      require_approval: false  # Whether approval is required
    submit_task:
      enabled: true         # Enable A2A_SubmitTask tool
      require_approval: true   # Whether approval is required

Security Considerations

Configuration Validation

  • Tools validate required parameters before execution
  • Invalid configurations result in clear error messages

Network Security

  • A2A connections require proper URL validation
  • Consider using HTTPS for production agent URLs
  • Implement proper timeout handling for network requests

Monitoring and Logging

Debug Logging

Enable debug logging to monitor A2A operations:

INFER_LOGGING_DEBUG=true infer chat

Check the logs:

tail -f ~/.infer/logs/debug-*.log

Task Tracking

The CLI logs:

  • Task submissions with agent URLs
  • Task IDs and completion status
  • Duration and event counts
  • Error conditions and failures

Error Handling

Common Error Conditions

  1. Invalid Parameters: Missing or invalid agent_url or task_description
  2. Connection Failures: Network timeouts or unreachable agents
  3. Streaming Errors: Issues with ADK client streaming

Error Messages

Tools provide descriptive error messages:

  • "A2A connections are disabled in configuration"
  • "agent_url parameter is required and must be a string"
  • "Streaming failed: [specific error]"

Troubleshooting

Configuration Issues

Check A2A configuration:

a2a:
  enabled: true

Connection Testing

Test agent connectivity using the SubmitTask tool with a simple description:

Test connection to agent at http://localhost:8081

Debug Information

Enable verbose logging and check for:

  • ADK client connection attempts
  • Streaming event processing
  • Task completion status
  • Error stack traces

Examples

Agent Configuration with /agents Shortcut

# First, configure an agent using the /agents shortcut
/agents add code-reviewer http://localhost:8081 --run --model openai/gpt-4 --environment GITHUB_TOKEN=xxx

# List configured agents
/agents list

Code Review Task

Submit a code review task to the agent at http://localhost:8081 for the current pull request

Security Analysis

Ask the security agent at http://localhost:8082 to analyze this codebase for vulnerabilities

Agent Capability Query

Query the documentation agent at http://localhost:8083 for its available features

Artifact Download

When a delegated A2A task completes with artifacts:

Download the artifact from task task-456

This will:

  1. Wait for the automatic completion notification with artifact details
  2. Use WebFetch with download=true to automatically save artifacts to disk
  3. The file will be saved to <configDir>/tmp with filename extracted from URL

Important: The artifact download URLs are provided in the completion notification. Use WebFetch to download artifacts:

Use WebFetch to download http://localhost:8081/artifacts/task-456/report.pdf

This automatically saves the file to the configured download directory and returns the local file path.