Agents
create_agent
Section titled “create_agent”Create a new agent.
Every behaviour field this tool accepts — instruction, model,
reasoning_effort, model_mode, vision_model,
allowed_tools, allowed_knowledge_bases, outcome_schema — is
captured on the new agent’s v1 revision, which starts as a draft:
it cannot run a chat until deployed. Pass deploy=true to publish v1
immediately, or call deploy_agent afterwards. allowed_tools is a
list of tool scope strings or slugs; model picks the LLM.
tags is a list of tag names to attach to the agent (created if they
don’t exist yet).
Per-chat spend cap: the cap is denominated in the unit your org is
billed in, and only that one is settable. An org billed in credits
(every plan that does not bring its own provider keys) sets
per_chat_credit_limit — the same unit get_chat reports spend in as
total_credits, so the two are directly comparable. An org that pays
its model providers directly sets per_chat_cost_limit_usd. Setting
the other one is refused rather than stored, because credits are not a
flat rate per dollar — the per-model multiplier means the same dollar
cap buys a different amount of work on every model. get_agent reports
whichever of the two applies, and never both. Omit both for the
platform default.
Effort vs models: an org whose plan selects effort rather than
models does not name a model — it sets model_mode (‘trivial’ |
‘normal’ | ‘high_effort’ | ‘x_high’, shown as Trivial / Standard / High
/ X-High) and the
platform decides what that level runs (model + reasoning effort +
thinking). No level is plan-gated. Exactly one of the two selections is
meaningful per plan, so setting a level on an org with direct model
choice is refused rather than stored inert; the refusal names the levels
on offer.
Mention tokens: Instructions can reference org resources inline using
/type[key] syntax (e.g. /prompt[summarize], /agent[researcher]).
The platform resolves them at run time and appends a “Referenced
Resources” block to the agent’s system prompt. Read the
agent-mentions documentation topic for the full list of supported
types and their keys.
decision_log (‘on’ | ‘off’ | ‘inherit’) overrides the org’s decision log
setting for this agent: ‘on’ makes it record its judgement calls with the
decide tool whatever the org says, ‘off’ exempts it, ‘inherit’ (the
default) follows the org. It is a behavioural setting, so it lands on the
draft like the others.
vision_model overrides which model this agent uses to describe images
and scanned pages it opens with read_file. Omit to defer to the org’s
own override (if any), then the platform’s. Allowed values are the same
models model accepts, narrowed to those whose catalog row supports
vision; a model that cannot read images is refused.
Every allowed_tools entry must resolve in this org — a scope grant, or
a tool slug from list_org_tools / list_code_tools.
allowed_knowledge_bases is the agent’s Knowledge Access: which
knowledge bases it may search with search_knowledge. Pass base ids or
slugs (list_knowledge_bases), ["*"] for every base (the default when
omitted), or [] for none — an agent granted none does not get the
search tool at all.
Outcome contract: outcome_schema is a raw JSON Schema (draft
2020-12, root type: object, no $ref) that the agent’s structured
result must satisfy. When set, every success/partial outcome the
agent records is validated against it and the agent is handed the
errors to correct; after five invalid attempts in one run the platform
stops asking and records the outcome as failed. Set it when a system
reads the agent’s result as fields rather than prose. Pass {} to
remove an existing contract.
| Parameter | Type | Required | Description |
|---|---|---|---|
| allowed_knowledge_bases | string[] | no | |
| allowed_tools | string[] | no | |
| decision_log | string | no | |
| deploy | boolean | no | |
| description | string | no | |
| instruction | string | no | |
| model | string | no | |
| model_mode | string | no | |
| name | string | yes | |
| org | string | no | |
| outcome_schema | object | no | |
| per_chat_cost_limit_usd | number | no | |
| per_chat_credit_limit | number | no | |
| reasoning_effort | string | no | |
| tags | string[] | no | |
| vision_model | string | no |
create_agent_draft
Section titled “create_agent_draft”Start (or reset) an agent’s draft from a chosen version’s full
config — model, effort, mode, tools, knowledge bases, mounted
skills, pins, outcome schema, every capability flag, and the
instruction. Unlike copying instruction text by hand, this is the
rollback recipe: create_agent_draft(agent, from_version=N) then
deploy_agent(agent) puts the agent back to exactly how vN behaved.
from_version omitted copies the currently active revision
instead — useful to blow away an in-progress draft and start clean
from what is live. Raises if from_version does not name a live
(non-deleted) revision on this agent, or, when omitted, if the agent
has never been deployed.
If the agent already has a draft with unsaved changes of its own
(its draft_changed_fields against what is live is non-empty), this
is refused naming how many fields would be discarded — pass
replace=True to overwrite it anyway. A draft that already matches
what is live is always overwritten, replace or not.
Legal while an experiment is running — only deploy_agent is refused
then, not this.
| Parameter | Type | Required | Description |
|---|---|---|---|
| agent | string | yes | |
| from_version | integer | no | |
| org | string | no | |
| replace | boolean | no |
deploy_agent
Section titled “deploy_agent”Deploy an agent’s draft, making it the active revision — instruction,
model, tools, skills, outcome schema and every other behaviour field
the draft carries, all at once. Refused if the draft is identical to
what is already live (nothing to deploy), has no draft at all, or an
A/B experiment is currently running on this agent (stop or promote it
first — see stop_experiment / promote_experiment_arm).
| Parameter | Type | Required | Description |
|---|---|---|---|
| agent | string | yes | |
| org | string | no |
get_agent
Section titled “get_agent”Get full detail for one agent (by id or slug), including its active instruction and any undeployed draft.
active_config / draft_config are the complete configuration each of
those revisions carries (instruction, model, effort, mode, tools,
knowledge bases, skills, pins, outcome schema, capability flags), with
a *_config_hash fingerprint: equal hashes mean identical behaviour.
draft_changed_fields names exactly which of those fields the draft
would change if deployed right now — [] when there is no draft, or
the draft is identical to what is live.
running_rollout is the agent’s current rollout — a plain deploy
(one arm) or a live A/B experiment (2-5 arms, kind: "experiment").
null for an agent that has never been deployed.
| Parameter | Type | Required | Description |
|---|---|---|---|
| agent | string | yes | |
| org | string | no |
get_experiment
Section titled “get_experiment”Get one rollout’s arms (label, revision version, weight), live
per-arm chat counts (counted_chats / excluded_chats), and a
compact results summary (outcome rates, mean cost/tokens, tool-call
and HITL rates, and which metrics differ significantly from control —
see get_experiment_results for the same shape on its own).
Pass rollout_id to fetch a specific rollout (running or ended);
omit it to get whichever rollout is currently running — a plain
deploy (kind: "deploy") or a live experiment (kind: "experiment").
Errors if the agent has never been deployed, or rollout_id does not
belong to it.
| Parameter | Type | Required | Description |
|---|---|---|---|
| agent | string | yes | |
| org | string | no | |
| rollout_id | string | no |
get_experiment_results
Section titled “get_experiment_results”A compact per-arm results summary for one rollout: outcome rates (success/partial/failed/no_outcome/errored), mean cost (in this org’s billing unit) and tokens, tool-call count and error rate per chat, HITL requests per chat, median duration, and which metrics differ significantly from the control arm (95% confidence intervals that don’t overlap — a heuristic, not a p-value).
insufficient_data on an arm means its counted_chats are below the
rollout’s min_sample — every figure is still computed, just worth
treating cautiously. Cached for about 45 seconds per rollout.
Pass rollout_id to fetch a specific rollout (running or ended);
omit it to get whichever rollout is currently running. Errors if the
agent has never been deployed, or rollout_id does not belong to
it.
| Parameter | Type | Required | Description |
|---|---|---|---|
| agent | string | yes | |
| org | string | no | |
| rollout_id | string | no |
list_agents
Section titled “list_agents”List the agents in an organization.
Paged: the response carries total, has_more and next_offset —
pass next_offset back as offset to walk the rest.
| Parameter | Type | Required | Description |
|---|---|---|---|
| limit | integer | no | Max rows to return (1–200). |
| offset | integer | no | Rows to skip — pass the previous response’s next_offset. |
| org | string | no |
promote_experiment_arm
Section titled “promote_experiment_arm”End the agent’s running experiment as promoted, and deploy the
named arm (by label) at 100% traffic. arm must name one of the
running experiment’s arms. Refused if no experiment is currently
running on this agent.
| Parameter | Type | Required | Description |
|---|---|---|---|
| agent | string | yes | |
| arm | string | yes | |
| org | string | no |
start_experiment
Section titled “start_experiment”Start a 2-5 arm A/B experiment on an agent, splitting traffic by weight across sealed revisions. Supersedes whatever rollout is currently running — a plain deploy is replaced automatically; another running experiment must be stopped or promoted first.
Requires a platform admin to have turned on the agent_experiments_enabled
setting — refused (403-equivalent ToolError) otherwise.
Each entry of arms is a dict:
{"label": str, "weight_bp": int, "revision_version"|"revision_id"|"use_draft": ...}
— exactly one of revision_version (int), revision_id (uuid string),
or use_draft: true (the agent’s current draft, sealed on start) per
arm. weight_bp are basis points (10000 = 100%) and must sum to
10000 across all arms (2-5 of them). control must name one of the
arm labels — its revision is what stop_experiment deploys.
Every arm’s model must pass this org’s model allowlist, and its
allowed_tools / mounted_skills / allowed_knowledge_bases must
resolve in the org’s catalog and this agent’s own reach — the same
checks update_agent runs, applied per arm. No two arms may share a
configuration unless allow_identical is set (an A/A test).
unit picks what assignment sticks to: chat (default, one chat =
one coin flip), thread (a whole email/webhook thread stays on one
arm), user (the creator does), sender (the normalised sender
address does).
| Parameter | Type | Required | Description |
|---|---|---|---|
| agent | string | yes | |
| allow_identical | boolean | no | |
| arms | object[] | yes | |
| control | string | yes | |
| hypothesis | string | no | |
| label | string | no | |
| org | string | no | |
| unit | string | no |
stop_experiment
Section titled “stop_experiment”End the agent’s running experiment as stopped, and deploy its control revision at 100% traffic. Refused if no experiment is currently running on this agent.
| Parameter | Type | Required | Description |
|---|---|---|---|
| agent | string | yes | |
| org | string | no |
update_agent
Section titled “update_agent”Update an agent (by id or slug). Partial: only the fields you pass are changed; omit the rest to leave them untouched.
Every behaviour field lands on the draft, not live. That is
instruction, model, reasoning_effort, model_mode,
vision_model, allowed_tools,
allowed_knowledge_bases, mounted_skills, outcome_schema — all of
it. A draft is forked from the currently active revision the first
time one of these is set, and nothing above changes what a running
chat does until you deploy it: pass deploy=true to publish this same
edit immediately, or call deploy_agent afterwards (get_agent shows
has_undeployed_draft and draft_changed_fields). Everything else —
name, description, execution_mode, status, the per-chat spend
cap, tags — applies immediately regardless of deploy.
execution_mode is auto/manual/paused/dry_run (dry_run starts chats
normally but suppresses write/execute tools — reads, lifecycle tools and
decide still run; it applies to chats started after the change);
status is active/archived.
tags replaces the agent’s current tag set (pass an empty list to
clear all tags).
Effort vs models: model_mode (‘trivial’ | ‘normal’ |
‘high_effort’ | ‘x_high’, shown as Trivial / Standard / High / X-High)
is what an org whose
plan selects effort sets instead of model — the platform decides
what each level runs. Setting one on an org with direct model choice is
refused (it would be stored inert), and the refusal names the levels on
offer. Pass an empty string to clear the level back to the platform
default; omitting it leaves whatever is set alone.
decision_log (‘on’ | ‘off’ | ‘inherit’) overrides the org’s decision log
setting for this agent: ‘on’ makes it record its judgement calls with the
decide tool whatever the org says, ‘off’ exempts it, ‘inherit’ (the
default) follows the org. It is a behavioural setting, so it lands on the
draft like the others.
vision_model overrides which model this agent uses to describe images
and scanned pages it opens with read_file, ahead of the org’s own
override (if any) and the platform’s. Allowed values are the same
models model accepts, narrowed to those whose catalog row supports
vision. Pass an empty string to clear it back to the org/platform
default; omitting it leaves whatever is set alone.
Mention tokens: Use /type[key] tokens in instruction to reference
org resources inline (e.g. /prompt[slug], /skill[slug],
/agent[slug], /tool[name], /connected-tool[slug]). The platform
resolves them at run time. See the agent-mentions documentation topic
for details.
To save tokens the response OMITS the full instruction texts (it returns
their lengths + revision ids + has_undeployed_draft); call get_agent
for the full text.
Every allowed_tools entry must resolve in this org (a scope grant, or a
slug from list_org_tools / list_code_tools), and every
mounted_skills entry must be an existing skill slug (list_skills).
Narrowing allowed_tools also unpins: any of the agent’s pinned tools
the new grants no longer admit is dropped (a pin is loaded directly,
ahead of discovery, and would otherwise survive the revocation).
allowed_knowledge_bases replaces the agent’s Knowledge Access grant:
base ids or slugs (list_knowledge_bases), ["*"] for every base, or
[] to revoke all knowledge. Omit it to leave the grant untouched.
Outcome contract: outcome_schema is a raw JSON Schema (draft
2020-12, root type: object, no $ref) that the agent’s structured
result must satisfy. When set, every success/partial outcome the
agent records is validated against it and the agent is handed the
errors to correct; after five invalid attempts in one run the platform
stops asking and records the outcome as failed. Set it when a system
reads the agent’s result as fields rather than prose. Pass {} to
remove an existing contract.
Per-chat spend cap: settable in your org’s own billing unit only.
An org billed in credits sets per_chat_credit_limit — the unit
get_chat reports spend in as total_credits, so cap and spend are
directly comparable. An org that pays its model providers directly sets
per_chat_cost_limit_usd. The other one is refused rather than stored:
credits are not a flat rate per dollar, so a dollar cap buys a
different amount of work on every model. The response reports whichever
applies, never both.
| Parameter | Type | Required | Description |
|---|---|---|---|
| agent | string | yes | |
| allowed_knowledge_bases | string[] | no | |
| allowed_tools | string[] | no | |
| decision_log | string | no | |
| deploy | boolean | no | |
| description | string | no | |
| execution_mode | string | no | |
| instruction | string | no | |
| model | string | no | |
| model_mode | string | no | |
| mounted_skills | string[] | no | |
| name | string | no | |
| org | string | no | |
| outcome_schema | object | no | |
| per_chat_cost_limit_usd | number | no | |
| per_chat_credit_limit | number | no | |
| reasoning_effort | string | no | |
| status | string | no | |
| tags | string[] | no | |
| vision_model | string | no |