agent.yaml Reference

This article lists every key of an agent definition. The same schema is used for top-level agents (AI/Agents/<agent>/agent.yaml) and for sub-agents (AI/Agents/<agent>/Subagents/<name>.yaml); where a key behaves differently for sub-agents, it is noted.

Unknown keys are ignored without an error. A misspelled key silently disables the feature it was meant to configure — check the key names carefully, or use the Studio Agent Editor, which writes valid keys for you.

Top-Level Keys

Key	Type / default	Description
`description`	string	One-line description of the agent. Shown to a parent agent in its sub-agent catalog — write it as a routing hint ("Credit cards — cards, statements, payments ...") — and returned by the `agents` web service.
`system_prompt`	string (Markdown)	The agent's role and instructions. The runtime appends generated sections after it (sub-agent catalog, skills catalog, planning instructions, response guidelines, constraints).
`response_prompt`	string	House style for the user-facing reply, appended under `## Response Guidelines`. It applies to the whole turn: when the agent delegates a turn, its response guidelines replace the sub-agent's own. See Sub-Agents and Delegation.
`constraints`	string or list of strings	Non-negotiable rules ("Never include internal IDs in a customer-facing reply"), appended last under `## Constraints`. Constraints are additive: when a turn is delegated, the caller's constraints are added to the sub-agent's.
`tools`	list default: `query`, `current_datetime`	Built-in tool toggles and Broadway flow tools, optionally with per-tool hooks. When `tools` is omitted, `query` and `current_datetime` are enabled. When it is present, only the listed built-ins are enabled. See Tools Entries.
`mcp_interfaces`	list of strings	Names of MCP interfaces whose tools are exposed to the agent, as `MCP__<interface>__<tool>`.
`skills`	list	Skills available to the agent, merged with the agent's `Skills/` folder. Use it to add LU-wide or shared skills and to set `auto_load`. Forms: `- name`, `- name: {auto_load: true}`, `- {name: x, auto_load: true}`. See Skills.
`sub_agents`	list default: all folder sub-agents	Adjusts the sub-agents discovered in the `Subagents/` folder: disable one (`enabled: false`), link a top-level agent of another LU (`lu:`), or restrict the route (`invoke: both \| task \| delegate`). Entries are a name or `{name, lu, enabled, invoke}`.
`delegate`	boolean default: `false`	Offers the `delegate` tool, which hands the whole turn to a sub-agent. Off by default.
`hooks`	map	Broadway flows for `step_start`, `step_end`, `pre_tool_call`, `post_tool_call` and `on_error`. See Hooks and Agent Inputs.
`planning`	boolean or map default: off	Plan-then-execute mode (top-level agents only). `true` enables it with user approval of the plan. Map form: `{enabled, approve, prompt}` — the map enables planning unless `enabled: false`; `approve: false` runs the plan without asking; `prompt` replaces the planner's prompt.
`search_reference`	boolean or map default: off	Adds the `search_references` tool over the agent's reference packs. Map form: `{enabled, prompt}`, where `prompt` replaces the reference-search sub-agent's prompt.
`widget`	boolean default: `false`	Adds the `build_widget` tool, with which the agent renders charts, tables and links in the chat.
`settings`	map	Behavior settings — see below. Folder sub-agents inherit the parent's settings key by key; a value in the sub-agent overrides the inherited one.

There is no model key: the model is defined by the LLM interface the agent uses (settings.llm_interface).

Tools Entries

Each entry of tools: is one of:

tools:
  - query                       # built-in toggle: query, fabric, current_datetime
  - current_datetime
  - fabric:                     # built-in with per-tool hooks
      enabled: true
      before: GuardFabricCommand
  - getCreditScore              # a Broadway flow tool (looked up in the agent's LU, then aifusion)
  - updateCreditCardLimit:      # flow tool with per-tool hooks
      before: ValidateLimit
      after: AuditOperation
  - LU__customer_crm__getCases  # flow tool pinned to another LU

Platform tools — task, ask_user, load_skill, search_references, the planning tools, build_widget and the MCP tools — are added automatically according to the other keys. Do not list them. See Tools.

Settings

All settings are optional.

Setting	Default	Description
`llm_interface`	`default`	The AI interface used for the agent's LLM calls (`llm://<name>`). The default resolves to the interface tagged `default`.
`thinking`	`off`	Reasoning level: `off`, `low`, `medium`, `high`, `xhigh`, `max`. Each connector maps it to its provider's API. See LLM Connectors.
`use_cache`	`true`	Use the provider's prompt caching.
`max_iterations`	`20`	Maximum number of LLM ↔ tool iterations in one turn.
`max_retries`	`1`	Retries of a failed LLM or tool call.
`max_step_continuations`	`3`	Maximum number of times a `step_end` hook can send the agent back to work in one turn. `0` disables continuations.
`observability`	`true`	Record messages, executions, tool calls and token usage. Required for Trace, Observation and Evaluation.
`logging_level`	`info`	Agent log level: `off`, `debug`, `info`, `warn`.
`lean_history`	`true`	When replaying earlier turns, keep only the user and assistant text and drop their tool calls and tool results, to keep the context small. Set to `false` if the agent must see earlier tool results.
`compaction_threshold_fraction`	`0` (off)	Fraction of the context window at which older history is summarized (for example `0.8`).
`compaction_context_window_tokens`	`0` (off)	The model's context window, in tokens (for example `200000`). Compaction runs only when both this and the threshold are greater than 0.
`compaction_keep_recent_messages`	`20`	Number of most recent messages that compaction keeps verbatim.
`compaction_interface`	= `llm_interface`	Interface used to write the compaction summary — a cheaper model is usually enough.
`chat_naming`	`true`	Generate a short name for the conversation, shown in chat history lists.
`chat_name_interface`	= `llm_interface`	Interface used to generate the chat name.
`snap_session_mode`	`none`	When to take snapshots of the session's data: `none`, `all`, `frequency` (with `snap_frequency_limit`, default 10) or `period` (with `snap_period_value`, default 15, and `snap_period_unit`, `minutes` or `hours`). Studio Preview always snapshots; evaluation runs never do.
`memory`	`false`	Enables the session memory store. See Sessions and Context.
`eval_defaults_name`	`evalDefaults`	The row of the `evaluationDefaults` MTable used when new test cases are created for this agent. See Quality Criteria.

Complete Example

Based on the banking agent of the aifusion-demo extension:

description: "Elite Banking concierge — answers from the customer's data, follows written procedures, routes operations to specialists"

system_prompt: |
  # Elite Banking Assistant
  You own the conversation with one customer.
  - Answer read-only data questions yourself with `query`.
  - For product and policy questions, call `search_references`.
  - For multi-step operations, follow ## Planning and use `task` for each step.
  - For a single operation with all inputs known, `delegate` to the specialist.
  When calling a sub-agent, always pass `customerId` in `args`.

response_prompt: |
  - Be concise. Ask only for missing essentials.
  - Reply like a banker: summarize rather than echo raw tool output.

constraints:
  - Never include internal IDs in a customer-facing reply.
  - Never state a figure you did not read from a tool result.

delegate: true

tools:
  - query
  - current_datetime

skills:
  - dda-schema
  - crm-schema: { auto_load: true }

sub_agents:
  - name: payroll
    enabled: false              # folder sub-agent, muted
  - name: credit-card
    invoke: delegate            # may only receive whole turns

hooks:
  step_start: Banking_CustomerStory   # loads the customer; declares the required customerId input
  on_error: FriendlyError

planning:
  approve: false                # plan-then-execute without asking for approval

search_reference: true
widget: true

settings:
  llm_interface: default
  thinking: medium
  max_iterations: 30
  max_retries: 2
  compaction_threshold_fraction: 0.8
  compaction_context_window_tokens: 200000
  compaction_keep_recent_messages: 30

Obsolete Keys

The following keys from pre-3.0 agent files are no longer read. Remove them when migrating:

.agent files — use agent.yaml.
tools: {built_in, custom} (nested form) and flows: — use the flat tools: list.
Top-level llm_interface, memory, snap_session_mode — move under settings:.
hooks: {max_iteration, retry_on_failure, custom_hooks, fabric_get} — use settings and flow hooks.
input_params, content_flows — agent inputs are now declared by hook flows.
search_reference.dir — packs are discovered from References/.
Built-in tools answer_user, execute_flow, list_skills, search_old_plans.

Next article: Tools