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:

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:

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