ai-agent-book/chapter9/gaia-experience/AWorld/tests/load_config/README.md

YAML-based Config Guide

Overview

Use a single YAML file to define multiple Agents and an optional Swarm topology. This loader supports two kinds of placeholders:

• ${ENV_VAR}: Values come from system environment variables
• ${vars.KEY}: Values come from the vars section of the same YAML file

When a field value is exactly a single placeholder like ${vars.DEFAULT_TEMPERATURE}, the loader preserves the original type (e.g., float) instead of converting it to a string. This avoids type errors in LLM parameters such as temperature.

Files in this folder

• agents.yaml: Example YAML configuration with environment and in-file variables
• load_from_yaml.py: Minimal runner that loads the YAML and executes a swarm

Quick Start

1. Set your environment variables
   • PowerShell: $env:OPENAI_API_KEY="your-openai-api-key" ; $env:OPENROUTER_API_KEY="your-openrouter-api-key"
   • macOS/Linux: export OPENAI_API_KEY="your-openai-api-key" ; export OPENROUTER_API_KEY="your-openrouter-api-key"
2. Run the example
   • python examples/load_config/load_from_yaml.py

YAML Schema

Top-level keys:

• vars: Optional. In-file variables used by ${vars.KEY}
• agents: Required. Map of agent name -> agent configuration
• swarm: Optional. Defines the topology (workflow, handoff, or team)

Example (abridged):

vars:
  DEFAULT_TEMPERATURE: 0.1
  OPENAI_URL: https://api.openai.com/v1
  OPENROUTER_URL: https://openrouter.ai/api/v1

agents:
  researcher:
    system_prompt: "You specialize at researching."
    llm_config:
      llm_provider: openai
      llm_model_name: gpt-4o
      llm_api_key: ${OPENAI_API_KEY}  # from system env
      llm_base_url: ${vars.OPENAI_URL}  # from vars section
      llm_temperature: ${vars.DEFAULT_TEMPERATURE}  # from vars section

  summarizer:
    system_prompt: "You specialize at summarizing."
    llm_config:
      llm_provider: openai
      llm_model_name: google/gemini-2.5-pro
      llm_api_key: ${OPENROUTER_API_KEY}  # from system env
      llm_base_url: ${vars.OPENROUTER_URL}  # from vars section
      llm_temperature: ${vars.DEFAULT_TEMPERATURE}  # from vars section

swarm:
  type: workflow
  order: [researcher, summarizer]

Variable Substitution

• System env: ${OPENAI_API_KEY}
• In-file vars: ${vars.DEFAULT_TEMPERATURE}

Type-preserving rule:

• If the entire value is exactly ${vars.KEY}, the raw value from vars is used with its original type (float/int/bool/string)
• If ${vars.KEY} appears inside a longer string, it is replaced as text (string interpolation)

Tip: For numeric LLM parameters (like llm_temperature), prefer defining numbers in vars without quotes (e.g., 0.1, not "0.1").

Swarm Topologies

• workflow
  • Execute agents in the given order
  • Example: order: [researcher, summarizer]
• handoff
  • Use edges: [[left, right], ...] to define agent handoffs
• team
  • Define a root agent and members: [ ... ]

If swarm is omitted, the loader defaults to a workflow in the order agents are declared in YAML.

Running from Python

from aworld.config.agent_loader import load_swarm_from_yaml
from aworld.runner import Runners

swarm, agents = load_swarm_from_yaml("examples/load_config/agents.yaml")
result = Runners.sync_run(
    input="Tell me a complete history about the universe",
    swarm=swarm,
)

Access a specific agent if needed:

summarizer = agents["summarizer"]

Advanced: YAML anchors and merge keys (optional)

You can also use YAML anchors/aliases/merge keys to reuse blocks within the same file:

llm_defaults: &llm_defaults
  llm_provider: openai
  llm_temperature: 0.1

agents:
  a:
    llm_config:
      <<: *llm_defaults  # merge default fields
      llm_model_name: gpt-4o

Note: Anchors are structural reuse (not string interpolation). Use ${vars.KEY} for string placeholders.

Troubleshooting

• Temperature type error (e.g., cannot unmarshal string into float64)
  • Ensure the value comes from ${vars.KEY} as a full value and that the vars value is a number (unquoted). The loader preserves numeric types on full-value substitution.
• Placeholders not replaced
  • Missing environment variables or missing vars.KEY. Check the comments in YAML and set the needed values.
• Import error for loader
  • Make sure you are running against the project source (e.g., pip install -e .) or your PYTHONPATH includes the project root.

API Reference

• load_agents_from_yaml(path) -> Dict[str, Agent]
  • Load agents only
• load_swarm_from_yaml(path) -> Tuple[Swarm, Dict[str, Agent]]
  • Load agents and build a swarm based on the swarm section (or default workflow)

This loader reuses the existing Pydantic configuration models under aworld.config.conf and does not add new dependencies.