企业官网建设流程全解析

聊《Agentic AI到底能不能干活？别只看 Demo 和跑分》之前，先说一句实在的：别急着背概念，先看它在真实项目里到底解决什么问题。

摘要

摘要
去年我带团队做电商售后Agent，Demo跑起来丝滑，上线联调当晚直接翻车。复盘下来，问题不在模型推理，而在权限边界没画清、日志断链、可观测缺失。本文复盘那次联调故障的定位路径，给出权限、日志、兜底三笔账的工程化写法，供准备把Agent推上生产线的开发者参考。

目录

• 一次联调翻车：现象、排查、定位
• Agentic不是"会聊天"，是"能闭环执行"
• 自主性边界：Agent敢停手，比敢动手更重要
• 任务拆解：从单轮意图到多步工作流
• 可观测性：日志断链比模型幻觉更致命
• 安全约束：权限、兜底、责任边界
• 总结

---

目录

• 一次联调翻车：现象、排查、定位
• Agentic不是"会聊天"，是"能闭环执行"
• 自主性边界：Agent敢停手，比敢动手更重要
• 任务拆解：从单轮意图到多步工作流
• 可观测性：日志断链比模型幻觉更致命
• 安全约束：权限、兜底、责任边界
• 总结

一次联调翻车：现象、排查、定位

去年Q3，我们给一个中小电商客户做售后Agent，核心诉求：用户提退款请求，Agent自动校验订单状态、调用ERP接口、生成工单、推送通知。Demo阶段用 Claude 3.5 + LangGraph 跑通，所有 happy path 都绿了。

上线联调那天，真实订单流进来，Agent 直接抛异常。日志里只有一行：

tool_call_error: refund_order returned None

没有上下文，没有步骤轨迹，没有权限判定依据。第一反应是模型"幻觉"，换了一批 prompt，问题依旧。

排查过程分三步：

1. 验证现象：把 Demo 脚本拿到生产环境复跑，用同一笔测试订单，Agent 正常返回；换成真实订单，依然失败。说明不是模型问题，是环境或数据差异。
2. 排除配置错误：检查工具注册表、API Key、网络策略，全部正常。
3. 定位根因：加详细链路日志后，发现 Agent 在调用refund_order工具时，传入了order_id字段，但生产环境 ERP 接口要求的是biz_order_no。字段映射缺失，且权限层没有做输入校验，直接透传导致接口返回None。

责任边界很清晰：不是模型推理失败，是工具契约没对齐、权限层没做输入校验、日志没记录字段映射关系。

---

Agentic不是"会聊天"，是"能闭环执行"

很多人把 Agentic AI 理解为"更聪明的聊天机器人"，这是最大的认知偏差。

Demo 里的 Agent：用户问"退订单"，模型回复"好的，请问订单号是？"，然后调用工具，返回结果。全程单轮、无状态、无约束。

生产里的 Agent：用户提退款请求 → Agent 解析意图 → 校验订单状态（是否已发货、是否在售后期内） → 调用 ERP 接口 → 生成工单 → 推送通知 → 记录审计日志。多轮、有状态、有边界、有兜底。

两者的差距不在模型能力，而在工程化厚度。

# 生产级 Agent 工具调用骨架 async def execute_refund(agent_ctx: AgentContext, user_input: str) -> AgentResult: # 1. 意图解析 + 参数提取 intent = await parse_intent(user_input) if intent.action != "refund": return AgentResult(status="rejected", reason="意图不匹配") # 2. 权限校验：用户是否有退款权限 if not await check_permission(agent_ctx.user_id, "refund"): return AgentResult(status="forbidden", reason="无退款权限") # 3. 输入校验：字段完整性 if not validate_refund_input(intent.params): return AgentResult(status="invalid_input", reason="参数缺失") # 4. 工具调用 + 异常兜底 try: result = await call_erp_tool("refund_order", intent.params) except ERPConnectionError as e: logger.error(f"ERP调用失败: {e}", extra={"user_id": agent_ctx.user_id}) return AgentResult(status="tool_error", reason="ERP服务异常", retry=True) # 5. 结果写入 + 审计日志 await write_audit_log(agent_ctx, result) return AgentResult(status="success", data=result)

代码解释：

• 输入：agent_ctx包含用户身份、权限上下文；user_input是用户原始请求。
• 核心逻辑：意图解析 → 权限校验 → 输入校验 → 工具调用 → 结果写入，五步闭环。
• 输出：统一AgentResult结构，包含状态、原因、数据、是否可重试。
• 异常处理：工具调用失败不直接抛异常，而是捕获后返回结构化错误，支持重试或降级。

Demo 里的 Agent 通常只有第 4 步，生产级 Agent 必须有 1-5 步完整闭环。

---

自主性边界：Agent敢停手，比敢动手更重要

Agent 的"自主性"不是无限自主，而是在边界内自主。边界画不清，Agent 就会越权操作。

我们翻车那次，如果权限层做了输入校验，biz_order_no缺失时直接拒绝，就不会把错误参数透传到 ERP。自主性的边界由三件事定义：

1. 权限边界：Agent 能做什么，不能做什么。比如退款 Agent 不能修改商品价格。
2. 操作边界：Agent 能调用哪些工具，不能调用哪些接口。比如不能调用delete_order。
3. 结果边界：Agent 的输出来自哪里，是否经过校验。比如 ERP 返回的结果必须经过业务规则校验才能写入。

判断标准：一个 Agent 是否具备生产级自主性，看它敢不敢在不确定时停手。能停手的 Agent，比能动手的 Agent 更安全。

---

任务拆解：从单轮意图到多步工作流

Demo 里的 Agent 通常是单轮对话：用户问，模型答，工具调用，返回结果。生产里的 Agent 是多步工作流：意图解析 → 状态校验 → 工具调用 → 结果校验 → 后续动作。

任务拆解的核心是把大任务拆成可观测的子步骤，每步都有明确的输入、输出、异常处理。

# 多步工作流示例 workflow = { "parse_intent": {"handler": IntentParser, "timeout": 5}, "check_permission": {"handler": PermissionChecker, "timeout": 3}, "validate_input": {"handler": InputValidator, "timeout": 2}, "call_erp": {"handler": ERPTool, "timeout": 10, "retry": 3}, "write_audit": {"handler": AuditLogger, "timeout": 5}, }

每步都有超时和重试策略，整体工作流有超时控制。这种拆解方式让 Agent 从"黑盒推理"变成"白盒执行"，可观测、可调试、可回滚。

---

可观测性：日志断链比模型幻觉更致命

翻车那次最痛的点不是模型幻觉，是日志断链。我们只记录了工具调用的结果，没有记录：

• 意图解析的原始输入
• 权限校验的依据
• 字段映射关系
• 工具调用的完整请求/响应

没有这些，排查就是盲人摸象。

生产级 Agent 的可观测性要求：

1. 链路追踪：每个请求有唯一 trace_id，贯穿意图解析、权限校验、工具调用、结果写入全流程。
2. 步骤日志：每步执行都有日志，包含输入、输出、耗时、异常。
3. 审计日志：关键操作（退款、修改、删除）必须有审计日志，可追溯、可追责。

# 链路追踪示例 import uuid from opentelemetry import trace tracer = trace.get_tracer(__name__) async def execute_with_trace(agent_ctx, user_input): trace_id = uuid.uuid4().hex with tracer.start_as_current_span("agent_execute", trace_id=trace_id) as span: span.set_attribute("user_id", agent_ctx.user_id) span.set_attribute("trace_id", trace_id) # 意图解析 intent = await parse_intent(user_input) span.set_attribute("intent", str(intent)) # 权限校验 allowed = await check_permission(agent_ctx.user_id, intent.action) span.set_attribute("permission_granted", allowed) # 工具调用 result = await call_erp_tool(intent.action, intent.params) span.set_attribute("result_status", result.status) return result

代码解释：

• 输入：agent_ctx用户上下文，user_input用户请求。
• 核心逻辑：用 OpenTelemetry 生成 trace_id，每步执行记录 span 和属性。
• 输出：完整链路追踪数据，可接入 Jaeger、Tempo 等可观测平台。
• 异常处理：span 自动记录异常，无需手动捕获。

---

安全约束：权限、兜底、责任边界

Agent 上线前必须回答三个问题：

1. 权限边界：Agent 能做什么，不能做什么。权限配置要最小化，默认拒绝。
2. 兜底机制：工具调用失败怎么办？结果校验不通过怎么办？必须有降级策略。
3. 责任边界：Agent 的操作谁负责？模型推理错误、工具调用错误、权限配置错误，责任归属要清晰。

常见失败原因分类：

| 类型 | 特征 | 排查方法 |
|------|------|----------|
| 业务错误 | 模型推理正确，但业务规则不满足 | 检查业务日志、规则配置 |
| 配置错误 | 工具调用参数错误、权限配置错误 | 检查配置表、字段映射 |
| 环境错误 | 网络超时、服务不可用 | 检查基础设施、依赖服务状态 |

区分这三类错误，是快速定位问题的关键。

适用边界：

• 适合场景：工具调用明确、业务规则清晰、结果可校验的流程型任务。
• 不适合场景：需要高度创意、模糊决策、无明确规则的任务。
• 取舍：可观测性越强，工程复杂度越高。小团队可以优先保证核心链路可观测，非核心链路可以简化。

---

总结

Agent 从 Demo 到生产，差距不在模型能力，而在工程化厚度。权限、日志、可观测这三笔账，每一笔都直接影响上线成功率。

实战建议：

1. 权限先行：上线前把权限边界画清楚，默认拒绝，最小授权。
2. 日志断链比模型幻觉更致命：每步执行都有链路追踪，排查时才能快速定位。
3. 兜底机制不能少：工具调用失败、结果校验不通过，必须有降级策略。
4. 责任边界要清晰：模型推理错误、工具调用错误、权限配置错误，责任归属要明确。

Demo 跑得欢，上线就崩的 Agent，往往不是模型问题，是工程问题。把权限、日志、可观测这三笔账算清楚，Agent 才能真正干活。

资料展示

下面是我整理的AI大模型学习资料和工具包预览，适合收藏后按主题逐步学习。

如果你想看完整资料目录，可以在评论区留言「资料」；也欢迎告诉我你更关注AI大模型里的哪类内容。