简介:本文面向企业开发者,拆解AI Agent从聊天机器人到可执行智能体的落地方法。读者可获得场景判断清单、工具描述模板、最小可运行代码、方案选型对比、上线检查表与指标口径,帮助团队在权限、安全、成本和可维护性之间取得平衡。
在企业场景中,AI Agent(智能体)并不是简单的“更强的大模型”,而是把大语言模型、知识检索、工具调用、状态记忆、权限控制和监控审计组合起来,让模型从“回答问题”走向“完成任务”。但是,是否需要搭建智能体,取决于业务是否存在外部系统闭环需求、是否具备可调用工具、是否能承担相应工程成本。
可以先按以下判断清单做初步评估:
AI Agent 和 RPA 有什么区别?
RPA 更适合规则固定、界面明确、流程稳定的自动化任务,例如固定页面录入、固定报表下载、固定系统间搬运。AI Agent 更适合输入非结构化、需要语义理解、动态决策、多工具编排的任务,例如从合同中抽取条款并结合库存生成补货建议。两者可以互补:智能体做理解、规划和异常处理,RPA 或工作流做确定性执行。
什么时候不需要智能体?
如果任务可以通过固定工作流完成,或者只需要模型生成文本,或者工具接口无法开放,或者业务收益不明显,就不建议强行使用智能体。过度设计会带来更高的维护成本、权限风险和故障定位难度。
工具描述怎么写?
工具描述不能只写一句“查询库存”。它应明确工具名、用途、输入参数、输出结构、权限范围、错误码和调用边界。工具描述是模型选择工具的重要依据,描述越清晰,误调用越少。
智能体常见失败原因有哪些?
常见问题包括:工具描述模糊导致模型选错工具;输入参数缺少校验;工具超时无重试;写操作缺少幂等和回滚;权限过大导致越权;没有监控指标;没有人工兜底;提示词未区分用户输入与外部内容,导致提示注入风险。
一个企业级 AI Agent 通常由四大模块组成:大脑、感知、工具、记忆。它们分别解决理解推理、信息获取、动作执行和状态积累的问题。
大脑通常由大语言模型承担,负责识别用户意图、拆解任务、选择工具、生成中间结果。选型时不应只看参数规模,而要看指令遵循、函数调用稳定性、上下文长度、响应延迟、成本、私有化部署要求和合规能力。
感知包括文档解析、表格读取、图片识别、消息监听、数据库查询等。企业场景中,很多任务不是缺模型,而是缺上下文。如果无法把合同、库存、工单、日志、工单状态等数据转换成结构化上下文,模型就很难做出可靠判断。
工具是智能体区别于普通聊天机器人的核心。工具可以调用业务 API、查询数据库、执行脚本、触发工作流、发送通知、创建工单。工具设计质量直接决定智能体是否能真正落地。
工具模块不能只暴露函数,还要建立统一注册表。建议每个工具包含以下元数据:
query_inventory。工具名:query_inventory
用途:查询指定仓库中某个 SKU 的当前可用库存、在途库存和单位信息。仅用于读取,不修改库存。
输入参数:
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| sku | string | 是 | 商品编码,例如 SKU-001 |
| warehouse | string | 否 | 仓库编码,不传则返回默认仓 |
输出结构:
| 字段 | 类型 | 说明 |
|---|---|---|
| status | string | 调用状态,成功为 ok |
| available_qty | number | 可用库存 |
| in_transit_qty | number | 在途库存 |
| unit | string | 库存单位 |
权限范围:只读。
错误码:
SKU_NOT_FOUND:商品编码不存在。WAREHOUSE_INVALID:仓库参数非法。DB_TIMEOUT:数据库查询超时。调用边界:只允许查询,不允许扣减库存;单次查询结果应缓存短时间,避免重复调用。
很多项目失败不是模型能力不够,而是技术路线选错。可以用下面的对比表做判断:
| 方案 | 闭环能力 | 语义理解能力 | 适用场景 | 成本 | 可维护性 | 主要风险 |
|---|---|---|---|---|---|---|
| 纯 LLM 对话 | 弱 | 强 | 问答、总结、改写、建议 | 低到中 | 中 | 幻觉、无法执行、上下文丢失 |
| 工作流引擎 | 中到强 | 弱 | 固定流程、审批链、数据流转 | 中 | 高 | 流程僵化、异常分支不足 |
| RPA | 中 | 弱 | 界面自动化、遗留系统操作 | 中到高 | 中 | 页面变化易失效、稳定性差 |
| AI Agent | 强 | 强 | 多系统协同、非标输入、动态决策 | 中到高 | 中 | 工具滥用、权限失控、调试复杂 |
选择原则可以概括为:
下面用一个“库存低于阈值自动补货”的场景说明智能体如何从输入走到闭环。假设业务要求:当仓库 A 的 SKU-001 库存低于阈值时,生成补货建议,并创建采购单。如果采购金额超过阈值,则必须人工审批。
用户或系统输入:
“仓库 A 的 SKU-001 库存低于安全库存,请检查并生成补货建议。”
query_inventory,输入 sku=SKU-001,warehouse=WH-A。query_vendor,获取默认供应商和采购单价。create_purchase_order,携带 idempotency_key,避免重复创建。这个示例说明:智能体不是只输出一段建议,而是通过工具调用把建议变成业务结果。写操作必须有幂等、审批和回滚机制。
下面给出一个最小可运行的智能体骨架。它只用于说明 session、tool_registry、超时、重试、异常捕获和失败回滚的基本逻辑。生产环境中还需要接入真实鉴权、审计、日志、监控、消息队列和数据库。
运行环境假设:
from dataclasses import dataclass, fieldfrom typing import Any, Dict, List, Optionalfrom concurrent.futures import ThreadPoolExecutor, TimeoutError as FutureTimeoutErrorimport time@dataclassclass ToolSpec:name: strdescription: strfunc: Anyreadonly: bool = Trueneeds_idempotency_key: bool = Falseclass ToolRegistry:def __init__(self):self._tools: Dict[str, ToolSpec] = {}def register(self, spec: ToolSpec):self._tools[spec.name] = specdef get(self, name: str) -> ToolSpec:if name not in self._tools:raise KeyError(f"tool not found: {name}")return self._tools[name]def call(self,name: str,args: Dict[str, Any],timeout: float = 10.0,retries: int = 2) -> Dict[str, Any]:spec = self.get(name)last_error: Optional[Exception] = Nonefor attempt in range(retries + 1):try:with ThreadPoolExecutor(max_workers=1) as pool:future = pool.submit(spec.func, **args)return future.result(timeout=timeout)except FutureTimeoutError as e:last_error = eexcept Exception as e:last_error = e# 写操作默认不直接重试,避免重复提交if not spec.readonly:breakif attempt < retries:time.sleep(0.2 * (attempt + 1))raise RuntimeError(f"tool call failed: {name}, last_error={last_error}")@dataclassclass PlanStep:type: str # tool 或 llmtool: Optional[str] = Noneargs: Dict[str, Any] = field(default_factory=dict)prompt: Optional[str] = None@dataclassclass Plan:steps: List[PlanStep]@dataclassclass AgentSession:messages: List[str] = field(default_factory=list)memory: Dict[str, Any] = field(default_factory=dict)SESSIONS: Dict[str, AgentSession] = {}def get_session(session_id: str) -> AgentSession:if session_id not in SESSIONS:SESSIONS[session_id] = AgentSession()return SESSIONS[session_id]# 示例工具实现def query_inventory(sku: str, warehouse: str) -> Dict[str, Any]:return {"status": "ok","sku": sku,"warehouse": warehouse,"available_qty": 3,"safety_qty": 10,"unit": "件"}def create_purchase_order(sku: str,qty: int,vendor: str,idempotency_key: str) -> Dict[str, Any]:# 生产环境应检查 idempotency_key,避免重复创建return {"status": "created","id": "PO-1001","sku": sku,"qty": qty,"vendor": vendor,"idempotency_key": idempotency_key}def cancel_purchase_order(order_id: str, reason: str) -> Dict[str, Any]:return {"status": "cancelled","id": order_id,"reason": reason}# 示例 LLM 接口,生产环境替换为真实模型客户端class DemoLLM:def plan(self, user_input: str, memory: Dict[str, Any]) -> Plan:if "库存低于" in user_input or "补货" in user_input:return Plan(steps=[PlanStep(type="tool",tool="query_inventory",args={"sku": "SKU-001", "warehouse": "WH-A"}),PlanStep(type="tool",tool="create_purchase_order",args={"sku": "SKU-001", "qty": 20, "vendor": "V-100"})])return Plan(steps=[])def generate(self, prompt: str, memory: Dict[str, Any]) -> str:return "已根据库存和采购规则生成结果。"def run_agent(llm: DemoLLM,session_id: str,registry: ToolRegistry,user_input: str) -> Dict[str, Any]:session = get_session(session_id)session.messages.append(user_input)plan = llm.plan(user_input, memory=session.memory)created_order_ids: List[str] = []last_result: Any = Nonetry:for step in plan.steps:if step.type == "tool":if not step.tool:raise ValueError("tool step missing tool name")args = dict(step.args)spec = registry.get(step.tool)if spec.needs_idempotency_key:step_count = len(session.memory.get("executed_steps", []))args["idempotency_key"] = f"{session_id}-step-{step_count}"result = registry.call(step.tool,args=args,timeout=10,retries=2)if result.get("status") == "created":created_order_ids.append(result["id"])session.memory.setdefault("executed_steps", []).append({"tool": step.tool,"args": args,"result": result})last_result = resultelse:last_result = llm.generate(step.prompt or user_input,memory=session.memory)return {"ok": True, "answer": last_result}except Exception as e:rollback_results = []for order_id in reversed(created_order_ids):try:rollback_results.append(registry.call("cancel_purchase_order",args={"order_id": order_id,"reason": f"agent failure: {e}"},timeout=10,retries=1))except Exception as rollback_error:rollback_results.append({"ok": False,"order_id": order_id,"error": str(rollback_error)})session.memory["last_failure"] = {"error": str(e),"rollback_results": rollback_results}return {"ok": False,"error": str(e),"rollback_results": rollback_results}# 注册工具registry = ToolRegistry()registry.register(ToolSpec(name="query_inventory",description="只读查询SKU库存和安全库存",func=query_inventory,readonly=True))registry.register(ToolSpec(name="create_purchase_order",description="创建采购单,属于写操作,需要幂等键",func=create_purchase_order,readonly=False,needs_idempotency_key=True))registry.register(ToolSpec(name="cancel_purchase_order",description="取消采购单,用于失败回滚",func=cancel_purchase_order,readonly=False))# 调用示例llm = DemoLLM()result = run_agent(llm=llm,session_id="s-001",registry=registry,user_input="仓库A的SKU-001库存低于安全库存,请检查并补货")print(result)
这个最小示例的关键点有三个:
cancel_purchase_order 做补偿。生产环境中,回滚设计应尽量做到幂等和可追溯。智能体具备执行能力后,风险会明显上升。上线前建议按以下检查表逐项确认:
| 检查项 | 检查内容 | 建议责任人 | 验收证据 |
|---|---|---|---|
| 权限矩阵 | 每个工具是否登记最小权限;读写是否分离;高风险工具是否单独标记 | 安全负责人、应用负责人 | 权限清单、工具注册表 |
| 写操作审批 | 创建订单、删除数据、付款、变更配置等是否触发审批或二次确认 | 业务负责人、流程负责人 | 审批流配置、测试记录 |
| 提示注入防护 | 外部文档、网页、邮件内容是否被直接当作系统指令;是否隔离用户输入与知识内容 | 算法负责人、安全负责人 | 防护策略、测试用例 |
| 工具滥用防护 | 是否限制调用频率、参数范围、单次数量和敏感字段;是否监控异常调用 | 后端负责人、安全负责人 | 限流配置、告警规则 |
| 幂等与去重 | 写操作是否有 idempotency_key;重复请求是否返回同一结果 |
后端负责人 | 幂等测试报告 |
| 失败回滚 | 失败时是否能取消已创建资源;回滚是否可审计 | 后端负责人、业务负责人 | 回滚流程、演练记录 |
| 监控指标阈值 | 是否监控工具失败率、超时率、P95 延迟、人工介入率、越权告警 | 运维负责人 | 监控面板、阈值配置 |
| 日志与审计 | 是否记录用户输入、工具调用、参数摘要、返回状态、异常原因 | 运维负责人、安全负责人 | 日志样例、审计字段 |
| 数据脱敏 | 敏感信息是否脱敏;是否允许进入日志、训练数据或第三方模型 | 安全负责人 | 脱敏策略、字段清单 |
| 人工兜底 | 智能体失败或不确定时,是否能转人工;是否有人工接管入口 | 业务负责人 | 人工接管流程 |
| 灰度策略 | 是否先小流量灰度;是否支持快速关闭 | 运维负责人 | 灰度方案、开关配置 |
| 责任人 | 是否明确每个模块的业务 owner、技术 owner 和应急 owner | 项目经理 | 责任矩阵 |
智能体上线后,建议用可量化指标替代主观判断。常见指标口径如下:
任务完成率 = 无需人工干预且业务结果正确的任务数 / 总任务数。它衡量智能体是否真正闭环。建议按业务基线设定目标,例如初期达到 80%,稳定后逐步提升。
工具调用准确率 = 工具选择正确、参数合法、返回成功的调用次数 / 总工具调用次数。这个指标比“回答像不像人”更重要,因为它直接影响业务结果。
平均响应时长用于观察整体体验,P95 延迟用于发现长尾问题。智能体涉及多轮模型调用和工具调用,应同时关注端到端耗时和单工具耗时。
人工介入率 = 转人工或需要人工修正的任务数 / 总任务数。高人工介入率说明智能体能力或工具链不足,需要持续优化。
包括越权尝试次数、写操作审批率、重复创建次数、回滚成功率。对于涉及资金、库存、合同、权限变更的场景,这类指标必须单独监控。
包括单次任务 token 成本、工具调用成本、缓存命中率、上下文裁剪率。成本不应只看单次调用,而要看完成一个业务闭环的总成本。
指标目标必须结合业务基线设定。不能简单套用“完成率 95%”或“延迟 1 秒”这样的通用值。例如客服场景可能更关注首次解决率和人工转接率,采购场景更关注审批合规率和重复下单率。
在通用云平台中,智能体通常可以由以下能力组合支撑:
架构设计上,建议把智能体拆成“编排层”和“执行层”。模型负责理解和规划,工具层负责真实执行,权限层负责最小授权,审计层负责追踪每一次动作。不要把所有逻辑都塞进提示词或单个函数中,否则后期难以维护和排错。
AI Agent 的价值,不在于让模型“说得更像人”,而在于让模型能在受控条件下调用工具、访问知识、处理异常并完成业务闭环。企业团队在搭建智能体时,应先判断是否真的需要智能体,再设计工具描述、权限边界、失败回滚和监控指标。
更稳妥的落地路径是:先用工作流或普通应用跑通业务闭环,再逐步引入模型进行语义理解;先覆盖低风险只读工具,再开放受控写操作;先做小流量灰度,再扩大范围。只要场景判断准确、工具设计清晰、权限控制严格、指标可验证,智能体就能从概念演示走向稳定生产。