# Agent SDK quickstart

> Install the agent SDK and run your first agent.

Source: https://maincode.com/docs/agent-sdk-overview
Section: Agent SDK · Matilda documentation

---

A TypeScript SDK for building agentic applications on Matilda. Provides agent abstractions, client-side tool execution, multi-turn sessions, automatic retry with exponential backoff, DSML tool-call interception, and durable stream resume — all on top of the Matilda-native chat contract. This guide covers SDK version 0.1.0.

The agent SDK wraps the [client SDK](https://maincode.com/docs/client-sdk-overview) and adds:

- **Agent** — a named, configurable persona with dynamic instructions and purpose-based routing
- **Runner** — runs agent turns with streaming, retry, and a client-side tool execution loop
- **Session** — multi-turn conversations with auto-managed `conversationId` and turn accumulation
- **Client tools** — register handlers the agent can invoke mid-turn; the SDK handles the roundtrip loop
- **DSML interception** — tool calls emitted as text tokens (`<｜DSML｜tool_call>`) are automatically captured and surfaced as native tool events
- **Durable stream resume** — reconnect to a detached stream from the last cursor

Agent runs send `persist: false` by default — conversations do not appear in the Matilda web app's chat history.

## What's included

- **Agent** — named persona with static or dynamic instructions, purpose-based routing
- **Runner** — `run()`, `stream()`, `streamText()`, `runText()`, `runObject()`, `streamObject()` with retry and tool execution
- **Session** — multi-turn conversations with automatic `conversationId` reuse
- **Client tools** — `ToolHandlers` with automatic roundtrip loop and advertised-tool guard
- **Files** — upload (single and parallel), retrieve metadata
- **Conversations** — list, retrieve, rename, and set message feedback
- **Auth** — managed PKCE browser login, RFC 8628 device flow, token restore, persistent token storage

## What's NOT included

- **Server-side tool execution** — server-side tools (web search, code execution, etc.) are handled by Matilda core. The agent SDK's tool loop is for client-side tools only.
- **Model/provider selection** — Matilda core owns routing, safety, and policy.

## Installation

**npm**

```bash
npm install @maincode-ai/matilda-agent-sdk
```

**pnpm**

```bash
pnpm add @maincode-ai/matilda-agent-sdk
```

**yarn**

```bash
yarn add @maincode-ai/matilda-agent-sdk
```

Requires Node.js ≥ 20.

`zod` (v3.25+) is a required peer dependency — install it alongside the SDK. It is used by the [structured-output helpers](https://maincode.com/docs/agent-sdk-structured-output):

```bash
npm install zod
```

### ESM import

```ts title="index.ts"
import { Agent, Runner, run, stream } from '@maincode-ai/matilda-agent-sdk';
```

### CommonJS require

```js title="index.js"
const { Agent, Runner, run, stream } = require('@maincode-ai/matilda-agent-sdk');
```

## Quick start

### Minimal: run a single agent turn

```ts title="run.ts"
import { run } from '@maincode-ai/matilda-agent-sdk';

const result = await run(
  { name: 'greeter', instructions: 'Be friendly and concise.' },
  'Say hello in three languages.',
);

console.log(result.finalOutput);
console.log(result.usage);
```

### Minimal: streaming

```ts title="stream.ts"
import { stream } from '@maincode-ai/matilda-agent-sdk';

for await (const event of stream(
  { name: 'storyteller', instructions: 'Write a short sci-fi haiku.' },
  'Write about a Dyson sphere.',
)) {
  if (event.type === 'message.delta') {
    process.stdout.write(event.delta);
  }
  if (event.type === 'done') {
    console.log('\n[done]');
  }
}
```

### Authenticated: device flow + run

```ts title="device-flow.ts"
import { Runner } from '@maincode-ai/matilda-agent-sdk';
import { MatildaCore } from '@maincode-ai/matilda-agent-sdk';

const runner = new Runner({
  core: new MatildaCore({ baseUrl: 'https://matilda.maincode.com/api' }),
});

// Authenticate via RFC 8628 device flow — prints a code to stderr
if (!(await runner.auth.getTokens())) {
  await runner.auth.loginWithDeviceFlow({ clientId: 'matilda-code' });
}

// Token is now managed automatically — refresh on 401 comes for free
const result = await runner.run(
  { name: 'helper', instructions: 'Be concise.' },
  'What is the capital of Australia?',
);
console.log(result.finalOutput);
```