@camelai/run

The TypeScript SDK for camelRun: durable agents you upsert by key and run, with tools that are ordinary functions in your code. The runtime runs the model loop, keeps each agent's history and files, and runs model-written code in a sandbox that can only call your tools.

npm install @camelai/run

Node 22 or later, Bun, Deno or Cloudflare Workers. Create an API key at https://run.camelai.com/console/tokens and export it as CAMELAI_API_KEY.

Coding agents: this version's docs are in the package, at node_modules/@camelai/run/docs/SKILL.md and docs/sdk.md. To set camelRun up in a project, read https://run.camelai.com/SKILL.md.

import { Agents, schema, tool } from "@camelai/run";

const agents = new Agents();

const weather = tool({
  description: "Today's weather in a city",
  input: schema.Object({ city: schema.String() }),
  execute: ({ city }) => ({ city, forecast: "sunny", highC: 24 }), // runs here, in your process
});

const agent = await agents.upsert("quickstart", {
  instructions: "You are a concise assistant.",
  tools: { weather },
});

const run = await agent.run("Should I bring an umbrella in Lisbon today?");
console.log(run.text);

await agents.close();

• Keyed agents. upsert(key, config) makes the agent for your key, or brings the existing one to config; its history and files last until you delete it.
• Runs. run() resolves with { status, text, inputs, error, toolErrors, toolCalls, … } and throws RunError on failure (unless throwOnError: false). No timeout: pass an AbortSignal to stop waiting. stream() yields text, tool calls and results as they happen, then the run.
• People in the loop. A tool with needsApproval: true waits for approval; run.inputs[0].answer(true, { from }) resumes the run.
• Tools. Each call's context.idempotencyKey is stable across retries; timeoutMs and context.progress() handle long calls. One process at a time serves an agent's tools; serverless and multi-user backends serve them over HTTP with serveTools (@camelai/run/server).
• Browsers. A chat in your app: one route with createAgentHandler (@camelai/run/server) and <AgentChat> or the hooks from @camelai/run-react (or /chat without React, /ai-sdk with the AI SDK's useChat); see the Frontend guide (docs/frontend.md), or start with npm create @camelai/run-app. watchAgent (@camelai/run/watch) shows an agent live with a browser token your server mints.

Documentation: Quickstart, Concepts, SDK reference, and all of it as Markdown at https://run.camelai.com/llms.txt.

AgentRuntime and AgentClient, the lower-level interface the SDK is built on, remain available. See the SDK reference's "Changes in 0.9" when upgrading.