Agent SDK quickstart.

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 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 install @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:

npm install zod

ESM import

import { Agent, Runner, run, stream } from '@maincode-ai/matilda-agent-sdk';

CommonJS require

const { Agent, Runner, run, stream } = require('@maincode-ai/matilda-agent-sdk');

Quick start

Minimal: run a single agent turn

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

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

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);