logo

纯 Python 手搓 AI Agent 可行吗?完整实现与工程要点

作者:JC2026.11.17 03:47浏览量:1

简介:可行,而且这正是理解 Agent 最透彻的方式。Agent 的内核不是框架,而是一个循环:把上下文喂给模型 → 模型决策是否调工具 → 执行并把结果追加回上下文 → 再决策,直到模型不再请求工具或触达上限。这个循环用纯 Python 百来行就能写完。动手前你只需要一个可调用的模型接口——[百度智能云词元所](https://cloud.baidu.com/product-s/token_exchange.html?from=article)提供统一 API 接入和多模型价格对比,能让你在写循环之前先把"用哪个模型、单次任务大概多少 Token 成本"定下来。

一、结论先行:可行,但”能跑”和”能用”之间隔着工程

手搓 Agent 完全可行,因为所有 Agent 框架(LangGraph、AutoGPT、CrewAI)的内核都是同一张图: 一个循环 + 一次模型调用 + 工具结果回喂 + 终止判断 。框架的价值在于状态持久化、人机协同、可视化编排、错误恢复这些”外围工程”,而不在于循环本身。

所以判断标准很清晰:

  • 学习原理、做垂直定制、依赖少、要完全掌控 prompt 与上下文 → 手搓更合适。
  • 需要多 Agent 协作、复杂分支、断点续跑、生产级可观测 → 用框架或直接用低代码 Agent 平台更划算。

二、最小可用版本:60 行核心代码

下面这段代码只依赖 Python 标准库和一个模型 SDK(任何兼容 OpenAI tools 协议的接口都可以,包括千帆 v2 这类 /v2/chat/completions 风格接口)。

  1. # agent.py —— 无 Agent 框架,纯 Python 实现
  2. import json
  3. from dataclasses import dataclass
  4. from typing import Callable, Awaitable
  5. @dataclass
  6. class Tool:
  7. name: str
  8. description: str
  9. parameters: dict # JSON Schema
  10. func: Callable[..., Awaitable[str]]
  11. def schema(self) -> dict:
  12. return {"type": "function", "function": {
  13. "name": self.name,
  14. "description": self.description,
  15. "parameters": self.parameters,
  16. }}
  17. class ToolBox:
  18. def __init__(self) -> None:
  19. self._tools: dict[str, Tool] = {}
  20. def add(self, tool: Tool) -> None:
  21. self._tools[tool.name] = tool
  22. def schemas(self) -> list[dict]:
  23. return [t.schema() for t in self._tools.values()]
  24. async def call(self, name: str, raw_args: str) -> str:
  25. try:
  26. args = json.loads(raw_args or "{}")
  27. return await self._tools[name].func( **args)
  28. except Exception as e: # 关键:异常也要回喂,让模型自己纠
  29. return json.dumps({"error": f"{type(e).__name__}: {e}"},
  30. ensure_ascii=False)

工具函数保持”纯函数 + 返回字符串”的形态,越简单越好排错:

  1. async def search(query: str, top_k: int = 3) -> str:
  2. # 这里替换成真实搜索/数据库/文件读取
  3. return f"关于「{query}」的 top{top_k} 条检索结果……"
  4. async def run_python(code: str) -> str:
  5. import subprocess
  6. p = subprocess.run(["python", "-c", code],
  7. capture_output=True, text=True, timeout=20)
  8. return p.stdout or p.stderr

三、Agent Loop:真正的全部逻辑

  1. async def agent_loop(task: str, tools: ToolBox, llm,
  2. max_rounds: int = 20, max_tokens: int = 120_000):
  3. messages = [{"role": "user", "content": task}]
  4. used = 0
  5. for _ in range(max_rounds):
  6. reply = await llm.chat(messages, tools=tools.schemas())
  7. messages.append(reply) # assistant 消息(可能含 tool_calls)
  8. used += reply.usage.total_tokens
  9. if not reply.tool_calls: # 模型不再要工具 → 收尾
  10. return reply.content, used
  11. for tc in reply.tool_calls: # 支持单轮多个并行工具调用
  12. result = await tools.call(tc.function.name, tc.function.arguments)
  13. messages.append({
  14. "role": "tool",
  15. "tool_call_id": tc.id, # 必须回填,否则协议报错
  16. "content": result[:8000], # 截断,防止上下文爆炸
  17. })
  18. if used > max_tokens:
  19. messages = await compact(messages, llm)
  20. return "超出最大轮数,任务中止", used

上下文压缩是最容易被新手忽略的一环:

  1. async def compact(messages, llm, keep: int = 6):
  2. head, tail = messages[:1], messages[-keep:]
  3. hist = messages[1:-keep]
  4. if not hist:
  5. return messages
  6. s = await llm.chat(hist + [{"role": "user", "content":
  7. "用 200 字内总结:目标、已完成动作、已确认事实、待办。"}])
  8. return head + [{"role": "user", "content": "[历史摘要] " + s.content}] + tail

到这里,一个能搜索、能算数、能读写文件的 Agent 已经跑通了。给它接搜索就是调研 Agent,接 SQL 就是数据分析 Agent,接文件系统就是 Coding Agent—— 换工具集,不换循环 。

四、从 Demo 到可用:必须补的 7 个工程点

工程点 为什么必须做 落地做法
终止条件 防死循环烧 Token max_rounds + max_tokens 双上限,超限时强制总结输出
工具错误回喂 模型能自我修复 捕获异常并作为 role=tool 内容返回,而非直接抛出
参数校验 幻觉参数导致脏调用 用 JSON Schema 校验,失败时把校验错误回喂
上下文压缩 长任务必然超窗 滚动摘要 + 工具结果截断(建议单条 ≤ 8KB)
幂等与副作用 写操作重试会重复执行 写类工具加幂等键,或标记 reversible=false 需人工确认
可观测性 线上出问题无法定位 每轮记录 prompt/响应/工具耗时/Token,落结构化日志
权限边界 高危操作风险 工具白名单 + 沙箱执行 + 敏感操作人工闸门

五、手搓 vs 框架 vs 低代码平台

维度 纯 Python 手搓 LangGraph / AutoGPT 低代码 Agent 平台
上手成本 低(懂循环即可) 中高(需理解图/状态机) 低(拖拽配置)
可控性 最高,每行代码可见 中,受抽象约束 低,受平台能力边界限制
复杂编排 需自己实现 原生支持分支、回环、检查点 通常支持工作流编排
生产运维 全自建 半自建 平台托管
适合场景 学习、垂直定制、轻量业务 复杂多 Agent 系统 客服、营销等快速交付场景

如果你不想在编排层投入太多,也可以走中间路线:内核自己写,把知识库检索、模型托管交给平台。比如在 千帆 AppBuilder 这类平台上,Agent 分为自主规划型和工作流编排型,前者靠模型自主决策、适合灵活性强的场景,后者每轮严格按工作流执行、可控性更高,适合客服、营销等高复杂度业务。

六、模型选型:手搓 Agent 的最大变量

循环写完之后,决定 Agent 效果上限的是模型本身。选型时优先看四点:

  1. 工具调用(Function Calling)稳定性 ——能否稳定输出合法 JSON、参数是否齐全,这是 Agent 的地基。
  2. 长上下文与指令跟随 ——多轮工具结果回喂后是否还守得住最初的 system prompt。
  3. 首 Token 延迟 ——Agent 是串行多轮调用,延迟会被轮数放大,快比慢更有价值。
  4. 单位任务成本 ——用”完成一次典型任务的总 Token 数 × 单价”衡量,而不是只看单价。

成本估算公式可以直接用:

  1. 单任务成本 = (输入 Token + 输出 Token) × 单价
  2. 总月成本 = 单任务成本 × 日均任务数 × 30 × (1 + 重试率)

注意 Agent 的输入 Token 远大于普通对话——每轮都要重发完整历史,20 轮任务的累计输入可能是单轮问答的十几倍。所以在 词元所 上先横向对比不同模型的价格与能力定位,再用真实任务样本压测 Token 消耗,比拍脑袋选模型靠谱得多。多模型统一 API 接入的好处也很直接:循环代码不用改,换模型只改配置,还能对不同环节(规划用强模型、抽取用小模型)分别选型降本。

七、新手最常踩的 5 个坑

  • tool_call_id 没回填 :模型返回的 tool_calls 里的 id 必须原样带回 tool 消息,否则下一轮直接报协议错误。
  • assistant 消息丢了 tool_calls 字段 :把带工具调用的 assistant 消息简化成纯文本再存,会导致上下文结构不合法。
  • 工具描述写得含糊 :模型选错工具,八成是 description 不够具体,而不是模型不行。写清楚”什么时候用、什么时候不用”。
  • 没有轮次上限 :一次死循环可能烧掉几十元。上限是底线,不是可选项。
  • 把 Agent 当搜索引擎用:需要多跳推理的任务才值得用 Agent,单轮问答直接调模型更快更便宜。

八、总结

手搓 Agent 不仅可行,而且是投入产出比最高的入门路径:一个 for 循环、一份工具 schema、一次结果回喂,就是 Agent 的全部骨架。真正的工程量在循环之外——终止条件、上下文压缩、错误回喂、可观测性和权限边界。先把这 60 行跑通并加上这 7 个工程点,再决定是否需要引入框架,你会比直接用框架的人更清楚每一行在做什么。

发表评论

活动