How A2A Protocol Powers Multi‑Agent Management in AgentRun

The A2A (Agent‑to‑Agent) protocol defines an AgentCard —a self‑describing JSON document that lists an agent’s identity, capabilities, endpoint URL, supported transport (JSON‑RPC/gRPC), and security constraints. Production use requires additional management features such as registration, isolation, permission control, and multi‑environment handling.

AgentRun Management Layer

AgentRun builds on A2A and introduces three core concepts:

Workspace : a logical namespace that isolates a set of agents, similar to a project space.

Discovery Endpoint : an environment‑specific entry point that maps agent names to their access URLs.

Platform‑Hosted vs External Agents : both can be registered in the same workspace and discovered uniformly.

Agents expose their AgentCard at /.well-known/agent-card.json. A typical AgentCard example:

{
  "name": "coffee_agent",
  "description": "智能咖啡店服务，帮助点咖啡和查询订单",
  "url": "https://agent.example.com/agent",
  "version": "0.0.1",
  "capabilities": {
    "streaming": true,
    "pushNotifications": true,
    "stateTransitions": ["submitted","working","completed","failed"]
  },
  "skills": [
    {"id":"coffee_agent-get_products","name":"获取商品列表","description":"获取当前可点的咖啡饮品列表","examples":["有什么咖啡推荐","看看菜单"]},
    {"id":"coffee_agent-create_order","name":"创建订单","description":"帮用户下单点咖啡","examples":["我要一杯拿铁","下单两杯美式"]}
  ]
}

Service Discovery

Since A2A does not define a centralized registry, a discovery layer is required. Clients query the discovery endpoint (e.g., ?discoveryEndpointName=default) and receive a paginated list of agents with their a2aAgentCardUrl. The response includes pageNumber, pageSize, and total fields and supports both new and legacy formats.

Communication Model

AgentRun uses JSON‑RPC 2.0 for request/response messaging and a Task model to represent interaction lifecycles. Example request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tasks/sendMessage",
  "params": {
    "message": {"role":"user","parts":[{"type":"text","text":"我要一杯拿铁"}]},
    "taskId": null
  }
}

Key methods: tasks/sendMessage: create or continue a task. tasks/get: query task status. tasks/cancel: abort a running task.

The task state machine progresses submitted → working → completed with possible failed or canceled branches.

Streaming and Push Notifications

If capabilities.streaming is true, agents can emit Server‑Sent Events (SSE) such as messageDelta for incremental output and taskStatusUpdate for final status. If capabilities.pushNotifications is true, the client can provide a callback URL in the initial request, allowing the agent to push results without polling.

Skill Invocation

Each skill entry defines id, name, description, and examples. Callers can let an orchestrator choose a skill based on intent or explicitly specify skillId in the tasks/sendMessage payload.

Credential Protection

Discovery endpoints are secured with API Key, HTTP Basic Auth, or custom headers. Credentials are bound to workspaces, enabling fine‑grained access control: invalid credentials result in 401/403, and credential rotation only requires updating the platform binding.

Step‑by‑Step Demo Using the Go SDK

Deploy coffee and delivery agents via the AgentRun console.

Create a workspace and register the agents (or migrate existing ones).

Configure a discovery endpoint (e.g., name default) and bind an API Key.

Use curl to query the discovery endpoint and retrieve the a2aAgentCardUrl for each agent.

Run the provided Go program ( examples/a2a-discovery-demo/main.go) which:

Requests the discovery endpoint with the API Key.

Parses the response to extract the first AgentCard URL.

Resolves the AgentCard and prints its metadata and skill list.

Creates an A2A client from the AgentCard, sends a greeting message, and prints the task result.

Execute the demo via run_demo.sh, passing base URL, workspace ID, endpoint name, and API key as environment variables.

The demo output shows discovery of two agents, retrieval of the coffee agent’s Card, and a successful single‑round conversation where the agent lists its capabilities.

Conclusion

Combining the A2A protocol with AgentRun’s workspace‑based isolation, discovery endpoints, and credential management yields a scalable, production‑ready foundation for multi‑agent AI systems. Standardized self‑description (AgentCard), JSON‑RPC messaging, and task lifecycle let developers focus on business logic while the platform handles registration, routing, security, and observability.

Reference: A2A Protocol Specification and the a2a‑go SDK (https://github.com/a2aproject/a2a-go).