The Bit Garden

写 Agent 时，很多人一上来就纠结「用哪个框架」。更值得先想清楚的是：模型负责推理，工具负责改世界；中间那一圈「观察 → 决策 → 调用 → 再观察」怎么收口。 框架只是把这圈循环写得更省事。本文按工程视角拆开这套循环，并落到 Python / TypeScript、MCP、Skill（可复用流程说明书）上常见的实现选择。

本文不讲「万能自主 AI」。默认场景是：IDE / CLI 里由人触发、有权限边界、可审计的编码与运维助手——和博客站里那篇 MCP 与 Skill 驱动下的跨端转换 同一类问题域。

---

1. Agent 到底多出来一层什么

聊天补全：用户一问，模型一答，结束。

Agent：模型在回答之前（或之间）可以 多次调用工具，把工具结果写回上下文，再继续推理，直到它认为可以给出最终答复，或被策略强制停下。

一张极简结构（内联 SVG，避免 Mermaid 中文裁切）：

差别不在「会不会说话」，而在：

维度	普通对话	Agent
上下文来源	主要靠用户粘贴	模型可主动拉仓库、日志、文档
副作用	通常没有	写文件、开 PR、调外部系统（需权限）
失败处理	用户再追问	循环里读错误信息、改参数重试
停机条件	一轮结束	预算（步数 / token / 时间）+ 明确结束态

若某次任务 不需要工具，硬套 Agent 只会更慢、更贵；有时「单次推理 + 你自己写好的脚本」反而更稳。

---

2. 工具调用循环：实现上绕不开的几件事

无论用 LangChain / LangGraph、自研，还是 IDE 内置 Agent，内核多半长这样：

1. 组装消息：系统提示 + 历史 + 当前任务 +（可选）可用工具 schema。
2. 调模型：要求返回「纯文本」或「结构化 tool call」。
3. 若有 tool call：校验参数 → 执行 → 把结果以 tool 角色写回消息列表。
4. 若无 tool call：视为最终答案，退出。
5. 防护：最大步数、单工具超时、敏感路径黑名单、是否允许联网。

伪代码（语言无关）：

messages = [system, user_task]
for step in 1..MAX_STEPS:
    resp = llm(messages, tools=TOOL_SCHEMAS)
    if resp.tool_calls:
        for call in resp.tool_calls:
            result = run_tool(call.name, call.args)   # 这里要做权限与超时
            messages.append(tool_result(call.id, result))
        continue
    return resp.text
raise BudgetExceeded

落地时容易踩的坑：

• 工具描述含糊：模型会乱选工具或乱填参数。schema 的 description 和「什么时候不该用」写清楚，比堆工具数量重要。
• 结果太长：把整份 build.log 塞回上下文，下一步推理会糊。要对日志做截断、摘要、或只回错误附近几行。
• 无退出条件：模型反复「再试一下」。步数上限 +「连续 N 次同类失败则停并汇报」比指望它自觉收手可靠。
• 把规划写进提示却不写进状态：复杂任务需要显式 todo / 状态机（LangGraph 一类），否则长对话里「计划」会被冲掉。

---

3. 上下文：窗口有限，策略才是能力

Agent 强不强，经常取决于 塞进上下文的东西是否刚好够用。常见策略：

1. 按需检索：向量库 / 关键字搜仓库，而不是整库灌进 prompt。
2. 工作区摘要：当前分支、最近 diff、相关文件列表先给一页「地图」，再按需 read_file。
3. 会话记忆分层：短期（本轮 tool 结果）、中期（本任务的结论）、长期（用户偏好、项目约定）分开存，不要全挤在同一条 system 里。
4. Skill / 说明书：把「本仓库怎么跑测试、怎么写 commit、评审看什么」写成可加载文档，需要时再注入——比每次口头重复稳定。

和「记忆」相关的务实结论：

• 对话历史 不等于 可靠记忆；长会话要压缩或外部化。
• 写进仓库的 AGENTS.md / Skill / 规则，往往比塞进某次聊天更可复用。
• 敏感信息（密钥、token）不要进模型上下文；工具侧用环境变量与密钥管理。

---

4. MCP 与 Skill：协议层和流程层

4.1 MCP

MCP（Model Context Protocol） 把「工具 / 资源怎么接到模型宿主」标准化了：同一套客户端可以接 Git、浏览器、内部 HTTP、数据库只读接口等。对 Agent 开发者的意义是：

• 少写一轮「每个 IDE 各接一遍」的胶水；
• 权限与审计可以做在 MCP Server 边界上；
• 换模型或换宿主时，工具面相对稳。

它不负责替你设计「何时调用、失败如何重试」——那仍是 Agent 循环与产品策略的事。

4.2 Skill

Skill（或同类「可复用流程说明书」）更偏 人写的、可版本管理的操作手册：触发条件、步骤、检查清单、输出格式。适合：

• 代码评审口径统一；
• 发布前检查；
• 跨端迁移的质量门禁（见站内 MCP + Skill 一文）。

经验上：MCP 解决「能碰到什么」；Skill 解决「碰到之后按什么规矩做」。 二者叠在一起，Agent 才不至于每次从零猜项目习惯。

---

5. 技术选型怎么挑（够用即可）

需求	常见选择	备注
Python 快速原型	官方 SDK + 自写循环，或 LangChain 工具层	先跑通 3～5 个工具再上图编排
多步骤状态 / 分支 / 人工确认	LangGraph、自研状态机	显式节点比「全靠长 prompt」好调试
TypeScript / Node 全栈	Vercel AI SDK、OpenAI Agents SDK、自研	与前端同栈时排错成本低
IDE 内编码助手	Cursor Agent、Copilot Workspace 类	重点变成规则、MCP、仓库约定，而不是自建 UI
只要批处理脚本	不要 Agent	cron + 确定性脚本更合适

Python 侧最小可运行思路（示意，非完整项目）：

# 示意：一轮 tool-calling；真实项目还要错误分级、日志、鉴权
tools = [
    {
        "type": "function",
        "function": {
            "name": "read_file",
            "description": "读取仓库内文本文件。path 为相对仓库根路径。",
            "parameters": {
                "type": "object",
                "properties": {"path": {"type": "string"}},
                "required": ["path"],
            },
        },
    }
]

def run_agent(client, messages, max_steps=8):
    for _ in range(max_steps):
        resp = client.chat.completions.create(
            model="gpt-4.1-mini",  # 换成你实际用的模型 id
            messages=messages,
            tools=tools,
        )
        msg = resp.choices[0].message
        if not msg.tool_calls:
            return msg.content
        messages.append(msg)
        for tc in msg.tool_calls:
            # 在这里做路径白名单、大小限制
            payload = execute(tc.function.name, tc.function.arguments)
            messages.append({
                "role": "tool",
                "tool_call_id": tc.id,
                "content": payload[:8000],
            })
    return "已达步数上限，请缩小任务或提高权限边界后重试。"

选型原则只有一条：先让「一个工具 + 一步循环」在你自己的仓库里跑通，再加编排框架。反过来很容易变成框架文档驱动开发。

---

6. 评测与上线：比 demo 更要紧的部分

Agent demo 好看，不等于能进业务。上线前至少钉死：

1. 任务集：准备 20～50 个真实小任务（修测试、改文案、查日志），固定输入，看成功率和平均步数。
2. 回归：改 prompt / 换模型后重跑同一集合，避免「感觉变聪明了」其实是样本变简单了。
3. 安全默认：写操作为准拒绝或二次确认；生产凭据不进工具默认环境；命令带 timeout。
4. 可观测：每次 tool call 记名称、参数摘要、耗时、成败；出事故时能复盘「卡在第几步」。
5. 人机边界：哪些步骤必须人点头（合并主分支、发版、付钱），写进产品而不是写进「模型应该懂」。

---

7. 和日常开发怎么叠

若你主要在 Cursor / 同类环境里用 Agent，工程化抓手通常是：

• 仓库级规则与 Skill：构建命令、目录约定、禁止事项；
• MCP：接内部文档、工单、浏览器、专用校验脚本；
• 短反馈环：能本地 test / lint 的，就让 Agent 自己跑，少靠「我觉得编译过了」。

自研 Agent 服务时，则额外要做：会话存储、配额、多租户隔离、工具沙箱。那是另一篇文章的体量；本文把骨架定在 循环 + 上下文 + 协议/说明书 + 评测 四层，一般够支撑从 demo 走到可用。

---

8. 小结：动手时盯这几条

• Agent = 带工具的推理循环，不是换皮聊天。
• 工具 schema、结果裁剪、步数上限，比「再堆一个 Agent 框架」更能提升稳定性。
• MCP 管连接面，Skill 管项目规矩；上下文策略决定上限。
• 没有固定任务集和日志，就谈不上迭代模型或 prompt。

下一步若要加深，可以按方向拆：只做「编码 Agent 的仓库门禁」、或只做「LangGraph 状态机里的人工确认节点」。有具体仓库结构时，把工具列表和失败日志贴出来，比空谈框架版本有用得多。