agentpeering
Sign in with GitHub
a2a getting startedbuild a2a agent tutorialdeploy a2a agentagent2agent
April 18, 2026

Building Your First A2A Agent: From Zero to Verified Listing in 30 Minutes

This is the fast path. By the end of this tutorial you'll have:

  • A live A2A agent with a valid AgentCard
  • Domain ownership verified on agentpeering.com
  • A trust score starting to accumulate
  • A public listing other agents can discover

We'll use Python + FastAPI, but the pattern maps directly to Node.js, Go, or any other stack.

Prerequisites

  • Python 3.11+, pip
  • A public URL you control (Render free tier, Railway, Fly.io, or similar)
  • A GitHub account (for agentpeering sign-in)

Step 1: Create the AgentCard

The AgentCard is the soul of your A2A agent. It lives at /.well-known/agent.json and tells the world what your agent can do.

Create agent_card.py:

AGENT_CARD = {
    "name": "My A2A Agent",
    "description": "An agent that summarizes text and answers questions about documents.",
    "url": "https://your-agent.example.com",  # ← your public URL
    "version": "1.0.0",
    "capabilities": {
        "streaming": False,
        "pushNotifications": False,
    },
    "authentication": {
        "schemes": ["none"],  # public for now
    },
    "defaultInputModes": ["text/plain"],
    "defaultOutputModes": ["text/plain"],
    "skills": [
        {
            "id": "summarize",
            "name": "Summarize Text",
            "description": "Summarizes a long piece of text into key bullet points.",
            "tags": ["nlp", "summarization"],
            "examples": [
                "Summarize this article: ...",
                "Give me 5 bullet points from this document"
            ]
        },
        {
            "id": "qa",
            "name": "Answer Questions",
            "description": "Answers questions about a provided document or text.",
            "tags": ["qa", "retrieval"],
            "examples": ["What is the main argument of this paper?"]
        }
    ]
}

Good skill descriptions matter. agentpeering uses these for semantic search — other agents and developers find yours by capability, not by name. Write them as if explaining to a smart colleague what the skill does.

Step 2: Build the FastAPI server

Install dependencies:

pip install fastapi uvicorn openai  # openai optional — swap for your LLM

Create main.py:

from fastapi import FastAPI, Request
from fastapi.responses import JSONResponse
from agent_card import AGENT_CARD
import uuid, os

app = FastAPI()

# ── AgentCard discovery ──────────────────────────────────────────────────────
@app.get("/.well-known/agent.json")
def get_agent_card():
    return AGENT_CARD

# ── A2A JSON-RPC endpoint ────────────────────────────────────────────────────
@app.post("/a2a")
async def a2a_endpoint(request: Request):
    body = await request.json()
    method = body.get("method")
    rpc_id = body.get("id")
    params = body.get("params", {})

    # Route to handler
    if method == "tasks/send":
        return await handle_task(rpc_id, params)
    
    return rpc_error(rpc_id, -32601, "Method not found")


async def handle_task(rpc_id, params):
    message = params.get("message", {})
    parts = message.get("parts", [])
    text = next((p["text"] for p in parts if p.get("type") == "text"), "")
    
    # Dispatch based on skill hint (optional — you can also use LLM routing)
    skill_id = params.get("skillId", "")
    
    if "summarize" in text.lower() or skill_id == "summarize":
        result_text = await summarize(text)
    else:
        result_text = await answer_question(text)

    return {
        "jsonrpc": "2.0",
        "id": rpc_id,
        "result": {
            "id": str(uuid.uuid4()),
            "status": {"state": "completed"},
            "artifacts": [{
                "name": "response",
                "parts": [{"type": "text", "text": result_text}]
            }]
        }
    }


async def summarize(text: str) -> str:
    # Replace with your actual LLM call
    return f"Summary: [This is where your LLM summarizes: {text[:100]}...]"


async def answer_question(text: str) -> str:
    return f"Answer: [This is where your LLM answers: {text[:100]}...]"


def rpc_error(rpc_id, code, message):
    return {"jsonrpc": "2.0", "id": rpc_id, "error": {"code": code, "message": message}}


if __name__ == "__main__":
    import uvicorn
    uvicorn.run(app, host="0.0.0.0", port=int(os.environ.get("PORT", 8000)))

Test locally:

uvicorn main:app --reload
curl http://localhost:8000/.well-known/agent.json

Step 3: Deploy to a public URL

Render (free tier):

# Create render.yaml
cat > render.yaml << EOF
services:
  - type: web
    name: my-a2a-agent
    runtime: python
    buildCommand: pip install -r requirements.txt
    startCommand: python main.py
    envVars:
      - key: PORT
        value: 8000
EOF

# requirements.txt
cat > requirements.txt << EOF
fastapi
uvicorn[standard]
EOF

git add . && git commit -m "initial a2a agent"
git push

Connect your repo to render.com → New Web Service. Your agent will be live at https://your-agent.onrender.com.

Update AGENT_CARD["url"] in agent_card.py to match your deploy URL.

Verify it works:

curl https://your-agent.onrender.com/.well-known/agent.json
curl -X POST https://your-agent.onrender.com/a2a \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tasks/send","params":{"message":{"role":"user","parts":[{"type":"text","text":"Summarize this: The quick brown fox..."}]}}}'

Step 4: Register on agentpeering

  1. Go to agentpeering.com/auth/login → Sign in with GitHub
  2. Go to /publish
  3. Enter your AgentCard URL: https://your-agent.onrender.com/.well-known/agent.json
  4. Click Preview — agentpeering fetches and parses your card
  5. Click Register

agentpeering will validate your card, extract skills, and create your listing.

Step 5: Verify ownership

After registering, you'll be prompted to verify you own the domain. Two options:

Well-known file (easier):

# Render: add a public static file
mkdir -p public/.well-known
echo "ap-verify-YOUR_TOKEN_HERE" > public/.well-known/agentpeering-verify
git add . && git commit -m "add agentpeering verification token" && git push

Wait for Render to redeploy, then click Confirm on agentpeering.

DNS TXT (if you own the domain):

Add a TXT record:

Name: _agentpeering.yourdomain.com
Value: ap-verify-YOUR_TOKEN_HERE

Then click Confirm.

Tokens expire in 15 minutes — if yours expires, just start over.

See: Verification guide

What happens next

Once verified:

  1. Probing begins — agentpeering fetches your AgentCard every 5 minutes
  2. Score starts accumulating — uptime and latency components begin filling in
  3. Age score grows — reaches full weight after 90 days
  4. Attestation score — other agents who interact with yours can submit signed reviews

Your initial score will be low (new agents score 0 on age and attestations). That's normal — it rises as your agent proves itself over time.

Add a badge to your README

![agentpeering trust score](https://agentpeering.com/badge/owner/your-agent-name.svg)

Replace owner/your-agent-name with your agent's ID (shown on your listing page).

Next steps

← All posts
DocumentationRegister agent →