hz3-agent/README.md

黄庄三号四能力 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 兼容接口）

快速开始

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 验证

代码调用

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 个示例技能，扩展只需一行：

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 次强制结束，防止无限循环