camelRun TypeScript and Python SDKs

View as Markdown · Docs index for coding agents

The two SDKs have the same features, named in each language's style; their version numbers are their own and do not line up.

npm install @camelai/run   # Node 22+ (on Node 26: 26.5.1+), Bun, Deno, Cloudflare Workers

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

Agents

const agents = new Agents({ apiKey, url }); // or `await using agents = new 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, which has the same names without await. 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 CAMELAI_API_KEY, and 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 camelRun. 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.
• connection (Python connection=) says when agent handles hold their event stream. "lazy", the default, holds it only while agent.stream() reads a run, so a server holding many agents keeps no idle connections, and agent.run() asks for its outcome instead. A handle that serves tools, or has onEvent, onInput or onConnection, holds the stream from upsert or get until close(). "eager" holds it from the start for every handle. Each upsert, get, fork and agent call can say otherwise.
• agents.runtime is the lower-level AgentRuntime: definitions, volumes, mounts, listAgents(), browserToken(agentId), inbox() and toolSources(agentId).

agents.upsert(key, config)

The agent for key (1 to 80 of A-Z a-z 0-9 _ -), made if there's none and brought to config if it differs. Returns a connected Agent.

agent.configHash (Python agent.config_hash), from upsert and get, is a hash of the agent's configuration. An upsert that changes nothing returns the hash the agent has and doesn't count as an agent create. Every agent's hash is in listAgents(), so a deploy script can tell what changed. Compare it; never parse it.

agents.get(keyOrId, config)

The existing agent with this key (or id), as it is. upsert sets an agent to the config it's given; get changes nothing, so use it where a process only runs or reads agents that another process configures.

const agent = await agents.get("support-triage");      // or its id

agent = await agents.get("support-triage")

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, the callbacks, attach and takeover as upsert does. Over REST, GET /v1/agents/{keyOrId}/credentials returns {id, token, expiresAt}, to your account's own credentials only (an API key, an OAuth grant, a console session). agents.agent(session, { tools }) connects to an agent whose credentials ({id, token}) you hold, without changing it. Available from @camelai/run 0.14.0 and camelai-run 0.10.0.

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.

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

fork = await agent.fork(key="support-b", at_message=5)

atMessage ends the copied history at a history index (that message and the tool results that answer it) or a request id (that run's whole turn); by default it ends with the last turn that finished, never mid-turn. Forking again with the same key returns the same fork, and agents.get(key) finds it. Without a key the fork lives a day (ttlSeconds changes that). subject, context, instructionsAppend (instructions_append=) and modelHeaders (model_headers=) are the fork's own instead of the source's. fork.forkedFrom (forked_from) is {agentId, atMessage}, and agents.fork(id, options) forks an agent by id. Available from @camelai/run 0.14.0 and camelai-run 0.10.0.

agents.run(config) and agents.runs

A stateless run: a configuration and an input in, a Run out, nothing carried over and no agent made.

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

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

config takes an agent's configuration (model, instructions, definition, builtins, delegate, mcpServers, thinkingLevel, maxOutputTokens, temperature, subject, context, workspaceId, keyScope, runLimits, modelHeaders, mounts, fileTools, codeMode, name) and the run's own: input, files, output, user, metadata, idempotencyKey, spendLimit, retentionSeconds, signal, throwOnError, traceparent. Python takes snake_case keywords, input first. It resolves with a Run (no inputs).

Agent

Run options for run and stream:

Run and stream parts

A Run is { 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). A delegate call has its sub-agent's agentId, and usage.subagentCostUsd is what its sub-agents spent. error is { code, message, uncertain? }. output is the answer of a run sent with output, typed by its schema (Python: an instance of the pydantic model). status is completed, input_required or failed. Each of run.inputs has answer(value, { from }) and decline({ from }) (Python: answer(value, from_=) and decline(from_=)), which resolve with the resumed run.

run.toolCalls names a call's tool tool and its id toolCallId. Stream parts carry the same values as name and id, and, from @camelai/run 0.14.0 and camelai-run 0.10.0, also as tool and toolCallId (Python tool_call_id). name and id stay. Every part but done has raw, the event it came from. Breaking out of the loop stops the reading, not the run.

Tools

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

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's both when the agent's served tools number 10 or fewer, and codemode past that.

A tool of a definition's source may be sent the agent's files as URLs. verifyFileUrl(url, { runtime, tenant?, agent?, issuer? }) (Python await verify_file_url(url, runtime=, ...)) checks one came from camelRun for the account and agent you expect and hasn't expired, and returns what it grants (tenant, agent, tool, volume, path, agentPath, kind, exp and more). It throws RuntimeTokenError otherwise.

With several processes (web workers, task queues, serverless), serve tools over HTTP: see Several processes, workers and deploys.

The synchronous Python client

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

from camelai_run.sync import Agents

with Agents() as agents:  # reads 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 has upsert, get, fork, agent(session), run and runs (stateless), and close. Agent has run, stream, steer, history, history_page, pending_inputs, configure, abort, fork, schedule, files and delete. Answer a run's inputs with run.inputs[0].answer(...).
• AgentRuntime has every call of the async one that is a single 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; agent.stream() reads the agent's events while it reads the run. timeout= (seconds) stops the wait, not the run.
• It never serves tools, since that needs the agent's connection held. Serve them over HTTP with camelai_run.sync.serve_tools (a WSGI app) and a definition; see Served tools. It also has verify_runtime_token, verify_file_url and a TestRuntime.
• Not here: on_event, on_input, volumes and create_agent. One Agents is for one thread at a time; give each thread (or Celery worker) its own.

Errors

• AgentError has status (HTTP, or 0), code (a stable name where camelRun gives one: APPLICATION_CONNECTED, APPLICATION_REPLACED, spend_limit and others), requestId, uncertain and retryAfterMs (Python request_id, and retry_after in seconds). With END_USER_CREDIT (a 402) or end_user_credit (a run), it also has reason (balance, daily_limit or bucket_limit, listed in CREDIT_REASONS), bucket and endUser (Python end_user). See End-user credits.
• endUserCredit(errorOrRun) (Python end_user_credit) returns an end user's credit refusal from a thrown error, a run or its error in one shape, else undefined.
• RunError is an AgentError for 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. run.servedModel (Python run.served_model) is the model that made its last response.

The SDKs retry 429 and 503 (honoring Retry-After) and transient failures of idempotent requests. See Errors.

The lower-level API

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

await agents.runtime.telemetry.set({ endpoint: "https://api.smith.langchain.com/otel/v1/traces", headers: { "x-api-key": process.env.LANGSMITH_API_KEY! } });
const { ok, traceId } = await agents.runtime.telemetry.test();

await agents.runtime.telemetry.set("https://api.smith.langchain.com/otel/v1/traces", headers={"x-api-key": os.environ["LANGSMITH_API_KEY"]})
result = await agents.runtime.telemetry.test()

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

Listing agents

listAgents() (list_agents()) returns every agent, as GET /v1/agents does without a limit. For an account with many, call the REST API with filters and pages:

• limit (1 to 200) returns a page by id. While more match, the response's X-Next-Cursor header holds the cursor to pass as cursor for the next.
• workspaceId: a workspace's agents, or unassigned.
• status: running (loaded now), failed (a run failed in the last 24 hours), or expiring (has an expiresAt).
• subAgents: only or exclude.
• q: part of the name, key or id, ignoring case.

Each agent also has workspaceId, lastActiveAt (when its latest run ended) and lastError ({ at, class } of its latest failed run: a class such as model_error, spend_limit or aborted, never the error's text; the run's outcome has the message).

Audio, voice and images

const { text } = await agents.transcriptions.create({ file: await readFile("voice.ogg"), language: "en" });
const { images: [image], costUsd } = await agents.images.generate("A watercolor camel at dawn", { size: "1536x1024" });

result = await agents.transcriptions.create(Path("voice.ogg"), language="en")
result = await agents.images.generate("A watercolor camel at dawn", size="1536x1024")

Examples

Both examples read CAMELAI_API_KEY: