Build

Agent YAML

Every field supported in an agent YAML file, plus the syntax for prompts, tools, and conditional configuration.

Last updated July 21, 2026

Configuration fields

Field	Type	Status	Description
version	string	Required	Configuration schema version. Currently only '1.0' is supported.
name	string	Required	Unique agent identifier. Use lowercase letters, numbers, and hyphens.
type	string	Optional	Agent type: `llm`, `sequential`, or `tool`. See Agent Types.Default: `llm`
description	string	Required	Human-readable description of what the agent does.
model	string	Optional	Primary AI model. Required for LLM agents. See Models and Providers.
fallback_model	string	Optional	Fallback used when the primary provider is unavailable because of an outage, rate limit, authentication error, or timeout.
system_prompt	string	Optional	Instructions for LLM agents. Use YAML's pipe character for multiple lines.
tools	list	Optional	Tools loaded into an LLM agent context. Supports strings, condition mappings, and wildcard patterns. See Conditional Tools. Maximum 100 per agent.Default: `[]`
discoverable_tools	list	Optional	Tools indexed for on-demand discovery instead of loaded up front. Uses the same strings, conditions, and wildcards as `tools`. See Discoverable Tools.Default: `[]`
agents	string[]	Optional	Agent names to execute in sequence. Required for sequential agents.Default: `[]`
tool_name	string	Optional	Custom tool executed directly by a tool agent. Use its exact dotted module path. Predefined and api: tools are not allowed.
max_concurrent_runs	integer	Optional	Maximum simultaneous runs, capped by the subscription plan. See Runtime Controls.Default: `1`
temperature	number	Optional	Controls randomness in LLM output. Lower values are more deterministic.Default: `1`
reasoning_effort	string	Optional	Shared reasoning level: auto, off, minimal, low, medium, high, or xhigh. Each provider maps it to a native parameter.Default: `auto`
reasoning_budget	integer	Optional	Deprecated raw reasoning-token budget for legacy Anthropic Claude 3.7/Sonnet 4 and Gemini 2.5 models. Use reasoning_effort for current models.
retry_options	object	Optional	Retries at the failing operation boundary. LLM requests are retried without replaying the agent; tool and sequential agents retain operation-level retries.
attempts	integer	Optional	Total attempts per selected model or non-LLM operation, including the first. Maximum 10.Default: `3`
initial_delay	number	Optional	Initial backoff in seconds. Model requests use capped exponential backoff with jitter unless the provider sends Retry-After.Default: `10`
max_delay	number	Optional	Maximum retry delay and Retry-After cap in seconds. Maximum 300.Default: `30`
rerun_middleware	boolean	Optional	Re-run before middleware for operation retries on tool and sequential agents. It has no effect on LLM agents.Default: `false`
timeout	integer	Optional	Maximum execution time in seconds. Minimum five seconds and always capped by the subscription limit.
max_iterations	integer	Optional	Maximum LLM loop iterations per run. Prevents infinite loops and excessive resource use.Default: `100`
guardrails	object	Optional	Input and output safety rules for LLM agents. See Guardrails.
input	object[]	Optional	Rules applied to raw input before middleware and agent execution.
output	object[]	Optional	Rules applied to the response before it is returned.
run_after_on_block	boolean	Optional	Whether after middleware runs when an input rule blocks the request.Default: `true`
type	string	Required	Guardrail type: prompt_injection, pii, moderation, topic_restriction, regex, pii_leakage, system_prompt_leakage, relevance, data_exfiltration, or custom.
mode	string	Optional	block, warn, or redact. Redaction is only supported for pii and pii_leakage.Default: `block`
name	string	Optional	Guardrail module name. Required when type is custom.
config	object	Optional	Per-rule options including messages, fail_run, entities, patterns, provider, sensitivity, and model.
rejection_message	string	Optional	Message returned when a rule blocks. Falls back to off_topic_message.
off_topic_message	string	Optional	Message for topic_restriction blocks and fallback for rejection_message.
fail_run	boolean	Optional	When true, a block marks the run failed. Otherwise it returns a completed response with the rejection message.Default: `false`
output_schema	string	Optional	JSON Schema filename from schemas/. Forces structured JSON output for LLM agents. See Output Schema.
mcp_servers	object[]	Optional	External MCP servers. Maximum 50 per agent. See Use MCP Servers.
name	string	Required	MCP server identifier.
url	string	Required	MCP server endpoint URL.
tools	string[]	Optional	Optional filter of tools to load. Omit to use every server tool.
headers	object	Optional	Authentication headers. Supports variable interpolation with `${VAR}` and per-run interpolation with `${context.*}`.
discoverable	boolean	Optional	Index tools from this server for on-demand discovery rather than loading them up front.Default: `false`
concurrency	object	Optional	One active run per resolved key. Not supported on sequential agents. See Concurrency Rules.
key	string	Required	Dot path used to extract the key from the trigger payload.
on_conflict	string	Optional	queue waits for the active run; drop cancels the new run.Default: `queue`
approval	object	Optional	Human approval for selected tools. See Approvals.
tools	list	Required	Tool references that require approval. A mapping value can condition approval with param.* and context.* expressions.
timeout	integer	Optional	Seconds to wait for a decision. Range: 30–604800.Default: `3600`
message	string	Optional	Custom message shown to the reviewer.
on_rejection	string	Optional	fail terminates the run; continue returns a rejection message to the LLM so it can adapt.Default: `fail`
session	object	Optional	Persistent conversation history keyed by a resolved value. See Persistent Sessions.
key	string	Required	Dot path beginning with context. or input. that resolves the session ID.
ttl	integer	Optional	Session expiry in seconds. Minimum 60; without it, sessions do not expire.
context_compression	object	Optional	Mid-run compression for long LLM sessions. Omit to keep compression off.
enabled	boolean	Optional	Enable compression when the block is present.Default: `true`
model	string	Optional	Optional model used only for compression summaries. Defaults to the agent model.
max_prompt_tokens	integer	Optional	Prompt-token threshold that can trigger compression before a provider context-window error.
keep_recent_messages	integer	Optional	Recent messages kept verbatim when compression runs.Default: `8`
session_history	object	Optional	Optional stored-history compaction between runs. Omit to keep it off.
interval	integer	Optional	Compact older stored history after this many runs.
keep_recent_runs	integer	Optional	Recent runs left unsummarized during stored-history compaction.Default: `1`

Required fields by type

All agents: version, name, and description

LLM: + model and system_prompt · Sequential: + agents · Tool: + tool_name

Writing system prompts

agents/agent.yaml

system_prompt: |
  This is a multi-line system prompt.

  You can write multiple paragraphs here.
  The pipe character (|) preserves newlines.

  Use this for complex instructions.

Best practices: define the role and responsibilities, include examples, specify output formats, and mention the available tools.

Referencing tools

agents/agent.yaml

# Reference tools by exact module path under tools/
tools:
  - search.web_search            # tools/search.py -> web_search()
  - billing.calculator.add       # tools/billing/calculator.py -> add()
  - email.send_notification      # tools/email.py -> send_notification()
  - billing.*                    # all public functions in tools/billing.py
  - support.search_*             # functions starting with search_ in tools/support.py

Tools are Python functions in tools/. Top-level modules use references like calculator.add; nested modules use their full dotted path. See Write Custom Tools.

A wildcard * matches a sequence of characters. billing.* includes every public function in tools/billing.py, while support.search_* includes matching functions. Wildcards also work with API spec tools. Deployment fails if a wildcard matches nothing.

Conditional tools

Use a mapping from tool reference to expression to make a tool available only when the expression is true. A false condition removes the tool for that request.

agents/agent.yaml

# Conditional tools use Python expression syntax.
tools:
  - calculator.add
  - calculator.multiply: context.multiply_allowed
  - web_search: input.search_enabled
  - admin.dangerous_tool: input.role == 'admin' or context.admin
  - premium.tool: input.tier == 'pro' and context.feature_on
  - optional.tool: not context.disabled

Expression Syntax

Python-like syntax: and, or, not; comparisons == != > < >= <=; membership in, not in; parentheses for grouping; string literals in single or double quotes. Reach into nested objects with dot-paths like context.user.role. A bare path like context.active is a truthy check: it passes when the value is set and not empty, zero, or false. Missing fields make the surrounding predicate fail rather than raising.

context.<key>

Values from the run context, including middleware values and runner fields. Nested paths such as context.user.role are supported.

input.<key>

Values from the connector JSON payload. For non-JSON payloads, every input.* check is false.

Set context in middleware

middleware/assistant.py

async def before(content: dict, context: dict) -> dict:
    # Set context values that tool conditions can check.
    payload = context.get("payload", {})
    context["multiply_allowed"] = True
    context["admin"] = payload.get("role") == "admin"
    return content

Validated at deploy time

Invalid expressions fail deployment. A bare accessor such as context.foo is a truthy check.

Discoverable tools

Loading a large tool set into the model context increases token usage and can reduce accuracy. Put infrequently used tools in discoverable_tools so the agent can find them on demand with a natural-language search. The list supports the same strings, wildcards, and conditions as tools.

agents/multi-purpose-assistant.yaml

version: "1.0"

name: multi-purpose-assistant
type: llm
model: gemini/gemini-2.5-pro
description: "Assistant that discovers tools on demand to keep context lean"
system_prompt: |
  You are a multi-purpose assistant with access to many tools.

# Always available in the LLM context
tools:
  - math.calculator.add
  - math.calculator.multiply

# Indexed for on-demand discovery at runtime
discoverable_tools:
  - math.calculator.calculate_tax
  - orders.*
  - social.twitter.post_tweet
  - assistant_tools.*

Discoverable MCP servers

Mark an entire MCP server as discoverable to index its tools instead of loading them up front.

agents/agent.yaml

mcp_servers:
  - name: large-toolset
    url: https://mcp.example.com/tools
    discoverable: true   # tools indexed for search, not loaded upfront

No overlap allowed

A function cannot resolve from both tools and discoverable_tools. Deployment fails when the lists overlap.

Continue configuring your agent

Runtime Controls

See concurrency, session, and defaults behavior

Output Schema

Force structured JSON output

Models & Providers

Choose and configure a supported model

Agent Types

Choose the right agent type for your workflow