Agent-to-Agent — A2A at the protocol level.

uv init a2a-agents --python 3.13
cd a2a-agents

uv add "a2a-sdk[http-server]==1.1.0" "groq==1.4.0" uvicorn httpx python-dotenv

# .env
GROQ_API_KEY=gsk_your_actual_key_here

"""Throwaway check that GROQ_API_KEY works with the async Groq client."""
import asyncio

from dotenv import load_dotenv
from groq import AsyncGroq

load_dotenv()  # must run before AsyncGroq()

async def main() -> None:
    client = AsyncGroq()
    response = await client.chat.completions.create(
        model="llama-3.3-70b-versatile",
        messages=[{"role": "user", "content": "Reply with exactly: Groq is working"}],
        max_tokens=20,
    )
    print(response.choices[0].message.content)

if __name__ == "__main__":
    asyncio.run(main())

PYTHONPATH=. uv run python test_groq.py

"""Research Agent — an A2A server that summarizes a topic with Groq."""
from dotenv import load_dotenv
from groq import AsyncGroq
from starlette.applications import Starlette

from a2a.helpers import new_task_from_user_message, new_text_message, new_text_part
from a2a.server.agent_execution import AgentExecutor, RequestContext
from a2a.server.events import EventQueue
from a2a.server.request_handlers import DefaultRequestHandler
from a2a.server.routes import create_agent_card_routes, create_jsonrpc_routes
from a2a.server.tasks import InMemoryTaskStore, TaskUpdater
from a2a.types import AgentCapabilities, AgentCard, AgentInterface, AgentSkill

load_dotenv()

SYSTEM_PROMPT = (
    "You are a research assistant. Given a topic, write a tight, factual "
    "summary in 3-4 sentences. No preamble, no bullet points."
)

def build_agent_card() -> AgentCard:
    """Build this agent's public Agent Card (its discovery document)."""
    skill = AgentSkill(
        id="summarize_topic",
        name="Summarize Topic",
        description="Generates a concise 3-4 sentence research summary of any topic.",
        tags=["research", "summary"],
        examples=["Summarize transformers in AI"],
    )
    return AgentCard(
        name="Research Agent",
        description="Summarizes any topic into a short research brief using Groq.",
        version="1.0.0",
        default_input_modes=["text/plain"],
        default_output_modes=["text/plain"],
        capabilities=AgentCapabilities(streaming=False),
        supported_interfaces=[
            AgentInterface(url="http://localhost:8001", protocol_binding="JSONRPC"),
        ],
        skills=[skill],
    )

def build_app() -> Starlette:
    """Wire the executor and card into a Starlette app with A2A routes."""
    card = build_agent_card()
    handler = DefaultRequestHandler(
        agent_executor=ResearchAgentExecutor(),
        task_store=InMemoryTaskStore(),
        agent_card=card,
    )
    routes = [
        *create_agent_card_routes(card),
        *create_jsonrpc_routes(handler, "/"),
    ]
    return Starlette(routes=routes)

app = build_app()

SYSTEM_PROMPT = (
    "You are an explainer. Rewrite the given text as a punchy, beginner-friendly "
    "explanation a smart 15-year-old would enjoy. Keep it to 3-4 short sentences. "
    "Use plain words and one concrete analogy. No preamble."
)

skill = AgentSkill(
    id="rewrite_simple",
    name="Rewrite Simply",
    description="Rewrites any text into a punchy, beginner-friendly explanation.",
    tags=["writing", "explainer"],
    examples=["Rewrite this dense paragraph so a beginner gets it"],
)

return AgentCard(
    name="Writer Agent",
    description="Rewrites text into a punchy, beginner-friendly explanation using Groq.",
    version="1.0.0",
    default_input_modes=["text/plain"],
    default_output_modes=["text/plain"],
    capabilities=AgentCapabilities(streaming=False),
    supported_interfaces=[
        AgentInterface(url="http://localhost:8002", protocol_binding="JSONRPC"),
    ],
    skills=[skill],
)

PYTHONPATH=. uv run uvicorn agents.writer_agent:app --port 8002
curl http://localhost:8002/.well-known/agent-card.json

# terminal 1
PYTHONPATH=. uv run uvicorn agents.research_agent:app --port 8001
# terminal 2
PYTHONPATH=. uv run uvicorn agents.writer_agent:app --port 8002
# terminal 3
PYTHONPATH=. uv run python orchestrator.py

{
  "jsonrpc": "2.0",
  "id": "req-1",
  "method": "message/send",
  "params": {
    "message": {
      "role": "ROLE_USER",
      "parts": [{ "text": "the transformer architecture in AI" }],
      "messageId": "a1b2c3d4"
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": "req-1",
  "result": {
    "id": "task-9f8e",
    "contextId": "ctx-7a6b",
    "status": { "state": "TASK_STATE_COMPLETED" },
    "artifacts": [{
      "artifactId": "art-1",
      "name": "result",
      "parts": [{ "text": "Transformers are a neural-network design that..." }]
    }]
  }
}

httpx.ConnectError: All connection attempts failed
  ... raised during A2ACardResolver.get_agent_card()
a2a.client.AgentCardResolutionError: agent card could not be resolved
  at http://localhost:8003/.well-known/agent-card.json