Build A2A agents with NanoGPT

Where NanoGPT fits

MCP and A2A serve different layers. Use NanoGPT MCP when an agent needs NanoGPT tools. Use A2A when independently deployed agents need to discover one another and delegate tasks.

This guide targets A2A 1.0 and the 1.x official Python SDK. Install the SDK with its HTTP server dependencies, an ASGI runner, and the OpenAI client. Keep the NanoGPT API key in the server environment; never put it in an Agent Card or send it to an A2A caller.

python -m pip install openai "a2a-sdk[http-server]>=1,<2" uvicorn
export NANOGPT_API_KEY="your_api_key"

Point the OpenAI client at NanoGPT's API base URL. The stable claw-medium alias is a sensible default for agent workloads; use a specific model ID when you need fixed behavior.

import os
from openai import AsyncOpenAI

nanogpt = AsyncOpenAI(
    api_key=os.environ["NANOGPT_API_KEY"],
    base_url="https://nano-gpt.com/api/v1",
)

async def generate_reply(prompt: str) -> str:
    response = await nanogpt.chat.completions.create(
        model="claw-medium",
        messages=[
            {
                "role": "system",
                "content": "You are a focused remote agent. Return a useful final answer.",
            },
            {"role": "user", "content": prompt},
        ],
    )
    return response.choices[0].message.content or ""

Keep the model adapter separate from the protocol layer. That lets you update models without changing the public skills and behavior advertised by your agent.

# Call this from your A2A SDK AgentExecutor or task handler.
async def handle_agent_message(message_text: str) -> str:
    return await generate_reply(message_text)

# Your A2A layer remains responsible for:
# - publishing the Agent Card
# - accepting and validating A2A messages
# - task state, streaming, cancellation, and artifacts
# - authenticating callers

Follow the official A2A Python SDK examples to connect this handler to an AgentExecutor and expose the protocol endpoint.

The Agent Card describes your agent—not NanoGPT. Publish it from your agent's domain at /.well-known/agent-card.json. For A2A 1.0, declare supportedInterfaces with the URL, protocol binding, and protocol version for each interface. Advertise only the capabilities, skills, input modes, output modes, and security requirements your server actually implements.

Production checklist

• Authenticate A2A callers separately from the NanoGPT API key used by your server.
• Apply per-caller quotas and spending limits before starting billable model work.
• Propagate client cancellation and enforce whole-task timeouts.
• Make task creation idempotent so retries cannot duplicate model calls or charges.
• Persist task state if clients can poll, reconnect to streams, or receive webhooks.
• Return bounded errors and avoid leaking prompts, credentials, provider details, or internal traces.
• Test the Agent Card and task lifecycle against at least one independent A2A client.