Build

Agent YAML

Agent YAML fields, plus the syntax for prompts, tools, and conditional configuration.

Last updated August 20, 2026

On this page

Configuration fields

Field	Type	Status	Description
version	string	Required	Configuration schema version. Must be '1.0'.
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 model request fails before returning output.
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	Use `auto` for model-managed behavior. Supported overrides vary by model; see the Connic model catalog or your BYOK provider's documentation.Default: `auto`
reasoning_budget	integer	Optional	Raw reasoning-token budget for models that accept an explicit budget. Use reasoning_effort for models with named effort levels.
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	Maximum attempts for the model being retried or for a non-LLM operation, including the first. With a fallback, the primary is tried once and this budget applies to the fallback. 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 generated backoff in seconds. Provider Retry-After values remain subject to the overall timeout. 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/. Constrains LLM output to the schema. See Output Schema.
database	object	Optional	Database tool access controls. Omit for unrestricted database access.
collections	string[] \| object	Optional	Restrict access to named collections. The mapping form supports per-collection prevent_delete and prevent_write overrides.
prevent_delete	boolean	Optional	Block db_delete. A collection override can replace this value.Default: `false`
prevent_write	boolean	Optional	Block db_insert, db_update, and db_upsert. A collection override can replace this value.Default: `false`
retrieval	object	Optional	Retrieval tool access controls. Omit for unrestricted retrieval access.
namespaces	string[] \| object	Optional	Restrict access to named namespaces. The mapping form supports per-namespace prevent_delete and prevent_write overrides.
prevent_delete	boolean	Optional	Block retrieval_delete. A namespace override can replace this value.Default: `false`
prevent_write	boolean	Optional	Block retrieval_store. A namespace override can replace this value.Default: `false`
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`
bridge	string	Optional	Bridge ID for routing to a private server. Supports `${VAR}` interpolation.
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.

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 Connic-provided run metadata. 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

Expression validation

Deployment rejects invalid Python expression syntax. At run time, unsupported expression forms and unknown roots evaluate to false. 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: connic/gpt-5.6-terra
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

Constrain output with a JSON schema

Models & Providers

Choose and configure a supported model

Agent Types

Choose the right agent type for your workflow