Chapter 18: Full Reference — Every Field at a Glance¶
← Back to Table of Contents | ← Previous: The Loading Pipeline
Root Config¶
version: "1" # Optional, defaults to "1"
vars: {} # Variable definitions (removed after interpolation)
models: {} # Named model definitions
agents: {} # Named agent definitions (required: at least one)
orchestrations: {} # Named orchestration definitions
mcp_servers: {} # Named MCP server definitions
mcp_clients: {} # Named MCP client connections
session_manager: {} # Global session manager
history: false # Default for per-agent history when an agent omits history:
attachments: {} # Global reference/attachment policy (AttachmentsDef)
runtime: {} # Runtime behavior toggles (RuntimeDef)
telemetry: {} # OpenTelemetry export (TelemetryDef), off by default
entry: "name" # Required: entry point agent or orchestration
log_level: "WARNING" # Optional: DEBUG, INFO, WARNING, ERROR
# Top-level keys beginning x- are stripped before validation, like vars,
# which is what makes them usable as YAML anchor scratch pads.
ModelDef¶
models:
name:
provider: bedrock | openai | ollama | gemini | module.path:CustomModel
model_id: "model-identifier"
params: {} # Provider-specific kwargs. For bedrock, client_config:
# {read_timeout, connect_timeout, retries: {max_attempts, mode}}
# sets the boto client (Chapter 2)
thinking: null # bedrock only: false | true | {effort, display}, the
# default for every agent on this model (Chapter 2)
AgentDef¶
agents:
name:
type: null # Custom factory: module.path:factory_func
agent_kwargs: {} # Extra kwargs for Agent() or custom factory
model: "model_name" # String ref to models: or inline ModelDef
thinking: null # false | true | {effort, display}, laid over
# the model's thinking: (Chapter 2)
system_prompt: "..." # System prompt string
description: "..." # Agent description (used in orchestration tools)
tools: [] # List of tool spec strings
hooks: [] # List of HookDef objects or import path strings
mcp: [] # List of MCP client names
tool_labels: {} # Tool name -> display label mapping
conversation_manager: null # ConversationManagerDef
session_manager: null # Per-agent SessionManagerDef (overrides global);
# ~ opts this agent out of the global one
stream: null # {group, title} — how this agent's output is
# labelled in the event stream (Chapter 15)
interrupt: null # InterruptDef (below), or true for the defaults:
# {tools: [], ask_user: true}
history: null # true/false, or a HistoryDef (below); falls back
# to the root history: default
context: null # ContextDef (below): what the model is sent
attachments: null # none | reference | inline | bool | {enabled, inline}
output_schema: null # Import path to a Pydantic model the agent must
# return (module.path:Model)
InterruptDef¶
agents:
name:
interrupt:
tools: [] # Tools that wait for the person's approval before
# running: names, fnmatch globs, or objects:
# {name, remember: once | thread | always,
# subject: module.path:fn}
skip_read_only: false # Let tools annotated readOnlyHint: true run
remember: once # Widest decision a person may make:
# once | thread | always
ask_user: true # Grant the built-in multiple-choice ask_user
ttl_seconds: null # Approval deadline (metadata.expiresAt), enforced
# by the agent; null waits indefinitely
tool_approvals: false # Let tools ask for approval themselves with a
# kaboo_approval reply
Scopes wider than once are offered only when the host remembers decisions
(forwardedProps.kaboo_grants). See
Human-in-the-loop, and
Tools that enforce their own approvals
for tool_approvals.
HistoryDef¶
agents:
name:
history:
enabled: true # Remember across turns of the conversation
group: null # Shared transcript bucket (default: the agent's path)
keep: full # full | masked — masked writes back each finished
# call without its tool results or reasoning
summarize_over: null # Tokens; with keep: masked, summarise the oldest
# calls once the written-back memory passes this
summarize_model: null # A name under models:; required with summarize_over
A delegate orchestration's forked agent remembers exactly as its entry_name
agent's history: says. See Multi-turn history.
ContextDef¶
agents:
name:
context:
clear_tool_results: # Off when absent (Chapter 8)
trigger: 60000 # Required: estimated input tokens
keep_last: 3 # Most recent turns whose results always stay (>= 1)
min_chars: 1500 # Shorter results always stay
keep_tools: [] # Tools whose results always stay
AttachmentsDef¶
attachments:
default: reference | none # Baseline for agents without their own attachments:
tool: true # Expose list_references / fetch_attachment tools
base_url: null # Origin for the host's own attachment routes
authorization: null # forwarded_props:<key> | env:<VAR> (own-origin only)
content_url_template: null # e.g. /attachments/{id}/content — upgrades
# attachment-kind object refs to fetchable transport
Per-agent override on AgentDef.attachments (shorthands normalize to {enabled, inline}):
agents:
vision:
attachments: inline # manifest + inline media (ContentBlocks)
researcher:
attachments: reference # manifest only (inherits if omitted)
writer:
attachments: none # excluded from references
RuntimeDef¶
runtime:
persist_session_state: true # Carry pending interrupts on the AG-UI state
# channel, so an approval survives a restart
# (Chapter 7). Disable only when the AG-UI
# endpoint is exposed straight to a browser.
allow_invocation_overrides: false # DEPRECATED — apply forwardedProps.agent_config
# (system_prompt / model_id) per invocation.
# Submit a config instead (Chapter 13).
TelemetryDef¶
telemetry:
enabled: false # Opt in; KABOO_TELEMETRY_ENABLED overrides
service_name: kaboo-workflows # OTel service name
console: false # Also export spans to stdout
sample_ratio: 1.0 # 0.0-1.0
trace_attributes: {} # Static attributes on every span
otlp:
endpoint: null # Falls back to KABOO_OTLP_ENDPOINT / OTEL_*
headers: null # Falls back to KABOO_OTLP_HEADERS / OTEL_*
Telemetry is initialised once per process, first call wins, so it is not something a per-run submitted config can change.
HookDef¶
hooks:
# Inline object form
- type: module.path:ClassName # or ./file.py:ClassName
params: {} # Constructor kwargs
# String shorthand (no params)
- module.path:ClassName
SessionManagerDef¶
session_manager:
provider: file | s3 | agentcore # Built-in provider name
type: null # Custom class: module.path:ClassName (overrides provider)
params: {} # Constructor kwargs (session_id, storage_dir, etc.)
ConversationManagerDef¶
conversation_manager:
type: strands.agent:SlidingWindowConversationManager
params: {} # Constructor kwargs (window_size, etc.)
MCPServerDef¶
mcp_servers:
name:
type: ./server.py:create # Factory function: module.path:func or ./file.py:func
params: {} # Forwarded to factory (port, host, etc.)
MCPClientDef¶
mcp_clients:
name:
# Exactly one of:
server: "server_name" # Reference to mcp_servers entry
url: "https://..." # External MCP server URL
command: ["cmd", "arg"] # Stdio subprocess command
transport: null # Override: "streamable-http" | "sse" | "stdio"
params: {} # Forwarded to strands MCPClient
# (prefix, startup_timeout, tool_filters)
transport_options: {} # Transport-specific options. Declare once per
# client — a second block silently replaces it.
tool_labels: {} # Tool name -> display label (agent labels win)
auth: null # Outbound auth; "relay" shorthand expands to the
# block below. Not valid with command:.
MCPClientAuthDef¶
auth:
type: relay | m2m | static
params:
header: Authorization # One name, or a list to send the token twice
scheme: Bearer # "" sends the raw value
# relay: token
# static: token (required)
# m2m: token_url, client_id, client_secret, scope, audience, extra
relay resolves the caller's identity from the request context, so it only
works when clients are resolved per run. See Chapter 9.
DelegateOrchestrationDef¶
orchestrations:
name:
mode: delegate
entry_name: "agent_name" # Agent blueprint to fork
connections:
- agent: "target_name" # Agent or orchestration name
description: "..." # Tool description for LLM
session_manager: null # Override session manager
hooks: [] # Additional hooks
agent_kwargs: {} # Override agent kwargs (merged)
SwarmOrchestrationDef¶
orchestrations:
name:
mode: swarm
agents: [agent1, agent2] # Participating agents
entry_name: "agent1" # Starting agent
chat_output: null # Member agent whose text becomes the reply
max_handoffs: 20 # Max handoffs
max_iterations: 20 # Max iterations
execution_timeout: 900.0 # Total timeout (seconds)
node_timeout: 300.0 # Per-agent timeout (seconds)
session_manager: null # Swarm-level session manager
hooks: [] # Swarm-level hooks
GraphOrchestrationDef¶
orchestrations:
name:
mode: graph
entry_name: "start_node" # Node with no incoming edges
chat_output: null # Node whose text becomes the reply
edges:
- from: "node_a"
to: "node_b"
condition: null # Optional: ./file.py:func or module:func
max_node_executions: null # Safety cap for loops
execution_timeout: null # Total timeout (seconds)
node_timeout: null # Per-node timeout (seconds)
reset_on_revisit: false # Reset agent state on revisit
session_manager: null # Graph-level session manager
hooks: [] # Graph-level hooks
create_agui_app¶
create_agui_app(
config_path, # Base config. With session_config_key set, the
# layer every submitted config merges over.
endpoint="/invocations",
ping_path="/ping",
cors_origins=None, # Defaults to ["*"]
cors_allow_credentials=True,
auth=None, # Inbound verifier -> Principal (raise to reject)
session_config_key=None, # forwardedProps key carrying this run's config.
# None serves config_path alone.
allowed_mcp_hosts=None, # Hosts a submitted mcp_client URL may point at
)
session_config_key changes the shape of the service, not just a setting: each run gets its own agents, orchestration, entry and MCP client sessions, released when its stream ends. See Chapter 13 for the merge rules and Chapter 17 for the pipeline.
Next: Chapter 19 — Attachments & Multimodal →
Bonus: Quick Recipes →