Dynamic workflows and sub-agents on camelRun

View as Markdown · Docs index for coding agents

A workflow is a JavaScript script an agent runs to coordinate many sub-agents at once. One tool call (run_workflow) carries the whole plan, the agents' answers stay in the script's variables, and only the script's return value comes back to the model. It is for work one conversation cannot coordinate turn by turn: a sweep over every route handler, a migration across hundreds of files, a question checked against several independent sources.

It is built on the same sub-agents as delegate: a workflow's agent() calls make real child agents, with the same limits, links, budget and events. For background sub-agents whose answers arrive as messages, see Multi-agent.

Turn it on

Give the agent the workflow builtin and say whom its scripts may coordinate. The SDKs add the builtin when you pass the settings; in REST send both.

const lead = await agents.upsert("migration-lead", {
  instructions: "You plan migrations. Write a workflow when the work is a sweep.",
  workflow: { agents: ["worker"], maxAgents: 40, maxParallel: 6 },
});

A definition takes the same pair, for every agent made from it. The settings go with the builtin in both directions: settings without it are refused, and so is the builtin without settings.

What the model writes

The tool takes a script and optional args. The script is plain JavaScript with top-level await:

export const meta = { name: "audit-routes", description: "Audit every route for missing auth" }

phase("discover")
const found = await agent("List every .ts file under src/routes/.", {
  agent: "worker",
  label: "list",
  schema: { type: "object", required: ["files"], properties: { files: { type: "array", items: { type: "string" } } } },
})

phase("audit")
const audits = await pipeline(found.files, file =>
  agent(`Audit ${file} for missing authentication checks. Reply with the issue, or "fine".`, { agent: "worker", label: file }),
)

phase("report")
const report = await agent(`Group these findings by severity:\n${audits.join("\n")}`, { agent: "reviewer", label: "report" })
return { files: found.files.length, report }

Each agent sees only the prompt it is given, never the parent's conversation, so put in it everything the child needs. Only the script's return value comes back: return the fields the model needs, not everything every agent said. A schema shapes one child's answer exactly as structured output does, validated before the call returns.

The tool's result

{
  "status": "completed",
  "agents": [
    { "index": 0, "label": "src/routes/a.ts", "agent": "worker", "status": "completed" },
    { "index": 1, "label": "src/routes/b.ts", "agent": "worker", "status": "failed", "error": "…" }
  ],
  "value": { "files": 12, "report": "…" }
}

A script that throws, runs past its deadline, or asks past maxAgents answers status: "failed" (or "canceled") with an error, and the call is an error result the model sees. A child that fails is null to the script instead, so the script decides what a partial failure means.

Who the children are

Every agent() call makes a child agent, as a delegate call does:

• linked to its parent: parentAgentId and parentRunId on the agent and in its run's metadata, one step down the delegation chain
• acting for whom the parent acts (subject, context), with its key scope, and billed to the same account
• bounded by the parent's budget: parallel children share what the run has left, and what they spend counts against the parent's limit (run.usage.subagentCostUsd)
• taken from the account's busy slots like any agent, with its own definition's runLimits
• a day long, as a scratch agent is

A script cannot coordinate an agent already working on its chain, and a workflow's children may not go past maxDepth — counted together with delegate's.

Interruption and the script's clock

If a workflow is interrupted, it resumes using the children it already started instead of starting the same work again. Keep its inputs stable so it asks the same questions when it resumes.

Date.now() is fixed at the time the request started and Math.random() is seeded from the run. new Date() and performance.now() are not frozen: keep them out of prompts, or pass the time in args.

Script environment

The script has no Node globals, filesystem, network access or module imports. Put work that needs tools in an agent's task. A script is stopped at its deadline or when its run is aborted. Workflows may queue when the runtime is at capacity.

Watch it

Ask for a run's sub-agents' events and a workflow's own arrive with them: ?subagents=1 in the API, subagents: true in the SDKs.

The children's own streams and histories always have everything; these are the parent's view. See Events.

Limits

See Limits for the rest.

Running a workflow without the model

The agent writes the script and calls run_workflow. Running a fixed script directly without a model turn is not available yet. To initiate a workflow from your application, send the agent a prompt with the task or the script to run.

Notes

• Named targets ({ agent: "key" }) are real agents with their own queue: two calls to one in the same script run one after the other. Definition targets make a new child per call and are the parallel choice.
• An explicit user abort stops the workflow and its children. An interruption that will resume preserves the children for the next attempt.
• maxAgents bounds one run_workflow call. A definition that also enables workflow can fan out again at the next level; the chain's maxDepth, spend limits and the account's busy-agent cap are what bound the total today.

For large fan-outs, the tool result includes up to 128 KB of child metadata in agents; agentsOmitted reports how many additional records were omitted. Child events and history remain available, and the script still receives every child answer.