# Agent YAML Configuration Schema Reference

This document is injected into LLM context when generating agent configs.

## Required Fields

```yaml
agentId: string        # kebab-case unique ID (e.g., "stock-analyzer")
name: string           # Human-readable name (e.g., "股票分析助手")
description: string    # One-line description
type: enum             # "react" | "chain" | "router" | "parallel"
systemPrompt: string   # The agent's system prompt (use | for multiline)
model:
  provider: string     # See provider list below
  name: string         # Model name matching provider
  temperature: float   # [0.0, 2.0], default 0.0
  maxTokens: int       # Default 1024
```

## Provider → Model Mapping

| Provider | Models |
|----------|--------|
| anthropic | claude-sonnet-4-20250514, claude-opus-4-20250514 |
| openai | gpt-4o, gpt-4o-mini |
| dashscope | qwen3-max-2026-01-23, qwen-max, qwen-plus |
| deepseek | deepseek-chat, deepseek-reasoner |
| zhipu | glm-4-plus, glm-4-flash |
| moonshot | moonshot-v1-128k |
| ollama | llama3, qwen2 |

## Type-Specific Blocks

### react (default for tool-using agents)
```yaml
react:
  maxSteps: 10          # Y combinator max expansion
  observationEnabled: true
  toolTimeout: 30       # seconds
  verbose: false
```

### chain (fixed pipeline)
```yaml
chain:
  steps:
    - name: step_name
      prompt: "step prompt with {prev_step_output}"
      outputParser: "text"  # "json" | "text" | "number"
      guard:
        validator: "python expression"
        retry: 2
```

### router (classifier-based dispatch)
```yaml
router:
  classifier:
    prompt: "classification prompt"
    categories: ["cat_a", "cat_b"]
  routes:
    cat_a:
      type: react
      systemPrompt: "..."
    cat_b:
      type: react
      systemPrompt: "..."
```

### parallel (concurrent execution)
```yaml
parallel:
  agents:
    - { agentId: ..., type: react, ... }
    - { agentId: ..., type: react, ... }
  merge: "merge strategy description"
```

## Optional Blocks

### memory
```yaml
memory:
  enabled: true
  strategy: "local"     # "local" | "redis"
  size: 20              # context window
  ttl: 3600             # seconds
```

### mcp (tools)
```yaml
mcp:
  onlineTool:
    example-mcp-server:
      - everything_get_sum
  localTools:
    - terminate          # MUST always include
    - shell
    - file
    - browser
    - app
    - system
    - screenshot
  policy:
    mode: "auto"         # "auto" | "force" | "intelligence" | "disable"
```

### guard
```yaml
guard:
  validator: "len(x.strip()) > 50"
  retry: 2
  dangerousCommandBlock: true
  highRiskConfirmation: true
  maxOutputLength: 5000
```

### rag
```yaml
rag:
  enabled: true
  strategy: "tfidf"     # "tfidf" | "chromadb"
  documents:
    - "path/to/docs/"
```

### app (MCP server connection)
```yaml
app:
  mcp:
    custom:
      nodes:
        example-mcp-server:
          url: https://your-mcp-endpoint.example.com
          endpoint: /mcp/airouting
          headers:
            Authorization: "${MCP_AUTH_TOKEN}"
```