<!-- https://run.camelai.com/docs/quickstart.md -->

# Quickstart

In five minutes you will have an agent that runs in the hosted runtime, calls a
tool in your own process, and answers you. The runtime keeps the model loop, the
agent's history and its files; your tools stay in your code, with your
credentials.

**With a coding agent.** Paste this into Claude Code, Codex, Cursor or any coding
agent. It asks you what the agent should do, installs the SDK, finds your API
key without you pasting it into chat, and runs your first agent:

```text
Read https://run.camelai.com/SKILL.md and set up camelRun in this project. Ask me what the agent should do.
```

**Try it with no API key.** Connect your coding agent to the hosted MCP server.
Signing in with GitHub or Google creates your account:

```sh
claude mcp add --transport http camelrun https://run.camelai.com/mcp   # then /mcp in Claude Code
codex mcp add camelrun --url https://run.camelai.com/mcp && codex mcp login camelrun
```

Then ask it to "use camelrun to build me my first agent". See the
[CLI and MCP server](https://run.camelai.com/docs/reference/cli.md).

**Credit.** GitHub accounts older than 30 days start with free credit. Everyone
else (Google sign-ins, newer GitHub accounts) unlocks the same credit by verifying
a card on the console's **Billing** page. The card is not charged.

To build it into your app yourself, read on.

## 1. Get an API key

Sign in to the console at <https://run.camelai.com/console> with GitHub or Google.
Under **API keys** (<https://run.camelai.com/console/tokens>), create a key,
and export it:

```sh
export CAMELAI_API_KEY=art_...
```

The key can create and control every agent in your account. Keep it on your
server and never ship it to a browser.

## 2. Install

TypeScript (Node 22 or later, or Bun):

```sh
npm install @camelai/run
```

Python (3.11 or later):

```sh
pip install camelai-run
```

## 3. Run an agent

TypeScript, `quickstart.mts` (`.mts` makes it an ES module, which top-level
`await` needs; in a project with `"type": "module"`, `.ts` works too):

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

const agents = new Agents(); // reads CAMELAI_API_KEY

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

// The same key is the same agent, with its history, every time you run this.
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();
```

```sh
npx tsx quickstart.mts
```

Python, `quickstart.py`. The Python SDK is async; synchronous code (a script, a
Django view, a Celery task) uses `camelai_run.sync`, which has the same names
without `await` (see [the synchronous client](https://run.camelai.com/docs/reference/sdk.md#the-synchronous-client-python)):

```python
import asyncio
from camelai_run import Agents, tool

@tool
def weather(city: str) -> dict:
    """Today's weather in a city"""
    return {"city": city, "forecast": "sunny", "highC": 24}

async def main():
    async with Agents() as agents:  # reads CAMELAI_API_KEY
        agent = await agents.upsert("quickstart", instructions="You are a concise assistant.", tools=[weather])
        run = await agent.run("Should I bring an umbrella in Lisbon today?")
        print(run.text)

asyncio.run(main())
```

```sh
python quickstart.py
```

curl (the agent has no tools of yours here: tools that run in your process need an
SDK, or a server of your own, see [Tools](https://run.camelai.com/docs/guides/tools.md)):

```sh
BASE=https://run.camelai.com; AUTH="Authorization: Bearer $CAMELAI_API_KEY"
# The Idempotency-Key is the agent's key: the same key is the same agent.
AGENT=$(curl -s $BASE/v1/agents -H "$AUTH" -H "Content-Type: application/json" -H "Idempotency-Key: quickstart" \
  -d '{"systemPrompt": "You are a concise assistant."}' | jq -r .id)
REQ=$(curl -s $BASE/v1/agents/$AGENT/prompt -H "$AUTH" -H "Content-Type: application/json" \
  -d '{"text": "Write a haiku about durable agents."}' | jq -r .id)
# ?wait=25 answers as soon as the run ends (or after 25 s, still running: ask again).
until RUN=$(curl -s "$BASE/v1/agents/$AGENT/requests/$REQ?wait=25" -H "$AUTH") && jq -e '.state == "completed"' <<< "$RUN" > /dev/null; do :; done
jq -r 'if .status == "failed" then "failed: \(.error)" else .outcome.result.reply end' <<< "$RUN"
```

The agent names no model, so it uses your account's default: the first of the
platform's default models your account can use. To choose one (optional), list
the models you can use, and pass one as `model`:

```sh
npx -y @camelai/camelrun models --available
# or, without Node:
curl -s "https://run.camelai.com/v1/models?available=true" -H "Authorization: Bearer $CAMELAI_API_KEY" | jq -r '.[].id'
```

```ts
const agent = await agents.upsert("quickstart", { model: "<a model id from that list>", instructions: "…" });
```

```python
agent = await agents.upsert("quickstart", model="<a model id from that list>", instructions="…")
```

A model your account can't use fails the run with code `model_key_missing`, and
an error that says which key to set: pick one from that list, or add the
provider's key under **Models & keys**.

## 4. Stream it

`run()` waits for the whole run. To show it as it happens, `stream()` yields its
text as the model writes it, each tool call and result, and last the run:

```ts
for await (const part of agent.stream("And tomorrow?")) {
  if (part.type === "text") process.stdout.write(part.text);
  if (part.type === "tool_call") console.log(`\n[${part.name}(${JSON.stringify(part.arguments)})]`);
  if (part.type === "done") console.log(`\n(${part.run.status})`);
}
```

```python
stream = agent.stream("And tomorrow?")
async for part in stream:
    if part.type == "text":
        print(part.text, end="", flush=True)
    elif part.type == "tool_call":
        print(f"\n[{part.name}({part.arguments})]")
    elif part.type == "done":
        print(f"\n({part.run.status})")
run = await stream.result()  # the same run as "done" has, also after a stream that broke off
```

The run's result is the truth; the stream is for display. A stream that breaks
never loses the run: `run()` (or `stream.result()`) still resolves with it.

## What just happened

- `upsert("quickstart", …)` made a keyed agent, or found the one made last time
  and brought it to this configuration. It lives until you delete it, so running
  the file again continues the same conversation. See [Concepts](https://run.camelai.com/docs/concepts.md).
- Because the agent has `tools`, this process served them: the runtime called
  `weather` here, over the connection the SDK holds. One process at a time serves
  an agent's tools, and only while it runs. Serverless functions, several web
  workers or task workers, and multi-user backends serve tools over HTTP
  instead, which also keeps them working through deploys; see [Several
  processes, workers and deploys](https://run.camelai.com/docs/guides/tools.md#several-processes-workers-and-deploys).
- `run()` resolved with a `Run`: `status` (`completed`, `input_required` or
  `failed`), `text`, `inputs`, `error`, `toolCalls` (Python `tool_calls`: each
  tool it called), `toolErrors` (Python `tool_errors`). A failed run throws a
  `RunError` unless you pass `throwOnError: false` (`throw_on_error=False`). A
  `completed` run can still list tool errors, e.g. `connection_lost` when the
  process serving its tools went away mid-call: check them.
- `agents.close()` let the process exit. The agent stays in the runtime.

One answer per input, with nothing to remember (classify, extract, vote)?
Skip the agent: `await agents.run({ instructions, input, output })` is one call,
and keeps nothing between runs. See [Stateless runs](https://run.camelai.com/docs/guides/stateless-runs.md).

Next: [Concepts](https://run.camelai.com/docs/concepts.md), then the guide for what you are building:
[a chat in your app](https://run.camelai.com/docs/frontend.md) (`npm create @camelai/run-app`),
[tools](https://run.camelai.com/docs/guides/tools.md), [asking people](https://run.camelai.com/docs/guides/human-input.md),
[showing an agent in a browser](https://run.camelai.com/docs/guides/browser.md), [files](https://run.camelai.com/docs/guides/files.md),
[agents for many users](https://run.camelai.com/docs/guides/multi-user.md), [webhooks](https://run.camelai.com/docs/guides/webhooks.md).
Before you ship, read the [production checklist](https://run.camelai.com/docs/production.md).

---

<!-- https://run.camelai.com/docs/concepts.md -->

# Concepts

## Agents are durable and keyed

An agent is a conversation that lasts: its history, its files, its configuration
(model, instructions, tools) and its pending work live in the runtime, not in
your process. Most agents are asleep at any moment and cost nothing; a message
wakes one on whichever node has room, and it picks up where it was.

You name an agent with a **key**, your own id for it: `support-triage`,
`user-123`, `thread-9f2c`. Keys are 1 to 80 letters, digits, `_` and `-`.

```ts
const agent = await agents.upsert("user-123", { model, instructions, tools });
```

- The same key is the same agent, from any process, for as long as you keep it.
  A keyed agent lives until you delete it (`agent.delete()`, `DELETE
  /v1/agents/{id}`). Only your API key can delete an agent: its own token gets
  a 401, since that token lives in your application's process (and in browsers
  through it), and deleting purges the agent's history and workspace.
- `upsert` makes the agent when there is none, and otherwise brings it to the
  configuration you pass: a changed model, instructions or tool list is applied
  between its turns, and its history carries over. Who the agent acts for
  (`subject`, `context`), its definition and its mounts are fixed when it is
  made; changing them is a 409 that names the field (an upsert may change the
  mounts with `remount: true`). Delete it and upsert again
  to start over.
- A deleted key makes a fresh agent the next time, with a new id and token.
- Make an agent once per user, conversation or job, and reuse it. Creating
  agents is cheap and limited only against abuse (600 a minute; an upsert that
  changes nothing does not count). The limit to design around is **busy
  agents**: how many may run at once, 20 on free credit and more with each
  [usage tier](https://run.camelai.com/docs/reference/limits.md#usage-tiers). Runs are limited to 240 a
  minute on free credit (600 once you buy credit). See
  [Rate limits](https://run.camelai.com/docs/reference/limits.md#rate-limits).
- Over REST, the key is the `Idempotency-Key` of `POST /v1/agents`.

Every agent also has an **id** (`client_…`), which is safe to log and store, and
a **token**, which lets its holder run it and nothing else (not delete it, nor
change who it acts for, its tools' sources or its limits). The SDKs keep the
token out of logs; you rarely need it, because upserting by key gives you the
agent again. If a token leaks, `POST /v1/agents/{id}/credentials/rotate` gives
the agent a new one: the old one stops working at once and connections made
with it close, and `GET /v1/agents/{id}/credentials` (the SDKs' `agents.get`)
gives the new one from then on.

Agents made without a key are scratch agents: they expire after a day unless you
set `ttlSeconds`. `idleTtlSeconds` instead makes an agent live that long from its
latest run, so one in use is kept and one left alone expires (an agent for a chat
that should go once nobody has written in a week, say).

## Runs

A message to an agent starts a **run**: the model loop, with every tool call it
makes, until the model answers or something stops it. One run at a time: a
message sent while a run is going waits for it (`whileRunning: "queue"`, the
default) or joins it (`whileRunning: "steer"`: the running turn reads it after its
current step). A steer is answered at once (`agent.steer()` returns a receipt:
`accepted`, `taken` or `queued`), and its request completes as the turn reads it,
so a turn fed messages constantly never fills the agent's queue.

```ts
const run = await agent.run("Summarize ticket 123", { user: "alice" });
```

A `Run` has:

| field | |
| --- | --- |
| `id` | the run's id; pass `idempotencyKey` to choose it, and sending the same key again returns the same run instead of starting another |
| `status` | `completed`, `input_required` (it waits on a person: see `inputs`), or `failed` |
| `text` | the final reply |
| `output` | with `output: schema`, the answer in that shape ([Structured output](https://run.camelai.com/docs/guides/structured-output.md)) |
| `inputs` | what it waits on, each with `answer()` |
| `error` | `{code, message, uncertain?}` when it failed |
| `toolErrors` | tool calls that did not complete (timed out, connection lost, no process serving the tools); the model was told and carried on |
| `toolCalls` | every tool call the run made (the first 100), calls from `js_exec`'s code included: `{tool, toolCallId, innerCallId?, ok, code?, agentId?}`. A `delegate` call names its sub-agent (`agentId`). Arguments and results are in history |
| `files` | files the run wrote |
| `usage` | what its model calls used, where the runtime reports it; `subagentCostUsd`, what its sub-agents spent; `imageCostUsd`, what its `generate_image` calls cost |

### Runs without the history

`history: "none"` (Python `history="none"`) runs a message as a new
conversation would: the model sees the agent's instructions and tools as they
are now, and this message, not the messages before it. One agent can then answer
many independent questions without making an agent for each (creates are
[rate limited](https://run.camelai.com/docs/reference/limits.md#rate-limits); runs far less).

```ts
const run = await agent.run("Is a hot dog a sandwich?", { history: "none", output: Verdict });
```

The run is still recorded in the agent's history, its user message marked
`history: "none"`, for audit and for the console. Runs that do not say `none`
see it as they see any other message. Such a run is never compacted after, since
it read nothing to compact; a later run with the whole history compacts first if
it must. It is for a prompt that starts its own turn, not `whileRunning: "steer"`.
Resumed after a person answers it, or continued on another node, the run stays
without the history.

`run()` has no timeout: runs can take minutes, and a run waiting on a person can
wait for days. Pass an `AbortSignal` (Python: `timeout=`) to stop waiting; the
run itself goes on, and `agent.abort()` stops it: the running turn ends, and the
runs queued behind it are cancelled (code `cancelled`), so nothing runs after the
stop (`abort({ queued: "keep" })` stops the running turn only). A failed run throws a
`RunError` carrying the run, unless you pass `throwOnError: false`.

### Stateless runs

When each answer should stand alone (classify, extract, vote, judge), there is
no agent to keep: `agents.run({ instructions, input, output })` (REST:
`POST /v1/runs`) takes a configuration and an input and returns the result,
with nothing carried over and no agent made. It is as durable as an agent's run
and counts against the same limits. See [Stateless runs](https://run.camelai.com/docs/guides/stateless-runs.md).

### Long conversations

An agent's history can outgrow its model's context window, so the runtime
**compacts** it: older messages are summarized, and the model sees the summary
followed by the recent messages. History keeps every message (`/history`); only
what the model is sent changes.

Compaction runs in the background. Once the context comes within a margin of
its limit (32k tokens, or 15% of a smaller window, before the window less a
reserve for the reply), the summary is made after the run ends, or between
model requests, while the agent goes on: the next run starts at once with the
whole context, and the summary takes over when it is written. Only a run whose
context would not fit waits, for the summary being made or, if none is, for one
of its own. A provider that rejects a request as too long also gets a summary
and the request again. Summaries are billed like model responses (`kind:
"compaction"` in usage) and count against spend limits; one made between runs
belongs to no run. An agent compacts one summary at a time.

## Forking

A **fork** is a new agent made from an existing one: the same configuration
(model, instructions, definition, tools, built-ins, who it acts for, key scope,
spend and run limits), a copy of its history, and a copy of its workspace files.
From then on each is its own: a turn, a compaction or a file written in one never
shows in the other. Fork to try another direction without losing the first, to
branch a conversation where a user edits an earlier message, or to start many
agents from one prepared one.

```ts
const branch = await agent.fork({ key: "thread-9f2c-b" });
const earlier = await agent.fork({ atMessage: 4 }); // history through message 4
```

- **Where it ends.** By default the copy ends with the agent's last finished
  turn: never inside a turn that is running or waiting on a person, so forking a
  busy agent is safe. `atMessage` ends it earlier: a history index (the `index`
  of a [history page](https://run.camelai.com/docs/reference/sdk.md#history-in-pages) entry) keeps that message
  and the tool results that answer it; a run's request id keeps that run's whole
  turn. A message in a turn that has not ended is a 409 `FORK_POINT_RUNNING`.
- **Compaction.** The copy keeps the source's summaries, so the fork's model sees
  what the source's would at that point: the summary, then the messages after it.
  History (`/history`) has every message.
- **Files.** The fork's workspace (at the source's path, `/workspace` by default) is a
  [fork of the source's volume](https://run.camelai.com/docs/guides/files.md#volumes) as it is when you fork,
  not as it was at `atMessage`. Other volumes the source mounts are mounted as
  they are, shared. Files the history refers to (attachments) stay the fork's,
  whatever becomes of the source.
- **Not copied:** schedules, channel bindings, pending inputs, runs and their
  events, and what the source has spent.
- **Its own:** `subject` and `context` (who it acts for, and its tool servers'
  context, fixed once it is made as at a create), `systemPromptAppend` and
  `modelHeaders` may be given for the fork instead of the source's: a fork for
  another conversation names that conversation.
- **Keys.** A fork made with a `key` is a keyed agent: it lives until deleted,
  and forking again with the same key returns the same fork (another agent's key
  is a 409). Without one it is a scratch agent that lives a day, unless you set
  `ttlSeconds`.
- `forkedFrom: {agentId, atMessage}` on the fork (`GET /v1/agents/{id}`, the
  console) says where it came from: `atMessage` is the index of the last message
  it began with.

A fork is an agent like any other: it counts toward your agents and their
storage, and against the `agent_creates` rate limit (`atMessage: 0` included).
To run one message without the history, send it with `history: "none"` instead. The copy costs only storage; its history and files share stored content
with the source. Over REST it is `POST /v1/agents/{id}/fork` with `{key?, name?,
atMessage?, ttlSeconds?, subject?, context?, systemPromptAppend?, modelHeaders?}` (the key may be
the `Idempotency-Key` header instead);
in the console, **Fork** on the agent's page, or **Fork from here** under a reply.
Browser tokens cannot fork.

## The result is the truth; events are for display

An agent's **events** stream every step: text as the model writes it, tool
calls and their progress, inputs asked and answered. Use them to show the agent
working. Do not use them to decide what happened.

- The run's result (`run()`, the webhook `run.completed`, or `GET
  /v1/agents/:id/requests/:id`) is recorded durably and always arrives, even if
  your process restarts or the connection drops.
- The stream is replayed from memory on reconnect, as far as it goes. Where it
  cannot replay (a restarted node, a long disconnection), the SDK gets a
  snapshot of the running turn instead; streamed deltas in between are gone.

So reply to your user from the run, and render the stream as progress. See the
[event reference](https://run.camelai.com/docs/reference/events.md).

## Tools: where they run

An agent's tools come from four kinds of place. Pick by where your code runs:

| Your situation | Use | How |
| --- | --- | --- |
| A long-lived server or worker, and the tools touch its state | **Attached tools** | `tools` on `upsert`; the SDK holds a connection and the runtime calls your functions over it. One process serves an agent's tools at a time; closing it on SIGTERM finishes its calls, so deploys lose none |
| Serverless functions, several instances, or one backend serving many users' agents | **Served tools** | `serveTools(tools)` on an HTTPS endpoint of yours, named in a **definition** with `auth: { type: "runtime" }` (or in the agent's own `mcpServers`); the runtime calls it with a signed token saying who each call is for. Safe through your deploys and restarts |
| A third-party API | **OpenAPI** or **MCP** sources in a definition | the runtime calls the API itself, with credentials it stores sealed |
| Web search, fetching pages, scheduling, asking the user | **Built-ins**, on the agent or in its definition | `builtins: ["web_search", "web_fetch", "schedule", "ask_user"]` |
| Other agents doing tasks for this one | The **`delegate`** built-in, with the agents it may reach | `delegate: { agents: ["researcher"] }`. See [Multi-agent](https://run.camelai.com/docs/guides/multi-agent.md) |

The same `tool({...})` definitions work attached and served, so you can start
attached and move to served without changing a tool (see [Several processes,
workers and deploys](https://run.camelai.com/docs/guides/tools.md#several-processes-workers-and-deploys)). Every agent also has file
tools over its [files](https://run.camelai.com/docs/guides/files.md), and `js_exec`, a sandbox where the model
writes code that calls all of its tools. See [Tools](https://run.camelai.com/docs/guides/tools.md).

## Processes and connections

A process that has an agent's tools **attaches** to it: it holds the agent's
event stream and answers its tool calls. One process at a time does, so a tool
call never lands in the wrong process. A second process that tries gets
`APPLICATION_CONNECTED`, unless it passes `takeover: true`; the one it replaces
hears `APPLICATION_REPLACED` and goes on without serving the tools.

Any number of processes can **run** an agent without serving its tools: an
agent upserted without local tools, or with `attach: false`, follows the
agent's stream read-only. That is how serverless functions, webhook handlers and
second services run agents whose tools are served elsewhere. Such a handle
connects lazily: it holds the stream only while `agent.stream()` reads a run (or
an `onEvent` handler listens), and `agent.run()` asks for its outcome instead,
so a server holding many agents holds no idle connections.

A run of an agent with attached tools while no process serves them is refused
up front, with `APPLICATION_NOT_CONNECTED` (after a few seconds' grace for a
process reconnecting), rather than running without them. Pass
`allowDisconnected: true` to run anyway: calls to those tools then fail, and the
run lists them in `toolErrors` with code `not_connected`. Schedules, channels and
resumed runs are never refused, so agents that must work with nobody attached
should use served tools.

A process that connects with tools other than those the agent was last given
(it was restarted with changed code) declares its own, between the agent's
turns. `upsert` declares them anyway.

## People in the loop

A run can stop and wait for a person: the model asks a question (`ask_user`), a
tool needs approval before it runs, or a tool asks for a form or a setup step.
The run ends with `status: "input_required"` and its `inputs`; the agent sleeps,
for days if need be; answering the last input resumes it.

```ts
if (run.status === "input_required") run = await run.inputs[0].answer(true, { from: "alice" });
```

See [Human input](https://run.camelai.com/docs/guides/human-input.md).

## Idempotency

Everything that changes something can be retried safely:

- `upsert` by key, and `run` / `POST /v1/agents/:id/prompt` by `idempotencyKey`
  (the request id): the same key returns the same agent or run.
- Every other POST takes an `Idempotency-Key` header: a retry with the same key,
  path and body gets the first answer again (for a day); the same key with a
  different body is a 409. An answer with a secret shown once (an API token,
  including a new tenant's from `POST /v1/tenants`, a signing secret, a browser
  token, a rotated agent token or a signed link) is never stored: a retry of a key that succeeded is a
  409, not the secret again.
- Every tool call carries `context.idempotencyKey`, the same for every attempt
  of that call: a retry after a lost connection, or the call run again after a
  person answered. Key your side effects by it. (`context.callId` is new each
  attempt.)

A tool call whose answer was lost (the connection dropped, or its deadline
passed) is never sent again: the model is told its outcome is unknown, so it can
check before repeating anything.

## Waking later

An agent can be woken by a schedule (`agent.client.schedule({ text, inSeconds |
at, everySeconds })`, or the `schedule` built-in for the agent to set its own), by
a [channel](https://run.camelai.com/docs/guides/channels.md) (Slack, Telegram, Discord), or by your own code
from a [webhook](https://run.camelai.com/docs/guides/webhooks.md).

A repeating schedule's wake-ups are turns of the agent, so by default each one
reads all the history before it, and a daily agent's context grows every day.
`history: "none"` on a text schedule wakes it with only the system prompt and the
text, as a prompt's `history: "none"` does: the runs are still recorded,
but no wake-up pays to read the ones before it. Write the text to say everything
the run needs.

A wake-up the runtime cannot deliver (the agent is busy at its account's limit,
say) is tried again 1, 5 and 15 minutes later, then given up; a refusal a retry
cannot change, like an agent or account at its spend limit (402), is given up at
once. A repeating schedule then moves to its next occurrence, and lists the
failure: `failures` (occurrences given up in a row) and `lastError`, until a
delivery succeeds. A one-off schedule given up is removed.

## Definitions

A **definition** is a reusable configuration: model, instructions, tool sources
(MCP servers, OpenAPI specs, built-ins), limits and mounts. Make agents from one
(`definition: "def_…"` on `upsert`), and roll a change out to all of them with
`apply: "all"`. See [Definitions](https://run.camelai.com/docs/guides/definitions.md).

## Several agents

Agents can work together, inside the runtime. With the `delegate` built-in, an
agent hands a task to a **sub-agent** (an agent of its own, made from a
definition for the task, or an existing one) and gets its answer back as the
call's result; several at once run in parallel. A sub-agent survives a lost
node, and counts against its parent's limits. There are no handoffs: the
conversation stays with the agent that has it. See [Multi-agent](https://run.camelai.com/docs/guides/multi-agent.md).

---

<!-- https://run.camelai.com/docs/pricing.md -->

# Pricing and credit

camelRun is prepaid: you buy credit, and usage draws it down. There is no
subscription and no per-seat or per-agent fee. `GET /v1/billing` (the console's
**Billing** page) shows your balance, this month's spending by kind, and the
rates below as your account is charged them.

| What | Price |
| --- | --- |
| Model calls on the platform's keys | The provider's own reported cost, else the model catalog's price (`GET /v1/models`, `cost` per million tokens). No markup. OpenRouter models add what funding OpenRouter credit costs: ×1.055 |
| Model calls on your own key (or a key scope's) | Nothing from camelRun: the provider bills you |
| Agent time | $0.01 per hour an agent spends in a run (model calls and tool execution), metered continuously. An idle agent costs nothing |
| Storage | $0.10 per GB-month of what your agents and volumes keep (history, files, snapshots), charged daily |
| `web_search` on the platform's keys | Per search, by the provider that answered: Exa $0.007, Brave $0.005, Parallel $0.001 |
| `web_fetch` page rendering on the platform's key | $0.00083 per page Firecrawl renders |
| [Transcription](https://run.camelai.com/docs/guides/voice.md) on the platform's OpenAI key | $0.0045 per minute of audio (`gpt-transcribe`), billed per second |
| [Images](https://run.camelai.com/docs/guides/images.md) on the platform's OpenAI key | Per token as OpenAI bills `gpt-image-2.5-flare`: $5 per million text tokens in, $8 per million image tokens in, $30 per million image tokens out. A 1024x1024 image is $0.0059 at `low`, $0.0132 at `medium`, $0.0527 at `high` |

## Credit

- **Starting credit: $5**, once. GitHub accounts older than 30 days get it at
  sign-up. Everyone else unlocks it by verifying a card on the **Billing** page;
  the card is not charged.
- **Buying credit:** $5 to $1,000 at a time, with a 5.5% fee on the purchase.
  Auto top-up can buy more when your balance runs low.
- **Before your first purchase:** at most $1 of model tokens and agent time an
  hour, and 1 GB stored. After it, 100 GB stored, and the
  [usage tiers](https://run.camelai.com/docs/reference/limits.md#usage-tiers) raise how many agents may be
  busy at once as your purchases add up.
- At zero balance, new runs and file writes get 402 `INSUFFICIENT_CREDIT`, and a
  running turn ends after the response that spent the last credit. Nothing is
  deleted: add credit and send the next message.

## Spending less

- Use your own provider keys (`PUT /v1/providers/:provider/key`): model calls
  then cost you only what the provider charges, and camelRun charges agent time
  and storage. See [Models and keys](https://run.camelai.com/docs/guides/models-and-keys.md).
- Bound an agent or a run with a [spend limit](https://run.camelai.com/docs/guides/models-and-keys.md#spend-limits),
  and see where credit goes with `GET /v1/usage` or the `usage.recorded`
  [webhook](https://run.camelai.com/docs/guides/webhooks.md).

A self-hosted runtime charges nothing unless its operator sets up billing; see
[Self-hosting](https://run.camelai.com/docs/operations/self-host.md).

---

<!-- https://run.camelai.com/docs/guides/projects.md -->

# Projects

A project is something an agent builds for your users, a bot, a site, a report,
that your application then runs or serves. The agent works on the files with its
file tools; your application checks them and publishes versions. The pattern:

1. **A volume per project**, made once per key (`projects.create`).
2. **An agent that works in it**, with the volume mounted read-write and its own
   workspace beside it (`project.mount`).
3. **A publish step in your code**: snapshot the volume, read every file at that
   snapshot, check them, and store them where your application keeps what it
   serves (`project.publish`). The snapshot is the version: what you checked is
   exactly what you stored, whatever the agent writes meanwhile.
4. **A `publish` tool the model calls** when its work is ready (`publishTool`),
   which finds the project from the call's signed identity and tells the model
   what to fix when the check fails.

## Making a project

```ts
import { Agents } from "@camelai/run";

const agents = new Agents();
const project = await agents.runtime.projects.create({
  key: `bot-${bot.id}`,
  template: { "bot.ts": starterCode, "README.md": "# My bot\n" },
});
```

- `key` names the project within your account: the first create makes its
  volume, and every later one returns the same volume, for as long as it lives
  (`POST /v1/volumes {key}`; `existing: true` on the later ones). Store
  `project.id` if you like, or create by key every time.
- `template` (path to text or bytes) seeds a new project. It never overwrites a
  file that is there; a project with no files is seeded again, so a create cut
  off half-way finishes on its retry.
- A deleted project's key makes no other (a 409): pick a new key.

## The agent that builds it

```ts
const builder = await agents.upsert(`builder-${bot.id}`, {
  definition: "bot-builder",            // its prompt and tools, including your publish tool
  subject: owner.id, context: { bot: bot.id },
  ...project.mount("/bot"),
});
```

`project.mount(path)` mounts the project's volume read-write at `path`, first,
so relative paths are the project's, keeps the agent's own workspace at
`/workspace` beside it (uploads, tool outputs and scratch files go there, not
into the project), and turns file tools on. To move an existing agent onto a
project, add `remount: true` to its upsert.

## Publishing

```ts
const result = await project.publish({
  prefix: "/",                                  // only these files (default: all)
  validate: files => check(files),              // [] when nothing is wrong
  store: async (files, version) => saveRelease(bot.id, files, version.id),
  keep: 20,                                     // published versions kept (default 20)
});
if (!result.ok) console.log(formatProblems(result.problems));
```

- `files` are `{path, size, contentType, sha256, text | data}`: `text` for UTF-8
  files, base64 `data` for any other (`fileBytes(file)` gives the bytes).
- `validate` returns problems, `{path?, line?, message}`. Any problem keeps the
  version from being published, and its snapshot is deleted. It may return
  `{problems, data}` instead: `data`, whatever the check worked out (a bundle,
  its manifest), reaches `store` as `checked` and comes back in the result
  (`result.checked`, and `published`'s argument in `publishTool`), so `store`
  does not work it out again.
- `store` runs once per version. It gets the version (`{id, seq, name,
  createdAt}`) and `{project, identity}` (the identity when `publishTool`
  published it); keep `version.id` to read that version again with
  `project.files({ version })`.
- `project.versions()` lists the published versions, oldest first. A volume
  keeps at most 100 snapshots, so older versions beyond `keep` are deleted.
- `idempotencyKey` publishes once per key: a retried call gets the version the
  first one made (its check runs again only for its `data`).
- `project.archive({ version?, path? })` gives a version's files (or the
  project as it is) as a tar.gz stream, for a build.
- `publish({ pin: true, labels })` pins the version: kept until
  `project.unpin(version)`, past `keep` (pinned versions do not count against
  it), up to 10,000 of them. Pin releases your application runs, so their source
  is always there; `project.pin(version, labels?)` pins one later.
  `project.versions({ labels })` finds versions by label, e.g.
  `{ release: "v12" }`.
- `project.restore(version)` puts the project back as a version had it, in
  place: the agent working in it sees the files change. The version stays
  published; publish again to make the restored files a new version.

## The publish tool

Give the model a tool that publishes, served by your application with
[`serveTools`](https://run.camelai.com/docs/guides/tools.md#served-tools-over-http-for-serverless-and-many-users) and named in the agent's
definition with `auth: { type: "runtime" }`:

```ts
import { publishTool } from "@camelai/run";
import { serveTools } from "@camelai/run/server";

export default {
  fetch: serveTools({
    publish: publishTool({
      // Who the call is for comes from the runtime's signed token, never from the model.
      project: identity => agents.runtime.projects.get(volumeOfBot(identity.context.bot)),
      validate: files => check(files),
      store: (files, version, { identity }) => saveRelease(String(identity!.context.bot), files, version.id),
    }),
  }, { runtime: "https://run.camelai.com", tenant: "acme" }),
};
```

An agent whose project changes during its life (one builder per user that
moves its `/bot` mount from bot to bot with `remount: true`) has no project in
its identity: its `context` was fixed when it was made. Look up what it has
mounted now instead, from the agent the call came from:

```ts
project: async identity => {
  const mount = (await agents.runtime.mounts(identity.agent)).find(entry => entry.path === "/bot");
  if (!mount) throw new Error("No bot is open in this builder");
  return agents.runtime.projects.get(mount.volumeId);
},
```

Check that the volume is one of the user's projects (a key or row of yours
names it) before you publish it: the mount was set by your code, but the lookup
is what decides which project a publish reaches.

It takes no arguments. On success the model gets `{published: true, version}`;
otherwise the call fails with the problems, one a line (`/bot.ts:12: …`), so the
model fixes them and publishes again. A retried call publishes once: the
runtime sends each call's idempotency key. A client that sends none gets a new
version for every call.

## In Python

`camelai_run.projects` has the same helper, async:

```python
from camelai_run.projects import Projects, publish_tool

projects = Projects(agents.runtime)
project = await projects.create(f"bot-{bot.id}", template={"bot.py": starter})
builder = await agents.upsert(f"builder-{bot.id}", definition="bot-builder", subject=owner.id, context={"bot": bot.id}, **project.mount("/bot"))
result = await project.publish(validate=check, store=lambda files, version, about: save_release(bot.id, files, version["id"]))

app = serve_tools([publish_tool(project=lambda identity: projects.get(volume_of_bot(identity.context["bot"])), validate=check, store=save)], runtime=RUNTIME, tenant="acme")
```

`publish_tool` works in `serve_tools` (ASGI) and in `camelai_run.sync.serve_tools`
(WSGI: Django, Flask). Files are dicts with `"text"` or base64 `"data"`
(`file_bytes(file)` gives the bytes).

## Security

- **Derive the project from identity.** `project(identity)` reads who the call
  is for from the runtime's signed token (`subject`, `context`), which you set
  when you made the agent and the model cannot change. Never take a project id,
  a path or a version from the model's arguments.
- **Check what you read, not what the model says.** `publish` reads the files
  server-side from a snapshot; the model never hands you content. Treat every
  file as untrusted input: validate it, and run it only where your application
  runs untrusted code.
- **Keep the agent to its project.** Give the builder the project's volume and
  its own workspace, nothing else of yours. Its own token can read and write its
  mounts; your API key, which reads every project, stays on your server.
- **Store versions, serve versions.** Serve what `store` kept for a published
  version, never the live volume, which the agent may be changing.

## From the REST API

| | |
| --- | --- |
| make or find a project's volume | `POST /v1/volumes {name, key}` |
| mount it beside the workspace | `mounts: [{volumeId, path: "/bot", mode: "rw"}, {workspace: true}]` on `POST /v1/agents` (`remount: true` on an upsert to change them) |
| take a version | `POST /v1/volumes/:id/snapshots {name}` |
| read every file of it at once | `GET /v1/volumes/:id/files?content=true&snapshot=snap_…` |
| list and delete versions | `GET /v1/volumes/:id/snapshots`, `DELETE /v1/volumes/:id/snapshots/:snapshot` |
| restore a version in place | `POST /v1/volumes/:id/restore {snapshot}` |
| pin a version, label it | `PATCH /v1/volumes/:id/snapshots/:snapshot {pinned, labels}`, or `pinned`/`labels` on the create |
| bring in a version kept elsewhere | `POST /v1/volumes/:id/snapshots {name, files, pinned, labels}` |
| download a version as a tar.gz | `GET /v1/volumes/:id/archive?snapshot=snap_…` |

---

<!-- https://run.camelai.com/docs/guides/tools.md -->

# Tools

An agent's tools are how it acts. This guide covers where they run, how to write
them so a retry never does harm, and how the runtime tells a tool who a call is
for. For the short version of where tools should run, see the table in
[Concepts](https://run.camelai.com/docs/concepts.md#tools-where-they-run).

## Writing a tool

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

const refund = tool({
  description: "Refund an order in full",
  input: schema.Object({ orderId: schema.String() }),
  timeoutMs: 60_000,
  execute: async ({ orderId }, context) => {
    context.progress("Contacting the payment provider");
    return payments.refund(orderId, { idempotencyKey: context.idempotencyKey, signal: context.signal });
  },
});
```

```python
from camelai_run import ToolContext, tool

@tool(timeout=60)
async def refund(order_id: str, context: ToolContext) -> dict:
    """Refund an order in full"""
    context.progress("Contacting the payment provider")
    return await payments.refund(order_id, idempotency_key=context.idempotency_key)
```

- **Input.** TypeScript takes a [TypeBox](https://github.com/sinclairzx81/typebox)
  schema (`schema` is TypeBox's `Type`), and infers the arguments' type from it.
  Python derives the schema from the annotations (`str`, `int`, `float`, `bool`,
  `list`, `dict`) and the description from the docstring. Arguments are checked
  against the schema before your function runs.
- **Result.** Return any JSON value; `undefined`/`None` is sent as `null`. The
  model reads it as JSON text, and code in `js_exec` gets the value. Throw (raise)
  to tell the model the call failed: it sees your message. A result is at most
  1 MiB of JSON. The model reads at most 32,000 characters of a tool's result;
  a longer one is saved whole (up to 700 KB) to
  `/workspace/tool-results/<toolCallId>.txt`, where it can read the rest.
- **Python functions** may be `async` or plain; a plain one runs in a thread, so
  it never blocks the connection.
- **`context.idempotencyKey`** is the same for every attempt of one call: a
  retry after a lost connection, or the call run again once a person answered.
  Pass it to anything with side effects. `context.callId` is new on each attempt.
- **Deadline.** A call may go 15 seconds without answering (`timeoutMs`,
  `@tool(timeout=)`: 1 s to 20 minutes). Each `context.progress(...)` restarts the
  wait, up to 20 minutes in all, and people watching the agent see the progress.
  A call cut off is reported to the model as "outcome unknown" (it may still
  finish in your process): make the side effect idempotent and the model can
  check and retry safely.
- **`context.signal`** aborts when the runtime cancels the call (the run was
  aborted, or the deadline passed). Cancellation is not rollback.
- **`context.identity`** says who the call is for; see [Identity](https://run.camelai.com/docs/guides/tools.md#identity-who-a-call-is-for).
- **`needsApproval: true`** (`needs_approval=True`) makes a person approve each
  call first, and `context.confirm/ask/requireUrl` ask from inside the tool; see
  [Human input](https://run.camelai.com/docs/guides/human-input.md).
- **`exposure`** (`@tool(exposure=...)` in Python): `"direct"` (the model calls
  it as a tool), `"codemode"` (only from code in `js_exec`, as
  `tools.<name>(args)`), or `"both"`. By default a source of up to 10 tools is
  `both` and a larger one `codemode`, so big catalogs do not crowd the model's
  context. **So by default the model can call your tools from `js_exec`**, your
  attached and served tools included, and it may well batch them in code. See
  [Keeping tools out of js_exec](https://run.camelai.com/docs/guides/tools.md#keeping-tools-out-of-js_exec).

### Keeping tools out of js_exec

Code the model writes in `js_exec` can call every tool whose exposure is
`codemode` or `both`. That is what makes large catalogs cheap (the model loops,
filters and calls several tools in one step), but it also means a tool your app
expected to see called on its own may be called from code instead: its call is
then inside `js_exec`'s, its arguments do not stream as `toolcall_delta` events,
and a page that renders a tool's arguments as they are written sees nothing
until the code has run.

To keep a tool out of `js_exec`, make it `direct`:

| Where the tool comes from | Set |
|---|---|
| Your process (`tools` in `upsert`) | `exposure: "direct"` on the tool; Python `@tool(exposure="direct")` |
| A served or MCP server named in a definition | `"exposure": "direct"` on the server entry (every tool), or `_meta["agent-runtime/exposure"]` on a tool in its `tools/list` (that tool; it beats the server's) |
| An OpenAPI source | `"exposure": "direct"` on the source |

A tool with `needsApproval` is always direct. The console's agent page shows each
tool's exposure (**Tools the model gets**), and `GET /v1/agents/:id` its
`toolSources`. `js_exec` itself stays: it still runs code, with `fs` and
`fetch`, and the tools left in it.

## Attached tools: in your process

Pass `tools` to `upsert` and this process serves them to the agent:

```ts
const agent = await agents.upsert("ops", { model, instructions, tools: { refund } });
```

The SDK holds the agent's event stream; the runtime sends each tool call over it
and the SDK posts the result back. Your tools run with your process's state and
credentials, and nothing is exposed on the network. The trade-offs:

- One process at a time serves an agent's tools. Another process that upserts
  with the same tools gets `APPLICATION_CONNECTED` (pass `takeover: true` to
  replace the first, or `attach: false` to run the agent without serving them).
- A run while no process serves the tools is refused with
  `APPLICATION_NOT_CONNECTED`, unless you pass `allowDisconnected: true`
  (`allow_disconnected=True`): then calls to them fail, listed in the run's
  `toolErrors` with code `not_connected`. Runs a schedule or a channel starts are
  never refused and may find nobody connected: use served tools for those agents.
- If the connection drops while a call runs, its outcome is unknown to the
  runtime, and the model is told so; the call is never sent again.

An existing MCP server (from `@modelcontextprotocol/sdk`) can be attached as is:
`upsert(key, { mcp: await fromMcpServer(server) })` from
`@camelai/run/mcp`.

### Several processes, workers and deploys

Every process that upserts an agent with `tools` tries to serve them, and only
one can. Under uvicorn or gunicorn with several workers, Celery, or any fleet of
instances, the first to connect serves the tools and the others fail with
`APPLICATION_CONNECTED` (or take them from each other, with `takeover`).

Pick one of these:

- **Served tools (recommended for fleets).** Serve the tools over HTTP from your
  web app (`serveTools` / `serve_tools`, below) and name the server in a
  definition. Every process, web worker and task then upserts the agent from
  the definition with no `tools`, and any of them can run it. Each call is an
  HTTP request of its own to whichever instance is up, so a rolling deploy that
  drains its connections loses no call.
- **One tool process.** Run one long-lived process that upserts the agent with
  its `tools`. Everywhere else, upsert it with the same `tools` and
  `attach: false` (`attach=False`), which runs the agent without serving them.

#### Deploying a tool process

Close the agents when the process is told to stop, and a deploy loses no call:

```ts
process.once("SIGTERM", () => void agents.close().then(() => process.exit(0)));
```

```python
from contextlib import asynccontextmanager
from fastapi import FastAPI

@asynccontextmanager
async def lifespan(app):
    yield
    await agents.close()  # uvicorn runs this on SIGTERM

app = FastAPI(lifespan=lifespan)
```

`close()` tells the runtime this process takes no new calls, finishes the
calls it is running (for up to 25 seconds: `close({ drainMs })`,
`close(drain=)` in seconds), then disconnects. Meanwhile new calls go to the
next process: in a rolling deploy, start it with `takeover: true`
(`takeover=True`), which takes the tools at once while the old process
finishes its calls; in a stop-then-start deploy, it connects without a
takeover, since a closing process holds the tools no longer, and calls wait a
few seconds for it. A takeover alone (without `close()`) also lets the
replaced process answer the calls it has, for up to 30 seconds.

What a deploy can still lose: a call that outlives the drain, and every call
running when a process crashes or is killed without `close()`. The model is then
told, in words it can pass on, that the tool's server disconnected during the
call and it may or may not have taken effect; the run lists it in `toolErrors`
(Python `tool_errors`) with code `connection_lost`. Key side effects by
`context.idempotencyKey` so that checking and retrying is safe.

#### When the tool process dies mid-run

The run lives in the runtime, not in your process, so it goes on without it:

- **The call that was running** fails as `connection_lost`, as above. The model
  is told, and usually checks or tries again.
- **A call while no process serves the tools** waits 3 seconds for one to
  connect, then fails as `not_connected` (it did not run).
- **The restarted process serves the run's next calls.** Once it upserts the
  agent with its `tools`, it serves every call that comes, including calls of
  runs a process before it started. A run is not tied to the process that sent it.
- **The `run()` the dead process awaited is gone, but its run is not.** Give each
  run an id of yours (`idempotencyKey`), saved before you send it, e.g. the job
  or the order it is for. After the restart, `run()` with the same text and the
  same key answers with that run instead of starting another: its result if it
  has ended, or once it ends if not. Without an SDK, `GET
  /v1/agents/:id/requests/<key>?wait=25` answers the same, and `GET
  /v1/agents/:id/state` lists the agent's runs.

Check `toolErrors` even when the run's `status` is `completed`: a run whose
call was cut off often ends normally, after the model worked around it.

```ts
// On startup (and after a crash): serve the tools, then collect the job's run.
const agent = await agents.upsert("ops", { model, instructions, tools: { refund } });
const run = await agent.run(`Refund order ${job.orderId}`, { idempotencyKey: job.id });
const lost = run.toolErrors.filter(error => error.code === "connection_lost");
if (lost.length) console.warn(`check whether ${lost.map(error => error.tool).join(", ")} took effect`);
console.log(run.status, run.text, run.toolCalls.map(call => call.tool));
```

```python
# On startup (and after a crash): serve the tools, then collect the job's run.
agent = await agents.upsert("ops", model=model, instructions=instructions, tools=[refund])
run = await agent.run(f"Refund order {job.order_id}", idempotency_key=job.id)
lost = [error for error in run.tool_errors if error["code"] == "connection_lost"]
if lost:
    print("check whether", ", ".join(error["tool"] for error in lost), "took effect")
print(run.status, run.text, [call["tool"] for call in run.tool_calls])
```
## Served tools: over HTTP, for serverless and many users

A server of yours answers tool calls over HTTP (MCP's Streamable HTTP), and a
definition tells the runtime to call it. Any number of instances can serve,
nothing needs to stay connected, and the runtime signs a token for each call
saying which agent it is for, whom that agent acts for, and who is acting.

```ts
import { serveTools } from "@camelai/run/server";

// A fetch handler: Cloudflare Workers, Bun and Deno serve it as is.
// tenant: your tenant's id (GET /v1/me, or `await agents.runtime.me()`): tokens for other tenants' agents are refused.
export default { fetch: serveTools({ refund }, { runtime: "https://run.camelai.com", tenant: "acme" }) };
```

On Node, wrap it: `createServer(nodeListener(handler, { origin: "https://tools.example.com" }))`
with `nodeListener` from `@camelai/run/node`. Tokens are checked
against the URL the runtime called, so set `origin` to your public URL. Without
it, the URL is the server's own (its socket's scheme and the Host header), which
is wrong behind a load balancer or proxy that ends TLS. `trustProxy: true` reads
`X-Forwarded-Proto` and `X-Forwarded-Host` instead, but only set it where the
proxy overwrites those headers: otherwise any client could choose the URL tokens
are checked against.

```python
from camelai_run import serve_tools

app = serve_tools([refund], runtime="https://run.camelai.com", tenant="acme")  # ASGI: uvicorn, or mount in FastAPI
```

Behind a proxy, run uvicorn with `--proxy-headers` (and `--forwarded-allow-ips`
naming the proxy), or pass `audience="https://tools.example.com/mcp"`.

To offer each agent its own tools (an admin's, a plan's), pass a function of the
caller's identity instead of the tools; a tool it is not given is refused if
called. A `ToolServer` of your own gets the same as `listTools(context)`:
`{identity, origin, signal}`.

```ts
serveTools(identity => identity.context.role === "admin" ? { refund, ban } : { refund }, options);
```

```python
serve_tools(lambda identity: [refund, ban] if identity.context.get("role") == "admin" else [refund], runtime=..., tenant=...)
```

### A server that moves

By default a token's audience is the server's URL, so a server that moves (a new
domain or path) refuses the tokens of agents still calling the old URL. Two ways
to move without that:

- Give the server a name that does not change: `audience:
  "urn:camelrun:<tenant>:<name>"` in the definition's server entry (your tenant's
  id, as `GET /v1/me` shows it, then a name of letters, digits and `._~:-`), and
  the same `audience` to `serveTools`. Tokens name it wherever the server is. Only
  your tenant's sources can name an audience in your tenant's namespace.
- Accept both addresses while agents move: `audience` takes a list, e.g.
  `["https://old.example.com/mcp", "https://new.example.com/mcp"]`.

Agents keep the definition revision they were made from, so after changing the
server's `url`, apply the new revision to them (`apply: "all"`, or
`applyOnUpdate: true` on the definition; see [Definitions](https://run.camelai.com/docs/guides/definitions.md)).

```ts
// Definition: { name: "shop", url: "https://tools.example.com/mcp", auth: { type: "runtime" }, audience: "urn:camelrun:acme:shop" }
export default { fetch: serveTools({ refund }, { runtime: "https://run.camelai.com", tenant: "acme", audience: "urn:camelrun:acme:shop" }) };
```

For Django, Flask or any WSGI server, `camelai_run.sync.serve_tools` takes the
same arguments and is a WSGI app. Plain functions run in the request's thread,
with its database connection; async ones run in an event loop of the request's
own. Mount it at the path the definition names:

```python
# Flask
from werkzeug.middleware.dispatcher import DispatcherMiddleware
from camelai_run.sync import serve_tools

app.wsgi_app = DispatcherMiddleware(app.wsgi_app, {"/mcp": serve_tools([refund], runtime="https://run.camelai.com", tenant="acme")})
```

```python
# Django: wsgi.py
from django.core.wsgi import get_wsgi_application
from camelai_run.sync import serve_tools

django_app = get_wsgi_application()
tools_app = serve_tools([refund], runtime="https://run.camelai.com", tenant="acme")

def application(environ, start_response):
    path = environ.get("PATH_INFO", "")
    if path == "/mcp" or path.startswith("/.well-known/oauth-protected-resource"):
        return tools_app(environ, start_response)
    return django_app(environ, start_response)
```

Behind a proxy, pass `audience="https://tools.example.com/mcp"`: the URL a WSGI
app sees is the server's own. `camelai_run.sync.verify_runtime_token` checks a token in a view
of your own.

(`pip install "camelai-run[server]"` for the token checks.)

Then name the server in a definition, and make agents from it:

```ts
const definition = await agents.runtime.upsertDefinition("support", {
  name: "Support",
  mcpServers: [{ name: "shop", url: "https://tools.example.com/mcp", auth: { type: "runtime" } }],
});
const agent = await agents.upsert(`user-${user.id}`, { definition: definition.id, subject: user.id, context: { org: user.orgId } });
```

Every request without a valid token for your server gets a 401: the signature
(the runtime's published Ed25519 keys), the issuer, the **tenant** (yours), the
audience (your server's URL as the runtime calls it) and the expiry are checked,
and nothing per user is stored anywhere.

`tenant` is required, and it matters: an identity means something only within
your own tenant. Any tenant can make agents, give them any `subject` and
`context`, and point them at your server's URL; the runtime signs their tokens
too. Only the tenant check tells your agents from theirs. Pass your tenant's id
(or a list, if several of your tenants share the server). To test your authorization without a runtime,
`testRuntime()` (`@camelai/run/testing`; `TestRuntime()` in Python, and
`camelai_run.sync.TestRuntime()` for a WSGI app) signs tokens with a key of its own:

```ts
const rt = await testRuntime();
const result = await rt.callTool(serveTools(tools, rt.options), "https://app.test/mcp", "refund", { orderId: "o1" }, { subject: "alice" });
```

Built with the MCP SDK or Cloudflare's `createMcpHandler` instead? Verify with
`runtimeAuth(request, { runtime, tenant })`, pass the result as the request's `auth`, and
read `runtimeIdentity(extra)` in a handler. `verifyRuntimeToken(token, { runtime,
tenant, audience })` checks a token on its own. `testRuntime()`'s tokens name
tenant `test`, which `rt.options` passes.

## Identity: who a call is for

Every tool call carries `context.identity`, from the signed token for served
tools and from the call itself for attached ones, so a tool reads it the same way
either way:

| field | |
| --- | --- |
| `user` | whom to authorize as: the turn's actor, else the agent's subject |
| `subject` | whom the agent acts for: `subject` given when it was made (its id if none) |
| `actor` | who is acting in this turn: the run's `user` (`from.id`), or an `actor` given with the message |
| `context` | claims given when the agent was made (`context: { org, workspace }`) |
| `tenant`, `agent`, `definition` | whose agent it is, and which (`definition` only for an agent made from one) |
| `origin` | where the turn came from: a channel, its conversation and sender |
| `approval` | the person's approval, for a call that needed one |

`subject` and `context` are set with your API key when the agent is made, and the
agent's own token cannot change them; the model cannot touch any of it. So,
once the token is checked to be from your own tenant (served tools), a tool can
trust `identity`, and should never take a user id from the model's arguments.
Another tenant's agents can claim any `subject`: `identity` is only meaningful
within your tenant. See [Many users](https://run.camelai.com/docs/guides/multi-user.md).

The token itself (for servers that verify it by hand, e.g. with `jose`):

```json
{ "iss": "https://agents.camelai.dev", "aud": "https://tools.example.com/mcp",
  "sub": "u_123", "tenant": "acme", "agent": "client_…", "definition": "def_…",
  "ctx": { "org": "acme" }, "act": "u_456", "origin": { … }, "req": "run_…", "tcid": "toolu_…",
  "par": "client_…", "root": "client_…", "iat": 1790000000, "exp": 1790000120, "jti": "…" }
```

```ts
const jwks = createRemoteJWKSet(new URL("https://run.camelai.com/.well-known/jwks.json"));
const { payload } = await jwtVerify(token, jwks, { issuer: "https://agents.camelai.dev", audience: "https://tools.example.com/mcp", algorithms: ["EdDSA"] });
// Any tenant's agent can get a token for your server's URL: accept only your own tenant's.
if (payload.tenant !== "acme") throw new Error("Not our tenant's agent");
```

- `tenant` must be your own (your tenant id, as `GET /v1/me` shows it): the
  signature, issuer and audience prove only that the runtime issued the token
  to some agent for your server's URL, and anyone can make an agent.
- `iss` is the hosted runtime's first address, `https://agents.camelai.dev`,
  at either of its URLs (a self-hosted runtime's is its `AGENT_ISSUER`, else its
  `AGENT_PUBLIC_URL`). The SDKs expect it for either hosted URL.
- `aud` is the server's URL, or the source's `audience`: another URL on the
  server's origin, or a name in your tenant's namespace,
  `urn:camelrun:<tenant>:<name>` (see [A server that moves](https://run.camelai.com/docs/guides/tools.md#a-server-that-moves)).
  The runtime mints no token for another origin's URL or another tenant's name,
  so a token cannot be replayed against a server that is not yours.
  Tokens live two minutes, and each request gets its own `jti`.
- `act` and `origin` are absent outside a turn (listing a server's tools as an
  agent starts), and so are `req`, the run's request id, and `tcid`, the model's
  tool call (`identity.requestId` and `toolCallId` in the SDKs).
- `par` and `root` are set only in a [sub-agent](https://run.camelai.com/docs/guides/multi-agent.md)'s run: the agent
  that started it and the first agent of its chain, from the run's chain as
  the runtime signed it (`identity.parentAgentId` and `rootAgentId` in the SDKs).
  Authorize a sub-agent's call by `root` when only the first agent's user is yours.
- The keys are at `/.well-known/jwks.json` (cache them for minutes);
  `/.well-known/oauth-authorization-server` names the issuer for MCP clients.

## Definitions' sources

A [definition](https://run.camelai.com/docs/guides/definitions.md) lists tool sources the runtime calls itself. An
agent without a definition can also have [MCP servers of its
own](https://run.camelai.com/docs/guides/tools.md#an-agents-own-mcp-servers), without credentials.

### MCP servers

```json
{"name": "Support", "mcpServers": [{
  "name": "kb", "url": "https://mcp.example.com/mcp",
  "auth": {"type": "bearer", "token": "…"}, "headers": {"X-Team": "support"},
  "allowTools": ["search", "fetch_article"], "exposure": "both", "timeoutMs": 30000
}]}
```

- Streamable HTTP, falling back to the older SSE transport when a server answers
  its POST with 400, 404 or 405.
- `auth` is `{"type": "bearer", "token"}` or `{"type": "runtime"}` (signed
  identity tokens, above). `headers` and `auth` are stored sealed; the API
  returns only `headerNames` and `auth.type`. Updating a server without them
  keeps its stored credentials, unless its URL moved to another origin.
- `fileArguments` (`"on"` or `"off"`) says whether its tools are sent the
  agent's files: on by default with `auth: {"type": "runtime"}` only. See
  [Files in tool calls](https://run.camelai.com/docs/guides/tools.md#files-in-tool-calls).
- Tools reach the model as `<server>__<tool>`, filtered by `allowTools` and
  `denyTools`. A server can set a tool's own exposure in `tools/list` with
  `_meta["agent-runtime/exposure"]`, and its deadline with
  `_meta["agent-runtime/timeoutMs"]`.
- Each call has a deadline (`timeoutMs`, default 60 s, at most 20 minutes). It
  limits silence: each progress notification restarts it, up to 20 minutes in
  all. A call from `js_exec` also ends with its execution (60 s at most), so
  expose long tools directly.
- Text reaches the model as it is; images, audio, blobs and text resources over
  64 KiB are saved to the agent's workspace and reach it as files. `isError`
  becomes a tool error; `structuredContent` is what code gets.
- The runtime lists each server when you save the definition: one that refuses
  its credentials is a 400 saying so, and the answer's `toolSources` shows what
  each server offers (`status: listed`, or `error` with why). A server that
  cannot be reached when an agent starts contributes no tools that run; the
  run's `sourceErrors` lists it.
- Tool lists are cached for five minutes and dropped on
  `notifications/tools/list_changed`; a running agent takes a changed list at its
  next start.
- Progress a server reports for a call (`notifications/progress`) reaches the
  agent's events as a `tool_execution_update`, at most one per call every 250 ms.

Each call carries `_meta` for the server: `agent-runtime/idempotencyKey` (stable
across attempts), `agent-runtime/callId`, `agent-runtime/toolCallId` (and
`agent-runtime/innerCallId` for a call from code), `agent-runtime/actor`,
`agent-runtime/origin`, and `camelrun/files` when files are sent.

### OpenAPI specs

```json
{"name": "Support", "openApi": [{
  "name": "shop", "spec": "https://api.example.com/openapi.json",
  "auth": {"type": "bearer", "token": "…"}, "allowTools": ["listOrders", "getOrder", "refundOrder"]
}]}
```

Every operation of an OpenAPI 3 spec (JSON or YAML) is a tool:

- Named `<name>__<operationId>` (or `<name>__<method>_<path>`). Its input is the
  operation's path, query and header parameters by name, plus `body` for the
  request body (JSON, or form-encoded with nested values in brackets, as Stripe
  reads them). A `multipart/form-data` body's file fields, and a binary body,
  take `{"$file": path}` and stream the file, when the source's
  `fileArguments` is on (as for MCP servers).
- The spec is fetched and checked when the definition is saved, and its
  operations (after `allowTools`/`denyTools`, at most 1024) are stored with it:
  an agent's tools never change under it. Save the definition again to take a
  spec's changes. `spec` may also be the document itself.
- Requests go to `baseUrl` (default the spec's first server), with no redirects,
  `timeoutMs` (default 30 s, at most 20 minutes), and each call's stable key as
  an `Idempotency-Key` header. A 2xx answer is the result (JSON, text, or a file
  saved to the workspace); any other status is a tool error quoting the method,
  path, status and the start of the body.

## An agent's own MCP servers

An agent made without a definition, and a [stateless run](https://run.camelai.com/docs/guides/stateless-runs.md),
can list MCP servers itself, with no definition:

```ts
const agent = await agents.upsert("support", {
  instructions: "…",
  mcpServers: [{ name: "kb", url: "https://mcp.example.com/mcp", auth: { type: "runtime" } }],
});
```

```bash
curl -X POST "$BASE/v1/agents" -H "Authorization: Bearer $KEY" -H "Idempotency-Key: support" \
  -d '{"mcpServers": [{"name": "kb", "url": "https://mcp.example.com/mcp", "auth": {"type": "runtime"}}]}'
```

- They take no credentials: `auth` is `{"type": "runtime"}` or left out, and
  there are no `headers`. A server with a token or headers is a 400 saying to
  use a definition.
- Why: a definition seals its credentials once, for every agent made from it.
  Credentials on each agent or run would be secrets stored, copied and rotated
  per agent. Identity tokens need none: the runtime signs one for each request,
  naming the agent, its `subject` and `context` (and no `definition`).
- Everything else is as in a definition: `allowTools`, `denyTools`, `exposure`,
  `timeoutMs`, `audience`, `approval`, and the same outbound checks.
- They are not listed when saved. A server that cannot be listed when the agent
  starts shows in the run's `sourceErrors`.
- `PATCH /v1/agents/:id/configuration` with `mcpServers` replaces the list;
  `null` or `[]` removes it. An upsert sets the whole list, so an upsert without
  `mcpServers` leaves none. They count toward the upsert's `configHash`.
- Only your API key changes them, never the agent's own token. An agent made
  from a definition has its definition's servers and refuses its own (400).
- Only MCP servers: OpenAPI specs are fetched and stored when saved, so they stay
  in definitions.

## Built-ins

Tools the runtime answers itself, given to an agent as `builtins` when it is
made or upserted (`agents.upsert("researcher", { builtins: ["web_search",
"web_fetch"] })`, or `PATCH /v1/agents/:id/configuration`), or by the definition
it is made from (whose builtins it then has):
`"builtins": ["web_fetch", "web_search", "schedule", "ask_user", "delegate", "generate_image", "agents"]`.

- `web_fetch` (`{url, maxCharacters?}`) reads a public page as text (HTML
  reduced to readable text, 20,000 characters by default, at most 100,000), or
  saves any other content (a PDF, an image) to the workspace. Pages that are
  only a JavaScript shell are rendered when a Firecrawl key is available.
- `web_search` (`{query, count?, freshness?}`) returns `{query, provider,
  results: [{title, url, date?, content | snippet}]}`, trying search providers
  in order (Exa, Brave, Parallel; a definition can pin its own with
  `"webSearch": {"providers": ["brave"]}`). Your own key for a provider
  (`PUT /v1/providers/<provider>/key`) is used first; otherwise the platform's,
  charged per search on prepaid credit. Saving a definition or an agent with
  `web_search` when none of its providers has a key answers with `warnings`
  saying which keys would set it up, and the console shows them; a search then
  fails with the same text ("Web search isn't available for this account: add
  an Exa, Brave or Parallel key under Models & keys").
- `schedule`, `list_schedules`, `cancel_schedule` let the agent manage its own
  wake-ups (100 per agent, at most a year ahead, repeats at least a minute apart).
- `ask_user` lets the model ask the user 1 to 4 multiple-choice questions; the
  run waits for the answer. See [Human input](https://run.camelai.com/docs/guides/human-input.md).
- `delegate` (with `delegate: { agents }`) hands a task to a sub-agent and
  returns its answer. See [Multi-agent](https://run.camelai.com/docs/guides/multi-agent.md).
- `generate_image` (`{prompt, images?, size?, quality?, format?, background?}`)
  makes an image, or edits images from the agent's files (`images`: their
  paths), saves it to the workspace under `tool-outputs/generate_image/` and
  shows it to the model; the model presents it to the user with `present_file`.
  It uses OpenAI's `gpt-image-2.5-flare` on your OpenAI key (or a key scope's),
  else the platform's, charged per token on prepaid credit, and counts against
  the agent's and the run's spend limits. Saving a definition or an agent with
  it and no OpenAI key answers with a warning. See [Images](https://run.camelai.com/docs/guides/images.md#in-an-agent).
- `agents` (with the same settings) starts sub-agents in the background
  (`spawn_agent`, `wait_agent`, `list_agents`); each one's answer arrives as a
  notification. See [Background sub-agents](https://run.camelai.com/docs/guides/multi-agent.md#background-sub-agents).

## Seeing an agent's tools

`GET /v1/agents/:id` returns `toolSources` (SDK: `agents.runtime.toolSources(agentId)`,
Python `tool_sources`): every source in order of precedence (the channel's, the
attached application's, file tools, then the definition's), each with its
`status` and `tools`, and for each tool why the model does not get it, if it
does not (an earlier source has its name, or the catalog is full).
`?schemas=true` adds input schemas; `?refresh=true` lists every MCP server now,
which is how to check one before the agent runs. The console shows the same on
an agent's Configuration tab.

## Tools from code: `js_exec`

The model can write JavaScript that calls any of its tools, in a sandbox
(a bare V8 isolate in a process of its own) that can reach nothing else: `await
tools.shop__getOrder({ id })`, `Promise.all` for parallel calls, `fs` over its
files, `tools.search(query)` to find tools in a large catalog, `tools.describe(name)`
for a schema. Code runs for at most 60 seconds, 2 s of CPU and 256 tool calls; see
[Limits](https://run.camelai.com/docs/reference/limits.md). `agent.client.execute(code)` runs code
yourself, outside the model's history, which is handy for testing tools.

### Without code: `codeMode: false`

An agent made with `codeMode: false` (Python `code_mode=False`, in a definition
too) has no `js_exec`. The model calls every tool directly, whatever its
`exposure`, and the runtime's part of the system prompt covers only the tools
it has, with nothing about code. With `fileTools: false` as well and no tools of
any source, it has no tools at all (not even `present_file`), and the system
prompt is your instructions plus a short note on who sent each message: for an
agent that answers in a line, a classifier or a judge, a request goes from about
2,000 input tokens to a few hundred.

```ts
const voice = await agents.upsert("voice-12", { instructions, codeMode: false, fileTools: false });
```

Set it when the agent is made. Changed later by an upsert, the agent's tools
change at once, while a conversation already under way keeps the runtime text
it began with (its prompt's cached prefix).

## Tool search

Code finds tools with `tools.search(query)` (or `tools.search(query, { namespace,
limit })`): the best matches as `{name, description, input}`, most relevant
first (20 by default, at most 128). `tools.namespaces()` lists the sources with
their tool counts. Only tool names enter the sandbox, so a catalog of thousands
of tools costs a script nothing until it asks. Ranking is by keywords, and, on
the hosted runtime, also by meaning (embeddings, then a model that drops tools
that cannot do what is asked); searches ranked by meaning are billed at cost.

## Files in tool calls

Tools of a definition's sources take and return files without their bytes
passing through the model. The model names a file by its path, as
`{"$file": "/workspace/report.pdf"}`, and the runtime sends it the way the
tool's schema asks.

### Marking a parameter

A string parameter takes a file when it is marked as MCP's file inputs proposal
(SEP-2631, a draft) marks one:

```json
{"type": "object", "properties": {
  "attachment": {"type": "string", "format": "uri",
    "x-mcp-file": {"accept": ["application/pdf", "image/*"], "maxSize": 10485760, "transferModes": ["url", "inline"]}},
  "site": {"type": "string", "format": "uri", "x-mcp-file": {}, "x-camelrun-directory": true}
}}
```

- `accept`: the MIME types it takes (`image/*` and `*/*` work). Others are a
  tool error.
- `maxSize`: the most bytes it takes. A larger file is a tool error.
- `transferModes`: `url` (the default), `inline`, or both.
- `x-camelrun-directory: true`: the parameter takes a directory.

Unmarked parameters take files too, as before: a base64 field
(`contentEncoding: base64`, OpenAPI's `format: byte` or `binary`) gets the
content (up to 4 MiB), and a `format: uri` field, or one named like a URL
(`source_url`), gets a URL. An OpenAPI multipart or binary body streams the
file. The model sees `{"$file": path}` offered beside the field, with what the
tool takes.

### What the tool receives

- **A URL**, `https://<runtime>/v1/files/<token>/<name>`. It answers `GET`
  (with `Range`) with the file, and nothing else.
- **Inline**, when `transferModes` has `inline` and the file is at most 4 MiB:
  a `data:<type>;base64,…` URI. With `inline` alone, a larger file is a tool
  error.
- **A directory**: the URL of a manifest:

```json
{"snapshot": "snap_…", "root": "/workspace/site",
 "files": [{"path": "index.html", "uri": "https://…/v1/files/…/index.html", "name": "index.html",
            "mimeType": "text/html", "size": 1840, "digest": {"algorithm": "sha-256", "value": "9f86d0…"}}],
 "archive": {"uri": "https://…/v1/files/…/site.tar.gz", "mimeType": "application/gzip"}}
```

  Each file has its own URL, and `archive` is a tar.gz of them all, with paths
  relative to the directory. A directory has at most 1,000 files and 256 MiB.

An MCP call also carries `_meta["camelrun/files"]`: each file sent as a URI,
by its argument's JSON pointer, as SEP-2631 describes a file:

```json
{"/attachment": {"uri": "https://…", "name": "report.pdf", "mimeType": "application/pdf",
                 "size": 48213, "digest": {"algorithm": "sha-256", "value": "e3b0c4…"}}}
```

`digest` is the sha-256 of the bytes, in hex; files over 64 MiB have none.
OpenAPI calls have no `_meta`.

### URL lifetime, binding and versions

- A URL lasts 5 minutes: fetch the file while the call runs.
- It is bound to one call. Its token names the tenant, the agent, the call (its
  idempotency key), the tool and the file.
- A file's URL serves the version the call named. Once the file changes, it
  answers 410 ("changed since the call"), so a tool never gets a mix of
  versions.
- A directory is sent as a snapshot made for the call. Its files read as they
  were then, whatever the agent writes meanwhile. The snapshot is deleted after
  the call, once its URLs have expired; it is not listed with the volume's
  snapshots and does not count toward them.
- An expired or altered URL answers 403.

### Verifying a URL

A tool can check that a URL came from camelRun, for the agent it expects:

```ts
import { verifyFileUrl } from "@camelai/run/server";

const file = await verifyFileUrl(args.attachment, { runtime: "https://run.camelai.com", tenant: "acme", agent: expectedAgent });
// { tenant, agent, call, tool, volume, path, agentPath, kind: "file" | "manifest" | "archive", version | snapshot, exp }
```

```python
from camelai_run import verify_file_url

file = await verify_file_url(arguments["attachment"], runtime="https://run.camelai.com", tenant="acme")
```

It checks that the URL is at the runtime and that its token is signed by the
runtime's keys (`/.well-known/jwks.json`, the identity tokens' keys) for files,
and has not expired. `camelai_run.sync.verify_file_url` is the synchronous one;
`testRuntime().fileUrl()` (Python `TestRuntime().file_url()`) makes one to test
with.

### Which sources get files

A source's `fileArguments` says whether it is sent files: `"on"` or `"off"`.

- By default it is on for sources with `auth: {"type": "runtime"}`: your own
  servers, which check who is calling.
- It is off for every other source. Its tools are not offered `{"$file": …}`,
  a `$file` argument is a tool error, and nothing about files reaches it. A
  model talked into it could otherwise send any file the agent can read to
  another party's server.
- Set `"fileArguments": "on"` on a third-party server you trust with the
  agent's files.

```json
{"mcpServers": [{"name": "docs", "url": "https://mcp.example.com/mcp", "fileArguments": "on"}]}
```

### Files a tool returns

- Images, audio, blobs and long text resources are saved to
  `/workspace/tool-outputs/<tool>/<call>/<name>`, and the model gets a
  reference to each (shown natively when it is an image or PDF it can view).
  So are binary OpenAPI responses and `web_fetch` downloads.
- For sources with `fileArguments` on, a `resource_link` to an `https:` or
  `data:` URI is saved too. It is fetched through the outbound guard, at most
  64 MiB. The transcript keeps the file's path, never the URL.
- One call may save 64 MiB, and one run 256 MiB.

## Outbound calls

Every request to a URL you or the model chose (MCP servers, OpenAPI specs and
APIs, `web_fetch`) goes through one guard: `https://` only, no credentials in
URLs, and no private, loopback, link-local or otherwise internal address, checked
on every connection (so DNS rebinding cannot slip past). MCP servers and API
calls get no redirects; where redirects are followed (`web_fetch`, spec
downloads) each hop is checked, and credentials never go to another origin.

A self-hosted runtime's operator can allow exact origins of their own
(`AGENT_OUTBOUND_ALLOW_ORIGINS`) for MCP servers, APIs and model providers on
their network; `web_fetch` never reaches them.

---

<!-- https://run.camelai.com/docs/guides/human-input.md -->

# Human input

A run can stop and wait for a person: the model asks a question, a tool needs
approval before it runs, or a tool asks for a form or a setup step. The call that
needs the person stays open and the run **suspends**: it ends with
`status: "input_required"` and the `inputs` it waits on, the agent goes to sleep
(nothing is billed while it waits), and once the last input is answered, minutes
or days later and from any process, the turn resumes. The model sees an ordinary
tool call and result, told who answered and how long it took.

```ts
let run = await agent.run("Delete the staging database", { user: "alice" });
while (run.status === "input_required") {
  const input = run.inputs[0];
  console.log(input.kind, input.message);          // "approval", "Allow db__drop to run?"
  run = await input.answer(true, { from: "alice" }); // resolves with the resumed run
}
console.log(run.text);
```

```python
run = await agent.run("Delete the staging database", user="alice")
while run.status == "input_required":
    run = await run.inputs[0].answer(True, from_="alice")
print(run.text)
```

## Where inputs come from

- **Approvals.** A tool with `needsApproval: true` (`@tool(needs_approval=True)`),
  or a function of its arguments deciding per call, is approved before each call.
  A definition's sources take an approval policy:
  `"approval": {"default": "never" | "always" | "destructive", "tools": {"delete_repo": "always"}}`
  (`destructive`: MCP tools annotated `destructiveHint`, OpenAPI operations other
  than GET, HEAD and OPTIONS; OpenAPI also takes `"methods": ["POST", "DELETE"]`).
  The person sees the real call: the tool, its source and its arguments. An
  approved call runs with exactly those arguments, and carries the approval
  (`context.identity.approval`), so a tool can require it; a declined call never
  runs.
- **Questions.** The `ask_user` built-in (`"builtins": ["ask_user"]` on the
  agent or its definition) lets the model ask 1 to 4 multiple-choice questions, with free text
  allowed where it says so.
- **The tool itself.** `context.confirm(message)`, `context.ask(message,
  schema)` (a flat form) and `context.requireUrl(url, message)` (a step on an
  https page: connect an account, sign something). An ask ends the call; once the
  person answers, the runtime calls the tool again with the same arguments and the
  ask returns the answer. **Everything before an ask runs again then**, so ask
  first and act after, and key side effects by `context.idempotencyKey`, which is
  the same on both calls.

```ts
const deleteApp = tool({
  description: "Delete an app", input: schema.Object({ app: schema.String() }),
  execute: async ({ app }, context) => {
    if (!await context.confirm(`Delete ${app}? Its URL stops working.`)) return { cancelled: true };
    return apps.delete(app, { idempotencyKey: context.idempotencyKey });
  },
});
```

Code in `js_exec` cannot wait for days: a call from code that would ask fails
with "needs the user's input: call it directly". Tools that ask are therefore
always offered to the model directly.

## Answering

`input.answer(value, { from })` takes a plain value by the input's `kind`:

| kind | value |
| --- | --- |
| `approval` | `true` to approve, `false` to decline |
| `question` | the chosen option's label (or labels, or free text where allowed); for several questions, `{ "<question>": answer, … }` |
| `form` | the fields, as an object (checked against the form's schema); a confirmation (`context.confirm`, a form without fields): `true` or `false` |
| `url` | `true` once the person has done what the page asks, else `false` |

`input.decline()` declines any input. Answering resolves with the resumed run, or,
when the run waits on other inputs too, with the run still `input_required`
listing those. Answering the same way twice is safe; a different answer to an
input already settled is a 409 that says how it settled.

Inputs outlive your process: answer later from anywhere.

- `agent.pendingInputs()` (Python `pending_inputs()`) lists an agent's waiting
  inputs, each with `answer()`.
- `agents.runtime.inbox("pending")` lists the inputs waiting across all your
  agents, for an approvals queue.
- Over REST: `GET /v1/agents/:id/inputs?state=pending`, and `POST
  /v1/agents/:id/inputs/:inputId {action: "accept" | "decline" | "cancel",
  content?, from?}`. A question's `content` is `{answers: {"<question>":
  "<label>" | ["<label>"] | "<own words>"}}`, a form's its fields. It answers
  `{input, request}`, where `request` is the resumed run (null until the last
  input is answered): poll it like a prompt.
- `onInput` (`on_input`) on `upsert` hears each input as it is asked: return an
  answer to give it at once, or nothing to answer later.
- An MCP client talking to the agent through its [MCP endpoint](https://run.camelai.com/docs/guides/mcp-server.md)
  is asked through elicitation, when it supports it.
- The agent's events include `input_required` and `input_resolved`, and
  [webhooks](https://run.camelai.com/docs/guides/webhooks.md) `input.requested` and `input.resolved`.

## Who may answer

By default the person whose message started the turn (the run's `user`, or its
`actor`) and the definition's `humanInput.approvers`. An answer must say who is
answering (`from`) whenever the input names who may (`responders.audience`, or
the definition has approvers): the SDKs refuse to send one without it, and the
runtime refuses it with 400; a `from` who may not answer is a 403. The model has
no way to answer.

## Waiting, and giving up

- A new message to the agent supersedes its waiting inputs: their calls close
  with "Not answered: the user sent a new message instead", then the message runs.
- `agent.abort()` cancels them.
- Inputs expire after `humanInput.expiresInSeconds` (7 days by default, at most
  30). Expired and cancelled inputs close their calls and the turn without
  calling the model, unless `humanInput.onExpire` is `resume`.

```json
{"name": "Ops", "builtins": ["ask_user"], "humanInput": {"expiresInSeconds": 86400, "approvers": ["slack:U0123"]},
 "mcpServers": [{"name": "github", "url": "…", "approval": {"tools": {"delete_repo": "always"}}}]}
```

## In a channel

In Slack, Telegram or Discord, a suspended turn's reply ends with its first input
as text: a question's numbered options, the call to approve, the URL, a
confirmation. The next message from someone allowed to answer, if it fits (an
option's number or label, `approve`/`yes` or `deny`/`no`, `done`), is the answer;
anything else is a new message. See [Channels](https://run.camelai.com/docs/guides/channels.md).

---

<!-- https://run.camelai.com/docs/guides/stateless-runs.md -->

# Stateless runs

A stateless run is one call: a configuration and an input in, the result out.
Nothing carries over between runs and no agent is kept, so fifty runs with the
same configuration are fifty independent answers, not one conversation.

```ts
import { Agents } from "@camelai/run";
import { z } from "zod";

const agents = new Agents(); // CAMELAI_API_KEY
const run = await agents.run({
  instructions: "You review release plans. Vote yes or no, with one reason.",
  input: "Ship the billing migration on Friday afternoon?",
  output: z.object({ vote: z.enum(["yes", "no"]), reason: z.string() }),
});
run.output; // { vote: "no", reason: "…" }
```

```python
from camelai_run import Agents
from pydantic import BaseModel
from typing import Literal

class Vote(BaseModel):
    vote: Literal["yes", "no"]
    reason: str

async with Agents() as agents:
    run = await agents.run("Ship the billing migration on Friday afternoon?",
                           instructions="You review release plans. Vote yes or no, with one reason.", output=Vote)
    print(run.output.vote)
```

```bash
curl -s https://run.camelai.com/v1/runs -H "Authorization: Bearer $CAMELAI_API_KEY" \
  -H "Content-Type: application/json" -d '{
    "systemPrompt": "You review release plans. Vote yes or no, with one reason.",
    "input": "Ship the billing migration on Friday afternoon?",
    "wait": true
  }'
# 200 with the ended run, or 202 with it still running: GET /v1/runs/<id>?wait=25 for the rest.
```

## Runs or agents

| | Stateless run (`POST /v1/runs`) | Agent (`POST /v1/agents`, `agents.upsert`) |
| --- | --- | --- |
| History | None: each run starts empty | Kept: each run continues the conversation |
| Lifetime | Its result is kept for a retention window (a day by default), then deleted | Until you delete it (keyed) |
| Tools | Built-ins (`web_fetch`, `web_search`, `delegate`), its own MCP servers, a definition's MCP servers and OpenAPI specs, `js_exec` | Also tools served by your process (`tools`), schedules and human input |
| Listed in `GET /v1/agents` | No | Yes |
| Use it for | Classify, extract, vote, judge, summarize: one answer per input | Chats, assistants, anything that remembers |

Use a run when the answer depends only on what you send. Use an agent when it
should remember, wait on a person, or call tools that run in your process.

## What a run takes

The fields an agent takes, plus the input:

- `input`: a string, or parts: `[{ "type": "text", "text": "…" }, { "type": "file", "name": "a.pdf", "data": "<base64>" }]`.
  Files (at most 4 MiB in all) give the run a workspace volume to hold them.
- `definition`: a definition's key or id, so the configuration is not sent each
  time. Fields given alongside override it, as for an agent.
- `model`, `systemPrompt`, `systemPromptAppend`, `thinkingLevel`, `maxOutputTokens`,
  `temperature` (see [Output length and temperature](https://run.camelai.com/docs/guides/models-and-keys.md#output-length-and-temperature)), `builtins`
  (`web_fetch`, `web_search`, `delegate`, `generate_image`: [generate_image](https://run.camelai.com/docs/guides/images.md#in-an-agent) gives the run a
  workspace for its images), `delegate`, `keyScope`, `modelHeaders`,
  `runLimits`, `subject`, `context`.
- `mcpServers`: MCP servers of its own, as an agent's: no credentials, only
  `"auth": {"type": "runtime"}` (identity tokens) or none. See
  [An agent's own MCP servers](https://run.camelai.com/docs/guides/tools.md#an-agents-own-mcp-servers).
- `output`: a schema for a structured answer (see [Structured output](https://run.camelai.com/docs/guides/structured-output.md)).
- `spendLimit`: the run's budget in USD.
- `fileTools: true`: a workspace and file tools. Without files or this, a run has
  no volume at all.
- `codeMode`: whether the model gets `js_exec`. A run with no tools at all (no
  definition, `builtins`, `delegate`, `mcpServers`, files or mounts) gets neither `js_exec` nor
  file tools, so its model sees only your instructions and the input: right for a
  classifier or a vote. A run with tools keeps `js_exec`. Set `codeMode` (or
  `fileTools`) to have it otherwise; what you set wins.
- `actor`, `from`, `metadata`: who sent it, and your own data, kept on the run.
- `retentionSeconds`: how long its result, events and messages are kept once it
  ends (60 to 604800; the runtime's default is a day).
- `wait`: `true` (up to 60 seconds) or a number of seconds to wait for the end.

The SDKs take the same configuration with their usual names (`instructions`,
`output` as zod, TypeBox or pydantic).

## Following a run

| | |
| --- | --- |
| `GET /v1/runs/{id}` | The run: `status` (`running`, `completed`, `failed`, `input_required`), `text`, `output`, `error`, `usage`, `toolCalls`, `toolErrors`. `?wait=25` waits for its end first |
| `GET /v1/runs/{id}/events` | Its events as server-sent events, ending with its `response`. Reconnect with `Last-Event-ID` and the stream picks up after it |
| `GET /v1/runs/{id}/messages` | Its messages: the input, the model's turns, tool results |
| `POST /v1/runs/{id}/abort` | Stop it: it ends `failed`, code `aborted` |
| `DELETE /v1/runs/{id}` | Delete it now, before its retention ends |

```ts
const stream = await agents.runs.stream({ instructions: "…", input: "…" });
for await (const part of stream) if (part.type === "text") process.stdout.write(part.text);
const run = await stream.result();

await agents.runs.get(run.id);       // as it ended
await agents.runs.abort(run.id);     // a running one
await agents.runs.messages(run.id);  // within its retention
```

**Events are replayable only for a short while.** A run's event stream replays
what it holds after `Last-Event-ID` while the run is going and for about five
minutes after it ends (while its node still holds it). After that, `/events`
answers with the run's `response` frame alone, and the record of what happened is
`/messages` (and `GET /v1/runs/{id}`), kept for the whole retention window.

## Idempotency

Send an `Idempotency-Key` (the SDKs' `idempotencyKey`, `idempotency_key`) and
the same key with the same body is the same run, while it is kept: a retry after
a lost response never starts a second one. The same key with another body is a
409 `IDEMPOTENCY_CONFLICT`. Without a key every create is a new run (the SDKs
make one up per call, so their own retries are safe).

## Durability

A run is as durable as an agent's run, within itself. If the node running it
dies, or a deploy retires it, the run goes on on another node from its last
completed step:

- A node that retires (a deploy) lets the step in flight finish, then hands the
  run to another node at that step boundary. Nothing is lost and nothing runs
  twice (`handoffs` lists them).
- A node that dies: another node resumes the run from its transcript, at most
  twice (`resumes`). A tool call that completed is not made again. A model call
  that was in flight is simply asked again. A tool call that was in flight when
  the node died has an unknown outcome, which the model is told, as for an agent.
  As for an agent, a run resumed after its node died reports in `usage` and
  `toolCalls` only what happened on the node that finished it; its messages have
  every step.
- A model that stalls (no first token within `runLimits.firstTokenSeconds`, or
  silent mid-answer for `runLimits.idleSeconds`) is retried, then the run ends
  `failed` with code `model_stream_stalled`: it never hangs.

## Limits and billing

A run counts as an agent's run does: against runs per minute, and against busy
agents while it runs (concurrency is what a run costs). It is not an agent create,
so creating runs does not count against agent creates, and it takes no place among
your agents. Model usage, agent time and web tools are billed as for agents. The
run's id is the `requestId` in usage webhooks and traces.

A run that cannot start (busy agents at their limit, runs per minute, no credit)
is refused with the same errors as an agent's prompt, and leaves nothing behind.
Busy agents and runs per minute are checked before anything is made, so a burst
past either is turned away cheaply (429 `BUSY_AGENT_LIMIT` or `RATE_LIMITED`, with
`Retry-After`).

## Notes

- **A run cannot wait on people.** `ask_user` and `schedule` are not among its
  built-ins. A tool that asks for approval or input (a definition's approval
  policy, an MCP server's elicitation) ends the run with status
  `input_required`, and for a run that is final: there is no way to answer it
  and resume. Use an agent for work that needs a person's go-ahead.
- **Servers with credentials, and OpenAPI specs, come through a definition.**
  A run's own `mcpServers` take no token or headers; name a definition with
  `definition` for those. Tools served by your process
  (`tools`, an attached MCP server) need an agent: a run has no process connected.
  Serve them over HTTP (`serveTools`) and name them in a definition instead.
- The CLI runs one with `camelrun run --stateless "…" [--definition key]`.

---

<!-- https://run.camelai.com/docs/guides/structured-output.md -->

# Structured output

Give a run an output schema and its answer comes back as an object in that
shape, as `run.output`. The schema can be zod, TypeBox or plain JSON Schema, or a
pydantic model in Python. The agent works as usual (tools, code, files) and then
answers by calling a `final_output` tool whose arguments are your schema. The
system prompt tells it to answer that way. The runtime checks the call against
the schema. If it does not fit, the model gets the call back with what is wrong
and tries again. Once it fits, the run ends.

```ts
import { z } from "zod";

const Triage = z.object({
  category: z.enum(["bug", "billing", "question"]),
  priority: z.number().int().min(1).max(4),
  summary: z.string(),
});

const run = await agent.run("Triage ticket 123", { output: Triage });
run.output; // { category: "bug", priority: 2, summary: "…" }, typed z.infer<typeof Triage>
```

```python
# pip install "camelai-run[pydantic]"
from pydantic import BaseModel
from typing import Literal

class Triage(BaseModel):
    category: Literal["bug", "billing", "question"]
    priority: int
    summary: str

run = await agent.run("Triage ticket 123", output=Triage)
run.output  # Triage(category='bug', priority=2, summary='…')
```

```bash
curl -s https://run.camelai.com/v1/agents/$AGENT/prompt -H "Authorization: Bearer $CAMELAI_API_KEY" \
  -H "Content-Type: application/json" -d '{
    "text": "Triage ticket 123",
    "output": { "schema": { "type": "object",
      "properties": { "category": { "enum": ["bug", "billing", "question"] }, "priority": { "type": "integer" }, "summary": { "type": "string" } },
      "required": ["category", "priority", "summary"] } }
  }'
# Poll GET /v1/agents/$AGENT/requests/<id>: once completed, outcome.result.output is the object.
```

## Schemas

- **The schema must describe an object** (`type: "object"`), at most 64 KB as
  JSON. For a list or a single value, wrap it: `z.object({ items: z.array(…) })`.
- **zod** needs version 4.2 or later. The SDK sends zod's JSON Schema
  (`~standard.jsonSchema`) and then parses the answer with zod, so refinements
  and transforms apply. **TypeBox** (`schema.Object(…)`, exported by the SDK)
  and plain JSON Schema are sent as they are. Any Standard Schema library that
  can produce JSON Schema also works.
- **pydantic** models are sent as `model_json_schema()` (nested models as
  `$defs`) and parsed with `model_validate`, so validators apply.
- The runtime checks what the JSON Schema can express. A check that only zod or
  pydantic can run, such as a refinement or a validator, happens in the SDK. If it
  fails, the run fails with `output_invalid`.

## How the run ends

| Outcome | What you get |
| --- | --- |
| The model called `final_output` with arguments that fit | `status: "completed"`, `output` set, and `text` with anything the model said alongside |
| The model answered in prose | That answer is discarded and the model is asked once more, with a reminder, and with `final_output` forced where the provider allows it (see [Forcing the tool](https://run.camelai.com/docs/guides/structured-output.md#forcing-the-tool)). If it answers in prose again: `status: "failed"`, `error.code: "output_missing"`, and `text` with what it said |
| The answer fit the JSON Schema but failed your zod or pydantic schema | `status: "failed"`, `error.code: "output_invalid"` |
| It waits on a person (an approval, a question) | `input_required`. Answering resumes the run, which still ends with `output` |

Calls whose arguments do not fit are not failures. The model sees them as tool
errors and calls again.

## Forcing the tool

Instructions that ask for a plain-text reply ("answer in one line") can win over
the schema: a model then answers in prose and never calls `final_output`. So the
runtime makes the call with the provider's `tool_choice`:

- When `final_output` is the agent's only tool (an agent with `codeMode: false`,
  `fileTools: false` and no tools of its own), every request of the run forces
  it, from the first: the model cannot answer in prose.
- When it has other tools, the first requests leave the choice to the model, so
  it can use them; once it answers in prose, the reminder's request forces
  `final_output`.

| Provider API | Forced with |
| --- | --- |
| Anthropic, and Anthropic models on Bedrock | `{type: "tool", name: "final_output"}`, unless the agent's `thinkingLevel` is on: Anthropic refuses a forced tool with extended thinking, so those get the reminder only |
| OpenAI Responses, Azure | `{type: "function", name: "final_output"}` |
| Chat Completions (OpenRouter, DeepSeek, Z.ai, Workers AI, your own providers), Mistral | `{type: "function", function: {name: "final_output"}}` |
| Google, OpenAI Codex | `any` / `required`, only when `final_output` is the only tool |

A provider or model that refuses the parameter (some hosts of open models, and
Claude models that take no forced tool) fails the request: the runtime takes
that failure back and asks again without forcing, for the rest of the run, so it
costs one refused request. A run forces at most three requests, so a model
whose calls never fit the schema still ends its turn.

## Notes

- **Per run.** `output` belongs to the prompt that starts a turn. It cannot be
  combined with `whileRunning: "steer"`. Each `run()` with an `output` schema
  declares `final_output` with that schema. The tool stays declared until a run
  without `output`, so a series of runs with the same schema keeps the model's
  tool set unchanged and its prompt cache intact. Switching schemas, or
  switching between structured and plain runs, changes the tool set once.
- **History.** The `final_output` call and its result are ordinary messages in
  the agent's history. Later turns can refer back to the answer.
- **Durable.** A structured run that is resumed on another node still ends with
  `output`.
- **An agent with its own tool named `final_output`** cannot take an output
  schema.

---

<!-- https://run.camelai.com/docs/frontend.md -->

# Frontend guide

Put a streaming chat with an agent in your app: your users talk to their own agents, the agent's
replies stream in as they are written, its tool calls show as cards (or as your own components), and
its questions and approvals are answered in place.

- [Start a new app](https://run.camelai.com/docs/frontend.md#start-a-new-app)
- [Add it to an app you have](https://run.camelai.com/docs/frontend.md#add-it-to-an-app-you-have): the route, then the UI
- [How it stays secure](https://run.camelai.com/docs/frontend.md#how-it-stays-secure)
- [The UI, four ways](https://run.camelai.com/docs/frontend.md#the-ui-four-ways): `<AgentChat>`, hooks, shadcn, AI SDK
- [Tools and generative UI](https://run.camelai.com/docs/frontend.md#tools-and-generative-ui)
- [Questions, approvals and files](https://run.camelai.com/docs/frontend.md#questions-approvals-and-files)
- [Conversations (threads)](https://run.camelai.com/docs/frontend.md#conversations-threads)
- [Theming and accessibility](https://run.camelai.com/docs/frontend.md#theming-and-accessibility)
- [Other frameworks](https://run.camelai.com/docs/frontend.md#other-frameworks)
- [Troubleshooting](https://run.camelai.com/docs/frontend.md#troubleshooting)

## Start a new app

```sh
export CAMELAI_API_KEY=art_...   # https://run.camelai.com/console/tokens
npm create @camelai/run-app my-app
cd my-app && npm run dev
```

It writes the key from `CAMELAI_API_KEY` to the app's `.env.local`.

A Next.js app with the chat, its route, a tool drawn by its own component, and a demo sign-in to
replace with yours. Examples with Vite (React, Vue, Svelte, Solid), the read proxy and the AI SDK are in
[examples/frontend](https://github.com/qaml-ai/run/blob/main/examples/frontend). Get an API key in the [console](https://run.camelai.com/console).

## Add it to an app you have

```sh
npm install @camelai/run @camelai/run-react
```

### 1. The route

One POST route on your server does everything the browser needs: it checks who the user is (your
own sign-in), gives their browser a short-lived token to read their agent, and sends their messages
and answers. Your API key never leaves the server.

```ts
// app/api/agent/route.ts (Next.js App Router)
import { createAgentHandler } from "@camelai/run/server";

export const POST = createAgentHandler({
  // CAMELAI_API_KEY from the environment, or apiKey: "…"
  authorize: async request => {
    const user = await getUser(request);          // your session check
    return user ? { userId: user.id, name: user.name } : null;   // null: 401
  },
  agent: {
    instructions: "You help customers with their orders.",
    model: "anthropic/claude-sonnet-5-5",           // optional; any model from GET /v1/models
  },
});
```

The same handler is a standard `fetch` handler everywhere:

```ts
// Hono
app.post("/api/agent", c => handler(c.req.raw));

// Cloudflare Workers, Bun, Deno
export default { fetch: handler };

// Express or node:http
import { nodeListener } from "@camelai/run/node";
app.post("/api/agent", nodeListener(handler));    // before any body parser for this route
```

`createAgentHandler` options:

| Option | |
| --- | --- |
| `authorize(request, { thread, action })` | Required. Return `{ userId, name?, agentKey? }` or `null`. |
| `agent` | How the user's agent is made: `{ instructions, model, tools, definition, context, spendLimit, … }`, or a function of the user. |
| `onSend({ auth, text, data, request })` | Before each message: return `{ text?, metadata? }`, or `throw new Response(…)` to refuse it (quotas, moderation). |
| `browserToken` | `{ ttlSeconds, events, redact, scopes, url }` for the tokens it mints (default 15 minutes, no provider cost). `scopes: ["events", "state", "history", "inputs", "children"]` adds `children`, to read the agent's background sub-agents too. |
| `allowedOrigins` | Other origins whose pages may call the route (with CORS). |
| `linkAnyMountedPath` | `true`: file links for any path in the agent's mounts, so the boundary is what the agent can read. Default: only files it presented, or in its own workspace volume. |
| `proxy` | `true`: browsers read their agent through this route too, and only ever talk to your origin (see [Reading through your route](https://run.camelai.com/docs/frontend.md#reading-through-your-route-proxy)). Default `false`. |
| `apiKey`, `url` | Default `CAMELAI_API_KEY`, and `CAMELAI_BASE_URL` or https://run.camelai.com. |

### 2. The UI

```tsx
"use client";
import { AgentChat } from "@camelai/run-react/ui";
import "@camelai/run-react/styles.css";

export default function Support() {
  return <AgentChat endpoint="/api/agent" suggestions={["Where is my order?"]} />;
}
```

`<AgentChat>` fills its container: give that a height.

### Reading through your route (proxy)

By default the browser reads its agent's stream straight from the runtime, with the browser token
your route gave it: the stream never passes through your server. With `proxy: true`, your route
passes those reads through as well (the event stream, its long-poll fallback, history, state and
inputs), and file downloads (`link` answers a URL under your route), so the browser only ever talks
to your origin: nothing to allow in a Content Security Policy, no runtime URL in the page, and the
runtime itself may be private (see [Self-hosting](https://run.camelai.com/docs/operations/self-host.md#networking)). The chat
needs no other change.

```ts
// app/api/agent/[[...path]]/route.ts: the route and every path under it
const handler = createAgentHandler({ authorize, agent, proxy: true });
export const GET = handler;
export const POST = handler;
```

Hono: `app.all("/api/agent/*", c => handler(c.req.raw))` as well as `/api/agent`. Express:
`app.use("/api/agent", nodeListener(handler))`. Workers: the same `fetch` handler.

Each read is checked with `authorize` like everything else and must name the user's own agent; the
route adds a browser token it keeps on the server (the browser never sees one), and streams each
chunk as it arrives. A browser that goes away cancels the read upstream.

The cost: every open chat holds a request on your server for as long as it is open. Serverless
functions cut a request at their time limit (on Vercel, the function's maximum duration); the chat
then reconnects from where it was, and after two streams that deliver nothing it switches to long
polls of at most 25 seconds, which fit any limit. Direct reads keep that load off your servers, so
they stay the default: use the proxy when policy requires a single origin.

### The route's protocol

The chat talks to your route in plain JSON, so anything that can POST can use it: a native app, a
test, a script or curl. Each request is `POST <route>` with `Content-Type: application/json`, the
cookie or header your `authorize` reads, and a body `{ action, thread?, … }`. `thread` (1 to 200
characters, or null) picks the conversation; with the user, it picks the agent
(`agentKeyFor(userId, thread)`) unless `authorize` names one.

| `action` | Body | Answer |
| --- | --- | --- |
| `token` | | `{ token, expiresAt, agentId, url }`: a browser token that reads the agent (`/v1/agents/:id/{events,history,state,inputs}` at `url`). With `proxy: true`, `{ proxy: true, agentId, token: "", expiresAt }`: read under the route instead. |
| `send` | `{ text, clientId, data?, whileRunning?, wait? }` | `{ requestId, state, steeredInto? }`, as soon as the message is accepted. `clientId` (8 to 80 letters, digits, `_` and `-`) is the message's id: sending the same one again sends nothing twice. `whileRunning` is `queue` (the default) or `steer`. `data` reaches only your `onSend`. With `wait`, see below. |
| `wait` | `{ requestId, wait? }` | A message sent before, by its `clientId`, as `send` with `wait` answers. Sends nothing. |
| `answer` | `{ inputId, answer: { action: "accept" \| "decline" \| "cancel", content? } }` | `{ input, request }`, as `POST /v1/agents/:id/inputs/:inputId` answers. The answer is the user's (`from`). |
| `stop` | | `{ aborted: true }`: the agent's running turn is stopped. |
| `link` | `{ path }` | `{ url, expiresAt }`: a download link for a file the agent presented or that is in its own workspace (any mounted path with `linkAnyMountedPath`). |

With `proxy: true` the route also takes `GET <route>[/threads/:thread]/v1/agents/:id/{events,history,state,inputs}`
(the runtime's read routes, for the user's own agent only) and the file links that `link` gives.

Errors are `{ error: { code, message } }` with the HTTP status: 401 `unauthorized` (`authorize`
returned null), 400 `invalid_request` or `invalid_json` (the message names the field), 403
`forbidden_origin` (another site; see `allowedOrigins`), 405, 413 `too_large`, 415
`unsupported_media_type`, and the runtime's own errors passed on with their status and code
(`INSUFFICIENT_CREDIT`, `not_found`, …; 502 `runtime_unreachable` when it cannot be reached). A
`Response` that your `onSend` throws is answered as it is.

#### Waiting for the reply

The chat follows the agent's stream, so it sends without waiting. A caller without the stream
passes `wait`: `true` (25 seconds) or whole seconds from 1 to 25. The route answers once the run
ends, with `state: "completed"`, `status` (`completed`, `input_required` or `failed`) and the run's
`reply` (its final message's text), `error` (why it failed) or `stopped` (`input_required`, `spend_limit` or `turn_limit`). A run still going when the wait is over
answers `state: "running"`: ask again with `wait`.

```sh
curl -s https://app.example.com/api/agent -H "Cookie: session=…" -H "Content-Type: application/json" \
  -d '{"action":"send","text":"Where is my order?","clientId":"msg_0001","wait":true}'
# {"requestId":"msg_0001","state":"completed","status":"completed","reply":"It shipped yesterday…"}
curl -s https://app.example.com/api/agent -H "Cookie: session=…" -H "Content-Type: application/json" \
  -d '{"action":"wait","requestId":"msg_0001","wait":25}'
```

Each wait holds a request on your server: keep `wait` under your platform's limit (serverless
functions cut requests at theirs). Without the handler, the runtime's
`GET /v1/agents/:id/requests/:requestId?wait=25` does the same with your API key.

## How it stays secure

- **The API key stays on your server.** The browser gets a *browser token* for one agent: it reads
  that agent's events, history, state and inputs, for 15 minutes, and nothing else. It cannot send,
  answer, stop, or read another agent. The chat renews it through your route before it expires.
- **Every write goes through your route**, after your `authorize`. The browser never names an agent:
  the route picks the user's agent from what `authorize` returned (by default one per user and
  thread, `agentKeyFor(userId, thread)`, a hash that no user's thread name can collide with). An
  agent's `subject` is its user and cannot change afterwards.
- **Messages and answers are sent as the user** (`from: { id: userId, name }`), never as whatever the
  browser claims; the runtime checks answers against who may answer. The browser's own data for a
  message (`send(text, { data })`) reaches the agent only if your `onSend` passes it on.
- **Sends are idempotent**: each carries the id the browser gave its message, so a retry never sends
  twice.
- **Cross-site requests are refused**: the route takes only `application/json` (which a form on
  another site cannot post) and refuses `Sec-Fetch-Site: cross-site` unless you list the origin.
- **Rendering is safe**: markdown is rendered with elements, never HTML; links are only http(s) and
  mailto; images the model links are shown as links unless you set `allowImages` (loading an image
  a model chose can leak data to its server).

## The UI, four ways

**`<AgentChat>`**, prebuilt (`@camelai/run-react/ui`): messages, streaming markdown, tool
cards, questions, files, a composer with Stop, scrolling that follows the reply. Replace any part:

```tsx
<AgentChat
  endpoint="/api/agent"
  tools={{ get_weather: WeatherCard }}                 // your component per tool
  components={{ Markdown: MyMarkdown, EmptyState: Welcome }}
  labels={{ placeholder: "Ask about your order" }}     // every string, for translation
  theme="system"                                       // or "light" / "dark"
/>
```

**Hooks**, for your own UI (`@camelai/run-react`):

```tsx
<AgentProvider endpoint="/api/agent">
  <MyChat />
</AgentProvider>

function MyChat() {
  const messages = useMessages();                  // user bubbles and assistant turns, as typed parts
  const send = useSend();
  const { status, isRunning, error, stop } = useAgentStatus();
  const { inputs, answer } = useInputs();
  const { hasOlder, loadOlder } = useLoadOlder();
  return messages.map(message => <Row key={message.id} message={message} />);
}
```

A message is `{ id, role: "user", text, parts, status: "sending" | "sent" | "failed" }` or
`{ id, role: "assistant", parts, streaming }`; parts are `text`, `reasoning`, `tool` (`name`, `args`
while they stream, `state`, `result`, `progress`, `input`) and `file`. A message that did not change
is the same object from one render to the next, and a sent message keeps its id when the agent's
copy arrives, so rows keyed by `id` never remount.

**shadcn**: copy the chat into your project, in your theme, and own the code:

```sh
npx shadcn add https://run.camelai.com/r/agent-chat.json
npx shadcn add https://run.camelai.com/r/agent-route.json   # the Next.js route
```

**AI SDK**: use `useChat` (and AI Elements) with the agent:

```tsx
import { useChat } from "@ai-sdk/react";
import { lastAssistantMessageIsCompleteWithApprovalResponses } from "ai";
import { AgentRuntimeChatTransport } from "@camelai/run/ai-sdk";

const transport = useMemo(() => new AgentRuntimeChatTransport({ endpoint: "/api/agent" }), []);
const { messages, setMessages, sendMessage, addToolApprovalResponse, stop } = useChat({
  id: threadId,                        // the route's thread
  transport,
  sendAutomaticallyWhen: lastAssistantMessageIsCompleteWithApprovalResponses,
});
// The conversation so far, from the agent:
useEffect(() => { void transport.loadMessages({ chatId: threadId }).then(setMessages); }, [transport, threadId]);
```

The agent keeps the conversation, so only the new message is sent. Tool calls arrive as
`dynamic-tool` parts, approvals as tool approval requests, other questions as `data-agent-input`
parts (answer with `transport.answer(input, value, { chatId: threadId })`, then `resumeStream()`).

Without React, the store behind all of these is `createAgentChat` from
`@camelai/run/chat`: `subscribe`, `getSnapshot`, `send`, `answer`, `stop`, `loadOlder`.

## Tools and generative UI

Give the agent tools in the route; draw their calls with your own components in the browser.

```ts
// route.ts
import { schema, tool } from "@camelai/run";
agent: {
  tools: {
    get_weather: tool({
      description: "The weather in a city",
      input: schema.Object({ city: schema.String() }),
      execute: async ({ city }, { identity }) => weather.now(city),   // identity.subject is the user
    }),
  },
},
```

```tsx
function WeatherCard({ args, state, result }: ToolRenderProps) {
  if (state === "input_streaming") return <p>Looking up {String(args.city ?? "")}…</p>;
  return <Card data={result?.data} loading={state !== "done"} />;
}
<AgentChat endpoint="/api/agent" tools={{ get_weather: WeatherCard }} />
// or anywhere under the provider: useToolRenderer("get_weather", WeatherCard)
```

A renderer gets `args` (partial while the model writes them), `state` (`input_streaming`, `running`,
`input_required`, `done`, `error`), `result` (`text`, and `data` when it is JSON), `progress`, and,
for a call that waits on the user, its `input` and `answer(value)`.

Tools given in the route run in that server process, so it must keep running (`next dev`,
`next start`, a container, a Node or Bun server). On serverless hosting (Vercel functions,
Workers), serve the tools over HTTP with `serveTools` and name them in a definition:
`agent: { definition: "def_…" }` (see `clients/README.md`, "Serving tools to many users").
`serveTools` checks the runtime's signed identity on every call, and needs your tenant's id
(`GET /v1/me`), so another tenant's agents can never call your tools as your users:

```ts
// app/api/tools/route.ts
import { serveTools } from "@camelai/run/server";
const handler = serveTools(tools, { runtime: "https://run.camelai.com", tenant: process.env.CAMELAI_TENANT! });
export { handler as GET, handler as POST };
```

With `nodeListener` (Express, node:http) behind a proxy that ends TLS, pass `trustProxy: true` only
if that proxy sets `X-Forwarded-Proto` and `X-Forwarded-Host` itself; they are ignored otherwise.

## Questions, approvals and files

When the agent asks (`ask_user`), a tool needs approval (`needsApproval`, or a definition's approval
policy), or a tool asks for a form or a URL step, the run waits, for days if need be. `<AgentChat>`
shows the question on the call that asked, with the choices, a form, or Approve and Deny; the
answer goes through your route as the user, and the run goes on. With hooks:
`useInputs().answer(input, value)`, where `value` is `true`/`false` for an approval, the chosen label
(or labels) for a question, or the fields for a form.

Files the agent hands over (`present_file`) show as images or downloads. Their signed links come with
the stream; for older ones the chat asks your route for a fresh link. The route signs links only for
files the agent presented, or that are in its own workspace volume (the one the runtime made for it):
a volume you mounted into it (shared data, say) is not downloadable by its users unless the agent
hands a file over. With `linkAnyMountedPath: true` the boundary is what the agent can read: any file
in any of its mounts.

## Conversations (threads)

A `thread` is your name for one of the user's conversations; each is its own agent, with its own
history:

```tsx
<AgentChat endpoint="/api/agent" thread={conversationId} />
```

The route receives it in `authorize(request, { thread })`. By default each user and thread is one
agent (`agentKeyFor(userId, thread)`).

**Agents several people share** (a team's assistant, a support conversation a customer and an agent
of yours both join): return the agent's key yourself, after checking the user may use it.

```ts
authorize: async (request, { thread }) => {
  const user = await getUser(request);
  if (!user) return null;
  // thread is the team's id here: only its members get its agent.
  if (thread && !(await isMember(user.id, thread))) return null;
  return { userId: user.id, name: user.name, agentKey: thread ? `team-${thread}` : undefined };
},
```

- The key is yours: 1 to 80 letters, digits, `_` and `-`, stable for as long as the conversation
  lives. Never build it from untrusted input without checking access first, as above.
- Each message is sent as its user (`from`), so the model knows who said what and the chat shows each
  sender's name; tools get the sender as `identity.actor`.
- The agent's `subject` (what its tools see as `identity.subject`) is set when it is made and never
  changes: for an agent you name, it is the key (`team-acme`), not whoever opened it first; return
  `subject` from `authorize` to choose it, and put what tools need (the team) in `agent.context`.
- Answers to the agent's questions are checked against who may answer: by default the person whose
  message started the turn.
- Everyone watching sees the same conversation, live.
- It is one conversation with one turn at a time: a message sent while the agent works waits for
  that turn (or joins it, with `whileRunning: "steer"`); anyone's Stop stops the turn for everyone;
  and a new message while the agent waits on a question supersedes the question (its call closes as
  not answered). Put per-user work in per-user agents.

## Theming and accessibility

`styles.css` defines the look with CSS variables on `.agent-chat` (or any ancestor):

```css
.agent-chat {
  --agent-accent: #4f46e5;        /* buttons, send */
  --agent-radius: 16px;
  --agent-font: "Inter", sans-serif;
  --agent-max-width: 880px;
}
```

Others: `--agent-bg`, `--agent-fg`, `--agent-muted`, `--agent-muted-fg`, `--agent-border`,
`--agent-user-bg`, `--agent-code-bg`, `--agent-danger`, `--agent-focus`, `--agent-font-size`. Dark mode
follows the system, a `.dark` (or `data-theme="dark"`) ancestor, or `theme="dark"`; use `theme="light"`
on a site without dark mode. With shadcn/ui, also import `@camelai/run-react/shadcn.css`
to use your theme's tokens. Every rule is `:where(…)`, so your CSS wins without `!important`; class
names (`agent-chat__message`, …) are stable.

Accessibility: the conversation is a `log` that screen readers do not read token by token; a polite
status says when the assistant is responding and then reads its reply. Everything works with the
keyboard (Enter sends, Shift+Enter is a new line, Escape stops a run); questions are fieldsets with
radio and checkbox groups; focus is always visible; motion follows `prefers-reduced-motion`.

## Other frameworks

The store (`@camelai/run/chat`) has no framework in it; the React bindings are a thin
layer over it, and so are those for Vue, Svelte and Solid (see their packages). React Native works
with the store and the hooks where `fetch` streams (Expo's `expo/fetch`), or with
`watch: { transport: "poll" }`.

## Troubleshooting

- **401 from the route**: `authorize` returned null: the user is not signed in, or the cookie did not
  reach the route (`credentials`).
- **"Could not reach the runtime … CORS"** in the browser: the runtime allows any origin only for
  browser tokens on its read routes; check the route's `browserToken.url` (or `CAMELAI_BASE_URL`).
- **Tool calls fail with "not connected"**: the process that serves the route's tools is not
  running (serverless); use `serveTools` and a definition.
- **Two server instances**: tools served from the route belong to one process at a time; run one
  instance, or serve tools over HTTP.

---

<!-- https://run.camelai.com/docs/guides/browser.md -->

# Showing an agent in a browser

A browser reads an agent directly from the runtime (its messages as they stream,
the running turn, tool progress, waiting inputs, older history) with a **browser
token** your server mints for each user after its own access checks. The browser
never holds your API key or the agent's token, and your server relays nothing.

## 1. Mint a token on your server

```ts
// POST /api/threads/:id/token, after checking the user may see this thread
const agent = await agents.upsert(`thread-${threadId}`, config);
return Response.json(await agents.runtime.browserToken(agent.id, { ttlSeconds: 900 })); // { token, expiresAt, agentId, url }
```

(Python: `await agents.runtime.browser_token(agent.id, ttl_seconds=900)`; REST:
`POST /v1/agents/:id/browser-tokens {ttlSeconds?, scopes?, events?, redact?, subject?}`.)

- The token reads that one agent: only `GET /v1/agents/:id/events`, `/state`,
  `/history` and `/inputs` (or the `scopes` you name). Everything else is a 403.
  Add `children` to its scopes, and it reads the same of the agent's
  [background sub-agents](https://run.camelai.com/docs/guides/multi-agent.md#background-sub-agents), by their ids.
- It lasts `ttlSeconds` (default 900, 5 to 3600), and its event stream ends when
  it expires. It is stateless: nothing revokes it sooner, so keep it short.
- `events` limits the event types it gets (the watcher needs `turn_opened`,
  `message_start`, `message_update` and `message_end` to follow messages);
  `redact: ["usage.cost"]` leaves every cost out of everything it reads (each
  message's `usage.cost`, and the provider's own `usage.providerCost` and
  `providerCreditCost`, in events, snapshots, history and inputs). It
  never gets the runtime's internal events, or a run's result, only whether and
  why a run stopped.
- It works from any origin, as publishable keys do: the token grants the read,
  so there is no origin list to keep. Send it as `Authorization: Bearer`, never in
  a URL.

## 2. Watch from the browser

```ts
import { watchAgent } from "@camelai/run/watch";

const { token, expiresAt, agentId, url } = await fetch(`/api/threads/${id}/token`, { method: "POST" }).then(r => r.json());
const watcher = watchAgent({
  url, agentId, token, expiresAt,
  // Called before the token expires, and if the runtime refuses it.
  getToken: () => fetch(`/api/threads/${id}/token`, { method: "POST" }).then(r => r.json()),
  onChange: state => render(state),
  onError: error => console.warn(error.message),
});
// later: watcher.loadOlder() on scroll-up; watcher.close() when the view goes away
```

`@camelai/run/watch` has no dependencies and no Node APIs (it bundles
to under 30 KB). `state` is:

| field | |
| --- | --- |
| `messages`, `indexes` | the agent's messages, oldest first, each at its index in the history; a user message carries its `requestId` and your `metadata`, to match an optimistic bubble |
| `partial` | the assistant message streaming now, with tool calls' arguments parsed as they stream |
| `progress` | the latest progress of each running tool call, by tool call id |
| `running` | whether a turn runs |
| `pendingInputs` | inputs the agent waits on (answer them through your server) |
| `lastOutcome` | how the latest run ended: `{id, stopped?, error?}` |
| `hasOlder` | whether `loadOlder()` has more |
| `loaded` | history and state have been read since it connected: until then, no messages means they are on their way, so show a loading state rather than an empty chat |
| `connected`, `transport` | `sse`, or `poll` where a proxy buffers streams |
| `expired` | the token expired (or was refused) and could not be renewed: the watcher stopped; watch again with a new token |

- It streams over SSE and falls back to long polls where streams deliver
  nothing. It reconnects from its cursor, or from a snapshot of the running turn
  where it cannot replay, and closes the stream while the page is hidden
  (`hiddenGraceMs`, default 30 s).
- Without `getToken`, the watcher stops when its token expires, with
  `state.expired` set and an error saying so. Pass `getToken` for any view that
  stays open longer than the token.
- In a browser a network failure and a CORS refusal both look like "Failed to
  fetch"; the watcher's error says which to check. The usual cause is a token
  that is not a browser token (the runtime allows cross-origin reads only with
  one), or a wrong `url`.

## Sending messages from the browser

The browser only reads. Send messages, answers and aborts through your server,
which checks the user and calls the agent:

```ts
// POST /api/threads/:id/messages
const agent = await agents.upsert(`thread-${threadId}`, config);
const run = await agent.run(text, { user: user.id, metadata: { clientId } });
return Response.json({ reply: run.text });
```

The watcher shows the run as it happens; `metadata.clientId` lets the page match
the stored user message to the bubble it showed optimistically.

## Ready-made components

The runtime serves a [shadcn](https://ui.shadcn.com) registry of React components: a streaming
chat with the user's agent, with tool cards, questions and approvals, and files (`agent-chat`); its
safe, streaming-tolerant Markdown (`agent-markdown`); and the Next.js App Router route the chat
talks to, which keeps your API key on the server and lets each user reach only their own agent
(`agent-route`). Add one to your app with its URL:

```bash
npx shadcn@latest add https://run.camelai.com/r/agent-chat.json
```

`/r/registry.json` lists them. The registry is public and cacheable; a self-hosted runtime serves
its own at `<its URL>/r/`.

## Without the watcher

The same reads work from any code: `GET /v1/agents/:id/events` (SSE; `?poll=1&wait=25`
for one JSON long poll), `/state`, `/history?limit=50` (pages of whole turns,
newest first, `before` for older) and `/inputs`, with a browser token or your
API key. See the [event reference](https://run.camelai.com/docs/reference/events.md).

---

<!-- https://run.camelai.com/docs/guides/voice.md -->

# Voice and audio

Agents hear audio: attach a voice note or a recording to a message, and the
runtime transcribes it before the model sees it, so every model, Claude
included, reads what was said. `POST /v1/transcriptions` transcribes audio on
its own, with no agent.

Transcription runs on OpenAI's `gpt-transcribe` (its recommended model for recorded speech) with the
OpenAI key a model call of yours would use: a [key scope](https://run.camelai.com/docs/guides/models-and-keys.md#key-scopes)'s, your own
(`PUT /v1/providers/openai/key`), else the platform's, which a prepaid account pays for per second of
audio (see [Pricing](https://run.camelai.com/docs/pricing.md)).

## Audio in a message

Attach audio as any file. A file whose type is `audio/*` is transcribed by
default:

```ts
const run = await agent.run("Summarize this and list the action items", { files: ["./standup.m4a"] });
```

```python
run = await agent.run("Summarize this and list the action items", files=[Path("standup.m4a")])
```

A voice note alone needs no text: `agent.run("", { files: [voiceNote] })`. In the SDKs a file is also
`{ url }` (Python `{"url"}`), and takes `transcribe: true | false`.

```bash
curl -X POST "$RUNTIME/v1/agents/$AGENT/prompt" -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"files": [{"url": "https://example.com/voice-message.ogg"}]}'
```

A file is attached as [Files](https://run.camelai.com/docs/guides/files.md#attaching-files-to-a-message) describes (uploaded, inline base64 up
to 4 MiB, or `{path}` of a file in the agent's mounts), or by URL: `{url, name?, contentType?}`, which the
runtime fetches from the public internet (at most 64 MiB, three redirects). `text` may be left out when the
message has audio.

The runtime transcribes the audio **before it accepts the message**: the prompt's answer comes once the
transcript is ready (a second or two for a voice note, longer for a long recording), and a transcription that
fails fails the request, with nothing run. The message, its events and the agent's history keep the audio
file's reference with its transcript:

```json
{ "type": "file", "path": "/workspace/uploads/r1/voice-message.ogg", "contentType": "audio/ogg", "size": 12538,
  "transcript": { "text": "Hello from camelRun.", "language": "en", "seconds": 5, "model": "gpt-transcribe" }, ... }
```

and the model reads it as text:

```
[Audio /workspace/uploads/r1/voice-message.ogg (audio/ogg, 0:05, en), transcript:
Hello from camelRun.
]
```

The audio stays in the agent's workspace like any attachment, for its tools to use.

- `transcribe: false` on a file keeps audio a plain file (named to the model, not transcribed).
- `transcribe: true` transcribes a file whose type does not say audio (`application/octet-stream`, or a
  video such as `video/mp4` or `video/webm`, whose sound is transcribed).
- Audio transcribed by default that cannot be (no OpenAI key, a format or length it does not take, the
  provider failing) is attached without a transcript, and the model is told why
  (`[File …: not transcribed (…)]`), so a voice note from a [channel](https://run.camelai.com/docs/guides/channels.md) still reaches the agent.
  A file you asked to transcribe (`transcribe: true`) fails the request instead.
- A spend limit refuses the request either way: the agent's, or the run's own `spendLimit`, which pays for
  the message's audio first (what is left is the run's to spend on its model).

[Channels](https://run.camelai.com/docs/guides/channels.md) get this with no setup: a Discord or Telegram voice message, or any audio file sent in
a channel, reaches the agent with its transcript. [Stateless runs](https://run.camelai.com/docs/guides/stateless-runs.md)
take audio as input parts: `{"type": "file", "url": "…"}` or `{"type": "file", "data": "…"}`.

## Transcribing on its own

```ts
const { text } = await agents.transcriptions.create({ file: await readFile("voice-message.ogg"), language: "en" });
```

```python
result = await agents.transcriptions.create(Path("voice-message.ogg"), language="en")
```

```bash
curl -X POST "$RUNTIME/v1/transcriptions" -H "Authorization: Bearer $TOKEN" -F file=@voice-message.ogg -F language=en
```

```json
{ "text": "Hello from camelRun.", "language": "en", "durationSeconds": 5, "model": "openai/gpt-transcribe", "costUsd": 0.000375 }
```

It takes the audio as multipart (`file`) or JSON: `{"data": "<base64>"}` or `{"url": "https://…"}`. With
either:

| Field | |
| --- | --- |
| `language` | ISO 639-1 (`en`) or a locale (`pt-BR`); detected when left out |
| `prompt` | names, jargon or the conversation so far, as a hint (at most 2,000 characters) |
| `keyScope` | a key scope whose OpenAI key goes first |
| `subject`, `context`, `actor` | who it is for and who asked, carried to its `usage.recorded` event, as an agent's identity is |

Nothing is kept: the audio goes to the provider and the transcript comes back to you. A retry transcribes (and
bills) again; it takes no `Idempotency-Key`. API tokens and OAuth tokens may transcribe; browser tokens may not.
Runs-per-minute limits count each transcription as a run.

## Formats and limits

| | |
| --- | --- |
| Formats | Ogg (Opus or Vorbis: Discord, Telegram and WhatsApp voice notes), WebM (browsers' `MediaRecorder`), MP3, M4A/MP4 (AAC), WAV, FLAC |
| One audio file | 25 MB and 30 minutes |
| One message | 5 audio files, 30 minutes in all |

The runtime reads a file's length from its container before sending it, so its cost is known first: audio
whose container gives no length (an Ogg stream cut short) is refused (415, `UNSUPPORTED_AUDIO`), as are
other formats (AIFF, CAF, AMR: convert them, e.g. `ffmpeg -i in.aiff out.flac`). Too large or too long is 413
(`AUDIO_TOO_LARGE`, `AUDIO_TOO_LONG`). A provider failure is 502 (`TRANSCRIPTION_FAILED`); audio the provider
refuses, 400.

## Billing

On the platform's key, a transcription costs $0.0045 a minute of audio (`gpt-transcribe`'s price), per second as
the provider bills it. On your own key or a
key scope's, OpenAI bills you and camelRun charges nothing. Either way it is recorded:

- in `GET /v1/usage`, a row per day with `kind: "transcription"` and model `openai/gpt-transcribe` (`responses` counts transcriptions);
- in the hour's ledger entry, as `transcription` (micro-USD), `transcriptions` and `audioSeconds`;
- as a [`usage.recorded`](https://run.camelai.com/docs/guides/webhooks.md) event with `kind: "transcription"`, `audioSeconds` and no tokens. In a
  message it carries the run's `requestId`, `actor`, the agent's identity and key scope; on its own,
  `agentId: null` and the `subject`, `context` and `actor` you sent. The older usage webhook
  (`/v1/usage-webhook`) carries model responses only.

It counts toward an agent's spend limit, a run's own spend limit, a tenant's monthly cap and prepaid credit,
as a model response does.

## Privacy

Audio and transcripts are never written to the runtime's logs, which carry sizes, lengths, the model and error
classes. An attached file and its transcript are kept with the agent's history and workspace, and deleted with
them; a standalone transcription keeps nothing. OpenAI processes the audio under its API data policy (not used
for training). See [Account data](https://run.camelai.com/docs/operations/privacy.md#transcription).

## Not yet

- **Audio to the model itself.** Every model reads the transcript today; models that hear audio natively may be
  given the sound later, beside it.
- **Timestamps or speaker labels.** Transcripts are text only, from the one model.
- **Live voice.** Transcription of streaming audio as it is spoken (OpenAI's realtime transcription sessions),
  and speech out (text to speech), are not offered yet.
- **Audio in `initialMessages`.** Transcribe it first with `POST /v1/transcriptions` and import the text.

---

<!-- https://run.camelai.com/docs/guides/images.md -->

# Images

`POST /v1/images` makes images from a prompt, or edits images you give it, with no agent. An agent makes them with
the `generate_image` builtin.

Images are made with OpenAI's `gpt-image-2.5-flare` and the OpenAI key a model call of yours would use: a
[key scope](https://run.camelai.com/docs/guides/models-and-keys.md#key-scopes)'s, your own (`PUT /v1/providers/openai/key`), else the platform's, which a
prepaid account pays for per token, at OpenAI's prices (see [Pricing](https://run.camelai.com/docs/pricing.md)).

## Making an image

```ts
const { images: [image], costUsd } = await agents.images.generate("A watercolor camel crossing dunes at dawn", { size: "1536x1024" });
await writeFile("camel.png", Buffer.from(image.data!, "base64"));
```

```python
result = await agents.images.generate("A watercolor camel crossing dunes at dawn", size="1536x1024")
Path("camel.png").write_bytes(base64.b64decode(result["images"][0]["data"]))
```

```bash
curl -X POST "$RUNTIME/v1/images" -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"prompt": "A watercolor camel crossing dunes at dawn", "size": "1536x1024"}'
```

```json
{
  "images": [{ "contentType": "image/png", "width": 1536, "height": 1024, "data": "iVBORw0KGgo…" }],
  "model": "openai/gpt-image-2.5-flare", "usage": { "inputTokens": 16, "outputTokens": 343 }, "costUsd": 0.01037
}
```

| Field | |
| --- | --- |
| `prompt` | what to make, or how to change the images given (at most 32,000 characters) |
| `size` | `1024x1024` (default), `1536x1024` (landscape) or `1024x1536` (portrait) |
| `quality` | `low`, `medium` (default) or `high` |
| `format` | `png` (default), `jpeg` or `webp` |
| `background` | `transparent` (with `png` or `webp`) or `opaque`; the model chooses when left out |
| `n` | how many images, 1 to 4 (default 1) |
| `keyScope` | a key scope whose OpenAI key goes first |
| `volumeId`, `path` | save the images in a volume of yours instead (below) |
| `subject`, `context`, `actor` | who it is for and who asked, carried to its `usage.recorded` event, as an agent's identity is |

The answer comes when the images are ready: about 10 seconds for one at `low` or `medium`, longer at `high` (OpenAI
allows up to two minutes for a complex prompt). The images come back as base64 and nothing is kept. A retry makes (and
bills) new images; it takes no `Idempotency-Key`. API tokens and OAuth tokens may make images; browser tokens may not.
Runs-per-minute limits count each request as a run.

## Editing images

Give up to 4 images (PNG, JPEG or WebP) in `images`, and the prompt says how to change or combine them:

```ts
const { images } = await agents.images.edit("Put this camel on a beach", [await readFile("camel.png")], { quality: "high" });
```

```python
result = await agents.images.edit("Put this camel on a beach", [Path("camel.png")], quality="high")
```

```bash
curl -X POST "$RUNTIME/v1/images" -H "Authorization: Bearer $TOKEN" -F prompt="Put this camel on a beach" \
  -F image=@camel.png -F quality=high
```

In JSON, each image is `{"data": "<base64>"}` or `{"url": "https://…"}`, which the runtime fetches from the public
internet (three redirects at most). As multipart, each is a file part named `image`, and the fields are form fields
(`context` as JSON). A `mask` (a part, or `{data}`/`{url}`) says where the first image may change: transparent there,
an image with an alpha channel in that image's format and size.

## Saving to a volume

With `volumeId` (one of your [volumes](https://run.camelai.com/docs/guides/files.md)), the images are saved there, under `path` (a directory, default
`/images`), and the answer gives their paths instead of their bytes:

```json
{ "images": [{ "contentType": "image/png", "width": 1024, "height": 1024, "volumeId": "vol_…", "path": "/images/image-20261009T104512-3fa9c1.png", "size": 1316554, "version": 1 }], … }
```

Read them with `GET /v1/volumes/{id}/files/{path}`, or hand a browser a signed link to one
(`POST /v1/volumes/{id}/links`). They count toward your storage like any file.

## In an agent

Give an agent (or its definition, or a stateless run) the `generate_image` builtin:

```ts
const agent = await agents.upsert("illustrator", { builtins: ["generate_image"] });
const run = await agent.run("Draw a camel crossing dunes at dawn, as a watercolor, and show it to me");
```

```python
agent = await agents.upsert("illustrator", builtins=["generate_image"])
run = await agent.run("Draw a camel crossing dunes at dawn, as a watercolor, and show it to me")
```

The model calls `generate_image` with a `prompt`, and optionally `images` (paths of images in its files: an
attachment, or one it made before, to edit or combine), `size`, `quality` (`medium` by default), `format` and
`background`. Each call makes one image, saved to the agent's workspace under `tool-outputs/generate_image/<call>/`,
and answers with its path, size and cost; the model is shown the image, so it can check it or describe it, and
presents it to the user with `present_file` (a `file_presented` event with a signed link). A stateless run with
`generate_image` gets a workspace for its images.

Each image is billed as a request to `POST /v1/images` is, with the run's facts on its `usage.recorded` event
(`agentId`, `requestId`, `actor`, the agent's identity and key scope). It counts against the agent's spend limit and the
run's own `spendLimit`: a call whose estimate is more than is left fails before anything is sent, and the model is told
why. The run's `usage.imageCostUsd` says what its images cost. Saving a definition or an agent with `generate_image`
when the account has no OpenAI key to use answers with a warning, and a call then fails with how to add one.

## Safety

OpenAI's safety system checks the prompt, the images given and the image made. A request it refuses is a 400
`IMAGE_REFUSED`, which names the stage (`input`: the prompt or images given; `output`: the image made) and the
categories it gives, never the prompt:

```json
{ "type": "error", "error": "OpenAI's safety system refused this request (violence)", "code": "IMAGE_REFUSED", "stage": "input", "categories": ["violence"] }
```

A refused request is not charged; in an agent, the model is told it was refused and why. Other errors: a request OpenAI cannot take is a 400 with its reason, a provider
failure is a 502 (`IMAGE_FAILED`), and no OpenAI key to use is a 400 (`IMAGE_UNAVAILABLE`).

## Limits

| | |
| --- | --- |
| Prompt | 32,000 characters |
| Images to edit | 4, PNG, JPEG or WebP, 25 MB each, 50 MB in all, at most 8,000 pixels a side |
| Images made | 4 per request |
| Time | 3 minutes for the provider to answer |

An image to edit that is not one of those types is a 415 (`UNSUPPORTED_IMAGE`); one too large is a 413
(`IMAGE_TOO_LARGE`).

## Billing

On the platform's key, images cost what OpenAI charges for `gpt-image-2.5-flare`: $5 per million text tokens in, $8 per
million image tokens in (images given to edit) and $30 per million image tokens out. The tokens are those OpenAI
reports for the request. One image costs:

| Quality | 1024x1024 | 1536x1024 or 1024x1536 |
| --- | --- | --- |
| `low` | $0.0059 (196 tokens) | $0.0047 (158 tokens) |
| `medium` | $0.0132 (439 tokens) | $0.0103 (343 tokens) |
| `high` | $0.0527 (1,756 tokens) | $0.0412 (1,372 tokens) |

plus the prompt (a few hundredths of a cent), and about $0.008 to $0.012 for each image given to edit (1,024 tokens for
a square one, 1,536 for a wide one). A spend limit refuses a request whose estimate (the most it can cost) is more than
is left of it, before anything is sent. On your own key or a key scope's, OpenAI bills you and camelRun charges
nothing. Either way it is recorded:

- in `GET /v1/usage`, a row per day with `kind: "image"` and model `openai/gpt-image-2.5-flare` (`responses` counts images);
- in the hour's ledger entry, as `image` (micro-USD) and `images`;
- as a [`usage.recorded`](https://run.camelai.com/docs/guides/webhooks.md) event with `kind: "image"`, `images`, and its tokens (`input`: text and images
  in, `output`: images out). Made alone, it has `agentId: null` and the `subject`, `context` and `actor` you sent. The
  older usage webhook (`/v1/usage-webhook`) carries model responses only.

It counts toward a tenant's monthly cap and prepaid credit, as a model response does.

## Privacy

Prompts and images are never written to the runtime's logs, which carry sizes, quality, tokens and timings. A request
without `volumeId` keeps nothing; with one, the images are kept in your volume until you delete them. OpenAI processes
the prompt and images under its API data policy (not used for training). See
[Account data](https://run.camelai.com/docs/operations/privacy.md#images).

---

<!-- https://run.camelai.com/docs/guides/files.md -->

# Files

Every agent has files: its own workspace at `/workspace` by default, or the
**volumes** you mount. Files you attach to a message land there, the model works
on them with its file tools and with code, tools save their outputs there, and
you read what the agent made by path.

## Attaching files to a message

```ts
const run = await agent.run("What changed in Q3?", {
  files: ["./q3.pdf", screenshotBytes, new File([csv], "data.csv"), { path: "/workspace/notes.md" }],
});
```

```python
run = await agent.run("What changed in Q3?", files=[Path("q3.pdf"), screenshot_bytes, {"name": "data.csv", "data": csv}, {"path": "/workspace/notes.md"}])
```

A file is bytes, a `Blob` or `File`, `{name, data, contentType?}` (Python
`{"name", "data", "content_type"?}`), a local path
(the Node entry `@camelai/run/node`, or a `str`/`Path` in Python), or
`{path}` for a file already in the agent's mounts. The SDKs upload each first,
streamed, to `uploads/<run id>/<name>` in the agent's workspace, then send the
message referring to them by path, so a retried run never uploads twice.

- At most 20 files per message, each at most 256 MiB.
- Over REST, upload with `PUT /v1/agents/:id/uploads/:requestId/:name`, then
  `POST /v1/agents/:id/prompt {text, requestId, files: [{path}]}`. The prompt also
  takes small files inline, `{name, data: <base64>, contentType?}`, up to 4 MiB in
  all.

## What the model sees

The message carries a line per file, such as
`[File /workspace/uploads/r1/q3.pdf (application/pdf, 2.1 MB)]`, and the file
itself where the model can take it:

| | Shown natively | Limits |
| --- | --- | --- |
| Images (PNG, JPEG, GIF, WebP) | models with image input | 5 MiB and 8,000 px a side each |
| PDFs | Anthropic, Google, OpenAI and OpenRouter models with image input | 16 MiB and 100 pages each |
| Per model request | | 24 MiB and 100 files shown; older files past that are named only |

An image goes to the model at most 1,568 px a side: a larger one is scaled down
in the request (keeping its shape; the file itself is unchanged), as Anthropic
would scale it anyway, so a conversation with many images stays within every
provider's limits. One that cannot be scaled down is named with why instead.
Inline images (a message's or a tool result's base64) are scaled down as they
enter the transcript.

Audio is transcribed when it is attached, and the model reads the transcript
(see [Voice and audio](https://run.camelai.com/docs/guides/voice.md)). Anything else is only named, and the model reads it with its file tools. The
transcript keeps a reference to each file's content, never its bytes, so a file
changed or deleted later still reads as it was when attached.

## The agent's file tools

`read`, `write`, `edit`, `ls`, `glob` and `grep` work on mount paths
(`/workspace/notes.md`). `read` shows an image or PDF to a model that can view
it. The runtime remembers which version of each file the agent last read or wrote,
so a `write` or `edit` of a file someone else changed since then fails ("changed
since you last read it; read it again") and the model reads again. The model
never sees version numbers; the files API for applications keeps them. An application whose own tools
handle files can leave these out with `fileTools: false` (in a definition, or when
the agent is made).

Code in `js_exec` has `fs` over the same mounts:

```js
const csv = await fs.readFile("/workspace/data.csv", { encoding: "utf8" });
await fs.writeFile("/workspace/out/chart.png", png, { contentType: "image/png" });
await fs.stat("/workspace/out/chart.png");  // {path, type, size, updatedAt, contentType}
await fs.list("/workspace/out");
```

One `fs` call moves at most about 700 KiB; read larger files in windows with
`tools.read({ path, offset, encoding: "base64" })`.

## Files out

A run lists what it wrote: `run.files` (`[{path, version, size, contentType}]`,
every file written, up to 100) and, in `run.raw.presented`, the files the model
handed over with `present_file` (with a caption). Each presented file is also a
`file_presented` event as soon as it is presented, with a signed download `url`.

Read them with the agent's own access:

```ts
const { data, contentType } = await agent.files.download("/workspace/out/chart.png");
const listing = await agent.files.list({ path: "/workspace/out" });
const link = await agent.files.link("/workspace/out/report.pdf", { expiresIn: 3600 }); // for a browser or another service
await agent.files.upload("/workspace/in/config.json", JSON.stringify(config));
```
Python has the same: `agent.files.download(path)` (`.data`, `.content_type`, `.version`), `list(path=...)`,
`link(path, expires_in=...)`, `upload(path, data)`.

Tools of a definition's sources take the agent's files as `{"$file": path}`,
and their file outputs are saved to the workspace: see
[Files in tool calls](https://run.camelai.com/docs/guides/tools.md#files-in-tool-calls).

## Volumes

A volume is a shared file tree. Without `mounts`, each agent gets its own
workspace volume at `/workspace`; mount the same volume in several agents to
share files, read-only or read-write:

```ts
const docs = await agents.runtime.createVolume({ name: "shared docs" });
await agents.runtime.volume(docs.id).write("handbook.md", handbook);
const agent = await agents.upsert("support", { mounts: [{ volumeId: docs.id, path: "/docs", mode: "ro" }], … });
```

- Mounts are `{volumeId, path, mode: "ro" | "rw", subpath?, notify?}`. `notify`
  prompts the agent (about a second after, coalesced) when others change files
  under the mount. Only your own volumes can be mounted, and an agent's mounts
  are fixed when it is made: an upsert with other mounts is a 409, unless it
  sends `remount: true`, which sets them between its turns.
- `PUT /v1/agents/:id/mounts` replaces them during a turn too. Mount changes
  apply at the agent's next tool call (a call under way keeps the mounts it
  began with): a removed volume is refused, a read-only one is read-only, and
  one added or swapped in is there at its path, so a tool can swap `/bot` for
  another volume and the model goes on working in it. Tool outputs go to the
  workspace as it is then. The running turn's environment text updates at the
  next run.
- The agent's own workspace stays at `/workspace` beside the mounts you give
  (after them). `{workspace: true}` among them puts it at that position,
  `{workspace: false}` leaves it out, and a mount you give at `/workspace` takes
  its place. The first mount is where relative paths resolve, e.g.
  `[{volumeId, path: "/bot", mode: "rw"}]` has `/bot` first and `/workspace`
  second; `[{workspace: false}]` is no mounts at all.
- `{workspace: true, path: "/scratch"}` mounts the workspace elsewhere, e.g.
  beside a project volume at `/workspace`:
  `[{volumeId: project, path: "/workspace", mode: "rw"}, {workspace: true, path: "/scratch"}]`.
  The path is absolute, written normalized, and clear of the other mounts.
- Attachments are saved under `uploads/<request>/` in the agent's own
  workspace, files tools return under `tool-outputs/`, and the model keeps
  scratch files in `tmp/`, wherever the workspace is mounted (`/workspace/...`
  by default, `/scratch/...` above). Without it, they go to a read-write
  `/workspace`, else the first read-write mount (and an agent with none cannot
  take attachments or tool files).
- An agent's own workspace is deleted with the agent, whether or not it is
  still mounted; volumes it only mounted stay.
- `createVolume({ name }, { idempotencyKey })` (Python
  `create_volume(name=…, idempotency_key=…)`) makes a volume once per key, for a
  day: a retry, or another process, gets the same volume.
- `volume.write(path, data, { version })` writes only if nobody changed the file
  since that version (`0`: it must not exist), `read`, `list`, `remove`,
  `changes(since, { prefix? })`. `runtime.volumes(ids)` reads up to 50 volumes'
  `seq` (and files and bytes) in one request, to see which changed.
- `volume.snapshot()` and `volume.fork({ snapshot })` copy metadata only: a fork
  shares its source's content and diverges independently. `read`, `list` and
  `readAll` take `{ snapshot }` to read a snapshot as it was.
- A snapshot can be pinned (`snapshot({ pinned: true })`, or
  `updateSnapshot(id, { pinned })`, `PATCH /v1/volumes/:id/snapshots/:id`): it is
  kept until unpinned, counts against 10,000 pinned snapshots rather than the
  100 others, and deleting it takes unpinning first or `deleteSnapshot(id,
  { force: true })`. Snapshots take `labels`, your own string map (16 at most),
  and `snapshots({ labels })` (`?label=key:value`) lists those that have them.
  Deleting a volume deletes all its snapshots, pinned ones too.
- `volume.snapshot({ files })` makes a snapshot of the files given (path to
  text or bytes; 1,000 files and 16 MiB at most) instead of the volume, which it
  leaves untouched: for bringing in versions kept elsewhere. It is made whole or
  not at all, and its answer has each file's `sha256` (`contents`).
- `volume.restore(snapshot)` (`POST /v1/volumes/:id/restore {snapshot}`) makes
  the volume as a snapshot was, in place: files the snapshot lacks are removed
  and files that differ are written back, in one write, each a change that
  agents mounting it see. It answers `{snapshot, seq, written, removed}`; the
  snapshot stays.
- `volume.archive({ snapshot?, path?, glob? })` (`GET /v1/volumes/:id/archive`)
  streams the files as a tar.gz, as the volume or a snapshot has them at one
  `seq` (`X-Volume-Seq`), named relative to `path`: for a build that wants the
  whole tree. At most 10,000 files and 1 GiB (else 413).
- `volume.readAll({ prefix?, glob?, snapshot? })` (Python `read_all`) reads every
  matching file with its contents in one request, as the volume was at one `seq`:
  `{seq, files: [{path, size, version, contentType, sha256, text | data}]}`
  (`data` is base64, for files that are not UTF-8 text). Use it to check or
  publish what an agent wrote: nothing written meanwhile shows in it. At most
  1,000 files and 16 MiB a read (a 413 says to narrow `prefix` or `glob`). REST:
  `GET /v1/volumes/:id/files?content=true&prefix=…&snapshot=…`.
- Every file has a content type: the upload's, else sniffed from its bytes and
  name. Downloads are served so a file can never run as the runtime's origin.
- Uploads may take 15 minutes; a volume suits up to about 100,000 files.
- Deleted files, volumes and snapshots stop being stored and billed about a day
  after nothing refers to them any more. A file an agent was sent or shown stays,
  as the agent's history refers to it, until the agent is deleted.

## Signed links

`volume.link(path, options)` or `agent.files.link(path, options)` returns `{url,
expiresAt}`: a URL that downloads (`GET`) or uploads (`PUT`, with `maxBytes` and
`contentType`) that one file without a token, so a browser, a tool server or a
channel moves the bytes directly. Links last 15 minutes by default, at most 24
hours, and cannot be revoked sooner. Downloads take `Range`.

From your server, with your API key, `POST /v1/agents/:id/links {path, method?,
expiresIn?, maxBytes?, contentType?}` signs a link to a file of an agent by the
path the agent sees (`/workspace/report.pdf`), without the agent's token; `POST
/v1/volumes/:id/links` does the same by a volume's own path. Both answer `{url,
method, path, expiresAt}`, and a retry with the same `Idempotency-Key` never
returns the link again.

---

<!-- https://run.camelai.com/docs/guides/multi-user.md -->

# Agents for many users

Most applications give each user, or each conversation, an agent of its own, and
serve every agent's tools from one backend. This guide puts the pieces
together: keys, identity, served tools, per-user limits and keys.

## One agent per user or conversation

Key agents by your own ids, and upsert on each request:

```ts
const agent = await agents.upsert(`thread-${thread.id}`, {
  definition: SUPPORT_DEFINITION,         // tools served by your backend, see below
  subject: thread.ownerId,                // whom the agent acts for
  context: { org: thread.orgId },         // claims your tools authorize against
});
const run = await agent.run(message, { user: currentUser.id });
```

- `subject` and `context` are set when the agent is made, with your API key; the
  agent's own token cannot change them, and nor can the model. Your tools get them
  as `identity.subject` and `identity.context`.
- `user` names who sent this message. The model sees who sent it (in a block only
  the runtime can write), and tools get it as `identity.actor` (and
  `identity.user`). Use `user: { id, name }` to give the model a display name too;
  names are the sender's own and never proof of anything, which the runtime tells
  the model.
- An agent shared by several people (a team channel) shares its whole
  conversation with all of them: keep private data in agents of one person each.

## Serve the tools from your backend

A multi-user backend runs many instances, so its tools are served over HTTP,
not attached to one process. Each call carries a signed token saying which agent
it is for and who is acting, so one endpoint answers every user's agents safely:

```ts
const tools = {
  list_todos: tool({
    description: "The current user's to-dos", input: schema.Object({}),
    execute: (_args, { identity }) => db.todos({ user: identity!.user, org: identity!.context.org }),
  }),
};
// tenant: yours (GET /v1/me). Other tenants' agents can reach this URL too, claiming any user: their tokens are refused.
export default { fetch: serveTools(tools, { runtime: "https://run.camelai.com", tenant: "acme" }) };
```

```ts
const definition = await agents.runtime.upsertDefinition("support", {
  name: "Support",
  mcpServers: [{ name: "app", url: "https://app.example.com/mcp", auth: { type: "runtime" } }],
});
```

Authorize every call as `identity.user` within `identity.context`, never from
the model's arguments. That identity is only meaningful within your own tenant,
which is why `serveTools` requires `tenant`. See [Tools](https://run.camelai.com/docs/guides/tools.md#served-tools-over-http-for-serverless-and-many-users)
and [Identity](https://run.camelai.com/docs/guides/tools.md#identity-who-a-call-is-for).

Your request handlers can be serverless: an agent upserted without local tools
follows its stream read-only, so any number of instances run agents at once.

## Showing each user their agent

Mint a browser token per user and let the browser read the agent directly; send
messages through your server. See [Showing an agent in a browser](https://run.camelai.com/docs/guides/browser.md).

## Spend: limits and keys per user

- `spendLimit: { usd }` caps what one agent may spend on model calls from now on
  (set it on upsert, or `PATCH /v1/agents/:id/configuration`). Setting it starts
  counting from zero, so you can set the remaining allowance before each run. An
  agent at its limit gets 402 for new runs, and a running turn ends with the run
  failed as `spend_limit`.
- A **key scope** per customer holds that customer's own provider keys, so their
  agents call providers with them: `PUT /v1/key-scopes/:scope/providers/:provider`,
  then `keyScope` on upsert. See [Models and keys](https://run.camelai.com/docs/guides/models-and-keys.md).
- `modelHeaders` label each model call, e.g. for a gateway's per-conversation logs.
- The `usage.recorded` [webhook](https://run.camelai.com/docs/guides/webhooks.md) reports each model response's cost
  with the agent's `subject`, `context`, `actor` and `keyScope`, to meter per user.

## Matching messages to your records

`run(text, { metadata })` attaches your own key-value data to the message (at
most 16 string values): the stored message and its run carry it, in history,
events and webhooks; the model never sees it. Pass `idempotencyKey` to choose the
run's id, so a retried request never runs twice, and to find the run later.

## Bringing in existing conversations

A conversation that began elsewhere continues on an agent made with its history:
`initialMessages` on `POST /v1/agents` (`createAgent({ initialMessages })`, or an
upsert's first create; Python `agents.upsert(key, initial_messages=[…])`). They
are [Pi](https://github.com/earendil-works/pi) messages, kept as they are, with
what a message leaves out filled in (a timestamp; an assistant message's `usage`,
zero, and `stopReason`; a tool result's `isError`, false):

- `user` (content a string, or text, image and file blocks), `assistant` (text,
  thinking and `toolCall` blocks, with its `usage`, `provider` and `model` if you
  have them) and `toolResult` (`toolCallId`, `toolName`, content).
- `compactionSummary` (`summary`, `tokensBefore`): the model then sees this
  summary instead of every message before it, and those that follow. Put it just
  before the first message it keeps; only the last counts. History still shows
  every message, so a long conversation need not be summarized again.

A conversation in another API's format comes in as it is: `importMessages` (not
with `initialMessages`) takes `{format, messages, model?}`, and the runtime
converts it to Pi messages, tool calls and results included:

| `format` | `messages` |
| --- | --- |
| `anthropic` | Messages API messages: text, images, `tool_use`, `tool_result`, `thinking` and `redacted_thinking` |
| `openai-responses` | Responses API input items: messages, `function_call`, `function_call_output` and `reasoning` |
| `openai-chat` | Chat Completions messages, `tool_calls` and `tool` results included |

```ts
await agents.upsert(`thread-${thread.id}`, { importMessages: { format: "openai-chat", messages: thread.messages, model: "openai/gpt-6-sol" } });
```

`model` names the model that wrote the assistant turns. Its reasoning (signed
thinking, encrypted reasoning items) goes back as it came to that same model; any
other model gets it as text, or not at all when it has none, as when a
conversation changes model. System and developer messages are left out: the
agent's own prompt replaces them. Images must be base64 (or `data:` URLs); the
runtime fetches nothing. A message it cannot convert is a 400 naming it
(`INVALID_HISTORY: importMessages.messages[3]: …`). Python takes
`import_messages={…}`; `toPiMessages(input)` (TypeScript) converts one yourself, to
see what an agent will begin with.

History is imported only when the agent is made: an agent that has one keeps it,
and an upsert with the same key makes the agent once. `GET …/history` shows it at
once. Thinking from another model reaches the model as text; a tool call with no
result gets one saying so; tools the old conversation called need not exist.
When what is imported is more than the model's context holds, the first run
compacts it before calling the model, charged as any compaction.

A refused import makes no agent: `INVALID_HISTORY` (400) names the message and
what it lacks, and past 16 MB of JSON it is `HISTORY_TOO_LARGE` (413). Send the
most recent messages that fit, after a `compactionSummary` of the rest; upload
images as files first to keep them out of those 16 MB.

---

<!-- https://run.camelai.com/docs/guides/webhooks.md -->

# Webhooks

The runtime can tell your server when runs start and end, when an agent asks a
person for input, and what each model response cost, so you react without
holding a connection open. Register an endpoint with the event types it wants:

```http
POST /v1/webhooks
Authorization: Bearer $CAMELAI_API_KEY

{"url": "https://example.com/hooks/agents", "events": ["run.completed", "run.failed", "input.requested"], "description": "prod"}
```

The answer carries the endpoint's `id` (`we_…`) and its signing `secret`
(`whsec_…`), shown only then. `GET /v1/webhooks` lists your endpoints (at most
16); `GET`, `PATCH` and `DELETE /v1/webhooks/:id` read, change and remove one;
`POST /v1/webhooks/:id/secret` replaces its secret (the old one also signs for 24
hours).

Each endpoint's `setBy` says who last set it: `token:<API token id>`, `console`,
`operator`, or `oauth:<grant id>` for one an OAuth app set before they no longer
could (null: set before this was recorded). An endpoint keeps sending when the
token that set it is revoked: revoking one answers with `left`, the endpoints
(and usage webhook and trace export) it set, so you can review them. OAuth apps
cannot create or change webhooks.

## Events

Every event is an envelope:

```json
{"id": "evt_3f9c0a1b2c3d4e5f60718293", "type": "run.completed", "created": 1790000000,
 "data": {"agentId": "client_…", "requestId": "…", "method": "prompt", "metadata": {"source": "web"},
          "replyIndex": 3, "messageCount": 4,
          "usage": {"responses": 2, "input": 2300, "output": 140, "cacheRead": 0, "cacheWrite": 0, "costUsd": 0.0081}}}
```

| Type | When | `data` |
| --- | --- | --- |
| `run.started` | A run (`method`: `prompt`, `continue`, `resume`, `execute`) began | `agentId`, `requestId`, `method`, `actor`, `metadata`; `resumes` when a node resumed a turn whose node was lost |
| `run.completed` | It ended without an error | as above, and `usage`; `stopped` (`input_required` with `inputIds`, `spend_limit` or `turn_limit`) if it stopped early; `replyIndex` and `messageCount`; `steeredInto` for a message a running turn took |
| `run.failed` | It ended with an error, the runtime's or the model's | as above, and `usage`, `error`, `code` where the error has a name (`cancelled`: a stop cancelled it before it began; `aborted`; `model_stream_stalled`; `turn_limit`…), and `uncertain` when a restart cut it short |
| `input.requested` | The agent asks a person for input (the run waits) | `agentId`, `requestId`, `inputId`, `toolCallId`, `kind`, `expiresAt` |
| `input.resolved` | An input settled | `agentId`, `requestId`, `inputId`, `state` |
| `usage.recorded` | A model response's usage was counted, a transcription's, or images' | `agentId`, `requestId`, `subject`, `actor`, `context`, `keyScope`, `provider`, `model`, `kind` (`response`, `compaction`, `transcription` or `image`), tokens, `audioSeconds` (a transcription's, with no tokens), `images` (how many images were made), `cost: {usd, source}`, `at`. A [transcription](https://run.camelai.com/docs/guides/voice.md) made with `POST /v1/transcriptions`, or [images](https://run.camelai.com/docs/guides/images.md) made with `POST /v1/images`, has `agentId: null`, and the `subject`, `context` and `actor` it was sent with. Treat a `kind` you do not know as other usage: kinds may be added |
| `billing.balance.low` | Funded balance crosses below the alert threshold (default $2) | `balance`, `previousBalance`, `threshold` (integer micro-USD), `source` |
| `billing.balance.depleted` | Positive balance reaches zero or below | Same balance fields |

Billing events are recorded in the transaction that changes the balance, including
usage, storage, refunds and adjustments. Remaining below a threshold does not
repeat the event; recovering above it allows a later crossing to notify again.
One charge can emit both types. A new account with no credit emits neither.
A threshold change can emit `billing.balance.low` with `source: "threshold_changed"`
and no `previousBalance`; ordinary crossings have `source: "balance"`.

- Payloads are small: ids and the key facts. Read the rest with your API key: the
  run (`GET /v1/agents/:id/requests/:requestId`, with its reply in
  `outcome.result.reply`), history, or inputs. `metadata` is what the message that
  started the run carried, so you can route an event without a lookup.
- `created` is in Unix seconds. An event's `data` only gains fields; a change you
  could not ignore comes as a new type.
- An endpoint receives the runs that begin after it is made.

## Verifying and handling

Requests are signed per [Standard Webhooks](https://www.standardwebhooks.com/):
`webhook-id` (the event's `id`), `webhook-timestamp` (Unix seconds) and
`webhook-signature`, `v1,<base64 HMAC-SHA256 of "<id>.<timestamp>.<body>">` keyed
with the secret's base64 part (space-separated when two secrets sign during a
rotation). Any Standard Webhooks library verifies them:

```ts
import { Webhook } from "standardwebhooks";
const event = new Webhook(process.env.WEBHOOK_SECRET!.replace(/^whsec_/, "")).verify(body, headers) as WebhookEvent;
```

(`WebhookEvent` is typed in `@camelai/run`.) In Python, `verify_webhook` checks
the signature in constant time and that the request was sent within 5 minutes,
and returns the event; pass the raw body, before parsing it:

```python
from camelai_run import WebhookVerificationError, verify_webhook

@app.post("/hooks/agents")  # Flask; in Django, request.body and request.headers
def hook():
    try:
        event = verify_webhook(request.get_data(), request.headers, os.environ["WEBHOOK_SECRET"])
    except WebhookVerificationError:
        return "", 400
    queue.put(event)
    return "", 200
```

During a rotation, pass both secrets as a list. The SDKs also manage endpoints:
`create_webhook(url, events)`, `webhooks()`, `update_webhook`, `delete_webhook`
and `rotate_webhook_secret` on `AgentRuntime` (Python).

- Delivery is at least once. Answer 2xx within 10 seconds; anything else is
  retried with exponential backoff, from 5 seconds to an hour apart, for 3 days.
- Dedupe by `id` (a retried event keeps it), and order by `created`: retries can
  reorder deliveries.
- Do the work after answering: queue it, then return 200.

## Continuing from a webhook

A handler can act on the agent itself. Send your own ids as `metadata` with each
message; they come back on the run's events, so the handler finds the agent by
its key without a lookup:

```ts
// When the message was sent: agent.run(text, { metadata: { thread: thread.id } })
if (event.type === "run.failed" && event.data.metadata?.thread) {
  const agent = await agents.upsert(`thread-${event.data.metadata.thread}`, config);
  await agent.run("The last step failed; tell the user what happened and what to try.");
}
```

A serverless handler that upserts without local tools never contends with the
process serving the agent's tools; see [Concepts](https://run.camelai.com/docs/concepts.md#processes-and-connections).

## The usage webhook (deprecated)

Before endpoints, `PUT /v1/usage-webhook {"url"}` set one URL that receives each
model response's usage in its own body (not an envelope). It still works, but
new integrations should register an endpoint for `usage.recorded` instead.

---

<!-- https://run.camelai.com/docs/guides/models-and-keys.md -->

# Models and keys

## Choosing a model

Agents name a model as `provider/model-id` from the catalog: `GET /v1/models`
(`?available=true` for the ones your account can use now), or the console's
**Models & keys**. For example `anthropic/claude-sonnet-5-5`,
`openai/gpt-5.2`, `openrouter/anthropic/claude-sonnet-5`. Change an agent's model
between runs with `upsert` (a changed `model`) or `agent.configure({ model })`;
its history carries over. `?available=true` answers `[]` when your account has
no key any model can use (a self-hosted runtime before its first key, say); that
response's `X-Camelrun-Hint` header says how to set one.

Each model in the list says whether it streams tool-call arguments as it writes
them (`toolCallStreaming`; the console's **Tool args** column). With `true`,
`toolcall_delta` events arrive while the model writes a call's arguments, so a
page that renders what a tool writes (a section, a card, a form) can show it as it
is written. With `false`, the arguments arrived in one piece when the call was
complete, at least sometimes, so you cannot count on streaming: Gemini, most GLM
4.x and Mercury 2 through OpenRouter do this, for example, and some models do it
only on some of the hosts a gateway routes them to. `"unknown"` means the model
has not been measured (or its probe failed), not that it streams. The values come
from probing each model through the runtime several times
(`scripts/probe-tool-streaming.ts`); a latency-first app that renders tool output
should pick a model that says `true`.

A model on a server of your own that speaks OpenAI's or Anthropic's API (vLLM,
Ollama, a gateway, a hosted API the catalog lacks) is named the same way once
you add its server as a provider, your account's or a key scope's: see
[Custom models](https://run.camelai.com/docs/guides/custom-models.md).

An agent that names no model (and whose definition names none) gets the
runtime's default: Claude Sonnet 5.5 on run.camelai.com, on the first of
Anthropic (`anthropic/claude-sonnet-5-5`), OpenRouter
(`openrouter/anthropic/claude-sonnet-5.5`) and Bedrock
(`amazon-bedrock/global.anthropic.claude-sonnet-5-5`) you have a key for (its
key scope's keys count too), else `openrouter/openai/gpt-6-luna`. It is chosen
when the agent is made and stays its model. `GET /v1/me` says which
(`defaultModel`; `runtime.me()` in the SDKs).

A model call uses, in order: the key of the agent's [key scope](https://run.camelai.com/docs/guides/models-and-keys.md#key-scopes) for
the model's provider, else your account's own key for the provider
(`PUT /v1/providers/:provider/key`, or the console), else the platform's key,
charged to your credit. An account that signed up before billing never uses the
platform's. A provider with your own key never uses the platform's. An agent on
a provider none of these has a key for is still made, and its runs fail with
`model_key_missing`, naming the key to set. Web search and `web_fetch`'s page
rendering take their keys (`exa`, `brave`, `parallel`, `firecrawl`) the same way,
without key scopes.

`PUT /v1/providers/:provider/key` checks the key with the provider before it
stores it, and refuses one the provider rejects. `{"apiKey": "…", "verify": false}`
stores it unchecked (a placeholder, a key for a provider the runtime cannot
reach yet). A run on a key the provider refuses fails with `model_key_invalid`.

A self-hosted runtime's operator can also give an account keys, and route its
model calls through a gateway of the operator's own: see
[Billing](https://run.camelai.com/docs/operations/billing.md) and [Model endpoints](https://run.camelai.com/docs/operations/model-endpoints.md).

### Amazon Bedrock

Bedrock takes a [Bedrock API key](https://docs.aws.amazon.com/bedrock/latest/userguide/api-keys.html),
sent as a bearer token, and the AWS region to call. It is the only credential
the runtime takes for Bedrock: no AWS access keys, no SigV4 signing, and never
AWS credentials the runtime's own host has.

- For the whole account: `PUT /v1/providers/amazon-bedrock/key` with
  `{"apiKey": "…", "region": "us-west-2"}`, or the console's Models page. The
  region is required. The key is not checked when saved (Bedrock has no free
  call for it): the first model call is.
- For one key scope: `PUT /v1/key-scopes/:scope/providers/amazon-bedrock` with
  `{"apiKey": "…", "region": "us-west-2"}`, or a regional `baseUrl`
  (`https://bedrock-runtime.<region>.amazonaws.com`) the region is read from
  (see [Key scopes](https://run.camelai.com/docs/guides/models-and-keys.md#key-scopes)).

Name Bedrock's Claude models by an inference profile:
`amazon-bedrock/global.anthropic.claude-sonnet-5-5` (routed anywhere, the
catalog's price), or a geography's, such as `us.` or `eu.` (kept in that
geography, a tenth dearer). Bedrock refuses a Claude model's base id
(`anthropic.claude-sonnet-5-5`) on demand, so `GET /v1/models` lists the
profiles only, and an agent that names a base id is called through its global
profile. An inference profile's geography must include the key's region.

### Azure OpenAI

The catalog's `azure/<model>` entries (`azure/gpt-6-sol`, `azure/gpt-6-luna`,
`azure/gpt-6.1-sol`, …) are OpenAI's models on the platform's own Azure OpenAI
resource. They are the platform's only: an account cannot set an Azure key
(`GET /v1/providers` says `apiKey: false`), and an account on the platform's keys
can use those the operator has deployed, which `GET /v1/models?available=true`
lists. Each costs what the same model does on OpenAI (`cost` in `GET /v1/models`,
long-context rates included), charged to your credit like any platform key.
They take the same thinking levels, tools and structured output as OpenAI's
Responses API. Naming one the operator has not deployed fails clearly: `PATCH
/v1/agents/:id/configuration` refuses it, and a run on it fails with
`model_key_missing`, before any call to Azure. Azure's own content filter may
refuse a prompt OpenAI would answer; the run then fails with Azure's words.

### Output length and temperature

Two settings shape each model response. `maxOutputTokens` is the most the model
writes in one response. It must be at most the model's own maximum (`maxTokens`
in `GET /v1/models`), which is also the default. A response that reaches it ends
with `stopReason: "length"`. On a Claude model with a thinking budget (models
before adaptive thinking, such as Claude Sonnet 4.5), the budget comes on top.
Elsewhere, reasoning counts toward it.

`temperature` (0 to 2) sets how varied the model's sampling is: lower is more
deterministic. The default is the provider's. Not every model takes one, and a
temperature a model would refuse would fail every run, so the runtime refuses it
with a 400 where you set it:

- Claude Opus 4.7 and later, Sonnet 5.5 and Fable 5.1 take none, wherever they are
  served (Anthropic, Bedrock, OpenRouter).
- A model that always reasons takes none: OpenAI's o-series and GPT-5, Claude Fable 5.
- A reasoning model takes none while it reasons: its `thinkingLevel` must be `off`.
  Give `"thinkingLevel": "off"` with the temperature, or `"temperature": null` with
  a new thinking level.

Set them when you make an agent, for a [stateless run](https://run.camelai.com/docs/guides/stateless-runs.md), or for
every agent of a [definition](https://run.camelai.com/docs/guides/definitions.md). Change them with
`PATCH /v1/agents/:id/configuration`; `null` removes either. The same check runs
there, against the model and thinking level the agent will have. `GET /v1/agents/:id`
shows both (`null` when unset).

```json
{"model": "anthropic/claude-sonnet-5", "maxOutputTokens": 2000, "temperature": 0.2}
```

Compaction summaries keep the runtime's own settings. If a later change makes a
temperature inapplicable (a definition applied with a new model or thinking level),
the agent's calls leave it out rather than fail.

### Prompt caching

The runtime marks the system prompt and tools (and the latest message) as a
cached prefix on Anthropic's API and on Bedrock's Claude models; OpenAI and
others cache on their own (Azure OpenAI too, keyed by the agent). The prefix is the same bytes from run to run (no
dates or ids in it; files and the sender of a message go in the messages), so
from an agent's second run on, `usage.cacheRead` counts what came from the cache.
A provider caches only a prefix past its minimum: on Anthropic 1,024 tokens for
Sonnet 5 and Opus 4.8, 2,048 for Opus 4.7, 4,096 for Haiku 4.5 and Opus 4.6.
An agent's runtime prompt and tools come to about 2,000 tokens, so on Haiku 4.5
a short-instruction agent caches nothing (`cacheRead: 0`) until its prefix
passes 4,096 tokens; on Sonnet 5 its second run reads about 2,400 tokens from
the cache. An agent that needs no tools can drop most of that prefix instead
(`codeMode: false`; see [Tools](https://run.camelai.com/docs/guides/tools.md#without-code-codemode-false)).

## Key scopes

An application that serves many customers can give each its own provider
credentials, so its agents call providers directly with that customer's keys: a
**key scope** per customer (e.g. `org_abc123`), holding one entry per provider.

```http
PUT /v1/key-scopes/org_abc123/providers/openrouter
{"apiKey": "sk-or-…", "baseUrl": "https://gateway.ai.cloudflare.com/v1/<account>/<gateway>/openrouter",
 "headers": {"cf-aig-authorization": "Bearer <gateway token>"}}
```

In Python, `await agents.runtime.set_scope_key("org_abc123", "openrouter", api_key=…, base_url=…, headers=…)`;
`key_scope(scope)`, `delete_scope_key(scope, provider)` and `delete_key_scope(scope)` read and remove them.

- An entry is `{apiKey?, baseUrl?, headers?, region?}`. `headers` are sent with
  every call, sealed like the key. The provider is any model provider of
  `GET /v1/providers` that takes a key, or `amazon-bedrock`.
- `baseUrl` (HTTPS, on a public address: it is checked when saved, and each call
  goes through the same [outbound guard](https://run.camelai.com/docs/guides/tools.md#outbound-calls) as MCP servers
  and `web_fetch`; Google's and Mistral's clients can't be kept to it, so their
  entries take no `baseUrl`) replaces the provider's API
  root in each request's URL, as an AI gateway's provider path stands for it
  (Cloudflare AI Gateway's `…/openrouter`, `…/anthropic`, `…/openai`):

  | provider | root `baseUrl` replaces | requests |
  |---|---|---|
  | `openrouter` | `https://openrouter.ai/api/v1` | `POST <baseUrl>/responses`; Anthropic models (its Messages API) `POST <baseUrl>/messages?beta=true` |
  | `anthropic` | `https://api.anthropic.com` | `POST <baseUrl>/v1/messages?beta=true` |
  | `openai` | `https://api.openai.com/v1` | `POST <baseUrl>/responses` (or `/chat/completions`, per the catalog's API for the model) |
  | `amazon-bedrock` | `https://bedrock-runtime.<region>.amazonaws.com` | `POST <baseUrl>/model/<URL-encoded id>/converse-stream` |
  | others | the model's base URL in `GET /v1/models` | as the provider's API appends |

- `apiKey` may be left out for `openrouter`, `anthropic` or `openai` behind a
  `baseUrl`: a gateway that holds the provider's key itself (authenticated by,
  say, `cf-aig-authorization` in `headers`). Its calls send no `Authorization` or
  `x-api-key` header, only the entry's `headers`.
- For `amazon-bedrock` the key is a Bedrock API key, sent as a bearer token (no
  SigV4), and the entry needs its region: `region`, or a regional `baseUrl`
  `https://bedrock-runtime.<region>.amazonaws.com`, which it is read from. Model
  ids are the catalog's inference profiles
  (`amazon-bedrock/us.anthropic.claude-sonnet-5`); see [Amazon Bedrock](https://run.camelai.com/docs/guides/models-and-keys.md#amazon-bedrock).
- `GET /v1/key-scopes/:scope` lists the providers set, with each key's last four
  characters, `baseUrl`, `region` and the extra headers' names, never a secret.
  `DELETE /v1/key-scopes/:scope/providers/:provider` removes an entry, and
  `DELETE /v1/key-scopes/:scope` the whole scope. Scope ids are 1–100 letters,
  digits, `_`, `.` and `-`. Keys and headers are stored sealed, bound to your account, the scope and the provider.
- An agent gets `keyScope` at creation (`POST /v1/agents`,
  the SDKs' `createAgent`), or through `PATCH /v1/agents/:id/configuration`
  (`null` clears it; the agent's own token cannot change it). Applying a
  definition keeps it. Models are named as usual, e.g.
  `openrouter/anthropic/claude-sonnet-5` (a routing variant like `:nitro` too),
  `anthropic/claude-opus-5` or `amazon-bedrock/us.anthropic.claude-sonnet-5`.
  OpenRouter's models are called through its Responses API (stateless, reasoning
  carried back as it came), whatever key they use, except Anthropic's, which keep
  its Messages API for prompt caching: the same rule as on a tenant's endpoint.
- Each model call, compaction summaries included, takes the key of the agent's
  scope for the model's provider, else the tenant's own key, else the
  platform's (see above). It is read at the call, so a changed key applies
  to every agent of the scope from its next call, within five seconds. An agent may be
  created on a provider only its scope has a key for.
- Scope keys are the tenant's own: no platform token charge, like a tenant's key
  (agent time is charged as usual), and their calls are counted in `/v1/usage`
  under the model as usual.
- A scope's (else the tenant's, else the platform's) `openai` key also transcribes
  its agents' audio, and `POST /v1/transcriptions` with that `keyScope` (see
  [Voice and audio](https://run.camelai.com/docs/guides/voice.md)), and makes images for `POST /v1/images` with that
  `keyScope` (see [Images](https://run.camelai.com/docs/guides/images.md)).

## Model headers

`modelHeaders: {name: value}` at creation or through `PATCH
/v1/agents/:id/configuration` are non-secret headers sent on each of the agent's
model calls, compaction included, e.g. `{"cf-aig-metadata": "{\"org\": …, \"thread\": …}"}`
to label a shared gateway's logs per conversation. A PATCH replaces them whole;
`null` or `{}` removes them. They come after a key scope entry's `headers` (and
win on a clash). At most 20 and 8 KB; `authorization`, `x-api-key`,
`x-goog-api-key`, `cf-aig-authorization`, `chatgpt-account-id`,
`x-agent-runtime-identity`, `x-amz-*` and transport headers (`host`,
`content-length`, `content-type`, `transfer-encoding`, `connection`) are refused
with 400. Only the tenant sets them; `GET /v1/agents/:id` shows them.

## Spend limits

`spendLimit: {"usd": n}` at creation or through `PATCH /v1/agents/:id/configuration`
is the most the agent may spend on model calls from then on: their cost as the
[webhooks](https://run.camelai.com/docs/guides/webhooks.md) (`usage.recorded`) reports it (the provider's own when it reports
one, else the catalog price), turns and compaction summaries, whoever's key they
ran on. Setting a value starts counting from zero; `null` removes it. A PATCH applies it at once, ahead of runs already queued. `GET /v1/agents/:id`
shows `spendLimit: {usd, spent}`. An agent at or over its limit gets 402 for new
`prompt` and `continue` runs, and a running turn ends after the response that
crossed it (its tool calls run and are recorded), with `stopped: "spend_limit"`:
the SDKs' `run()` fails with code `spend_limit`. The result's `limit` says which
limit it was: `"run"` (the run's own budget, below), `"agent"` (the agent's),
`"tenant"` (your account's monthly cap) or `"credit"` (your prepaid credit ran out).
Only you can set it, not the agent's own token.

A run can have a budget of its own: `spendLimit: {"usd": n}` on
`POST /v1/agents/:id/prompt` (the SDKs' `run`, `stream` and `prompt` take
`spendLimit`, `spend_limit=` in Python). The run ends the same way once it has
spent that, before its next model request; the agent's own limit is unchanged,
and still counts the run. To give each prompt what is left of a budget you keep,
send it with the prompt instead of reconfiguring the agent.

## Run limits

A run also stops at **1,000 model responses** (compaction summaries count) or
**2 hours** from when it began, whichever comes first, so a model that never stops
calling tools ends on its own. Like a spend limit, the turn ends after the response
that reached the limit (its tool calls run and are recorded), before the next model
request, with `stopped: "turn_limit"` and `code: "turn_limit"`; the reason is in
`error`, e.g. `This run stopped at its limit of 1000 model responses. Send another
message to continue`. The history stays valid: the next message picks up from there.
The SDKs' `run()` fails with code `turn_limit`.

Lower them for an agent with `runLimits: {"maxResponses": n, "maxSeconds": n}` (the
SDKs' `runLimits`, `run_limits=` in Python) when you make it, or with
`PATCH /v1/agents/:id/configuration` (`null` removes them), or for every agent of a
[definition](https://run.camelai.com/docs/guides/definitions.md) with its `runLimits`. An agent's own stay when its
definition is applied. One run can lower them further: `runLimits: {"maxResponses": n,
"maxSeconds": n}` on `POST /v1/agents/:id/prompt` (the SDKs' `run`, `stream`, `prompt`
and `send` take `runLimits`, `run_limits=` in Python) applies to that run alone, and
only where it is lower than the agent's. Values above the runtime's maximums count as the maximums,
which its operator sets (see [Configuration](https://run.camelai.com/docs/operations/configuration.md),
`AGENT_MAX_RUN_RESPONSES`). Only you can set them, not the agent's own token. They are counted on the node running the
turn: a turn resumed on another node after its node was lost counts again from there.

### Context size

A long history is compacted (its older part summarized) before a request would not fit the model's context window.
On a model with a large window that is late: every request reads the whole context, so a long-lived agent pays for
its history on each step long before it nears a million tokens. `runLimits.contextTokens` (at least 20,000) keeps
each of the agent's requests within that many tokens instead: compaction starts in the background somewhat below
it, and the summary, the recent messages and the system prompt carry on from there. Set it like the other run
limits, on the agent or its definition; a single run cannot set it. For a chat agent whose turns mostly need what
happened recently, 100,000 is a reasonable start.

---

<!-- https://run.camelai.com/docs/guides/custom-models.md -->

# Custom models

Any server that speaks OpenAI Chat Completions, OpenAI Responses or Anthropic
Messages can be a provider of your own: a hosted API the catalog lacks, a model
the catalog has not caught up with yet, a gateway, or your own vLLM, Ollama or
LM Studio. You name the provider, list its models, and your agents use them
like catalog models: `<name>/<model id>`. A provider can be your account's, or
one [key scope](https://run.camelai.com/docs/guides/custom-models.md#in-a-key-scope)'s, for one customer's agents only.

```ts
await agents.runtime.setProvider("acme-llm", {
  type: "openai-completions",
  baseUrl: "https://llm.acme.example/v1",
  apiKey: process.env.ACME_LLM_KEY,
  models: [{ id: "acme-70b", contextWindow: 131072, maxOutputTokens: 8192, pricing: { input: 0.6, output: 0.8 } }],
});
const agent = await agents.upsert("support", { model: "acme-llm/acme-70b" });
```

In Python, `await agents.runtime.set_provider("acme-llm", base_url=..., api_key=..., models=[...])`.
Over HTTP, `PUT /v1/providers/acme-llm` with the same body.

## The provider

`PUT /v1/providers/{name}` adds a provider or replaces it:

| Field | |
| --- | --- |
| `type` | the API it speaks: `"openai-completions"`, OpenAI Chat Completions (`POST <baseUrl>/chat/completions`); `"openai-responses"`, OpenAI Responses (`POST <baseUrl>/responses`); `"anthropic-messages"`, Anthropic Messages (`POST <baseUrl>/v1/messages`). All stream |
| `baseUrl` | the API root, public and `https` (see [Where the server can be](https://run.camelai.com/docs/guides/custom-models.md#where-the-server-can-be)): with `/v1` for OpenAI's APIs (`https://api.example.com/v1`), without for Anthropic's (`https://api.example.com`) |
| `apiKey` | sent as `Authorization: Bearer <apiKey>` (`x-api-key` for Anthropic Messages). Leave it out when you save again to keep the stored key; `null` removes it, for a server that takes none |
| `auth` | Anthropic Messages only: `"bearer"` sends the key as `Authorization: Bearer <apiKey>`, as some Anthropic-compatible gateways and proxies take it, instead of `x-api-key` (the default). Saved again without it, `x-api-key` |
| `headers` | more headers for each call, e.g. `{"api-key": "…"}` for a server that takes its key that way. Stored sealed like the key; left out keeps them, `null` removes them. The runtime sets `Authorization` itself |
| `models` | the models to use, 1 to 200 (below) |

- The name is 1 to 40 lowercase letters, digits and `-`. It can't be a built-in
  provider's (`openai`, `groq`, `openrouter` and the rest of
  `GET /v1/providers`) or one of your model endpoints'.
- The key and headers are sealed like your other keys and never shown again.
  `GET /v1/providers` lists your providers after the built-in ones: under
  `custom` their address, header names and models, and under `key` the key's
  last four characters.
- A rotated key, a new address or new headers reach agents at their next model
  call, with no reconfiguration. A model's declaration (its context window,
  pricing, `compat`) is taken when an agent takes the model: agents already on
  it take a changed declaration when configured with it again
  (`PATCH /v1/agents/:id/configuration` with `{"model": "<name>/<id>"}`).
- Deleting the provider (`DELETE /v1/providers/{name}`) fails its agents at
  their next call, until it is set again or they move to another model.
- A [key scope](https://run.camelai.com/docs/guides/models-and-keys.md#key-scopes) can have its own entry for your
  provider (`PUT /v1/key-scopes/{scope}/providers/{name}`, `{apiKey?, baseUrl?,
  headers?}`). Agents in the scope then call with that key, address or headers,
  e.g. each customer's own deployment. What the entry gives replaces the
  provider's own (its `headers` all of the provider's); what it leaves out is the
  provider's, the key included. Deleting the provider deletes its scopes' entries.

## In a key scope

A [key scope](https://run.camelai.com/docs/guides/models-and-keys.md#key-scopes) can have providers of its own, for
its agents only: each customer's own endpoint, under the same name in every
scope.

```bash
curl -X PUT https://run.camelai.com/v1/key-scopes/org_42/model-providers/custom \
  -H "Authorization: Bearer $CAMELAI_API_KEY" -H "Content-Type: application/json" \
  -d '{"type": "openai-responses", "baseUrl": "https://bedrock-mantle.us-west-2.api.aws/openai/v1",
       "apiKey": "'"$ORG_42_BEDROCK_API_KEY"'", "models": [{"id": "openai.gpt-5.6-terra", "contextWindow": 200000, "reasoning": true}]}'
```

An agent in `org_42` (`keyScope: "org_42"`) then names `custom/openai.gpt-5.6-terra`.

- The body, the name's rules and the limits are those of your own providers
  (above): up to 20 per scope, besides your account's 20.
- Only agents in the scope see its providers. An agent elsewhere, in another
  scope or none, that names the model gets `Unknown model`, and its calls never
  use the scope's key. In its scope, a provider shadows one of your account's
  with the same name.
- A model is resolved in the agent's scope when it is made or configured, and
  in the new scope when `PATCH /v1/agents/:id/configuration` moves it (give the
  `model` there too). Definitions name your account's providers only.
- `GET /v1/key-scopes/{scope}/model-providers` lists the scope's (never their
  key or header values), `DELETE …/model-providers/{name}` deletes one, and
  deleting the scope (`DELETE /v1/key-scopes/{scope}`) deletes them all.
  `GET /v1/models?keyScope={scope}` lists models as the scope's agents see them.

## Models

Each model is `{id, contextWindow, maxOutputTokens?, input?, reasoning?, pricing?, compat?}`:

| Field | |
| --- | --- |
| `id` | the model's id on the server, sent as `model`. Agents name it `<provider>/<id>`; an id may contain `/` and `:` |
| `contextWindow` | its context window in tokens. A long history is summarized (compacted) to keep each request within it |
| `maxOutputTokens` | the most it writes in a reply. Default 8,192, or half a smaller context window |
| `input` | `["text", "image"]` for a model that sees images: attached and read images are shown to it. Default `["text"]`: images are described in text |
| `reasoning` | `true` for a model that reasons, so `thinkingLevel` applies |
| `pricing` | `{input, output, cacheRead?, cacheWrite?}` in USD per million tokens. It is what runs cost in usage, [spend limits](https://run.camelai.com/docs/guides/models-and-keys.md#spend-limits) and webhooks. Without it, the model's runs cost 0 |
| `compat` | switches for a server that differs from OpenAI's (below) |

`GET /v1/models` lists your providers' models before the catalog's, all `available`.

A model whose id the catalog knows for the provider's API (Anthropic's models
over Anthropic Messages, OpenAI's over OpenAI's APIs: a gateway in front of
them) is called as the catalog calls it, such as which thinking settings it
takes. What you declare wins, and its price is yours (`pricing`), not the
catalog's.

### Servers that differ from OpenAI's

For Chat Completions servers. The runtime streams, sends tools as OpenAI function tools and reads tool calls
as they arrive in pieces. It copes with what many servers leave out:

- A stream without usage costs nothing and counts no tokens. Set
  `compat.supportsUsageInStreaming: false` if the server refuses
  `stream_options`.
- A server that ends its streams without `finish_reason` needs
  `compat.supportsFinishReason: false`: the reply then ends as a tool call or a
  stop by what came. Without it such a stream fails, rather than risk taking a
  reply cut off mid-way for a whole one.

Other switches, per model:

| `compat` | |
| --- | --- |
| `supportsFinishReason` | `false` for a server that ends streams without `finish_reason` |
| `maxTokensField` | `"max_tokens"` for a server that doesn't take `max_completion_tokens` |
| `supportsDeveloperRole` | `false` sends the system prompt as a `system` message, not `developer` |
| `supportsReasoningEffort` | whether the server takes `reasoning_effort` |
| `thinkingFormat` | how reasoning is asked for: `openai` (`reasoning_effort`), `openrouter`, `deepseek`, `together`, `zai`, `qwen` or `qwen-chat-template` |

## Where the server can be

The runtime calls the address you give from the public internet, through the
same [outbound guard](https://run.camelai.com/docs/guides/tools.md#outbound-calls) as MCP servers and `web_fetch`.
The address is checked when you save the provider, and again at every call:
it must be `https`, and its host must resolve to public addresses only.
Loopback, private and link-local addresses are refused, so `localhost` and your
LAN are unreachable.

A server on your own machine or network needs a public `https` address in front
of it, such as a tunnel. Keep it behind a key: anyone with the address can call
it.

A [self-hosted runtime](https://run.camelai.com/docs/operations/self-host.md#networking) can call servers
on its own network: its operator names each one's exact origin in
`AGENT_OUTBOUND_ALLOW_ORIGINS` (e.g. `http://10.1.2.3:8000` for a vLLM or
Ollama host), which allows that origin alone, over `http` too, and never to
`web_fetch`.

## Billing

Your own providers are yours: their calls never use the platform's keys, and
their tokens are never charged to prepaid credit. Usage records what the
declared `pricing` says each run cost. That feeds spend limits, the usage
pages, and the `usage.recorded` and `run.completed` webhooks.

## Examples

### A Groq model the catalog doesn't have yet

Groq is a built-in provider: set its key (`PUT /v1/providers/groq/key`) and use
`groq/<model>` for any model in `GET /v1/models`. For one the catalog lacks,
add Groq's API under a name of your own:

```bash
curl -X PUT https://run.camelai.com/v1/providers/groq-preview \
  -H "Authorization: Bearer $CAMELAI_API_KEY" -H "Content-Type: application/json" \
  -d '{"type": "openai-completions", "baseUrl": "https://api.groq.com/openai/v1", "apiKey": "'"$GROQ_API_KEY"'",
       "models": [{"id": "new-model-preview", "contextWindow": 131072, "maxOutputTokens": 8192,
                   "pricing": {"input": 0.2, "output": 0.6}}]}'
```

Then name it `groq-preview/new-model-preview`.

### Ollama on your machine, through a tunnel

Ollama serves Chat Completions at `http://localhost:11434/v1`. Give it a public
`https` address with a tunnel. With a [Cloudflare Tunnel](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/),
route a hostname of yours to it (`ollama.example.com` → `http://localhost:11434`)
and put [Cloudflare Access](https://developers.cloudflare.com/cloudflare-one/identity/service-tokens/)
in front with a service token, so only calls carrying the token get through:

```ts
await agents.runtime.setProvider("home-ollama", {
  type: "openai-completions",
  baseUrl: "https://ollama.example.com/v1",
  apiKey: null,
  headers: { "CF-Access-Client-Id": process.env.ACCESS_CLIENT_ID!, "CF-Access-Client-Secret": process.env.ACCESS_CLIENT_SECRET! },
  models: [{ id: "qwen3:32b", contextWindow: 40960, reasoning: true, compat: { maxTokensField: "max_tokens" } }],
});
const agent = await agents.upsert("local-helper", { model: "home-ollama/qwen3:32b" });
```

If the tunnel's address changes, save the provider again with the new
`baseUrl`; agents follow at their next call.

---

<!-- https://run.camelai.com/docs/guides/definitions.md -->

# Definitions

A definition is a reusable agent configuration: name, model, system prompt,
thinking level, tool sources (built-ins, remote MCP servers and OpenAPI specs),
limits (`ttlSeconds`, or `idleTtlSeconds`: a lifetime from each agent's latest run), run limits (`runLimits`, see [Run limits](https://run.camelai.com/docs/guides/models-and-keys.md#run-limits)) and mounts. Manage them with the SDKs
(`agents.runtime.upsertDefinition`, `createDefinition`, `updateDefinition`,
`definition(s)`, `deleteDefinition`; `upsert_definition` and so on in Python),
`/v1/definitions`, or the console's Definitions page, and make agents from one.
`upsertDefinition(key, …)` (`POST /v1/definitions` with an `Idempotency-Key`) is
the one to run at every deploy: the same key is the same definition, set to what
you send (fields left out are cleared), with a new revision only when that
changes it. `createDefinition` makes a new one each time.

```ts
const definition = await agents.runtime.upsertDefinition("support", {
  name: "Support", model: "anthropic/claude-sonnet-5-5", systemPrompt: "You answer support tickets.",
  builtins: ["web_search", "ask_user"],
  mcpServers: [{ name: "app", url: "https://app.example.com/mcp", auth: { type: "runtime" } }],
});
const agent = await agents.upsert(`ticket-${ticket.id}`, { definition: definition.id, subject: ticket.customerId });
```

Saving a definition lists its MCP servers: credentials a server refuses are a
400 that says so, and the answer's `toolSources` shows what each offers.

A definition is where a source's credentials go: they are sealed once, for all
its agents. An agent without a definition, or a stateless run, can list MCP
servers of its own, but without credentials (identity tokens or none); see
[An agent's own MCP servers](https://run.camelai.com/docs/guides/tools.md#an-agents-own-mcp-servers). An agent made
from a definition has only its definition's sources.

Each MCP server and OpenAPI source takes `exposure`: `"direct"` (the model calls
its tools itself), `"codemode"` (only from code in `js_exec`) or `"both"`. Left
out, a source of up to 10 tools is `both` and a larger one `codemode`, so by
default the model can call them from `js_exec`. Set `"direct"` on a source whose
tools must never be called from code; see
[Keeping tools out of js_exec](https://run.camelai.com/docs/guides/tools.md#keeping-tools-out-of-js_exec).

A `description` (1–1,000 characters) says what its agents are for; models see it
as the description of each agent's [MCP tool](https://run.camelai.com/docs/guides/mcp-server.md), and as what it is
for when another definition can delegate to it.

`delegate`, with its builtin, lets its agents hand tasks to sub-agents:
`"builtins": ["delegate"], "delegate": {"agents": ["researcher"]}`. It may name
definitions not saved yet, so two can name each other. See
[Multi-agent](https://run.camelai.com/docs/guides/multi-agent.md).

The definition supplies the model, prompt, thinking level, `maxOutputTokens`,
`temperature` and tool sources;
`name`, `ttlSeconds` (or `idleTtlSeconds`), `mounts` and `initialMessages` given alongside it override
its defaults, and tools of your process (`tools`) are added as its attached
server.

An agent can also have configuration of its own, which applying its definition
leaves alone:

```json
{"definition": "def_…", "model": "anthropic/claude-opus-5", "thinkingLevel": "low",
 "systemPromptAppend": "Thread thr_123 in workspace ws_9."}
```

- `model`, `thinkingLevel`, `maxOutputTokens`, `temperature` and `runLimits` given
  at creation, or later through `PATCH /v1/agents/:id/configuration`, and
  `fileTools` given at creation, are the agent's own: an apply changes every other
  field and keeps them. `null` set through configuration is the agent's own too.
  An agent's own temperature that the definition's new model or thinking level
  cannot take is left out of its calls (see
  [Output length and temperature](https://run.camelai.com/docs/guides/models-and-keys.md#output-length-and-temperature)).
- `systemPromptAppend` is text the model reads after the definition's prompt
  (after the runtime's default prompt without one), e.g. per-conversation
  context. An apply replaces the prompt and keeps the addition; configuring
  `systemPromptAppend` changes it, and `""` removes it. Agents not made from a
  definition can have one too.
- `systemPrompt` cannot be given with a definition: the definition owns the
  prompt, so an apply would silently replace it. A `systemPrompt` configured
  on one agent later lasts until the next apply.

Every change is a new revision (`PATCH` replaces the fields given; `null`
removes one; `revision` makes it conditional). An agent records the definition
and revision it was made from (`definition` in `GET /v1/agents/:id`), and keeps
that configuration when the definition changes: only new agents get the new
revision. `PATCH … {"apply": "all"}` also reconfigures every live agent made
from the definition, through each agent's `configure` request, queued behind its
runs so it lands between turns; the application's attached tools are kept, and
the tool lists the runtime holds for the definition's MCP servers are read again,
so a server that changed its tools with the deploy is seen at once. Only
the tenant can apply a definition, never an agent's own token. `GET
/v1/definitions/:id/agents` lists the agents and the revision each has. Deleting
a definition leaves its agents as they are; a definition a channel uses cannot
be deleted.

To have every change reach live agents without asking each time, save the
definition with `applyOnUpdate: true`: every save that makes a new revision (an
upsert that changes it, or a `PATCH`) then applies it as `apply: "all"` does,
and answers with `applied`. An upsert that changes nothing, as at most deploys,
applies nothing. It suits definitions whose agents must all run the same tools
and prompt, such as one whose MCP server moved:

```ts
const definition = await agents.runtime.upsertDefinition("builder", {
  name: "Builder", systemPrompt: "You build bots.", applyOnUpdate: true,
  mcpServers: [{ name: "builder", url: "https://bots.example.com/builder/mcp", auth: { type: "runtime" } }],
});
// definition.applied: every live agent asked to take the new revision, when this deploy changed it
```

The response's `applied` lists each agent with its `requestId` and `status`:
`updated` (it has the revision), `queued` (it takes it after its current turn;
poll `GET /v1/agents/:id/requests/:requestId` for the outcome) or `failed`, with
an `error`. On the console's Channels page, **Model & prompt** opens a channel's
definition with apply selected.

`PATCH /v1/agents/:id/configuration` changes one agent's `model`,
`systemPrompt`, `systemPromptAppend`, `thinkingLevel`, `maxOutputTokens`, `temperature`, `keyScope`, `spendLimit` or `modelHeaders` without touching its definition or history:

```http
PATCH /v1/agents/client_…/configuration
Authorization: Bearer <API token>
Content-Type: application/json

{"requestId": "model-change-1", "model": "openrouter/openai/gpt-6-luna"}
```

It answers `202` with the request, which is queued like an applied definition
and survives a restart; poll it for the outcome, and reuse `requestId` to retry.
A model must be in `GET /v1/models`, and the tenant must have a key for its
provider, or the change is refused with `400`. So is a `temperature` the agent's
model or thinking level, after the change, cannot take. An agent that is not running
takes the change when it next starts.

---

<!-- https://run.camelai.com/docs/guides/multi-agent.md -->

# Multi-agent: sub-agents

The `delegate` built-in lets an agent hand a task to a **sub-agent** and get its
answer back as the call's result, while it keeps the conversation. This is the
OpenAI Agents SDK's `agent.as_tool()` and LangGraph's supervisor. The runtime
runs it, and it is durable: a sub-agent is an agent of its own, and a parent
whose node is lost while it waits collects the sub-agent's answer on another
node.

The `agents` built-in starts sub-agents in the **background** instead: the
model goes on at once, and each one's answer arrives as a message of its own
when it ends. See [Background sub-agents](https://run.camelai.com/docs/guides/multi-agent.md#background-sub-agents).

camelRun has no handoffs: an agent cannot pass its conversation to another
agent. See [Coming from the OpenAI Agents SDK](https://run.camelai.com/docs/guides/multi-agent.md#coming-from-the-openai-agents-sdk).

## Sub-agents: `delegate`

Give an agent the `delegate` builtin and say whom it may delegate to: its
`agents`, by definition key or id. The SDKs add the builtin when you pass the
settings.

```ts
await agents.runtime.upsertDefinition("researcher", {
  name: "Researcher", description: "Finds sources and summarizes them",
  systemPrompt: "You research a question and answer with sources.", builtins: ["web_search", "web_fetch"],
});

const lead = await agents.upsert("research-lead", {
  instructions: "You plan research and write the report. Delegate each question to the researcher.",
  delegate: { agents: ["researcher"] },
});
const run = await lead.run("Compare the three largest EV makers' 2025 margins.");
```

```python
await agents.runtime.upsert_definition("researcher", name="Researcher", description="Finds sources and summarizes them",
    systemPrompt="You research a question and answer with sources.", builtins=["web_search", "web_fetch"])

lead = await agents.upsert("research-lead",
    instructions="You plan research and write the report. Delegate each question to the researcher.",
    delegate={"agents": ["researcher"]})
run = await lead.run("Compare the three largest EV makers' 2025 margins.")
```

A definition takes the same settings, for every agent made from it:

```json
{ "name": "Research lead", "systemPrompt": "…", "builtins": ["delegate"], "delegate": { "agents": ["researcher", "writer"] } }
```

The model gets a `delegate` tool that lists the agents with what each is for
(the definition's `description`, unless the entry gives its own):

| Argument | |
| --- | --- |
| `agent` | Which agent, by its name in the list |
| `instructions` | Instead of `agent`, with `instructions: true` in the settings: a system prompt for a sub-agent the model designs itself, on its own model |
| `task` | What to do. The sub-agent sees only this, not the conversation |
| `output` | A JSON Schema for an object: the answer comes back in that shape (see [Structured output](https://run.camelai.com/docs/guides/structured-output.md)) |

The call's result is `{ agentId, requestId, status, text, output?, error? }`.
`status` is `completed`, `input_required` (the sub-agent waits on a person) or
`failed`. The model sees a failed or waiting sub-agent as a failed call, with
the reason.

### Who the sub-agent is

An entry in `agents` is one of these:

| Entry | The sub-agent |
| --- | --- |
| `"researcher"` or `{ definition: "researcher", name?, description? }` | A new agent made from the definition, for each call |
| `{ agent: "billing-specialist", name?, description? }` | Your existing agent with that key. It keeps its own history across calls. Runs queue, one at a time, like any of its runs |
| `instructions: true` (a setting, not an entry) | A new agent with the model's instructions, the parent's model, and the parent's `web_search` and `web_fetch` if it has them |

A sub-agent the runtime makes is a real agent:

- It is **linked to its parent**: `parentAgentId` and `parentRunId` in
  `GET /v1/agents/{id}` and the agent list, and in the metadata of its run.
- It **acts for whom the parent acts** (`subject`, `context`) and uses the
  parent's key scope. It is billed to the same account. Its tool servers'
  [identity tokens](https://run.camelai.com/docs/guides/tools.md) also name its parent and its chain's first agent
  (`par` and `root`; `identity.parentAgentId` and `rootAgentId` in the SDKs).
- It has its **own workspace**. Pass it what it needs in the task, or mount a
  shared [volume](https://run.camelai.com/docs/guides/files.md#volumes) in both definitions.
- It **lives a day**, as a scratch agent does. Read its history in the meantime
  with its id, from `run.toolCalls`:

```ts
const call = run.toolCalls.find(call => call.tool === "delegate");
const child = await agents.get(call.agentId!);
console.log(await child.history());
```

### Parallel sub-agents

The model may call `delegate` several times in one response. The calls run at
once, up to `maxParallel` (default 4) per run; the rest wait their turn. This is
map-reduce: one call per item, and the model combines the answers.

```ts
delegate: { agents: ["researcher"], maxParallel: 8 }
```

### Limits

Sub-agents are agents, so everything that bounds agents bounds them, and the
parent's limits cover them:

| Limit | |
| --- | --- |
| Depth | A sub-agent's sub-agents count. Delegation stops at `maxDepth` (default 2: a parent, its children and theirs; at most 5). Past it, the call fails and the model does the work itself. Only the runtime places a run in a chain: its child runs' `delegation*` metadata is signed (`delegationSignature`), and a prompt of yours that sends those keys starts a chain of its own |
| Fan-out | `maxParallel` calls in flight per run (default 4, at most 16) |
| Busy agents | A running sub-agent takes one of your account's busy slots. At the limit, the call fails with `BUSY_AGENT_LIMIT` |
| Spend | Your account's spend limits apply to sub-agents too. A parent's own spend limits (the agent's, and the run's `spendLimit`) bound its sub-agents: each gets what the parent has left as its run's spend limit (shared evenly among sub-agents running at once), and what it spent counts against the parent's. `run.usage.subagentCostUsd` says how much that was |
| Run rate and run limits | A sub-agent's run counts against your account's run rate. Its definition's `runLimits` apply to it |

Parallel sub-agents split what the parent has left: each holds its share until
it ends, and a later call gets an even share of what no running sub-agent
holds. So together they stay within the parent's limit, but for the one
response each may finish past its own.

An agent cannot delegate to an agent already working on its chain (it would
wait on itself), and an agent's own key cannot change any of these settings.
The model calls `delegate` directly, never from `js_exec`.

### Cancelling

Aborting the parent's run (`agent.abort()`, `POST /v1/agents/{id}/abort`)
aborts the sub-agents it is waiting on (and cancels the parent's queued runs). So does deleting the parent. A named
agent is aborted only while it runs the parent's task, never another.

### When a node is lost

A sub-agent is keyed by the parent's tool call, and its run by the call too. If
the parent's node is lost while it waits, the parent's run resumes on another
node and makes the call again. That call finds the same sub-agent and run, and
waits for its answer; the task never runs twice. The sub-agent, if its own node
was lost, resumes like any agent.

### Watching sub-agents

A sub-agent's progress can appear on its parent's event stream. Ask for it:
`subagents: true` in the SDKs, or `?subagents=1` on the events URL. Without it
you get none of these events.

| Event | |
| --- | --- |
| `subagent_start` | `{ toolCallId, agentId, requestId, name, depth }`: the call started its sub-agent |
| `subagent_event` | `{ toolCallId, agentId, event }`: one of the sub-agent's events (its streamed text left out). A grandchild's events arrive nested in its parent's |
| `subagent_end` | `{ toolCallId, agentId, requestId, status, error? }` |

```ts
const lead = await agents.upsert("research-lead", { delegate: { agents: ["researcher"] }, subagents: true });
for await (const part of lead.stream("…")) {
  if (part.type === "subagent_start") console.log(`→ ${part.name} (${part.agentId})`);
  if (part.type === "subagent_end") console.log(`← ${part.agentId}: ${part.status}`);
}
```

In a browser, the watcher (`@camelai/run/watch`, with `subagents: true`) folds
them into `state.subagents`, by delegate call, and a chat made with
`watch: { subagents: true }` shows each sub-agent as a collapsible transcript
under its call in `<AgentChat>` (`part.subagent` for a tool renderer of your own).
A browser token that lists its `events` needs these types listed too.

A sub-agent's events are relayed while it runs on the same node as its parent,
which it does unless a node was lost; its own stream and history always have
everything.

## Background sub-agents

The `agents` builtin gives the model five tools, with the same `delegate`
settings (whom it may start, `maxDepth`, `maxParallel`). The builtin needs them,
as `delegate` does; an agent may have both builtins.

```ts
const lead = await agents.upsert("research-lead", {
  instructions: "Start a researcher for each question, and write the report as their answers come in.",
  builtins: ["agents"], delegate: { agents: ["researcher"], maxParallel: 8 },
});
```

| Tool | |
| --- | --- |
| `spawn_agent({ agent \| instructions, task, output?, name? })` | Starts a sub-agent, as `delegate` would, and returns `{ agentId, name }` at once. `name` is the model's handle for it, unique among its running sub-agents (default: the agent's name and a number, `researcher-1`) |
| `wait_agent({ agents?, timeoutMs? })` | Waits until one of the given sub-agents (names or ids; default: any running one) ends, or `timeoutMs` passes (default 5 minutes, at most 10). Returns each one's `status`, with the answer (`text`, `output?`, `error?`) of those that ended |
| `list_agents()` | The agent's sub-agents: `{ agentId, name, status, startedAt, endedAt? }`, `status` being `running`, `completed`, `failed`, `aborted` or `input_required` |
| `send_message({ to, text })` | Messages one of its sub-agents (name or id) or, from a sub-agent, its parent (`"parent"`). See [Messages](https://run.camelai.com/docs/guides/multi-agent.md#messages) |
| `interrupt_agent({ agent })` | Aborts one of its running sub-agents; its notification follows with status `aborted` |

The sub-agent is the same as a delegated one: the same targets, chain and
depth limit, identity and key scope, and it lives a day. Its run's spend limit
is a share of what its parent agent may still spend (its `spendLimit`): what no
running sub-agent holds, split evenly among the slots `maxParallel` leaves, so
sub-agents started together share it rather than each getting all of it. A stateless run
(`POST /v1/runs`) cannot start one: nothing would hear it end.

### Notifications

When a sub-agent's run ends (completed, failed, aborted, or waiting on a
person), the runtime sends its parent a prompt with request id
`child_<the child's request id>`. It queues behind the parent's running turn,
or starts a turn if the parent is idle. Its message is a user message with a
source of its own, in history, events and exports:

```json
{ "role": "user", "content": [{ "type": "text", "text": "Found 3 sources: …" }],
  "source": { "kind": "agent", "agentId": "client_…", "name": "researcher-1" }, "requestId": "child_spawn_…",
  "metadata": { "agentId": "client_…", "name": "researcher-1", "status": "completed", "output": { … }, "usage": { … } } }
```

The model reads it in a block only the runtime writes, never as the person:

```text
<agent_notification name="researcher-1" status="completed">
Found 3 sources: …
</agent_notification>
```

The sub-agent's text cannot close the block or open another: such tags in it
(and in any user message or tool result) are neutralized, as sender blocks are.
UIs should render a message with `source` as a notification, not as the user.

A sub-agent whose ending a `wait_agent` call answered adds no notification:
one already on its way ends without its message (`result.skipped`).
A parent waiting on a person (an approval, `ask_user`) gets its notifications
once they answer: a new message would supersede what it asked.

A sub-agent that waits on a person notifies with status `input_required`, and
`metadata.inputs` lists what it asked. Answer its inputs as any agent's
(`POST /v1/agents/{child}/inputs/{id}`, or a browser token with the `children`
scope reads them); it resumes, and its next ending notifies again.

### Messages

`send_message` goes between an agent and its own sub-agents and parent, no one
else:

- **Parent to sub-agent:** the text joins the sub-agent's running turn, or
  starts a turn that keeps its history. A sub-agent that had finished works
  again, and its answer comes back as a new notification. The sub-agent reads
  `<agent_message name="parent">…</agent_message>`.
- **Sub-agent to parent:** `to: "parent"`, which the runtime resolves through
  the run's signed chain. It reaches the parent as a notification does, without
  the sub-agent's turn ending, as `<agent_message name="researcher-1">…`, with
  `source` and `metadata.kind: "message"`. The parent's stream has
  `subagent_message` (`{ agentId, name, text }`). A sub-agent the runtime made has
  `send_message` even without the builtin.

A turn sends at most 20 messages, and the turns messages start count against
the wake cap below, so two agents messaging each other stop.

### Stopping sub-agents

- `interrupt_agent`, or `POST /v1/agents/{child}/abort` for one sub-agent: its
  turn is aborted, and its parent's notification says `aborted`.
- Aborting the parent (`agent.abort()`, `POST /v1/agents/{id}/abort`) aborts its
  running sub-agents too. `{ "children": "keep" }` (`abort({ children: "keep" })`)
  leaves them running.
- An abort never drops a notification: one waiting for its turn, or about to
  start it, lands in history without a turn (its run ends `aborted`).
- Deleting the parent aborts its running sub-agents and deletes the ones the
  runtime made. Named agents it started (`{ agent: "…" }` targets) stay.

### Exactly once

Each sub-agent has a row in `agent_children`, written before its prompt is sent
and keyed by the `spawn_agent` call, so a turn resumed on another node finds
the same sub-agent and never starts a second. Its ending is delivered by the node
that ran it, as the run ends, and otherwise by a sweep on any node (every
`AGENT_CHILD_SWEEP_MS`, default 15 s). Every delivery sends the same request,
which the parent takes once, so a node lost on the way (the sub-agent's, the
parent's, or both) delays the notification by a sweep and never repeats it.

### Cost and loop guards

- What the sub-agent spent is charged to the parent's spend limit when its
  notification lands (or its `wait_agent` answers it), and shows in that run's
  `usage.subagentCostUsd`.
- Spend limits apply to the turns notifications start. A parent at its limit
  gets the notification in history, without a turn: the run ends with
  `stopped: "spend_limit"`.
- Notifications and messages may start at most `AGENT_WAKES_PER_HOUR` turns
  (default 100) per chain of agents (counted by its first agent) and clock hour,
  so agents that keep starting each other stop. Past it, a notification or
  message lands in history without a turn, and its run ends with
  `stopped: "agent_loop_limit"`, naming the limit. Send the agent a message to
  go on. A refusal is recorded before the message lands, so a node lost then
  never lets the turn run on another.
- At most `maxParallel` sub-agents run at once per parent; past it,
  `spawn_agent` fails and the model waits for one.

### Events

With `?subagents=1` (`subagents: true` in the SDKs), the parent's stream has
`subagent_start` (with `background: true`) when a sub-agent starts,
`subagent_event` with its events while it runs on the parent's node, and
`subagent_end` (with `background: true`, `name` and `status`) when its
notification lands or a `wait_agent` answers it, and `subagent_message` when it
messages its parent. Its own stream and history always have everything.

A browser token minted with the `children` scope (with the others it needs:
`{ "scopes": ["events", "history", "children"] }`) reads the agent's sub-agents
too, by their ids, as it reads the agent: a chat can reload a sub-agent's
transcript with its parent's token.

### Workers your tools prepare

A tool can start a sub-agent for the model, so the model never names an agent:
your tool does the authorization and setup with your API key, and answers with
a spawn directive. Use it for workers per customer object (a bot, a repo, a
ticket) that keep their history across tasks.

```ts
import { serveTools, spawnAgent } from "@camelai/run/server";
import { tool, schema } from "@camelai/run";

export default { fetch: serveTools({
  work_on_bot: tool({
    description: "Hand a task to the bot's worker", input: schema.Object({ bot: schema.String(), task: schema.String() }),
    execute: async ({ bot, task }, { identity }) => {
      await assertOwnsBot(identity!.rootAgentId ?? identity!.agent, bot);
      const worker = await agents.upsert(`bot-worker-${bot}`, { instructions: "You maintain one bot." });
      return spawnAgent({ agent: worker.id, task, name: `bot-${bot}` });
    },
  }),
}, { runtime: "https://run.camelai.com", tenant: "acme" }) };
```

```python
from camelai_run import spawn_agent, tool

@tool
async def work_on_bot(bot: str, task: str) -> dict:
    """Hand a task to the bot's worker"""
    worker = await agents.upsert(f"bot-worker-{bot}", instructions="You maintain one bot.")
    return spawn_agent(worker.id, task, name=f"bot-{bot}")
```

The directive is `_meta["camelrun/spawn"]: { agent, task, name?, output? }` on
the tool's result, if you answer MCP yourself. The runtime takes it only from a
tool server with auth `"runtime"` (a definition's or the agent's own), and checks
that the agent is your tenant's, is not already in the calling agent's chain,
and that the depth and `maxParallel` limits allow it (the calling agent's
`delegate` settings, or the defaults). An agent that starts sub-agents only
through your tools can set those limits alone, `delegate: { maxParallel, maxDepth }`
without the `delegate` or `agents` builtin, which gives the model no tool of
its own to start them. The model's call then answers
`{ agentId, name }`, and the worker's answer arrives as a notification. The
calling agent needs no `agents` builtin for this.

A worker is an agent of its own, so its runs go one at a time: a task given to
a worker that is busy queues behind its current run (the call answers
`queued: true`), and each task notifies when it ends. Deleting the parent leaves
such workers alone; aborting it aborts the worker only while it runs the
parent's task.

### In the SDKs and UIs

- `agentNotice(message)` (Python `agent_notice`) tells a history message the
  runtime wrote apart: `{ kind: "notification" | "message", agentId, name, status?, error?, output?, usage?, inputs? }`
  (a notification's structured `output`, its `usage`, and the `inputs` it waits on), or undefined for anyone else's.
- `stream()` parts and watcher events include `subagent_message`;
  `abort({ children: "keep" })` keeps background sub-agents running.
- `<AgentChat>` shows notifications and agent messages as collapsible notices
  (`AgentNotice`), never as the user's bubbles; the chat model's
  `UserChatMessage.agent` says which (`labels.agentNotification` and
  `labels.agentMessage` name them).
- Tool servers read `identity.parentAgentId` and `identity.rootAgentId` in a
  sub-agent's calls.

## Coming from the OpenAI Agents SDK

| OpenAI Agents SDK | camelRun |
| --- | --- |
| `agent.as_tool(tool_name, tool_description)` | `delegate: { agents: [{ name, definition, description }] }` |
| Agents as tools in parallel (`asyncio.gather` in a tool) | Several `delegate` calls in one response run at once (`maxParallel`) |
| `handoffs=[…]`, `handoff()` | Not supported: there are no handoffs. Delegate to the specialist instead: the conversation stays with the first agent, which relays the answer. Or route in your code, running the agent the message is for (see [Migrating](https://run.camelai.com/docs/guides/migrating.md#handoffs-and-multi-agent)) |
| `max_turns` | The run's `runLimits`, and `delegate.maxDepth` for chains of agents |

## Coming from LangGraph

| LangGraph | camelRun |
| --- | --- |
| Supervisor (`create_supervisor`, or a supervisor node routing to workers) | A lead agent with `delegate: { agents: [...] }`: the model routes, workers answer as tool results |
| Subgraphs (a compiled graph as a node) | A definition per subgraph, delegated to. Its history is its own agent's |
| `Send` (map-reduce over items) | Parallel `delegate` calls, one per item |
| Swarm (`create_swarm`), `Command(goto=…)` | Not supported: there are no handoffs. Use a supervisor (`delegate`) instead |
| Shared state between nodes | The task text, and a shared [volume](https://run.camelai.com/docs/guides/files.md#volumes) |
| `recursion_limit` | `delegate.maxDepth` and the run's `runLimits` |
| Checkpointed subgraph state | Each sub-agent's own history, read by its id (`run.toolCalls[i].agentId`) |

---

<!-- https://run.camelai.com/docs/guides/channels.md -->

# Channels

A channel lets people talk to agents from a messaging service (Telegram, Slack,
Discord or email), or has agents answer activity on GitHub. A `webhook` channel lets any service that sends webhooks (Sentry,
Linear, Stripe, your own) start agents; see [Generic webhooks](https://run.camelai.com/docs/guides/channels.md#generic-webhooks). Tenants manage channels with `/v1/channels` or the console's Channels page:

```sh
curl -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"type":"telegram","credentials":{"botToken":"<from @BotFather>"},
       "definition":"def_…","access":{"allow":["@ada","123456789"]}}' \
  https://run.camelai.com/v1/channels
```

Each conversation's agent is made from the channel's `definition`. A channel
created without one gets an empty definition of its own, which is deleted with
the channel.

| Service | Credentials | Messages arrive | A conversation (one agent) is |
| --- | --- | --- | --- |
| `telegram` | `botToken` | webhook, registered for you | a chat |
| `slack` | `botToken` (`xoxb-…`), `signingSecret` | webhook, pasted into the app | a thread started by an @mention, or a DM |
| `discord` | `botToken` | the Gateway (a WebSocket) | a DM, or a channel or thread where the bot is @mentioned |
| `discord-managed` | none from the customer; one Discord authorization from the console | Camel's shared Gateway | an allowed server channel or thread where Camel is @mentioned |
| `github` | `appId`, `privateKey`, `webhookSecret` | webhook, pasted into the GitHub App | a pull request or issue |
| `webhook` | `secret`, optional `replyUrl` | webhook, pasted into the sending service | whatever the `key` template names (one agent by default) |
| `email` | none | SES, on the runtime's domain | an email thread |

Creating a channel checks its credentials with the service. Credentials and a
random webhook secret are stored encrypted; the API returns only masked values.

- **Telegram.** `https://run.camelai.com/channels/telegram/<id>` is registered as the
  bot's webhook with the random secret, which each delivery must echo (compared
  in constant time). Deleting the channel removes the webhook. `/start` gets the
  channel's `greeting` without a model call.
- **Slack.** Create an app with the bot scopes `app_mentions:read`, `chat:write`,
  `im:history`, `channels:history` (and `groups:history` for private channels),
  `files:read` (attachments in) and `files:write` (files out), and install it. Slack has no API to set an app's event URL,
  so paste the channel's `webhookUrl` into Event Subscriptions and subscribe to
  `app_mention`, `message.im` and `message.channels`. Deliveries must carry a
  valid `X-Slack-Signature` from the signing secret, at most five minutes old; the
  URL check is answered once it verifies. A mention starts a thread and replies go
  there; later messages in that thread reach its agent without a mention. The
  same message sent as both `app_mention` and `message` is handled once. Slack has
  no typing indicator for bots.
- **Discord.** Create an application, add a bot, and invite it with View
  Channel, Send Messages, Send Messages in Threads, Attach Files and Read
  Message History.
  There is no webhook for ordinary messages: the runtime keeps the bot's Gateway
  connection itself, reconnecting and resuming as needed. A token Discord rejects
  is retried every five minutes. The bot needs no privileged intents: it
  answers only DMs and messages that mention the bot user. A mention of a role
  with the bot's name does not count: in autocomplete, pick the entry with the
  App badge. Replies never ping anyone (`allowed_mentions` is empty). The health
  log counts messages received, accepted and ignored by reason, and a message
  ignored as a role mention (`role_mention_without_bot_mention`) or as empty is
  logged with its id. Once the token is saved, the console shows an invite link
  and a test mention to paste into Discord.

- **GitHub.** Create a GitHub App with the repository permissions Pull requests
  (read and write), Issues (read and write), Contents (read) and Metadata (read),
  subscribe it to Pull request, Issue comment, Pull request review comment (and
  Issues, if you choose `issues.opened`), generate a private key, set a webhook
  secret, and install it on the repositories it should see. Create the channel
  with the App ID, the private key (PEM) and the secret, which the runtime checks
  by calling `GET /app` with a JWT the key signs; then paste the channel's
  `webhookUrl` into the app's Webhook URL. Deliveries must carry a valid
  `X-Hub-Signature-256` and are deduplicated by `X-GitHub-Delivery`; pings are
  answered. Each pull request or issue gets its own agent. The prompt describes
  the event (marked `[From GitHub]`) and a pull request's current diff is
  attached as `pr-<n>.diff`. The reply is a comment on the pull request or issue,
  posted with an installation token scoped to the app's installation; files are
  sent as links. Nothing the app does itself (its comments, pushes by its token)
  starts a turn. The channel's `settings` choose what does:

  | Setting | Default | Meaning |
  | --- | --- | --- |
  | `events` | all but `issues.opened` | Some of `pull_request.opened`, `pull_request.reopened`, `pull_request.ready_for_review`, `pull_request.synchronize` (new commits), `issue_comment` and `pull_request_review_comment` (comments that @mention the app), `issues.opened` |
  | `repos` | every repository the app is installed on | `owner/repo` or `owner/*` |
  | `ignoreDrafts` | `true` | Draft pull requests start nothing until marked ready |
  | `reply` | `comment` | `none`: replies and `send_message` are not posted; the agent acts through its tools (a GitHub MCP server in its definition, say) |
  | `authors` | `allowlist` | `members`: repository owners, members and collaborators need no allowlist entry |
  | `debounceSeconds` | `30` | New commits wait this long for more; a burst of pushes starts one turn, on the latest |

  The allowlist takes GitHub logins. Pull requests, issues and comments are
  written by whoever can open them, which on a public repository is anyone: treat
  them as untrusted input (prompt injection), keep `access.public` off, and give
  the agent's tools no more than the conversation needs.

## Add the Camel Discord bot

When the runtime operator enables the managed Discord integration, the console's
Channels page offers **Add Camel to Discord** alongside the existing channel
setup. It opens Discord, where you choose a server you own or have Manage Server
in and authorize Camel; that single step adds the bot and connects the server to
your camelRun account. You do not need to create a Discord application or copy a
bot token. Back in the console, the server's settings open. One server belongs to
one camelRun account at a time.

Choose an existing definition, or create one with the prompt, model and tools
you want. Select allowed channels explicitly, then choose which members may
interact: a Discord user-ID allowlist or all members. Saving activates the
server; until then Camel does not answer there. Each channel or thread has its
own persistent agent, with history shared by the people using that
conversation. Every new turn requires a direct mention of the Camel bot user; a
same-named role mention does not count. Direct messages are ignored.

Members who can interact may invoke the definition's tools using your camelRun
account's credentials. Select tools and allowed members accordingly. Usage is
billed to the connected account, with its normal credit and spending controls.
The managed integration offers per-sender rate limits and a daily turn limit;
it does not yet offer an aggregate dollar budget across a server's agents. A
definition with the `schedule` builtin cannot serve a server (any member could
have the agent wake itself up outside those limits), and turns you start through
the API count against the server's daily limit. An account connects at most 10
servers, or one while on free credit, which also caps each server at 500 turns a
day.

Use **Configure** to edit the selected definition, including tools, and apply it to
existing conversations; the console reports updated, queued or failed outcomes
using the normal [definition revision mechanism](https://run.camelai.com/docs/guides/definitions.md).

Pause stops new routing and pending sends; resume requires Camel to be in the
server. Disconnect retains conversation history and stops routing; it does not
remove Camel from Discord. Removing Camel from the server disconnects it, and
adding it again requires explicit reactivation. A temporary Discord server
outage is tracked separately from removal. A successful configuration save is
not proof that Discord delivered a reply: test with a fresh mention in an
allowed channel.

A server's administrators decide who runs Camel there. To move a server to
another camelRun account, remove Camel from the server, then add it again from
that account. The previous account keeps its past conversations but sees no new
ones. If Camel finds itself in a server nobody added through camelRun, it leaves
when mentioned.

Managed channels are created through console setup, rather than generic
`POST /v1/channels`. The existing `discord` provider and customer-owned bot flow
remain available. Operators can find the platform setup and pilot boundaries in
[Managed Discord operations](https://run.camelai.com/docs/operations/managed-discord.md).

## Shared channel behavior

What they all share:

- Each external conversation gets its own agent, made on first contact from
  the channel's definition, at its revision then.
- Senders must be on the allowlist unless the channel sets `access.public`:
  Telegram and Discord user ids or @usernames, Slack member ids (`U0123ABCD`).
  Each sender is rate limited (`limits.perSenderPerMinute`, default 10) and the
  channel has a daily turn cap (`limits.turnsPerDay`, default 1000).
- Each message carries its sender as `from` (see [Who sent a message](https://run.camelai.com/docs/guides/multi-user.md#one-agent-per-user-or-conversation)), and tool calls carry a runtime-set `origin`
  (`{channel, conversationId, sender}`, `context.origin` in the SDKs) that
  tools can authorize against.
- Attachments of any type (Telegram photos, documents, audio, voice notes,
  videos and animations; Slack files; Discord attachments) are streamed into the
  agent's workspace at `uploads/<requestId>/<name>` and the prompt refers to
  them by path (`files: [{path}]`), as in [Attaching files](https://run.camelai.com/docs/guides/files.md#attaching-files-to-a-message).
  Up to 10 files and 25 MiB each (20 MB on Telegram, the most a bot may
  download), 100 MiB per message. Downloads go only to the service's file host
  (Slack's with the bot token, Discord's CDN, Telegram's file API), never follow
  redirects, and have 60 seconds each. A file too large or that fails to
  download is left out, and the prompt says so: `(file big.zip too large, not
  attached)`. A message with only files reads `(sent a file)`. Audio (voice
  notes, audio files) is transcribed for the model as it arrives: see
  [Voice and audio](https://run.camelai.com/docs/guides/voice.md).
- The turn's final answer is sent back when the turn ends, split to the
  service's limit (4,096 characters on Telegram, 4,000 on Slack, 2,000 on
  Discord), with a typing indicator meanwhile where the service has one. Channel
  agents also get a `send_message` tool for updates mid-turn, which takes
  `files` too: paths in the agent's mounts, each checked and pinned to its
  current version when the tool is called.
- Files the turn presents (`present_file`, the run's `result.presented`) follow
  the reply's text, each with its caption: on Telegram images (JPEG, PNG, WebP,
  up to 10 MB) as photos and anything else as documents (up to 50 MB); on Slack
  through the external upload (`files.getUploadURLExternal`, the bytes, then
  `files.completeUploadExternal` into the thread; up to 100 MiB); on Discord as
  a multipart attachment (up to 10 MiB, the limit in servers without boosts). A
  file over the service's limit is sent as a [signed link](https://run.camelai.com/docs/guides/files.md#signed-links) that
  works for 24 hours, the longest a link may last.
- A message is recorded durably before it is acknowledged, and duplicates
  (provider retries, a Gateway resume) are dropped by message id for seven days.
  Replies go through a durable outbox: a failed send is retried with backoff,
  each message is sent once, and a permanent failure
  (the bot was removed from the chat) is not retried. Each part of the text and
  each file is a step recorded as it is sent, so a retry resumes after the last
  one sent rather than sending the reply again.

## Generic webhooks

A `webhook` channel turns each delivery from any service into a prompt. Give it
the secret the service signs with (or make one up and give it to the service),
then point the service at the channel's `webhookUrl`:

```sh
curl -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"type":"webhook","credentials":{"secret":"<the signing secret>"},"definition":"def_…",
       "settings":{"signature":{"type":"hmac-sha256","header":"Sentry-Hook-Signature"},
                   "key":"sentry-{{data.issue.id}}",
                   "filter":[{"path":"action","in":["created"]}],
                   "prompt":"Sentry issue {{data.issue.title}} ({{data.issue.web_url}}) was created. Triage it."}}' \
  https://run.camelai.com/v1/channels
```

- **`signature`** is how a delivery proves itself; unsigned or wrongly signed
  ones get 401:
  - `{"type":"standard"}` (the default): [Standard Webhooks](https://www.standardwebhooks.com/)
    `webhook-id`, `webhook-timestamp` (at most five minutes old) and
    `webhook-signature` (any of several). A `whsec_` secret is base64 after the
    prefix, as the spec says; any other secret is used as it is.
  - `{"type":"hmac-sha256","header":"X-Hub-Signature-256","prefix":"sha256="}`: the
    header holds the HMAC-SHA256 of the raw body, in hex (or `"encoding":"base64"`),
    after the optional prefix. This covers GitHub, Sentry, Linear
    (`Linear-Signature`), Shopify (`X-Shopify-Hmac-Sha256`, base64) and most others.
  - `{"type":"token","header":"X-Gitlab-Token"}`: the header must equal the secret.
- **`key`** picks the conversation, and so the agent: deliveries that render to the
  same key go to the same agent, which keeps its history. Without a key the
  channel has one agent. A key that has characters other than letters, digits,
  `_`, `.` and `-`, or is longer than 64, is cleaned up and given a hash suffix.
- **`prompt`** is what the agent is told. By default it is the payload itself,
  pretty-printed (cut off past 8,000 characters). Either way the whole payload is
  attached as `payload.json` in the agent's workspace.
- **`sender`** names who a delivery is from, for the message's `from` and the
  per-sender rate limit (default `webhook`); for example `{{actor.email}}`.
- **`filter`** is a list of conditions that must all hold, or the delivery is
  acknowledged and ignored. Each has a `path` and one or more of `in` (a list of
  values), `equals` (a value) and `exists` (`true` or `false`). Values are compared as text.
- **`idPath`** or **`idHeader`** names where a delivery's id is, so a retry is
  dropped. Without either, the id is the first of the headers `webhook-id`,
  `X-Request-Id`, `X-Delivery-Id`, `X-GitHub-Delivery`, `Linear-Delivery` and
  `Idempotency-Key`, else a hash of the body.

Templates are `{{path}}`: a dotted path into the JSON payload (`data.items.0.id`
reaches into arrays), `{{headers.<name>}}` for a request header, and
`{{body.<path>}}` for a payload field named `headers`. A missing value renders as
nothing; an object renders as JSON. Bodies must be JSON, up to 1 MiB.

A webhook channel is public (`access.public: true`) and allows 60 deliveries a
minute per sender: the signature is what keeps others out. It still has the daily
turn cap, and `access` and `limits` can be set as for any channel.

There is no conversation to answer, so the agent acts through its tools, and the
turn's end reaches you as a [`run.completed`](https://run.camelai.com/docs/guides/webhooks.md) event. To have the
reply too, give `credentials.replyUrl`: each reply (and each `send_message`) is
POSTed there as `{"type":"message","conversationId","text"}`, signed per Standard
Webhooks with the channel's secret, and retried like any channel's messages.
Files are sent there as a link.

## Email

An email channel is an address on the runtime's own domain, which it receives
mail for through Amazon SES (on a runtime with `AGENT_EMAIL_DOMAIN`; see
[Configuration](https://run.camelai.com/docs/operations/configuration.md)). It takes no credentials:

```sh
curl -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"type":"email","settings":{"address":"support","fromName":"Acme Support"},
       "definition":"def_…","access":{"allow":["ada@example.com","@acme.com"]}}' \
  https://run.camelai.com/v1/channels
```

- **Address.** `settings.address` is the part before the `@` (or the whole
  address on the domain), unique across the runtime and case-insensitive; the
  channel's id is its address until one is chosen. Taken addresses answer 409;
  role addresses (`postmaster`, `abuse`, `noreply`…) and `ch_…` are reserved.
  Changing it frees the old one, and mail to it is then dropped. Replies come
  from the same address, under `settings.fromName` if set.
- **Who may write.** The allowlist holds addresses and `@domain` entries for
  everyone at a domain. A sender counts only when SES proves the From address:
  DMARC passed, or SPF passed for the From domain (or one above it). DKIM alone
  does not count, since SES does not say which domain signed. Mail that fails
  DMARC, is spam or carries a virus is dropped, as is mail an agent should not
  answer: `Auto-Submitted` other than `no`, `Precedence: bulk`, `list` or `junk`,
  bounces (`mailer-daemon`, `postmaster`), and mail from the runtime's own domain.
  Drops are logged (`email_inbound`, with a reason), never answered.
- **Threads.** A conversation is a thread: its root Message-ID (the first in
  `References`, else `In-Reply-To`), or the thread of any message of ours a reply
  names, so a client that keeps only `In-Reply-To` stays in its thread. A new
  message without either starts a new conversation. The agent is named after
  the subject, and gets `Subject: …` and the new text of each message, with
  quoted history (`On … wrote:` and what follows, `>` lines, `Original Message`
  blocks) left out; an HTML-only message is read as text. Attachments are saved
  like other channels' (images an HTML body shows inline are not).
- **Replies** go to whoever wrote last in the thread, with `Re: <subject>`,
  `In-Reply-To` the last message and `References` the thread's root and recent
  messages, so mail clients thread them, and `Auto-Submitted: auto-replied`, so
  other systems do not answer them. Each `send_message` and presented file is an
  email of its own; files up to 10 MiB are attached, larger ones sent as links.
- **Receiving.** SES stores each message in S3 and notifies an SNS topic, whose
  HTTPS subscription is `/channels/email/inbound` for every channel. The runtime
  accepts only messages SNS signed (the certificate from SNS's own host) for its
  configured topics, less than a day old, confirms the subscription itself, and
  hands a message to each channel it is addressed to (To, Cc or Bcc). SNS
  retries what fails; a message is recorded once by Message-ID.

---

<!-- https://run.camelai.com/docs/guides/migrating.md -->

# Coming from the OpenAI Agents SDK or LangGraph

The concepts mostly carry over. The main difference is where the agent lives. In
the OpenAI Agents SDK and LangGraph, the loop runs in your process, and its state
lives in a session or checkpointer that you run. In camelRun the loop runs in the
runtime, and so do the agent's history and files. Your process provides the
tools and starts runs.

This page maps each concept. It also lists what camelRun does not have, so you
know before porting.

## The same agent, ported

OpenAI Agents SDK:

```python
from agents import Agent, Runner, SQLiteSession, function_tool

@function_tool
def lookup_order(order_id: str) -> dict:
    """Look up an order by id."""
    return orders.get(order_id)

agent = Agent(name="Support", instructions="You help with orders.", tools=[lookup_order])
result = await Runner.run(agent, "Where is order 42?", session=SQLiteSession("user-123"))
print(result.final_output)
```

camelRun:

```python
from camelai_run import Agents, tool

@tool
def lookup_order(order_id: str) -> dict:
    """Look up an order by id."""
    return orders.get(order_id)

async with Agents() as agents:  # reads CAMELAI_API_KEY
    agent = await agents.upsert("user-123", instructions="You help with orders.", tools=[lookup_order])
    run = await agent.run("Where is order 42?")
    print(run.text)
```

The key (`"user-123"`) does the job of the session: the same key is the same
agent, with its history, from any process. `upsert` creates the agent the first
time and later brings it to the configuration you pass. Nothing is stored on
your side.

> **Deploy topology: one process serves an agent's tools.** In the OpenAI Agents
> SDK and LangGraph, every worker runs its own loop with its own tools. Here the
> loop is in the runtime, and tools passed to `upsert(tools=…)` are served by
> the **one** process holding the agent's connection. A straight port that
> upserts with `tools` in every gunicorn or uvicorn worker, or every Celery
> task, works with one worker and fails at two: `AgentError: Another process
> serves this agent's tools…` (`APPLICATION_CONNECTED`). With several workers,
> serve the tools over HTTPS instead, and make agents from a definition that
> names the server, with no `tools`: then any worker can run any agent, and
> deploys lose no call. See [Served tools](https://run.camelai.com/docs/guides/tools.md#served-tools-over-http-for-serverless-and-many-users).

```python
from camelai_run import serve_tools

# In your web app (pip install "camelai-run[server]"): every worker serves the same tools.
tools_app = serve_tools([lookup_order], runtime="https://run.camelai.com", tenant="acme")  # mount at /mcp

# Once, at deploy time: a definition naming the server.
definition = await agents.runtime.upsert_definition("support", name="Support", systemPrompt="You help with orders.",
    mcpServers=[{"name": "shop", "url": "https://app.example.com/mcp", "auth": {"type": "runtime"}}])

# In any worker or task: no tools here, so no worker holds them.
agent = await agents.upsert("user-123", definition=definition["id"])
run = await agent.run("Where is order 42?")
```

```ts
import { serveTools } from "@camelai/run/server";

// In your web app, on every instance: POST /mcp.
export const POST = serveTools({ lookup_order }, { runtime: "https://run.camelai.com", tenant: "acme" });

const definition = await agents.runtime.upsertDefinition("support", {
  name: "Support", systemPrompt: "You help with orders.",
  mcpServers: [{ name: "shop", url: "https://app.example.com/mcp", auth: { type: "runtime" } }],
});
const agent = await agents.upsert("user-123", { definition: definition.id });
```

`tenant` is your account's id (`GET /v1/me`). One long-lived process that holds
the tools, with every other process upserting with `attach=False`, works too;
see [Several processes, workers and deploys](https://run.camelai.com/docs/guides/tools.md#several-processes-workers-and-deploys).

## OpenAI Agents SDK

| OpenAI Agents SDK | camelRun |
| --- | --- |
| `Agent(name, instructions, tools, model)` | `agents.upsert(key, instructions=, tools=, model=)`; models are `provider/model` ids from `GET /v1/models` |
| `Runner.run(agent, input)`, `result.final_output` | `agent.run(text)`, `run.text` |
| `Runner.run_streamed` | `agent.stream(text)`: text, tool calls and results as they happen, then `done` with the run |
| `@function_tool` | `@tool` (TypeScript: `tool({ input, execute })`). Arguments are checked against the schema first. See [Tools](https://run.camelai.com/docs/guides/tools.md) |
| Sessions (`SQLiteSession`, Redis…) | The agent's key. History is durable and compacted when it gets long; `agent.history()` reads it |
| `output_type=Model` | `run(text, output=Model)`, `run.output` (`pip install "camelai-run[pydantic]"`). See [Structured output](https://run.camelai.com/docs/guides/structured-output.md) |
| Handoffs | Not supported: camelRun has no handoffs. Delegate instead, or route in your code; see [Handoffs and multi-agent](https://run.camelai.com/docs/guides/migrating.md#handoffs-and-multi-agent) |
| `agent.as_tool()` | The `delegate` built-in: `delegate: { agents: ["researcher"] }`. The sub-agent's answer is the call's result; several calls run in parallel. See [Multi-agent](https://run.camelai.com/docs/guides/multi-agent.md#sub-agents-delegate) |
| Input guardrails | Your code, before `run()`. With `createAgentHandler`, `onSend` can rewrite or refuse a message |
| Output guardrails | Your code, on `run.text` or `run.output`, before you use it |
| Tool approval (`needs_approval`), interruptions | `@tool(needs_approval=True)`; the run ends `input_required` and `run.inputs[0].answer(True)` resumes it, from any process, days later if need be. See [Human input](https://run.camelai.com/docs/guides/human-input.md) |
| `RunContextWrapper` (context for tools) | `context` and `subject` on the agent, plus `user` on each run. Tools get them in `context.identity`, set by your code and never by the model. See [Identity](https://run.camelai.com/docs/guides/tools.md#identity-who-a-call-is-for) |
| Hosted tools: `WebSearchTool` | `builtins=["web_search"]` |
| `CodeInterpreterTool` | `js_exec`, always on: JavaScript in a sandbox that can call the agent's tools. It has no Python |
| `FileSearchTool` (vector stores) | No equivalent. Agents have files and file tools, not vector search |
| `MCPServerStreamableHttp` | `mcpServers` in a [definition](https://run.camelai.com/docs/guides/definitions.md): the runtime calls the server itself. A local MCP server object can be attached with `fromMcpServer` (TypeScript) |
| Tracing (`trace()`, the traces dashboard) | OpenTelemetry trace export to your own backend (LangSmith, Langfuse, Honeycomb, Datadog, Tempo, any OTLP endpoint): a span per run, model call, tool call and wait, continuing your `traceparent`. See [Observability](https://run.camelai.com/docs/guides/observability.md). Also the event stream (`on_event`, `stream()`), `run.completed` and `usage.recorded` [webhooks](https://run.camelai.com/docs/guides/webhooks.md), and `GET /v1/agents/:id/history` |
| `max_turns` | `run_limits={"maxResponses": n}` on the agent (at most 1,000 model responses and 2 hours a run by default); a run that reaches it stops with `stopped: "turn_limit"`. `spend_limit={"usd": …}` on a run, or on the agent, bounds what it spends |
| `ModelSettings` (temperature, top_p) | Not settable. `thinking_level` is |

## LangGraph

| LangGraph | camelRun |
| --- | --- |
| `create_react_agent(model, tools, prompt)` (LangChain's `create_agent`) | `agents.upsert(key, model=, tools=, instructions=)`: the runtime runs the tool loop |
| Checkpointer and `thread_id` | The agent's key. One agent per thread: `upsert(f"thread-{thread_id}")` |
| `graph.get_state(config)` | `agent.history()`, `agent.history_page()` |
| `interrupt()` in a node or tool | In a tool: `await context.confirm(…)`, `await context.ask(…)`. The model can also ask, with `builtins=["ask_user"]` |
| `Command(resume=…)` | `run.inputs[0].answer(value)` |
| `graph.stream(…, stream_mode="messages")` | `agent.stream(text)`, or the agent's events |
| `response_format`, `with_structured_output` | `run(text, output=Model)` |
| Supervisor (`create_supervisor`) and subgraphs | A lead agent with the `delegate` built-in, each worker or subgraph a definition. See [Multi-agent](https://run.camelai.com/docs/guides/multi-agent.md#coming-from-langgraph). A swarm (handoffs between agents) is not supported |
| A custom `StateGraph` | Where the model decides, `delegate`; where your code decides, a sequence of runs, branching on `run.output`. There is no graph DSL; see below |
| `Send` (map-reduce) | Parallel `delegate` calls in one response, or `asyncio.gather` over runs of several agents |
| Long-term memory (`Store`) | Files. Mount a shared [volume](https://run.camelai.com/docs/guides/files.md#volumes) in several agents |
| Time travel (`get_state_history`, replay from a checkpoint) | [Fork](https://run.camelai.com/docs/concepts.md#forking) the agent at an earlier message (`agent.fork({ atMessage })`): a new agent goes on from there. An agent cannot be rewound in place |
| LangSmith | Export traces to LangSmith's OTLP endpoint (`PUT /v1/telemetry`, [preset](https://run.camelai.com/docs/guides/observability.md#presets)); include content to see messages |

## Handoffs and multi-agent

camelRun has no handoffs: an agent cannot pass its conversation to another
agent, and there is no graph. Use one of these instead.

**Delegate.** The agent hands a task to a sub-agent and gets its answer back as
the call's result, while the conversation stays with it: the Agents SDK's
`as_tool`, or a LangGraph supervisor. The sub-agent is an agent of its own, made
from a definition for each call, and the parent's limits cover it. See
[Multi-agent](https://run.camelai.com/docs/guides/multi-agent.md).

```python
await agents.runtime.upsert_definition("billing-specialist", name="Billing specialist",
    description="Answers questions about invoices, refunds and charges", systemPrompt="You answer billing questions.")
support = await agents.upsert("support-user-123", instructions="You help customers.",
    delegate={"agents": ["billing-specialist"]})
```

Several `delegate` calls in one response run in parallel. To keep one
specialist's history across calls, name an existing agent instead of a
definition: `{"agent": f"billing-{user_id}"}`.

**Route.** Your code picks the agent for each message. A small agent with
structured output can make the decision:

```python
class Route(BaseModel):
    team: Literal["billing", "technical", "general"]

router = await agents.upsert("router", instructions="Pick the team that should answer this message.")
team = (await router.run(message, output=Route)).output.team
answer = await (await agents.upsert(f"{team}-user-123", instructions=PROMPTS[team])).run(message)
```

What does not carry over: in a handoff, the receiving agent takes over the
conversation and sees its history. In camelRun each agent has its own history,
so pass what the other agent needs in the task or the message.

## Bringing conversations over

Existing conversations can continue in camelRun. Create the agent with its
history in `initialMessages`, converted to the runtime's message format (user,
assistant with tool calls, tool results). See [Bringing in existing
conversations](https://run.camelai.com/docs/guides/multi-user.md#bringing-in-existing-conversations).

## What camelRun adds

- **Durable runs.** A run survives your process restarting and the runtime's
  nodes being replaced. A run waiting on a person waits for days at no cost.
- **Tools anywhere.** Tools run in your process (attached) or behind an HTTPS
  endpoint (served, for serverless and many workers), and the model can call
  many of them from code in `js_exec`. See [Tools](https://run.camelai.com/docs/guides/tools.md).
- **Channels and schedules.** Slack, Telegram, Discord, GitHub and email can
  reach an agent directly, and agents can wake themselves. See
  [Channels](https://run.camelai.com/docs/guides/channels.md).

---

<!-- https://run.camelai.com/docs/guides/mcp-server.md -->

# Agents as MCP servers

Every agent is also an MCP server, at `https://run.camelai.com/v1/agents/<agent id>/mcp`
(Streamable HTTP). Connect Claude, Cursor or any MCP client to it, and the model
there can talk to your agent. It has one tool, `message`: it sends the agent a
message and returns the agent's reply. The agent's own tools stay its own.

Claude Code:

```sh
claude mcp add --transport http support https://run.camelai.com/v1/agents/client_…/mcp
# then /mcp in Claude Code to sign in; or skip signing in with a token from your environment:
claude mcp add --scope project --transport http support https://run.camelai.com/v1/agents/client_…/mcp \
  --header 'Authorization: Bearer ${SUPPORT_AGENT_TOKEN}'
```

The single quotes keep the variable as written, so the project's `.mcp.json`
names it and Claude Code reads its value from the environment. Never write a
token's value into an MCP config: they are often committed (see
[Keys stay out of MCP configs](https://run.camelai.com/docs/reference/cli.md#keys-stay-out-of-mcp-configs)).

Claude (claude.ai and the desktop app): Settings, Connectors, Add custom
connector, with the agent's URL. Cursor and other clients configured with JSON:

```json
{ "mcpServers": { "support": { "url": "https://run.camelai.com/v1/agents/client_…/mcp" } } }
```

- **One conversation.** A message joins the agent's history exactly as a prompt
  (`POST /v1/agents/:id/prompt`) does, next to messages from the API, the
  console and channels. There are no threads per caller; to give each caller a
  conversation of its own, give each an agent. Each message is a run, limited
  and billed as a prompt is.
- **Who may call it.** Whatever may prompt the agent: its own token (the
  `token` it was created with), an API token of its tenant, or an OAuth sign-in.
  A `401` names the agent's protected-resource metadata
  (`/.well-known/oauth-protected-resource/v1/agents/<id>/mcp`), so clients sign
  in [as with the hosted MCP server](https://run.camelai.com/docs/reference/cli.md#hosted-mcp-server).
  Other tenants' tokens get `404`.
- **The tool's description** names the agent and, when the agent is made from a
  [definition](https://run.camelai.com/docs/guides/definitions.md) with a `description`, says what it is for:
  `"description": "Answers questions about orders and refunds."` (1–1,000
  characters). Its system prompt is never shown.
- **Long turns.** A call lasts as long as the turn. It sends progress
  notifications as the agent works (its text as it streams, each tool it uses,
  and a heartbeat every 20 seconds), so clients that reset their timeout on
  progress keep waiting. A caller that goes away does not stop the turn.
- **Retries.** Pass `requestId`: sending the same text with the same id again is
  the same message, never sent twice, and the call returns its reply (waiting
  for it if it is still running). A call your client sends again in the same
  session is recognized without one.
- **A busy agent.** A message to an agent that is working queues behind its
  current turn, as a prompt does. Once 32 requests are open, the call fails:
  `The agent is busy: …`.
- **Human input.** When the turn [waits on a person](https://run.camelai.com/docs/guides/human-input.md) and the
  client supports elicitation, the question, approval, form or page comes up in
  the client, and the answer resumes the turn. Otherwise the call ends with a
  result listing what the agent waits on (`structuredContent.status` is
  `input_required`) and how to answer it; once answered, the same call again
  (same text and `requestId`) returns the reply. A new message instead sets the
  inputs aside.
- **Errors** (a failed run, a spend limit, a model error, a refused request)
  come back as tool errors carrying the runtime's message.

---

<!-- https://run.camelai.com/docs/guides/export.md -->

# Exporting your data

`GET /v1/account/export` (the console's **Account → Export data**) answers with a
zip of everything camelRun stores for your account. Any API token of the account
can call it; a browser token cannot.

```sh
curl -sf https://run.camelai.com/v1/account/export -H "Authorization: Bearer $CAMELAI_API_KEY" -o camelrun-export.zip
```

| In the zip | |
| --- | --- |
| `README.txt` | what each file is |
| `account.json` | your account's id, the identity you sign in with, when it was made and exported |
| `agents/<id>/agent.json` | each agent's configuration and schedules |
| `agents/<id>/history/*.json` | each agent's whole history, a page of whole turns per file, named by its first message's index |
| `definitions.json`, `channels.json`, `webhooks.json` | your definitions, channels and webhook endpoints (secrets and credentials left out or masked) |
| `tokens.json`, `keys.json` | your API tokens' names and prefixes, and which provider keys are set (last four characters): never a token or key |
| `oauth-grants.json`, `discord.json` | applications you let act for your account, and managed Discord bindings |
| `volumes/<id>/volume.json`, `volumes/<id>/files/…` | each volume's name and size, and its files |
| `billing/ledger.jsonl`, `billing/usage.json` | your credit ledger (newest first) and model usage per day and model |

**An export is whole, or it fails.** Each agent's history is read from the node
serving it, so it includes the turn that just ended. If anything cannot be read,
the download stops before the zip's end, so no zip reader opens it as complete
(`curl -f` fails, and `unzip` reports a missing central directory): export
again. A zip that opens holds every agent.

## Leaving, or moving to a self-hosted runtime

The runtime is open source, and [Self-hosting](https://run.camelai.com/docs/operations/self-host.md) runs
the same API on your own machines. **There is no import yet**: nothing loads an
export into another runtime in one step. To carry agents over by hand:

- **Configuration:** make each agent again from its `agent.json` (or each
  definition from `definitions.json`) with the same key, pointing the SDK at the
  new runtime (`CAMELAI_BASE_URL`).
- **History:** each `history/*.json` file is a list of `{index, message}`. Take
  the `message`s of every file, in order of the file names, and pass them as
  `initialMessages` when you make the agent; see [Bringing in existing
  conversations](https://run.camelai.com/docs/guides/multi-user.md#bringing-in-existing-conversations).
- **Files:** upload a volume's `files/` to a new volume.
- **Keys, tokens, channel credentials and webhook secrets** are not in the
  export: set them again.

To delete the account and everything in it, use **Delete account** on the
console's Account page.

---

<!-- https://run.camelai.com/docs/production.md -->

# Production checklist

Before you ship an application on the runtime, check each of these.

## Keys and access

- [ ] Your API key is only on your servers, in a secret store, never in a
      browser, a mobile app or a repository. Browsers get [browser
      tokens](https://run.camelai.com/docs/guides/browser.md), minted per user after your own access checks.
- [ ] An agent's token (`agent.session.token`) is secret too. You rarely need it:
      upsert by key instead. The SDKs keep it out of logs and JSON; do not print it
      yourself.
- [ ] Tools authorize every call as `context.identity.user` within
      `identity.context`, never from ids in the model's arguments. `subject` and
      `context` are set when the agent is made. See [Identity](https://run.camelai.com/docs/guides/tools.md#identity-who-a-call-is-for).
- [ ] Served tools verify the runtime's token (`serveTools`, `serve_tools`,
      `runtimeAuth` do) with `tenant` set to your own tenant, so another tenant's
      agents cannot act as your users.
- [ ] Behind a TLS-terminating proxy the audience is your public URL: pass
      `origin` to `nodeListener` (or `trustProxy: true` only where the proxy
      overwrites `X-Forwarded-*`). Test with `testRuntime()`.

## Agents

- [ ] Agents are keyed by your ids (`upsert("user-123", …)`), so any process finds
      them and a retry never makes a second. Keyed agents live until deleted:
      delete the ones you no longer need (`agent.delete()`), e.g. when the user or
      thread is deleted.
- [ ] Configuration lives in one place: the `upsert` call (or a definition, with
      `apply: "all"` to roll changes out). Fields fixed at creation (`subject`,
      `context`, `definition`, `mounts`) are a 409 if they change; handle that as
      "delete and recreate" only where you mean it.
- [ ] You pick a model your account has a key for, and set `spendLimit` on agents
      that act for untrusted users.

## Tools

- [ ] Every tool with side effects passes `context.idempotencyKey` to what it
      calls, so a retried or re-run call acts once.
- [ ] Long tools set `timeoutMs` and report `context.progress()`; nothing relies
      on a call finishing within the default 15 seconds.
- [ ] Tools that ask a person (`needsApproval`, `context.confirm/ask`) ask
      before they act: everything before an ask runs again once answered.
- [ ] Where tools run matches how you deploy: a long-lived process attaches
      them; serverless or several instances serve them over HTTP. Agents woken by
      schedules, channels or webhooks use served tools, or nobody may be there to
      answer (`toolErrors` with `not_connected`). A run with nobody serving
      attached tools is refused (`APPLICATION_NOT_CONNECTED`) unless it passes
      `allowDisconnected`.
- [ ] Exactly one process attaches an agent's tools. Others run it with
      `attach: false` (or without tools). A process that loses them
      (`APPLICATION_REPLACED` on `onError`) keeps running the agent without them.

## Runs

- [ ] You reply to users from the run's result (`run.text`), not from the event
      stream. The stream is for display.
- [ ] Failures are handled: `run()` throws `RunError` (with `code`, and
      `uncertain` when a restart cut the run short); `run.toolErrors` lists tool
      calls that did not complete.
- [ ] Runs that wait on people (`status: "input_required"`) are shown to someone
      who can answer, or answered from your inbox (`agents.runtime.inbox("pending")`
      and the `input.requested` webhook). Inputs expire after 7 days by default.
- [ ] Retries reuse the run's `idempotencyKey`, so a request retried after a
      timeout observes the same run instead of starting another.
- [ ] Waits have a bound where your caller needs one (`signal`, Python
      `timeout=`), knowing the run goes on; `agent.abort()` stops it.
- [ ] `onEvent` handlers are quick or queue their work; they run in order, apart
      from the connection, and their errors go to `onError`.

## Operations

- [ ] Your process closes its agents on shutdown, on SIGTERM (`await agents.close()`,
      or `await using`): it finishes the tool calls it is running, hands new
      ones to the next process, and releases the agents' tools, so a deploy
      loses no call. A rolling deploy starts the new process with `takeover: true`.
      See [deploying a tool process](https://run.camelai.com/docs/guides/tools.md#deploying-a-tool-process).
- [ ] You register a [webhook](https://run.camelai.com/docs/guides/webhooks.md) endpoint for `run.failed` and
      `input.requested` (and `usage.recorded` to meter spend), verify signatures,
      dedupe by event `id`, and answer within 10 seconds.
- [ ] To trace runs in your own backend, you set [trace export](https://run.camelai.com/docs/guides/observability.md)
      (`PUT /v1/telemetry`), pass `traceparent` from your request's span, send a
      test span, and decide deliberately whether to include content.
- [ ] You handle 429 and 503 by waiting `Retry-After` (the SDKs retry them),
      and know the [limits](https://run.camelai.com/docs/reference/limits.md) your workload approaches.
- [ ] Serverless: prefer served tools.

---

<!-- https://run.camelai.com/docs/reference/sdk.md -->

# SDKs

The TypeScript SDK (`@camelai/run`) and the Python SDK
(`camelai-run`). Start with the [Quickstart](https://run.camelai.com/docs/quickstart.md);
this page is the reference. The two have the same features, named in each
language's style; their version numbers are their own and do not line up.

```sh
npm install @camelai/run      # Node 22+, Bun, Deno, Cloudflare Workers
pip install camelai-run       # Python 3.11+; "camelai-run[server]" for serve_tools, "camelai-run[pydantic]" for pydantic output
```

| TypeScript entry | |
| --- | --- |
| `@camelai/run` | everything portable: `Agents`, `tool`, `schema`, the lower-level `AgentRuntime` and `AgentClient`, the types |
| `@camelai/run/node` | the same for Node and Bun, plus local file paths as attachments, `nodeListener` |
| `@camelai/run/server` | `serveTools`, `verifyRuntimeToken`, `runtimeAuth`, `runtimeIdentity`: serving tools over HTTP; `verifyFileUrl`: checking a file URL a tool was sent |
| `@camelai/run/watch` | `watchAgent`: reading an agent from a browser |
| `@camelai/run/mcp` | `fromMcpServer`: attaching an MCP SDK server (needs `@modelcontextprotocol/sdk`) |
| `@camelai/run/testing` | `testRuntime`: signing identity tokens (and file URLs, `fileUrl`) in tests |

The public types need nothing else installed: messages and events are declared
in the SDK (`Message`, `AgentEvent`, `AssistantMessage`, …).

## Agents

```ts
const agents = new Agents({ apiKey, url });   // or `await using agents = new Agents()`
```

```python
async with Agents(api_key, url=url) as agents: ...
```

The Python SDK is async: every call is awaited inside `async def`. Synchronous
code (a script, a Django or Flask view, a Celery task) uses `camelai_run.sync`,
the same names without `await`: see [The synchronous client](https://run.camelai.com/docs/reference/sdk.md#the-synchronous-client-python).
Its names are the TypeScript ones in snake_case (`throw_on_error`,
`run.tool_errors`, `part.is_error`), as the tables below show.

- `apiKey` defaults to the `CAMELAI_API_KEY` environment variable, `url` to
  `CAMELAI_BASE_URL`, else `https://run.camelai.com`.
- `agents.close()` closes every agent's connection so the process can exit;
  their runs go on in the runtime. A process serving tools first finishes the
  calls it is running, up to `drainMs` (Python `drain=`, seconds; default 25 s),
  while new calls go to another process: call it on SIGTERM. See [deploying a
  tool process](https://run.camelai.com/docs/guides/tools.md#deploying-a-tool-process).
- `connection` (Python `connection=`) says when agent handles hold their event
  stream. `"lazy"`, the default: only while `agent.stream()` reads a run, so a
  server holding many agents (50 keyed agents behind one page, say) holds no idle
  connections, and `agent.run()` waits for its outcome by asking for it (`GET
  /clients/:id/requests/:id?wait=25`, again until it settles). A handle that serves
  tools, or has `onEvent`, `onInput` or `onConnection` (`on_event`, `on_input`),
  needs the stream throughout, so it holds it from `upsert`/`get` until `close()`
  whatever this says. `"eager"` holds it from the start for every handle. Each
  `upsert`, `get`, `fork` and `agent` call may say otherwise (`connection`).
  The lower-level `connectAgent` (`connect_agent`) stays eager unless asked.
- `agents.runtime` is the lower-level `AgentRuntime`: definitions, volumes,
  mounts, `listAgents()`, `browserToken(agentId)`, `inbox()`, `toolSources(agentId)`.

### `agents.upsert(key, config)`

The agent for `key` (1 to 80 of `A-Z a-z 0-9 _ -`), made if there is none, and
brought to `config` if it differs. Returns a connected `Agent`. See
[Concepts](https://run.camelai.com/docs/concepts.md#agents-are-durable-and-keyed).

| TypeScript | Python | |
| --- | --- | --- |
| `model` | `model=` | `"provider/model-id"` from `GET /v1/models` |
| `instructions` | `instructions=` | the system prompt |
| `instructionsAppend` | `instructions_append=` | text after the prompt (a definition's, say): per-conversation context |
| `tools` | `tools=` | tools served from this process: `{ name: tool({...}) }`, or a list of `@tool` functions |
| `mcp` | | an MCP server of yours to attach instead (`fromMcpServer`) |
| `definition` | `definition=` | make it from a definition (its model, prompt and tool sources) |
| `thinkingLevel` | `thinking_level=` | `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max` |
| `maxOutputTokens`, `temperature` | `max_output_tokens=`, `temperature=` | the most the model writes in a response, and its sampling temperature (0 to 2; refused for a model or thinking level that takes none). See [Output length and temperature](https://run.camelai.com/docs/guides/models-and-keys.md#output-length-and-temperature) |
| `subject`, `context` | `subject=`, `context=` | whom it acts for, and claims for its tools; fixed at creation |
| `keyScope`, `spendLimit`, `runLimits`, `modelHeaders` | `key_scope=`, `spend_limit=`, `run_limits=`, `model_headers=` | see [Models and keys](https://run.camelai.com/docs/guides/models-and-keys.md) |
| `mounts`, `fileTools` | `mounts=`, `file_tools=` | its volumes (fixed at creation), and whether it has file tools |
| `codeMode` | `code_mode=` | `false`: no `js_exec`; every tool is called directly, and an agent with no tools at all gets little more than its instructions as its system prompt. See [Tools](https://run.camelai.com/docs/guides/tools.md#without-code-codemode-false) |
| `name` | `name=` | a label, shown in the console |
| `builtins` | `builtins=` | tools the runtime answers itself, without a definition: `web_fetch`, `web_search`, `schedule`, `ask_user`, `delegate`, `agents` |
| `delegate` | `delegate=` | sub-agents it may hand tasks to (`{ agents, instructions?, maxDepth?, maxParallel? }`); brings its builtin. See [Multi-agent](https://run.camelai.com/docs/guides/multi-agent.md) |
| `mcpServers` | `mcp_servers=` | remote MCP servers of its own, without a definition: `[{ name, url, auth?: { type: "runtime" }, allowTools?, … }]`, no credentials. See [An agent's own MCP servers](https://run.camelai.com/docs/guides/tools.md#an-agents-own-mcp-servers) |
| `subagents` | `subagents=` | also deliver its sub-agents' progress: `subagent_start`, `subagent_event`, `subagent_end` events, and stream parts |
| `attach` | `attach=` | `false`: declare `tools` without serving them (another process does) |
| `takeover` | `takeover=` | replace the process serving the tools now |
| `onEvent(event, runId)` | `on_event=` | every event, for display; runs in order, apart from the connection; plain or async |
| `onInput(input)` | `on_input=` | each input as it is asked: return an answer, or nothing |
| `onError(error)` | `on_error=` | errors from the connection and from `onEvent` |
| | `initial_messages=` | the history it begins with, used only when it is made (`runtime.createAgent({ initialMessages })` in TypeScript); see [Bringing in existing conversations](https://run.camelai.com/docs/guides/multi-user.md#bringing-in-existing-conversations) |
| | `import_messages=` | a conversation in Anthropic's or OpenAI's format (`{"format", "messages", "model"?}`), converted by the runtime (`importMessages` in TypeScript; `toPiMessages` converts one locally) |

### `agents.get(keyOrId, { tools, … })`

The existing agent with this key (or id), as it is: `upsert` sets an agent to
the `config` it is given, `get` changes nothing. Use it where a process only
runs or reads agents that another process configures. It throws an `AgentError`
with `status` 404 when no live agent has the key or id, and 409
`AGENT_KEYLESS` for an agent made without a key. It takes `tools`, `onEvent`,
`onInput`, `onError`, `attach` and `takeover` as `upsert` does (Python:
`await agents.get(key, tools=[…])`). REST: `GET /v1/agents/{keyOrId}/credentials`
gives the agent's `{id, token, expiresAt}`, to the account's own credentials
only (an API token, an OAuth grant, a console session): a browser token gets
403 and an agent's token 401, and browsers get no CORS access to it. From `@camelai/run` 0.13.1 and
`camelai-run` 0.9.1.

`agents.agent(session, { tools, … })` connects to an agent you hold the
credentials of (`{id, token}`) without changing it.

`agent.configHash` (Python `agent.config_hash`), from `upsert` and `get`, is a
hash of the agent's configuration (from `upsert`, the one it asked for). Equal
hashes are equal configurations: an upsert that changes nothing returns the
hash the agent has, and is not counted as an agent create. Every agent's is in
`agents.runtime.listAgents()` (`list_agents()`), so a deploy script can tell
what changed without keeping a manifest. It is opaque: compare it, never parse it.

### `Agent`

| TypeScript | Python | |
| --- | --- | --- |
| `agent.id` | `agent.id` | `client_…`: safe to log and store |
| `agent.run(text, options)` | `await agent.run(text, …)` | send a message, wait for the run: a `Run` |
| `agent.stream(text, options)` | `agent.stream(text, …)` | the run as it happens: `for await` / `async for` over parts |
| `agent.pendingInputs()` | `pending_inputs()` | inputs waiting on people, each with `answer()` |
| `agent.history()`, `historyPage({ before, limit })` | `history()`, `history_page(before=, limit=)` | the whole history (a list of messages, oldest first), or a page of whole turns |
| `agent.send(text, options)`, `agent.wait(id)` | `await send(text, …)`, `await wait(id)` | send a message without waiting: resolves once the runtime has taken it, with `{id, state}` (`POST …/prompt`'s 202); `wait(id)` is its `Run` later, from this process or another. For work queues and webhooks that should not hold a connection for the whole run |
| `agent.steer(text, options)` | `steer(text, …)` | hand the running turn a message (else start one), answered as soon as the runtime has it: `{id, status: "accepted" \| "taken" \| "queued", steeredInto?}`. `wait: true` (`wait=True`) resolves with the run that took it instead, as `run(text, { whileRunning: "steer" })` |
| `agent.configure({ model, instructions, thinkingLevel, tools, maxOutputTokens, temperature })` | `configure(…)` | change it between runs; `null` (`None`) removes `maxOutputTokens` or `temperature` |
| `agent.schedule({ text, inSeconds, at, everySeconds, history })` | `schedule(…)` | wake it later (`history: "none"`: without its history); `schedules()`, `unschedule(id)` |
| `agent.files` | `agent.files` | `list`, `download`, `upload`, `link` by the paths the agent sees |
| `agent.abort({ queued })` | `abort(queued=)` | stop the agent: its running turn, and the runs queued behind it (each fails with code `cancelled`); `queued: "keep"` stops the running turn only. Resolves with `{aborted, cancelled}` |
| `agent.fork({ key, name, atMessage, ttlSeconds })` | `fork(key=, name=, at_message=, ttl_seconds=)` | a new agent with its configuration, a copy of its history and of its files: see [Forking](https://run.camelai.com/docs/reference/sdk.md#agentforkoptions) |
| `agent.delete()` | `delete()` | delete it, its history and files |
| `agent.close()` | `close()` | close this process's connection |
| `agent.client` | `agent.client` | the lower-level `AgentClient` |

Run options (`run`, `stream`):

| TypeScript | Python | |
| --- | --- | --- |
| `user` | `user=` | who sent it: your user id, or `{ id, name, username }`; the model sees who, tools get `identity.actor` |
| `files` | `files=` | attachments, by bytes, path, `{ url }` or `{ path }` in the agent's mounts; audio among them is transcribed for the model (`transcribe: false` keeps a file plain). See [Files](https://run.camelai.com/docs/guides/files.md) and [Voice and audio](https://run.camelai.com/docs/guides/voice.md). With audio, the text may be `""` |
| `metadata` | `metadata=` | your own key-value data about the message (16 strings); the model never sees it |
| `idempotencyKey` | `idempotency_key=` | the run's id: the same key returns the same run, joining it if it is still going |
| `signal` | `timeout=` | stop waiting; the run goes on |
| `throwOnError` | `throw_on_error=` | `false`: return a failed run instead of throwing `RunError` |
| `history` | `history=` | `"none"`: the model sees the instructions and this message only, not the agent's history; the run is still recorded. See [Runs without the history](https://run.camelai.com/docs/concepts.md#runs-without-the-history) |
| `whileRunning` | `while_running=` | `"queue"` (default) or `"steer"` |
| `spendLimit` | `spend_limit=` | `{usd}`: this run's own budget; see [Spend limits](https://run.camelai.com/docs/guides/models-and-keys.md#spend-limits) |
| `runLimits` | `run_limits=` | `{maxResponses, maxSeconds}`: this run's own, lowering the agent's; see [Run limits](https://run.camelai.com/docs/guides/models-and-keys.md#run-limits) |
| `allowDisconnected` | `allow_disconnected=` | run even with nobody serving the agent's tools (else refused: `APPLICATION_NOT_CONNECTED`) |
| `output` | `output=` | structured output: a zod (or other Standard Schema), TypeBox or JSON Schema (Python: a pydantic model class, or a JSON Schema dict) for an object; the answer is `run.output`. See [Structured output](https://run.camelai.com/docs/guides/structured-output.md) |
| `traceparent` | `traceparent=` | a W3C trace context (`00-<trace-id>-<span-id>-<flags>`), sent as the `traceparent` header: when the tenant exports telemetry (`runtime.telemetry`), the run's spans continue your trace, under that span. Not part of the run's idempotency |

### `agent.fork(options)`

A new `Agent` made from this one: its configuration, a copy of its history and
a fork of its workspace, each its own from then on ([Forking](https://run.camelai.com/docs/concepts.md#forking)).
`atMessage` (Python `at_message=`) ends the copied history at a history index
(that message and the tool results answering it) or a request id (that run's
whole turn); by default it ends with the last turn that finished, never mid-turn.
`key` is the fork's own: forking again with it returns the same fork, and
`agents.get(key)` finds it; without one, the SDK makes one up for its own retries
and the fork lives a day (`ttlSeconds` to change that), as `createAgent`'s
does. `subject`, `context`, `instructionsAppend` (Python `instructions_append=`)
and `modelHeaders` (`model_headers=`) are the fork's own instead of the source's. It takes `tools`, `onEvent` and the rest as `agents.get` does.
`fork.forkedFrom` (`forked_from`) is `{agentId, atMessage}`. `agents.fork(id,
options)` forks an agent by id. Lower level: `runtime.forkAgent(id, options)`
(`fork_agent`) returns the fork's credentials and `forkedFrom`. REST: `POST
/v1/agents/{id}/fork`. From `@camelai/run` 0.13.1 and `camelai-run` 0.9.1.

```ts
const fork = await agent.fork({ key: "support-b", atMessage: 5 });
await fork.run("Try the other approach");
```

### `agents.run(config)` and `agents.runs`

A stateless run ([guide](https://run.camelai.com/docs/guides/stateless-runs.md)): a configuration and an
input in, a `Run` out, nothing carried over and no agent made.

```ts
const run = await agents.run({ instructions: "Vote yes or no.", input: "Ship on Friday?", output: Vote });
```

```python
run = await agents.run("Ship on Friday?", instructions="Vote yes or no.", output=Vote)
```

`config` takes an agent's configuration (`model`, `instructions`,
`instructionsAppend`, `definition`, `builtins`: `web_fetch`, `web_search`,
`delegate`; `delegate`, `mcpServers` (no credentials), `thinkingLevel`, `maxOutputTokens`, `temperature`, `subject`, `context`, `keyScope`,
`runLimits`, `modelHeaders`, `mounts`, `fileTools`, `codeMode`, `name`; a run with
no tools defaults to `codeMode: false` and `fileTools: false`) and the run's own:
`input`, `files` (inline bytes, or `{ url }`; audio is transcribed, and `input` may then be `""`), `output`, `user`, `metadata`, `idempotencyKey`,
`spendLimit`, `retentionSeconds`, `signal`, `throwOnError`, `traceparent`
(Python: snake_case keywords, `input` first). It resolves with a `Run` (no
`inputs`), and throws a `RunError` when the run failed unless
`throwOnError: false`.

| `agents.runs.` | |
| --- | --- |
| `create(config, { wait })` | start one; resolves at once with the runtime's view (`StatelessRun`: `status` `running`…), or with `wait` once it ends within it |
| `get(id, { wait })` | the run, as it is or as it ended (`wait`: seconds, at most 25) |
| `stream(config)` / `stream(id)` | resolves with a stream of its parts (as an agent's, without `input_required`), `done` last; `result()` is the run |
| `abort(id)` | stop it: it ends `failed`, code `aborted` |
| `delete(id)` | delete it before its retention ends |
| `messages(id)` | its messages |
| `events(id, { lastEventId })` | its raw event frames, to its `response`, reconnecting with `Last-Event-ID` |

Python's `agents.runs.stream(input, …)` or `stream(run_id=…)` resolves with a
`StatelessRunStream`. The lower level is `runtime.createRun`, `getRun`,
`waitForRun`, `abortRun`, `deleteRun`, `runMessages` and `runEvents` (Python:
`create_run`, `get_run`, …).

### `Run`

`{ id, status, text, output?, inputs, error, usage, files, toolErrors, toolCalls, sourceErrors, raw }`
(Python: `tool_errors`, `tool_calls`, `source_errors`). `toolCalls` lists every
tool call the run made, with `ok` or an error `code`, not their arguments or
results (see [Run outcomes](https://run.camelai.com/docs/reference/events.md#run-outcomes)); a `delegate` call has its
sub-agent's `agentId`, and `usage.subagentCostUsd` is what its sub-agents spent. `status` is `completed`,
`input_required` or `failed`; `error` is `{ code, message, uncertain? }`.
`output` is a run with `output`'s answer, typed by its schema (`Run<T>`; Python:
an instance of the pydantic model). See
[Concepts](https://run.camelai.com/docs/concepts.md#runs) and [Errors](https://run.camelai.com/docs/reference/errors.md#run-failures).

Each of `run.inputs` is the input (`id`, `kind`, `message`, `detail`,
`responders`, `expiresAt`, …) with `answer(value, { from })` and
`decline({ from })` (Python: a dict with `answer(value, from_=)` and
`decline(from_=)`), which resolve with the resumed run. See [Human
input](https://run.camelai.com/docs/guides/human-input.md#answering).

### Stream parts

| `type` | fields |
| --- | --- |
| `text` | `text`: reply text as it is written (successive messages separated by a blank line) |
| `tool_call` | `id`, `name`, `arguments` |
| `tool_result` | `id`, `name`, `output` (the result's text), `isError` (`is_error`) |
| `input_required` | `input`, with `answer()` |
| `subagent_start`, `subagent_end` | with `subagents: true`: `toolCallId` (Python `id`), `agentId` (`agent_id`), `name` at the start, `status` at the end |
| `done` | `run`: always last |

`run.toolCalls` names a call's tool `tool` and its id `toolCallId`; stream parts
have the same values as `name` and `id`, and, from `@camelai/run` 0.13.1 and
`camelai-run` 0.9.1, also as `tool` and `toolCallId` (`tool_call_id`), so code
can use one name for both. `name` and `id` stay.

Every part but `done` has `raw`, the event it came from. `stream.result()`
resolves with the run; breaking out of the loop stops the reading, not the run.

## Tools

```ts
tool({ description, input: schema.Object({...}), execute: (args, context) => result, timeoutMs?, needsApproval?, exposure?, executionMode?, resultFormat? })
```

```python
@tool(name=None, description=None, timeout=None, needs_approval=None, exposure=None)
def or_async_def(arg: str, context: ToolContext): ...
```

`exposure` is how the model may call the tool: `"direct"` (as a tool of its
own), `"codemode"` (only from code in `js_exec`) or `"both"`. Left out, it is
`both` for an agent with up to 10 tools and `codemode` past that, so the model
can call your tools from `js_exec` unless they say `"direct"`; see
[Keeping tools out of js_exec](https://run.camelai.com/docs/guides/tools.md#keeping-tools-out-of-js_exec).

`context` (`ToolContext`):

| TypeScript | Python | |
| --- | --- | --- |
| `idempotencyKey` | `idempotency_key` | the same for every attempt of this call: key side effects by it |
| `callId` | `call_id` | this attempt's id |
| `toolCallId` | `tool_call_id` | the model's tool call |
| `identity` | `identity` | who the call is for: `user`, `subject`, `actor`, `tenant`, `agent`, `context`, `origin`, `approval` |
| `origin` | `origin` | where the turn came from (a channel) |
| `signal` | (task cancellation) | aborted when the runtime cancels the call |
| `progress(message \| { progress, total, message })` | `progress(message, progress=, total=)` | report progress; restarts the deadline |
| `confirm`, `ask`, `requireUrl` | `confirm`, `ask`, `require_url` | ask the user; see [Human input](https://run.camelai.com/docs/guides/human-input.md) |

See [Tools](https://run.camelai.com/docs/guides/tools.md) for attached and served tools, identity and
the definitions' sources, and `serveTools` / `serve_tools`.

A tool of a definition's source may be sent the agent's files as URLs
([Files in tool calls](https://run.camelai.com/docs/guides/tools.md#files-in-tool-calls)).
`verifyFileUrl(url, { runtime, tenant?, agent?, issuer? })` (Python
`await verify_file_url(url, runtime=, tenant=None, agent=None, issuer=None)`)
checks one came from the runtime for the tenant and agent you expect, and has
not expired, and returns what it grants: `tenant`, `agent`, `call`, `tool`,
`volume`, `path`, `agentPath`, `kind` (`file`, `manifest` or `archive`),
`version` or `snapshot`, and `exp`. It throws `RuntimeTokenError` otherwise. With several
processes (web workers, task queues, serverless), serve tools over HTTP: see
[Several processes, workers and deploys](https://run.camelai.com/docs/guides/tools.md#several-processes-workers-and-deploys).

## The synchronous client (Python)

`camelai_run.sync` has the SDK's names for code that is not async: a script, a
Django or Flask view, a Celery task. Calls return their answer; nothing is
awaited.

```python
from camelai_run.sync import Agents

with Agents() as agents:  # CAMELAI_API_KEY
    agent = agents.upsert("support-triage", instructions="Be brief.")
    run = agent.run("Summarize ticket 123", user="alice")
    for part in agent.stream("And the next one?"):
        if part.type == "text":
            print(part.text, end="")
    vote = agents.run("Ship on Friday?", instructions="Vote yes or no.", output=Vote)
```

- `Agents`: `upsert`, `get`, `fork`, `agent(session)`, `run` and `runs`
  (stateless), `close`. `Agent`: `run`, `stream`, `steer`, `history`,
  `history_page`, `pending_inputs`, `configure`, `abort`, `fork`, `schedule`,
  `files`, `delete`. A run's inputs are answered with `run.inputs[0].answer(…)`.
- `AgentRuntime` has every call of the async one that is one request
  (definitions, providers, key scopes, tokens, usage, webhooks, `me`,
  `browser_token`, runs, `telemetry`), and `wait_for_run` and `run_events`.
- Handles hold no connection. `agent.run()` sends the message and asks for its
  outcome (a long poll of up to 25 s at a time); `agent.stream()` reads the
  agent's events while it reads the run. `timeout=` (seconds) stops the wait,
  not the run.
- It never serves tools: that needs the agent's connection held, as the async
  SDK does. Serve them over HTTP with `camelai_run.sync.serve_tools` (a WSGI
  app; see [Tools](https://run.camelai.com/docs/guides/tools.md#served-tools-over-http-for-serverless-and-many-users))
  and a definition. `upsert(tools=[…])` declares tools for a process with the
  async SDK to serve; an upsert sets the agent's tools to those it is given, so
  `get` an agent whose tools another process serves.
- Not here: `on_event` and `on_input`, volumes (`runtime.volume`), and
  `create_agent`. One `Agents` is for one thread at a time; give each thread
  (or Celery worker) its own.

`camelai_run.sync` also has `verify_runtime_token` and `verify_file_url` (synchronous) and a
`TestRuntime` whose `call_tool` calls a WSGI app.

## Errors

- `AgentError`: `status` (HTTP, or 0), `code` (a stable name where the runtime
  gives one: `APPLICATION_CONNECTED`, `APPLICATION_REPLACED`, `REPLAY_GAP`,
  `spend_limit`, …), `requestId`, `uncertain`, `retryAfterMs` (Python
  `request_id`, `retry_after` in seconds).
- `RunError extends AgentError`: a failed run, with `run`. When a model call failed it,
  `run.error` also has `errorClass` (`billing`, `rate_limit`, `server`, `refusal`, `auth`,
  `timeout`, `other`), `providerStatus`, `retryable` and `model`: branch on those, not the
  message ([Model failures](https://run.camelai.com/docs/reference/errors.md#model-failures)). `run.servedModel` (Python
  `run.served_model`) is the model that made its last response.

The SDKs retry 429 and 503 (honouring `Retry-After`) and transient failures of
idempotent requests. See [Errors](https://run.camelai.com/docs/reference/errors.md).

## The lower-level API

`Agents` and `Agent` are built on `AgentRuntime` and `AgentClient`, which stay
available and stable for code that needs the wire's shape: `agents.runtime`,
`agent.client`, or `new AgentRuntime({ url, apiKey })` directly.

| TypeScript | Python | |
| --- | --- | --- |
| `runtime.upsertAgent(key, options)` | `runtime.upsert_agent(key, …)` | upsert, returning credentials (not connected) |
| `runtime.createAgent({ tools, ttlSeconds, idempotencyKey, … })` | `runtime.create_agent(tools=[...], …)` | provision and connect; with `idempotencyKey`, the same as an upsert |
| `runtime.connectAgent(session, { tools, attach, takeover, connection })` | `runtime.connect_agent(session, tools=, attach=, takeover=, connection=)` | connect with stored credentials (`connection: "lazy"`: see [Agents](https://run.camelai.com/docs/reference/sdk.md#agents)) |
| `runtime.browserToken(agentId, options)` | `runtime.browser_token(agent_id, …)` | a browser token |
| `runtime.me()` | `runtime.me()` | who the API key is: `tenant`, your tenant's id, which `serveTools` takes |
| `runtime.setProvider(name, config)`, `providers()`, `deleteProvider(name)` | `set_provider(name, base_url=, models=, api_key=, headers=)`, `providers()`, `delete_provider(name)` | a provider of your own: any OpenAI-compatible server and its models; see [Custom models](https://run.camelai.com/docs/guides/custom-models.md) |
| `runtime.listAgents()` | `runtime.list_agents()` | the tenant's agents, each with the `key` it was made with (`null` without one) and its `name` |
| `runtime.upsertDefinition(key, input)`, `createDefinition`, `updateDefinition`, `definition(s)`, `deleteDefinition` | `upsert_definition(key, …)`, `create_definition`, … | definitions; the same key is the same definition |
| `runtime.createVolume`, `volume(id)`, `mounts`, `setMounts` | `create_volume`, `volume(id)`, … | volumes and mounts |
| `runtime.projects.create({ key, template })`, `project.mount`, `project.publish`, `publishTool` | `camelai_run.projects`: `Projects(runtime).create(key, template=)`, `mount`, `publish`, `publish_tool` | [projects](https://run.camelai.com/docs/guides/projects.md): an agent builds in a keyed volume; your code checks and publishes snapshots |
| `runtime.inbox(state)`, `toolSources(agentId)` | `inbox(state=)`, `tool_sources(agent_id)` | inputs across agents; an agent's tools |
| | `set_scope_key(scope, provider, api_key=, base_url=, headers=, region=)`, `key_scope(scope)`, `delete_scope_key(scope, provider)`, `delete_key_scope(scope)` | a key scope's provider keys (`/v1/key-scopes`): agents made with `key_scope=` use them first; see [Models and keys](https://run.camelai.com/docs/guides/models-and-keys.md) |
| | `set_scope_provider(scope, name, base_url=, models=, …)`, `scope_providers(scope)`, `delete_scope_provider(scope, name)` | a key scope's own providers, as `set_provider`'s |
| | `usage(days=)` | tokens and cost per day and model (`GET /v1/usage`) |
| | `tokens()`, `create_token(name)`, `revoke_token(token_id)` | API tokens; a new one's secret is in `create_token`'s answer only |
| | `create_webhook(url, events, description=)`, `webhooks()`, `webhook(id)`, `update_webhook(id, …)`, `delete_webhook(id)`, `rotate_webhook_secret(id)` | webhook endpoints; see [Webhooks](https://run.camelai.com/docs/guides/webhooks.md) |
| | `rotate_agent_credentials(agent_id)` | a new token for an agent; the old one stops at once |
| `runtime.telemetry.set({ endpoint, headers, protocol, sampleRate, include: { content } })`, `get()`, `test()`, `clear()` | `await runtime.telemetry.set(endpoint, headers=, protocol=, sample_rate=, include_content=)`, `get()`, `test()`, `clear()` | export each run as an OpenTelemetry trace to your OTLP/HTTP endpoint (see [Telemetry](https://run.camelai.com/docs/reference/sdk.md#telemetry)) |
| `client.prompt(text, { from, actor, files, metadata, whileRunning, output, idempotencyKey, signal })` | `client.prompt(text, from_=, …)` | a run's raw result: `{ reply, output, error, stopped, inputs, files, toolErrors, … }`; rejects on a runtime error. `output` here is `{ schema }`, a JSON Schema |
| `client.request(method, params, options)` | `client.request(method, params, …)` | any request (`prompt`, `continue`, `execute`, `configure`, `status`, `abort`); `traceparent` (`traceparent=`) continues your trace |
| `client.waitForRequest(id)` | `wait_for_request(id)` | wait for a request already sent, from any process |
| `client.requestStatus(id, { wait })`, `outcomes()` | `request_status(id, wait=)`, `outcomes()` | a request's record (`wait`: seconds, at most 25, to wait for it to settle first); every request's state |
| `client.answer(inputId, { action, content, from })`, `inputs(state)` | `answer(input_id, action=, …)`, `inputs(state=)` | inputs, raw |
| `client.execute(code)` | `execute(code)` | run code in the sandbox with the agent's tools, outside its history |
| `client.steerMessage(text, options)` | `steer_message(text, …)` | `prompt` with `whileRunning: "steer"`, answered as soon as the runtime has it: `{id, status: "accepted" \| "taken" \| "queued", steeredInto?}` (`client.prompt(text, { whileRunning: "steer" })` waits for the turn that took it) |
| `client.status()`, `client.abort({ queued })` | `status()`, `abort(queued=)` | whether the agent is busy (`busy`, `activeRun`, `queuedRuns`, as `GET /v1/agents/{id}` says too); stop it (its running turn, and unless `queued: "keep"` the runs queued behind it) |
| `client.steer(text)` | `steer()` | the legacy `steer` request, which holds the message for the running (or next) turn; new code uses `steerMessage` |
| `client.setMetadata({ name, type })` | `set_metadata(name=, type=)` | rename or regroup |
| `client.destroy()`, `close()` | same | delete the agent; close the connection |

`client.prompt()` resolves with the run's raw result, even when the model
failed (`result.error`), and rejects only on a runtime error. Requests have no
timeout unless you pass `timeoutMs` or `signal` (Python: `timeout`).

### Telemetry

`runtime.telemetry` (in the simple interface, `agents.runtime.telemetry`) is the
tenant's trace export, `/v1/telemetry`: each run becomes an OpenTelemetry trace,
with spans for its model calls and tool calls, sent to an OTLP/HTTP endpoint
(LangSmith, Langfuse, Honeycomb, Datadog, Tempo, your own collector). See
[Observability](https://run.camelai.com/docs/guides/observability.md) for the spans, presets and what is
exported.

```ts
await agents.runtime.telemetry.set({ endpoint: "https://api.honeycomb.io/v1/traces", headers: { "x-honeycomb-team": key } });
const { ok, traceId } = await agents.runtime.telemetry.test();   // one test span, sent now
const run = await agent.run("Summarize ticket 123", { traceparent }); // continues your trace
```

```python
await agents.runtime.telemetry.set("https://api.honeycomb.io/v1/traces", headers={"x-honeycomb-team": key})
result = await agents.runtime.telemetry.test()
run = await agent.run("Summarize ticket 123", traceparent=traceparent)
```

- `set` changes only what it is given: options left out keep their current
  values (their defaults the first time, when `endpoint` is needed). `headers`
  are stored encrypted and never returned: `get()` lists their names. Left out
  of a later `set`, they stay while the endpoint keeps its origin, and are
  dropped when it moves; `{}` removes them. `protocol` is `http/protobuf`
  (default) or `http/json`, `sampleRate` (`sample_rate=`) the share of runs
  traced (default 1), and `include: { content: true }` (`include_content=True`)
  also exports prompts, replies and tool arguments and results.
- `get()` is the settings with `status: { lastExportAt, lastError, lastErrorAt }`,
  or `null` (`None`) when none are set. `clear()` stops export: `{ deleted }`,
  false when nothing was set. `test()` is `{ ok, status?, error?, traceId, spanId }`.
- `traceparent` is also taken by `client.prompt`, `client.request`, and
  `createAgent` / `upsertAgent` (`create_agent` / `upsert_agent`) for their
  first `prompt`. A run's record (`client.requestStatus(id)`, typed as
  `RequestRecord`) carries `trace: { traceId, spanId, parentSpanId?, sampled }`
  while the tenant exports telemetry.

### Transcriptions

`agents.transcriptions` (`runtime.transcriptions`) is speech to text on its own, `POST /v1/transcriptions`: audio in,
its transcript out, nothing kept. Audio attached to a message needs none of it: it is transcribed as it is attached.
See [Voice and audio](https://run.camelai.com/docs/guides/voice.md).

```ts
const { text, language, durationSeconds, costUsd } = await agents.transcriptions.create({ file: await readFile("voice.ogg"), language: "en" });
const call = await agents.transcriptions.create({ url: "https://example.com/call.m4a" });
```

```python
result = await agents.transcriptions.create(Path("voice.ogg"), language="en")
call = await agents.transcriptions.create(url="https://example.com/call.m4a")
text = camelai_run.sync.Agents().transcriptions.create(b"...")["text"]  # synchronous
```

`create` takes the audio as `file` (bytes or a Blob/File; Python: bytes or a local path) or `url`, and `language`,
`prompt`, `keyScope` (`key_scope=`), and `subject`, `context`, `actor` for its `usage.recorded` event.
It resolves with `{ text, language, durationSeconds, model, costUsd }` (Python: that dict). It is not
retried, as each attempt is billed.

### Images

`agents.images` (`runtime.images`) makes images on their own, `POST /v1/images`: `generate(prompt, options?)` from a
prompt, `edit(prompt, images, options?)` from up to 4 images (bytes, a Blob/File or `{ url }`; Python: bytes, a local
path or `{"url"}`), with `mask` for the first. Agents make images with the `generate_image` builtin instead. See
[Images](https://run.camelai.com/docs/guides/images.md).

```ts
const { images: [image], costUsd } = await agents.images.generate("A watercolor camel at dawn", { size: "1536x1024" });
await writeFile("camel.png", Buffer.from(image.data!, "base64"));
const blue = await agents.images.edit("Make the camel blue", [await readFile("camel.png")], { quality: "high" });
```

```python
result = await agents.images.generate("A watercolor camel at dawn", size="1536x1024")
Path("camel.png").write_bytes(base64.b64decode(result["images"][0]["data"]))
blue = await agents.images.edit("Make the camel blue", [Path("camel.png")], quality="high")
images = camelai_run.sync.Agents().images.generate("A camel")["images"]  # synchronous
```

Options: `size`, `quality` (`low`, `medium`, `high`), `format`, `background`, `n` (1 to 4), `keyScope` (`key_scope=`),
`volumeId` and `path` (`volume_id=`, `path=`: save the images there and answer their paths), and `subject`, `context`,
`actor` for its `usage.recorded` event. It resolves with `{ images: [{ contentType, width, height, data } | { …,
volumeId, path, size, version }], model, usage: { inputTokens, outputTokens }, costUsd }` (Python: that dict). It is
not retried, as each attempt is billed. A run's `usage.imageCostUsd` is what its `generate_image` calls cost.

### Events, reconnects and replay

An eager client (and a lazy one, while something listens) holds one SSE stream
per agent (`GET /clients/:id/events`) and reconnects with backoff. A lazy client
without a listener holds none: each request it is waiting on asks for its own
outcome, a long poll of up to 25 s at a time, and a refusal for good (401, 403,
404, 410) fails it. When a listener comes (`agent.stream()`), the client
connects before sending the run, so the listener sees it from its start, and
lets the stream go once the last listener is gone; the next stream starts from a
snapshot, as a new client does. The runtime numbers events and replays them from memory
from `Last-Event-ID`: up to 512 events or about 2 MiB. Where it cannot (a
restarted node, a cursor too old), the SDK asks for a snapshot of the running
turn instead (`?snapshot=1`), and recovers every settled request's outcome from
`/state`, so a run's result never depends on its event arriving. A request still
waiting also asks for its own status every 30 s (`pollMs`, Python
`poll_interval`).

A `message_update` is its delta alone (`assistantMessageEvent`), not the whole
message: fold the message from its `message_start` and the deltas since
(`@camelai/run/watch` does). A subscriber that cannot replay gets a
`snapshot` of the running turn first. See the [event
reference](https://run.camelai.com/docs/reference/events.md).

`onEvent` (`on_event`) handlers run one at a time, in order, apart from the
stream: a slow handler never holds up tool calls, and what it throws goes to
`onError`. Past 10,000 events waiting, streamed deltas are dropped (with one
`onError`) until it catches up. `close()` stops them: the call in progress may
finish (`close()` waits up to 2 seconds for it), and events still queued are
dropped.

### Tool calls and connections

Tool calls are MCP: each attached connection is an MCP session with the SDK as
the server (the runtime sends `initialize`, `tools/list`, `tools/call` and
`notifications/cancelled` as `mcp` events, and the SDK answers with `POST
/clients/:id/mcp`, naming its connection). A call goes to one connection, once.
If the connection drops or the call's deadline passes before its answer arrives,
the model gets an "outcome unknown" result and the call is never sent again.
A connection that closes (`close()`) first POSTs a
`notifications/agent-runtime/draining` notification: the runtime sends it no new
calls, and it answers those it has before it disconnects. A connection replaced
by a takeover likewise stays open, up to 30 seconds, until its calls are
answered, then hears it was replaced.

A connection whose tools differ from those the agent was last given (the ready
event's `toolsHash`) declares them, between the agent's turns (`syncTools:
false` to leave them). One connection at a time serves an agent's tools. A second is refused with
`APPLICATION_CONNECTED` unless it asks to take over (`takeover`), or the one
serving them is closing; the SDK names
its connection when it reconnects, so it keeps its place. A connection that was
replaced, or finds the tools taken when it reconnects, hears
`APPLICATION_REPLACED` / `APPLICATION_CONNECTED` on `onError` and goes on
following the agent without serving them. A client with `attach: false` follows
the stream read-only (`?watch=1`) and never contends.

This is not an exactly-once transaction across the runtime and your database.
Authorization, transactional writes and idempotency stay in your tools: use
`context.idempotencyKey`.

### History in pages

`historyPage({ limit, before })` (`GET /clients/:id/history?limit=50`) answers
whole turns, oldest first, with at least `limit` messages where there are that
many: `{ entries: [{ index, message }], next, total }`. Pass `next` as `before`
for the page before it (`null` at the start). A settled page never changes, so it
can be cached. `history()` answers the whole transcript.

### Portable use

The portable entry (`@camelai/run`) imports no Node modules and reads
environment variables only where the platform has them, so it runs on
Cloudflare Workers and other runtimes without a filesystem. A client keeps its
stream's cursor in memory; a new one starts from a snapshot of the running turn.

### The wire

`GET /clients/:id/events` streams SSE; `POST /clients/:id/requests` accepts
idempotent requests (with a W3C `traceparent` header, the run continues that trace); `POST /clients/:id/mcp` carries the application's MCP
messages; all with the agent's token as `Authorization: Bearer`. `/clients/*`
refuses requests with a browser `Origin`. Application code should use the SDK
rather than speak this protocol.

### Webhooks

`verify_webhook(body, headers, secret)` (Python; TypeScript uses any Standard
Webhooks library) checks a webhook request the runtime sent and returns its
event: the signature against the endpoint's secret (or a list of secrets),
compared in constant time, and that it was sent within `tolerance=` seconds
(300) of now. It raises `WebhookVerificationError`. See
[Webhooks](https://run.camelai.com/docs/guides/webhooks.md#verifying-and-handling).

## Agent identity and Studio

`name` identifies an agent and `type` groups agents in Studio, e.g. `September
release` and `Docs launch`, both `release-reviewer`. Rename or regroup without
changing its history with `agent.client.setMetadata({ name, type })`
(`set_metadata(name=, type=)`). SDK-created agents appear in a local Studio
(`npm run studio`) at `/studio/agents`; Studio observes the runtime, and your
application keeps serving its tools.

## 0.20.0 (TypeScript) / 0.16.0 (Python), 2026-10-10

Needs runtime 0.9.0 or later (run.camelai.com has it).

- Workers your tools prepare: `spawnAgent({ agent, task, name?, output? })` (from `@camelai/run` and
  `@camelai/run/server`; Python `spawn_agent(...)`) builds a tool result that starts a background sub-agent. See
  [Workers your tools prepare](https://run.camelai.com/docs/guides/multi-agent.md#workers-your-tools-prepare).
- `agentNotice(message)` (Python `agent_notice`) tells sub-agents' notifications and messages apart in history, with
  `output`, `usage` and `inputs`. `<AgentChat>` renders them as notices; the chat's `UserChatMessage.agent` carries
  them.
- `agent.abort({ children: "keep" })` keeps background sub-agents running (aborting stops them by default).
  `subagent_message` is in the event types, and `SubagentView.status` includes `aborted`.
- `delegate: { maxParallel, maxDepth }` alone is sent with no builtin, to bound the sub-agents your tools start.
- `createAgentHandler`'s `browserToken.scopes` (add `children` to read sub-agents with the chat's token).
- `CallToolResult` has `_meta`.

## 0.19.0 (TypeScript) / 0.15.0 (Python), 2026-10-09

Needs runtime 0.8.0 or later (run.camelai.com has it).

- Images: `agents.images.generate(prompt, options?)` and `agents.images.edit(prompt, images, options?)` (also
  `runtime.images`), with the `ImageOptions`, `ImagesResult` and `GeneratedImage` types. See [Images](https://run.camelai.com/docs/reference/sdk.md#images).
- `Builtin` includes `generate_image` and `agents`; `RunUsage` has `imageCostUsd`; `usage.recorded` events type
  `kind: "image"` and `images`.
- Tool servers: `identity.parentAgentId` and `identity.rootAgentId` on a sub-agent's calls (from `delegate` or
  `spawn_agent`). A sub-agent's notification in history carries `source: { kind: "agent", agentId, name }`.
- Python: `agents.images.generate(prompt, ...)` and `agents.images.edit(prompt, images, ...)` (also `runtime.images`,
  and the synchronous clients'), images given as bytes, local paths or `{"url"}`; `identity.parent_agent_id` and
  `root_agent_id`.
- The CLI's MCP tools take `generate_image` among an agent's builtins.

## 0.18.0 (TypeScript) / 0.14.0 (Python), 2026-10-09

Needs runtime 0.7.0 or later (run.camelai.com has it).

- Pinned versions: `project.publish({ pin, labels })`, `project.pin(version, labels?)`, `project.unpin(version)` and
  `project.versions({ labels })`. A pinned version is kept past `keep`, up to 10,000 of them. `ProjectVersion` has
  `pinned` and `labels`.
- Snapshots: `volume.snapshot({ name, pinned, labels, files })`, where `files` makes a snapshot of the contents given,
  leaving the volume untouched, and answers each file's `sha256` (`contents`). Also `volume.snapshots({ labels })`,
  `volume.updateSnapshot(id, { pinned, labels })` and `volume.deleteSnapshot(id, { force })` (a pinned one needs
  `force`). `VolumeSnapshot` has `pinned` and `labels`.
- Python: the same, snake_case (`update_snapshot`, `delete_snapshot(id, force=True)`, `project.pin` / `unpin`).

## 0.17.0 (TypeScript) / 0.13.0 (Python), 2026-10-09

Needs runtime 0.6.0 or later (run.camelai.com has it). Python 0.13.0 has the same features, with snake_case names.

- Projects: `runtime.projects.create({ key, template })` and `get(id)`; `project.mount(path)`, `files`, `versions`,
  `publish({ validate, store, keep, idempotencyKey })`, `restore(version)` and `archive({ version })`; and `publishTool`
  for `serveTools`, which finds the project from the call's identity. `validate` may return `{ problems, data }`, and
  `data` reaches `store` as `checked`. Python: `camelai_run.projects`. See [Projects](https://run.camelai.com/docs/guides/projects.md).
- Volumes: `createVolume({ key })` gives a key's volume, the same one every time; `createVolume({ name },
  { idempotencyKey })`. Also `volume.readAll({ prefix, glob, snapshot })`, `runtime.volumes(ids)`,
  `volume.changes(since, { prefix })`, `{ snapshot }` on `read` and `list`, `volume.restore(snapshot)` and
  `volume.archive({ snapshot, path, glob })` (a tar.gz).
- Mounts: `MountInput` takes `{ workspace: false }` (no own workspace) and `{ workspace: true, path? }` (where it
  goes, e.g. `/scratch`). Changed: an agent's own workspace now stays beside the `mounts` it is given. Upserts take
  `remount: true` to change an existing agent's mounts.
- Agents: `maxOutputTokens` and `temperature`; `mcpServers` (`InlineMcpServer`, no credentials); `importMessages`
  (Anthropic Messages, OpenAI Responses or Chat Completions) and `toPiMessages` to convert one locally; `idleTtlSeconds`.
  Definitions take `applyOnUpdate`, `runLimits` (typed now) and `limits.idleTtlSeconds`. Python's definition methods
  take snake_case field names too.
- Runs: `runLimits` on one run; `agent.send(text)` and `agent.wait(id)` (`client.submit` one level down) to send
  without waiting; `result.limit` says which spend limit stopped a run.
- Voice: `agents.transcriptions.create({ file | url, language, prompt })`; attachments take `{ url }` and
  `transcribe`, and a message with audio may have no text (a stateless run's `input` may be `""`). `usage.recorded`'s
  type takes `kind: "transcription"`, `audioSeconds`, and a null `agentId` / `subject` for a transcription made
  alone. See [Voice and audio](https://run.camelai.com/docs/guides/voice.md).
- Tool servers: `serveTools` takes a function of the caller's identity in place of the tools, and a `ToolServer`'s
  `listTools(context)` gets `{ identity, origin, signal }`. `identity.requestId` and `toolCallId` are set during a
  turn. Audiences may be `urn:camelrun:<tenant>:<name>`. `verifyFileUrl` checks a file URL a tool was sent. In
  tests, `testRuntime().fileUrl()` makes one, and `callTool` sends a fresh idempotency key on each call.
- Chat: `ChatSnapshot.loaded` (`AgentView.loaded`) is true once history and state have been read. The React kit's
  empty state waits for it.
- Python only: `camelai_run.sync`, a synchronous client for scripts and WSGI apps (with `serve_tools`, `TestRuntime`
  and `verify_runtime_token`); `verify_webhook`; and `AgentRuntime` methods for key scopes, API tokens, usage,
  webhooks and agent credentials.

## 0.12.0 (Python), 2026-10-08

Python's side of TypeScript 0.16.0. Needs runtime 0.5.0 or later (run.camelai.com has it).

- Stateless runs: `agents.run(input, instructions=…, output=…)` runs once with nothing carried over and no agent
  made; `agents.runs` creates, gets, streams, aborts and deletes them, and reads their `messages` and `events` (the
  lower level: `runtime.create_run`, `get_run`, `wait_for_run`, `abort_run`, `delete_run`, `run_messages`,
  `run_events`). See [Stateless runs](https://run.camelai.com/docs/guides/stateless-runs.md).
- Agent handles connect lazily: `Agents()` handles hold their event stream only while a run streams, so a server
  with many agents holds no idle connections; handles that serve tools or have `on_event` or `on_input` are
  unchanged. `Agents(connection="eager")` keeps the old behaviour; `connect_agent` takes `connection="lazy"` to opt in.
- `run`, `stream` and `client.prompt` take `history="none"`; `upsert` and definitions take `code_mode=False`.
  `agent.config_hash` from `upsert` and `get`.
- Breaking: `agent.steer()` returns a receipt as soon as the runtime has the message (`{id, status, steeredInto?}`);
  `steer(text, wait=True)` returns the run that took it, as before. `client.steer_message` is the receipt at the
  lower level. `abort(queued="keep" | "cancel")` returns `{aborted, cancelled?}`.
- A stream the runtime closes on purpose (`event: reconnect`) is reconnected at once, resuming with `Last-Event-ID`.
- `tool(exposure=)`: `"direct"`, `"codemode"` or `"both"`, how the model may call the tool.

## 0.16.0 (TypeScript), 2026-10-07

Needs runtime 0.5.0 or later (run.camelai.com has it).

- Stateless runs: `agents.run({ instructions, input, output })` runs once with nothing carried over and no agent made;
  `agents.runs` creates, gets, streams, aborts and deletes them, and reads their `messages` and `events` (the lower
  level: `runtime.createRun`, `getRun`, `waitForRun`, `abortRun`, `deleteRun`, `runMessages`, `runEvents`). See
  [Stateless runs](https://run.camelai.com/docs/guides/stateless-runs.md). CLI: `camelrun run --stateless`, `camelrun runs get <runId>`.
- Agent handles connect lazily: `new Agents()` handles hold their event stream only while `agent.stream()` reads a
  run, instead of from `upsert`/`get` until `close()`, so a server with many agents holds no idle connections.
  Handles that serve tools or have `onEvent`, `onInput` or `onConnection` are unchanged. `connection: "eager"` on
  `Agents` or a single call keeps the old behaviour; the lower-level `connectAgent` takes `connection: "lazy"` to opt
  in. A lazy handle's `upsert`/`get` no longer waits for a connection, so an unreachable stream shows up at the
  first run rather than there.
- `run`, `stream` and `client.prompt` take `history: "none"`: the run sees the agent's instructions and its own
  message only, for many independent questions to one agent without an agent create each. `upsert` and definitions
  take `codeMode: false` (definitions also `fileTools: false`): no `js_exec`, and a tool-less agent's system prompt
  shrinks to its instructions and a sender note.
- `agent.configHash` from `upsert` and `get`, and `configHash` on `listAgents()`: an upsert of the configuration an
  agent has is not counted as an agent create.
- Breaking: `agent.steer()` resolves as soon as the runtime has the message, with a receipt
  (`{ id, status: "accepted" | "taken" | "queued", steeredInto? }`); `steer(text, { wait: true })` resolves with the
  run that took it, as before. `client.steerMessage` is the receipt at the lower level; `client.prompt` with
  `whileRunning: "steer"`, `createAgentHandler`'s waiting send and `camelrun run --steer` still answer with the
  turn's outcome.
- `agent.abort({ queued: "keep" | "cancel" })` and `client.abort(…)` resolve with `{ aborted, cancelled? }`. A runtime
  with queue cancellation stops the runs queued behind the running turn too (code `cancelled`) unless
  `queued: "keep"`.
- A stream the runtime closes on purpose (`event: reconnect`: a drain, or the agent moved) is reconnected at once,
  resuming with `Last-Event-ID`; other closes keep their backoff. The agent client and `watchAgent` do this.
- `runLimits` takes `firstTokenSeconds` and `idleSeconds` (how long a model request may go quiet before it fails
  as stalled and is retried); `turn_resumed` / `turn_recovered` events carry `handoff` (`retire`, `drain`).
- `createAgentChat` (and so the React, Vue, Svelte and Solid chats) stays `streaming` from the run's first reply
  until it ends, through tool calls, instead of dropping back to `submitted` between messages.
- CLI: `camelrun models` (and `list_models`) show `toolCallStreaming`.

## 0.15.0 (TypeScript) / 0.11.0 (Python), 2026-10-03

Needs runtime 0.4.0 or later (run.camelai.com has it).

- Sub-agents: `delegate` settings on `upsert` / definitions (`delegate: { agents, instructions?, maxDepth?,
  maxParallel? }`, Python `delegate=`) turn on the `delegate` built-in. `subagents: true` on `stream` / `watch`
  (Python `subagents=True`) relays `subagent_start` / `subagent_event` / `subagent_end`; `run.toolCalls[].agentId`
  names the sub-agent, and `run.usage.subagentCostUsd` its spend. `@camelai/run-react`'s chat shows a sub-agent's
  transcript under its delegate call (`watch: { subagents: true }`). CLI manifests take `delegate`.

## 0.14.0 (TypeScript) / 0.10.0 (Python), 2026-10-03

Needs runtime 0.3.0 or later (run.camelai.com has it).

- Forking: `agent.fork({ key?, name?, atMessage? })` (Python `fork(...)`), `agents.fork(...)` and
  `runtime.forkAgent(...)` (`fork_agent`) copy an agent's configuration, committed history and workspace
  into a new agent; the result carries `forkedFrom` (`forked_from`). CLI `camelrun agents fork`.
- `agents.get(keyOrId, { tools, ... })` returns an existing agent's handle without changing its configuration
  (`runtime.agentCredentials()` / `agent_credentials()`).
- OpenTelemetry: `runtime.telemetry.get / set / clear / test` configures trace export, and a `traceparent`
  option on `run`, `stream`, `prompt`, `request` and create continues your trace. CLI `camelrun telemetry`
  (header values from `@env:VAR` or `@stdin`) and `run --traceparent`.
- Stream `tool_call` / `tool_result` parts also carry `tool` and `toolCallId` (`tool_call_id`), the names
  `run.toolCalls` uses; `name` and `id` stay.
- `RunError.status` is documented as 0 for run failures: branch on `code`.

## 0.13.0 (TypeScript) / 0.9.0 (Python), 2026-10-03

- Run limits: an agent or definition may set `runLimits: { maxResponses, maxSeconds }`
  (Python `run_limits=`), at most the runtime's maximums. A run that reaches one ends
  `stopped: "turn_limit"`; send another message to continue.
- A run whose model has no key, or whose key the provider refused, is `failed` with
  code `model_key_missing` / `model_key_invalid` and says what to do; `RunError`
  carries both.
- Compaction events may carry `background: true` (summaries now run in the
  background before a conversation reaches its limit); `compaction_end.skipped` is a
  string.
- `createAgentHandler`'s waited `send` returns `status`.
- The 409 for unconnected tools names each SDK's call (`connectAgent` /
  `connect_agent`).
- Python: `camelai-run[pydantic]` installs pydantic for output schemas, and
  `camelai_run.__version__`.
- CLI: reads the runtime's URL from `CAMELAI_BASE_URL` (as the SDKs do; `CAMELAI_URL`
  still works). `create-run-app` has a real `--help` and takes the key from the
  environment.

## 0.12.0 (TypeScript) / 0.8.0 (Python), 2026-10-01

- Structured output: `run(text, { output })` (`run(text, output=)`) takes a
  zod (4.2+), TypeBox or JSON Schema object schema (Python: a pydantic model
  class or a JSON Schema dict), and `run.output` is the answer, typed and
  parsed. A run that ends without one fails with `output_missing`; one the
  schema's own checks reject, with `output_invalid`. See
  [Structured output](https://run.camelai.com/docs/guides/structured-output.md). Needs a runtime with
  structured output (run.camelai.com has it).
- `run.toolCalls` (`run.tool_calls`): the tool calls a run made, each
  `{ tool, toolCallId?, innerCallId?, ok, code? }`, the first 100.
- `client.requestStatus(id, { wait })` (`request_status(id, wait=)`) waits up
  to 25 s for the request to settle. `createAgentHandler`'s `send` takes `wait`
  (`true` or 1–25 seconds) and returns the reply when the run ends, and a new
  `wait` action asks about an earlier message without sending it again.
- `close()` drains: it tells the runtime it is shutting down, finishes the tool
  calls it is running for up to 25 s (`drainMs` / `drain=`), then disconnects,
  so a deploy that closes on SIGTERM loses no call. `drainMs: 0` (`drain=0`)
  closes at once, as before; `destroy()` never waits.
- A confirmation (`context.confirm`) is answered with `answer(true)` /
  `answer(True)` or `false`, as the docs show.
- Python: the package ships `py.typed` and `__all__`, and its missing-key error
  names `CAMELAI_API_KEY`.
- `camelrun mcp`: `list_agents` reports `loaded` and `toolsConnected`, its
  errors no longer suggest CLI commands, and `add_schedule` is marked
  open-world.

## 0.11.2 (TypeScript) / 0.7.2 (Python), 2026-10-01

- `@camelai/run` and `camelai-run` ship this version's docs for coding agents:
  `SKILL.md` (the setup skill also served at https://run.camelai.com/SKILL.md)
  and `sdk.md` (this reference), at `node_modules/@camelai/run/docs/` and next
  to `camelai_run`'s code. `camelai_run` is now a package rather than a single
  module; imports are unchanged.
- A missing API key's error (`new Agents()`, `Agents()`, the CLI) says where to
  create one, https://run.camelai.com/console/tokens, and points coding agents
  at SKILL.md.
- `npm create @camelai/run-app` writes an `AGENTS.md` (and a `CLAUDE.md` that
  imports it) for coding agents, and its agent names no model, so it gets the
  account's default; `AGENT_MODEL` still chooses one.

## 0.11.1 (TypeScript) / 0.7.1 (Python), 2026-09-30

- `@camelai/run/watch` (and so `createAgentChat`) reads a snapshot's history before
  asking whether a turn runs. A message sent just as the watcher connected could
  otherwise show in history with no turn running, and a chat's status went
  `submitted`, `ready`, `submitted` before the reply streamed.
- `verifyRuntimeToken` / `serveTools` (`verify_runtime_token` / `serve_tools`)
  with `runtime` set to either of the hosted runtime's URLs,
  `https://run.camelai.com` or `https://agents.camelai.dev`, expect the issuer
  `https://agents.camelai.dev`, which the hosted runtime's identity tokens name
  at both. Pass `issuer` to expect another.
- The default `url` (and the CLI's) is `https://run.camelai.com`, the hosted
  runtime's new address. `https://agents.camelai.dev` keeps working, with the
  same agents, tokens and OAuth grants, so an earlier version or a configured
  URL needs no change.
- `close()` stops `onEvent` (`on_event`): events still queued when it is called
  are dropped instead of handed over, and `close()` waits only for the call in
  progress. Before, a slow handler kept being called for the whole backlog after
  `close()` returned.

## Changes in 0.9 (Python 0.5)

- New: `Agents`, `upsert`, `run`, `stream`, `Run`, `RunError`, `input.answer()`.
  The lower-level API stays.
- The default `url` is `https://agents.camelai.dev` (was localhost); the API key
  also reads `CAMELAI_API_KEY`.
- `onEvent` is no longer awaited in the stream: handlers run in order apart from
  it, and their errors go to `onError`. Python's async `on_event` now runs.
- Requests have no default timeout (was 180 s); pass `signal` / `timeoutMs`
  (Python `timeout=`). At most 1000 may wait at once (was 8).
- A tool returning `undefined` sends `null` (was a failure).
- `context.idempotencyKey` is the stable key for side effects; `callId` changes
  with each attempt, as it always did.
- Tools may time out per tool (`timeoutMs`, `@tool(timeout=)`) and report
  `context.progress()`.
- Python tools may be plain functions (run in a thread).
- One process serves an agent's tools at a time (`APPLICATION_CONNECTED`,
  `takeover`, `attach: false`).
- `agent.session`'s token is left out of logs and JSON; use `agent.id` to name an
  agent.
- The types no longer come from Pi: `Message`, `AgentEvent` and the rest are the
  SDK's own.
- Keyed agents (made with an idempotency key) live until deleted, and upsert
  instead of failing when their configuration changes (server-side). The
  lower-level `createAgent` / `create_agent` without a key of yours still makes a
  scratch agent that lives a day.
- `serveTools`, `runtimeAuth`, `verifyRuntimeToken` (`serve_tools`,
  `verify_runtime_token`) require `tenant`, and refuse other tenants' tokens.
- `nodeListener` no longer trusts `X-Forwarded-*` unless `trustProxy: true`; set
  `origin` behind a proxy.
- The session's token is left out of its JSON (TypeScript) and it is not
  JSON-serializable (Python): store credentials explicitly,
  `{ id: session.id, token: session.token }` or `session.credentials()`.

## Examples

[`examples/`](https://github.com/qaml-ai/run/blob/main/examples) has runnable programs, each of which exits when done:

| | |
| --- | --- |
| [`quickstart.ts`](https://github.com/qaml-ai/run/blob/main/examples/quickstart.ts), [`quickstart.py`](https://github.com/qaml-ai/run/blob/main/examples/quickstart.py) | the quickstart |
| [`stream.ts`](https://github.com/qaml-ai/run/blob/main/examples/stream.ts) | streaming a run to the terminal |
| [`approval.ts`](https://github.com/qaml-ai/run/blob/main/examples/approval.ts) | a tool that needs approval, answered in code |
| [`release-board.ts`](https://github.com/qaml-ai/run/blob/main/examples/release-board.ts), [`inventory.py`](https://github.com/qaml-ai/run/blob/main/examples/inventory.py) | an application's tools over its own data |
| [`team-todos.ts`](https://github.com/qaml-ai/run/blob/main/examples/team-todos.ts) | served tools with the runtime's identity tokens |
| [`file-report.ts`](https://github.com/qaml-ai/run/blob/main/examples/file-report.ts) | files in and out |

Each reads `CAMELAI_API_KEY` (and `CAMELAI_BASE_URL` for a runtime of your own).
`npm run demo:clients` runs the release board and inventory examples against a
temporary local runtime with scripted code, calling no model.

---

<!-- https://run.camelai.com/docs/reference/cli.md -->

# camelRun CLI and MCP server

`camelrun` deploys and manages agents from a terminal, a script or CI. Coding
agents (Claude Code, Cursor, Codex…) get the same operations over MCP, so they can
write an agent's manifest, deploy it, talk to the agent and read what it did:
from the hosted MCP server at `https://run.camelai.com/mcp`, with nothing to
install ([below](https://run.camelai.com/docs/reference/cli.md#hosted-mcp-server)), or from `camelrun mcp` on your machine,
which can also deploy the manifests in your repository.

```sh
npm install -g @camelai/camelrun   # Node 22+; or npx @camelai/camelrun <command>
camelrun login                     # paste an API key from the console's API tokens page
```

`login` checks the key and saves it to `~/.config/camelrun/credentials.json`
(mode 600). `CAMELAI_API_KEY` and `CAMELAI_BASE_URL` (for a self-hosted runtime, as
the SDKs read it; `CAMELAI_URL` works too), or
`--api-key` and `--url`, take precedence over it.

## Deploy from a manifest

An agent's configuration lives in your repository as `agent.yaml`, and `camelrun
deploy` makes it so in the runtime. `camelrun init [key]` writes one to start from.

```yaml
key: support                     # the same key is the same definition
name: Support
model: anthropic/claude-sonnet-5-5
systemPromptFile: prompts/support.md
builtins: [web_search, ask_user]
mcpServers:
  - name: app
    url: https://app.example.com/mcp
    auth: { type: bearer, token: "${APP_MCP_TOKEN}" }
openApi:
  - name: billing
    specFile: openapi.yaml
    auth: { type: runtime }
agents:                          # keyed agents made from it on deploy
  - key: support-main
  - key: support-eu
    systemPromptAppend: Answer customers in the EU region.
```

- Every field but `key`, `agents`, `systemPromptFile` and an OpenAPI source's
  `specFile` is sent as the [definition](https://run.camelai.com/docs/guides/definitions.md) (`name`,
  `model`, `systemPrompt`, `thinkingLevel`, `fileTools`, `builtins`, `webSearch`,
  `mcpServers`, `openApi`, `limits`, `mounts`, `delegate`, `applyOnUpdate`), and the runtime
  validates it. `delegate` ([Multi-agent](https://run.camelai.com/docs/guides/multi-agent.md)) adds its
  builtin.
  `name` defaults to the key.
- `${NAME}` and `${NAME:-default}` in the manifest's strings read the
  environment, so credentials stay out of the file; an unset one is an error.
  `$${NAME}` is a literal `${NAME}`. Files named by `systemPromptFile` and
  `specFile` are read as they are, relative to the manifest.
- Each entry of `agents` is a keyed agent made from the definition, with the
  fields of `POST /v1/agents` (`name`, `subject`, `context`, `model`,
  `thinkingLevel`, `systemPromptAppend`, `ttlSeconds`, `mounts`…). An agent that
  exists is brought to them between its turns, keeping its history; who it acts
  for (`subject`, `context`) and its mounts are fixed when it is made, and
  changing them fails that agent (delete it to start over).
- A file can hold several manifests as YAML documents separated by `---`.

```sh
camelrun deploy                  # ./agent.yaml (or agent.yml, agent.json)
camelrun deploy agents/*.yaml    # several files
camelrun deploy --dry-run        # what would change, credentials hidden
camelrun deploy --apply          # also move live agents to the new revision
```

Deploying upserts each definition by its key: it is created the first time, gets
a new revision when the manifest changed it, and is `unchanged` otherwise, so
deploy on every push. Agents keep the revision they were made with until you
deploy with `--apply`, which reconfigures each live agent between its turns and
keeps its history.

## Commands

An agent is named by its key or its id (`client_…`), a definition by its key or
its id (`def_…`).

| Command | |
| --- | --- |
| `whoami` | the account the key belongs to, and its default model |
| `models [--available]` | the model catalog, or the models your account can use |
| `init [key] [--model m]` | write `agent.yaml` |
| `deploy [file…] [--apply] [--dry-run]` | deploy manifests |
| `agents list` / `agents get <agent>` | agents; one agent's configuration and tool sources |
| `agents create <key> [--definition d] [--model m] [--prompt text]` | an agent outside a manifest |
| `agents configure <agent> [--model m] [--prompt text] [--prompt-append text] [--thinking level]` | change one agent between its runs |
| `agents fork <agent> [--key k] [--name n] [--at message]` | a new agent with its configuration, history and files ([Forking](https://run.camelai.com/docs/concepts.md#forking)); `--at` ends the history at a message index or a request id |
| `agents delete <agent> --yes` | stop an agent and purge its history and files |
| `run <agent> <message…>` | send a message and print the reply |
| `runs get <agent> <requestId> [--wait s]` | a run's result |
| `run --stateless <message…> [--definition d] [--model m] [--prompt text] [--thinking level] [--request-id key]` | a [stateless run](https://run.camelai.com/docs/guides/stateless-runs.md): the answer, with nothing carried over and no agent kept |
| `runs get <runId> [--wait s]` | a stateless run's result |
| `history <agent> [--limit n]` | its latest messages, tool calls included |
| `abort <agent>` | stop it: its running turn, and the runs queued behind it |
| `inputs [agent]` / `answer <agent> <inputId> <value>` | questions and approvals waiting on someone, and answering them |
| `schedules list\|add\|delete <agent>` | wake-ups: `add --text t --in 3600 [--every 86400] [--history none]` |
| `definitions list\|get\|agents\|delete` | definitions, and the revision each agent has |
| `telemetry get\|set\|test\|clear` | export each run as an OpenTelemetry trace to your OTLP/HTTP endpoint ([below](https://run.camelai.com/docs/reference/cli.md#telemetry)) |

`run` waits for the run to end; `--wait 30` waits at most 30 seconds and
`--no-wait` not at all, printing the request id to follow with `runs get`.
`--from user-1` says who is sending, `--steer` gives the message to a run that
is going. An agent whose tools are attached by an application that is not
connected refuses the run (`APPLICATION_NOT_CONNECTED`) unless you pass
`--allow-disconnected`.

`--traceparent 00-<trace-id>-<span-id>-01` makes the run continue that trace
when the account exports telemetry.

`answer` takes `true` or `false` for an approval, the chosen label or your own
words for a question (`{"<question>": "<answer>"}` for several), the fields as
JSON for a form, and `decline`.

### Telemetry

```sh
camelrun telemetry set https://api.honeycomb.io/v1/traces --header x-honeycomb-team=@env:HONEYCOMB_KEY
op read op://ops/langsmith/key | camelrun telemetry set https://api.smith.langchain.com/otel/v1/traces \
  --header x-api-key=@stdin --header Langsmith-Project=agents
camelrun telemetry set --content   # change one option; the rest stay
camelrun telemetry test          # one test span, sent now: what the endpoint answered, and its trace id
camelrun telemetry get           # the endpoint, header names, and how the last export went
camelrun telemetry clear         # stop exporting
```

`set [<endpoint>]` changes what it is given (`PUT /v1/telemetry`): options left
out keep their current values (their defaults the first time, when the endpoint
is needed). `--header` (repeat it for several) is sent with every export, stored
encrypted, and never shown again: `get` prints header names only, and no command
prints a value. Give the value as `name=@env:VAR` (from the environment) or
`name=@stdin` (from standard input, one header), so the key stays out of your
shell history and the process list; `name=value` works too. A later `set`
without `--header` keeps the stored headers while the endpoint stays on the same
origin, and drops them when it moves. See [Observability](https://run.camelai.com/docs/guides/observability.md). `--protocol` is `http/protobuf` (default) or `http/json`,
`--sample-rate` the share of runs traced (0 to 1, default 1), and `--content`
also exports prompts, replies and tool arguments and results (default
`--no-content`). `test` exits 1 when the endpoint refused the span or could not
be reached.

### Output and exit codes

Output is text on a terminal and JSON otherwise (or with `--json`), so scripts
and agents get JSON without asking. Errors go to stderr, as `{"error", "status",
"code"}` in JSON mode.

| Exit | |
| --- | --- |
| 0 | done |
| 1 | an error, a failed run, or an agent in a deploy that failed |
| 2 | the run waits on a person: its `inputs` say what to `answer` |

## MCP tools

Both MCP servers have tools for everything above: `deploy`, `list_agents`,
`get_agent`, `create_agent`, `configure_agent`, `fork_agent`, `delete_agent`, `run_agent`,
`get_run`, `agent_history`, `abort_agent`, `list_inputs`, `answer_input`, the
schedule and definition tools, `list_models`, `whoami`, and `read_docs`, which
reads these docs.

`run_agent` and `get_run` wait at most `wait` seconds (default 50, so a call
stays inside clients' tool timeouts); a run still going comes back as `running`
with its `requestId`. A run that asks a person something comes back as
`input_required`: the coding agent should ask you and answer with what you
decided.

Every tool has a title and states MCP's `readOnlyHint`, `destructiveHint` and
`openWorldHint`. The tools that overwrite, delete, stop or irreversibly answer
something (`deploy`, `configure_agent`, `create_agent`, the deletes,
`abort_agent`, `answer_input`) are marked destructive, so clients that ask
before such calls ask you first. `create_agent` is because, for a key that
already has an agent, it brings that agent to the configuration given (keeping
its history). `fork_agent` only adds an agent, so it is not. `run_agent`, `answer_input` and `add_schedule` are open-world:
the runs they start can search and fetch the web and call the agent's tool
servers. A result longer than 100,000 characters is cut, saying so.

## Hosted MCP server

`https://run.camelai.com/mcp` serves the tools over Streamable HTTP. Add it
by URL and sign in when your client asks: the runtime's sign-in page (GitHub,
or an API token) asks you to allow the client, which then acts for your
account until you revoke it.

Claude Code:

```sh
claude mcp add --transport http camelrun https://run.camelai.com/mcp
# then /mcp in Claude Code to sign in; or skip signing in with a key from your environment:
claude mcp add --scope project --transport http camelrun https://run.camelai.com/mcp \
  --header 'Authorization: Bearer ${CAMELAI_API_KEY}'
```

The single quotes keep `${CAMELAI_API_KEY}` as written: `--scope project` saves
it in the project's `.mcp.json`, and Claude Code reads the variable from its
environment each time it starts. The file is safe to commit; a key is not (see
[Keys stay out of MCP configs](https://run.camelai.com/docs/reference/cli.md#keys-stay-out-of-mcp-configs)).

Claude (claude.ai and the desktop app): Settings, Connectors, Add custom
connector, with the URL above. Cursor and other clients configured with JSON:

```json
{ "mcpServers": { "camelrun": { "url": "https://run.camelai.com/mcp" } } }
```

How it differs from `camelrun mcp`:

- `deploy` takes the manifest's YAML (`manifest`), not a file. The hosted
  server reads no files and no environment variables of its own, so
  `systemPromptFile`, `specFile` and `${NAME}` are refused: write the values in,
  or deploy from your machine with `camelrun deploy`.
- It keeps no session: every request stands alone, on any node.

Signing in is OAuth 2.1, as MCP's authorization spec describes: a `401` from
`/mcp` names `/.well-known/oauth-protected-resource/mcp`, which names the
runtime as the authorization server (`/.well-known/oauth-authorization-server`);
clients register themselves (`/oauth/register`) and use the authorization code
flow with PKCE. Access tokens last an hour and work with your tenant's agents at
`/mcp` and the REST API: agents, their runs, inputs, schedules and mounts,
definitions, and reads of models, providers, usage and the balance. They get no
credential that would outlive the grant and send nothing elsewhere: an agent's
token (creating or forking an agent over OAuth answers without one), API tokens,
browser tokens, signed links, webhooks, the usage webhook, the trace export,
channels, provider keys and endpoints, volumes and the account export are all
`403` to them; use an API token or the console for those. Refresh tokens last 30
days and rotate on each use. A refresh token presented again within 10 seconds of its
rotation (a retry, or refreshes racing) gets the same new tokens; later, it revokes its grant.
The console's API tokens page lists connected apps under **Connected apps**,
where you revoke them (or `GET /v1/oauth/grants`, `DELETE
/v1/oauth/grants/{id}`). Any API token also works, as `Authorization: Bearer`.
Revoking an API token or a grant answers with `left`: the webhooks and trace
export it last pointed somewhere (`setBy` on each names who did), which keep
sending until you change or delete them; the console lists them when you
revoke. Grants made before they were limited may have set some.

Each registration makes a client of its own, even for the same name and
redirect URIs, so a confidential client's secret is known only to whoever
registered it. The consent page shows where it sends the authorization (a web
app's scheme and host, or a native app's whole redirect URI) and marks the
name the application gave itself as unverified: judge it by that destination.

Each agent is also an MCP server of its own, with one tool that messages it:
see [Agents as MCP servers](https://run.camelai.com/docs/guides/mcp-server.md).

## In the browser: WebMCP

The console also offers the tools to the agent built into your browser, through
[WebMCP](https://webmachinelearning.github.io/webmcp/): while you are signed in
to the console, a browser with WebMCP (Chrome with the WebMCP testing flag
turned on, for now) lists them, and they act as you, through the console's own
session. They are the hosted server's tools: `deploy` takes the manifest's YAML.
Every tool that changes something is marked consequential, so the browser can
ask you before it runs one. Signing out removes them.

## Local MCP server

`camelrun mcp` serves the tools over stdio, with the CLI's credentials (read on
each call). Its `deploy` also takes `file`, a path to a manifest (default
`./agent.yaml`), and reads the files and environment variables it names.

Claude Code:

```sh
claude mcp add camelrun -- npx -y @camelai/camelrun mcp
```

It uses `CAMELAI_API_KEY` from the environment Claude Code starts it in, or
else your `camelrun login`. To name the key in the project's `.mcp.json`, as
a variable rather than its value:

```json
{
  "mcpServers": {
    "camelrun": { "command": "npx", "args": ["-y", "@camelai/camelrun", "mcp"], "env": { "CAMELAI_API_KEY": "${CAMELAI_API_KEY}" } }
  }
}
```

Cursor (`.cursor/mcp.json`) reads the environment as `${env:NAME}`:

```json
{
  "mcpServers": {
    "camelrun": { "command": "npx", "args": ["-y", "@camelai/camelrun", "mcp"], "env": { "CAMELAI_API_KEY": "${env:CAMELAI_API_KEY}" } }
  }
}
```

Codex (`~/.codex/config.toml`) passes the variables `env_vars` names through:

```toml
[mcp_servers.camelrun]
command = "npx"
args = ["-y", "@camelai/camelrun", "mcp"]
env_vars = ["CAMELAI_API_KEY"]
```

### Keys stay out of MCP configs

MCP configs such as `.mcp.json` and `.cursor/mcp.json` are often committed.
Never write a key's value into one: name the variable, as above, and keep the
key in your shell's environment or an ignored file such as `.env.local`. A key
or a connected app can create and delete every agent in the account. Give a
coding agent a key of its own, or connect it with OAuth, so you can revoke it
alone.

---

<!-- https://run.camelai.com/docs/reference/events.md -->

# Events

An agent's event stream says what it is doing as it does it: text as the model
writes it, tool calls and their progress, questions it waits on, files it
presents. Use it for display. **A run's result is the truth; events are for
display**: a stream can drop events (a restart, a slow reader, a frame too
large), and every SDK settles a run from its outcome, never from its events.

- [Reading the stream](https://run.camelai.com/docs/reference/events.md#reading-the-stream): endpoints, framing, cursors, snapshots
- [Frames](https://run.camelai.com/docs/reference/events.md#frames): `event`, `response`, `snapshot`, `mcp`
- [Event types](https://run.camelai.com/docs/reference/events.md#event-types): every `event.type`
- [Run outcomes](https://run.camelai.com/docs/reference/events.md#run-outcomes): what a `response` frame carries
- [Webhook events](https://run.camelai.com/docs/reference/events.md#webhook-events)

## Reading the stream

| Endpoint | Who | Mode |
| --- | --- | --- |
| `GET /clients/:id/events` | the agent's own token (the SDKs) | the application's connection: it also carries the runtime's MCP calls to the application's tools (`mcp` frames) |
| `GET /clients/:id/events?watch=1` | the agent's own token | a read-only watcher: every event, no MCP calls, holds nothing |
| `GET /v1/agents/:id/events` | an API key, or a [browser token](https://run.camelai.com/docs/guides/browser.md) | always a read-only watcher |

Query parameters and headers:

| | |
| --- | --- |
| `Last-Event-ID: <cursor>` | resume after this event id. Absent or `0` takes everything still buffered. |
| `?snapshot=1` | where the stream cannot replay what you missed (a first connect, or a cursor behind the buffer), send a [`snapshot`](https://run.camelai.com/docs/reference/events.md#snapshot) of the running turn first instead of a 409. Watchers and polls (`?watch=1`, `?poll=1`, `/v1/agents/:id/events`) get one by default (`?snapshot=0` opts out); the application's connection only when it asks, as the SDKs do. |
| `?poll=1&wait=N` | answer once, as JSON, instead of streaming: `{cursor, events: [{id, data}]}`, where `data` is a frame. With `wait` (seconds, at most 25) and nothing buffered, it answers when the next event arrives or the wait ends. Poll again with `Last-Event-ID: <cursor>`. For clients that cannot hold a stream open. |
| `?request=<id>` | only that request's events, and its `response` frame: one run's progress, for a caller that sent it with `POST …/prompt` and wants nothing else. `ready`, `snapshot` and other frames that are not a request's still come. |
| `?subagents=1` | also send the agent's sub-agents' progress, from its `delegate` calls: [`subagent_start`, `subagent_event` and `subagent_end`](https://run.camelai.com/docs/reference/events.md#sub-agents). Without it, none of them. The SDKs: `subagents: true` |
| `?takeover=true` | (application connection only) replace the process serving the agent's tools now. See [One application at a time](https://run.camelai.com/docs/reference/events.md#one-application-at-a-time). |
| `X-Agent-Connection: <connection>` | (application connection only) reconnecting: the `connection` the last `ready` named, so the runtime knows it is the same application coming back. |

The response is `text/event-stream`. Each frame is `data:` JSON; most have an
`id:` line, the cursor. A comment line (`: heartbeat`) arrives about every
5 seconds, so a stream that delivers nothing for much longer than that is dead:
reconnect with the last cursor.

```text
event: ready
data: {"version":5,"agentId":"client_…","connection":"…"}

id: 1727520000000123
data: {"type":"event","requestId":"8c1…","event":{"type":"agent_start"}}
```

### `event: ready`

The first frame of every stream: `{version, agentId, connection?, watch?}`.
`connection` (the application's connection only) names this connection: the
application's MCP answers (`POST /clients/:id/mcp`) must carry it as
`X-Agent-Connection`, and a reconnect sends it back. `watch: true` on a watcher.

### `event: closed`

`{"reason": "replaced"}`: another process took over this agent's tools
(`?takeover=true`), and this stream ends. Do not take them back: to keep
following the agent, reconnect as a watcher (`?watch=1`), as the SDKs do (they
report `APPLICATION_REPLACED` to `onError`).

### `event: reconnect`

```text
event: reconnect
retry: 0
data: {"type": "reconnect", "reason": "drain", "retryMs": 0}
```

The last frame of a stream the runtime closes on purpose: its node is leaving
(`drain`: a deploy, a scale-in, a retiring task) or the agent is now served by
another node (`moved`). Reconnect at once, with `Last-Event-ID` set to the last
event id you took, and the stream goes on from there on the agent's next owner:
no backoff, nothing missed. The frame has no `id` (it is not an event and moves
no cursor), and `retry: 0` tells an `EventSource` to reconnect without waiting.
A stream that ends without it, or is cut off, is a failure: reconnect with your
usual backoff. The SDKs (TypeScript, Python, the browser watcher, chat and the
AI SDK adapter) do this. A long poll (`?poll=1`) is answered at once instead,
with what it has; poll again straight away.

### Cursors and gaps

Event ids rise, and an id is never reused, even after the agent moves to another
node. The runtime buffers each agent's recent events in memory (the
last 512, at most 2 MiB) for replay. A `Last-Event-ID` behind that buffer (after
a long disconnect, or after the agent moved to another node) cannot be replayed:
without a snapshot (the application's connection without `?snapshot=1`, or a
watcher with `?snapshot=0`) the stream answers **409 `REPLAY_GAP: recover from
session state`**; otherwise it starts with a `snapshot`. Recover what settled from
`GET …/state` (each request's outcome) and `GET …/history`. Nothing durable is
lost in a gap: only display events are.

### One application at a time

One process at a time serves an agent's tools (the application connection that
answered MCP's `initialize`). Another application connection is refused with
**409 `APPLICATION_CONNECTED`**, unless it asks `?takeover=true` (the one serving
gets `event: closed`) or names the connection it held
(`X-Agent-Connection`, reconnecting). Watchers and a connection that serves no
tools hold nothing. See [Concepts](https://run.camelai.com/docs/concepts.md) and [Errors](https://run.camelai.com/docs/reference/errors.md).

## Frames

### `event`

```json
{ "type": "event", "requestId": "…", "event": { "type": "message_update", … } }
```

One [event](https://run.camelai.com/docs/reference/events.md#event-types). `requestId` is the run it belongs to (the id you sent
the prompt with, or the SDK's). It is `""` for events of no run: `turn_resumed`
and `turn_recovered`, and a file presented or a tool's progress when no run had
begun.

### `response`

```json
{ "type": "response", "id": "<requestId>", "outcome": { "result": { … } } }
{ "type": "response", "id": "<requestId>", "outcome": { "error": "…", "uncertain": true } }
```

A request settled. `outcome.result` is what it produced ([run
outcomes](https://run.camelai.com/docs/reference/events.md#run-outcomes) for prompts); `outcome.error` means the runtime could not
carry it out, and `uncertain: true` that nobody can tell whether its work took
effect (a restart cut it short). The same outcome is at
`GET …/requests/:requestId` and in `GET …/state`, which is what to trust. There,
an ended request (`state: "completed"`) also carries `status` (`completed`,
`input_required` or `failed`), `error` (the runtime's, or the model's from
`result.error`) and `stopped` on top, so a failed run reads as failed without
looking inside `result`. `GET …/requests/:requestId?wait=<seconds>` (at most 25)
waits for a running request: it answers as soon as the request settles, or when
the wait ends with it still `running` (ask again), so a caller without the stream
gets the outcome in one call instead of polling.

A browser token sees an outcome only as `{id, outcome: {stopped?, error?}}`, its
`error` the model's too.

### `snapshot`

```json
{ "type": "snapshot", "cursor": 1727…, "requestId": "…" | null,
  "turn": { "start": 42, "count": 3, "messages": [ … ], "partial": { … } | null, "truncated": true } | null }
```

Sent (with `?snapshot=1`) in place of what the stream could not replay: the
running turn as a subscriber that saw every event since it began would have it.
`turn` is null when no turn runs. `messages` are the messages the turn finished,
in order; `partial` the assistant message streaming now. `start` is the index its
first message has in the agent's history (null if unknown), and `count` how many
it finished; the next message takes index `start + count`. `truncated`: the
messages were too large to send (over about 1 MB), so read them from history.
A snapshot restarts the stream at its `cursor`, even one below yours.

A browser token that neither reads `history` nor gets `message_end` sees
`turn: null`; one that does not get `message_update` sees no `partial`.

### `mcp`

```json
{ "type": "mcp", "message": { "jsonrpc": "2.0", "id": 7, "method": "tools/call", "params": { … } } }
```

The application connection only: the runtime's JSON-RPC messages to the
application's tools (`initialize`, `ping`, `tools/list`, `tools/call`,
`notifications/cancelled`). They have no `id:` line and are never replayed. The
application answers each with `POST /clients/:id/mcp` (and may send
`notifications/progress` there). The SDKs do all of this; see
[Tools](https://run.camelai.com/docs/guides/tools.md).

## Event types

The model loop's events, then the runtime's. New types may be added: ignore
those you do not know. Marked *internal* are the runtime's own, which a browser
token does not receive unless it lists them in `events`.

### Runs and turns

| Type | Fields | When |
| --- | --- | --- |
| `turn_opened` | `index` | a model run (prompt, continue, resume) begins: `index` is where its first message will sit in the agent's history |
| `agent_start` | | the model loop starts |
| `turn_start` | | a model round starts (one response and its tool calls) |
| `turn_end` | `message`, `toolResults` | a round ends |
| `agent_end` | `messages` | the model loop ends: the messages it added |
| `turn_resumed` | `reason`, `handoff?` | the node running this turn was lost; it continues here, with unresolved tool calls marked unknown. With `handoff` (`retire`, `drain`): the node left the cluster at a step boundary, and the turn continues here with nothing lost; a `turn_opened` follows, and no `agent_end` came before it (`requestId` is `""`) |
| `turn_recovered` | `reason` | the runtime restarted during a turn; unresolved tool calls were marked unknown (`requestId` is `""`) |

### Messages

| Type | Fields | When |
| --- | --- | --- |
| `message_start` | `message` | a message begins: the user's, an assistant response (empty so far), a tool result |
| `message_update` | `assistantMessageEvent` | the assistant message streaming grew. The delta **alone**, without the message it updates: fold it into the message from its `message_start` (see below) |
| `message_end` | `message` | a message finished: this is the message as history keeps it |
| `message_retracted` | `index` | a response taken back (before a retry, or a compaction on overflow): the message at `index` is gone, and the next takes its place |
| `event_omitted` | `reason`, `was?` | an event was too large for the stream (over the transport limit, 1.1 MB). `was` is its type; for a `message_end`, the message still takes its place: read it from history |

`assistantMessageEvent` is one of:

| `type` | Fields |
| --- | --- |
| `start` | |
| `text_start`, `thinking_start` | `contentIndex` |
| `text_delta`, `thinking_delta` | `contentIndex`, `delta` (the new text) |
| `text_end`, `thinking_end` | `contentIndex`, `content` (the block's whole text) |
| `toolcall_start` | `contentIndex`, `id?`, `name?` |
| `toolcall_delta` | `contentIndex`, `delta` (more of the arguments' JSON; parse it partially) |
| `toolcall_end` | `contentIndex`, `toolCall` (`{type: "toolCall", id, name, arguments}`) |
| `done`, `error` | `reason?` |

Only `text_delta` is reply text. `thinking_*` is the model's reasoning, and
`toolcall_delta` is JSON. The SDKs' `stream()` yields only reply text, and the
watcher (`@camelai/run/watch`) folds all of them for you.
Not every model streams a tool call's arguments: some send them in one
`toolcall_delta` when the call is complete. `GET /v1/models` says which
(`toolCallStreaming`: `true`, `false` or `"unknown"`); see
[Models and keys](https://run.camelai.com/docs/guides/models-and-keys.md#choosing-a-model).

Messages (`message` fields, and history) are one of:

| `role` | Fields |
| --- | --- |
| `user` | `content`: a string, or `[{type: "text", text} \| {type: "image", data, mimeType}]`; `timestamp`. History also records `from`, `requestId`, `metadata` |
| `assistant` | `content`: `[{type: "text", text} \| {type: "thinking", thinking} \| {type: "toolCall", id, name, arguments}]`; `provider`, `model`, `usage`, `stopReason` (`stop`, `length`, `toolUse`, `error`, `aborted`), `errorMessage?`, `timestamp` (when the request started), `durationMs?` (how long the response took; absent on older messages) |
| `toolResult` | `toolCallId`, `toolName`, `content` (text and image blocks), `details?`, `isError`, `timestamp`, `durationMs?` (how long the tool ran) |
| `system` | `content`: instructions the runtime added (a changed configuration, a compaction summary) |

### Tools

| Type | Fields | When |
| --- | --- | --- |
| `tool_execution_start` | `toolCallId`, `toolName`, `args` | a tool call starts |
| `tool_execution_update` | `toolCallId`, `toolName`, `args`, `partialResult` | progress. A tool's own progress (MCP `notifications/progress`, `context.progress()`) arrives as `partialResult: {content: [{type: "text", text}], details: {type: "progress", tool, innerCallId?, progress, total?, message?}}`, at most every 250 ms per call. A call from js_exec code reports on js_exec's `toolCallId`, with `innerCallId` |
| `tool_execution_end` | `toolCallId`, `toolName`, `result` (`{content, details}`), `isError` | a tool call finished. A call that waits on a person ends first with a placeholder (`result.details.inputRequired`); when its turn resumes (the input answered, declined or closed) it gets its own `tool_execution_start` and `tool_execution_end` again, in the resume's run, before its `toolResult` message |
| `codemode` *internal* | `toolCallId`, `event: {type: "output", text}` | js_exec's code printed `text` (`console.log`, `text()`), as it runs |
| `output` | `text` | an `execute` request's code printed `text` (not a model run: no `codemode` wrapper) |
| `file_presented` | `file` (`{type: "file", path, volume, version, size, contentType, caption?, …}`), `url?`, `expiresAt?` | the agent presented a file to the user (`present_file`): `url` is a signed download link |

### People

| Type | Fields | When |
| --- | --- | --- |
| `input_required` | `input` | the turn waits on a person: a question, an approval, a form or a URL step. `input`: `{id, agent, requestId, toolCallId, kind: "question" \| "approval" \| "form" \| "url", message, detail, responders: {audience?}, state, createdAt, expiresAt}`; `detail` by kind: question `{questions}`, approval `{tool, source, arguments, argumentsHash, reason?}` (`arguments` an object, as in the call; past 4,000 characters of JSON, `argumentsPreview` instead), form `{requestedSchema}`, url `{url, origin}`. See [Human input](https://run.camelai.com/docs/guides/human-input.md) |
| `input_resolved` | `id`, `state` (`answered`, `declined`, `cancelled`, `expired`, `superseded`), `by?` | an input settled |

### Sub-agents

See [Multi-agent](https://run.camelai.com/docs/guides/multi-agent.md). The `subagent_*` events reach only streams that ask for them (`?subagents=1`).

| Type | Fields | When |
| --- | --- | --- |
| `subagent_start` | `toolCallId`, `agentId`, `requestId`, `name`, `depth` | a `delegate` call started (or, on a resumed turn, found) its sub-agent `agentId`, running request `requestId` |
| `subagent_event` | `toolCallId`, `agentId`, `event` | one of the sub-agent's events, as its own stream has it, its streamed text (`message_update`) left out. A sub-agent's own `subagent_*` events arrive nested in its `subagent_event`s. Relayed while the sub-agent runs on its parent's node; its own stream has them all |
| `subagent_end` | `toolCallId`, `agentId`, `requestId`, `status` (`completed`, `input_required`, `failed`), `error?` | the sub-agent's run ended, or its parent stopped waiting for it |

### The runtime

| Type | Fields | When |
| --- | --- | --- |
| `auto_retry_start` | `attempt`, `maxAttempts`, `delayMs`, `errorMessage` | a transient provider failure (overload, rate limit, 5xx, dropped stream) is being retried; the failed response was retracted |
| `auto_retry_end` | `success`, `attempt`, `finalError?` | retrying ended |
| `model_stream_stalled` | `phase` (`first_token`, `idle`), `ms`, `provider`, `model` | the model's stream went quiet (nothing before its first token for `runLimits.firstTokenSeconds`, or nothing mid-response for `idleSeconds`), so the runtime ended the request; it is retried like any transient failure, and when retries run out the run fails with code `model_stream_stalled`. Provider keep-alives do not count as an answer |
| `steer_taken` | `steeredInto` | a prompt sent with `whileRunning: "steer"` (its id is the frame's `requestId`) was read by the running turn `steeredInto`: the model has it, and its request has completed |
| `run_cancelled` | `reason` (`stopped`) | a run queued behind the running one was cancelled by a stop (`POST /v1/agents/:id/abort`) before it began; its `response` follows, with code `cancelled` |
| `compaction_start` | `reason`, `background?` | the conversation is being summarized to fit the model's context. With `background: true` it is made between or alongside runs, outside any run's request (`requestId` is empty), and nothing waits for it |
| `compaction_end` | `reason`, `background?`, and `skipped`, or `tokensBefore`, `summarizedMessages`, `keptMessages`, or `error` | summarizing ended |
| `compaction_usage` *internal* | `provider`, `model`, `usage`, `timestamp`, `background?` | what the summary's model call used |
| `context_trimmed` | `retainedMessages`, `omittedMessages` | older messages were left out of a model request to fit it |
| `spend_limit_reached` *internal* | `message` | the agent (or tenant) reached its spend limit; the turn stops after this response's tool calls |
| `turn_limit_reached` *internal* | `message` | the run reached its limit of model responses or time (`runLimits`); the turn stops after this response's tool calls |

## Run outcomes

A prompt's `response.outcome.result` (and `GET …/requests/:id`'s `outcome`):

| Field | |
| --- | --- |
| `reply` | the final assistant message's text; absent when it said nothing |
| `output` | a prompt sent with `output`: the answer, which fits its schema. See [Structured output](https://run.camelai.com/docs/guides/structured-output.md) |
| `replyIndex` | that message's index in the agent's history |
| `messages` | how many messages the agent's history holds after the run |
| `error` | the model's error (a provider refusal after retries), or `null` |
| `code` | a stable name for `error`, where the runtime gives one: `model_key_missing` (no key for the agent's model), `model_key_invalid` (the provider refused the key), `output_missing` (a structured run ended without its output), `model_stream_stalled` (the model stopped answering mid-request, past every retry), `aborted` (the agent was stopped while the run went), `cancelled` (a stop cancelled the run before it began), `spend_limit`, `turn_limit` |
| `stopped` | why the run stopped early: `input_required` (it waits on `inputs`), `spend_limit` or `turn_limit` (its model responses or time, see [run limits](https://run.camelai.com/docs/guides/models-and-keys.md#run-limits)), with the reason in `error` |
| `inputs` | when `stopped` is `input_required`: the pending inputs (as `input_required` carries them) |
| `files` | files the run wrote (at most 100): `{path, version, size, contentType, …}` |
| `presented` | files the run presented to the user (at most 20) |
| `toolErrors` | tool calls that did not complete (the model was told): `{tool, toolCallId?, innerCallId?, code, outcomeUnknown?, message}`; `code` is `timeout`, `connection_lost`, `not_connected`, `source_unavailable` or `failed`. See [Errors](https://run.camelai.com/docs/reference/errors.md#tool-errors) |
| `toolCalls` | every tool call the run made, in order, the first 100: `{tool, toolCallId?, innerCallId?, ok, code?, agentId?}`; `agentId` is the sub-agent a `delegate` call ran. A call from `js_exec`'s code has js_exec's `toolCallId` and its own `innerCallId`; `js_exec` itself is not listed. `code`, when `ok` is false: a `toolErrors` code, `tool_error` (the tool answered with an error), `input_required` (it waits on a person; the run that resumes it lists it again) or `aborted`. Arguments and results are left out: read them from history (`GET /v1/agents/:id/history`) by `toolCallId` |
| `sourceErrors` | tool sources (MCP servers, OpenAPI specs) that could not be listed, so the model went without their tools: `{kind, source, message}` |
| `usage` | what its model responses used: `{responses, input, output, cacheRead, cacheWrite, costUsd}`, and `subagentCostUsd` when its sub-agents spent something (theirs, apart from `costUsd`), `imageCostUsd` when its `generate_image` calls did |

An `execute` request's result is `{output: string[], truncated}` (plus `files`,
`presented`, `toolErrors`, `toolCalls`, `sourceErrors` as above). A steered prompt's request
completes as soon as the running turn reads its message, with `{steeredInto}` as its result and on
its record: the turn's own request has the turn's outcome. Its 202 says how it was taken at once
(`steer`: `accepted` by the running turn, or `queued` as a turn of its own).

The SDKs turn this into a typed `Run`: `status` (`completed`, `input_required`,
`failed`), `text`, `output`, `inputs`, `error: {code, message, uncertain?}`, `files`,
`toolErrors`, `toolCalls`, `sourceErrors`. A browser token never sees a run's
result, `toolCalls` included: only whether and why it stopped.

## Webhook events

A tenant's webhook endpoints (`POST /v1/webhooks {url, events}`) receive
signed events (Standard Webhooks) in an envelope `{id, type, created, data}`;
dedupe by `id`. See [Webhooks](https://run.camelai.com/docs/guides/webhooks.md).

| Type | `data` |
| --- | --- |
| `run.started` | `agentId`, `requestId`, `method` (`prompt`, `continue`, `resume`, `execute`), `actor?`, `metadata?`, `resumes?` |
| `run.completed` | the above, `usage` (`{responses, input, output, cacheRead, cacheWrite, costUsd}` or null), `stopped?`, `inputIds?`, `replyIndex?`, `messageCount?`, `steeredInto?` |
| `run.failed` | the above, `usage`, `error`, `code?` (the outcome's code: `cancelled`, `aborted`, `model_stream_stalled`, `turn_limit`…), `uncertain?`, `steeredInto?` |
| `input.requested` | `agentId`, `requestId`, `inputId`, `toolCallId`, `kind`, `expiresAt` |
| `input.resolved` | `agentId`, `requestId`, `inputId`, `state` |
| `usage.recorded` | `agentId` (null for a [transcription](https://run.camelai.com/docs/guides/voice.md) or [images](https://run.camelai.com/docs/guides/images.md) made alone), `requestId`, `subject`, `actor`, `context`, `keyScope`, `provider`, `model`, `kind` (`response`, `compaction`, `transcription`, `image`), `input`, `output`, `cacheRead`, `cacheWrite`, `reasoning?`, `audioSeconds?` (a transcription's), `images?` (how many images were made), `cost: {usd, source}`, `at` |

---

<!-- https://run.camelai.com/docs/reference/limits.md -->

# Limits

Every limit a developer can hit, from the runtime's code. Sizes: KiB = 1024
bytes, MiB = 1024 KiB. Past a size limit the request is refused (400 or 413);
past a count or rate limit, 409 or 429 (with `Retry-After`). See
[Errors](https://run.camelai.com/docs/reference/errors.md) for what to do about each.

## Rate limits

Past one, the API answers 429 with `code: "RATE_LIMITED"`, `Retry-After` (in
seconds), and the limit it hit in `limit`:
`{"name": "runs", "scope": "tenant", "max": 600, "windowSeconds": 60}`. The SDKs
wait out `Retry-After` and retry. `GET /v1/billing` has the account's run limit
(`runsPerMinute: {limit, afterPurchase?}`), and the console's Billing page shows it.

| Limit (`limit.name`) | Scope | Value |
| --- | --- | --- |
| `api_requests`: requests to `/v1/*` | client address | 600 a minute |
| `auth_requests`: requests to `/console/auth/*` and `/oauth/*` (sign-in, sign-up callbacks, OAuth) | client address | 20 a minute |
| `signups`: new accounts | client address | 5 a UTC day; past it, sign-in says so instead of making the account |
| `password_failures`: failed email and password sign-ins (an unknown address counts as a wrong password) | email address, and client address | 10 per 15 minutes per address; 20 per 15 minutes per client address. Past either, sign-in answers 429, even with the right password, until the window turns over |
| `email_requests`: requests that mail a link (email sign-up, password reset, adding a password), where the runtime has account mail | client address | 10 an hour |
| `emails`: those mails to one address, whether or not it has an account | email address | 5 a UTC day |
| `agent_creates`: `POST /v1/agents` (an upsert that changes its agent too) and forks (`POST /v1/agents/:id/fork`) | account | 600 a minute, against abuse only: making agents costs almost nothing. Design around [busy agents](https://run.camelai.com/docs/reference/limits.md#usage-tiers) instead |
| `runs`: runs started (prompt, continue, execute), however sent: REST, SDKs, MCP, schedules, channels | account | 600 a minute; 240 on free credit (the 429 says buying credit raises it) |

- A client address is the caller's IP address; an IPv6 address counts with the
  rest of its `/64`. The runtime's own calls (hosted MCP tools calling the API)
  are not counted.
- `api_requests` refills continuously (a request comes back every tenth of a
  second at 600 a minute); the others count in fixed windows (the minute, 15
  minutes, the hour, or the UTC day), so `Retry-After` is the time to the next window.
- A retried request (the same request id or `Idempotency-Key`) that the runtime
  answers from its record is not a new run.
- An upsert whose configuration equals the agent's (the same `configHash`) is
  not an agent create: deploying 50 unchanged agents counts nothing. A fork
  counts, `atMessage: 0` included: it makes an agent (and a copy of its
  workspace). For a run without the history, send `history: "none"` instead.
- **Headers.** Answers that count against `agent_creates` (creates, upserts,
  forks) or `runs` (`POST /v1/agents/{id}/prompt`, and the SDKs' requests)
  carry `X-RateLimit-Limit` (the account's limit a minute),
  `X-RateLimit-Remaining` (what is left of it this minute) and
  `X-RateLimit-Reset` (seconds until the window resets), and so do their 429s,
  with `Retry-After` equal to `X-RateLimit-Reset`. Windows are fixed and align
  to the clock minute (UTC), not to your first request: 60 runs at 12:00:59
  and 60 more at 12:01:00 are both allowed. The headers say only the calling
  account's own counts. An account with no limit (an admin tenant) gets none,
  and neither does a retried request. A create with a first `prompt` carries
  the create's.
- Admin tenants (the operator's own, from its tenants file) are not rate
  limited: neither their account limits, nor `api_requests` for requests made
  with their tokens, browser tokens or console sessions. An admin tenant's
  `maxAgentCreatesPerMinute` and `maxRunsPerMinute` set limits for it anyway.
- Operators set every value (see [Configuration](https://run.camelai.com/docs/operations/configuration.md)),
  and a self-serve account's own with `PUT /v1/tenants/{id}/limits`
  `{agentCreatesPerMinute, runsPerMinute}` (see [Billing](https://run.camelai.com/docs/operations/billing.md)). A self-hosted runtime has no per-address limits unless it
  sets them, or trusts Cloudflare's `CF-Connecting-IP`.
- Channel senders and Get Help have limits of their own (below, and in
  [Errors](https://run.camelai.com/docs/reference/errors.md)).

## Agents

| Limit | Value |
| --- | --- |
| An agent's key (`Idempotency-Key` on `POST /v1/agents`, the SDKs' `upsert(key)`) | 1–80 characters of `A-Z a-z 0-9 _ -` |
| Lifetime (`ttlSeconds`) | 60 s to 31,622,400 s (366 days), or `null`: until deleted. Default: until deleted for an agent made with a key; 1 day for one made without |
| Create body (`POST /v1/agents`, with `initialMessages`) | 18 MiB |
| Imported history (`initialMessages`) | 16 MB of JSON (`HISTORY_TOO_LARGE`, 413) |
| `systemPrompt`, `systemPromptAppend` | 32,000 characters each |
| `modelHeaders` | at most 20 headers, 8 KB in all; never auth headers |
| `spendLimit.usd` | 0 to 1,000,000 |
| `subject` | a string; `context`: at most 4 KB |
| Mounts | at most 16 per agent |
| Agents busy at once per account | by [usage tier](https://run.camelai.com/docs/reference/limits.md#usage-tiers), across the whole runtime (not per node). An agent is busy while it has a run open, running or queued; a busy agent queues more runs without another slot. A run past the limit gets 429 `BUSY_AGENT_LIMIT` (below) |
| Tools in an agent's catalog | 4,096 tools, 16 MiB of schemas; at most 64 declared directly to the model (the rest are reached from js_exec) |

### Usage tiers

An account's tier comes from what it has paid for credit in total, net of refunds.
Starting credit and other grants do not count. A payment moves the account up as soon as it lands.

| Tier | Paid in total | Agents busy at once |
| --- | --- | --- |
| Free | nothing yet | 20 |
| Tier 1 | $5 | 50 |
| Tier 2 | $50 | 100 |
| Tier 3 | $250 | 250 |
| Tier 4 | $1,000 | 1,000 |

`GET /v1/billing` has `busyAgents`: the limit, how many are busy now, the tier, and the next one
(`next: {tier, paid, limit}`); the console's Billing page shows the same. An account whose limit
the operator set (the tenants file's `maxAgents`, or `maxBusyAgents` with
`PUT /v1/tenants/{id}/limits`) has `source: "tenant"` and no tier. Self-hosted runtimes set the tiers with
`AGENT_USAGE_TIERS` ([configuration](https://run.camelai.com/docs/operations/configuration.md)).

At the limit, a run (a prompt, `continue` or `execute`) gets 429 with `Retry-After`:

```json
{
  "error": "This account has 20 agents busy, the most its usage tier (Free) allows; retry when one finishes. $5 more of credit unlocks Tier 1: 50 busy agents (it applies once the account has paid $5 in total).",
  "code": "BUSY_AGENT_LIMIT",
  "busyAgents": { "busy": 20, "limit": 20, "source": "tier", "tier": "Free", "paid": 0, "next": { "tier": "Tier 1", "paid": 5000000, "limit": 25 } }
}
```

Amounts are micro-USD. The SDKs retry it after `Retry-After`, like any 429. Creating agents,
reading them and sending them input do not count; only runs do.

## Runs and requests

| Limit | Value |
| --- | --- |
| Request id (a prompt's `requestId`, the SDKs' `idempotencyKey`) | 1–80 characters of `A-Z a-z 0-9 _ -` |
| Settled requests kept per agent for idempotent retries | the most recent 256 |
| Open requests per agent (running and queued) | 32; more is 429 `Too many requests queued for this agent` |
| Prompt body (`POST /v1/agents/:id/prompt`) | 6 MiB, with inline files |
| Request body over an agent's own token (`/clients/:id/requests`, `/mcp`) | 1.1 MB (1,100,000 bytes) |
| `text` | must not be blank, unless the message attaches audio ([Voice and audio](https://run.camelai.com/docs/guides/voice.md)) |
| `from` | `id` 1–200 characters; `name`, `username` at most 200 each |
| `metadata` | at most 16 keys of 1–64 characters, string values of at most 512 characters |
| `configure` body | 1 MiB |
| Provider retries within a turn | 3 attempts, backing off from 2 s (overload, rate limits, 5xx, dropped streams); context overflow is not retried |
| Model responses in one run | 1,000, compaction summaries included; `runLimits.maxResponses` lowers it for an agent or a definition, and the operator sets the maximum (`AGENT_MAX_RUN_RESPONSES`, or per tenant `maxRunResponses`; admin tenants have none unless their entry sets one). At it, the turn stops before its next model request: `stopped: "turn_limit"` |
| A run's time | 2 hours from when it began, checked before each model request; `runLimits.maxSeconds` lowers it, the operator sets the maximum (`AGENT_MAX_RUN_SECONDS`, or per tenant `maxRunSeconds`; none for admin tenants unless set). `stopped: "turn_limit"` too; send another message to continue. A turn still inside one model request or tool call 60 s past its limit is aborted there, and its agent stopped at 120 s |
| A quiet model stream | a model request that sends nothing before its first token (text, thinking or a tool call) for 120 s (300 s for a reasoning model at `thinkingLevel` high and up), or nothing for 45 s once it streams, is ended as stalled and retried like other transient failures; keep-alives do not count. `runLimits.firstTokenSeconds` and `runLimits.idleSeconds` set an agent's or definition's own (1 to 3,600); the operator sets the runtime's (`AGENT_MODEL_FIRST_TOKEN_SECONDS`, `AGENT_MODEL_IDLE_SECONDS`). Past every retry the run fails with code `model_stream_stalled` |
| Wait | none beyond a run's time limit; a turn waiting on people (`input_required`) is not running, and may wait for days. The SDKs have no default timeout |
| `Idempotency-Key` header (any other POST) | 1–255 characters; its answer is kept for 24 hours |
| Stateless run (`POST /v1/runs`) body | 7 MiB, with inline files (4 MiB of files in all) |
| A stateless run's `wait` | at most 60 seconds on create, 25 on `GET /v1/runs/{id}`; it then answers with the run still running |
| A stateless run's retention | its result, events and messages are kept for a day after it ends (`retentionSeconds`: 60 to 604800; the operator's default is `AGENT_RUN_RETENTION_SECONDS`), then deleted. Its `Idempotency-Key` names it for as long. A run whose end was never recorded (its node died at that moment) is deleted 7 days after its retention would have begun |
| Stateless runs and limits | each counts against runs per minute and busy agents, as an agent's run does; not against agent creates or the agents a tenant has |

## Files

| Limit | Value |
| --- | --- |
| Files attached to one message | 20 |
| Inline (base64) file bytes in one message | 4 MiB in all, decoded; upload larger ones first (`PUT …/uploads/:requestId/:name`) and attach them by path |
| A file attached by URL (`{url}`) | 64 MiB, fetched within 60 s, at most 3 redirects, public addresses only |
| One file (upload, volume write) | 256 MiB |
| An upload's whole request | 15 minutes (other requests: 30 s without progress in the SDKs) |
| Image the model sees natively | 5 MiB and 8,000 pixels a side (larger ones are described in text); sent at most 1,568 pixels a side, scaled down in the request |
| PDF the model sees natively | 16 MiB and 100 pages |
| Files in one model request | 24 MiB and 100 images; older files past that are described in text |
| Parsing an untrusted file for its text | 32 MiB in, 10 s, 1,000,000 characters out |
| Files a run lists in its outcome | 100 written (`files`), 20 presented (`presented`) |
| Signed links (`POST …/links`) | `expiresIn` 1 to 86,400 s, default 900 |
| A volume | 100,000 files, 100 snapshots and 10,000 pinned ones; the change feed keeps the last 1,000 changes; a listing page is at most 1,000 files |
| Channel attachments | 10 files a message, 25 MiB each, 100 MiB in all |
| Storage per tenant | 1 GB (10^9 bytes) on free credit, 100 GB once it has bought credit; an operator can set another per tenant. Counted as the storage charge counts it: file contents (each distinct content once), agents' history logs and volumes' file trees. A write that would pass it is refused with 507 `STORAGE_LIMIT`, its body carrying `limit` and `used` in bytes: delete files or volumes to make room. Uploads, file writes and tool outputs all count |
| Storing on spent credit | a prepaid tenant at a zero balance cannot store more: uploads, file writes and tool outputs get 402 `INSUFFICIENT_CREDIT`. Reading and deleting still work |


## Audio

See [Voice and audio](https://run.camelai.com/docs/guides/voice.md).

| Limit | Value |
| --- | --- |
| One audio file transcribed | 25 MB and 30 minutes, its length read from its container before it is sent (413 `AUDIO_TOO_LARGE`, `AUDIO_TOO_LONG`) |
| Audio transcribed for one message | 5 files, 30 minutes in all |
| Formats | Ogg (Opus, Vorbis), WebM, MP3, M4A/MP4, WAV, FLAC; others, and audio whose container gives no length, are 415 `UNSUPPORTED_AUDIO` |
| `POST /v1/transcriptions` body | 25 MB of audio (multipart), or its base64 in JSON; each counts as a run against runs per minute |
| A provider's answer | 5 minutes |

## Images

See [Images](https://run.camelai.com/docs/guides/images.md).

| Limit | Value |
| --- | --- |
| Prompt | 32,000 characters |
| Images to edit | 4 per request, PNG, JPEG or WebP, 25 MB each and 50 MB in all, at most 8,000 pixels a side (413 `IMAGE_TOO_LARGE`; other types 415 `UNSUPPORTED_IMAGE`) |
| Images made | 4 per request (`n`) |
| Sizes and qualities | `1024x1024`, `1536x1024`, `1024x1536`; `low`, `medium`, `high` |
| `POST /v1/images` | each request counts as a run against runs per minute |
| A provider's answer | 3 minutes |

## Tools

| Limit | Value |
| --- | --- |
| A tool result the model reads | 32,000 characters; a longer one is saved whole (up to 700 KB) to `/workspace/tool-results/<toolCallId>.txt` |
| Attached tool call deadline (tools in your process) | 15 s without an answer by default; a tool's own `timeoutMs` from 1 s to 20 minutes |
| Remote MCP server call deadline | the source's `timeoutMs` (1 s to 20 minutes), default 60 s |
| OpenAPI operation deadline | the source's `timeoutMs` (1 s to 20 minutes), default 30 s |
| Progress | each progress notification restarts a call's deadline, up to 20 minutes in all. Progress events are published at most every 250 ms per call |
| One MCP result from the SDKs (a tool's return value) | 1 MiB of JSON |
| A remote MCP server's response | 8 MiB |
| An OpenAPI spec | 8 MiB; at most 1,024 operations allowed (`allowTools`) |
| Tool sources per definition | 64 MCP servers, 64 OpenAPI specs; `allowTools`/`denyTools` at most 512 names (MCP) |
| A file in a tool's arguments (base64, or inline as `data:`) | 4 MiB |
| A file's URL in a tool's arguments | 5 minutes, bound to the call and the file's version |
| A directory in a tool's arguments | 1,000 files, 256 MiB |
| A binary tool response saved to the workspace | 64 MiB; 64 MiB per call and 256 MiB per run saved in all |
| An MCP text resource shown inline | 64 KiB (longer ones are saved as files) |

### js_exec (code the model writes) and `execute`

| Limit | Value |
| --- | --- |
| Wall time | 30 s by default, at most 60 s (`timeoutMs`; a longer one is cut to it). Admin tenants may ask for 120 s; an operator can set a tenant's maximum up to 120 s (`codeMaxTimeoutMs`) |
| CPU time | 2 s of keeping its thread busy, TypeScript stripping included (time waiting on tools does not count). Enforced from outside the guest: an execution past it is stopped whatever it is doing, with `Codemode CPU limit exceeded`. An operator can set a tenant's up to 30 s (`codeCpuMs`) |
| Executions at once | 4 per tenant on each node (2 on free credit; `codeConcurrency`), all such tenants together within what the node's memory affords (6 on a 2 GB node). Executions past it wait their turn, tenants in rotation, within their own `timeoutMs`. Admin tenants are not limited unless their entry sets it |
| Memory | a 128 MiB V8 heap (reaching it ends the execution) and 128 MiB of ArrayBuffers (past it, a `RangeError`) |
| Output | 32,000 characters by default, at most 128,000 (`maxOutputCharacters`); 1,024 chunks |
| Tool calls | 256 per script, at most 32 in flight |
| Tool traffic | arguments at most 128 KiB of JSON a call, results at most 1 MiB, 8 MiB in all |
| One `fs.readFile` / `fs.writeFile` | 700 KiB |

## People

| Limit | Value |
| --- | --- |
| How long an input waits | 7 days by default; a definition's `humanInput.expiresInSeconds` from 60 s to 30 days, never past the agent's expiry |
| Inputs one tool call may ask at once | 8 |
| An input's message, an approval's shown arguments | 4,000 characters |
| Answers in one batch (`POST …/inputs`) | 1–100; one answer's body 256 KiB |
| Approvers (`humanInput.approvers`) | 100 |
| `ask_user` | 1–4 questions, each with 2–4 options and a header of at most 12 characters |

## Sub-agents

See [Multi-agent](https://run.camelai.com/docs/guides/multi-agent.md).

| Limit | Value |
| --- | --- |
| Delegation depth (`delegate.maxDepth`) | 2 by default (a parent, its children and theirs); 1–5 |
| `delegate` calls in flight per run (`delegate.maxParallel`) | 4 by default, 1–16; more wait their turn |
| A sub-agent's spend | what its parent's run and agent spend limits have left when it starts, as its run's spend limit; what it spent counts against both |
| A sub-agent's lifetime | a day (86,400 s), as a scratch agent's; one named by key (`{ agent }`) is yours and keeps its own |
| A `delegate` task | 100,000 characters; inline `instructions` 32,000 |
| Agents in one allowlist (`delegate.agents`) | 32; a name 1–64 letters, digits, `_` and `-`; a description at most 1,000 characters |

Sub-agents are agents: each counts against busy agents, the run rate and your
spend limits like any other.

## Streams and browsers

| Limit | Value |
| --- | --- |
| One SSE frame | 1.1 MB; a larger event is sent as `event_omitted` |
| Events buffered per agent for replay | the last 512, at most 2 MiB; a cursor behind them gets a snapshot (or `REPLAY_GAP`) |
| A snapshot's messages | about 1 MB; more is `truncated: true` (read history) |
| Long poll `wait` | at most 25 s |
| Read-only subscribers (watchers and waiting polls) | 32 per agent, 1,024 per tenant on a node (or the tenant's `maxWatchers`), 4,096 per node; past it, 429 |
| Browser token lifetime | 5 to 3,600 s, default 900; its stream ends when it expires |
| Browser token `events` list | 64 types |
| History page (`?limit=`) | 1 to 500 messages, default 50 |

## Schedules, channels and webhooks

| Limit | Value |
| --- | --- |
| Schedules per agent | 100 |
| Repeating schedules | `everySeconds` at least 60 |
| Schedule delivery retries | 3, after 1, 5 and 15 minutes (none for a 402 or another refusal a retry cannot change, nor past the next occurrence); then that occurrence is skipped and recorded (`failures`, `lastError`) |
| Schedule body | 64 KiB |
| Channel senders | `perSenderPerMinute` 1–600 (default 10), `turnsPerDay` 1–1,000,000 (default 1,000); `allow` at most 1,000 senders |
| Channel daily turns | count messages and, since they also post, turns started through the API or a schedule; past the limit those do not post |
| Camel Discord servers per account | 10, or 1 on free credit (an operator can change either) |
| A Camel Discord server | `perSenderPerMinute` 1–100 (default 5), `turnsPerDay` 1–10,000 (default 100; at most 500 on free credit); no `schedule` builtin |
| Webhook endpoints per tenant | 16 |
| A webhook delivery | 10 s to answer; retried until delivered, for up to 3 days |
| A rotated webhook secret | keeps signing beside the new one for 24 hours |

## Trace export

| Limit | Value |
| --- | --- |
| Endpoints per tenant | 1 (`PUT /v1/telemetry`), OTLP/HTTP only (protobuf or JSON) |
| Headers | 16, each value at most 4,096 characters; endpoint at most 2,048 |
| Spans waiting to be sent | 5,000 per tenant and 20,000 in all, per node; more are dropped |
| An export request | at most 512 spans; 10 s to answer; 5 attempts, retrying 429, 502, 503, 504 and connection failures |
| A content attribute (with `include.content`) | 16,384 characters, then cut |

## Spending

| Limit | Value |
| --- | --- |
| An agent's spend limit | from when it is set: new prompts are refused, and a running turn stops after the response that crossed it (`stopped: "spend_limit"`) |
| Run limits | 1,000 model responses and 2 hours a run (see [Runs and requests](https://run.camelai.com/docs/reference/limits.md#runs-and-requests)): `stopped: "turn_limit"` |
| A tenant's monthly cap (`maxMonthlyCost`) | 402 for new runs once reached |
| Prepaid credit | 402 at a zero balance, for runs and for storing files; free credit allows $1 of usage per hour (429 past it) |

---

<!-- https://run.camelai.com/docs/reference/errors.md -->

# Errors

Three kinds of failure, and where each shows:

1. **The API refused a request**: an HTTP status and a JSON body
   `{"error": "<message>"}` ([below](https://run.camelai.com/docs/reference/errors.md#http-errors)). The SDKs throw `AgentError`
   with `status`.
2. **A run failed**: the request was accepted, and the run ended badly. Its
   outcome says why ([Run failures](https://run.camelai.com/docs/reference/errors.md#run-failures)); the SDKs' `run()` throws
   `RunError` with the run, unless `throwOnError: false`.
3. **A tool call did not complete** within a run that otherwise went on: the
   model was told, and the run's outcome lists it in `toolErrors`
   ([Tool errors](https://run.camelai.com/docs/reference/errors.md#tool-errors)). Nothing throws; check them where a tool's
   side effect matters.

## HTTP errors

Error bodies are `{"error": "<message, for people>", "code": "<for code>"}`
(`type: "error"` too on some routes). The message may change; the code does not,
so switch on `code` (the SDKs' `AgentError.code`). Codes may be added: treat an
unknown one by its status. A conflict about an input also carries the input as it
now is (`"input"`), and a rate limit's 429 the limit it hit (`"limit"`). Every 429 and 503 has `Retry-After` (and a per-account rate limit's 429 its `X-RateLimit-*` headers: see [Rate limits](https://run.camelai.com/docs/reference/limits.md#rate-limits)); the SDKs honour it and
retry.

| Status | `code` | Meaning |
| --- | --- | --- |
| 400 | `INVALID_REQUEST` | The request is malformed or invalid; the message says how |
| 400 | `INVALID_HISTORY` | An imported history (`initialMessages`) has a message it cannot take; the message names which, and what it lacks |
| 400 | `TRANSCRIPTION_UNAVAILABLE` | Audio was to be transcribed and the account has no OpenAI key to do it with (nor the platform's); the message says how to add one |
| 400 | `IMAGE_UNAVAILABLE` | An image was to be made and the account has no OpenAI key to do it with (nor the platform's); the message says how to add one |
| 400 | `IMAGE_REFUSED` | OpenAI's safety system refused the request (`stage: "input"`) or the image it made (`stage: "output"`); `categories` names why. Nothing was charged |
| 400 | `FORK_POINT_INVALID` | A fork's `atMessage` is not an index in the agent's history, nor a request id one of its messages carries |
| 401 | `UNAUTHORIZED` | No valid token; the message says where to create one (https://run.camelai.com/console/tokens) |
| 402 | `SPEND_LIMIT` | A spend limit is reached: the agent's, or the account's monthly cap; or a message's audio, or an image, would cost more than the run's or agent's spend limit has left |
| 402 | `INSUFFICIENT_CREDIT` | The account's prepaid credit is spent: no runs start and no files are stored |
| 403 | `FORBIDDEN` | The token may not do this |
| 404 | `NOT_FOUND` | No such agent, request, input or other resource for this account, or no such path at all (the message points at `/llms.txt`) |
| 409 | `IDEMPOTENCY_CONFLICT` | The Idempotency-Key or request id was used for another request |
| 409 | `IDEMPOTENCY_IN_PROGRESS` | The first request with this Idempotency-Key is still running; retry |
| 409 | `APPLICATION_CONNECTED` | Another connection serves this agent's tools; connect with `?takeover=true` to replace it |
| 409 | `APPLICATION_NOT_CONNECTED` | The agent's tools need its application and none is connected; connect it, or send `allowDisconnected: true` |
| 409 | `FORK_POINT_RUNNING` | A fork's `atMessage` is in a turn that has not ended (running, or waiting on a person); fork at an earlier message, or once it ends |
| 409 | `REPLAY_GAP` | The Last-Event-ID is behind the buffer; read `/state` (or ask for a snapshot) and continue from its cursor |
| 409 | `CONFLICT` | Another conflict, named in the message |
| 410 | `GONE` | The agent was deleted or has expired |
| 413 | `TOO_LARGE` | The request body is too large |
| 413 | `HISTORY_TOO_LARGE` | An imported history is over 16 MB of JSON |
| 413 | `AUDIO_TOO_LARGE`, `AUDIO_TOO_LONG` | Audio to transcribe is over 25 MB or 30 minutes (a message's, 5 files or 30 minutes in all) |
| 413 | `IMAGE_TOO_LARGE` | An image to edit is over 25 MB or 8,000 pixels a side, or a request's images are over 50 MB in all |
| 415 | `UNSUPPORTED_AUDIO` | Audio to transcribe is in a format transcription does not take, or its container gives no length |
| 415 | `UNSUPPORTED_IMAGE` | An image to edit is not PNG, JPEG or WebP |
| 429 | `BUSY_AGENT_LIMIT` | The account has as many agents busy as its [usage tier](https://run.camelai.com/docs/reference/limits.md#usage-tiers) allows; `busyAgents` in the body has the limit and the next tier. Retry after `Retry-After`, or when one of its runs ends |
| 429 | `RATE_LIMITED` | Too many: a rate limit (the body's `limit` names it: `{name, scope, max, windowSeconds}`; see [Rate limits](https://run.camelai.com/docs/reference/limits.md#rate-limits)), or too many agents, requests or subscribers at once; retry after `Retry-After` |
| 502 | `TRANSCRIPTION_FAILED` | The transcription provider failed or refused the key; nothing was charged |
| 502 | `IMAGE_FAILED` | The image provider failed or refused the key; nothing was charged |
| 503 | `UNAVAILABLE` | Retry after `Retry-After`: capacity, an agent moving, a node draining |
| 503 | `DATABASE_RETRY` | The database refused the request for now (a conflict with another request, or a statement timeout); retry after `Retry-After` |
| 507 | `STORAGE_LIMIT` | The account's storage limit would be passed; the body has `limit` and `used`, in bytes |
| 500 | `INTERNAL` | A bug; retry, and report it with the request id |

In more detail:

| Status | Meaning | What to do |
| --- | --- | --- |
| 400 | The request is malformed: a field fails validation (the message names it and what it takes), an unknown option, a blank `text`, an invalid request id or agent key, an answer that does not fit its input, an answer that names no one for an input meant for particular people (`This input is for …: answer with from or actor naming who answers`) | Fix the request; retrying it unchanged fails again |
| 401 | No token, an unknown or wrong token, or an expired browser token (`This browser token has expired; mint a new one`); an agent's token used on another agent | Send `Authorization: Bearer <token>` with a valid key. A browser: mint a new browser token (the watcher's `getToken`) |
| 402 | Payment required: the tenant's prepaid credit is used up (runs and file writes are refused), or its monthly model spend cap is reached. Queued runs fail with the same message | Add credit in the console, or raise the cap |
| 403 | Authenticated but not allowed: a browser token outside its agent or its scopes, an agent token changing what only the tenant may (`keyScope`, `spendLimit`, `modelHeaders`), a person not allowed to answer an input, a write to a read-only mount, an expired signed link | Use a token that may do it (usually the tenant's API key, server-side) |
| 404 | No such agent, request, input, volume, file, definition, schedule, webhook or route; or the feature is not enabled on this runtime. Another tenant's agent is a 404 too | Check the id. A deleted agent is 404 on `/v1/agents/:id` |
| 405 | A signed link used with the other method | Use the method it was made for |
| 409 | A conflict: see [409s](https://run.camelai.com/docs/reference/errors.md#409s) | Depends on the case |
| 410 | The agent was deleted or expired (`Session expired or revoked`, on `/clients/:id/*`) | Stop using that id and token. With a key, `upsert` it again: the key makes a fresh agent |
| 412 | A versioned write lost (a volume file changed since the `version` you gave) | Read it again and retry with the new version |
| 413 | Too large: the request body, inline files over 4 MiB, a file over 256 MiB, an upload over a link's `maxBytes` | See [Limits](https://run.camelai.com/docs/reference/limits.md); upload large files first and attach them by path |
| 415 | An upload through a signed link with another content type | Send the type the link names |
| 422 | A channel's credentials were rejected by the provider (Slack, Telegram, Discord) | Fix the bot token |
| 429 | Too many: a [rate limit](https://run.camelai.com/docs/reference/limits.md#rate-limits) (requests from one address, agents created or runs started a minute, sign-in requests), the tenant's agents awake at once, the agent's 32 open requests, event-stream subscribers, or free credit's hourly allowance | Retry after `Retry-After` (the SDKs do, up to 8 times). A rate limit's body names it in `limit`; to go faster for good, ask for a higher limit |
| 500 | A bug | Retry; report it with the request id |
| 503 | The runtime cannot serve it right now: a node is draining or starting, lost ownership of an agent, has no room for its work, or the database is failing over; also a feature this runtime is not configured for | Retry after `Retry-After` (the SDKs retry); nothing happened |
| 507 | A volume is full (100,000 files), or the account's storage limit would be passed (`STORAGE_LIMIT`, with `limit` and `used` in bytes) | Delete files, or use another volume; for the account's limit, delete files or volumes, or buy credit (free credit stores 1 GB) |

### 409s

| Message | Meaning | What to do |
| --- | --- | --- |
| `REPLAY_GAP: recover from session state` | The stream cannot replay from your `Last-Event-ID` | Reconnect with `?snapshot=1` (the SDKs do), and recover settled outcomes from `/state` |
| `APPLICATION_CONNECTED: another connection serves this agent's tools…` | Another process serves this agent's tools. The SDKs raise it as `code: "APPLICATION_CONNECTED"` | Close the other one; or connect with `takeover: true` to replace it; or connect without serving tools (`attach: false`) to run the agent from here |
| `APPLICATION_NOT_CONNECTED: …` | A run (prompt, continue, execute, steer, follow-up) of an agent with application tools while no process serves them (after about 3 s' grace). The SDKs raise it as `code: "APPLICATION_NOT_CONNECTED"` | Start or reconnect the process that serves the tools; serve them over HTTP instead; or pass `allowDisconnected: true` to run without them |
| `Not the agent's current connection; reconnect` | An MCP answer on a connection that was replaced | Reconnect (the SDKs do) |
| `Request ID reused with different arguments` | The same request id (`idempotencyKey`) sent with another prompt | Use a new id for a new message; the same id only to retry the same one |
| `This Idempotency-Key was sent with another request…` | The same `Idempotency-Key` header on a different method, path or body | A key is for one request |
| `A request with this Idempotency-Key is still running; retry` / `…just finished; retry` | A retry raced the first request | Retry shortly: it then gets the first one's answer |
| `An existing agent's subject, context, definition, mounts cannot change…` | An upsert of an existing key with a different value for a field set only at creation | Delete the agent (`DELETE /v1/agents/:id`) or use another key |
| `FORK_POINT_RUNNING: Message N is in a turn that has not ended yet…` | A fork's `atMessage` falls in the running turn, or in one waiting on a person (its tool calls have no results yet) | Fork without `atMessage` (it ends before that turn), at an earlier message, or once the turn ends |
| `This key names another agent, not a fork of this one…` | A fork's key is already another agent's (one made with it, or a fork of another agent) | Use another key; the same key returns the same fork only for the same source |
| `Idempotency key belongs to another tenant` | Two tenants' keys cannot collide in practice; this guards it | Use another key |
| `This input is already answered` (or declined, cancelled, expired, superseded) | Someone answered first. The body's `input` says how. Answering again with the same answer is 200 | Show the input as it is |
| `The definition is at revision N, not M` / `The definition changed meanwhile; retry` | A definition update with a stale `revision` | Read it again and retry |
| `A volume keeps at most 100 snapshots…`, `A tenant has at most 16 webhook endpoints`, `Channel … uses this definition…`, `Volume … already exists` | A count limit or a dependency | Remove one first |

## Run failures

A run ends in one of three ways: it answered, it waits on people
(`stopped: "input_required"`), or it failed. It failed when:

| Code (SDK `RunError.code`) | Outcome | Meaning |
| --- | --- | --- |
| `model_key_missing` | `result.code` (with `result.error`) | No key is set for the agent's model. The error names the model and the remedy: set a key with `PUT /v1/providers/<provider>/key` (or the key scope's entry), or move the agent to a model you can use (`GET /v1/models?available=true`) |
| `model_key_invalid` | `result.code` (with `result.error`) | The provider refused the key (HTTP 401). The error says the same remedy, then the provider's own words |
| `model_error` | `result.error` is set | The model provider refused or failed (after 3 retries for transient failures): a bad request, content refused, context overflow that compaction could not fix |
| `output_missing` | `result.code` (with `result.error`) | A run sent with `output` ended without the model calling `final_output`: it answered in prose twice, the second time after a reminder. `text` has what it said. Send the prompt again, make the instructions say what the answer is for, or use a stronger model |
| `output_invalid` | (the SDKs only) | The output fit the JSON Schema the runtime checked, but not the zod or pydantic schema the SDK parsed it with (a refinement or validator the JSON Schema cannot say) |
| `spend_limit` | `result.stopped: "spend_limit"` | A spend limit stopped the turn after the response that crossed it; its tool calls ran. `result.limit` says which: `run` (the run's own `spendLimit`), `agent`, `tenant` (the monthly cap) or `credit` (prepaid credit spent). Raise that limit and send the next message |
| `turn_limit` | `result.stopped: "turn_limit"` | The run made as many model responses (1,000 by default) or ran as long (2 hours) as its [run limits](https://run.camelai.com/docs/guides/models-and-keys.md#run-limits) allow; the turn stopped after that response's tool calls. Send another message to continue, or raise the agent's `runLimits` |
| `runtime_error` | `outcome.error` (no `result`) | The runtime could not carry the run out: e.g. the agent was deleted, code execution failed, a queued run refused for credit |
| (any, with `uncertain`) | `outcome.uncertain: true` | A restart cut the run short where it could not resume (a code execution, or a turn resumed twice already): its tool calls may or may not have taken effect. Check before retrying |

### Model failures

When a model call failed the run (`model_error`, `model_stream_stalled`, `model_key_invalid`…), its error says how,
so you need not parse `message`:

```json
{ "code": "model_error", "message": "402 This request requires more credits…",
  "errorClass": "billing", "providerStatus": 402, "retryable": false, "model": "openrouter/anthropic/claude-sonnet-5" }
```

| Field | Meaning |
| --- | --- |
| `errorClass` | `billing` (the provider's 402, a quota or budget used up, even one sent as a 429), `rate_limit` (429), `server` (5xx, overloaded, the provider unreachable), `refusal` (the model declined, or the provider's safety filter stopped it), `auth` (401, 403, no key), `timeout` (the provider's, or the model stream went quiet), `other`. Classes may be added: treat an unknown one as `other` |
| `providerStatus` | The provider's HTTP status, when its error gives one |
| `retryable` | Whether the runtime retries this kind of failure itself (3 times, with backoff, on the same model). On a failed run, `true` means it was transient and the retries ran out: trying again later, or with another model, may work. `false`: the same request will fail the same way. A model on your own endpoint ([custom models](https://run.camelai.com/docs/guides/custom-models.md)) is not retried by the runtime, except for a stalled stream, so its failures are `false` |
| `model` | The model that failed, as `provider/model-id` (an id of `GET /v1/models`) |

The same fields are on the `run.failed` webhook, and as `failure` on the stream's events for a failed response
(`message_end` with `stopReason: "error"`) and its retries (`auto_retry_start`, and `auto_retry_end` when they run
out). A request record has them as `outcome.result.modelError`. They are the classes the runtime counts in its
metrics and the same rule it retries by, so they agree with what it did.

A run's `servedModel` (and `run.completed`'s, `run.failed`'s) is the model that made its last response, as
`provider/model-id`; retries ask the same model.

A request record (`GET …/requests/:requestId`, `GET …/state`) puts an ended run's
`status` (`completed`, `input_required` or `failed`, as the SDKs' runs say it),
`error`, whichever kind, and `stopped` on top. Its `state` says only whether it
ended (`running`, `completed`): a failed run is `state: "completed"`,
`status: "failed"`.

A failed model response that is retried is retracted from history (`message_retracted`); the last one stays, with its `errorMessage`. A run
whose node was lost mid-turn resumes on another (`turn_resumed`), with any tool
call whose answer was lost marked "outcome unknown" for the model; tool calls
are never sent twice. A deploy or drain loses nothing: the node finishes the
step in flight and hands the turn off at that boundary (`turn_resumed` with
`handoff`; the run's `handoffs` records it).

## Tool errors

A run's outcome lists each tool call that did not complete as
`toolErrors: [{tool, toolCallId?, innerCallId?, code, outcomeUnknown?, message}]`
(the SDKs: `run.toolErrors`). The model got the same message as the call's
result and carried on.

| `code` | Meaning | `outcomeUnknown` |
| --- | --- | --- |
| `timeout` | No answer (or progress) within the tool's deadline | yes: it may have taken effect |
| `connection_lost` | The connection the call went out on closed before its answer: the process serving the tools crashed, or was stopped without `close()`, or its call outlived `close()`'s drain. See [deploying a tool process](https://run.camelai.com/docs/guides/tools.md#deploying-a-tool-process) | yes |
| `not_connected` | No process served the agent's tools (no application attached), so the call did not run. Typical for REST, schedules and channels driving an agent whose tools live in a process that is not running: serve them over HTTP instead ([Tools](https://run.camelai.com/docs/guides/tools.md)) | no |
| `source_unavailable` | Its MCP server could not be reached, listed or authenticated with | no |
| `failed` | Anything else that kept it from running or answering | no |

A tool that ran and reported its own failure (threw, or answered `isError`) is
not a tool error: that is the tool's answer, which the model reads.

`sourceErrors: [{kind, source, message}]` lists tool sources (MCP servers,
OpenAPI specs) that could not be listed when the run began, so the model went
without their tools.

Every attempt at one tool call carries the same idempotency key
(`_meta["agent-runtime/idempotencyKey"]`, an OpenAPI operation's
`Idempotency-Key` header, the SDKs' `context.idempotencyKey`): key side effects
by it, and a call that runs twice acts once.

## SDK errors

| | TypeScript | Python |
| --- | --- | --- |
| Any failure | `AgentError`: `message`, `status` (HTTP status, or 0 for a run's or the connection's), `code?`, `requestId?`, `uncertain?`, `retryAfterMs?` | `AgentError`: `status`, `code`, `request_id`, `uncertain`, `retry_after` (seconds) |
| A failed run | `RunError extends AgentError`: `run` (the `Run`, `status: "failed"`, `error: {code, message, uncertain?, errorClass?, providerStatus?, retryable?, model?}`) | `RunError`: `run` (the same in `run.error`) |
| Another process took the agent's tools | `code: "APPLICATION_REPLACED"`, through `onError`; the client goes on without serving them | the same, through `on_error` |
| A tool server's token check | `RuntimeTokenError` (`serveTools`, `verifyRuntimeToken`): the call gets 401 | `RuntimeTokenError` |

A run's failure is not an HTTP response, so `RunError.status` is always 0, in
both SDKs: it does not mean the network failed. Branch on `code`
(`model_key_missing`, `spend_limit`, …: see [Run failures](https://run.camelai.com/docs/reference/errors.md#run-failures)). An
`AgentError` with `status` 0 and no `code` is the connection's failure.

Stopping a wait (`signal`, `timeoutMs`; Python `timeout`) throws the signal's
reason (an `AbortError` or `TimeoutError`), or an `AgentError` saying the request may still be running:
the run goes on in the runtime. Wait for it again with the same
`idempotencyKey`, or `waitForRequest(id)`.