Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.atthene.com/llms.txt

Use this file to discover all available pages before exploring further.

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"
​
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 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.
​
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 (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

​
name
string
required
Unique identifier for the agent within the system
​
agent_type
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
​
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 (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
​
prompt_config
object
Prompt composition configuration
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
​
llm_config
object
Configuration for the language model

​
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
​
streaming_config
object
Controls real-time event streaming behavior

​
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"
​
structured_output
object
Configuration for structured output generation.

​
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
​
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:
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
​
agents[].tools
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
​
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.
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"
​
max_iterations
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
​
supervised_agents
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"]
​
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)
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.

​
Next Steps

Agent Types

Learn about available agent types and when to use each

Agent Capabilities

Explore tools, streaming, and other agent capabilities