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

Top-Level Fields

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.

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.

Example:

exec:
  use_template:
    name: security/scanner

ToolSelect

Selects the built-in tools available to the agent.

When transfer_to_workspace is enabled, the instructions must explicitly mention:

• how to identify the sandbox and the workspace;
• to use use_workspace to target the workspace;
• to transfer to the workspace agent.

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.

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.

SubAgent.Custom

SubAgent.Template

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.

Example:

visibility:
  scope: SUB_AGENT

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