> ## 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"
```

<ParamField path="name" type="string" required>
  Name of your multi-agent system
</ParamField>

<ParamField path="description" type="string" required>
  Brief description of what your system does
</ParamField>

<ParamField path="architecture" type="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.
  </Note>
</ParamField>

<ParamField path="recursion_limit" type="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)
</ParamField>

<ParamField path="entry_point" type="string" required>
  Name of the agent that receives the initial user input. Must match an agent name in the `agents` list.
</ParamField>

<ParamField path="save_messages" type="boolean" default="true">
  Whether to persist messages in the agent session for conversation history
</ParamField>

<ParamField path="persistent_state" type="boolean" default="true">
  Enable checkpointing for state persistence across executions
</ParamField>

<ParamField path="variables" type="object" default="{}">
  Variable schema for dynamic values updated during execution. Defines variables that can be modified by agents.
</ParamField>

<ParamField path="memory_config" type="object">
  Global memory system configuration (applies to all agents unless overridden). Note that `agent` scoped modules are not allowed at the system level.
</ParamField>

## 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

<ParamField path="name" type="string" required>
  Unique identifier for the agent within the system
</ParamField>

<ParamField path="agent_type" type="string" required>
  Type of agent to instantiate. See [Agent Types](/documentation/agent-types) 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
</ParamField>

<ParamField path="description" type="string">
  Human-readable description of the agent's purpose and capabilities
</ParamField>

<ParamField path="dependencies" type="array" default="[]">
  List of dependencies on other agents' structured outputs (e.g., `[{"agent": "classifier"}]`)
</ParamField>

<ParamField path="outputs" type="array" default="[]">
  List of output declarations for this agent
</ParamField>

<ParamField path="knowledge_bases" type="array" default="[]">
  List of knowledge base references or configurations accessible to this agent. Both strings and detailed objects are supported.
</ParamField>

<ParamField path="memory_config" type="object">
  Agent-specific memory configuration (overrides system-level memory config)
</ParamField>

### 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
```

<ParamField path="prompt_config" type="object">
  Prompt composition configuration

  <Expandable title="Prompt Config Properties">
    <ParamField path="system_prompt" type="string" default="">
      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.
    </ParamField>

    <ParamField path="include_history" type="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
    </ParamField>

    <ParamField path="include_user_input" type="boolean" default="true">
      Whether to include the current user message in the prompt. Set to `false` to exclude the latest user message.
    </ParamField>

    <ParamField path="include_media_in_history" type="boolean" default="false">
      Whether to include media content (images, PDFs, files) from historical messages. Current user input media is always included regardless.
    </ParamField>

    <ParamField path="include_internal_messages" type="boolean" default="true">
      Whether to include internal agent messages (from agents with `show_output_to_user: false`) in history.
    </ParamField>

    <ParamField path="few_shot_examples" type="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"
      ```
    </ParamField>
  </Expandable>
</ParamField>

<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`.
</Note>

### 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
```

<ParamField path="llm_config" type="object">
  Configuration for the language model

  <Expandable title="LLM Config Properties">
    <ParamField path="model" type="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`).
    </ParamField>

    <ParamField path="temperature" type="number" default="0.7">
      Controls randomness in responses (0.0 = deterministic, 2.0 = very random)

      Range: 0.0 - 2.0
    </ParamField>

    <ParamField path="max_tokens" type="integer">
      Maximum number of tokens to generate in responses. If not set, uses the provider's default.
    </ParamField>

    <ParamField path="api_key" type="string">
      Optional API key override. If provided, this key is used instead of the environment variable for this agent's LLM provider.
    </ParamField>
  </Expandable>
</ParamField>

### 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
```

<ParamField path="streaming_config" type="object">
  Controls real-time event streaming behavior

  <Expandable title="Streaming Config Properties">
    <ParamField path="enable_streaming" type="boolean" default="true">
      Enable streaming of agent responses
    </ParamField>

    <ParamField path="show_output_to_user" type="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).
    </ParamField>

    <ParamField path="show_tool_to_user" type="boolean" default="true">
      Show tool calling events to end users
    </ParamField>

    <ParamField path="show_reasoning" type="boolean" default="false">
      Show agent reasoning/thinking process to end users (for models that support thinking mode)
    </ParamField>

    <ParamField path="show_memory" type="boolean" default="true">
      Show memory query events to end users
    </ParamField>

    <ParamField path="send_preview_snippet" type="boolean" default="false">
      Generate and send an agent introduction snippet before processing the query
    </ParamField>

    <ParamField path="main_chatbox" type="boolean" default="false">
      Identifies this agent as the main chatbox agent (UI hint for frontend rendering)
    </ParamField>
  </Expandable>
</ParamField>

### 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"
```

<ParamField path="structured_output" type="object">
  Configuration for structured output generation.

  <Expandable title="Structured Output Properties">
    <ParamField path="enabled" type="boolean" default="true">
      Whether to enable structured output generation for this agent.
    </ParamField>

    <ParamField path="schema" type="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`.
    </ParamField>
  </Expandable>
</ParamField>

### 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
```

<ParamField path="variable_assignments" type="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"`)
</ParamField>

### 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
```

<ParamField path="agents[].tools" type="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"
  ```
</ParamField>

#### **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
```

<ParamField path="tools" type="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.
  </Note>
</ParamField>

#### **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"
```

<ParamField path="max_iterations" type="integer" default="10">
  Maximum number of ReAct reasoning-action-observation cycles. Only applicable for `react_agent` type. Prevents infinite tool calling loops.
</ParamField>

<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.
</Note>

### 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
```

<ParamField path="supervised_agents" type="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"]
  ```
</ParamField>

<ParamField path="return_to_supervisor" type="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.
</ParamField>

<ParamField path="max_handoffs" type="integer" default="10">
  Maximum number of agent handoffs to prevent infinite coordination loops
</ParamField>

<ParamField path="tools" type="array" default="[]">
  Additional tools for the supervisor agent (the handoff tool is automatically injected)
</ParamField>

<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.
</Note>

## 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>

<Note>
  Supervisor architecture does not require explicit edges - the supervisor handles routing dynamically.
</Note>

## 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>

<Tip>
  **Temperature Settings**: Use lower temperatures (0.1-0.3) for factual tasks and higher (0.7-1.0) for creative tasks.
</Tip>

<Warning>
  **Entry Point**: Always ensure your `entry_point` matches an existing agent name, or the system will fail to initialize.
</Warning>

<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.
</Tip>

## 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

<CardGroup cols={2}>
  <Card title="Agent Types" icon="robot" href="/documentation/agent_config/types_config/agent-types">
    Learn about available agent types and when to use each
  </Card>

  <Card title="Agent Capabilities" icon="wand-magic-sparkles" href="/documentation/agent_config/agent-capabilities">
    Explore tools, streaming, and other agent capabilities
  </Card>
</CardGroup>