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

# Getting Started

> Clone an agent, connect to the mesh, talk to it — in under 10 minutes.

# Getting Started

By the end of this guide, you'll have:

* A running agent on your machine
* Connected to the Svantic mesh
* Responding to natural language prompts
* Fully traced in the dashboard

## Prerequisites

<Columns cols={2}>
  <Card title="Node.js 20+" icon="server" href="https://nodejs.org/">
    Required runtime for Svantic agents. Download the latest LTS version.
  </Card>

  <Card title="Svantic Account" icon="user-plus" href="https://app.svantic.com/signup">
    Free to create. You'll need API keys from the dashboard.
  </Card>
</Columns>

## Quick Start

<Steps>
  <Step title="Clone the starter agent">
    The starter agent has simple capabilities (calculator, clock, unit converter) — things you wouldn't normally need AI for. That's intentional.

    <Info title="Philosophy">
      AI should only do what requires AI. A calculator doesn't need an LLM — it needs arithmetic. The LLM's job is to *understand* "what's 42 times 17?" and *route* it to the right tool. The tool does the actual work, deterministically and cheaply.

      This is how Svantic works: the mesh uses AI for understanding and routing, your agents use code for execution. You get natural language interfaces without burning tokens on tasks that don't need them.
    </Info>

    ```bash theme={null}
    git clone https://github.com/svantic/starter-agent.git
    cd starter-agent
    npm install
    ```
  </Step>

  <Step title="Get your API keys">
    Sign up at [app.svantic.com/signup](https://app.svantic.com/signup), go to **Settings → API Keys → Create Key**, and copy your **Client ID** and **Client Secret**.
  </Step>

  <Step title="Add credentials">
    ```bash theme={null}
    cp .env.example .env
    # Edit .env and add your keys:
    # SAVANT_CLIENT_ID=your-client-id
    # SAVANT_CLIENT_SECRET=your-client-secret
    ```
  </Step>

  <Step title="Start the agent">
    ```bash theme={null}
    npm run dev
    ```

    You should see:

    ```
    [agent] Listening on http://localhost:4000
    [agent] Connected to Svantic mesh (authenticated + registered)
    Starter agent is running. Try asking: "What is 42 times 17?"
    ```

    Your agent is live — registered on the mesh, publishing capabilities, exporting telemetry.
  </Step>

  <Step title="Talk to your agent">
    Open a second terminal:

    ```bash theme={null}
    npm install -g @svantic/terminal
    svantic --client-id your-client-id --client-secret your-client-secret
    ```

    The starter agent has three capabilities. Test each one:

    <Tabs>
      <Tab title="Calculator">
        ```
        > What's 42 times 17?
        42 times 17 is 714.
        ```
      </Tab>

      <Tab title="Timezone Clock">
        ```
        > What time is it in Tokyo?
        It's currently 3:45 PM in Tokyo (JST).
        ```
      </Tab>

      <Tab title="Unit Converter">
        ```
        > Convert 100 kg to pounds
        100 kilograms is 220.46 pounds.
        ```
      </Tab>
    </Tabs>

    If you see responses like these, your agent is working.
  </Step>
</Steps>

### See it in the dashboard

Go to [app.svantic.com](https://app.svantic.com) and click into your session:

* **Agent registry** — Your agent listed with URL, version, heartbeat status
* **Session timeline** — The conversation you just had
* **Tool calls** — `calculate` called with `{ operator: "multiply", a: 42, b: 17 }`
* **Telemetry spans** — End-to-end timing for every step

Every action traced, no extra code required.

## Understand the Code

Everything is in `src/agent.ts` — **5 lines to create an agent, \~10 lines per capability.**

### The Agent

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

const agent = new Agent({
  name: 'starter-agent',
  description: 'A utility agent that does math, tells time, and converts units.',
  port: 4000,
  mesh: {
    client_id: process.env.SAVANT_CLIENT_ID,
    client_secret: process.env.SAVANT_CLIENT_SECRET,
  },
});
```

**`name`** — Identity in the mesh. Other agents discover you by this.

**`description`** — The mesh LLM reads this to decide when to route tasks to your agent.

**`port`** — The mesh calls your agent at this port to invoke capabilities.

**`mesh`** — Credentials for mesh connection. Without this, the agent runs standalone.

### Capabilities

Each capability is a function the mesh can call:

```typescript theme={null}
agent.define_capability({
  name: 'calculate',
  description: 'Perform basic arithmetic.',
  parameters: {
    type: 'object',
    properties: {
      operator: { type: 'string', enum: ['add', 'subtract', 'multiply', 'divide'] },
      a: { type: 'number' },
      b: { type: 'number' },
    },
    required: ['operator', 'a', 'b'],
  },
  handler: async (args) => {
    const { operator, a, b } = args;
    if (operator === 'add') return { result: a + b };
    if (operator === 'multiply') return { result: a * b };
    // ...
  },
});
```

**`name`** — The mesh invokes your capability by this name.

**`parameters`** — JSON Schema. The LLM constructs arguments from natural language.

**`handler`** — Your business logic. Receives parsed arguments, returns a result.

### Start

```typescript theme={null}
await agent.start();
```

One line to start the agent and join the mesh, ready to serve.

```mermaid theme={null}
flowchart LR
    A[a2ui-terminal authenticates] --> B[creates session] --> C[registers] --> D[self-joins]
```

## What's Next

<Columns cols={2}>
  <Card title="Build with Forge" icon="sparkles" href="build/forge">
    Generate agents from OpenAPI specs or prompts.
  </Card>

  <Card title="Build by Hand" icon="hammer" href="build/your-first-agent">
    Deeper guide with multiple capabilities.
  </Card>

  <Card title="Add to Existing Service" icon="plug" href="build/existing-services">
    Use `attach()` with Express apps.
  </Card>

  <Card title="Connecting Agents" icon="network" href="build/connecting-agents">
    Discover and call other agents.
  </Card>
</Columns>