# 黄庄三号四能力 Agent

基于 LangGraph 的多能力 AI Agent，集成 FC/MCP/思考模式/Skill 四种核心能力。

## 四项能力

| 能力 | 方案 | 支持度 |
|------|------|--------|
| Function Call | LangGraph 原生 ToolNode | ★★★★★ |
| MCP | langchain-mcp-adapters + 确定性路由 | ★★★★ |
| 思考模式 | 自建 think_node + CoT 推理链 | ★★★★ |
| Skill | 自建 SkillRegistry 注册机制 | ★★★★ |

## 模型

GLM-4.5-air（智谱，OpenAI 兼容接口）

## 快速开始

```bash
cd /path/to/hz3-agent

# 自动测试（不带MCP）
python3 agent_v3.py --test

# 自动测试（带MCP）
python3 agent_v3.py --mcp --test

# 交互模式
python3 agent_v3.py --mcp
```

## 文件说明

| 文件 | 说明 |
|------|------|
| `agent_v3.py` | Agent 主程序（四能力完整版） |
| `mcp_server.py` | MCP 服务器（示例工具：时间/字符统计/UUID） |
| `step1_basic_fc.py` | Step1 基础 FC 验证 |

## 代码调用

```python
from agent_v3 import run_agent, build_graph

graph = build_graph()
result = await run_agent("黄庄天气怎么样？", graph)

print(result["reply"])      # 回复
print(result["thinking"])   # 思考过程
print(result["skill"])      # 使用的技能
```

## 架构流程

```
用户输入 → think(思考) → skill_route(路由)
                              │
                   ┌──────────┴──────────┐
               匹配MCP工具            匹配Skill
               直接调用             进入skill_exec
                   │                    │
              返回结果          执行工具+提示词模板
                   │                    │
                   └──────────┬─────────┘
                              │
                         agent(主节点)
                         │           │
                   有tool_calls   无tool_calls
                      │              │
                   tools节点        END
                      │
                   回到agent
```

## MCP 服务器

`mcp_server.py` 基于 FastMCP 提供 3 个示例工具：

- `get_current_time` - 获取当前时间
- `count_chars` - 统计文本字符数
- `generate_uuid` - 生成随机 UUID

## Skill 系统

已注册 3 个示例技能，扩展只需一行：

```python
skills.register(SkillDef(
    name="新技能",
    description="技能描述",
    prompt="提示词模板，{input}为占位符",
    tools=["依赖的工具名"]
))
```

## 关键设计决策

1. **MCP 确定性路由**：关键词匹配后直接 session.call_tool()，绕过模型不调工具的问题
2. **思考结果合并**：与 system prompt 合并为单条 SystemMessage，避免干扰工具调用
3. **AsyncExitStack 长连接**：MCP session 在 Agent 生命周期内保持，退出时统一关闭
4. **迭代保护**：agent 节点迭代超过 5 次强制结束，防止无限循环