Skip to content
Blog

Routing Tasks Across Agents with the A2A Protocol

Build a router that matches incoming work to the right remote agent with A2A: skill-based routing from Agent Cards, task delegation patterns, fan-out and fallback, and a working Python router over JSON-RPC.

Published on • November 16, 2026

AI Assistant

A front desk does one job well: take the request, decide who handles it, hand it over. In multi-agent systems the equivalent component is missing in most designs - one agent answers everything, or a brittle if/elif chain hardcodes which specialist gets what. When the specialists are remote agents owned by other teams or other companies, hardcoding is not just ugly, it is wrong: endpoints move, capabilities change, and your router should not need a redeploy to notice.

The Agent2Agent (A2A) protocol gives you the raw material for a proper router: every A2A server publishes a machine-readable Agent Card declaring its skills, interfaces, and capabilities, and every unit of work is a Task you can delegate with SendMessage and track with GetTask. In this tutorial you will build a skill-based A2A router in Python that discovers agents from their cards, routes tasks by capability, handles fan-out and fallback, and never hardcodes a partner’s endpoint.

Prerequisites

  • Python 3.11+ with httpx installed (pip install httpx)
  • Familiarity with JSON-RPC 2.0 and the A2A task lifecycle (submitted, working, input-required, completed, failed, canceled, rejected)
  • Two or more A2A servers to route between - the reference samples in the A2A repository (Helloworld, LangGraph currency agent) or your own
  • An understanding of why routing lives outside the agents: the router orchestrates, the agents execute

Why Route on the Card, Not on a Config File

The alternative to card-based routing is a YAML file listing endpoints and capabilities. It works until the first drift: a partner renames a skill, a team adds a second endpoint, or a capability flag changes. A2A’s design assumes the agent describes itself at runtime:

GET https://agent-a.example/.well-known/agent-card.json   -> skills, capabilities, interfaces
GET https://agent-b.example/.well-known/agent-card.json   -> skills, capabilities, interfaces

Three fields do the routing work:

Card fieldRouting use
skills[].id / name / descriptionMatch the incoming request to a capability
capabilities.streamingDecide whether the delegation can stream updates back
capabilities.pushNotificationsDecide whether long tasks can notify instead of being polled
url + preferredInterfaceWhere and how to send the JSON-RPC calls

The router’s contract with the outside world is then a single interface: given a request, return a task handle. Everything about how the work gets to the right agent is derived from live card data.

Step 1: A Directory of Resolvable Agents

Start with a small directory. Entries carry only a base URL - everything else comes from the card:

import httpx

DIRECTORY = [
    {"name": "helloworld", "base_url": "http://127.0.0.1:9999"},
    {"name": "currency", "base_url": "http://127.0.0.1:10000"},
    {"name": "support", "base_url": "http://127.0.0.1:10001"},
]

async def fetch_card(client: httpx.AsyncClient, entry: dict) -> dict | None:
    url = entry["base_url"].rstrip("/") + "/.well-known/agent-card.json"
    try:
        r = await client.get(url, timeout=10)
        r.raise_for_status()
        return r.json()
    except (httpx.HTTPError, ValueError):
        return None  # unreachable or malformed: treated as down

Failures here are routing data, not exceptions to crash on. An agent whose card cannot be fetched is temporarily unroutable - record it, skip it, and let the fallback path handle the request.

Step 2: Score Skills Against the Request

Skill matching is retrieval, and for a router it should be deliberately simple and explainable. Start with exact and substring matching over skill id and name, and keep an embedding-based scorer as an optional upgrade:

from dataclasses import dataclass, field

@dataclass
class Route:
    entry: dict
    card: dict
    skill: dict
    score: float = 0.0

def score_skill(request: str, skill: dict) -> float:
    req = request.lower()
    haystacks = [skill.get("id", ""), skill.get("name", ""),
                 skill.get("description", "")]
    best = 0.0
    for text in haystacks:
        tokens = text.lower().replace("-", " ").split()
        if not tokens:
            continue
        hits = sum(1 for t in tokens if t in req)
        best = max(best, hits / len(tokens))
    return best

async def route(client: httpx.AsyncClient, request: str) -> Route | None:
    best: Route | None = None
    for entry in DIRECTORY:
        card = await fetch_card(client, entry)
        if not card:
            continue
        for skill in card.get("skills", []):
            s = score_skill(request, skill)
            if s > 0 and (best is None or s > best.score):
                best = Route(entry=entry, card=card, skill=skill, score=s)
    return best

Two routing rules worth copying from production systems:

  • Always return the runner-up. When the top route fails, retrying the same agent is pointless; retry the second-best Route with its skill.id intact. A thin wrapper gives you the ordered candidate list the handler uses later:
async def all_routes(client: httpx.AsyncClient, request: str) -> list[Route]:
    matches: list[Route] = []
    for entry in DIRECTORY:
        card = await fetch_card(client, entry)
        if not card:
            continue
        for skill in card.get("skills", []):
            s = score_skill(request, skill)
            if s > 0:
                matches.append(Route(entry=entry, card=card, skill=skill, score=s))
    return sorted(matches, key=lambda r: r.score, reverse=True)
  • Never route on a skill the card does not declare. If nothing scores above zero, the correct behavior is “no match” - not “send it to the most general agent and hope.”

Step 3: Delegate the Task

Once routed, delegation is a single JSON-RPC call over HTTPS. The router speaks the protocol directly so the routing logic stays framework-agnostic:

async def delegate(route: Route, request: str) -> dict:
    payload = {
        "jsonrpc": "2.0",
        "id": 1,
        "method": "SendMessage",
        "params": {
            "message": {
                "role": "ROLE_USER",
                "parts": [{"type": "text", "text": request}],
                "metadata": {"skillId": route.skill["id"]},
            }
        },
    }
    endpoint = route.card["url"]  # prefer the card's declared RPC URL
    async with httpx.AsyncClient(timeout=120) as client:
        r = await client.post(endpoint, json=payload)
        r.raise_for_status()
        body = r.json()
        if "error" in body:
            raise RuntimeError(f"JSON-RPC error: {body['error']}")
        return body["result"]

Note what the router does not do: it does not parse the answer. The result is a Task (or a Message); the router’s job ends at delivering a handle. Reading task["status"]["state"] and artifacts is the caller’s job - keep the router’s output uniform regardless of which agent handled the work.

Step 4: Follow the Task to Completion

A routed task is almost never finished when SendMessage returns. Poll until the task reaches a terminal state, and be ready for input-required:

TERMINAL = {"TASK_STATE_COMPLETED", "TASK_STATE_FAILED",
            "TASK_STATE_CANCELED", "TASK_STATE_REJECTED"}

async def await_task(base_url: str, task_id: str, poll_s: float = 1.5) -> dict:
    payload = {
        "jsonrpc": "2.0",
        "id": 2,
        "method": "GetTask",
        "params": {"id": task_id},
    }
    async with httpx.AsyncClient(timeout=30) as client:
        while True:
            r = await client.post(base_url + "/rpc", json=payload)
            task = r.json()["result"]
            state = task["status"]["state"]
            if state in TERMINAL:
                return task
            if state == "TASK_STATE_INPUT_REQUIRED":
                # surface task["status"]["message"] to the user, then
                # re-send with the SAME taskId/contextId to continue it
                return task
            await asyncio.sleep(poll_s)

If the card declared capabilities.streaming: true, replace polling with SendStreamingMessage - the server responds 200 OK with Content-Type: text/event-stream and emits TaskStatusUpdateEvent / TaskArtifactUpdateEvent frames until a terminal state. If it declared capabilities.pushNotifications: true and the task is long-running, register a webhook with CreateTaskPushNotificationConfig and stop polling entirely. The card tells you which of the three strategies is legal.

Step 5: Fan-Out, Fallback, and Consolidation

Real routers do more than pick one agent. Three compositions cover most workloads:

Fan-out (parallel delegation). Send the same request fragment to N agents that each hold part of the answer:

import asyncio

async def fan_out(request: str, routes: list[Route]) -> list[dict]:
    async def one(route: Route):
        try:
            return await delegate(route, request)
        except Exception as exc:
            return {"error": str(exc), "agent": route.entry["name"]}

    results = await asyncio.gather(*(one(r) for r in routes))
    return [r for r in results if "error" not in r]

Filtering failures before consolidation is what keeps fan-out honest: two successful specialist answers beat three answers plus an error object.

Fallback (sequential). Try the best route; on transport or JSON-RPC error, move to the runner-up. Bound the attempts - two is usually right, because the third attempt triples latency for a request that probably does not fit any agent.

Consensus (voting). For high-stakes classification, fan out to several agents that expose the same skill and majority-vote over the returned text. The A2A layer is unchanged; only the consolidation step differs.

Step 6: Keep the Router Observable

A router that hides which agent failed is a debugging nightmare. Emit one structured line per decision:

import logging, time

log = logging.getLogger("a2a-router")

def audit(request: str, route: Route, task: dict, started: float) -> None:
    log.info("route", extra={
        "request_len": len(request),
        "agent": route.entry["name"],
        "skill": route.skill["id"],
        "score": round(route.score, 3),
        "task_id": task.get("id"),
        "state": task.get("status", {}).get("state"),
        "elapsed_ms": int((time.monotonic() - started) * 1000),
    })

Fields worth alerting on: routing miss rate (requests with no matching skill), per-agent failure rate, and input-required frequency - a spike there usually means a partner changed their task contract.

Putting It All Together

import asyncio, logging, time

import httpx

async def handle(request: str) -> dict:
    started = time.monotonic()
    async with httpx.AsyncClient() as client:
        candidates = await all_routes(client, request)  # best first, runner-ups included
        if not candidates:
            return {"error": "no skill match"}
        for candidate in candidates:
            try:
                result = await delegate(candidate, request)
                task = result.get("task") or {}
                if task.get("id"):
                    task = await await_task(candidate.entry["base_url"], task["id"])
                audit(request, candidate, task, started)
                return task
            except Exception:
                logging.exception("delegate failed, falling back")
                continue
        return {"error": "all routes exhausted"}

Run it against two reference servers, send one request whose wording matches each agent’s skill, and watch the audit log show the decision path. The complete working code lives in the A2A samples alongside the routers their authors shipped.

Conclusion & Next Steps

Routing across agents is a discovery problem before it is a dispatch problem. Because A2A makes every agent self-describing, your router can derive skills, endpoints, and streaming support from live Agent Cards instead of a config file that goes stale - and because every delegation lands on a durable Task, fan-out, fallback, and audit all compose around a single uniform handle.

Next steps:

  • Swap the token scorer for embedding similarity and measure routing accuracy on a labeled request set.
  • Add CancelTask on client timeouts so abandoned routed work stops consuming partner resources.
  • Cache cards with HTTP ETag/Cache-Control to cut discovery latency (see our Agent Cards post).

Sources: A2A Protocol repository (google/A2A), A2A Protocol Specification, A2A Samples