Skip to main content

Agents

Synced from bicycle-studio-api

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 with agent_run and agent_result, or referenced from an agent function as agent: {ref: "bicycle:cause@<n>"}.

Build one​

  1. 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.
  2. function_create, then function_put_files with function.json (below).
  3. function_try(name, input): one real run as you; it spends budget, so say the cost first. Read it with invocation_get and invocation_events. Check the answer with the person on an input they know.
  4. function_publish: the first publish of an agent always needs a person; give them the link.

The spec (agent.spec)​

FieldWhat
system (<= 8000 chars)your instructions, after the platform's rules; put connection know-how here
task, input_schema, output_schemathe 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)
modela 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​

StepsTool callsCostTime
Default3080$2.00600 s
Ceiling100300$101800 s
Preset Standard2050$1.25300 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: queued with queue_position. Keep watching; do not call again. A direct call over capacity answers 429 agent_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