A2A Protocol Quickstart

This guide will help you get started with the A2A protocol, whether you're implementing a client, a server, or both.

Prerequisites

Basic understanding of HTTP and JSON-RPC
Development environment with your preferred language
Familiarity with authentication concepts

Installation

A2A is a protocol specification, not a specific library or framework. However, there are reference implementations and SDKs available:

# JavaScript/TypeScript client
npm install @a2a/client
 
# Python client
pip install a2a-client
 
# Server SDK for Node.js
npm install @a2a/server

Basic Client Implementation

Here's a simple TypeScript example of a client creating a task:

import { A2AClient } from '@a2a/client';
 
// Initialize the client with agent URL
const client = new A2AClient({
  url: 'https://example-agent.com/a2a',
  authToken: 'your-auth-token'
});
 
// Create a task
async function createSimpleTask() {
  const task = await client.createTask({
    message: {
      parts: [
        {
          mimeType: 'text/plain',
          data: 'What's the weather in San Francisco today?'
        }
      ]
    }
  });
  
  console.log(`Created task with ID: ${task.taskId}`);
  return task;
}
 
// Poll until task completes
async function waitForCompletion(taskId) {
  let task;
  do {
    task = await client.getTask({ taskId });
    console.log(`Task status: ${task.status}`);
    
    if (task.status === 'Completed' || task.status === 'Failed') {
      break;
    }
    
    await new Promise(resolve => setTimeout(resolve, 1000));
  } while (true);
  
  return task;
}
 
// Main function
async function main() {
  const task = await createSimpleTask();
  const completedTask = await waitForCompletion(task.taskId);
  
  if (completedTask.status === 'Completed') {
    console.log('Task artifacts:', completedTask.artifacts);
  } else {
    console.error('Task failed');
  }
}
 
main().catch(console.error);

Simple Server Implementation

Here's a basic Node.js example for implementing an A2A server:

import { A2AServer } from '@a2a/server';
import express from 'express';
 
const app = express();
const port = 3000;
 
// Initialize the A2A server
const server = new A2AServer({
  agentCard: {
    name: 'Example Agent',
    description: 'A simple example A2A agent',
    url: `http://localhost:${port}/a2a`,
    version: '1.0.0',
    authentication: {
      schemes: ['Bearer']
    },
    capabilities: {
      streaming: true
    },
    defaultInputModes: ['text/plain'],
    defaultOutputModes: ['text/plain'],
    skills: [
      {
        id: 'echo',
        name: 'Echo',
        description: 'Echoes back the user input',
        tags: ['utility'],
        examples: ['Hello, world!']
      }
    ]
  },
  
  // Task handler
  async handleTask(task) {
    // Get the input message
    const inputMessage = task.messages[0];
    const inputText = inputMessage.parts[0].data.toString();
    
    // Process the task (in this case, just echo back)
    const outputText = `Echo: ${inputText}`;
    
    // Create an artifact with the result
    return {
      status: 'Completed',
      artifacts: [
        {
          id: 'echo-result',
          type: 'echo',
          parts: [
            {
              mimeType: 'text/plain',
              data: outputText
            }
          ],
          created: new Date().toISOString()
        }
      ]
    };
  }
});
 
// Register A2A routes with Express
app.use('/a2a', server.router);
app.get('/.well-known/agent.json', (req, res) => {
  res.json(server.agentCard);
});
 
// Start the server
app.listen(port, () => {
  console.log(`A2A server running at http://localhost:${port}`);
});

Next Steps

After getting the basics working:

Explore more complex communication patterns, like multi-turn conversations
Implement streaming for real-time updates
Add push notifications for long-running tasks
Integrate with production authentication systems
Check out the Samples for more examples

Troubleshooting

Common issues and solutions:

Authentication Errors: Ensure you're using the correct authentication scheme and credentials
Content Type Mismatches: Verify that your MIME types match what the agent supports
HTTP Status Codes: 401/403 indicate auth issues, 404 means endpoint not found, 500 is server error

Quickstart