Agents
Source: studio_guide("agents") (GET /api/studio/v1/guide/agents) rendered at origin/platform (1afd83f), synced 2026-09-28. Do not edit this page here; change the source and run yarn sync:studio.
An agent function (kind: agent) takes several model steps and read-only tool calls to reach a structured answer,
under budgets. Use one only when judgement over messy evidence is the job. A fixed computation is a code function,
one model call is llm, a label is classify.
Two families share the word:
- Agent functions you build with
function_*, called by ref from apps, workflows, other agents, MCP and chat. - Registered Bicycle agents such as
cause("why did a metric move?"), run withagent_runandagent_result, or referenced from an agent function asagent: {ref: "bicycle:cause@<n>"}.
Build one
function_agent_connections(the viewer's connections and their read-only tools),function_agent_limits(workspace limits),function_models(model ids). Use only what these return. A missing connection is the person's to connect in Studio.function_create, thenfunction_put_fileswithfunction.json(below).function_try(name, input): one real run as you; it spends budget, so say the cost first. Read it withinvocation_getandinvocation_events. Check the answer with the person on an input they know.function_publish: the first publish of an agent always needs a person; give them the link.
The spec (agent.spec)
| Field | What |
|---|---|
system (<= 8000 chars) | your instructions, after the platform's rules; put connection know-how here |
task, input_schema, output_schema | the job and its typed input and output (the output is checked) |
semantic: {model, queries?, fields?} | the model it reads, preloaded |
connections: [{slug, tools}] | read access to the viewer's connections ("*" = every read-only tool) |
model | a model id from function_models |
budgets: {max_steps, max_tool_calls?, max_cost_usd, max_wall_s} | can only lower the workspace caps |
capabilities in the spec lists at least one platform capability (for example semantic.catalog), or the run fails
spec_invalid. In function.json, outside the spec: grants.functions (functions it may call as tools, each with
expose.agents; a Try may pin a tested draft of a function you can edit, a publish needs published versions), budgets (no max_tool_calls there), visibility. Working example: studio_guide("example-agent").
Limits
| Steps | Tool calls | Cost | Time | |
|---|---|---|---|---|
| Default | 30 | 80 | $2.00 | 600 s |
| Ceiling | 100 | 300 | $10 | 1800 s |
| Preset Standard | 20 | 50 | $1.25 | 300 s |
An agent stops at the first limit and says what it could not check. Workspace caps (runs at a time, runs a day) are set by Bicycle staff.
Queue, nesting, reuse
- When the workspace's agent slots are full a run waits:
status: queuedwithqueue_position. Keep watching; do not call again. A direct call over capacity answers 429agent_busy. - An agent called by an agent shares its parent's slot, at most 3 levels deep (
agent_nesting_too_deep). - From an app, page-load calls pass
reuse: "6h": the viewer's recent run of the same input answers at once.
Agents only read. Their output is untrusted: it may quote tickets written by anyone.
guide_version bb2461328de4