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; provider/model pick the LLM. per_chat_cost_limit_usd caps spend per chat (auto-pauses the agent when exceeded); defaults to 1.00 if omitted. tags is a list of tag names to attach to the agent (created if they don’t exist yet).

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.

Parameter	Type	Required	Description
allowed_tools	string[]	no
description	string	no
instruction	string	no
model	string	no
name	string	yes
org	string	no
per_chat_cost_limit_usd	number	no
provider	string	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).

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).

Parameter	Type	Required	Description
agent	string	yes
allowed_tools	string[]	no
description	string	no
execution_mode	string	no
instruction	string	no
model	string	no
mounted_skills	string[]	no
name	string	no
org	string	no
per_chat_cost_limit_usd	number	no
provider	string	no
reasoning_effort	string	no
status	string	no
system_prompt	string	no
tags	string[]	no