a2a

The A2A (Agent-to-Agent) extension implements the A2A protocol for agent discovery and inter-agent communication.

Installation

bun add @regent/a2a

Basic Usage

import { createAgent } from '@regent/core';
import { http } from '@regent/http';
import { a2a } from '@regent/a2a';

const agent = await createAgent({
  name: 'my-agent',
  version: '1.0.0',
})
  .use(http())
  .use(a2a())
  .build();

// Build this agent's card
const card = agent.a2a.buildCard('https://my-agent.example.com');

// Fetch another agent's card
const otherCard = await agent.a2a.fetchCard('https://other-agent.example.com');

// Invoke another agent
const result = await agent.a2a.client.invoke(otherCard, 'echo', { text: 'hello' });

API Reference

a2a()

Creates the A2A extension.

function a2a(): Extension<{ a2a?: A2ARuntime }>

A2ARuntime

When the extension is used, agent.a2a provides:

interface A2ARuntime {
  buildCard(origin: string): AgentCardWithEntrypoints;
  fetchCard(baseUrl: string, fetchImpl?: FetchFunction): Promise<AgentCard>;
  fetchCardWithEntrypoints(baseUrl: string, fetchImpl?: FetchFunction): Promise<AgentCardWithEntrypoints>;
  client: A2AClient;
}

Agent Cards

Building Cards

const card = agent.a2a.buildCard('https://my-agent.example.com');

Returns an AgentCardWithEntrypoints containing:

• Agent identity (name, version, description)

• Skills derived from entrypoints

• Capabilities (streaming, pushNotifications, stateTransitionHistory)

• Full entrypoints manifest

Fetching Cards

// Fetch another agent's card
const card = await agent.a2a.fetchCard('https://other-agent.example.com');

Discovery paths (tried in order):

1. Direct URL (for ERC-8004)

2. /.well-known/agent-card.json

3. /.well-known/agent.json

4. /agentcard.json

AgentCard Structure

type AgentCard = {
  protocolVersion?: string;      // "1.0"
  name: string;
  description?: string;
  version?: string;
  url?: string;
  iconUrl?: string;
  capabilities?: AgentCapabilities;
  skills?: Skill[];
  payments?: PaymentMethod[];
  registrations?: RegistrationEntry[];
  trustModels?: TrustModel[];
  defaultInputModes?: string[];
  defaultOutputModes?: string[];
};

Card Utilities

import { findSkill, hasCapability, hasSkillTag, supportsPayments, hasTrustInfo } from '@regent/a2a';

// Find a skill by ID
const skill = findSkill(card, 'echo');

// Check capabilities
if (hasCapability(card, 'streaming')) {
  // Use streaming endpoint
}

// Check for skill tags
if (hasSkillTag(card, 'blockchain')) {
  // Agent has blockchain skills
}

// Check payment support
if (supportsPayments(card)) {
  // Payment required
}

// Check trust info
if (hasTrustInfo(card)) {
  // Has identity/trust information
}

A2A Client

The client object provides methods for calling other agents.

Direct Invocation

invoke()

Directly invoke an entrypoint:

const result = await agent.a2a.client.invoke(card, 'echo', { text: 'hello' });
// { run_id: string, status: 'completed' | 'failed', output: unknown }

Endpoint: POST /entrypoints/{skillId}/invoke

stream()

Stream responses:

await agent.a2a.client.stream(
  card,
  'generate',
  { prompt: 'hello' },
  async (event) => {
    if (event.type === 'delta') {
      console.log(event.data);
    }
  }
);

Endpoint: POST /entrypoints/{skillId}/stream

fetchAndInvoke()

Convenience method:

const result = await agent.a2a.client.fetchAndInvoke(
  'https://other-agent.example.com',
  'echo',
  { text: 'hello' }
);

Task-Based Operations

Task-based operations enable asynchronous, multi-turn interactions.

Sending Messages

const response = await agent.a2a.client.sendMessage(
  card,
  'chat',
  { text: 'hello' },
  undefined,
  { contextId: 'conv-123' }
);
// { taskId: string, status: 'running' }

Endpoint: POST /tasks

Getting Task Status

const task = await agent.a2a.client.getTask(card, taskId);
// { taskId, status, result?, error?, createdAt, updatedAt }

Status values: 'running' | 'completed' | 'failed' | 'cancelled'

Subscribing to Updates

await agent.a2a.client.subscribeTask(card, taskId, async (event) => {
  if (event.data.status === 'completed') {
    console.log('Result:', event.data.result);
  }
});

Endpoint: GET /tasks/{taskId}/subscribe (SSE)

Listing Tasks

const tasks = await agent.a2a.client.listTasks(card, {
  contextId: 'conv-123',
  status: 'completed',
  limit: 10,
});

Cancelling Tasks

const cancelled = await agent.a2a.client.cancelTask(card, taskId);

Waiting for Tasks

import { waitForTask } from '@regent/a2a';

const completed = await waitForTask(agent.a2a.client, card, taskId, 30000);

Multi-Turn Conversations

Use contextId to maintain conversation context:

const contextId = 'conv-123';

// First message
const r1 = await agent.a2a.client.sendMessage(
  card, 'chat', { text: 'What is AI?' },
  undefined, { contextId }
);
await waitForTask(agent.a2a.client, card, r1.taskId);

// Follow-up in same context
const r2 = await agent.a2a.client.sendMessage(
  card, 'chat', { text: 'Tell me more' },
  undefined, { contextId }
);
await waitForTask(agent.a2a.client, card, r2.taskId);

// List conversation history
const history = await agent.a2a.client.listTasks(card, { contextId });

A2AClient Interface

interface A2AClient {
  // Direct invocation
  invoke(card: AgentCard, skillId: string, input: unknown, fetch?: FetchFunction): Promise<InvokeAgentResult>;
  stream(card: AgentCard, skillId: string, input: unknown, emit: StreamEmit, fetch?: FetchFunction): Promise<void>;
  fetchAndInvoke(baseUrl: string, skillId: string, input: unknown, fetch?: FetchFunction): Promise<InvokeAgentResult>;

  // Task-based
  sendMessage(card: AgentCard, skillId: string, input: unknown, fetch?: FetchFunction, options?: { contextId?: string; metadata?: Record<string, unknown> }): Promise<SendMessageResponse>;
  getTask(card: AgentCard, taskId: string, fetch?: FetchFunction): Promise<Task>;
  subscribeTask(card: AgentCard, taskId: string, emit: (chunk: TaskUpdateEvent) => void, fetch?: FetchFunction): Promise<void>;
  fetchAndSendMessage(baseUrl: string, skillId: string, input: unknown, fetch?: FetchFunction): Promise<SendMessageResponse>;
  listTasks(card: AgentCard, filters?: ListTasksRequest, fetch?: FetchFunction): Promise<ListTasksResponse>;
  cancelTask(card: AgentCard, taskId: string, fetch?: FetchFunction): Promise<Task>;
}

Types

InvokeAgentResult

type InvokeAgentResult = {
  run_id: string;
  status: 'completed' | 'failed';
  output: unknown;
};

SendMessageResponse

type SendMessageResponse = {
  taskId: string;
  status: TaskStatus;
};

Task

type Task<TOutput = unknown> = {
  taskId: string;
  status: TaskStatus;
  contextId?: string;
  result?: { output: TOutput; usage?: Usage };
  error?: { code: string; message: string };
  createdAt: string;
  updatedAt: string;
};

ListTasksRequest

type ListTasksRequest = {
  contextId?: string;
  status?: TaskStatus | TaskStatus[];
  limit?: number;
  offset?: number;
};

ListTasksResponse

type ListTasksResponse = {
  tasks: Task[];
  total: number;
  hasMore: boolean;
};

Exports

// Extension
export { a2a } from '@regent/a2a';

// Card utilities
export {
  buildAgentCard,
  fetchAgentCard,
  fetchAgentCardWithEntrypoints,
  parseAgentCard,
  findSkill,
  hasCapability,
  hasSkillTag,
  supportsPayments,
  hasTrustInfo,
} from '@regent/a2a';

// Runtime
export { createA2ARuntime } from '@regent/a2a';

// Client utilities
export { waitForTask } from '@regent/a2a';

// Types
export type {
  A2ARuntime,
  A2AClient,
  AgentCard,
  AgentCardWithEntrypoints,
  InvokeAgentResult,
  Task,
  TaskStatus,
  SendMessageResponse,
  ListTasksRequest,
  ListTasksResponse,
} from '@regent/a2a';