AI Agent Definition
An AI Agent Definition describes a custom, user-defined AI Agent: what the agent is for, how it is executed, which tools and MCP servers it may use, which sub agents it may delegate to, and which model runs it.
The definition is what the agent editor in the Web Console writes, and what is exchanged when an agent is cloned, shared at org level, or managed as configuration. The agent's own name is the name of the agent resource, and is therefore not part of the definition below.
For a guided walkthrough of building an agent, see Build AI Agents.
Structure Overview
brief: One line about what the agent does.
details: |
Longer explanation of how to use the agent.
instructions: |
The system prompt of the agent's own conversation.
exec: # Optional dedicated execution environment
use_template:
name: ...
tools: # Built-in tool selection
system: true
mcp_servers: # External tools
use_global_config: true
explicit:
- ref: ...
sub_agents: # Agent team members
- custom:
name: ...
visibility: # Where the agent can be used
scope: NORMAL
model: coding # Model selector
model_mapping: # Optional per-agent model remapping
mappings:
generic: fast
prompts: # Prompt templates offered to start conversations
- name: default
prompt:
inputs:
- name: ...
body:
language: mustache
script: ...
Top-Level Fields
| Field | Type | Description |
|---|---|---|
brief |
string | A short summary of what the agent does. This is essential for the LLM model to find the right agent during the planning phase, so it should be accurate and stay compact. |
details |
string | A more detailed description of the agent. It is queried when the LLM model wants to learn more about an agent it has selected, and typically explains what the initial prompt should contain. |
instructions |
string | Used as part of the system prompt during agent execution. It is only visible inside the agent's own conversation, never to the model or parent agent that starts it. |
exec |
Exec | How to execute the agent. Omit it when the agent needs no dedicated environment of its own. |
mcp_servers |
MCPServerSelect | The MCP servers to connect during agent execution. |
tools |
ToolSelect | Selection of the built-in tools. |
sub_agents |
SubAgent[] | The sub agents that the current agent may use. |
visibility |
Visibility | Defines the visibility and usability of the agent. |
model |
string | The default model used to run the agent. It can be a model purpose, an alias, or a full provider:name selector. If unspecified, the GENERIC model is used. See Model for how a selector is resolved. |
model_mapping |
ModelMapping | Remaps the models used by this agent. The mapping is copied into the session context when a session is created for this agent and the initial context defines no mapping of its own. An invalid entry is reported as an error rather than being silently ignored. |
prompts |
Prompt[] | Prompt templates offered to start or compose conversations with this agent, in display order. They are embedded in the agent, so they share the lifetime of the agent. |
The three text fields play distinct roles: brief and details are written for the caller — the system, or a parent agent, deciding which agent to use — while instructions are written for the agent itself.
Exec
Defines how to execute the agent. When exec is omitted, the agent runs without a dedicated sandbox and relies on its instructions, tools, and MCP servers alone.
Exactly one execution method must be specified.
| Field | Type | Description |
|---|---|---|
use_template |
Exec.UseTemplate | Required. Create a sandbox from a template to run the agent. |
When an execution environment is defined, the sandbox is created for the conversation before it starts, and its lifetime is linked to that conversation: it is deleted when the conversation is archived or deleted.
Exec.UseTemplate
Creates a sandbox to run the agent.
| Field | Type | Description |
|---|---|---|
name |
string | Required. The full name of the template, including the folder path when the template is in a folder. |
exec |
LLMAgent.Exec | The details for execution inside the created sandbox: which workload runs the agent, the command to launch it, and the event format. If omitted, the built-in agent of the first workspace is used. |
Example:
exec:
use_template:
name: security/scanner
ToolSelect
Selects the built-in tools available to the agent.
| Field | Type | Description |
|---|---|---|
system |
boolean | Include the Crafting system tools, which let the agent interact with the Crafting system — for example, listing templates and managing sandboxes. |
transfer_to_workspace |
boolean | If true, the agent may eventually transfer to the built-in workspace agent. When this is set, the system tools are selected automatically. |
When transfer_to_workspace is enabled, the instructions must explicitly mention:
- how to identify the sandbox and the workspace;
- to use
use_workspaceto target the workspace; - to transfer to the
workspaceagent.
Once transferred, the session stays with the workspace agent as the current agent. This is the mechanism behind a flexible environment, where an agent works inside an existing sandbox instead of a dedicated one.
Example:
tools:
transfer_to_workspace: true
MCPServerSelect
Selects the MCP servers to connect during agent execution.
| Field | Type | Description |
|---|---|---|
use_global_config |
boolean | Use the MCP servers defined in the global configuration — the Globally Activated MCP Servers list of the org. |
explicit |
MCPServer[] | Explicitly specified MCP servers to connect during agent execution. |
Each entry of explicit either references an authorized server by name (ref), or defines a server inline. An inline definition counts as a custom MCP server and is only permitted when the org's MCP server policy allows custom servers.
Example:
mcp_servers:
use_global_config: true
explicit:
- ref: github
- sandbox: tools/mcp-hub
SubAgent
References a sub agent that the current agent may delegate to. Exactly one of custom or template must be specified.
| Field | Type | Description |
|---|---|---|
custom |
SubAgent.Custom | Reference another custom (user-defined or org-level) agent. |
template |
SubAgent.Template | Reference an agent declared in the customizations of a template. |
SubAgent.Custom
| Field | Type | Description |
|---|---|---|
name |
string | Required. The name of the custom agent. Wildcards * and ? are accepted, so that the agent can coordinate with every matching agent instead of a fixed set. See The Team Lead. |
SubAgent.Template
| Field | Type | Description |
|---|---|---|
name |
string | Required. The name of the template that declares the agent. |
agent |
string | The name of the agent in the template's customizations. If unspecified, the first agent is used. |
Example:
sub_agents:
- custom:
name: coding
- custom:
name: qa
- template:
name: security/scanner
agent: vulnerability-scan
A general purpose leading agent uses a wildcard instead:
sub_agents:
- custom:
name: '*'
Visibility
Defines the visibility and usability of the agent.
| Field | Type | Description |
|---|---|---|
disabled |
boolean | If true, this agent cannot be used. |
scope |
enum | Where the agent may be used: NORMAL (default) — the agent is listed and can start a conversation, and can also be used as a sub agent; SUB_AGENT — the agent is only usable as a sub agent, and is not listed as an agent to start a conversation with. |
Example:
visibility:
scope: SUB_AGENT
Prompt
A prompt template offered to start or compose conversations with this agent. See Prompt Templating for how prompt templates are used.
| Field | Type | Description |
|---|---|---|
name |
string | Required. Identifies the prompt within the agent, as titles are only for display and may repeat. It follows the same rule as agent names (letters, digits and dashes), and must be unique within the agent. |
description |
string | Tells users what the prompt is for when browsing the prompts of the agent. |
prompt |
Snippet | The content of the prompt. It is expanded by the client before sending, so the agent only sees plain text. |
No session presets (such as the agent to use) are defined here, as the agent is implied. To bundle a prompt with session presets, use a Quick Task instead.
From the CLI, a prompt is selected with cs llm session run --agent-prompt NAME, and its inputs are given with -i, --input KEY=VAL.
Example:
prompts:
- name: default
description: The default prompt
prompt:
inputs:
- name: sandbox
title: Sandbox
description: The sandbox where code change exists
required: true
reference:
kind: SANDBOX
body:
language: mustache
script: >
Review the code change in {{sandbox}}
Snippet
A titled text with inputs for the user to fill in, expanded into plain text. A snippet only holds the content; the containing object (for example, a Prompt) identifies and describes it.
| Field | Type | Description |
|---|---|---|
title |
string | The human readable name displayed in the UI, as names are restricted for references. If unspecified, the name of the containing object is displayed. |
body |
Transform | The template expanded with the values of the inputs. The language must be mustache or go-template. |
inputs |
InputField[] | The inputs filled in by the user when the snippet is used, displayed in this order. Every input must be referenced in the body, and referencing an undeclared input is invalid. |
Referencing Inputs
An input is referenced as {{NAME}} in Mustache, and as {{ .inputs.NAME }} in a Go template. Mustache is preferred: clients expand the body before sending it, and a client without a Go template implementation, such as the browser, has to ask the server to expand a Go template.
A value is printed as text:
- a number without an exponent;
- a boolean as
trueorfalse; - multiple choices joined by
,; - no value as empty text.
For loops in Mustache, each of the multiple choices has value, index (starting from 1), first and last, and the list itself has Count and Any.
To keep expansion fast, sections in Mustache and ranges in a Go template nest at most 4 levels deep, and a Go template can't range over an integer or call templates recursively.
Example:
inputs:
- name: areas
title: Areas to review
choice:
multiple: true
options:
- value: security
- value: performance
- value: style
body:
language: mustache
script: |
Review the change, focusing on:
{{#areas}}
{{index}}. {{value}}
{{/areas}}
Transform
| Field | Type | Description |
|---|---|---|
language |
string | The language of the script: mustache — a Mustache template, with HTML escaping off and partials not allowed; go-template — a Go template. |
script |
string | The template in the selected language. |
InputField
A single field for the user to fill in. It is rendered as a form control in the Web Console, and as a flag or an interactive prompt by the CLI. The input types are a superset of the requested schema of MCP elicitation.
Exactly one of text, number, boolean, choice or reference must be specified, which determines the type of the field.
| Field | Type | Description |
|---|---|---|
name |
string | Required. Identifies the field — referenced as {{NAME}} in a snippet body, used as the key of the value, and as the CLI flag. Must match [A-Za-z_][A-Za-z0-9_]* and be unique within the containing list. |
title |
string | The label of the control. If unspecified, the name is displayed. |
description |
string | Longer help text shown on demand, for fields that need more explanation than the title. |
placeholder |
string | Text displayed in place of an empty value, telling the user what to fill in (e.g. e.g. TestCreateSandbox). It is not a value, so it is never submitted or inserted into a snippet. In a snippet preview, it is displayed where the field is referenced in the body. |
required |
boolean | Requires a value before the form can be submitted. Without it, an empty value is accepted and expands to empty text in a snippet. |
text |
InputField.Text | Free text. |
number |
InputField.Number | A number. |
boolean |
InputField.Boolean | A yes/no answer. |
choice |
InputField.Choice | A selection from a fixed list. |
reference |
InputField.Reference | A Crafting resource visible to the user. |
InputField.Text
Free text.
| Field | Type | Description |
|---|---|---|
default |
string | Pre-filled value, so the user only needs to change it when necessary. |
multiline |
boolean | Renders a multi-line editor for long text, e.g. a bug description. |
min_length |
integer | If positive, rejects text shorter than this number of Unicode code points. |
max_length |
integer | If positive, rejects text longer than this number of Unicode code points. |
format |
enum | A well-known format, letting the client offer specialized editors and checks: PLAIN (default), EMAIL, URI, DATE, DATE_TIME. |
validators |
Text.Validator[] | Rules the value must all satisfy, checked in order. The message of the first failing rule is shown. |
Text.Validator
A rule the value must satisfy.
| Field | Type | Description |
|---|---|---|
regexp |
string | Required. A regular expression the whole value must match. Use only the syntax common to RE2 and JavaScript, as the server (RE2) is authoritative while the UI checks early. |
message |
string | Explains the expected value when the rule fails, instead of showing the rule. |
Example:
- name: ticket
title: Ticket
placeholder: e.g. ENG-1234
required: true
text:
validators:
- regexp: '[A-Z]+-[0-9]+'
message: Must be a ticket ID like ENG-1234
InputField.Number
A number, optionally restricted to integers and a range. All numbers must be finite with an absolute value less than 1e15.
| Field | Type | Description |
|---|---|---|
default |
number | Pre-filled value, or none if unspecified. |
minimum |
number | The smallest accepted value, inclusive, or no limit if unspecified. |
maximum |
number | The largest accepted value, inclusive, or no limit if unspecified. |
integer |
boolean | Rejects fractions. |
InputField.Boolean
A yes/no answer, rendered as a checkbox or a switch.
| Field | Type | Description |
|---|---|---|
default |
boolean | Pre-filled value. |
InputField.Choice
A selection from a fixed list. Nothing is selected by default unless defaults is specified.
| Field | Type | Description |
|---|---|---|
options |
Choice.Option[] | Required. The options in display order. At least one is required. |
multiple |
boolean | Allows selecting more than one option, and the value becomes a list. |
allow_custom |
boolean | Also allows entering a custom value that is not in the list, besides selecting options. |
defaults |
string[] | Pre-selected option values — at most one unless multiple is set. They must be values of options unless allow_custom is set. |
min_items |
integer | If positive, the fewest selections accepted when multiple is set. |
max_items |
integer | If positive, the most selections accepted when multiple is set. |
Choice.Option
| Field | Type | Description |
|---|---|---|
value |
string | Required. The value recorded, and inserted when used in a snippet. Must be unique within the options. |
title |
string | The label displayed. If unspecified, the value is displayed. |
description |
string | Explains the option, e.g. as a tooltip or secondary text. |
Example:
- name: severity
title: Severity
choice:
defaults: [medium]
options:
- value: low
- value: medium
- value: high
description: Requires immediate attention
InputField.Reference
A Crafting resource visible to the user, picked from live candidates and recorded by its full name.
| Field | Type | Description |
|---|---|---|
kind |
enum | The kind of resource to reference: SANDBOX or TEMPLATE. |
default |
string | The full name of the pre-selected resource. It is ignored if the resource is not visible to the user. |
Full Example
A leading agent that coordinates a team, runs on the coding model, and works inside whichever sandbox the user names:
brief: Coordinate coding, review and security tasks across a project
details: |
Describe the change to make, and optionally name a sandbox to work in.
The agent plans the work, delegates to the specialized agents, and
reports back a summary of what has been changed.
instructions: |
You are a software engineering manager coordinating a team of agents.
Break the request into focused tasks and delegate each of them.
Only use a sandbox if the user explicitly names one.
Otherwise, create a new sandbox from the backend-dev template.
Transfer to the workspace to perform the tasks inside.
tools:
transfer_to_workspace: true
mcp_servers:
use_global_config: true
explicit:
- ref: github
sub_agents:
- custom:
name: '*'
visibility:
scope: NORMAL
model: coding
A sub agent with a dedicated execution environment:
brief: Scan vulnerabilities from a given URL
details: |
Specify a URL for the agent to scan vulnerabilities.
The agent reports discoveries which can be used as feedback for fixing them.
instructions: |
You are responsible for detecting vulnerabilities from web sites.
When asked to scan a given URL, run `/home/owner/scan/scan.sh -m fast URL`
and report the findings parsed from the output JSON of the command.
exec:
use_template:
name: security/scanner
visibility:
scope: SUB_AGENT
See Also
- AI Agent — the concept behind this definition
- Build AI Agents — defining, testing, and sharing an agent
- LLM Configuration Definition — providers, models, and the org-level MCP registry
- Sandbox Definition — the template that backs an execution environment
- MCP Servers — authorizing and using external tools
- Agentic Sessions — the conversations an agent runs in
- Prompt Templating — prompts with inputs filled in by the user
- Quick Task Definition — prompts bundled with session presets, using the same
Snippet