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

# Index

# Svantic SDK

`@svantic/sdk` is the TypeScript toolkit for building AI agents on Svantic.

You describe what your agent can do in plain code, and Svantic handles the rest — discovery, orchestration, streaming, authentication, and observability. A handler you write today runs the same way whether it's called by a user in the chat UI, by another agent as a tool, or by a scheduled trigger at 3 a.m.

## Install

```bash theme={null}
npm install @svantic/sdk
```

Requires Node.js 20 or later.

## Hello, agent

```typescript theme={null}
import { Agent } from '@svantic/sdk';

const agent = new Agent({
  name: 'hello-agent',
  description: 'Greets people by name.',
  mesh: {
    client_id: process.env.SVANTIC_CLIENT_ID!,
    client_secret: process.env.SVANTIC_CLIENT_SECRET!,
  },
});

agent.define_capability({
  name: 'greet',
  description: 'Return a friendly greeting for the given name.',
  parameters: {
    type: 'object',
    properties: {
      name: { type: 'string', description: 'Name to greet' },
    },
    required: ['name'],
  },
  handler: async ({ name }) => ({ message: `Hello, ${name}!` }),
});

await agent.start();
```

Run it with your credentials from the Svantic dashboard:

```bash theme={null}
SVANTIC_CLIENT_ID=... SVANTIC_CLIENT_SECRET=... npx tsx hello.ts
```

Your agent is now live, discoverable, and callable by other agents on Svantic. No ingress, no public URL, no port forwarding — it dials out to `api.svantic.com` and keeps a persistent connection open.

## What the SDK gives you

| You want to...                                   | Start here                                              |
| ------------------------------------------------ | ------------------------------------------------------- |
| Expose functions an AI can invoke                | [Defining capabilities](./guides/defining-capabilities) |
| Let an LLM plan which capabilities to call       | [Smart agents](./guides/smart-agents)                   |
| Call another agent's capabilities                | [Calling other agents](./guides/calling-other-agents)   |
| Embed agent endpoints in an existing Express app | [Attach to Express](./guides/attach-to-express)         |
| Run on webhooks, cron, or emitted events         | [Triggers](./guides/triggers)                           |
| Bridge an MCP server as capabilities             | [MCP integration](./guides/mcp-integration)             |
| Trace what your agent did, and why               | [Telemetry & tracing](./guides/telemetry)               |
| Reject forged dispatches to a hosted agent       | [Securing dispatches](./guides/securing-dispatches)     |
| Keep secrets out of the agent and LLM            | [Sensitive forms](./guides/sensitive-forms)             |

## Two ways to run

Every agent built with the SDK is either:

* **Connected** — the default. Your agent dials Svantic over an outbound WebSocket. No public URL, no inbound firewall rules. Ideal for laptops, CI, ephemeral workers, and anything behind NAT.
* **Hosted** — your agent exposes a public HTTPS URL, and Svantic POSTs to it. Use this when you want Svantic traffic to flow through your own ingress for auditing or WAF reasons.

See [Connecting to Svantic](./guides/connecting) for when to choose which.

## How to read these docs

* **[Guides](./guides/index)** are task-oriented. Start here if you're building something. Each guide is a complete walkthrough.
* **[Reference](./reference/index)** is the exhaustive API listing — every class, method, option, and type.

If you're new, go to the [Quickstart](./guides/quickstart).

## Getting credentials

Every SDK call to Svantic uses a `client_id` / `client_secret` pair issued to your tenant. Create them in the Svantic dashboard under **Settings → API Credentials**, then set them as environment variables:

```bash theme={null}
export SVANTIC_CLIENT_ID=...
export SVANTIC_CLIENT_SECRET=...
```

The SDK exchanges these for a short-lived token automatically — you never mint or refresh JWTs by hand.

## Support

* Source and issues: [github.com/svantic/svantic](https://github.com/svantic/svantic)
* Questions: [support@svantic.com](mailto:support@svantic.com)
* Status: [status.svantic.com](https://status.svantic.com)