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.