这篇我按“先跑起来、再讲取舍”的方式写《大家都在聊Agentic AI，企业真正需要的却不是更多 Demo》。概念会讲，但重点放在代码怎么组织、哪里容易踩坑。

摘要

最近翻了几家公司的 JD，发现一个挺有意思的现象：招 Agentic AI 开发的，要求里反复出现"任务拆解""工具调用""错误恢复""权限控制"这几个词。但真正能把这些落地的候选人，简历上写的要么是个人 Demo，要么是 RAG 检索之类的基础能力。

我这边团队前阵子把 Claude Code 和 Codex 接进协作流程，联调阶段集体踩坑，权限、日志、异常恢复一个没跑通。今天想把这段时间复盘的东西整理出来，不讲概念，讲判断标准和练习顺序。

---

目录

• Agentic 到底是什么，别被 Demo 骗了
• 自主性不是自由度，是边界清晰度
• 任务拆解：从一句话到可执行步骤
• 可观测性：联调翻车的元凶
• 安全约束：别等出事才补
• 总结：从 Demo 到生产的距离

Agentic 到底是什么，别被 Demo 骗了

很多人对 Agentic 的理解还停留在"能自动跑脚本的聊天机器人"。我接触的项目里，能明确说清楚边界和约束的不到三成。

本质上，Agentic 系统要回答三个问题：它知道自己在做什么？它能调用什么工具？它做错了怎么收场？

ChatGPT 能回答前两个，但不会主动处理第三个。Agent 必须把第三个问题作为一等公民来设计。

我们团队之前有个坑：把工具调用能力直接塞进 LLM，没做权限隔离，Agent 第一次运行就把测试库的数据清了。不是模型笨，是没人定义清楚"它能做什么"。

---

自主性不是自由度，是边界清晰度

这是我踩过最深的坑。个人用 Agent 很爽，因为失败成本低；团队用 Agent 很痛，因为一次失控可能影响整个交付。

自主性的核心不是"让它做更多"，而是"让它知道不能做什么"。

我在项目里总结了一个责任清单，每次接入新工具都要过一遍：

| 动作 | 是否需要人工确认 | 失败后如何处理 |
|------|----------------|--------------|
| 读取文件 | 否 | 记录日志，返回错误 |
| 执行命令 | 是 | 记录命令内容，人工审批 |
| 写入生产环境 | 禁止 | 直接拒绝，告警 |
| 删除数据 | 是 | 二次确认，保留快照 |

这个表不是理论，是翻车之后写的。写完之后团队再也没出过权限事故。

---

任务拆解：从一句话到可执行步骤

JD 里反复提到"任务拆解能力"，但很少有教程讲清楚怎么练。

我见过两种拆解方式：一种是让模型自己分解，一种是人工定义好框架让模型填充。前者在简单场景可行，后者在复杂场景更稳。

我们项目里用的是混合策略：

class TaskPlanner:
    def __init__(self, llm_client, tool_registry):
        self.llm = llm_client
        self.tools = tool_registry

    def decompose(self, goal: str) -> list[Step]:
        # 先让模型理解目标
        intent = self.llm.extract_intent(goal)

        # 再映射到可用工具
        steps = []
        for tool in self.tools.available_tools:
            if tool.matches(intent):
                step = Step(
                    tool=tool.name,
                    params=tool.prepare_params(intent),
                    safety_check=self.safety_policy(tool)
                )
                steps.append(step)
        return steps

关键点：safety_check 这一步很多人会漏。每个 Step 都要过安全策略，不是最后才检查。

---

可观测性：联调翻车的元凶

这是我团队踩坑最多的地方。Agent 跑起来之后，你根本不知道它做了什么、为什么这么做。

我们后来加了一套完整的日志追踪：

import uuid
from datetime import datetime

class Observability:
    def __init__(self):
        self.trace_id = str(uuid.uuid4())
        self.log = []

    def record_tool_call(self, tool_name: str, params: dict, result: dict, duration: float):
        entry = {
            "trace_id": self.trace_id,
            "timestamp": datetime.now().isoformat(),
            "tool": tool_name,
            "params": self.sanitize(params),  # 过滤敏感信息
            "result": result,
            "duration_ms": int(duration * 1000)
        }
        self.log.append(entry)

    def sanitize(self, data: dict) -> dict:
        # 过滤密码、token 等敏感字段
        sensitive_keys = {"password", "token", "api_key", "secret"}
        return {k: v for k, v in data.items() if k not in sensitive_keys}

这套东西看起来简单，但真正跑起来之后，排查问题效率提升了不止一个量级。以前联调一个 Agent 要半天，现在看 trace 几分钟定位问题。

---

安全约束：别等出事才补

个人 Demo 阶段，安全约束基本可以忽略。但一进入团队协作，这就是生死线。

我们总结了几条铁律：

1. 权限最小化：Agent 能访问的资源，只给完成任务所需的最小范围
2. 操作可回滚：任何写操作都要有对应的撤销方案
3. 关键动作人工确认：删除、部署、修改配置这类操作必须有人点确认
4. 审计日志不可篡改：日志本身要受到保护，防止 Agent 自己删掉痕迹

这些不是建议，是事故之后写的规矩。

---

总结：从 Demo 到生产的距离

Agentic AI 不是什么新概念，但真正能过生产环境考验的很少。原因很简单：大部分人只练了"让它跑起来"，没练"让它安全地跑起来"。

如果你准备往这个方向走，建议按这个顺序练习：

1. 先写一个简单的工具调用脚本，理解 LLM 如何输出结构化指令
2. 加一个任务拆解模块，把大目标拆成可执行步骤
3. 加上权限检查和日志记录，模拟团队协作场景
4. 最后加上错误恢复和回滚机制

JD 里那些要求，拆开来看就是这四步。能完整做下来，比十个 Demo 都有用。

---

最近在团队里推行这套规范，联调效率明显提升。如果你也在做类似的事情，欢迎交流踩坑经验。

资料展示

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

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