Build

Agent YAML

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

Last updated October 2, 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	Model used after a failed primary request, while time remains and no output from that request has been delivered. Configured context repair runs first. See fallback behavior.
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, including generated `approval.inputs` tools. MCP server tools and `discoverable_tools` do not count.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 the BYOK provider 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	Controls attempts, request timeouts, and backoff for all LLM request failures without replaying the agent. Tool and sequential agents retain operation-level retries.
attempts	integer	Optional	Maximum normal attempts, including the first. Without fallback, the primary gets this budget. With fallback, the primary gets one attempt and the fallback gets this budget. Context repair can add one same-model request per logical call. For non-LLM agents, the budget applies to the operation. Range: 1–10.Default: `3`
attempt_timeout	number	Optional	Positive, finite time limit in seconds for each LLM completion or whole stream, capped by the run’s remaining time. Incoming chunks do not reset it. Retries share the original run deadline.Default: `120`
initial_delay	number	Optional	Initial generated backoff in seconds. Same-model LLM retries use exponential backoff with equal jitter unless the provider sends a valid Retry-After. Switching to fallback is immediate.Default: `10`
max_delay	number	Optional	Maximum generated backoff in seconds. A valid Retry-After overrides generated backoff; all waits remain bounded by the run deadline. 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`
files	object	Optional	File tool access controls. Omit for access to the whole file tree. See File Tools.
folders	string[] \| object	Optional	Restrict access to these folders and everything below them. The mapping form supports per-folder prevent_delete, prevent_write, and session_only overrides.
prevent_delete	boolean	Optional	Block file_delete. A folder override can replace this value.Default: `false`
prevent_write	boolean	Optional	Block file_write and file_update. A folder override can replace this value.Default: `false`
session_only	boolean	Optional	Show the agent only files written in its current session. Requires session. A folder 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.
condition	string	Optional	Connect the server only when this expression is true for the run. Uses the conditional tools grammar.
optional	boolean	Optional	Continue the run without this server when connecting or listing its tools fails. See Conditional and Optional Servers.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; coalesce keeps one waiting run per key and replaces it with newer events.Default: `queue`
approval	object	Optional	Human approvals and input tools. See Approvals.
tools	list	Optional	Existing tool references that require a yes/no decision. A mapping value can condition approval with param.* and context.* expressions.Default: `[]`
inputs	list	Optional	LLM agents only. One-key mappings from an ASCII identifier of at most 64 characters, such as get_mfa, to prompt, label, and optional params and sensitive. Names must be unique, cannot use reserved tool-discovery names, and cannot collide with tools, discoverable_tools, or approval.tools. connic creates each tool automatically; generated input tools count toward the 100-tool agent limit.Default: `[]`
prompt	string	Required	Nonblank tool description shown to the agent, explaining when to request human input.
params	list	Optional	One-key mappings from unique ASCII identifiers to str, int, float, or bool. Python keywords and context are not allowed as names. The agent must supply every declared parameter; extra arguments are rejected. Values appear as context above the human input field. Omit for a tool with no arguments.Default: `[]`
label	string	Required	Nonblank label of at most 200 characters shown above the human input field.
sensitive	boolean	Optional	Mask the input and protect stored response data. The model still receives the tool result; see Approvals for the protection scope.Default: `false`
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	boolean \| object \| null	Optional	Set true for one shared session across the agent’s runs, or use an object to configure it. False, null, or omission disables sessions. See Persistent Sessions.
key	string \| null	Optional	Optional context.* or input.* path that resolves the session ID. Omit or set null to share one session across the agent’s runs.
ttl	integer \| null	Optional	Session expiry after this many inactive seconds. Minimum 60; omitted or null means no expiry.Default: `null`
history	boolean	Optional	Retain conversation history across runs. False starts each run with fresh chat history.Default: `true`
browser	boolean	Optional	Retain browser cookies and local storage across runs. False keeps browser tools available with fresh browser state.Default: `true`
context_compression	object	Optional	Shortens long LLM conversation history. Context-window errors trigger compression before fallback and allow one extra request to the same model. See context repair limits. 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`
voice_config	object	Optional	Enable native realtime audio for an LLM agent, using its model, prompt, and tools. See Voice configuration.
voice	string	Optional	Voice ID accepted by the selected provider. Omit to use its default voice.
language	string	Optional	Preferred spoken language, such as en or de-DE. Added to the model instructions and used as a transcription hint where supported; it does not force recognition into that language.
transcription_model	string	Optional	OpenAI model name for transcribing user speech, or an existing transcription deployment name in the same Azure resource. Omit to disable user transcription for OpenAI and Azure. Gemini and Vertex AI use native transcription without this setting.
greeting	string	Optional	Opening greeting requested from the model. Omit to let the user speak first.
thinking_sound	boolean	Optional	Play a quiet repeating tone during tool waits or provider-reported background work. Pauses while the user or agent speaks.Default: `true`
hang_up_allowed	boolean	Optional	Allow the agent to end the conversation itself. A spoken farewell plays in full before the conversation ends. Set false to disable this ability.Default: `true`
turn_detection	object	Optional	Control detection of when the user has finished speaking.
silence_ms	integer	Optional	Silence duration in milliseconds before ending the user's turn. Must be greater than zero. Omit to use the provider default.
interruptions	object	Optional	Control whether user speech interrupts the spoken response. Interruptions are enabled when this object is omitted.
enabled	boolean	Required	Whether the user can interrupt the agent. Required when interruptions is present.
idle_timeout_seconds	integer	Optional	End the voice session after this many seconds of conversational inactivity. Tool execution and provider-reported background work keep the session active. Must be greater than zero. Omit for no voice-specific idle timeout; the run timeout still applies.
keypad	object	Optional	Map keypad keys (0-9, *, #) to tools listed in tools. A key press runs its tool without a model turn; the tool cannot have required parameters.

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. A wildcard without a dot matches predefined tool names; for example, db_* includes every predefined database tool. 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. The search matches the words of the agent’s query against tool names and descriptions, so write descriptions in the language the agent works in. Finding a tool takes an extra model step before the call, so keep frequently used tools in 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 the agent

Runtime ControlsSee concurrency, session, and defaults behavior Output SchemaConstrain output with a JSON schema Models & ProvidersChoose and configure a supported model Agent TypesChoose the right agent type for the workflow