Skip to content
- Agent — the primary entity. Has a
name/slug, an LLM (provider/model),
an instruction (its task definition), an allowed toolset, and mounted skills. execution_mode is
auto / manual / paused / dry_run (a dry run starts chats but
suppresses write/execute tools, frozen per chat at creation); status is active / archived.
- Effort — how an org whose plan selects effort rather than models picks
its LLM: set
model_mode (trivial | normal | high_effort | x_high,
shown as Trivial / Standard / High / X-High) on the agent instead of
provider/model, and the platform decides what that level runs. Trivial is
the cheap rung for routine work and burns a fraction of Standard; High and
X-High buy dearer models for harder work. No level is plan-gated. start_chat takes a model_mode_override to
change one chat’s level in either direction (sticky for that chat’s later
messages). Exactly one of the two selections is meaningful per plan — an org
with direct model choice is refused a level rather than storing an inert one,
and the refusal names the levels on offer.
- Revisions & drafts — a revision is an agent’s complete behavioural
configuration: instruction, model, reasoning effort, mode, allowed tools,
knowledge bases, mounted skills, pins, outcome schema, and the capability
flags. Editing ANY of those with
update_agent lands on a draft revision
(forked from the active one) — none of it is live until you deploy_agent
or pass deploy=true to update_agent/create_agent. Fields outside that
list (name, description, status, execution_mode, tags, per-chat caps) apply
immediately either way. get_agent shows instruction/active_config
(active) plus draft_instruction/draft_config/has_undeployed_draft/
draft_changed_fields (what deploying now would change).
- Building blocks (reusable, org-scoped) the agent composes:
- Code tool (
code_tool) — a custom Python tool: one public entrypoint
function plus any _-prefixed helpers. What the model sees comes from a
normal docstring on that function (the module docstring is the fallback) —
its first paragraph is the tool description and an Args: section
describes the parameters — plus the type annotations for the parameter
types. A parameter can carry its own description with
Annotated[str, "..."] instead, which wins over Args:. A YAML manifest:
block in the docstring is a deprecated legacy form; write Args:.
- Prompt — a reusable prompt template with
{{variables}}. Optionally
carries an extraction schema (fields, see prompt-fields) — when set,
running it pulls structured fields out of input instead of generating
free text.
- Skill — a bundle of {instructions + a tool subset + reference material}
an agent mounts by slug. Live immediately on create/update.
- Integration — a connection to an external SaaS / MCP server (read-only here;
connect new ones in the web UI — many need an interactive OAuth flow).
- Environment — where the agent’s files live and its commands run. Defaults
to our built-in cloud sandbox; an org can instead point an agent at its own
container image or at a machine it owns. See
agent-environments.
- Chat — the unit of work. You
start_chat with a message; the agent runs a
turn. Success is recorded as outcomes (not a terminal status).
- Outcome — an append-only record the agent emits when it completes a goal
(status success / failed / partial, with a summary).
- HITL — human-in-the-loop. A chat can pause awaiting approval or input; you
answer with
respond_to_hitl to resume it.