Skip to content

Agent Harness 从零手写(二):MCP 运行时发现与两层循环 ​

第一篇的工具是手写在 TOOL_MAP 里的,Agent 也只有一层循环。这一篇解决两个「放大」之后才会遇到的问题:工具多了怎么办(MCP),任务复杂了怎么办(两层循环)。

一、MCP:把"手写工具"换成"运行时发现" ​

1.1 手写 TOOL_MAP 的天花板 ​

手写工具在单机 demo 里没问题,一放到真实场景就露馅:

  • 每接一个新工具,就要改 tools 声明、改 TOOL_MAP、改参数解析
  • 工具和 Agent 代码强耦合,换个工具集就得改代码
  • 别人写好的工具,你没法直接拿来用

MCP(Model Context Protocol)解决的正是这件事:把"工具怎么暴露、怎么发现、怎么调用"标准化。

1.2 server / client / stdio 三件事 ​

list_tools() 是这套机制的灵魂 —— 客户端不再写死工具清单,而是运行时问出来:

python
async with stdio_client(server) as (read, write):
    async with ClientSession(read, write) as session:
        await session.initialize()
        tools = await session.list_tools()          # 发现:运行时问出有哪些工具
        r = await session.call_tool("add", {"a": 3, "b": 5})   # 调用:工具名 + JSON 参数

1.3 桥接只有一行 ​

MCP 和 OpenAI function calling 之间要对接,看起来是个麻烦事,实际上一行就够:

python
def mcp_tool_to_openai(tool):
    """把 MCP 工具转成 OpenAI function 格式"""
    return {
        "type": "function",
        "function": {
            "name": tool.name,
            "description": tool.description or "",
            "parameters": tool.input_schema,   # MCP 给的就是 JSON Schema,直接当 parameters 用
        },
    }

因为两边都用 JSON Schema 描述参数,所以 input_schema 可以原样当 parameters 用。这一行是整个 MCP 集成里最漂亮的地方。

1.4 换 server 就换能力 ​

写完之后的效果:换一个 MCP 服务器,Agent 代码一行都不用改,它会自己发现新工具。这跟手写 TOOL_MAP 的时代是完全不同的体验 —— 也是"标准化"这件事真正的价值。

项目里 Stage 27 更进一步:把规划器(Planner)的执行者从"手写工具"换成"MCP 工具",能力变了,规划逻辑没动。

二、两层循环:Plan-and-Execute + ReAct ​

2.1 单层循环在复杂任务上会散 ​

一个循环处理"查资料 → 算数 → 写报告"这种多步任务时,模型容易顾此失彼:做着第三步忘了第一步的目标。

解法是把循环分成两层:

2.2 外层拆步骤,内层动手 ​

  • 外层(Plan-and-Execute):Planner 先把任务拆成 3~5 个清晰步骤,只输出 JSON
  • 内层(ReAct):每一步交给一个会调工具的循环去完成
  • 最后:Summarizer 把各步成果组织成完整回答

这个项目在 Stage 26 专门做了一次演进:Stage 21 的执行者只是个"纯 LLM 角色",在脑子里把步骤完成,算错了也将错就错;Stage 26 把它换成 ReAct 循环之后,执行者能真的去查时间、真的去算数,闭环才完整。

2.3 顺带解决的两个工程问题 ​

写规划器时会撞上两个很典型的坑,项目的处理方式可以直接抄:

python
# 1) 模型可能不老实:把 JSON 包在 markdown 代码块里,或前后加一堆解释
def extract_steps(text):
    text = text.strip()
    if text.startswith("```"):           # 剥掉代码围栏
        text = text.split("```", 2)[1]
        if text.startswith("json"):
            text = text[4:]
    start = text.find("{")               # 从第一个 { 开始解析,忽略前面的话
    obj, _ = json.JSONDecoder().raw_decode(text[start:])
    return obj["steps"]

# 2) 模型偶尔返回空内容 —— 空就重试,别直接崩
for _ in range(3):
    resp = client.chat.completions.create(**kwargs)
    content = resp.choices[0].message.content
    if content and content.strip():
        return content
return ""

另外,工具实现里也有安全细节:calculate 工具不允许直接把表达式喂给 eval,而是先用白名单正则过滤掉除数字和运算符之外的一切字符。

本文阅读--次|全站访问--次|访客--人