我是AI时代的无业游民,我游荡在现实与意念之间


GitHub 热门项目 cindy 拆解:把「开箱即用 AI Agent」写成一份可复用的工程手册

什么时候用这份手册

你在课程作业或作品集里想加一个「AI 能自己动手干活」的模块,但一搜 Agent 框架就被 LangGraph、AutoGen、MCP、工具调用协议、沙箱、记忆存储这些词劝退;或者你已经抄了一份 demo,跑起来却只会聊天、不会做事,一接真实任务就报错。这份手册按「使用频率」组织:先看症状对号入座,再看诊断定位根因,然后照抄重构后的最小模板,最后用检查清单自查。目标读者是学过语法、但还没在真实协作约束下写过工程代码的在校学生与转行者。

前置知识只有三条:会写 Python 函数、知道什么是 HTTP 请求、能读懂 JSON。读完你能拿出的作品集能力是:独立实现一个「任务输入 → 规划 → 调用工具 → 校验结果」的最小 Agent 闭环,并能说清每一步为什么这么设计。行业里这项技能的真实用法,不是让你从零造框架,而是让你能读懂一个开源 Agent 项目的目录结构、判断它是否可信、并把它裁剪进自己的项目。

An abstract scene of modular glowing cubes assembl

① 重构前的症状:一个「会聊天但不会干活」的 Agent

最常见的初学者写法,是把所有逻辑塞进一个函数,用字符串拼接 prompt,让模型「顺便」输出要执行的命令:

# before.py —— 能跑,但一接真实任务就崩
import json, subprocess
from openai import OpenAI

client = OpenAI()

def run_agent(user_input: str) -> str:
    prompt = f"""
    你是助手。用户说:{user_input}
    如果需要执行命令,请直接输出 shell 命令,我会执行。
    """
    resp = client.chat.completions.create(
        model="gpt-5.5",
        messages=[{"role": "user", "content": prompt}],
    )
    text = resp.choices[0].message.content
    # 直接把模型输出当命令执行
    result = subprocess.run(text, shell=True, capture_output=True, text=True)
    return result.stdout

三个可复现的痛点:

  • 模型返回一句「好的,我来帮你查一下」而不是命令,subprocess 直接抛 FileNotFoundError;
  • 模型返回带解释的多行文本,shell=True 把整段当命令,行为不可预测;
  • 没有循环:一次调用结束就返回,模型说「我需要先看目录」,程序也不会真的去看。

面试/作业常被追问的点:这段代码里 shell=True 加模型自由文本,等价于把任意代码执行权交给一个概率模型,这是安全评审一票否决的写法。

② 问题诊断:根因是「没有协议」和「没有循环」

表面看是解析失败,根因有三层:

  1. 输出格式无约束。自然语言和可执行指令混在一个通道里,解析必然脆弱。解法是让模型输出结构化 JSON,并用 schema 校验。
  2. 没有工具抽象。命令是裸字符串,没有名称、参数、返回值约定。解法是定义工具注册表,模型只能「点名」已注册的工具。
  3. 没有 Agent 循环。Agent 的本质是「观察 → 决策 → 行动 → 再观察」的循环,单次调用只是其中一步。解法是加 while 循环和最大步数上限。

这也解释了为什么「开箱即用」的 Agent 项目值得看:它们把上述三层封装成了默认约定,你打开目录就能看到 tools/、agent loop、sandbox 的分层,而不是一坨 prompt。

③ 重构后的写法:协议 + 注册表 + 循环

# after.py —— 最小可复用闭环
import json
from openai import OpenAI

client = OpenAI()
MAX_STEPS = 8

# 1) 工具注册表:名称 -> (函数, 参数 schema)
TOOLS = {
    "list_dir": {
        "fn": lambda path=".": "\n".join(__import__("os").listdir(path)),
        "schema": {"type": "object", "properties": {"path": {"type": "string"}}},
    },
    "read_file": {
        "fn": lambda path: open(path, encoding="utf-8").read()[:2000],
        "schema": {"type": "object", "properties": {"path": {"type": "string"}},
                   "required": ["path"]},
    },
}

SYSTEM = """你是一个执行型 Agent。每轮只输出一个 JSON 对象,二选一:
{"action":"tool","name":"工具名","args":{...}}
{"action":"final","answer":"给用户的最终答复"}
不要输出 JSON 以外的任何文字。"""

def run_agent(user_input: str) -> str:
    messages = [{"role": "system", "content": SYSTEM},
                {"role": "user", "content": user_input}]
    for _ in range(MAX_STEPS):
        resp = client.chat.completions.create(
            model="gpt-5.5", messages=messages,
            response_format={"type": "json_object"},  # 关键改动 1
        )
        raw = resp.choices[0].message.content
        try:
            step = json.loads(raw)
        except json.JSONDecodeError:
            messages.append({"role": "user", "content": "输出不是合法 JSON,请重试。"})
            continue

        if step["action"] == "final":
            return step["answer"]

        name, args = step["name"], step.get("args", {})
        tool = TOOLS.get(name)                      # 关键改动 2:白名单
        if tool is None:
            obs = f"未知工具 {name},可用:{list(TOOLS)}"
        else:
            try:
                obs = tool["fn"](**args)
            except Exception as e:
                obs = f"工具执行失败:{e}"
        messages.append({"role": "user", "content": f"观察结果:{obs}"})  # 关键改动 3
    return "达到最大步数,任务未完成。"

三处关键改动对照:

改动beforeafter作用
输出协议自由文本response_format=json_object + 固定二选一结构解析不再靠猜
工具边界任意 shell 字符串TOOLS 白名单 + 参数 schema模型只能调用你允许的能力
控制流单次调用for 循环 + MAX_STEPS支持多步任务且不会死循环

注意点:read_file 这类工具务必加路径校验(如限制在项目目录内),示例为保持短小省略了;真实项目中把工具执行放进容器或子进程,而不是主进程。

④ 收益与代价

  • 可读性:逻辑从「一个巨型 prompt」变成「注册表 + 循环 + 协议」三块,新增工具只需往 TOOLS 加一项,不改主流程。
  • 健壮性:非法 JSON、未知工具、工具异常三类失败都有兜底分支,不再整段崩溃;MAX_STEPS 把最坏情况从「无限调用」压到 8 次。
  • 性能与成本:多步任务必然多轮调用,token 消耗随步数线性增长;MAX_STEPS=8 是成本与能力的折中,可按任务复杂度下调到 4。
  • 复杂度:代码从约 15 行涨到约 50 行,但换来的是可测试性——每个工具函数可以单独单测,循环逻辑可以 mock 模型响应来测。

⑤ 适用边界与检查清单

不该这么改的时候:任务只需单轮问答(如文本润色、翻译),加循环纯属浪费;工具涉及不可逆操作(删除、支付)时,仅靠白名单不够,必须加人工确认环节;对延迟极敏感的场景,多轮调用不划算。

提交作品集前的检查清单:

  • 模型输出是否被 schema 或 json_object 约束,解析失败有重试分支?
  • 工具是否全部走注册表白名单,没有裸 shell=True 拼接模型文本?
  • 是否有 MAX_STEPS 上限和超限后的明确返回?
  • 工具异常是否被捕获并作为「观察结果」回灌给模型,而不是直接抛出?
  • 文件类工具是否做了路径范围限制?
  • 能否用 mock 的模型响应写一条不依赖网络的单测?

把这份手册当成模板:先跑通 after.py,再照着开源 Agent 项目的目录结构,把 tools/、agent loop、sandbox 拆成独立文件——这一步做完,你就有了一个能讲清设计取舍、也能经得起追问的最小 Agent 项目。

Logo

更多推荐