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.

​
Agent

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

​
What it is

Agent is the main class in the SDK. An Agent bundles three things:
  1. Identity — a name, description, type, and instance id that together become the agent’s public card.
  2. Capabilities — the functions this agent makes callable over A2A (see define_capability).
  3. Runtime — an HTTP server or an outbound WebSocket, plus the Svantic registration / heartbeat machinery and automatic telemetry.
An Agent is also optionally smart: pass instructions and llm to let it reason about natural-language tasks and call its own capabilities as tools. Without those, it’s a deterministic tool server — capabilities are invoked directly.

​
When to use it

Every Svantic agent you build starts with new Agent(...). Reach for it when you want to:
  • Expose structured capabilities an LLM or another agent can invoke.
  • Run a smart agent that plans its own work.
  • Bridge MCP servers into the platform.
  • Embed an agent into a service you already run.
If you only need to call other agents without hosting one yourself, use RemoteAgent instead.

​
Functional usage

The typical lifecycle: 
import { Agent } from '@svantic/sdk';

// 1. Create the agent with identity and (optionally) smart-agent config.
const agent = new Agent({
  name: 'invoice-agent',
  description: 'Reads and summarizes invoices.',
  mesh: {
    client_id: process.env.SVANTIC_CLIENT_ID!,
    client_secret: process.env.SVANTIC_CLIENT_SECRET!,
  },
});

// 2. Register everything the agent can do. Capabilities must be
//    declared before start() so they appear on the agent card.
agent.define_capability({
  name: 'summarize',
  description: 'Summarize the given text in one sentence.',
  parameters: {
    type: 'object',
    properties: { text: { type: 'string' } },
    required: ['text'],
  },
  handler: async ({ text }) => ({ summary: `TL;DR of ${text.length} chars` }),
});

// 3. Optionally bridge an MCP server as additional capabilities.
await agent.register_mcp('filesystem', {
  command: 'npx',
  args: ['@modelcontextprotocol/server-filesystem', '/data'],
});

// 4. Go live. In connected mode (the default) this opens an
//    outbound WebSocket to Svantic. In hosted mode it starts an
//    HTTP server and registers its public URL.
await agent.start();

// 5. Shut down cleanly. stop() deregisters from Svantic and
//    closes any MCP child processes.
process.on('SIGTERM', () => agent.stop());
Two things are happening here that you don’t see in the code:
  • Every capability invocation is automatically wrapped in a telemetry span, visible in the dashboard’s Traces tab. See Telemetry.
  • When the caller had an active trace, its W3C trace context is parsed and surfaced to your handler on CapabilitySessionContext, so outbound HTTP calls can continue the same trace. See Trace propagation.
See the Defining capabilities, Smart agents, and MCP integration guides for worked examples.

​
Constructor

new Agent(config: AgentConfig)
AgentConfig is documented in full in Types. The most common shape: 
const agent = new Agent({
  name: 'invoice-agent',
  description: 'Reads and summarizes invoices.',
  mesh: {
    client_id: process.env.SVANTIC_CLIENT_ID!,
    client_secret: process.env.SVANTIC_CLIENT_SECRET!,
  },
});

​
Methods

​
define_capability(config)

Register a capability. Must be called before start() or expose(). 
agent.define_capability({
  name: 'summarize',
  description: 'Summarize the given text in one sentence.',
  parameters: {
    type: 'object',
    properties: {
      text: { type: 'string', description: 'Text to summarize' },
    },
    required: ['text'],
  },
  handler: async ({ text }, context) => {
    return { summary: `TL;DR of ${text.length} chars` };
  },
});
The handler receives (args, context):
  • args — the parsed parameters, validated against the JSON Schema.
  • context — a CapabilitySessionContext with session_id, tenant_id, and W3C trace-propagation fields.
See CapabilityConfig for the full option surface.

​
register_mcp(server_name, config, options?)

Spawn an MCP server as a child process and register each of its tools as a capability on this agent. 
await agent.register_mcp('chrome-devtools', {
  command: 'npx',
  args: ['chrome-devtools-mcp@latest'],
});
  • server_name — logical name used as the capability prefix (hyphens become underscores, so chrome-devtools → capabilities named chrome_devtools_<tool>).
  • config — McpServerSpawnConfig: { command, args?, env? }.
  • options.tool_prefix — override the default prefix.
Returns the list of registered capability names. Must be called before start() / expose(). See the MCP integration guide.

​
start()

const port = await agent.start();
Starts the agent as a standalone service:
  • Connected mode (default) — opens an outbound WebSocket to Svantic. No HTTP server is started, no port is opened. Requires mesh credentials on AgentConfig.
  • Hosted mode — when public_url or port is set on AgentConfig, starts an Express server on port (or an ephemeral port) and mounts /send + /.well-known/agent-card.json.
Returns the port the server is listening on (0 for connected-mode agents).

​
expose(app, endpoint_path?)

agent.expose(app);              // mounts on /send
agent.expose(app, '/invoke');   // mounts on /invoke
Mount the agent’s A2A endpoints on an Express application you already own. Use this when embedding into an existing service; pair with MeshConnector to register with Svantic. Adds two routes:
  • /.well-known/agent-card.json — agent card discovery
  • /send (or the path you pass) — JSON-RPC 2.0 A2A endpoint

​
stop()

await agent.stop();
Stop a running agent: disconnects from Svantic, closes the HTTP server (if any), and calls close(). Safe to call even if the agent was never started.

​
close()

await agent.close();
Flush telemetry and tear down MCP child processes without touching the mesh connection or HTTP server. Normal teardown should use stop(); call close() directly only when you’re managing the HTTP server and mesh connection yourself (e.g. in tests or when using expose(app) + a standalone MeshConnector).

​
set_context(context)

Merge values into the agent’s live context. Context is surfaced on the agent card and used by the platform for context-aware routing.

​
Properties

PropertyTypeDescription
namestringThe agent’s display name.
descriptionstringWhat the agent does.
public_urlstringPublic HTTPS URL (hosted mode); empty string for connected mode.
agent_typestringLogical agent type used for mesh routing.
instance_idstringUnique id for this running instance.
versionstringAgent version (defaults to '1.0.0').
capabilitiesMap<string, CapabilityConfig>Registered capabilities, keyed by name.
contextRecord<string, unknown>Current live context.
instructionsstring | undefinedSystem prompt (smart agent mode).
llm_configLlmConfig | undefinedLLM configuration (smart agent mode).
is_smart_agentbooleantrue when both instructions and llm are set.
Telemetry is not owned by the Agent anymore — it flows through the global OpenTelemetry TracerProvider. Use trace.getTracer(...) from @opentelemetry/api to add custom spans. See Telemetry.

​
Helper methods

​
build_agent_card()

Returns the A2A agent card produced from the agent’s current configuration and registered capabilities. Useful for inspection and testing.

​
See also