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.

​
RemoteAgent

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

​
What it is

RemoteAgent is the SDK’s client for any A2A-compliant agent — another Svantic agent in your tenant, a public agent on the internet, or an agent you’re running locally during development. It discovers the remote’s agent card, wraps the A2A JSON-RPC transport, and exposes three ways to interact:
  • Structured invocation — call a named capability with typed arguments (invoke_capability).
  • Natural-language prompts — send plain text to a smart agent (send).
  • Streaming — receive incremental A2A events as the remote produces them (send_stream, send_stream_message).
RemoteAgent does not require the caller to be an Agent. You can use it from any Node.js process.

​
When to use it

Reach for RemoteAgent whenever you need to call another agent:
  • From a standalone script or service that isn’t itself an agent.
  • From inside a capability handler to delegate work to a specialist agent.
  • From a smart agent’s orchestration code when the platform’s own routing isn’t enough.
If you only need to inspect an agent’s card without sending messages (e.g. to build a capability picker), use AgentDiscovery — it skips the full client setup.

​
Functional usage

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

// 1. Connect — fetches /.well-known/agent-card.json and builds the client.
const invoice_agent = await RemoteAgent.connect(
  'https://api.svantic.com/agents/invoice-agent',
);

// 2a. Structured call — you know the capability and arguments.
const invoice = await invoice_agent.invoke_capability('lookup_invoice', {
  invoice_id: 'inv_123',
});

// 2b. Natural language — the remote is a smart agent that plans its own work.
const response = await invoice_agent.send(
  'Summarize the top three overdue invoices for Acme.',
);

// 2c. Streaming — incremental output for UIs or long-running tasks.
for await (const event of invoice_agent.send_stream('Give me Q3 spend by vendor')) {
  render(event);
}

// 3. Inspect before calling (optional).
console.log(invoice_agent.name, 'has', invoice_agent.skills.length, 'capabilities');
Use MessageBuilder + send_stream_message when you need to attach files, session context, or other metadata on the way out. See Calling other agents for the common patterns.

​
Connecting

​
RemoteAgent.connect(url, token?)

const agent = await RemoteAgent.connect('https://api.svantic.com/agents/invoice-agent');
Fetches the remote agent’s /.well-known/agent-card.json, validates it, and returns a ready-to-use RemoteAgent. Pass an optional bearer token when the remote requires authentication. Throws if the card cannot be fetched or is malformed.

​
Sending messages

​
send(message, context_id?)

const response = await agent.send('Summarize Q3 revenue');
Send a natural-language message and wait for the complete response. Returns an A2A Message or Task. Use context_id to continue an existing A2A conversation.

​
send_stream(message, context_id?)

for await (const event of agent.send_stream('Summarize Q3 revenue')) {
  console.log(event);
}
Same as send, but yields streaming A2A events (Message, Task, TaskStatusUpdateEvent, TaskArtifactUpdateEvent) as the remote produces them.

​
send_stream_message(message)

for await (const event of agent.send_stream_message(rich_message)) { … }
Stream a fully-formed A2A Message — use this when you need DataParts, FileParts, or custom metadata alongside text. Construct message with MessageBuilder.

​
Invoking capabilities

​
invoke_capability(capability, args, session_context?, context_id?, dispatch_auth?)

const result = await agent.invoke_capability('extract_invoice', {
  url: 'https://example.com/invoice.pdf',
});
Invoke a single named capability with structured arguments. Returns the value the remote handler returned — the SDK unwraps the DataPart envelope for you. Parameters:
  • capability — capability name as it appears on the agent card.
  • args — arguments matching the capability’s JSON Schema.
  • session_context (optional) — { session_id, tenant_id } forwarded to the remote handler.
  • context_id (optional) — A2A conversation id.
  • dispatch_auth (optional) — dispatch-auth envelope when the remote requires it.

​
Inspecting the remote

PropertyTypeDescription
agent_cardAgentCardThe full agent card fetched at connect time.
skillsExtendedAgentSkill[]Registered capabilities with parameter schemas.
namestringRemote agent name.
urlstringBase URL passed to connect().
clientClientUnderlying @a2a-js/sdk client — for advanced / escape-hatch use.

​
See also