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

# Remote agent

# RemoteAgent

```typescript theme={null}
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`](./agent-discovery) — it skips the full client setup.

## Functional usage

```typescript theme={null}
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`](./message-builder) + `send_stream_message` when you need to attach files, session context, or other metadata on the way out.

See [Calling other agents](../guides/calling-other-agents) for the common patterns.

## Connecting

### `RemoteAgent.connect(url, token?)`

```typescript theme={null}
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?)`

```typescript theme={null}
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?)`

```typescript theme={null}
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)`

```typescript theme={null}
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`](./message-builder).

## Invoking capabilities

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

```typescript theme={null}
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. |

## See also

* [Calling other agents](../guides/calling-other-agents)
* [`MessageBuilder`](./message-builder) — for constructing rich messages.
* [`AgentDiscovery`](./agent-discovery) — inspect agent cards without connecting.