Agentic AI从Demo到团队：我花三个月才搞懂的权限和日志-拓冰建站

如果你正准备往大模型方向转，《Agentic AI到底能不能干活？别只看 Demo 和跑分》这类问题别只看热度。更重要的是判断自己该补哪块能力，以及怎么证明你真的会。

摘要

去年开始做Agentic AI项目时，我以为模型智商是核心。接进团队协作后才发现，权限配置和日志可观测才是Demo和生产之间的真正鸿沟。本文复盘一个实际项目从个人试用到团队协作的踩坑过程，重点讲任务拆解、权限边界和可观测性设计。

---

Agentic不是聊天机器人

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

聊天机器人的交互模式是：用户提问→模型回答→结束。Agent不一样，它需要感知环境、做出决策、执行动作，然后再次感知。这个循环可以重复多次，直到任务完成。

我做的那个项目，最初就是一个代码补全工具。个人试用阶段，Claude Code或者Codex能独立完成单文件修改，看起来丝滑得很。但一旦接入团队，问题就来了：Agent不知道项目整体结构，它改了一个文件，可能破坏了其他模块的依赖关系。

关键判断标准：如果一个任务只需要"理解+输出"，那是聊天机器人。如果需要"理解+决策+执行+验证"，才是Agent。

---

自主性边界：什么该让Agent做

团队接手Agent项目，最先问的问题是：这个Agent能自主到什么程度？

我的经验是，不要追求完全自主。Demo里展示的"全自动完成需求"，在生产环境往往是灾难。

具体做法是分三层：

1. 感知层：Agent可以读取代码、搜索文档、查看日志。这部分完全放开，模型擅长理解上下文。
2. 决策层：Agent可以提出方案，但关键决策点需要人工确认。比如"是否要重构这个模块"、"是否要删除这个文件"。
3. 执行层：Agent可以执行命令，但涉及生产环境、数据库写操作、线上部署的，必须有人工审批。

我见过一个团队把Agent权限配得太松，结果Agent在测试环境执行了清理脚本，把一周的测试数据全删了。不是模型蠢，是权限边界没划清楚。

取舍建议：个人试用阶段可以适当放开，让模型多试错。团队协作阶段必须收紧，宁可多几次确认，也不要出事故。

---

任务拆解：从模糊需求到可执行步骤

Agent最容易出现的问题是：需求太模糊，模型不知道怎么下手。

比如用户说"优化一下登录流程"，这个需求Agent根本无法直接执行。它需要拆解成：

找到登录相关的代码文件
分析当前流程的性能瓶颈
提出优化方案
修改代码并测试

实战建议：

不要指望Agent能自己理解模糊需求。在项目初期，花时间在需求拆解上，把大任务拆成小步骤，每一步都有明确的输入输出。

# 任务拆解示例：登录流程优化 task_breakdown = [ { "step": 1, "action": "read_files", "target": ["auth/login.py", "auth/middleware.py"], "output": "当前登录流程的代码结构" }, { "step": 2, "action": "analyze_performance", "input": "代码结构", "output": "性能瓶颈报告" }, { "step": 3, "action": "propose_solution", "input": "性能报告", "output": "优化方案（需人工确认）" }, { "step": 4, "action": "implement", "input": "确认的方案", "output": "修改后的代码" }, { "step": 5, "action": "test", "input": "修改后的代码", "output": "测试结果" } ]

每个步骤的输入输出要写清楚，这样Agent执行时才知道下一步该做什么。

---

可观测性：日志比模型智商更重要

这是我最想强调的部分。

Demo阶段，模型输出正确，你觉得一切正常。但上线后，Agent可能执行了100步操作，其中第47步出了问题，你根本不知道发生了什么。

可观测性三要素：

1. 执行日志：每一步操作都要记录，包括输入、输出、耗时、模型调用次数。
2. 状态快照：Agent执行过程中，关键状态要保存。比如文件修改前的内容、数据库操作前的数据。
3. 错误追踪：出错时要有堆栈信息，知道是模型理解错了、工具调用失败了、还是权限不足。

我推荐用一个简单的日志结构：

{ "trace_id": "abc-123-xyz", "step": 3, "action": "propose_solution", "input": { "file": "auth/login.py", "issue": "token验证耗时过长" }, "output": { "solution": "引入缓存机制", "confidence": 0.85 }, "cost": { "tokens": 1250, "latency_ms": 3400 }, "status": "pending_approval" }

有了这些日志，出问题时可以回溯，知道Agent在哪个步骤做了什么，模型为什么这么决策。

团队接手时的检查清单：

[ ] 每个Agent调用都有唯一trace_id
[ ] 执行日志包含输入输出和耗时
[ ] 错误信息足够详细，能定位到具体步骤
[ ] 关键状态有快照，可回滚

---

安全约束：权限配置是上线前必过的一关

Demo阶段，Agent可能用你的个人账号，权限是开放的。但团队协作时，必须用专门的Service Account，权限要严格限制。

权限配置原则：

1. 最小权限：Agent能访问的资源，只给它完成任务所需的最小权限。
2. 环境隔离：开发、测试、生产环境的权限要严格区分。Agent在测试环境有写权限，在生产环境只能读。
3. 操作审计：所有Agent执行的操作都要记录，包括谁创建的Agent、什么时间执行的、修改了什么文件。

我见过最严重的案例：一个团队的Agent被配置了生产数据库的写权限，结果模型在优化查询时，误删了一张表。不是模型故意破坏，是权限配错了。

权限配置示例：

agent_permissions: read: - "code_repository/**" - "documentation/**" - "test_results/**" write: - "code_repository/src/**" # 只能写源码 - "test_results/**" # 可以写测试结果 execute: - "npm test" # 可以运行测试 - "npm run build" # 可以构建 deny: - "production_db/**" # 禁止访问生产数据库 - "deploy/**" # 禁止执行部署 - "user_data/**" # 禁止访问用户数据

交接文档要点：