同样是Agentic AI，为什么有的能干活有的只能演示？

头像违规？？

231人浏览 · 2026-08-18 22:26:02

头像违规？？ · 2026-08-18 22:26:02 发布

聊《同样是Agentic AI，为什么有的能上线、有的只能演示？》之前，先说一句实在的：别急着背概念，先看它在真实项目里到底解决什么问题。

摘要

摘要：最近团队接入 Claude Code 和 Codex 做协作开发，表面看效率提升明显，但真正上线后才发现"能跑 Demo"和"能扛生产"之间差了一大截。本文复盘一次 Agent 从演示到上线的真实踩坑经历，重点讲清楚任务拆解、可观测性、安全约束三个最容易忽略的工程细节，以及学习路线上该先补什么、暂时放什么。

---

Agentic 的定义：不止是"会调工具"
自主性边界：Agent 不该越权的三件事
真实案例：一个任务拆解失败的协作场景
排查过程：从"能跑"到"崩了"的链路还原
代码解释：可观测日志的关键结构
失败原因：业务、配置、环境三类的区分方法
适用边界：什么时候该用、什么时候别用
总结：学习路线上的取舍建议

---

Agentic 的定义：不止是"会调工具"
自主性边界：Agent 不该越权的三件事
真实案例：一个任务拆解失败的协作场景
排查过程：从"能跑"到"崩了"的链路还原
代码解释：可观测日志的关键结构
失败原因：业务、配置、环境三类的区分方法
适用边界：什么时候该用、什么时候别用
总结：学习路线上的取舍建议

Agentic 的定义：不止是"会调工具"

文章插图 1

很多人对 Agentic AI 的理解停留在"能调用工具"。但真正决定一个 Agent 能不能上线的，不是它能不能调工具，而是它在什么条件下调、调错了怎么回退、结果能不能被追踪。

我见过太多 Demo 漂亮的 Agent，上线后第一件事就是：任务跑到一半卡死，没有人知道卡在哪，也没有人能决定是重试还是放弃。

Agentic 的核心不是"自主"，而是可控的自主。区别在于，前者是模型自己跑，后者是模型在框架约束下跑。

---

自主性边界：Agent 不该越权的三件事

文章插图 2

团队刚用 Claude Code 做代码生成时，所有人都觉得"太爽了"。但很快暴露问题：Agent 会自己决定重构模块、会直接提交代码、会在没有 review 的情况下改生产配置。

自主性不是越大越好，上线前必须明确三条边界：

1. 写权限边界：Agent 能写哪些目录、哪些文件类型，必须显式配置，不能默认全开
2. 执行权限边界：subprocess、os.system 这类调用必须白名单控制
3. 提交权限边界：代码生成可以放开，但 commit 和 push 必须人工确认

这三条不是建议，是上线前的硬性要求。 Demo 阶段可以放开，但进入协作流程就必须收。

---

真实案例：一个任务拆解失败的协作场景

场景：团队让 Agent 完成"为现有 API 添加分页查询功能"。

输入：

现有代码仓库路径：/project/api-service
任务描述：在 /users 接口增加 page 和 size 参数，返回分页结果
使用的工具：文件读取、代码编辑、终端执行

步骤（Agent 实际执行）：

1. 读取了 routes/users.py，理解现有结构
2. 直接修改了路由文件，添加了分页参数解析
3. 修改了 service 层，添加了分页逻辑
4. 运行了 pytest，测试通过
5. 直接执行了 git commit -m "add pagination"
6. 尝试执行 git push，被权限拦截

可观察结果：

代码逻辑正确，测试通过
但 Agent 在修改 service 层时，没有读取现有测试文件，导致部分边界 case 没覆盖
commit 信息过于简略，后续 review 困难
最关键的问题：Agent 没有记录它改动了哪些文件，review 时需要人工逐文件对比

这个案例的失败不是模型能力问题，是任务拆解不完整——Agent 不知道"改代码"和"确保质量"是两件事。

---

CSDN资料领取方式

排查过程：从"能跑"到"崩了"的链路还原

上线后第一个线上问题：Agent 在处理复杂任务时，偶尔会陷入无限循环。

现象：任务执行时间超过 10 分钟，CPU 占用持续 100%，没有任何输出。

验证动作：
1. 检查 Agent 的日志，发现循环发生在"任务规划"阶段，模型反复生成相同的子任务
2. 检查工具调用记录，发现某个工具返回了空结果，但 Agent 没有判断空结果的语义，继续用空结果发起下一次调用
3. 检查超时配置，发现默认超时是 30 分钟，太长导致问题持续

排除结果：

不是模型本身的问题，同一个 prompt 在简化场景下正常工作
不是工具本身的问题，工具返回空结果是正常的业务场景
问题出在循环检测和结果验证的缺失

最终的修复方案：在 Agent 框架层面增加两步——① 记录最近 N 步的子任务序列，检测到重复则强制终止；② 工具返回空结果时，要求模型明确说明"是否需要重试或跳过"。

---

代码解释：可观测日志的关键结构

下面这段代码是我们团队在 Agent 框架中增加的可观测层，核心思路是把 Agent 的每一步决策都记录下来，而不是只记录最终结果。

import time
import json
from typing import List, Dict, Any

class ObservableAgent:
    def __init__(self, base_agent, logger):
        self.base_agent = base_agent
        self.logger = logger
        self.execution_log: List[Dict] = []

    def run(self, task: str, max_steps: int = 10) -> Dict[str, Any]:
        start_time = time.time()
        step_count = 0
        context = {"task": task, "steps": []}

        try:
            while step_count < max_steps:
                step_start = time.time()

                # 记录当前状态
                snapshot = {
                    "step": step_count,
                    "timestamp": step_start,
                    "status": "running"
                }

                # 调用基础 Agent 执行一步
                result = self.base_agent.step(context)

                # 记录结果
                snapshot.update({
                    "duration_ms": (time.time() - step_start) * 1000,
                    "tool_called": result.get("tool"),
                    "tool_output": self._sanitize_output(result.get("output")),
                    "status": "completed"
                })

                self.execution_log.append(snapshot)
                self.logger.info(json.dumps(snapshot, ensure_ascii=False))

                # 检测循环：检查最近3步是否重复
                if self._detect_loop():
                    snapshot["status"] = "loop_detected"
                    self.execution_log.append(snapshot)
                    raise LoopException("Detected repetitive task pattern")

                # 检查是否完成
                if result.get("done"):
                    break

                step_count += 1

        except Exception as e:
            self.execution_log.append({
                "step": step_count,
                "status": "error",
                "error": str(e)
            })
            raise
        finally:
            context["total_duration_ms"] = (time.time() - start_time) * 1000
            context["total_steps"] = step_count

        return context

    def _detect_loop(self) -> bool:
        """检测最近3步的子任务是否重复"""
        if len(self.execution_log) < 3:
            return False
        recent = self.execution_log[-3:]
        tools = [s.get("tool_called") for s in recent]
        return len(set(tools)) == 1 and all(t is not None for t in tools)

    def _sanitize_output(self, output: Any) -> str:
        """脱敏处理，避免日志泄露敏感信息"""
        if isinstance(output, str):
            return output[:500]  # 截断过长输出
        return str(output)[:500]

逐段解释：