ai-agent-book 精选快照（<2MB 代码与文档，来自 github.com/bojieli/ai-agent-book）

2026-08-20 13:12:50 +00:00
commit b119135836
10275 changed files with 3284984 additions and 0 deletions
@@ -0,0 +1,125 @@
+# 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):
+```yaml
+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
+```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:
+```python
+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:
+```yaml
+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.