type
Post
status
Published
date
Apr 27, 2026
slug
agent21
summary
tags
Agent
category
icon
password
很多团队做 Agent 的第一步，是把 LLM 接上几个工具：搜索、数据库、代码执行、HTTP 请求。这个阶段很快能做 Demo，但离生产级 Agent 还差一整套运行时系统。
生产级 Agent 不是一个“会调用工具的 Prompt”，而是一个具备 上下文管理、工具治理、权限控制、状态持久化、可观测性、安全隔离、评测闭环和部署运维能力 的系统。Claude Code 的公开文档里可以看到完整的 Agent loop、工具权限、hooks、sandbox、memory 和 OpenTelemetry 设计；OpenCode 则把工具、LSP、MCP、自定义 Agent、skills、权限规则做成了较完整的工程化形态；OpenClaw 更偏“长驻 Gateway + 多消息通道 + session 隔离 + 设备/节点配对”的 Agent 操作系统形态。(Claude Code)
1. 先定义：生产级 Agent 到底是什么？
一个生产级 Agent 系统，本质上是一个“可控的自主执行运行时”：它接收用户目标，构造上下文，规划或反应式地调用工具，读取观察结果，持续迭代，直到完成任务；同时它必须保证权限、成本、安全、可恢复、可审计。
可以把它拆成 9 个核心模块：
模块 | 作用 |
Gateway / API | 统一接入 CLI、Web、IM、Webhook、自动任务 |
Session Manager | 会话隔离、状态恢复、多用户边界 |
Agent Runtime | ReAct / Plan-Execute / 多 Agent 编排 |
Context Engine | Prompt、短期记忆、长期记忆、RAG、压缩 |
Tool Registry | 工具声明、schema、权限元数据、执行器 |
Permission Engine | allow / ask / deny、路径限制、命令限制、人工审批 |
Sandbox / Executor | Bash、代码、浏览器、数据库、云 API 的隔离执行 |
Event Store | 消息、tool call、observation、成本、错误、审批记录 |
Observability & Eval | trace、metric、log、回放、任务评测、红队测试 |
Claude Code Agent SDK 的公开文档明确描述了一个自主循环：接收 prompt，评估上下文，决定工具调用，执行工具，再把结果带回模型继续迭代，直到完成或达到限制；它还支持 max turns、成本限制、权限模式、上下文压缩和 subagent。(Claude Code)
2. 总体架构图
这个架构里，LLM 只是决策器，不是系统边界。真正的生产能力来自运行时、权限、工具治理、事件日志和观测系统。
3. 从成熟 Agent 抽象出的 5 条工程原则
3.1 Agent loop 要显式建模，而不是藏在 Prompt 里
Claude Code 的 Agent SDK 把 loop 建成可编程运行时，支持内置工具、工具权限、parallel read-only tools、顺序执行有副作用工具、上下文压缩、subagent 和预算限制。(Claude Code)
生产实践：不要让模型“自由发挥”整个任务流程。应该由 Runtime 控制：最多迭代几轮、最多花多少钱、哪些工具能用、哪些工具必须审批、失败后如何恢复。
3.2 工具必须声明 schema、风险等级和权限规则
OpenCode 的工具系统包括 bash、edit、write、read、grep、glob、LSP、skill、webfetch、websearch、自定义工具和 MCP 工具，并且通过 permission 配置控制 run / ask / deny。(OpenCode)
生产实践：每个工具都要有：
- 输入 JSON Schema
- 是否只读
- 是否有副作用
- 是否访问网络
- 是否访问敏感数据
- 是否需要人工确认
- 最大超时时间
- 审计字段
3.3 会话隔离比模型能力更重要
OpenClaw 的 Gateway 设计里，不同消息源、群聊、Webhook、cron 任务有不同 session 规则，并且明确提醒：如果多人能和同一个 Agent 说话，需要启用 DM 隔离，否则 Alice 的私密上下文可能被 Bob 看到。(OpenClaw)
生产实践：多用户 Agent 不能只靠 prompt 说“不要泄露上下文”。必须在 Session Manager、Memory Store、Vector DB、Tool Executor 层面做租户隔离。
3.4 安全不能只做一次审批，要做分层防御
Claude Code 的安全文档强调默认只读、编辑和命令需要权限、bash sandbox、路径限制、网络审批、prompt injection 防护、命令黑名单和 MCP 信任校验；OpenClaw 也强调 Gateway 是单一可信操作边界，不适合作为敌对多租户系统直接暴露。(Claude API Docs)
生产实践：权限控制要覆盖：
- 模型能看到什么
- Agent 能记住什么
- 工具能访问什么
- 命令能执行什么
- 网络能连到哪里
- 文件能改哪些路径
- 哪些动作必须人工确认
- 审计日志能否还原全过程
3.5 可观测性是 Agent 生产化的生命线
Claude Code 文档提到生产 Agent 需要看到工具调用、延迟、token、失败，并支持 OpenTelemetry metrics、logs、traces；OpenAI Agents SDK 也把 LLM generation、tool call、handoff、guardrail 等作为 trace span。(Claude Code)
生产实践：你需要能够回答：
- 为什么 Agent 调用了这个工具？
- 哪一步花了最多 token？
- 哪个工具最容易失败？
- 哪类任务最容易幻觉？
- 审批被拒绝后 Agent 怎么继续？
- 某次线上事故能不能完整回放？
4. 源码级骨架：Agent Runtime 怎么写？
下面用 TypeScript 给一个最小但可生产演进的骨架。
4.1 核心类型定义
这个模型有一个关键点：AgentDefinition 和 ToolSpec 是声明式的。不要把权限散落在业务代码里，而是让 Runtime 在执行前统一判断。
4.2 Agent loop
Claude Code 文档里提到 read-only tools 可以并行，而修改状态的工具需要顺序执行，这是生产级 Agent 非常重要的调度原则。(Claude Code)
5. Context Engine：Agent 成败的核心
Agent 的上下文不是简单拼 Prompt。生产系统里至少要分 5 层：
Claude Code 的 memory 文档中可以看到项目级 memory、自动记忆、按需加载 topic files、文件大小限制等设计；OpenCode 也有 skill 机制，通过
SKILL.md 把可复用行为按需加载。(Claude API Docs)5.1 推荐的上下文分层
层级 | 内容 | 生命周期 |
System Prompt | Agent 身份、行为边界、安全规则 | 版本级 |
Project Instructions | 项目架构、编码规范、部署规则 | 项目级 |
Session Memory | 当前对话摘要、已完成步骤、用户偏好 | 会话级 |
Working Memory | 当前任务 scratchpad、todo、tool observations | run 级 |
Long-term Memory | 用户明确允许保存的信息 | 用户级 |
RAG Context | 文档、代码、知识库检索结果 | 查询级 |
Tool Result | 文件读取、命令输出、API 返回 | turn 级 |
5.2 RAG 检索管线
生产级 RAG 要注意一个顺序问题：权限过滤必须在 rerank 和注入上下文之前完成。否则模型可能在中间环节看到无权访问的文档。
5.3 Context Engine 代码骨架
6. Tool Registry：工具不是函数，是受管控能力
MCP 规范把 Host、Client、Server 分开，并规定 Server 可以暴露 resources、prompts、tools；MCP tools 有名称、描述、输入 schema，并建议 UI 能展示工具调用、让人类确认或拒绝。(Model Context Protocol)
生产级 Tool Registry 应该长这样：
工具风险分级建议
等级 | 示例 | 默认策略 |
read | read、grep、glob、LSP hover | allow |
network | webfetch、websearch、HTTP GET | ask 或 allowlist |
write | edit、write、apply_patch | ask |
exec | bash、python、npm、docker | ask + sandbox |
critical | deploy、db write、email send、cloud IAM | ask + 二次确认 + 审计 |
OpenCode 默认允许 read，但
.env 默认拒绝读取；它还支持按工具、命令模式、路径、agent 做细粒度权限配置。(OpenCode)7. Permission Engine：生产级 Agent 的刹车系统
一个可参考的权限判断顺序：
Claude Code SDK 的权限评估顺序包含 hooks、deny rules、permission mode、allow rules、
canUseTool callback；hooks 可以在 PreToolUse 阶段阻断工具调用。(Claude Code)7.1 权限策略配置示例
7.2 Permission Engine 代码骨架
8. Sandbox：工具执行必须和 Agent Runtime 隔离
Claude Code 的安全文档提到 bash 工具会在 sandbox 中运行，并限制写入启动目录和子目录；部署 Agent 时还需要最小权限、隔离、纵深防御，因为 Agent 可以执行代码、访问文件和外部服务，并可能受到 prompt injection 影响。(Claude API Docs)
推荐的执行隔离层级：
场景 | 隔离方式 |
本地 CLI | workspace-only + shell allowlist |
企业内网 | container sandbox + network allowlist |
多租户 SaaS | microVM / Firecracker / gVisor |
浏览器操作 | 独立 browser context + 无痕 profile |
数据库写入 | dry-run + transaction + approval |
云资源操作 | 临时凭证 + 最小 IAM + 审计 |
ToolBus 代码骨架
9. 多 Agent 设计：不要一上来就做“群聊式 Agent”
OpenCode 支持 primary agent、subagent、build/plan/reviewer 等不同 agent，并允许为 agent 配置不同 model、tools、permission；Claude Code 也使用 subagent 来获得新的上下文窗口、隔离任务。(OpenCode)
推荐的生产级多 Agent 切分：
Agent | 职责 | 工具权限 |
Planner | 拆解任务、输出计划 | 只读 |
Explorer | 搜索代码、查文档、RAG 检索 | read / grep / webfetch |
Builder | 修改代码、生成补丁 | read / edit / bash ask |
Reviewer | 审查 diff、安全风险、测试建议 | 只读 |
Verifier | 运行测试、验证结果 | bash ask |
Reporter | 总结结果、生成交付说明 | 无副作用工具 |
多 Agent 的关键不是“越多越智能”，而是 隔离上下文和权限。比如 Planner 不应该能执行
bash，Reviewer 不应该能修改文件，Verifier 可以跑测试但不能部署。10. Gateway：从本地 Agent 进化到企业 Agent
如果只是本地 coding agent，CLI 就够了。但生产级系统通常需要 Gateway：
Gateway 负责接入 Web、CLI、Slack、Webhook、定时任务、自动化系统；同时维护 session、认证、限流、事件流、审批回调和节点连接。
OpenClaw 的 Gateway 设计是一个长驻进程，连接 WhatsApp、Telegram、Slack、Discord、Signal、iMessage、WebChat 等消息面，控制客户端和自动化通过 WebSocket 连接，节点也通过 WebSocket 接入，并用 JSON Schema 校验帧、使用认证、幂等键和设备配对。(OpenClaw)
Gateway API 示例
幂等键非常重要。OpenClaw 的 wire protocol 明确要求有副作用的方法使用 idempotency key，这能避免网络重试导致重复发邮件、重复部署、重复改库。(OpenClaw)
11. 状态持久化：Agent 必须可恢复、可回放
LangGraph 的 durable execution 文档强调：长时间任务、人类审批、超时或失败场景下，需要保存进度并从中断处恢复；有副作用的操作应该包进 task，并注意确定性和幂等性。(LangChain 文档)
Event Store 事件模型
推荐存储选型
数据 | 推荐存储 |
Run / Session / Event | PostgreSQL |
Stream / Queue | Redis Streams / Kafka |
文件产物 | S3 / MinIO |
向量索引 | pgvector / Milvus / Qdrant |
Memory | PostgreSQL + Vector DB |
Trace | OpenTelemetry Collector |
Prompt / Eval 版本 | Git + DB version table |
12. Hooks：把组织规则插入 Agent 生命周期
Claude Code hooks 支持在 SessionStart、SessionEnd、UserPromptSubmit、Stop、PreToolUse、PostToolUse 等生命周期点执行 shell、HTTP 或 LLM prompt；PreToolUse 可以阻断工具调用。(Claude API Docs)
生产系统里 hooks 很适合做这些事：
Hook | 典型用途 |
SessionStart | 加载项目规范、检查 workspace |
UserPromptSubmit | 注入安全策略、检测 prompt injection |
PreToolUse | 权限校验、命令黑名单、路径限制 |
PostToolUse | secret redaction、输出压缩、审计 |
Stop | 自动测试、生成总结、更新 memory |
SessionEnd | 清理 sandbox、落盘 trace |
Hook 配置示例
13. 安全基线：从第一天就要做
OpenClaw 的安全文档建议先明确谁能和 Agent 对话、Agent 能在哪里行动、能触碰哪些资源，并提供 hardened baseline：本地 gateway、token auth、DM isolation、workspaceOnly、exec deny 或 ask、默认禁用高危控制工具等。(OpenClaw)
生产级安全 checklist
类别 | 必做项 |
身份认证 | 用户、服务、节点、MCP server 都要认证 |
租户隔离 | session、memory、vector、workspace、trace 全隔离 |
Prompt Injection | 外部文档降权、工具结果标记为 untrusted |
Secret 防护 | .env 默认禁止、输出脱敏、日志脱敏 |
文件系统 | workspaceOnly、路径规范化、防止 ../ |
命令执行 | sandbox、allowlist、超时、无 root、无宿主 Docker socket |
网络访问 | egress allowlist、内网地址阻断 |
人工审批 | write / exec / critical tool 强制审批 |
审计日志 | tool input/output、审批人、时间、结果 |
插件治理 | MCP server、skills、自定义工具需要签名或审核 |
数据保留 | session transcript、artifact、memory 有过期策略 |
MCP 官方规范也提醒，MCP 场景涉及任意数据访问和代码执行，必须考虑用户同意、访问控制、工具安全等问题。(Model Context Protocol)
14. 可观测性：不要只看最终回答
生产级 Agent 至少要采集 4 类数据：
推荐指标：
指标 | 含义 |
task_success_rate | 任务成功率 |
tool_error_rate | 工具失败率 |
approval_rate | 需要人工审批的比例 |
approval_reject_rate | 审批拒绝比例 |
avg_turns_per_run | 平均 Agent 迭代轮数 |
avg_cost_per_run | 平均成本 |
p95_latency | 端到端延迟 |
context_hit_rate | RAG 命中率 |
hallucination_rate | 幻觉率 |
rollback_rate | 需要回滚的比例 |
Claude Code 的 OpenTelemetry 说明把 model request 和 tool execution 都作为 span，这个粒度很适合生产排障。(Claude Code)
15. 评测体系：Agent 不能只靠人工体验
生产 Agent 的评测要覆盖 5 层：
层级 | 评测内容 |
Prompt Eval | 指令遵循、格式稳定性 |
RAG Eval | Recall、MRR、NDCG、faithfulness |
Tool Eval | 工具选择是否正确、参数是否正确 |
Trajectory Eval | 多轮路径是否合理 |
Safety Eval | 越权、泄密、危险命令、prompt injection |
轨迹评测样例
自动评测伪代码
16. 推荐落地路线：从 MVP 到生产
阶段一：本地 MVP
目标：做出一个可用的单 Agent CLI。
能力范围：
- read / grep / glob
- edit 需要确认
- bash 需要确认
- SQLite / Postgres 记录 event
- 简单 system prompt
- max turns / timeout / cost limit
不要一开始就做：
- 多 Agent
- 自动部署
- 浏览器控制
- 云资源操作
- 长期记忆自动写入
阶段二：项目级 Agent
目标：让 Agent 真正理解一个代码仓库或知识库。
新增能力：
- project instructions
- workspace index
- RAG 检索
- session summary
- tool observations 压缩
- LSP 工具
- 自动测试建议
- diff review
OpenCode 的工具体系里包含 LSP diagnostics、hover、definition、references 等操作，这类工具对 coding agent 很关键，因为它让 Agent 不只靠文本 grep，而能利用语言服务理解代码。(OpenCode)
阶段三：安全可控 Agent
目标：让 Agent 可以进入真实研发流程，但不能越权。
新增能力：
- permission policy
- human approval
- hooks
- secret redaction
- sandbox
- network allowlist
- audit log
- eval regression
阶段四：生产 Gateway
目标：接入真实用户、真实消息通道和真实业务系统。
新增能力：
- Web / Slack / CLI / Webhook
- session isolation
- SSE / WebSocket event stream
- approval callback
- idempotency key
- queue worker
- retry / resume
- OpenTelemetry
- admin console
阶段五：企业级 Agent Platform
目标：多个团队、多个 workspace、多个 Agent 共用平台能力。
新增能力：
- multi-tenant isolation
- RBAC / ABAC
- agent marketplace
- tool marketplace
- MCP server governance
- prompt / agent versioning
- eval dashboard
- cost center
- policy as code
17. 一个生产级目录结构
18. 最容易踩的坑
坑 | 后果 | 解决方案 |
只写 Prompt，不建 Runtime | 不可控、不可恢复 | 显式 Agent loop |
工具无权限分级 | 越权、删库、泄密 | Tool risk + Permission Engine |
RAG 不做 ACL | 跨租户泄露 | 检索前强制权限过滤 |
tool output 直接进上下文 | prompt injection | 标记 untrusted、压缩、过滤 |
没有 event log | 事故无法复盘 | event sourcing |
没有 sandbox | 命令执行风险 | container / microVM |
没有 eval | 每次升级都靠感觉 | golden set + regression |
memory 自动乱写 | 信息污染 | 显式保存、可删除、可追踪 |
多 Agent 滥用 | 成本高、路径不可控 | 先单 Agent，再按权限拆分 |
审批体验差 | 用户疲劳 | 风险分级 + allow once / always |
Claude Code 的安全设计里也提到要避免 prompt fatigue，低风险操作可以减少打扰，高风险操作必须明确确认。(Claude API Docs)
19. 最小生产可用 Checklist
上线前至少满足：
每个 Agent 有独立配置、模型、工具、权限
每个工具有 schema、risk、timeout、审计字段
write / exec / critical 工具默认 ask
.env、secret、私钥默认 denyworkspace 路径强隔离
tool call 全量落 event store
approval 可恢复、可审计
RAG 检索有 tenant ACL
session memory 不跨用户泄露
sandbox 无 root、无宿主敏感挂载
所有输出日志脱敏
trace 覆盖 LLM、tool、approval
有 golden eval 和安全 eval
支持 max turns、timeout、cost limit
支持中断恢复和幂等重试
20. 结论
自建 Agent 系统的关键，不是把模型换成最新的，也不是让 Prompt 更长，而是把 Agent 当成一个 受控的分布式执行系统 来设计。
Demo 级 Agent 关注“能不能做”。生产级 Agent 关注“能不能安全、稳定、可恢复、可审计、可评测地做”。
参考 Claude Code，可以学习它的 agent loop、权限、hooks、sandbox、memory 和 observability；参考 OpenCode，可以学习工具注册、LSP、MCP、skills、多 Agent 和 per-agent permissions；参考 OpenClaw，可以学习 Gateway、session isolation、WebSocket protocol、设备配对和安全边界。把这些能力抽象出来，你会得到一个真正可落地的 Agent Platform，而不是一个脆弱的 LLM wrapper。
分享