Quickstart

Prerequisites

You've installed @theokit/sdk and have a provider API key. The cheapest path is OpenRouter — sign up at openrouter.ai, copy a key, and:

export OPENROUTER_API_KEY="sk-or-v1-..."

The SDK auto-detects which provider env var you set. No extra config.

Write your first agent

Save this as hello.ts:

import { Agent } from "@theokit/sdk";

const agent = await Agent.create({
  apiKey: process.env.OPENROUTER_API_KEY,
  model: { id: "openai/gpt-4o-mini" },
});

const run = await agent.send("What is 2+2?");
const result = await run.wait();
console.log(result.result);

await agent.dispose();

Run it

npx tsx hello.ts

You should see something like:

2 + 2 = 4

That's it. 7 lines, no scaffolding, no config file.

What just happened

1. Agent.create() spins up a local agent loop bound to your API key + a model id.
2. agent.send(prompt) returns a Run handle — the agent is processing in the background.
3. run.wait() blocks until the agent is done. The result has .status, .result, .messages, etc.
4. agent.dispose() releases any file handles, MCP processes, or background tasks. Always dispose.

Next steps