Skip to main content
This page describes the URLs exposed at startup for A2A communication.

​
Endpoint Paths

For any agent base URL, the paths are:
  • A2A JSON-RPC endpoint: POST /
  • Agent card endpoint: GET /.well-known/agent-card.json

​
Startup Output

At startup, aion serve prints both proxy and direct agent URLs. Example format: 
Proxy API: http://localhost:8000
Agents:
  hello-world:
    Card: http://localhost:8001/.well-known/agent-card.json
    Card (Proxy): http://localhost:8000/agents/hello-world/.well-known/agent-card.json
    RPC: http://localhost:8001
    RPC (Proxy): http://localhost:8000/agents/hello-world/

​
Single Agent Configured

If only one agent is configured, use that agent root URL directly. Example:
  • POST http://localhost:8001/
  • GET http://localhost:8001/.well-known/agent-card.json

​
Multiple Agents Configured

If multiple agents are configured, you have two access options:
  1. Proxy URL with agent_id path segment: http://{proxy_host}:{proxy_port}/agents/{agent_id}/
  2. Direct URL on each agent’s own port: http://{agent_host}:{agent_port}/
The agent_id value is the ID defined in aion.yaml. Example for an agent ID hello-world:
  • Proxy RPC: POST http://localhost:8000/agents/hello-world/
  • Proxy card: GET http://localhost:8000/agents/hello-world/.well-known/agent-card.json
  • Direct RPC: POST http://localhost:8001/
  • Direct card: GET http://localhost:8001/.well-known/agent-card.json

​
Port Assignment

If you do not pin ports, the SDK assigns them automatically and prints them at startup. For port configuration options, see: