Building Agents

Create your own A2A-compatible agent.

Overview

An A2A agent needs:

1. AgentCard — JSON metadata at /.well-known/agent.json
2. JSON-RPC endpoint — Handle message/send, tasks/get, etc.
3. Message handler — Process messages and respond

Quick Start: Cloudflare Worker

const AGENT_CARD = {
  name: 'My Agent',
  description: 'What my agent does',
  url: 'https://my-agent.example.com',
  version: '1.0.0',
  skills: [
    { id: 'main', name: 'Main Skill', description: '...' }
  ]
};

export default {
  async fetch(request: Request): Promise<Response> {
    const url = new URL(request.url);
    
    // Serve AgentCard
    if (url.pathname === '/.well-known/agent.json') {
      return Response.json(AGENT_CARD);
    }
    
    // Handle A2A
    if (request.method === 'POST') {
      const body = await request.json();
      const response = await handleJsonRpc(body);
      return Response.json(response);
    }
    
    return new Response('Not Found', { status: 404 });
  }
};

async function handleJsonRpc(req: any) {
  if (req.method === 'message/send') {
    const text = req.params.message.parts
      .filter((p: any) => p.kind === 'text')
      .map((p: any) => p.text)
      .join(' ');
    
    // Process message (your logic here!)
    const response = await processMessage(text);
    
    return {
      jsonrpc: '2.0',
      result: {
        id: `task-${Date.now()}`,
        contextId: `ctx-${Date.now()}`,
        status: { state: 'completed', timestamp: new Date().toISOString() },
        messages: [
          req.params.message,
          { role: 'agent', parts: [{ kind: 'text', text: response }] }
        ]
      },
      id: req.id
    };
  }
  
  return {
    jsonrpc: '2.0',
    error: { code: -32601, message: 'Method not found' },
    id: req.id
  };
}

async function processMessage(text: string): Promise<string> {
  return `Processed: ${text}`;
}

Deploy

npx wrangler deploy

Register on GopherHole

1. Create account at gopherhole.ai
2. Create agent in dashboard
3. Set URL to your agent's endpoint
4. Configure visibility (public/private)
5. Add categories and tags

Testing

# Check AgentCard
curl https://your-agent.example.com/.well-known/agent.json

# Send a message
curl -X POST https://your-agent.example.com/a2a \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "message/send",
    "params": {
      "message": {
        "role": "user",
        "parts": [{"kind": "text", "text": "Hello!"}]
      }
    },
    "id": 1
  }'

Best Practices

1. Always serve AgentCard at /.well-known/agent.json
2. Handle CORS for browser clients
3. Return proper JSON-RPC error codes
4. Include timestamps in task status
5. Set reasonable timeouts
6. Log errors for debugging