Build your own agent on ForceAI's smart-router (A2A)

ForceAI’s A2A agents proxy to an upstream A2A server; the gateway does not run a model for an A2A agent. So to build an agent whose brain is ForceAI’s own smart-router, you put a small A2A server in the middle. It receives the A2A message, calls the gateway’s OpenAI-compatible /v1/chat/completions with model: smart-router, and returns the answer as an A2A artifact

client ──A2A──▶ ForceAI Gateway (key, RBAC, guardrails, system-knowledge, audit)
                      │  forwards message/send
                      ▼
                Your A2A wrapper  ──▶ POST /v1/chat/completions (model: smart-router)
                      ▲                         │
                      └───── answer ◀───────────┘  gateway routes to the best LLM

The outer A2A hop is fully governed, and the inner chat-completions call is routed by smart-router and is itself subject to your guardrails. A reference implementation ships in deploy/smart-router-agent/

The wrapper

A minimal FastAPI A2A server. On each message/send it joins the text parts (a ForceAI system-knowledge document, if attached, arrives as the leading part), calls the gateway, and returns a completed A2A task

GATEWAY_URL = os.environ["FORCEAI_GATEWAY_URL"]   # e.g. http://forceai-gateway:4000
API_KEY = os.environ["FORCEAI_API_KEY"]           # a ForceAI virtual key
MODEL = os.environ.get("FORCEAI_MODEL", "smart-router")

async def ask(prompt: str) -> str:
    async with httpx.AsyncClient(timeout=60) as c:
        r = await c.post(f"{GATEWAY_URL}/v1/chat/completions",
            headers={"Authorization": f"Bearer {API_KEY}"},
            json={"model": MODEL, "messages": [{"role": "user", "content": prompt}]})
    r.raise_for_status()
    return r.json()["choices"][0]["message"]["content"]

The A2A result must be a valid Task (or Message); returning a bare {"artifacts": [...]} makes the gateway hand the caller an empty result

Give the wrapper a virtual key scoped to the models it may call, not your admin key. The wrapper authenticates to the gateway as any other API client

Run it

The reference agent is wired into the compose stack and reaches the gateway over the compose network

docker compose up -d --build smart-router-agent
curl -s http://localhost:9100/.well-known/agent-card.json   # sanity check the card

Onboard it

Register the wrapper as an A2A Standard agent, pointing at its URL (compose DNS http://smart-router-agent:9100/ from the gateway’s perspective)

curl -X POST https://YOUR_GATEWAY_DOMAIN/v1/agents \
  -H "Authorization: Bearer $ADMIN_KEY" -H "Content-Type: application/json" \
  -d '{
        "agent_name": "forceai-smart-router-agent",
        "agent_card_params": {
          "protocolVersion": "0.3",
          "name": "ForceAI Smart-Router Agent",
          "description": "Brain is ForceAI smart-router",
          "url": "http://smart-router-agent:9100/",
          "version": "1.0.0",
          "defaultInputModes": ["text"],
          "defaultOutputModes": ["text"],
          "capabilities": { "streaming": false },
          "skills": [{ "id": "chat", "name": "Chat", "description": "smart-router chat", "tags": ["llm"] }]
        }
      }'

New agents start pending; approve it before it can be invoked

curl -X POST https://YOUR_GATEWAY_DOMAIN/v1/agents/$AGENT_ID/approve -H "Authorization: Bearer $ADMIN_KEY"

In the dashboard you can do the same under Agents -> Add New Agent -> A2A Standard, and optionally attach a System knowledge document on the Configure step; it is injected as leading instructions on every call

Invoke it

curl -X POST https://YOUR_GATEWAY_DOMAIN/a2a/$AGENT_ID/message/send \
  -H "Authorization: Bearer $VIRTUAL_KEY" -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":"1","method":"message/send",
       "params":{"message":{"role":"user","parts":[{"kind":"text","text":"Write a friendly one-sentence greeting."}],"messageId":"m1"}}}'

The answer is produced by smart-router, and the Logs page records the inner hop as model: smart-router. Because the guardrail runs on that inner call, a prompt the guardrail blocks returns a 400 from the agent, exactly as a direct chat completion would

Exposing it to external users

Everything is the gateway, one surface, two protocols, all authenticated with a virtual key:

Models and the smart-router: POST /v1/chat/completions (OpenAI-compatible)
Agents: POST /a2a/{agent_id}/message/send and /message/stream (A2A JSON-RPC), plus GET /a2a/{agent_id} for the card

Mint a virtual key, scope it to the specific models and agents the user may reach, and hand them the key. They call the same endpoints you do

Get started

LLM providers

A2A agents

Skills

Knowledge Catalog

Single sign-on

Admin settings

Tools

Guardrails

Command line

Coding tools

Build your own agent on ForceAI's smart-router (A2A)

The wrapper

Run it

Onboard it

Invoke it

Exposing it to external users