Calling other agents

This guide covers how to call another A2A agent — another Svantic agent, a public third-party agent, or a local agent you’re developing against. The main tool is RemoteAgent. It handles discovery, authentication, and the A2A protocol so you can focus on the call.

One-shot structured call

Use invoke_capability when you know exactly which capability you want and the shape of its arguments:

import { RemoteAgent } from '@svantic/sdk';

const invoice = await RemoteAgent.connect(
  'https://api.svantic.com/agents/invoice-agent',
);

const result = await invoice.invoke_capability('lookup_invoice', {
  invoice_id: 'inv_123',
});

console.log(result);

The SDK unwraps the A2A DataPart envelope for you — result is whatever the remote handler returned.

Natural-language prompt

Use send when you want the remote agent to plan its own work (only useful against smart agents):

const billing = await RemoteAgent.connect('https://api.svantic.com/agents/billing-assistant');
const response = await billing.send('Refund invoice inv_123 for $42.');

response is an A2A Message or Task. Inspect .parts to extract text or data parts.

Streaming responses

send_stream yields A2A events as they arrive — use it for anything that emits intermediate progress (plans, tool calls, partial outputs):

for await (const event of billing.send_stream('Summarize this month\'s invoices')) {
  if (event.kind === 'message' && event.parts?.[0]?.kind === 'text') {
    process.stdout.write(event.parts[0].text ?? '');
  }
}

Event types: Message, Task, TaskStatusUpdateEvent, TaskArtifactUpdateEvent.

Rich messages (files, context, metadata)

Use MessageBuilder when plain text isn’t enough — attachments, session context, form replies, direct routing:

import { MessageBuilder, RemoteAgent } from '@svantic/sdk';

const docs = await RemoteAgent.connect('https://api.svantic.com/agents/docs-agent');

const msg = new MessageBuilder('Summarize this contract')
  .with_context_id(session_id)
  .with_file({
    name: 'msa.pdf',
    mime_type: 'application/pdf',
    size: 82_400,
    file_id: uploaded_file_id,
  })
  .build();

for await (const event of docs.send_stream_message(msg)) {
  console.log(event);
}

Upload files to Svantic first (POST /files/upload) and pass the returned file_id — the platform resolves it to LLM-native format at call time.

Continuing a conversation

Pass a context_id (usually the Svantic session_id) to keep turns on the same conversation thread:

await billing.send('What was my last charge?', session_id);
await billing.send('Refund it.', session_id); // same conversation

Inspecting before calling

Use AgentDiscovery to fetch just the agent card:

import { AgentDiscovery } from '@svantic/sdk';

const discovery = new AgentDiscovery();
const card = await discovery.discover('https://api.svantic.com/agents/invoice-agent');

for (const skill of card.skills ?? []) {
  console.log(skill.name, '—', skill.description);
}

RemoteAgent discovers internally, so you don’t need AgentDiscovery to call — use it only when inspection is the goal (e.g. building a capability picker).

Authenticating

Most calls to Svantic-hosted agents go through your own agent’s session (the caller’s JWT is forwarded automatically when you’re inside a capability handler or smart-agent turn). For standalone scripts calling a remote that requires auth, pass a bearer token:

await RemoteAgent.connect(url, bearer_token);

Error handling

invoke_capability, send, and the stream methods reject or throw on transport, auth, or remote-side errors. Catch and inspect the message — the SDK preserves the A2A error payload in the thrown Error.

Overview

Guides

Reference

Calling other agents

Calling other agents

One-shot structured call

Natural-language prompt

Streaming responses

Rich messages (files, context, metadata)

Continuing a conversation

Inspecting before calling

Authenticating

Error handling

See also

​Calling other agents

​One-shot structured call

​Natural-language prompt

​Streaming responses

​Rich messages (files, context, metadata)

​Continuing a conversation

​Inspecting before calling

​Authenticating

​Error handling

​See also

Calling other agents

One-shot structured call

Natural-language prompt

Streaming responses

Rich messages (files, context, metadata)

Continuing a conversation

Inspecting before calling

Authenticating

Error handling

See also