YAML Configuration

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:

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:

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"

string

required

Name of your multi-agent system

string

required

Brief description of what your system does

string

default:"workflow"

Architecture pattern for agent coordinationOptions:

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

Additional architecture types (routing, orchestration, collaboration) are defined but not yet implemented.

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)

string

required

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

boolean

default:"true"

Whether to persist messages in the agent session for conversation history

boolean

default:"true"

Enable checkpointing for state persistence across executions

object

default:"{}"

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

object

Global memory system configuration (applies to all agents unless overridden). Note that agent scoped modules are not allowed at the system level.

Agent Configuration

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

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

string

required

Unique identifier for the agent within the system

string

required

Type of agent to instantiate. See 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

string

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

array

default:"[]"

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

array

default:"[]"

List of output declarations for this agent

array

default:"[]"

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

object

Agent-specific memory configuration (overrides system-level memory config)

Prompt Configuration

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

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

object

Prompt composition configuration

Show Prompt Config Properties

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.

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

boolean

default:"true"

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

boolean

default:"false"

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

boolean

default:"true"

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

array

default:"[]"

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

few_shot_examples:
  - input: "What is 2+2?"
    output: "2+2 equals 4"

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:

agents:
  - name: "my_agent"
    llm_config:              # ← LLM configuration
      model: "gpt-4o"        # ← is nested within
      temperature: 0.7       # ← each agent
      max_tokens: 1000

object

Configuration for the language model

Show LLM Config Properties

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).

number

default:"0.7"

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

integer

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

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:

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

object

Controls real-time event streaming behavior

Show Streaming Config Properties

boolean

default:"true"

Enable streaming of agent responses

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).

boolean

default:"true"

Show tool calling events to end users

boolean

default:"false"

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

boolean

default:"true"

Show memory query events to end users

boolean

default:"false"

Generate and send an agent introduction snippet before processing the query

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.

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"

object

Configuration for structured output generation.

Show Structured Output Properties

boolean

default:"true"

Whether to enable structured output generation for this agent.

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.

Variable Assignments

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

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

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:

agents:
  - name: "my_agent"
    agent_type: "react_agent"
    tools:                    # ← Agent-level tools
      - "tavily_search"       # ← are defined within
      - "calculator"          # ← each agent object

array

List of tool identifiers for this agent. Only applicable for react_agent type.Example tools: tavily_search, tavily_extract, calculator

agents:
  - name: "my_agent"
    agent_type: "react_agent"
    tools:
      - "tavily_search"
      - "calculator"

System-Level Tools (Advanced)

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

tools: []                     # ← System-level tools
                              # ← are defined at root level
agents:
  - name: "agent1"
    # ... agent config

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.

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:

agents:
  - name: "my_agent"
    agent_type: "react_agent"
    max_iterations: 10        # ← Maximum ReAct loop iterations
    tools:
      - "tavily_search"

integer

default:"10"

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

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:

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

array

required

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

agents:
  - name: "supervisor"
    agent_type: "supervisor"
    supervised_agents: ["agent1", "agent2"]

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.

integer

default:"10"

Maximum number of agent handoffs to prevent infinite coordination loops

array

default:"[]"

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

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:

# 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

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.

Supervisor architecture does not require explicit edges - the supervisor handles routing dynamically.

Complete Examples

Basic Conversational Agent

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

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

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

System Prompts: Use multi-line strings with | for better readability of complex prompts.

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

Entry Point: Always ensure your entry_point matches an existing agent name, or the system will fail to initialize.

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.

Getting started

Agent Configuration

Multi Agent Systems

Advanced Features

Artaios Agents Studio

Platform

Integration

Configuration Structure

Core Fields

System Configuration

Agent Configuration

Basic Agent Fields

Prompt Configuration

LLM Configuration

Streaming Configuration

Structured Output

Variable Assignments

Tool Configuration

Agent-Level Tools (Recommended)

System-Level Tools (Advanced)

Tool Calling Behavior

Supervisor Configuration

Workflow Edges

Complete Examples

Basic Conversational Agent

Tool-Enabled Agent

Supervisor Multi-Agent System

Best Practices

Validation

Next Steps

Agent Types

Agent Capabilities

​Configuration Structure

​Core Fields

​System Configuration

​Agent Configuration

​Basic Agent Fields

​Prompt Configuration

​LLM Configuration

​Streaming Configuration

​Structured Output

​Variable Assignments

​Tool Configuration

​Agent-Level Tools (Recommended)

​System-Level Tools (Advanced)

​Tool Calling Behavior

​Supervisor Configuration

​Workflow Edges

​Complete Examples

​Basic Conversational Agent

​Tool-Enabled Agent

​Supervisor Multi-Agent System

​Best Practices

​Validation

​Next Steps

Agent Types

Agent Capabilities

Configuration Structure

Core Fields

System Configuration

Agent Configuration

Basic Agent Fields

Prompt Configuration

LLM Configuration

Streaming Configuration

Structured Output

Variable Assignments

Tool Configuration

Agent-Level Tools (Recommended)

System-Level Tools (Advanced)

Tool Calling Behavior

Supervisor Configuration

Workflow Edges

Complete Examples

Basic Conversational Agent

Tool-Enabled Agent

Supervisor Multi-Agent System

Best Practices

Validation

Next Steps