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

Property	Type	Description
`agent_card`	`AgentCard`	The full agent card fetched at connect time.
`skills`	`ExtendedAgentSkill[]`	Registered capabilities with parameter schemas.
`name`	`string`	Remote agent name.
`url`	`string`	Base URL passed to `connect()`.
`client`	`Client`	Underlying `@a2a-js/sdk` client — for advanced / escape-hatch use.

Overview

Guides

Reference

Remote agent

RemoteAgent

What it is

When to use it

Functional usage

Connecting

`RemoteAgent.connect(url, token?)`

Sending messages

`send(message, context_id?)`

`send_stream(message, context_id?)`

`send_stream_message(message)`

Invoking capabilities

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

Inspecting the remote

See also

​RemoteAgent

​What it is

​When to use it

​Functional usage

​Connecting

​RemoteAgent.connect(url, token?)

​Sending messages

​send(message, context_id?)

​send_stream(message, context_id?)

​send_stream_message(message)

​Invoking capabilities

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

​Inspecting the remote

​See also

RemoteAgent

What it is

When to use it

Functional usage

Connecting

`RemoteAgent.connect(url, token?)`

Sending messages

`send(message, context_id?)`

`send_stream(message, context_id?)`

`send_stream_message(message)`

Invoking capabilities

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

Inspecting the remote

See also