> ## Documentation Index
> Fetch the complete documentation index at: https://docs.artaios.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# YAML Configuration

> Learn how to configure your multi-agent systems using YAML

YAML configuration files define your multi-agent system's structure, behavior, and capabilities. This guide covers the complete configuration schema with practical examples.

## Configuration Structure

Every YAML configuration follows this basic structure:

```yaml theme={null}
name: "System Name"
description: "System description"
architecture: "workflow" | "supervisor"
save_messages: true
persistent_state: true
entry_point: "agent_name"

agents:
  - name: "agent_name"
    agent_type: "llm_agent" | "react_agent" | "supervisor"
    # ... agent configuration

# Optional: System-level tool definitions (advanced usage)
tools: []

edges: []
```

## Core Fields

The following sections detail all configuration parameters available in your YAML file.

### System Configuration

These parameters are defined at the root level of your YAML configuration:

```yaml theme={null}
name: "System Name"           # ← System configuration
description: "Description"    # ← parameters are defined
architecture: "workflow"      # ← at the root level
save_messages: true
persistent_state: true
entry_point: "agent_name"
```

**name** `string` *required*

Name of your multi-agent system

**description** `string` *required*

Brief description of what your system does

**architecture** `string` (default: workflow)

Architecture pattern for agent coordination

**Options:**

* `workflow` - Linear or branching agent workflows with explicit edges
* `supervisor` - Multi-agent coordination with a supervisor agent

> [!NOTE]
>
> Additional architecture types (`routing`, `orchestration`, `collaboration`) are defined but not yet implemented.

**recursion\_limit** `integer` (default: 5-50 (env-controlled))

Maximum number of steps allowed in workflow execution to prevent infinite loops. Controlled by environment variables:

* Default: `AGENT_ITERATION_LIMIT` env var (fallback: lower limit)
* Range: `AGENT_ITERATION_LOWER_LIMIT` (default 5) to `AGENT_ITERATION_UPPER_LIMIT` (default 50)

**entry\_point** `string` *required*

Name of the agent that receives the initial user input. Must match an agent name in the `agents` list.

**save\_messages** `boolean` (default: true)

Whether to persist messages in the agent session for conversation history

**persistent\_state** `boolean` (default: true)

Enable checkpointing for state persistence across executions

**variables** `object` (default: \{})

Variable schema for dynamic values updated during execution. Defines variables that can be modified by agents.

**memory\_config** `object`

Global memory system configuration, applied to every agent unless an agent overrides it. Accepts `auto_save`, `auto_save_trigger`, `auto_save_interval`, `num_results`, `llm_model` and `modules`; unrecognised keys fail validation.

`agent`-scoped modules are **not** allowed here — declare those on the agent instead.

```yaml theme={null}
memory_config:
  auto_save: true
  auto_save_trigger: "on_interval_turns"
  auto_save_interval: 3
  num_results: 10
  modules:
    - name: user_prefs
      scope: user
      relevance_prompt: "Extract user preferences and durable facts."
```

See [Memory System](https://docs.artaios.ai/amas/advanced/memory-system.md) for scopes, auto-save triggers and relevance prompts.

## Agent Configuration

Each agent in the `agents` list requires these fields. These parameters are defined within individual agent objects:

```yaml theme={null}
agents:
  - name: "agent_name"         # ← Agent configuration
    agent_type: "llm_agent"    # ← parameters are defined
    description: "..."         # ← within each agent object
    system_prompt: "..."
    # ... additional agent config
```

### Basic Agent Fields

**name** `string` *required*

Unique identifier for the agent within the system

**agent\_type** `string` *required*

Type of agent to instantiate. See [Agent Types](https://docs.artaios.ai/amas/agent_config/types_config/agent-types.md) for available options.

**Common types:**

* `llm_agent` - Basic LLM-powered conversational agent
* `react_agent` - ReAct pattern agent with tool calling
* `supervisor` - Supervisor agent for multi-agent coordination

**description** `string`

Human-readable description of the agent's purpose and capabilities

**dependencies** `array` (default: \[])

List of dependencies on other agents' structured outputs (e.g., `[{"agent": "classifier"}]`)

**outputs** `array` (default: \[])

List of output declarations for this agent

**knowledge\_bases** `array` (default: \[])

List of knowledge base references or configurations accessible to this agent. Both strings and detailed objects are supported.

**memory\_config** `object`

Agent-specific memory configuration, overriding the system-level block. Accepts `modules`, `num_results`, `auto_save`, `auto_save_trigger`, `auto_save_interval` and `relevance_prompt`.

`agent` scope is only valid here, not at the system level. See [Per-Agent Memory](https://docs.artaios.ai/amas/advanced/memory-system.md#per-agent-memory).

### Prompt Configuration

Configure how the agent's prompt is composed. This is nested within each agent's configuration:

```yaml theme={null}
agents:
  - name: "my_agent"
    prompt_config:                        # ← Prompt configuration
      system_prompt: |                    # ← is nested within
        You are a helpful assistant.      # ← each agent
      include_history: true
      include_user_input: true
```

**prompt\_config** `object`

Prompt composition configuration

**Prompt Config Properties**

**system\_prompt** `string`

Instructions that define the agent's behavior, personality, and capabilities. Supports multi-line strings with `|` syntax. Positioned first in the message sequence for maximum LLM attention.

**include\_history** `boolean | integer` (default: true)

Whether and how much conversation history to include.

* `true` — include all history
* `false` — include no history
* Positive integer (e.g., `5`) — include only the last N messages

**include\_user\_input** `boolean` (default: true)

Whether to include the current user message in the prompt. Set to `false` to exclude the latest user message.

**include\_media\_in\_history** `boolean` (default: false)

Whether to include media content (images, PDFs, files) from historical messages. Current user input media is always included regardless.

**include\_internal\_messages** `boolean` (default: true)

Whether to include internal agent messages (from agents with `show_output_to_user: false`) in history.

**few\_shot\_examples** `array` (default: \[])

Teaching examples positioned after the system prompt. Each example must have `input` and `output` keys.

```yaml theme={null}
few_shot_examples:
  - input: "What is 2+2?"
    output: "2+2 equals 4"
```

> [!NOTE]
>
> The `system_prompt` field must be placed inside `prompt_config`, not at the agent level. While some examples may show `system_prompt` at the agent level for brevity, the correct location is `prompt_config.system_prompt`.

### LLM Configuration

Configure the language model for your agents. This is nested within each agent's configuration:

```yaml theme={null}
agents:
  - name: "my_agent"
    llm_config:              # ← LLM configuration
      model: "gpt-4o"        # ← is nested within
      temperature: 0.7       # ← each agent
      max_tokens: 1000
```

**llm\_config** `object`

Configuration for the language model

**LLM Config Properties**

**model** `string`

Model identifier. If not specified, the default model from environment variables is used. Both display names and internal model names are accepted (e.g., `gpt-4o`, `mistral-medium`).

**temperature** `number` (default: 0.7)

Controls randomness in responses (0.0 = deterministic, 2.0 = very random)

Range: 0.0 - 2.0

**max\_tokens** `integer`

Maximum number of tokens to generate in responses. If not set, uses the provider's default.

**api\_key** `string`

Optional API key override. If provided, this key is used instead of the environment variable for this agent's LLM provider.

### Streaming Configuration

Control real-time event streaming for each agent. This is nested within each agent's configuration:

```yaml theme={null}
agents:
  - name: "my_agent"
    streaming_config:              # ← Streaming configuration
      enable_streaming: true       # ← is nested within
      show_output_to_user: true    # ← each agent
      show_tool_to_user: true
```

**streaming\_config** `object`

Controls real-time event streaming behavior

**Streaming Config Properties**

**enable\_streaming** `boolean` (default: true)

Enable streaming of agent responses

**show\_output\_to\_user** `boolean` (default: true)

Show agent text output to end users in real-time. When `false`, agent output goes to internal messages (invisible to end user but available to other agents).

**show\_tool\_to\_user** `boolean` (default: true)

Show tool calling events to end users

**show\_reasoning** `boolean` (default: false)

Show agent reasoning/thinking process to end users (for models that support thinking mode)

**show\_memory** `boolean` (default: true)

Show memory query events to end users

**send\_preview\_snippet** `boolean` (default: false)

Generate and send an agent introduction snippet before processing the query

**main\_chatbox** `boolean` (default: false)

Identifies this agent as the main chatbox agent (UI hint for frontend rendering)

### Structured Output

Agents can be configured to produce structured data (JSON) matching a specific schema instead of unstructured text. This uses BAML under the hood for reliable extraction.

```yaml theme={null}
agents:
  - name: "classifier"
    agent_type: "llm_agent"
    structured_output:                # ← Structured output config
      enabled: true
      schema:
        category:
          type: "str"
          description: "The primary issue category"
        confidence:
          type: "float"
          description: "Confidence score 0.0 to 1.0"
```

**structured\_output** `object`

Configuration for structured output generation.

**Structured Output Properties**

**enabled** `boolean` (default: true)

Whether to enable structured output generation for this agent.

**schema** `object`

Dictionary mapping field names to their definitions. Each field definition must include a `type` (e.g., `"str"`, `"int"`, `"list[str]"`) and can optionally include a `description`. See [Type Notation](https://docs.artaios.ai/amas/advanced/type-notation.md) for every accepted type string.

The reserved key `__root__`, used alone, makes the agent return a bare value (typically a list) instead of an object.

Returning a bare list instead of an object:

```yaml theme={null}
agents:
  - name: "topic_extractor"
    agent_type: "llm_agent"
    structured_output:
      schema:
        __root__:                     # ← must be the only key
          type: "list[str]"
          description: "Key topics, most significant first"
```

> [!WARNING]
>
> Any field can return `null` regardless of its declared type — every field is optional at the schema-building layer so a missing value cannot crash the run. Handle absent values downstream, and note that a `null` is silently skipped rather than written into a non-nullable variable.

> **[Structured Output](https://docs.artaios.ai/amas/advanced/structured-output.md)**
>
> Root schemas, nested fields, multi-agent data passing and error handling

### Variable Assignments

Map agent outputs (either structured output fields or raw text) to system variables. This allows sharing data between agents across the workflow.

```yaml theme={null}
agents:
  - name: "classifier"
    agent_type: "llm_agent"
    structured_output:
      enabled: true
      schema:
        category: { type: "str" }
    
    variable_assignments:             # ← Map output to variables
      user_category: "classifier.output.category"
      last_response: "classifier.output"
      max_retries: 3                  # Static assignment
```

**variable\_assignments** `object`

Dictionary mapping system variable names to their values. Values can be:

* References to structured output fields (e.g., `"agent_name.output.field_name"`)
* References to raw agent text (e.g., `"agent_name.output"`)
* Static values (e.g., `10`, `"fixed_string"`)

### Tool Configuration

Tools can be configured at two levels. Choose the approach that best fits your use case:

***

#### **Agent-Level Tools (Recommended)**

Configure tools directly within each agent's configuration:

```yaml theme={null}
agents:
  - name: "my_agent"
    agent_type: "react_agent"
    tools:                    # ← Agent-level tools
      - "tavily_search"       # ← are defined within
      - "calculator"          # ← each agent object
```

**agents\[].tools** `array`

List of tool identifiers for this agent. **Only applicable for `react_agent` type.**

Example tools: `tavily_search`, `tavily_extract`, `calculator`

```yaml theme={null}
agents:
  - name: "my_agent"
    agent_type: "react_agent"
    tools:
      - "tavily_search"
      - "calculator"
```

#### **Tool Objects (per-tool options)**

An entry can be an object instead of a bare string when a tool needs its own options — `config` for tool-specific settings, `hitl_config` for human approval:

```yaml theme={null}
persistent_state: true          # ← required when any tool uses HITL

agents:
  - name: "my_agent"
    agent_type: "react_agent"
    tools:
      - "tavily_search"                   # string form
      - name: "mail_send_email"           # object form
        tool_type: "mail_send_email"
        hitl_config:
          requires_human_approval: true
          confirmation_prompt: "Send this email?"
```

**agents\[].tools\[].name** `string` *required*

Instance name for this tool. Use the registry identifier unless you need to distinguish two instances of the same tool.

**agents\[].tools\[].tool\_type** `string` *required*

The registry identifier of the tool.

**agents\[].tools\[].enabled** `boolean` (default: true)

Set to `false` to keep the entry but withhold the tool from the agent.

**agents\[].tools\[].config** `object`

Tool-specific configuration. Validated against the tool's own config class — tools declared `NON_CONFIG` reject a non-empty `config`, and tools declared `CONFIG_REQUIRED` reject an empty one.

**agents\[].tools\[].hitl\_config** `object`

Human-in-the-Loop settings for this tool instance: `requires_human_approval`, `mandate_human_approval`, `disable_human_approval`, `confirmation_prompt`. Requires `persistent_state: true` when a gate ends up active. See [Human-in-the-Loop](https://docs.artaios.ai/amas/agent_config/human-in-the-loop.md).

#### **System-Level Tools (Advanced)**

Define tools at the root level for reuse across multiple agents:

```yaml theme={null}
tools: []                     # ← System-level tools
                              # ← are defined at root level
agents:
  - name: "agent1"
    # ... agent config
```

**tools** `array`

Optional system-level tool definitions. This is for advanced configurations where you want to define tool configurations once and reference them across multiple agents.

> [!NOTE]
>
> Most users should configure tools at the agent level. System-level tools are for advanced use cases.

#### **Tool Calling Behavior**

The ReAct agent's iteration limit is configured directly on the agent, not in a nested `tool_calling` object:

```yaml theme={null}
agents:
  - name: "my_agent"
    agent_type: "react_agent"
    max_iterations: 10        # ← Maximum ReAct loop iterations
    tools:
      - "tavily_search"
```

**max\_iterations** `integer` (default: 10)

Maximum number of ReAct reasoning-action-observation cycles. Only applicable for `react_agent` type. Prevents infinite tool calling loops.

> [!NOTE]
>
> There is no `tool_calling` configuration object. Tool calling is always enabled for `react_agent` agents when tools are provided. Use `max_iterations` at the agent level to control the iteration limit.

### Supervisor Configuration

**For supervisor agents only.** These parameters are configured within the supervisor agent's configuration object:

```yaml theme={null}
agents:
  - name: "supervisor"
    agent_type: "supervisor"
    supervised_agents: [...]      # ← Supervisor-specific
    return_to_supervisor: true    # ← parameters are defined
    max_handoffs: 10              # ← within the supervisor agent
    prompt_config:
      system_prompt: "..."        # ← Custom supervisor instructions
```

**supervised\_agents** `array` *required*

**Required for supervisor agents.** List of agent names that this supervisor coordinates. Must contain at least one agent.

```yaml theme={null}
agents:
  - name: "supervisor"
    agent_type: "supervisor"
    supervised_agents: ["agent1", "agent2"]
```

**return\_to\_supervisor** `boolean` (default: true)

Whether worker agents should return control to the supervisor after completing their tasks. Set to `false` for simple one-way delegation where workers respond directly to the user.

**max\_handoffs** `integer` (default: 10)

Maximum number of agent handoffs to prevent infinite coordination loops

**tools** `array` (default: \[])

Additional tools for the supervisor agent (the handoff tool is automatically injected)

> [!NOTE]
>
> Supervisor agents use `prompt_config.system_prompt` for their coordination instructions. There is no separate `supervisor_prompt` field. The system prompt is injected into a template that adds routing and evaluation logic around your custom instructions.

## Workflow Edges

**For `workflow` architecture only.** Define edges at the root level to connect agents in your workflow:

```yaml theme={null}
# Root-level configuration
architecture: "workflow"

edges:                        # ← Edges are defined
  # Static edge                # ← at the root level
  - from: "__start__"
    to: "first_agent"
  
  # Dynamic edge (conditional)
  - from: "first_agent"
    condition: "Route based on category: {{ first_agent.output.category }}"
    condition_type: "literal"
    possible_outputs: ["second_agent", "third_agent"]
    llm_model: "gpt-4o"       # ← Optional evaluation model
  
  # Final static edges
  - from: "second_agent"
    to: "__end__"
  - from: "third_agent"
    to: "__end__"
```

**Special nodes:**

* `__start__` or `START` - Entry point of the workflow
* `__end__` or `END` - Exit point of the workflow

> [!NOTE]
>
> Dynamic edges can use the `llm_model` parameter to specify an evaluation model compatible with BAML (e.g. `google_gemini`, `azure_openai`, `mistral`, `telekom_otc`). If omitted, the system default is used.

> [!NOTE]
>
> Supervisor architecture does not require explicit edges - the supervisor handles routing dynamically.

## Complete Examples

### Basic Conversational Agent

```yaml theme={null}
name: "Basic LLM Agent"
description: "Simple conversational assistant"
save_messages: true
persistent_state: true

agents:
  - name: "assistant"
    agent_type: "llm_agent"
    description: "A helpful AI assistant"
    prompt_config:
      system_prompt: "You are a helpful AI assistant."
    llm_config:
      temperature: 0.7
      max_tokens: 500
    streaming_config:
      show_output_to_user: true

edges:
  - from: "__start__"
    to: "assistant"
  - from: "assistant"
    to: "__end__"

entry_point: "assistant"
```

### Tool-Enabled Agent

```yaml theme={null}
name: "Tool-Enabled Assistant"
description: "AI assistant with calculator, web search, and database tools"
architecture: "workflow"
save_messages: true
persistent_state: true

agents:
  - name: "tool_agent"
    agent_type: "react_agent"
    description: "AI assistant with tool calling capabilities"
    
    prompt_config:
      system_prompt: |
        You are a helpful AI assistant with access to various tools.
        When you need to use a tool, think step by step about what information you need.
    
    tools:
      - "tavily_search"
      - "tavily_extract"
      - "calculator"
    
    max_iterations: 10
    
    llm_config:
      temperature: 0.1
      max_tokens: 2000
    
    streaming_config:
      enable_streaming: true
      show_output_to_user: true

edges:
  - from: "START"
    to: "tool_agent"
  - from: "tool_agent" 
    to: "END"

entry_point: "tool_agent"
```

### Supervisor Multi-Agent System

```yaml theme={null}
name: "Research Team Supervisor"
description: "Complete supervisor architecture with research, analysis, and synthesis agents"
architecture: "supervisor"
save_messages: true
persistent_state: true

agents:
  # Supervisor Agent
  - name: "research_supervisor"
    agent_type: "supervisor"
    description: "Intelligent supervisor coordinating research team specialists"
    supervised_agents: ["research_agent", "analysis_agent", "synthesis_agent"]
    return_to_supervisor: true
    max_handoffs: 15
    
    streaming_config:
      enable_streaming: true
      show_output_to_user: true

    prompt_config:
      system_prompt: |
        You are a research team supervisor coordinating specialized agents.

        Your team consists of:
        - research_agent: Expert at web search and information gathering
        - analysis_agent: Specialist in data analysis and pattern recognition
        - synthesis_agent: Expert at summarizing findings

        For ANY user request, immediately delegate to the appropriate agent.
        Always provide clear reasoning when transferring.

  # Research Agent
  - name: "research_agent"
    agent_type: "react_agent"
    description: "Specialized in research and information gathering"
    
    tools:
      - "tavily_search"
      - "tavily_extract"
    
    max_iterations: 5
    
    streaming_config:
      show_output_to_user: true
      show_reasoning: true
    
    prompt_config:
      system_prompt: |
        You are a Research Specialist in a multi-agent team.
        
        Your expertise includes:
        - Web search and information gathering
        - Fact-checking and source verification
        - Identifying reliable sources
        
        Always provide detailed, well-sourced research results.

  # Analysis Agent
  - name: "analysis_agent"
    agent_type: "react_agent"
    description: "Specialized in data analysis and pattern recognition"
    
    tools:
      - "calculator"
    
    max_iterations: 3
    
    streaming_config:
      show_output_to_user: true
    
    prompt_config:
      system_prompt: |
        You are an Analysis Specialist in a multi-agent team.
        
        Your expertise includes:
        - Data analysis and statistical processing
        - Pattern recognition and trend identification
        - Insight generation from complex information
        
        Focus on extracting meaningful insights.

  # Synthesis Agent
  - name: "synthesis_agent"
    agent_type: "llm_agent"
    description: "Specialized in synthesizing information"
    
    streaming_config:
      show_output_to_user: true
    
    prompt_config:
      system_prompt: |
        You are a Synthesis Specialist in a multi-agent team.
        
        Your expertise includes:
        - Combining research and analysis into coherent narratives
        - Creating well-structured, comprehensive reports
        - Ensuring completeness and coherence
        
        Create comprehensive, well-organized final responses.

entry_point: "research_supervisor"
```

## Best Practices

> [!TIP]
>
> **System Prompts**: Use multi-line strings with `|` for better readability of complex prompts.

> [!TIP]
>
> **Temperature Settings**: Use lower temperatures (0.1-0.3) for factual tasks and higher (0.7-1.0) for creative tasks.

> [!WARNING]
>
> **Entry Point**: Always ensure your `entry_point` matches an existing agent name, or the system will fail to initialize.

> [!TIP]
>
> **Supervisor Coordination**: When using `return_to_supervisor: true`, the supervisor can evaluate worker outputs and decide on next steps. Set to `false` for simpler one-way delegation.

## Validation

The system automatically validates your configuration:

* **Required fields** are checked
* **Agent types** are verified against the registry
* **Entry point** must reference an existing agent
* **Supervised agents** must exist in the agents list
* **Edges** must reference valid agent names

Validation errors will be returned with specific field-level details to help you fix issues quickly.

## Next Steps

> **[Agent Types](https://docs.artaios.ai/amas/agent_config/types_config/agent-types.md)**
>
> Learn about available agent types and when to use each

> **[Agent Capabilities](https://docs.artaios.ai/amas/agent_config/agent-capabilities.md)**
>
> Explore tools, streaming, and other agent capabilities


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.