103 lines
2.9 KiB
Markdown
103 lines
2.9 KiB
Markdown
|
# 黄庄三号四能力 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 次强制结束，防止无限循环
|