a2a-js-dev

Files (3)

• SKILL.md
• protocol-spec.md · references/
• sdk-api.md · references/

SKILL.md (first lines)

# A2A JavaScript/TypeScript SDK Development Guide

Build standards-compliant agent-to-agent applications using the `@a2a-js/sdk`. This guide covers server agents, clients, task management, streaming, and all three transport bindings.

## Quick Reference

```bash
# Install the SDK
npm install @a2a-js/sdk

# For Express server integration
npm install express

# For gRPC support (Node.js only)
npm install @grpc/grpc-js @bufbuild/protobuf
```

**Import paths:**
```typescript
import { AgentCard, Message, Task, AGENT_CARD_PATH } from '@a2a-js/sdk';
import { AgentExecutor, DefaultRequestHandler, InMemoryTaskStore } from '@a2a-js/sdk/server';
import { agentCardHandler, jsonRpcHandler, restHandler, UserBuilder } from '@a2a-js/sdk/server/express';
import { ClientFactory } from '@a2a-js/sdk/client';
import { GrpcTransportFactory } from '@a2a-js/sdk/client/grpc';
```

The SDK implements **A2A Protocol Specification v0.3.0**.

---

## Architecture Overview

An A2A application has two sides:

1. **Server (Agent)** — exposes capabilities via an Agent Card, handles incoming messages, manages tasks, and publishes events
2. **Client (Consumer)** — discovers agents, sends messages, tracks tasks, and consumes streaming updates

The protocol supports three transport bindings. Each transport provides the same operations — pick based on your deployment needs:

| Transport | Client | Server | Notes |
|-----------|--------|--------|-------|
| JSON-RPC | Yes | Yes | Default, works everywhere |
| HTTP+JSON/REST | Yes | Yes | RESTful, good for web clients |
| gRPC | Yes | Yes | Node.js only, high performance |

---

## Building an A2A Server

### Step 1: Define the Agent Card

The Agent Card is the identity and capability declaration for your agent. Other agents discover it at `/.well-known/agent-card.json`.

```typescript
import { AgentCard } from '@a2a-js/sdk';

const agentCard: AgentCard = {
  name: 'My Agent',
  description: 'Describe what your agent does clearly.',
  protocolVersion: '0.3.0',
  version: '1.0.0',
  url: 'http://localhost:4000/a2a/jsonrpc',
  skills: [
    {
      id: 'skill-id',
      name: 'Skill Name',
      description: 'What this skill does',
      tags: ['relevant', 'tags'],
    },
  ],
  capabilities: {
    pushNotifications: false,
    streaming: true,
  },
  defaultInputModes: ['text'],
  defaultOutputModes: ['text'],
  additionalInterfaces: [
    { url: 'http://localhost:4000/a2a/jsonrpc', transport: 'JSONRPC' },
    { url: 'http://localhost:4000/a2a/rest', transport: 'HTTP+JSON' },
  ],
};
```

**Key design decisions for the Agent Card:**
- `skills` — declare what your agent can do so clients can match capabilities
- `capabilities` — advertise streaming and push notification support honestly; clients check these before using those features
- `additionalInterfaces` — list all transport endpoints you support so `ClientFactory` can auto-select

### Step 2: Implement the AgentExecutor

This is where your agent's logic lives. The `execute` method receives a `RequestContext` and an `ExecutionEventBus`.

```typescript
import { AgentExecutor, RequestContext, ExecutionEventBus } from '@a2a-js/sdk/server';
import { Message, Task, TaskStatusUpdateEvent, TaskArtifactUpdateEvent } from '@a2a-js/sdk';
import { v4 as uuidv4 } from 'uuid';

class MyAgentExecutor implements AgentExecutor {
  async execute(
    requestContext: RequestContext,
    eventBus: ExecutionEventBus
  ): Promise<void> {
    const { taskId, contextId, userMessage, task } = requestContext;

    // Access the user's message text
    const userText = userMessage.parts
      .filter((p) => p.kind === 'text')
      .map((p) => p.text)
      .join('\n');

    // If this is a new task (no existing task), initialize it
    if (!task) {
      const newTask: Task = {
        kind: 'task',
        id: taskId,
        contextId,
        status: { state: 'working', timestamp: new Date().toISOString() },
        history: [userMessage],
      };

From delexw/claude-code-misc, MIT.

More from delexw/claude-code-misc