Agents

create_agent

Create a new agent.

instruction is the agent’s task definition (becomes its v1 draft revision — call deploy_agent to make it active). 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’, shown as Trivial / Standard / 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.

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
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
system_prompt	string	no
tags	string[]	no

deploy_agent

Deploy an agent’s draft instruction, making it the active revision.

Parameter	Type	Required	Description
agent	string	yes
org	string	no

get_agent

Get full detail for one agent (by id or slug), including its active instruction and any undeployed draft.

Parameter	Type	Required	Description
agent	string	yes
org	string	no

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

update_agent

Update an agent (by id or slug). Partial: only the fields you pass are changed; omit the rest to leave them untouched.

instruction edits land on the agent’s draft revision (NOT live until you call deploy_agent); other fields apply immediately. execution_mode is auto/manual/paused; 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’, shown as Trivial / Standard / 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.

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
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
system_prompt	string	no
tags	string[]	no