纯 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 风格接口)。
# agent.py —— 无 Agent 框架,纯 Python 实现import jsonfrom dataclasses import dataclassfrom typing import Callable, Awaitable@dataclassclass Tool:name: strdescription: strparameters: dict # JSON Schemafunc: Callable[..., Awaitable[str]]def schema(self) -> dict:return {"type": "function", "function": {"name": self.name,"description": self.description,"parameters": self.parameters,}}class ToolBox:def __init__(self) -> None:self._tools: dict[str, Tool] = {}def add(self, tool: Tool) -> None:self._tools[tool.name] = tooldef schemas(self) -> list[dict]:return [t.schema() for t in self._tools.values()]async def call(self, name: str, raw_args: str) -> str:try:args = json.loads(raw_args or "{}")return await self._tools[name].func( **args)except Exception as e: # 关键:异常也要回喂,让模型自己纠return json.dumps({"error": f"{type(e).__name__}: {e}"},ensure_ascii=False)
工具函数保持”纯函数 + 返回字符串”的形态,越简单越好排错:
async def search(query: str, top_k: int = 3) -> str:# 这里替换成真实搜索/数据库/文件读取return f"关于「{query}」的 top{top_k} 条检索结果……"async def run_python(code: str) -> str:import subprocessp = subprocess.run(["python", "-c", code],capture_output=True, text=True, timeout=20)return p.stdout or p.stderr
三、Agent Loop:真正的全部逻辑
async def agent_loop(task: str, tools: ToolBox, llm,max_rounds: int = 20, max_tokens: int = 120_000):messages = [{"role": "user", "content": task}]used = 0for _ in range(max_rounds):reply = await llm.chat(messages, tools=tools.schemas())messages.append(reply) # assistant 消息(可能含 tool_calls)used += reply.usage.total_tokensif not reply.tool_calls: # 模型不再要工具 → 收尾return reply.content, usedfor tc in reply.tool_calls: # 支持单轮多个并行工具调用result = await tools.call(tc.function.name, tc.function.arguments)messages.append({"role": "tool","tool_call_id": tc.id, # 必须回填,否则协议报错"content": result[:8000], # 截断,防止上下文爆炸})if used > max_tokens:messages = await compact(messages, llm)return "超出最大轮数,任务中止", used
上下文压缩是最容易被新手忽略的一环:
async def compact(messages, llm, keep: int = 6):head, tail = messages[:1], messages[-keep:]hist = messages[1:-keep]if not hist:return messagess = await llm.chat(hist + [{"role": "user", "content":"用 200 字内总结:目标、已完成动作、已确认事实、待办。"}])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 效果上限的是模型本身。选型时优先看四点:
- 工具调用(Function Calling)稳定性 ——能否稳定输出合法 JSON、参数是否齐全,这是 Agent 的地基。
- 长上下文与指令跟随 ——多轮工具结果回喂后是否还守得住最初的 system prompt。
- 首 Token 延迟 ——Agent 是串行多轮调用,延迟会被轮数放大,快比慢更有价值。
- 单位任务成本 ——用”完成一次典型任务的总 Token 数 × 单价”衡量,而不是只看单价。
成本估算公式可以直接用:
单任务成本 = (输入 Token + 输出 Token) × 单价总月成本 = 单任务成本 × 日均任务数 × 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 个工程点,再决定是否需要引入框架,你会比直接用框架的人更清楚每一行在做什么。

登录后可评论,请前往 登录 或 注册