@402md/a2a

A2A protocol SDK for Node.js. Discover, publish, and communicate with AI agents using the Agent-to-Agent (A2A) standard v0.3.0.

Serve — Middleware to serve your Agent Card at /.well-known/agent-card.json
Client — JSON-RPC client to send tasks to remote agents (with SSE streaming)
Handler — JSON-RPC server middleware to receive and process tasks
Validate — Validate Agent Cards against the spec
Discover — Fetch Agent Cards from any A2A-compatible agent

Zero framework lock-in. Works with Express, Hono, Next.js, Connect, and raw Node.js HTTP.

Installation

npm install @402md/a2a

Quick Start

1. Publish your agent (serve the Agent Card)

import express from 'express'
import { serveAgentCard } from '@402md/a2a'

const app = express()

// Reads ./SKILL.md and serves the Agent Card automatically
app.use(serveAgentCard())

app.listen(3000)

curl http://localhost:3000/.well-known/agent-card.json

Next.js App Router

// app/.well-known/agent-card.json/route.ts
import { agentCardResponse } from '@402md/a2a'

export const GET = agentCardResponse()

// app/a2a/route.ts
import { handleA2ANext } from '@402md/a2a'

export const POST = handleA2ANext({
  onSendTask: async (params) => ({
    id: params.id,
    status: {
      state: 'completed',
      message: {
        role: 'agent',
        parts: [{ type: 'text', text: `You said: ${params.message.parts[0].type === 'text' ? params.message.parts[0].text : ''}` }]
      }
    }
  })
})

2. Discover a remote agent

import { fetchAgentCard } from '@402md/a2a'

const card = await fetchAgentCard('https://agent.example.com')
console.log(card.name, card.skills)

3. Send a task to a remote agent

import { A2AClient } from '@402md/a2a'

const client = new A2AClient('https://agent.example.com')

const task = await client.sendTask({
  role: 'user',
  parts: [{ type: 'text', text: 'What is the weather in Tokyo?' }]
})

console.log(task.status.state) // 'completed'
console.log(task.status.message) // agent's response

4. Handle incoming tasks (be an A2A server)

import express from 'express'
import { serveAgentCard, handleA2A } from '@402md/a2a'

const app = express()

// Discovery
app.use(serveAgentCard())

// Task handler
app.use(handleA2A({
  onSendTask: async (params) => {
    const userText = params.message.parts
      .filter(p => p.type === 'text')
      .map(p => p.text)
      .join(' ')

    return {
      id: params.id,
      status: {
        state: 'completed',
        message: {
          role: 'agent',
          parts: [{ type: 'text', text: `You said: ${userText}` }]
        }
      }
    }
  }
}))

app.listen(3000)

API Reference

Discovery

`serveAgentCard(options?)`

Express/Connect middleware that serves the Agent Card at /.well-known/agent-card.json.

function serveAgentCard(options?: ServeAgentCardOptions | string): Middleware

Reads SKILL.md once at startup, caches the JSON
String shorthand: serveAgentCard('./path/to/SKILL.md')
Cache-Control: public, max-age=3600 by default

`serveAgentCardHono(options?)`

Same as serveAgentCard, but for Hono:

import { Hono } from 'hono'
import { serveAgentCardHono } from '@402md/a2a'

const app = new Hono()
app.use(serveAgentCardHono())

`ServeAgentCardOptions`

Option	Type	Default	Description
`skillMdPath`	`string`	`'./SKILL.md'`	Path to the SKILL.md file
`card`	`A2AAgentCard`	—	Pre-built card (skips file reading)
`maxAge`	`number`	`3600`	Cache-Control max-age in seconds
`url`	`string`	manifest `base_url`	Override the agent's URL
`providerName`	`string`	manifest `author`	Provider organization name
`providerUrl`	`string`	—	Provider URL
`authSchemes`	`A2AAuthScheme[]`	`[{ scheme: 'x402' }]`	Authentication schemes
`preferredTransport`	`A2ATransport`	`'REST'`	Transport protocol
`streaming`	`boolean`	—	Streaming support
`pushNotifications`	`boolean`	—	Push notification support
`documentationUrl`	`string`	—	Link to docs

`fetchAgentCard(baseUrl, options?)`

Fetch a remote agent's Agent Card:

const card = await fetchAgentCard('https://agent.example.com')
// Hits GET https://agent.example.com/.well-known/agent-card.json

Supports AbortSignal for cancellation:

const controller = new AbortController()
const card = await fetchAgentCard(url, { signal: controller.signal })

`toAgentCard(manifest, options?)`

Pure function to convert a SkillManifest into an A2AAgentCard. Re-exported from @402md/skillmd:

import { toAgentCard } from '@402md/a2a'
import { parseSkillMd } from '@402md/skillmd'

const manifest = parseSkillMd(raw)
const card = toAgentCard(manifest, { providerName: 'Acme Corp' })

Mapping:

Agent Card field	Source
`schemaVersion`	`'1.0'`
`humanReadableId`	`author/name` or `name`
`agentVersion`	`manifest.version` or `'1.0.0'`
`name`	`manifest.displayName` or `manifest.name`
`url`	`options.url` or `manifest.base_url`
`protocolVersion`	`'0.3.0'`
`authSchemes`	`options.authSchemes` or `[{ scheme: 'x402' }]`
`skills[]`	One per `manifest.endpoints`

Client

`A2AClient`

Full A2A JSON-RPC client with support for all standard methods:

const client = new A2AClient('https://agent.example.com', {
  headers: { 'Authorization': 'Bearer token' }
})

Methods:

Method	Description
`client.agentCard()`	Fetch the agent's Agent Card
`client.sendTask(params)`	Send a task (`tasks/send`)
`client.sendTask(message, id?)`	Shorthand — pass a `Message` directly
`client.getTask(id, historyLength?)`	Get task status (`tasks/get`)
`client.cancelTask(id)`	Cancel a task (`tasks/cancel`)
`client.sendTaskSubscribe(params)`	Stream task updates via SSE (`tasks/sendSubscribe`)
`client.setPushNotification(id, config)`	Set push notification config
`client.getPushNotification(id)`	Get push notification config

Sending a task

// Full params
const task = await client.sendTask({
  id: 'task-123',
  message: {
    role: 'user',
    parts: [{ type: 'text', text: 'Summarize this document' }]
  },
  historyLength: 5
})

// Shorthand
const task = await client.sendTask(
  { role: 'user', parts: [{ type: 'text', text: 'Hello' }] },
  'task-456' // optional id, auto-generated if omitted
)

Streaming

const params = {
  id: 'task-789',
  message: {
    role: 'user' as const,
    parts: [{ type: 'text' as const, text: 'Write a poem' }]
  }
}

for await (const event of client.sendTaskSubscribe(params)) {
  if (event.type === 'status') {
    console.log('Status:', event.status.state)
  } else if (event.type === 'artifact') {
    console.log('Artifact:', event.artifact)
  }
}

Error handling

import { A2AClientError } from '@402md/a2a'

try {
  await client.sendTask(message)
} catch (err) {
  if (err instanceof A2AClientError) {
    console.log(err.statusCode) // HTTP status (e.g. 404)
    console.log(err.rpcCode)    // JSON-RPC error code (e.g. -32001)
    console.log(err.data)       // Extra error data from server
  }
}

Server Handler

`handleA2A(handlers, options?)`

Express/Connect middleware that handles incoming A2A JSON-RPC requests:

function handleA2A(handlers: A2AHandlers, options?: HandleA2AOptions): Middleware

A2AHandlers:

Handler	Required	Method	Description
`onSendTask`	Yes	`tasks/send`	Process an incoming task
`onGetTask`	No	`tasks/get`	Return task status (returns error if not implemented)
`onCancelTask`	No	`tasks/cancel`	Cancel a task (returns error if not implemented)

HandleA2AOptions:

Option	Type	Default	Description
`path`	`string`	`'/'`	Path to listen on for JSON-RPC requests

Full server example with task persistence

import express from 'express'
import { serveAgentCard, handleA2A } from '@402md/a2a'
import type { Task, SendTaskParams, GetTaskParams, CancelTaskParams } from '@402md/a2a'

const app = express()
const tasks = new Map<string, Task>()

app.use(serveAgentCard())

app.use(handleA2A({
  onSendTask: async (params: SendTaskParams): Promise<Task> => {
    const task: Task = {
      id: params.id,
      status: {
        state: 'completed',
        message: {
          role: 'agent',
          parts: [{ type: 'text', text: 'Task processed!' }]
        },
        timestamp: new Date().toISOString()
      },
      history: [params.message]
    }

    tasks.set(task.id, task)
    return task
  },

  onGetTask: async (params: GetTaskParams): Promise<Task> => {
    const task = tasks.get(params.id)
    if (!task) throw new Error('Task not found')
    return task
  },

  onCancelTask: async (params: CancelTaskParams): Promise<Task> => {
    const task = tasks.get(params.id)
    if (!task) throw new Error('Task not found')
    task.status = { state: 'canceled', timestamp: new Date().toISOString() }
    return task
  }
}))

app.listen(3000)

Next.js App Router

`agentCardResponse(options?)`

Next.js route handler for serving the Agent Card. Use in app/.well-known/agent-card.json/route.ts:

function agentCardResponse(options?: ServeAgentCardOptions | string): NextRouteHandler

Accepts the same ServeAgentCardOptions as serveAgentCard(). The card is built once and cached.

// Default — reads ./SKILL.md
export const GET = agentCardResponse()

// Custom path
export const GET = agentCardResponse('./skills/my-agent.md')

// Pre-built card
export const GET = agentCardResponse({ card: myCard, maxAge: 7200 })

`handleA2ANext(handlers)`

Next.js route handler for A2A JSON-RPC requests. Use in app/a2a/route.ts (or any route):

function handleA2ANext(handlers: A2AHandlers): NextRouteHandler

Same A2AHandlers interface as handleA2A() — onSendTask (required), onGetTask, onCancelTask.

Full Next.js example

app/
  .well-known/
    agent-card.json/
      route.ts          ← agentCardResponse()
  a2a/
    route.ts            ← handleA2ANext()

// app/.well-known/agent-card.json/route.ts
import { agentCardResponse } from '@402md/a2a'

export const GET = agentCardResponse()

// app/a2a/route.ts
import { handleA2ANext } from '@402md/a2a'
import type { Task, SendTaskParams, GetTaskParams } from '@402md/a2a'

const tasks = new Map<string, Task>()

export const POST = handleA2ANext({
  onSendTask: async (params: SendTaskParams): Promise<Task> => {
    const task: Task = {
      id: params.id,
      status: {
        state: 'completed',
        message: {
          role: 'agent',
          parts: [{ type: 'text', text: 'Processed by Next.js!' }]
        },
        timestamp: new Date().toISOString()
      },
      history: [params.message]
    }
    tasks.set(task.id, task)
    return task
  },

  onGetTask: async (params: GetTaskParams): Promise<Task> => {
    const task = tasks.get(params.id)
    if (!task) throw new Error('Task not found')
    return task
  }
})

Validation

`validateAgentCard(card)`

Validate any object against the A2A v0.3.0 Agent Card spec:

import { validateAgentCard } from '@402md/a2a'

const result = validateAgentCard(someCard)

if (!result.valid) {
  console.error('Errors:', result.errors)
}

if (result.warnings.length > 0) {
  console.warn('Warnings:', result.warnings)
}

What it checks:

Category	Checks
Required fields	`schemaVersion`, `humanReadableId`, `agentVersion`, `name`, `description`, `url`, `protocolVersion`, `preferredTransport`
Provider	Must have `provider.name`
Capabilities	Must have `capabilities.a2aVersion`
Auth	`authSchemes` must be a non-empty array with valid `scheme` fields
URL	`url` and `documentationUrl` must be valid URLs
Skills	Each skill must have `id`, `name`, `description`
Warnings	Missing `skills`, missing `documentationUrl`

Validate a fetched card

import { fetchAgentCard, validateAgentCard } from '@402md/a2a'

const card = await fetchAgentCard('https://agent.example.com')
const { valid, errors, warnings } = validateAgentCard(card as Record<string, unknown>)

if (!valid) {
  console.error('This agent card is non-compliant:', errors)
}

Combining Everything

Full A2A agent with @402md/gateway

import express from 'express'
import { Gateway } from '@402md/gateway'
import { serveAgentCard, handleA2A } from '@402md/a2a'

const app = express()
const gateway = new Gateway({ skillToken: process.env.SKILL_TOKEN })

// 1. Discovery — public
app.use(serveAgentCard())

// 2. A2A protocol — handles tasks/send, tasks/get, etc.
app.use('/a2a', handleA2A({
  onSendTask: async (params) => {
    // Your agent logic here
    return {
      id: params.id,
      status: { state: 'completed', message: {
        role: 'agent',
        parts: [{ type: 'text', text: 'Done!' }]
      }}
    }
  }
}, { path: '/a2a' }))

// 3. Direct REST API — protected by x402 payment
app.post('/v1/generate', gateway.protect(), (req, res) => {
  res.json({ result: 'paid content' })
})

app.listen(3000)

Agent-to-agent communication

import { A2AClient, fetchAgentCard } from '@402md/a2a'

// Discover
const card = await fetchAgentCard('https://other-agent.example.com')
console.log(`Found: ${card.name} with ${card.skills?.length ?? 0} skills`)

// Communicate
const client = new A2AClient('https://other-agent.example.com')
const task = await client.sendTask({
  role: 'user',
  parts: [{ type: 'text', text: 'Translate this to Japanese: Hello world' }]
})

if (task.status.state === 'completed') {
  const reply = task.status.message?.parts
    .filter(p => p.type === 'text')
    .map(p => (p as { text: string }).text)
    .join('')

  console.log('Translation:', reply)
}

Types

Protocol Types

import type {
  // Tasks
  Task,
  TaskState,        // 'submitted' | 'working' | 'completed' | 'failed' | ...
  TaskStatus,
  Artifact,

  // Messages
  Message,          // { role: 'user' | 'agent', parts: Part[] }
  Part,             // TextPart | FilePart | DataPart
  TextPart,         // { type: 'text', text: string }
  FilePart,         // { type: 'file', file: { name?, mimeType?, bytes?, uri? } }
  DataPart,         // { type: 'data', data: Record<string, unknown> }

  // Params
  SendTaskParams,
  GetTaskParams,
  CancelTaskParams,
  PushNotificationConfig,

  // Streaming
  TaskStatusUpdateEvent,
  TaskArtifactUpdateEvent,
  TaskUpdateEvent,

  // JSON-RPC
  JsonRpcRequest,
  JsonRpcResponse,
  JsonRpcError
} from '@402md/a2a'

Agent Card Types

import type {
  A2AAgentCard,
  A2ATransport,     // 'JSONRPC' | 'gRPC' | 'REST'
  A2AProvider,
  A2ACapabilities,
  A2AAuthScheme,
  A2ASkill,
  ToAgentCardOptions
} from '@402md/a2a'

Error Codes

import { A2A_ERROR_CODES } from '@402md/a2a'

A2A_ERROR_CODES.TASK_NOT_FOUND        // -32001
A2A_ERROR_CODES.TASK_NOT_CANCELABLE   // -32002
A2A_ERROR_CODES.UNSUPPORTED_OPERATION // -32004
A2A_ERROR_CODES.INVALID_REQUEST       // -32600
A2A_ERROR_CODES.METHOD_NOT_FOUND      // -32601
A2A_ERROR_CODES.INVALID_PARAMS        // -32602
A2A_ERROR_CODES.INTERNAL_ERROR        // -32603
A2A_ERROR_CODES.PARSE_ERROR           // -32700

A2A Protocol Compatibility

This package targets A2A specification v0.3.0.

Feature	Status
Agent Card discovery (`/.well-known/agent-card.json`)	Supported
`tasks/send`	Supported
`tasks/get`	Supported
`tasks/cancel`	Supported
`tasks/sendSubscribe` (SSE streaming)	Client only
`tasks/pushNotification/set`	Client only
`tasks/pushNotification/get`	Client only

Framework Support

Framework	Discovery	Handler
Express / Connect	`serveAgentCard()`	`handleA2A()`
Hono	`serveAgentCardHono()`	`handleA2A()`
Next.js App Router	`agentCardResponse()`	`handleA2ANext()`
Raw Node.js HTTP	`serveAgentCard()`	`handleA2A()`

License

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 13 Commits
__tests__		__tests__
src		src
.gitignore		.gitignore
.prettierrc		.prettierrc
README.md		README.md
eslint.config.mjs		eslint.config.mjs
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json
tsup.config.ts		tsup.config.ts

Folders and files

Latest commit

History

Repository files navigation

@402md/a2a

Installation

Quick Start

1. Publish your agent (serve the Agent Card)

Next.js App Router

2. Discover a remote agent

3. Send a task to a remote agent

4. Handle incoming tasks (be an A2A server)

API Reference

Discovery

serveAgentCard(options?)

serveAgentCardHono(options?)

ServeAgentCardOptions

fetchAgentCard(baseUrl, options?)

toAgentCard(manifest, options?)

Client

A2AClient

Sending a task

Streaming

Error handling

Server Handler

handleA2A(handlers, options?)

Full server example with task persistence

Next.js App Router

agentCardResponse(options?)

handleA2ANext(handlers)

Full Next.js example

Validation

validateAgentCard(card)

Validate a fetched card

Combining Everything

Full A2A agent with @402md/gateway

Agent-to-agent communication

Types

Protocol Types

Agent Card Types

Error Codes

A2A Protocol Compatibility

Framework Support

License

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

`serveAgentCard(options?)`

`serveAgentCardHono(options?)`

`ServeAgentCardOptions`

`fetchAgentCard(baseUrl, options?)`

`toAgentCard(manifest, options?)`

`A2AClient`

`handleA2A(handlers, options?)`

`agentCardResponse(options?)`

`handleA2ANext(handlers)`

`validateAgentCard(card)`

Packages