camelRun by camelAIcamelRun by camelAI · AI sub-agents

Multi-agent orchestration

camelRun is camelAI's hosted runtime for AI agents. One agent fans out tasks to sub-agents and folds their answers back in.camelRun, camelAI's hosted runtime for AI agents, lets one agent fan out tasks to sub-agents. They work in parallel, and every answer folds back into its reply.

Get an API key Read the quickstartQuickstart

Agentresearch-lead1 of 3 answered

lead.run("Compare the three largest EV makers' 2025 margins.")

→ researcher · Largest by deliveriesrunning
← researcher · Second largest3 sources
→ researcher · Third largestrunning

The delegate tool

Fan out tasks to AI sub-agents

List the agents your agent may hand tasks to, and its model gets a delegate tool. Each call starts a sub-agent with its own tools and history, and its answer comes back as the call's result. Several calls in one response run in parallel.

research.mts

1import { Agents } from "@camelai/run";
2
3const agents = new Agents(); // reads CAMELAI_API_KEY
4
5await agents.runtime.upsertDefinition("researcher", {
6  name: "Researcher", description: "Finds sources and summarizes them",
17  systemPrompt: "You research a question and answer with sources.", builtins: ["web_search", "web_fetch"],
8});
9
10const lead = await agents.upsert("research-lead", {
11  instructions: "You plan research and write the report. Delegate each question to the researcher.",
12  delegate: { agents: ["researcher"] },
213});
14const run = await lead.run("Compare the three largest EV makers' 2025 margins.");
15console.log(run.text);
16
17await agents.close();

$ export CAMELAI_API_KEY=art_...$ npm install @camelai/run$ npx tsx research.mts

TooldelegateThe model sees

Hand a task to a sub-agent and wait for its answer: its final text, or with `output`, an object in that schema. The sub-agent works on its own (its own tools and history), sees only the task you give it, and its answer comes back as this call's result. Call delegate several times in one response to run tasks in parallel.

Agents you can delegate to:

- researcher: Finds sources and summarizes them

agent: "researcher"Which agent to delegate to
task: stringThe task, with everything the sub-agent needs to know: it sees none of this conversation
output: objectA JSON Schema for an object, if you want the answer in that shape (type: "object")

Result{ agentId, requestId, status, text, output?, error? }

The agents built-in

Background AI agents that report back

Add the agents built-in, and the lead starts sub-agents and moves on. Each answer arrives as a message of its own, and wakes the lead if it's asleep.

Lead, in the background

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

Historyresearch-leadRunningAsleep

user
Compare the three largest EV makers' 2025 margins.
research-lead
- → spawn_agent({ agent: "researcher", task: "…" })
- → spawn_agent({ agent: "researcher", task: "…" })
- → spawn_agent({ agent: "researcher", task: "…" })
- ← { agentId: "client_4be1…", name: "researcher-1" }
- ← { agentId: "client_91c0…", name: "researcher-2" }
- ← { agentId: "client_d27a…", name: "researcher-3" }
research-lead
Three researchers are on it. I'll write the report as their answers come in.
Asleep
<agent_notification name="researcher-2" status="completed">Found 3 sources: the 2025 annual report, the Q4 2025 results release and the earnings call. Both margins are in the annual report's income statement. </agent_notification></agent_notification>
research-lead
researcher-2 is in. Waiting on two more.
Asleep

Inside a sub-agent

Watch every AI sub-agent work, step by step

Stream the lead with subagents: true, and every sub-agent's steps arrive as they happen. A chat made with watch: { subagents: true } shows each one as a transcript under its call, and OpenTelemetry traces nest them the same way.

Your app

Compare the three largest EV makers' 2025 margins.

Used delegate

Arguments

{
  "agent": "researcher",
  "task": "Find the 2025 gross and operating margins of the second-largest EV maker by deliveries. Cite your sources."
}

Sub-agent researcher · 6 messages

Find the 2025 gross and operating margins of the second-largest EV maker by deliveries. Cite your sources.
→ web_search
{"query":"second-largest EV maker by deliveries 2025","provider":"exa","results":[{"title":"2025 Annual Report","url":"https://investors.example.com/2025-annual-report","content":"Consolidated statements of operations…"}]}
→ web_fetch
{"url":"https://investors.example.com/2025-annual-report","status":200,"contentType":"text/html","title":"2025 Annual Report","text":"2025 Annual Report. Consolidated statements of operations…"}
Found 3 sources: the 2025 annual report, the Q4 2025 results release and the earnings call. Both margins are in the annual report's income statement.

Result

{
  "agentId": "client_3f9d0b6a1c7e4f28a5d9c0b7e6f1a2d4c8b5e903",
  "requestId": "delegate_8c1e5a7f2b9d04c6e3a1f7b5d9c2e08a",
  "status": "completed",
  "text": "Found 3 sources: the 2025 annual report, the Q4 2025 results release and the earnings call. Both margins are in the annual report's income statement."
}

Used delegate

Here's how the three compare, with a source under each figure.

Your server

lead.stream

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

Output

→ researcher (client_6a2f9e14c07b3d85e1f4a09c7b2d6e3f8a51c0d9)
→ researcher (client_3f9d0b6a1c7e4f28a5d9c0b7e6f1a2d4c8b5e903)
→ researcher (client_b81e4c7a29f0d53e6c1a8b4f07d29e5c3a6f1b84)
← client_3f9d0b6a1c7e4f28a5d9c0b7e6f1a2d4c8b5e903: completed
← client_6a2f9e14c07b3d85e1f4a09c7b2d6e3f8a51c0d9: completed
← client_b81e4c7a29f0d53e6c1a8b4f07d29e5c3a6f1b84: completed

Settings

Set depth, parallel runs and spend for AI sub-agents

Set them once on the lead, and they cover every sub-agent it starts.

How deep
maxDepth: 2
A lead, its sub-agents and theirs. You choose how many levels.
How many at once
maxParallel: 8
You choose how many run together. The rest start as others finish.
How much
spendLimit: { usd: n }
Each sub-agent spends from the lead's budget, so one number covers the whole run.

Every sub-agent is an agent

parentAgentId

Each one is linked to its lead. Find it under the lead in the console and read its own history.

Console

Agents

Name	Type	Status
client_5e0a8d3f71c94b2e6a0f8d17c3b59e42a6d1f083	general	Running
↳researcher	subagent	Running
↳researcher	subagent	Asleep
↳researcher	subagent	Running

Questions about multi-agent orchestration

run.textHere's how the three compare, with a source under each figure.

What are the best practices for multi-agent orchestration?

Keep one lead in charge and give each sub-agent a task that stands on its own, since it sees only its task. Describe each worker clearly and fan out independent tasks in parallel. In camelRun, depth, parallel calls and spend are settings on the lead.

What are some examples of multi-agent orchestration frameworks?

LangGraph, the OpenAI Agents SDK and CrewAI are popular frameworks for writing the orchestration in your own code. camelRun has the pattern built in: give a lead agent the delegate setting, and its sub-agents' answers come back as tool results.

What are AI subagents?

Subagents (sub-agents) are agents another agent starts to handle part of its task. In camelRun each one is a real agent with its own tools and history, linked to its lead, and its answer comes back to the lead.

How do I run parallel AI agents?

Give a lead agent the delegate setting. Several delegate calls in one response run at once, four at a time by default and more when you raise maxParallel. It's fan-out and fan-in: one call per item, and the lead combines the answers.

Can a sub-agent remember earlier tasks?

Yes. Point delegate at one of your own keyed agents, like an analyst that has covered EV makers before, and it keeps its own history from task to task. A sub-agent made from a definition starts fresh each time.

What happens to sub-agents if a server goes down?

They carry on. The lead's run resumes on another server, finds the same sub-agent and waits for its answer, so the task never runs twice.

How much do sub-agents cost?

A sub-agent is billed like any agent: $0.01 per agent-hour while it's in a run, $0.10 per GB-month of storage, and $0 for tokens on your own provider keys. What it spends counts against the lead's spend limit.

Is camelRun the CAMEL-AI multi-agent framework?

No. camelRun is camelAI's hosted runtime for AI agents, and CAMEL-AI is a separate open-source project with a similar name. camelRun is open source too, and you can host it yourself as one container and Postgres.

Keep reading

Docs

camelRun

Blog

Agent Harness vs Framework vs Runtime vs Sandbox, ExplainedWhere orchestration frameworks end and a runtime begins.

Run your first AI sub-agents

Get an API key and run the program above: three researchers answer, and the lead writes the report.

Get an API key Read the quickstart

Set up with your coding agent

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

Paste into Claude Code, Codex, Cursor or any coding agent. It asks what your agent should do, then builds it.