Agent

Canonical contract: packages/sdk/docs.md — the source-of-truth file for every Agent option.

What is an Agent

An Agent is a typed loop around a model, a set of tools, an optional memory store, and a session. You hand it a prompt; it decides whether to answer directly, call tools, hand off to another agent, or stream a response.

The SDK ships two flavours:

• LocalAgent — runs in your process. Backed by a local agent loop, MCP servers spawned via stdio, in-process tool registry, and a SQLite session store on disk. This is what you get from Agent.create({ apiKey, model }).
• CloudAgent — pointer to a remote agent running on Theo PaaS (pre-release). Auto-detected when the agent id starts with bc- (vs agent- for local).

Lifecycle

Agent.create(opts)  →  agent.send(prompt)  →  run.wait()  →  agent.dispose()
                              │
                              └──▶ (concurrent) run.stream()  →  AsyncIterator<SDKMessage>

1. Create. Agent.create({ apiKey, model, tools?, mcpServers?, memory?, ... }) constructs the loop, resolves the provider, opens any MCP servers, and assigns an agentId. Returns a Promise<SDKAgent>.

2. Send. agent.send(prompt, options?) enqueues a turn. Returns a Run handle.

3. Wait or stream. run.wait() blocks until the agent finishes. run.stream() yields SDKMessage events as they happen (text deltas, tool calls, partials).

4. Dispose. agent.dispose() closes MCP servers, releases file handles, and stops background tasks. Use await using for automatic disposal:

   await using agent = await Agent.create({...});
   // ... auto-disposes at block exit

Persistence

Every LocalAgent gets an agentId (e.g. agent-7a3...) and persists session state under .theokit/agents/<id>/. Resume from a different process:

const agent = await Agent.resume(id);

The full message history, tool registry, and (if enabled) memory store rehydrate transparently. See Sessions for the persistence contract.

Multi-provider fallback

const agent = await Agent.create({
  apiKey: process.env.OPENROUTER_API_KEY,
  model: { id: "openai/gpt-4o-mini" },
  providers: {
    routes: [{ provider: "openrouter" }],
    fallback: ["openai", "anthropic"],
  },
});

If openrouter returns a transient error, the SDK retries on openai, then anthropic. See Providers for credential pools (multi-key rotation per provider).

Common patterns

API reference