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.
Types
Canonical listing of the configuration and value types exported from @svantic/sdk. Individual class pages link back here for option details.
AgentConfig
Passed to new Agent(...). See Agent for methods.
| Field | Type | Purpose |
|---|
name | string | Display name in the agent card. |
description | string | What the agent does. Shown to callers and LLMs. |
public_url? | string | Public HTTPS URL. Set this only for hosted-mode agents. |
port? | number | Port for agent.start() in hosted mode. Ignored in connected mode and for expose(app). |
mesh? | { svantic_url?, client_id?, client_secret?, token? } | Svantic platform config. Omit to skip registration. svantic_url defaults to https://api.svantic.com. |
instructions? | string | System prompt for smart agent mode. |
llm? | LlmConfig | LLM for smart agent mode. |
version? | string | Advertised version. Default '1.0.0'. |
agent_type? | string | Logical type for mesh routing. Defaults to name. |
instance_id? | string | Unique per-process id. Auto-generated from hostname + port/pid if omitted. |
context? | Record<string, unknown> | Live metadata surfaced on the card. |
learning? | LearningConfig | Controls platform learner behavior for this agent. |
CapabilityConfig
Passed to agent.define_capability(...).
| Field | Type | Purpose |
|---|
name | string | Unique, snake_case. |
description | string | Shown to LLMs and remote callers. Invest here. |
parameters | CapabilitySchema | JSON Schema for the handler’s arguments. |
tags? | string[] | Free-form labels shown on the agent card. |
handler | (args, context) => Promise<unknown> | Async function that runs when the capability is invoked. |
CapabilitySchema
JSON Schema subset used for capability parameters.
interface CapabilitySchema {
type: 'object';
properties: Record<string, SchemaProperty>;
required?: string[];
}
interface SchemaProperty {
type: 'string' | 'number' | 'boolean' | 'integer' | 'array' | 'object';
description?: string;
enum?: string[];
default?: unknown;
items?: SchemaProperty;
properties?: Record<string, SchemaProperty>;
required?: string[];
}
CapabilitySessionContext
Second argument to every capability handler.
| Field | Type | Description |
|---|
session_id | string | Svantic session id the invocation belongs to. |
tenant_id | string | Tenant that owns the session. |
propagation_headers? | Record<string, string> | Raw W3C headers (traceparent, baggage). Forward to downstream HTTP services. |
parent_trace_id? | string | 32-hex trace id parsed from traceparent. |
parent_span_id? | string | 16-hex span id parsed from traceparent. |
baggage? | Record<string, string> | Parsed baggage. Empty when absent. |
LlmConfig
| Field | Type | Description |
|---|
provider | 'gemini' | 'openai' | 'anthropic' | LLM provider. |
model? | string | Provider-specific model name. Sensible defaults per provider. |
api_key? | string | API key. Falls back to GOOGLE_API_KEY / OPENAI_API_KEY / ANTHROPIC_API_KEY. |
temperature? | number | Sampling temperature. |
max_tokens? | number | Response cap. |
MeshConnectorConfig
Passed to new MeshConnector(agent, config). Same fields appear on AttachConfig.mesh and (partially) on AgentConfig.mesh.
| Field | Type | Default | Purpose |
|---|
svantic_url? | string | https://api.svantic.com | Svantic platform URL. |
client_id? / client_secret? | string | — | Credentials for the OAuth2 client_credentials grant. |
token? | string | — | Pre-issued JWT (skips credential exchange). |
retries? | number | 3 | Registration retry attempts. |
retry_delay_ms? | number | 2000 | Delay between retries. |
session_count_provider? | () => number | — | Reports active-session count on heartbeat. |
deployment_mode? | 'connected' | 'hosted' | connected | Transport mode. |
dispatch_auth? | DispatchAuthConfig | — | Turns on dispatch-auth envelopes. See Dispatch auth. |
LearningConfig
Platform learner configuration, re-exported from @svantic/shared. Use it to opt this agent into (or out of) automated knowledge capture. Fields include enabled, scope, and capture filters; see the Knowledge Store concept page for semantics.
ExecutionContext
Structured execution context forwarded to the learner. Re-exported from @svantic/shared. Set via MessageBuilder.with_execution_context().
FilePayload
File attachment carried in a message DataPart.
| Field | Type | Description |
|---|
name | string | Filename shown to the agent. |
mime_type | string | IANA media type. |
size | number | Bytes. |
file_id? | string | Preferred. Id returned by the platform file-upload endpoint. The mesh resolves it to LLM-native format at call time. |
content? / data? / file_uri? / artifact_ref? | string | Deprecated. Inline-content alternatives, kept for compatibility. |
AgentStatus / AgentStatusValue
enum AgentStatus {
AVAILABLE = 'available',
BUSY = 'busy',
DRAINING = 'draining',
OFFLINE = 'offline',
UNHEALTHY = 'unhealthy',
UNKNOWN = 'unknown',
}
AgentStatusValue is the string-literal union ('available' | 'busy' | …). AGENT_STATUS_VALUES is the runtime array, handy for Zod enums.
Response types
Shapes returned by related platform APIs — re-exported so TypeScript consumers don’t have to re-declare them. See the API Reference for the REST contracts.
| Type | Endpoint |
|---|
McpRegistrationResponse | POST /config/add_mcp_default |
McpListResponse | POST /config/get_mcp_defaults |
McpRemoveResponse | POST /config/remove_mcp_default |
GeminiFileResponse | POST /files/upload |
SessionSummary | POST /sessions/list |
SessionHistory (SessionTurn) | POST /sessions/get |
ApprovalListResponse | POST /guard/get_approvals |
A2A re-exports
The SDK re-exports A2A primitive types from @a2a-js/sdk so you don’t import them twice: AgentCard, AgentSkill, Message, Task, TaskState, TextPart, DataPart, FilePart, Part, TaskStatusUpdateEvent, TaskArtifactUpdateEvent, and the A2AStreamEventData union used by streaming APIs.