A2A

Examples of inter-agent communication using the A2A protocol.

Fetching Agent Cards

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

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

// Fetch another agent's card
const card = await agent.a2a.fetchCard('https://other-agent.example.com');
console.log('Agent:', card.name);
console.log('Skills:', card.skills?.map(s => s.id));

Direct Invocation

// Invoke another agent's entrypoint
const result = await agent.a2a.client.invoke(
  card,
  'process',
  { text: 'Hello from client agent' }
);

console.log('Status:', result.status);
console.log('Output:', result.output);

Streaming

await agent.a2a.client.stream(
  card,
  'generate',
  { prompt: 'Tell me a story' },
  async (event) => {
    if (event.type === 'delta') {
      process.stdout.write(event.data.delta);
    }
    if (event.type === 'run-end') {
      console.log('\nDone!');
    }
  }
);

Task-Based Communication

// Send a message (creates a task)
const response = await agent.a2a.client.sendMessage(
  card,
  'chat',
  { text: 'What is AI?' },
  undefined,
  { contextId: 'conversation-123' }
);

console.log('Task ID:', response.taskId);

// Poll for completion
const task = await agent.a2a.client.getTask(card, response.taskId);
console.log('Status:', task.status);

if (task.status === 'completed') {
  console.log('Result:', task.result?.output);
}

Subscribe to Task Updates

const response = await agent.a2a.client.sendMessage(
  card,
  'process',
  { data: 'large dataset' }
);

// Subscribe to updates via SSE
await agent.a2a.client.subscribeTask(
  card,
  response.taskId,
  async (event) => {
    console.log(`Task ${event.data.taskId}: ${event.type}`);

    if (event.data.status === 'completed') {
      console.log('Result:', event.data.result);
    }
    if (event.data.status === 'failed') {
      console.error('Error:', event.data.error);
    }
  }
);

Wait for Task

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

const response = await agent.a2a.client.sendMessage(
  card,
  'analyze',
  { query: 'market trends' }
);

// Wait up to 30 seconds
const completed = await waitForTask(
  agent.a2a.client,
  card,
  response.taskId,
  30000
);

console.log('Output:', completed.result?.output);

Multi-Turn Conversation

const contextId = 'conversation-' + Date.now();

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

// Follow-up question
const r2 = await agent.a2a.client.sendMessage(
  card,
  'chat',
  { text: 'Can you give me an example?' },
  undefined,
  { contextId }
);
await waitForTask(agent.a2a.client, card, r2.taskId);

// Get conversation history
const history = await agent.a2a.client.listTasks(card, { contextId });
console.log(`Conversation had ${history.total} messages`);

Task Management

// List all tasks
const allTasks = await agent.a2a.client.listTasks(card);

// Filter by status
const runningTasks = await agent.a2a.client.listTasks(card, {
  status: 'running',
  limit: 10,
});

// Cancel a task
const cancelled = await agent.a2a.client.cancelTask(card, taskId);
console.log('Cancelled:', cancelled.status);

Check Agent Capabilities

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

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

// Check capabilities
if (hasCapability(card, 'streaming')) {
  console.log('Supports streaming');
}

// Check payments
if (supportsPayments(card)) {
  console.log('Requires payment');
}

// Check trust info
if (hasTrustInfo(card)) {
  console.log('Has on-chain identity');
}

// Find specific skill
const skill = findSkill(card, 'analyze');
if (skill) {
  console.log('Found skill:', skill.name);
}

Complete Example

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

async function main() {
  // Create our agent
  const agent = await createAgent({
    name: 'orchestrator',
    version: '1.0.0',
  })
    .use(http())
    .use(a2a())
    .build();

  // Discover target agent
  const targetUrl = 'https://helper-agent.example.com';
  const card = await agent.a2a.fetchCard(targetUrl);

  console.log(`Connected to: ${card.name}`);
  console.log(`Skills: ${card.skills?.length || 0}`);

  // Choose interaction pattern based on capabilities
  if (hasCapability(card, 'streaming')) {
    // Use streaming for real-time output
    await agent.a2a.client.stream(
      card,
      'generate',
      { prompt: 'Hello' },
      async (event) => {
        if (event.type === 'delta') {
          process.stdout.write(event.data.delta);
        }
      }
    );
  } else {
    // Use task-based for async processing
    const response = await agent.a2a.client.sendMessage(
      card,
      'process',
      { input: 'Hello' }
    );

    const task = await waitForTask(agent.a2a.client, card, response.taskId);
    console.log('Result:', task.result?.output);
  }
}

main().catch(console.error);