@a2a-relay/client

Discover and communicate with A2A agents. Fetch Agent Cards, send messages, get responses.

Part of Agent Relay — the open infrastructure for the agent economy.

Install

npm install @a2a-relay/client

Quick Start

import { RelayClient } from '@a2a-relay/client';

const client = new RelayClient();

// Discover an agent by URL
const agent = await client.discover('https://some-agent.example.com');

// See what it can do
console.log(agent.card.name);        // "Car Expert"
console.log(agent.card.skills);      // [{ id: 'diagnose', ... }]

// Send a message
const response = await agent.send('My engine is making a clicking noise');
console.log(response.text);          // "Based on your description..."

Features

• 🔍 Agent Discovery — fetch Agent Cards from any A2A-compliant agent
• 💬 Send Messages — text and structured data
• 🔐 Auth Support — pass bearer tokens for protected agents
• 🎯 Skill Inspection — check agent capabilities before sending
• 📋 A2A Compliant — speaks standard Agent-to-Agent protocol

Discovery

const client = new RelayClient();

// Discover via well-known URL
const agent = await client.discover('https://some-agent.com');

// Discover with authentication
const agent = await client.discover('https://private-agent.com', 'my-token');

// Or set a default token for all discoveries
const client = new RelayClient({ token: 'default-token' });
const agent = await client.discover('https://private-agent.com');

Sending Messages

// Simple text message
const response = await agent.send('What time is it?');
console.log(response.text);

// With conversation context (multi-turn)
const r1 = await agent.send('Hi, I need help with my car');
const r2 = await agent.send('The engine is overheating', {
  contextId: r1.contextId,
});

// With auth token (per-request)
const response = await agent.send('Hello', { token: 'specific-token' });

Structured Data

// Send structured data
const response = await agent.sendData({
  type: 'diagnostic_request',
  symptoms: ['clicking noise', 'rough idle'],
  vehicle: { make: 'Toyota', year: 2019 },
});

// Read structured response
console.log(response.text);          // Human-readable text
console.log(response.data);          // { diagnosis: ..., confidence: 0.85 }
console.log(response.parts);         // Raw A2A message parts

Skill Inspection

const agent = await client.discover('https://some-agent.com');

// Check for a specific skill
if (agent.hasSkill('diagnose')) {
  const response = await agent.send('Engine clicking noise');
}

// Find skills by tag
const diagnosticSkills = agent.skillsByTag('diagnostics');
console.log(diagnosticSkills);

Connect Without Discovery

If you already have an Agent Card (e.g., from a registry), skip the HTTP fetch:

const card = {
  name: 'Known Agent',
  url: 'https://agent.example.com/a2a/jsonrpc',
  skills: [{ id: 'greet', name: 'Greeting', description: 'Say hello' }],
};

const agent = client.connect(card);
const response = await agent.send('Hello!');

API

new RelayClient(options?)

| Option | Type | Description | |--------|------|-------------| | token | string | Default bearer token for all requests |

client.discover(url, token?)

Fetch an Agent Card from the well-known URL and return a connected RemoteAgent.

client.connect(card, token?)

Create a RemoteAgent from a known Agent Card (no HTTP fetch).

agent.send(text, options?)

Send a text message. Returns AgentResponse.

agent.sendData(data, options?)

Send structured data. Returns AgentResponse.

agent.hasSkill(id)

Check if the agent has a specific skill.

agent.skillsByTag(tag)

Get all skills matching a tag.

AgentResponse

| Field | Type | Description | |-------|------|-------------| | text | string | Combined text from all text parts | | data | object \| undefined | Structured data (if any) | | parts | MessagePart[] | Raw A2A message parts | | messageId | string | Response message ID | | contextId | string \| undefined | Context ID for multi-turn |

Related

• @a2a-relay/server — build A2A agents in minutes
• Agent Relay — the full project
• A2A Protocol — the underlying standard

License

MIT