首页 / 资讯中心 / 文章详情

Agentic AI实战:手写最小Agent,从原理到工程落地

Agentic AI实战:手写最小Agent,从原理到工程落地 ★ FEATURED ARTICLE
一次闲聊中的“帮我查一下航班顺便把酒店也订了”其实对应的是一个完整的任务链路查询、比价、决策、下单、再确认。放在过去你得自己打开三五个 App 来回切换而大模型时代的“Agent”正在尝试把这套链路交给一个能自主规划、调用工具、判断结果并自我修正的智能体来做。从 2024 年下半年开始Agentic AI 几乎成了大模型行业最高频的关键词之一很多机构直接给出千亿美元级别的市场预测。这个判断到底靠不靠谱“黄金时代”是已经来了还是仍在路上如果是做技术的我们现在又该怎么理解它、上手它并且避免被概念泡沫误导这篇文章不会只停留在概念层面我会从 Agentic AI 的定义和技术架构讲起然后手写一个最小的可运行 Agent再结合工程落地的实际问题聊聊这个千亿美元市场真正走向成熟还需要跨过哪些坎。1. Agentic AI 是什么为什么它被视为下一阶段的核心1.1 从 Chatbot 到 Agent本质变化在哪里过去两年我们接触最多的其实是 Chatbot 形态的大模型应用用户输入一句话模型输出一段回答。交互是一次性的、被动的模型本身不负责继续跟进任务。Agentic AI 把这种交互模式改掉了。它不再只回答“是什么”“怎么做”而是去完成“请你帮我做”的任务。一个 Agent 系统通常具备四个核心能力理解目标把模糊的用户请求拆解成可执行计划。调用外部工具比如搜索、数据库查询、API 请求、代码执行。观察工具返回结果判断下一步动作。在失败时自我修正而不是直接放弃。换句话讲Chatbot 是“你问我答”Agent 是“你说目标我来拆解并执行”。这是从被动对话到主动任务执行的转变。1.2 常见的 Agentic AI 应用场景目前 Agentic AI 最密集的应用场景集中在以下几个方向办公自动化自动查阅邮件、整理会议纪要、生成周报、安排日程。代码开发根据 Issue 描述生成 PR、自动修复测试失败、辅助 Code Review。客户服务从简单的 FAQ 问答升级为能处理退换货、订单查询、投诉跟进的多轮任务智能体。数据分析根据自然语言问题自动写 SQL、跑脚本、绘制图表并生成结论。个人助理跨 App 完成订票、比价、打车、导航等操作。这些场景有一个共同特征任务链路长、涉及多个步骤传统规则脚本写不清楚但大模型加工具组合之后机器第一次具备了“临场应变”的能力。1.3 Agentic AI 与 RAG、工作流的关系这里有一个容易混淆的地方Agentic AI 和 RAG、工作流之间的边界经常被讨论但本质上它们是不同层级的技术。RAG 解决的是知识来源问题让模型能引用外部文档减少幻觉。它本身不强调多步决策。工作流解决的是流程固定问题比如“先查询订单状态再判断是否满足退款条件最后调用退款接口”每一步都是预设好的用户不能随意改变路径。Agentic AI 则是在前两者之上的决策层模型在每一步根据当前状态动态决定调用哪个工具、是否继续、是否换一种策略。它更适合任务路径不固定、需要灵活应变的场景。所以工业级的 Agent 系统通常会同时用到 RAG 和工作流并不是互斥关系。2. Agentic AI 的核心架构一个 Agent 是怎么工作的要从零理解 Agent我建议先抛开各种花哨的框架关注四个核心模块。2.1 规划把大目标拆成小步骤规划模块负责把用户的一句话目标拆成子任务。最简单的方式是让模型直接输出一段步骤列表复杂一点的做法会引入任务分解树甚至用独立的 Planner 模型专门负责拆解。举个例子用户说“帮我安排下周去上海的出差行程”Agent 可能需要拆解成查询下周三上海天气。查询高铁班次并预订。查找距离客户公司较近的酒店。比较价格并生成行程单。这一步的质量直接影响后续所有环节。如果规划出错后面即使工具调用全部成功最终结果也可能偏离用户目标。2.2 记忆短期上下文与长期偏好Agent 需要在多轮交互中记住两类信息短期记忆当前任务的上下文比如已经查到的航班号、已经选定的酒店。长期记忆用户的偏好比如“经常订靠窗座位”“酒店预算不超过 600 元”。工程上短期记忆一般通过上下文窗口保存长期记忆依赖向量数据库或键值存储在每轮任务开始时把相关记忆检索出来注入提示词。2.3 工具Agentic AI 的“手脚”工具是 Agent 能和真实世界交互的接口。常见形式有三种API 调用通过 function calling 机制让模型选择并生成对应参数。代码执行模型生成 Python/SQL 代码由沙箱执行后返回结果。浏览器操作模拟点击、输入、跳转页面适合没有开放 API 的场景。工具的设计直接决定 Agent 的能力边界。一个好的工具定义应该包括清晰的名称、用途说明、参数结构、返回格式因为模型需要靠这些描述来决策。2.4 反思失败后的自我修正反思模块是 Agent 区别于普通工作流的重要能力之一。当工具返回错误或结果异常时Agent 可以分析错误原因修改参数重新调用。切换备选工具。向用户请求补充信息。在多次失败后主动终止任务并汇总已完成的步骤。业界常见的 ReAct 模式Reasoning Acting就是典型实现模型在思考、行动、观察之间循环直到任务完成。下面这一段是 ReAct 循环的典型流程描述1. 根据当前状态思考下一步应该做什么 2. 选择一个工具并构造调用参数 3. 执行工具得到观察结果 4. 判断是否还需要继续或者任务已经可以结束 5. 重复以上流程直到输出最终答案3. 手写一个最小可运行的 Agent从零实现 ReAct 循环很多刚接触 Agent 的开发者容易陷入框架依赖一上来就用 LangChain、AutoGen反而忽略了核心原理。这里我用 Python 手写一个最小可用的 Agent不依赖任何第三方 Agent 框架只需要调用一个大模型 API 和几个模拟工具帮助理解 Agent 的内部机制。3.1 方案选型与环境准备本示例使用 Python 3.10依赖openaiSDK示例中以常见的 Chat Completions 接口为例。如果你使用的是其他模型服务例如国内大模型平台的 OpenAI 兼容接口只需要修改base_url和api_key即可。pip install openai示例项目结构如下agent-demo/ ├── agent.py # Agent 核心逻辑 ├── tools.py # 工具定义 └── main.py # 运行入口3.2 定义工具为了让模型能够调用工具我们通过 JSON Schema 的方式声明工具列表。模拟场景选择“查询天气”和“计算运费”两个工具一个偏检索一个偏计算便于后续观察 Agent 的决策过程。# 文件路径agent-demo/tools.py # 工具的具体实现这里用模拟数据代替真实 API def get_weather(city: str) - str: weather_data { 北京: 晴25℃, 上海: 多云28℃, 广州: 阵雨30℃, } return weather_data.get(city, f暂无{city}的天气数据) def calculate_shipping(weight: float, distance: int) - str: # 模拟运费计算首重 10 元续重每公斤 2 元距离超过 1000 公里加 5 元 if weight 1: fee 10 else: fee 10 (weight - 1) * 2 if distance 1000: fee 5 return f预估运费{fee:.2f} 元 # 工具说明模型会根据这段描述决定是否调用 TOOLS [ { type: function, function: { name: get_weather, description: 查询指定城市的当前天气情况, parameters: { type: object, properties: { city: { type: string, description: 城市名称例如北京 } }, required: [city] } } }, { type: function, function: { name: calculate_shipping, description: 根据包裹重量和运输距离计算预估运费, parameters: { type: object, properties: { weight: { type: number, description: 包裹重量单位公斤 }, distance: { type: integer, description: 运输距离单位公里 } }, required: [weight, distance] } } } ] TOOL_IMPL { get_weather: get_weather, calculate_shipping: calculate_shipping, }这里需要注意工具描述的作用很大。模型本身并不知道calculate_shipping内部怎么实现它只能根据 description 和 parameters 来判断这个工具适不适合当前任务。描述写得越清楚模型选错工具的概率就越低。3.3 实现 Agent 核心循环Agent 核心逻辑是一个循环把用户消息发送给模型如果模型返回工具调用请求就执行工具并把结果追加回消息历史然后再次调用模型直到模型给出最终文本回复。# 文件路径agent-demo/agent.py import json from openai import OpenAI from tools import TOOLS, TOOL_IMPL class MinimalAgent: def __init__(self, api_key: str, base_url: str None, model: str gpt-4o-mini): self.client OpenAI(api_keyapi_key, base_urlbase_url) self.model model self.messages [] def run(self, user_input: str, max_steps: int 5) - str: self.messages.append({role: user, content: user_input}) for step in range(max_steps): print(f\n 第 {step 1} 轮 ) response self.client.chat.completions.create( modelself.model, messagesself.messages, toolsTOOLS, ) choice response.choices[0] message choice.message if not message.tool_calls: # 模型不再调用工具直接返回最终结果 print(模型最终输出, message.content) return message.content # 模型请求调用工具 self.messages.append(message) for tool_call in message.tool_calls: fn_name tool_call.function.name fn_args json.loads(tool_call.function.arguments) print(f模型选择调用工具{fn_name}参数{fn_args}) result TOOL_IMPL[fn_name](**fn_args) print(f工具返回结果{result}) self.messages.append({ role: tool, tool_call_id: tool_call.id, content: result, }) # 超过最大步数仍未结束给出提示 return 任务已在最大步数内结束但未得到最终结果。 def reset(self): self.messages []这段代码虽然短但已经覆盖了 Agent 最核心的机制。几个细节值得解释第一message.tool_calls是模型返回的工具调用指令包含工具名和参数但此时工具并未真正执行需要我们在本地代码里完成调用。第二工具执行结果需要以role: tool的消息回传给模型并且带上tool_call_id用于关联具体的那次调用。第三每轮循环中模型面对的是完整的历史消息用户原话、之前调用过的工具、返回结果。这样它才能基于上下文做出下一步决策。3.4 编写运行入口并验证# 文件路径agent-demo/main.py from agent import MinimalAgent AGENT_API_KEY 你的 API Key AGENT_BASE_URL https://api.openai.com/v1 # 如使用兼容接口服务请替换为对应地址 AGENT_MODEL gpt-4o-mini if __name__ __main__: agent MinimalAgent( api_keyAGENT_API_KEY, base_urlAGENT_BASE_URL, modelAGENT_MODEL, ) user_input 北京天气怎么样另外一个 3.5 公斤的包裹从北京运到上海距离大约 1200 公里运费大概多少 agent.run(user_input)运行后预期输出类似下面这样 第 1 轮 模型选择调用工具get_weather参数{city: 北京} 工具返回结果晴25℃ 第 2 轮 模型选择调用工具calculate_shipping参数{distance: 1200, weight: 3.5} 工具返回结果预估运费20.00 元 第 3 轮 模型最终输出北京当前天气晴朗25℃。包裹从北京运到上海距离约 1200 公里重量 3.5 公斤预估运费 20 元。到这里你已经亲手写完了一个最简单但结构完整的 Agent。它具备了规划、工具调用、状态记忆的基本能力。虽然距离生产级还有很大距离但核心原理已经在手里了。3.5 从最小实现到生产级还差什么上面的代码能跑通流程但它缺少很多生产环境必须考虑的东西没有真实的工具鉴权和限流。没有处理模型返回 JSON 格式异常的情况。没有对敏感操作做人工确认。没有日志链路追踪。没有 Prompt 级别的安全防护。没有多轮对话的长期记忆存储。所以理解一个最小 Agent 只是起点。真正难的部分是如何把它放到业务环境里让它稳定、安全、不出错。4. Agentic AI 规模化落地面临的四座大山千亿美元市场要成为现实光有演示级的 Agent 是不够的。从我的观察来看Agentic AI 距离大规模商业化还要跨过几个核心问题。4.1 可靠性Agent 的“飘忽不定”大模型本质上是概率系统同样的输入换一次采样参数就可能得到不同的中间决策。这在单轮问答场景里问题不大但在多步任务链路中会被放大。如果第一步的规划有偏差后续所有工具调用都会跟着跑偏。更麻烦的是Agent 自己往往意识不到错误会把错的结果包装得看起来非常合理。目前工程上能做的缓解措施包括把关键步骤的决策交给规则校验不依赖模型自觉。对工具输入做结构化校验拒绝明显超出范围的参数。增加任务评审节点让模型在最终交付前自查一遍。为高风险操作配置人工审批流。一句话Agent 可以用在大规模任务处理上但核心关键节点必须有确定性兜底。4.2 安全与权限边界Agent 一旦拥有调用工具的能力就意味着它可以直接触达业务系统发邮件、下单、改数据库、执行命令。如果权限管控不到位一次幻觉引发的工具调用就可能造成生产事故。比较务实的安全方案有这几个层次工具权限最小化Agent 只用最低必要权限不能一上来就用管理员身份执行任意操作。操作清单白名单无论模型怎么规划最终可执行的动作必须在预设白名单内。敏感操作二次确认涉及资金、删除、发送消息的操作强制人工确认。全程审计日志记录模型的每一次决策依据和工具调用参数方便事后追溯。这些不是可选优化而是 Agent 上线的基本前提。4.3 成本控制多轮调用的 token 消耗Agent 相比普通 Chatbot 的调用成本要高得多。一个任务可能需要 5-10 轮模型推理每一轮都要携带完整的历史上下文token 消耗呈线性甚至超线性增长。在实际项目里常见的成本治理手段包括控制最大迭代步数防止 Agent 陷入无效循环。及时截断不相关的历史消息用小窗口模型处理中间决策。引入路由策略简单任务走小模型复杂任务才升级到大模型。对工具返回结果做摘要避免让模型反复阅读大段原始文本。这些优化不会影响用户体验但能把部署成本降低数倍。4.4 评测体系没有 Metrics 就没有优化方向传统软件可以用单元测试覆盖核心逻辑但 Agent 的中间决策难以直接断言对错。这就带来一个尴尬局面你升级了一个模型版本微调了 Prompt很难快速判断整体效果是变好还是变坏。工业界目前普遍采用的评估思路是构建任务级 benchmark整理一批真实业务任务样本标注期望的工具调用序列和最终答案。让 Agent 在样本上批量运行。分别统计任务完成率、平均步数、工具调用正确率、最终结果满意度。只有这种端到端的评测跑通Agent 的系统调优才有抓手。5. 千亿美元市场的依据与现实瓶颈回到主题Agentic AI 的市场空间为什么被看得这么大“黄金时代”什么时候才算真正到来5.1 为什么市场空间会被看得很大核心逻辑在于Agentic AI 不是在原有市场上做存量替换而是在创造一种新的软件交付模式。传统 SaaS 把人力流程固化为一套界面和规则用户必须学习系统逻辑。Agent 则反过来系统去理解用户目标然后操作底层工具完成任务。这意味着软件从“工具”变成了“数字员工”可定价空间从按席位收费变成按任务价值收费整体市场规模自然被重估。此外Agentic AI 可以以 API 或平台形式嵌入现有业务系统潜在覆盖的不只是软件行业还包括客服、物流、财务、医疗、法律等一大批依赖流程化操作的领域。所以千亿美元级别的预测不是凭空而来的它对应的是对劳动密集型流程的自动化替代。5.2 从项目制到产品化的鸿沟不过当前大量 Agent 项目还停留在“定制开发”阶段。每接一个客户就要针对业务场景重新设计工具集、流程编排和 Prompt很难形成可复制的标准化产品。这里面有几个深层次问题没有完全解决第一不同企业的工具系统差异太大Agent 很难跨企业通用。能查天气、能算运费不等于能操作 SAP、能处理私有协议。第二企业对容错率的要求极高。一个客服机器人答错可以接受但一个自动下单 Agent 下错单无法接受。第三Agent 的评测和验收标准尚未成熟采购方很难在合同里写清楚交付质量。所以Agent 离形成类似当年 SaaS 的标准化订阅市场还有一段距离。5.3 黄金时代何时来可以关注的几个信号与其猜测具体年份不如关注几个可观察的信号出现了跨行业的通用 Agent 协议或生态标准工具接口能够低成本互通。任务完成率在复杂场景下稳定超过人工水平且可被客观评测证明。主流云厂商把 Agent 运行环境做成默认基础设施企业无需自建提示词工程团队。出现以“按成果付费”计费的 Agent 商业模式企业按成功任务数结算。在这些信号出现之前Agentic AI 会持续增长但更准确地说是“快速爬坡期”而不是完整的黄金时代。对做技术的我们来说现在最值得做的不是去赌市场什么时候爆发而是先把 Agent 的核心原理吃透在实际项目里积累工具设计、安全管控和评测调优的经验。6. 给开发者的学习路线与工程实践清单6.1 学习路径建议如果刚接触 Agentic AI我建议按以下顺序深入学习第一步先理解大模型基础。掌握 Prompt 工程、上下文窗口、function calling这些是 Agent 的地基。第二步手写一个最小 Agent就是我上面演示的那套 ReAct 循环。即便不用在生产环境这个练习也能帮你理解 Agent 和普通 API 调用的本质差异。第三步学习主流框架。LangChain、LangGraph、AutoGen、Dify 等都可以用来提高开发效率但要带着问题去学例如“它帮我解决了什么工程问题”“它内部是怎么实现的”。第四步深入工程化方向。重点研究记忆管理、工具注册与鉴权、可观测性、评测平台、沙箱执行。这些才是 Agent 能否上生产的关键。第五步选择一个行业垂直场景做深度项目。比如智能客服、数据报表助手、代码审查助手。只有进入具体业务你才会真正理解工具设计和容错策略的重要性。6.2 工程实践清单结合我们前面的讨论在公司里落地 Agent 项目时建议提前准备一份检查清单检查项具体说明目标边界明确 Agent 负责什么、不负责什么超过边界直接转人工工具权限每个工具是否遵循最小权限原则是否存在删除/写入类高危操作参数校验模型输出参数是否经过结构化校验能否防御异常值最大步数是否设置了任务步数上限避免死循环沙箱隔离代码执行类工具是否运行在隔离环境人工确认敏感操作前是否有二次确认机制日志追踪是否记录每轮决策原因、工具调用参数、耗时和 token 消耗测试集是否沉淀了一组稳定的评测样本灰度发布是否支持按用户比例灰度异常时快速回滚成本监控是否对单次任务成本设置告警阈值这个清单不需要一次全部落地但新项目启动前过一遍能规避掉绝大多数低级事故。6.3 现阶段最值得关注的风险最后提醒一点Agentic AI 的技术迭代非常快不要被具体框架绑住思路。今天很火的框架半年后可能就被新方案替代。真正值钱的是对 Agent 核心机制的理解包括模型决策、工具抽象、安全策略和评测方法。在实际项目中优先关注成功率和安全性而不是一味追求“全自动”。一个在 70% 场景下全自动、30% 场景下会主动求助人工的 Agent远比一个追求 95% 全自动但失败时完全失控的 Agent 更可靠也更容易落地到真实业务里。如果你正准备把 Agent 引入自己的项目建议先用最小闭环跑通一个低风险场景把工具设计、日志观测和评测集这三件事做扎实再逐步扩大业务范围。这条路不性感但它是通往“黄金时代”最稳妥的路径。
阅读完成 · 觉得有帮助?
咨询建站