Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.svantic.com/llms.txt

Use this file to discover all available pages before exploring further.

​
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.

​
See also