Harness Engineering 如何驱动云端智能体：腾讯云ADP 的设计实践

导语

Agent 不只是模型，Agent = Model + Harness。 模型负责推理，Harness 负责工具、状态、权限、上下文、执行环境、恢复、评估、观测和反馈闭环。 Agent Harness不是一个花哨的新名词，而是 Agent 从 demo 走向生产之后必然出现的工程抽象。

为什么需要Agent Harness

业界提出 agent harness，本质上是因为大家逐渐发现：只靠"更强的模型 + 一个提示词"不足以稳定完成真实复杂任务。模型能力越强，越需要一个工程化外壳来承接它的行动、状态、安全、反馈和恢复能力。这个外壳就是 harness。

Agent = Model + Harness

Model 负责理解、推理、生成决策；Harness 负责让这些决策在真实环境中可执行、可控、可恢复、可评估。

注：业界权威学术和开源对Harness的观点参考：附录-业界对Harness理解

实际生成过程中Agent遇到的问题：

真实任务不是一次模型调用能完成的

早期很多 LLM 应用是"用户输入 -> 模型输出"。但 Agent 要完成的是长链路任务，比如：

• 修改一整个代码仓库
• 调试失败测试
• 分析线上日志
• 操作浏览器完成业务流程
• 调用多个 API 完成跨系统任务
• 长时间运行、等待外部事件、恢复上下文

这些任务需要多轮循环：观察环境 -> 思考下一步 -> 调用工具 -> 读取结果 -> 调整计划 -> 继续执行

模型需要"手"，而不只是"大脑"

模型本身只能生成文本或结构化输出。要真正干活，它需要：

• 读文件
• 写代码
• 执行 shell
• 调用 API
• 查询数据库
• 提交 PR
• 跑测试
• 读取日志
• 调 MCP 工具

长周期任务需要状态管理

一次多轮聊天，上下文会满，进程可能会挂，容器可能会重启，任务可能跨小时甚至跨天。 如果没有 harness，Agent 的状态通常散落在：

• 模型上下文里
• 临时文件里
• 容器内存里
• 工具返回结果里
• 用户聊天记录里

这很脆弱，所以需要管理：

• session 日志
• 任务计划
• 中间结果
• 文件变更
• 工具调用历史
• 上下文压缩
• 失败恢复
• wake/resume 机制

长任务不能只依赖模型当前上下文，必须有外部持久状态和交接机制

Agent 需要反馈闭环，而不是盲目执行

模型会犯错。尤其是 coding agent，常见问题包括：

• 改错文件
• 编译不过
• 测试失败
• 风格不一致
• 引入架构违规
• 误删用户改动
• 过度重构
• 没理解真实约束

人类工程师写代码时会依赖大量反馈：

• 编译器
• 单元测试
• linter
• 类型检查
• code review
• 运行时日志
• 产品验收

安全和权限管理

Agent 一旦能执行工具，就有安全问题：

• 能不能读敏感文件？
• 能不能访问生产数据库？
• 能不能调用付费 API？
• 能不能提交代码？
• 能不能发消息、删资源、改配置？
• 凭证是否暴露给模型？
• 工具调用是否需要人工审批？

如果把 token、代码、shell、网络访问全部丢进同一个环境，风险很高。提示注入也可能诱导模型读取密钥、泄露数据或执行危险命令。

所以 harness 通常需要提供：

• sandbox 隔离
• 权限分级
• 工具 allowlist
• 人工审批
• 凭证托管
• 审计日志
• 网络隔离
• 危险操作拦截

这也是 Anthropic Managed Agents 强调 session、harness、sandbox 解耦的重要原因之一：凭证不应该直接进入 sandbox，工具访问应该通过受控代理完成。

多 Agent 协作也需要 Harness 编排

复杂任务往往不是一个 Agent 单线完成，而是多个角色协作：

• planner 负责拆任务
• executor 负责执行
• reviewer 负责检查
• evaluator 负责验收
• researcher 负责查资料
• coder 负责改代码

这些 Agent 怎么分工？怎么传递上下文？谁有权限执行工具？失败后谁重试？什么时候终止？ 这些也是 harness 或 agent runtime 的职责。

产品化 Agent 需要可观测性和可运维性

真实生产环境里，Agent 不能是黑盒。团队需要知道：

• 它为什么做这个决策？
• 调了哪些工具？
• 哪一步失败了？
• token 花在哪里？
• 哪些任务耗时最长？
• 哪些工具失败率最高？
• 哪些 prompt 或策略导致质量下降？
• 用户能否回放整个过程？

所以 harness 还要承担：

• tracing
• logging
• metrics
• replay
• checkpoint
• cost tracking
• error taxonomy
• eval 数据采集

OpenAI Agents SDK、LangGraph、Microsoft Agent Framework 都强调 tracing、durable execution、middleware、telemetry 这些能力。这些其实都是 harness 工程化之后的自然产物。

Harness价值

Agent Harness不是一个花哨的新名词，而是 Agent 从 demo 走向生产之后必然出现的工程抽象。

更工程化的说：Agent Harness = Agent 的运行时 + 工具层 + 状态层 + 安全层 + 反馈层 + 评估层

Agent Harness 涉及一些关键概念

腾讯云ADP Agent Harness 的设计思路

整体架构设计

业界Agent Harness主要挑战：

业界客户端Agent Harness，包括claude code，codex等，把Harness所有的memory，沙箱，agent loop都打包CLI在容器中执行，但面对长任务和复杂任务，会暴露出连接脆弱、状态丢失、恢复困难、扩展差、安全边界不清晰的问题（参考 Anthropic Managed Agents）：

• 容器变成"宠物"：每个 Agent 容器都承载了状态、harness 和执行环境。一旦容器挂了，任务状态也可能丢失，所以容器不能随便重建，只能小心维护。
• 失败恢复困难：如果 harness 卡住、容器崩溃、进程异常，系统很难从外部恢复。因为任务历史和运行状态都在容器内部，新的进程无法轻松接管。
• 调试和运维风险高：工程师要排查问题时，可能需要进入用户容器。但容器里可能有用户代码、数据和中间产物，带来安全、隐私和合规风险。
• 安全边界不清晰：Claude 生成的代码、执行环境、工具凭证可能都在同一个容器里。Prompt injection 或恶意代码有机会读取环境变量、token 或敏感文件。
• 扩展性差：每个 Agent session 都要绑定一个容器。即使任务暂时不需要执行代码，也要先启动容器、准备环境、拉取资源，增加延迟和资源成本。
• harness 难以演进：harness 和容器、session 强绑定。模型升级后，harness 逻辑想调整，比如上下文管理、工具调用策略、恢复机制，都容易牵动底层环境。

腾讯云ADP 基于云端Agent Harness的设计考虑点和方案

考虑点：可恢复、安全边界清晰、弹性扩展、可替换、长任务，可持续演进。

方案：采用Agent loop(brain)，memory，sandbox，tools，可观测解耦设计。

ADP 的Agent Harness架构图

Agent Loop

Agent Loop 通常是 harness 的核心执行循环：它负责把"用户目标"不断转成 模型调用 → 工具调用 → 状态更新 → 再次决策，协调 LLM、工具、运行时状态、记忆、事件、hook 和续跑策略，让 agent 从输入逐步推进到任务完成、等待用户、失败、被中断或达到上限。

#### Agent Loop挑战点

上下文管理

难点：

• tool result 太大
• 历史会话太长
• 中间过程污染主上下文
• 压缩后丢关键信息
• 压缩摘要和真实状态不一致

解决方案：

• 每轮请求前跑做工具裁剪，微压缩，自动压缩，长期记忆异步提取，长期记忆提取，按需注入
• fork 用来隔离中间工具噪音，dream 用来整理长期 memory
• 摘要 prompt 强制结构化保留关键信息
• 保留最近消息原文，不全靠摘要
• 压缩后恢复最近读过的文件

长任务稳定性

难点：Agent Loop 不是一次 API 调用，而是一个长运行过程。长任务里任何环节都可能失败：

• 模型超时
• 工具超时
• 网络错误
• MCP 连接断开
• shell 命令卡住
• 用户中断
• 上下文超限
• token budget 超限
• 外部环境变化

解决方案：

• 状态机驱动的 Agent 运行时：通过状态机统一管理执行阶段与流转关系，更稳定地支撑复杂多步骤任务，天然适配多 Agent 协作、多阶段推进、阶段间等待与恢复等场景
• 任务驱动的自动续跑机制：围绕任务状态持续推进后续执行，当任务链路较长、步骤较多、需要分阶段完成时，Agent 可以基于任务进展自动续跑，减少中途打断后的遗漏与遗忘
• 异步化的 Agent 执行系统：基于标准 AGUI 事件协议进行状态与结果回传，支持流式反馈、断线重连、过程恢复和执行状态同步
• 异常处理机制：
• API 层：retry / backoff / fallback / credential refresh
• Loop 层：补 tool_result / compact recovery / abort reason
• Tool 层：timeout / progress / error tool_result
• Task 层：background / kill / notification / cleanup
• Context 层：budget / compact / collapse

多Agent协作

单 Agent 的场景：适合上下文高度连续、决策需要集中、任务不值得拆开的场景。 多 Agent 的场景：适合任务可以拆分、互相独立、需要并行、需要独立判断或需要隔离执行的场景。

ADP 多Agent核心设计：

SubAgent：参考claude code设计，主 Agent 通过 AgentTool 启动子 Agent，子 Agent 复用同一套 agent loop，但拥有独立上下文和生命周期。

多 Agent 不是一个独立的"多智能体框架"，而是把 Agent 工具做成了"递归启动另一个 agent loop"的能力：主 Agent 调用 AgentTool，选择某个 agentType，为它构造独立的 system prompt、工具集、权限、MCP、memory、上下文，然后通过 runAgent() 再跑一套完整的 agentLoop() 循环。

agentType：

Agent Team【即将上线】：

subagent 执行流程：主 Agent -> 子 Agent -> 返回一次结果

agent team 执行流程：team lead 创建团队 -> teammate 持续运行 -> 领取任务 -> 做任务 -> 发消息 -> 等待新任务 -> 可被中断/恢复/关闭

适合场景：

• 大型功能开发：可以拆成前端、后端、测试、文档、迁移等并行任务
• 代码库大规模改造：多个 teammate 分区域修改，team lead 汇总冲突和进展
• 多模块排障：一个查日志，一个查调用链，一个读代码，一个验证修复
• 市场/竞品分析：需要分别收集产品、价格、渠道、用户评价、行业趋势，再汇总判断
• 发布前检查：verification、测试、文档、配置、兼容性可以并行
• 迁移项目：数据库、API、前端、配置、CI/CD 各自推进
• 长时间后台工作：teammate 可以持续领取任务，不只是一次性返回
• 企业团队协作模拟：不同 agent 角色承担 reviewer、implementer、tester、planner

Memory

#### Memory核心难点

#### ADP Memory架构设计

跨会话长期记忆：从对话中自动提取并沉淀用户偏好、反馈风格、项目背景、关键事实四类长期记忆，按用户维度跨 session 召回。Agent在每轮对话中可主动命中并复用历史结论，保证跨会话的记忆连贯性。

Part / Message / Session 多级存储结构：对齐主流 agent 协议，以 Part 为最小语义单元（文本、工具调用、工具结果、推理、压缩摘要等多类型），向上聚合为 Message 和 Session。完整保留 agent的多模态消息流与工具调用链路，无有损压缩，支持细粒度回放、审计与二次加工。

Session 级智能压缩：针对长对话与长任务场景提供 session 维度的持续摘要能力。后台增量压缩对话历史，compact接口直接消费已就绪的摘要，将同步压缩的响应耗时由秒级降至毫秒级，规避上下文窗口超限与同步调用超时风险。

结构化 Todo 与任务记忆：提供 run → todo_list → todo 三层任务记忆模型，面向 code-agent 等长链路、多步骤任务场景。完整记录每次 agent 运行的任务规划、执行进度与状态流转，支持长任务的中断恢复与执行过程可观测。

提取与召回解耦，全链路可溯源：写入侧采用异步增量提取，不阻塞主链路；读取侧由 agent 按需主动召回，命中结果以结构化方式注入上下文，并保留来源会话、来源 run、命中记忆 ID 等元信息。

多租户隔离与业务级灰度：以 Memory Resource 作为顶层租户单元，按用户、场景、空间多维度隔离，数据归属严格。长期记忆、session 摘要等能力均支持租户级独立开关与灰度。

#### ADP Memory规划

长期记忆久了会出现的问：

• 记忆越来越碎
• 重复记忆变多
• 旧记忆和新记忆冲突
• 检索命中质量下降
• 上下文成本升高
• 重要信息被淹没
• 时间信息容易失真

长期记忆整理（类似claude code中的auto-dream）【即将上线】

沙箱（Sandbox）

沙箱它给 agent 一个可操作但受控的工作空间，让 agent 能读写文件、跑命令、生成产物、调用部分环境能力，同时把权限、资源、路径、网络和副作用控制在边界内。Sandbox 承载工具执行与工作区副作用的隔离执行层，负责把模型提出的动作安全、可观测、可恢复地落到真实或虚拟环境中。

#### 基于AGS Cube安全沙箱的优势

• 内核级强隔离：每实例独立 Guest OS，环境/会话/网络/存储分别隔离，LLM 生成的代码与 Bash 命令在 VM 级边界内执行。
• 极速启动 + 进程快照：AGS 镜像预热实现 100ms 级冷启动；进程级快照支持 Pause/Resume，恢复时进程、内存、依赖原样保留。
• Serverless 弹性伸缩：按需调度、空闲自动回收、并发数十万实例/分钟，平台无需预占资源。
• 自动"暂停恢复"、"停止恢复"，成本低：空闲超 5 分钟自动 Pause、调用自动 Resume；实例数随活跃用户增长（而非 Session 数），长期不使用自动销毁，workspace数据打包到cos，恢复自动加载，成本可预测，体验接近常驻。
• 数据隔离且能共享：智能工作台跨用户、空间双重隔离，同一用户多 Session 共用实例共享数据，支持跨 Session 协作；Claw模式应用Session完全隔离。
• 数据盘使用独立云存储：智能工作台每实例独占物理盘，更独立、安全、稳定、高性能，并支持 10 GB ~ 16 TB 灵活扩容。
• 凭证零落地：沙箱内环境变量看到的只是占位符，真凭证留在可信域，沙箱内任意进程拿不到真值。

工具（Tools）

将工具执行从 Agent 进程中解耦出来，形成可独立部署、可复用、可治理的工具执行服务。相比常见的 SDK 内嵌式工具或 IDE/CLI 强绑定工具，它更强调运行时隔离、跨框架复用、并发安全和资源生命周期管理。

#### 沙箱内置工具（Runtime Tools）

主要实现bash，read，write，edit，glop，grep等

#### HTTP-as-Boundary：把工具执行层从 Agent 进程里抽离

业界主流方案有两种：LangChain / LangGraph 工具函数直接定义在 Agent 进程里；Cursor / Aider 工具能力和用户界面紧耦合。

Sandbox claudecode 选择把工具执行变成一个独立的 HTTP 服务，带来三层好处：

• 跨语言：Agent 可以用任何语言写（Python、Go、Java、Rust），通过 HTTP 调用同一套工具
• 跨部署：工具服务可以独立扩缩容、独立升级、独立做安全策略
• 可复用：多个 Agent 框架共享同一套工具实现

#### Adapter 模式 + 编译期模板替换：双运行时统一接口、零运行时开销

支持两套独立的工具执行运行时（OpenCode 和 ClaudeCode），并通过环境变量 CODETOOL_ADAPTER 切换。采用编译期模板替换：构建时通过 adapter.cc.ts / adapter.oc.ts 替换主入口，最终得到两个完全独立的 artifact。

三个特性：

• 运行时零开销
• 依赖隔离
• 部署清晰：ags-oc 和 ags-cc 两个镜像家族独立演进

#### 双层 AsyncLocalStorage 并发隔离：让业务代码"无感知"并发

工具执行服务必须处理并发请求，每个请求有自己的 workdir、sessionId、cwd。Sandbox 用了双层 AsyncLocalStorage：

• 外层 contextStorage 装载 session context（workdir + sessionId）
• 内层 cwdOverrideStorage 提供更细粒度的 cwd 覆盖

业务代码看起来像单进程同步代码，但底层是天然请求隔离的。比 LangChain 进程内共享 os.chdir() 的做法安全得多。

#### 三层生命周期的 DirectoryContextRegistry：资源精细回收

三层生命周期：

• refs 引用计数：正在使用的 context 不会被回收
• idle 计时器：refs 归零后启动空闲计时（用 unref() 不阻塞进程退出）
• LRU 限额：超过容量上限时驱逐最久未使用的空闲 context

支持 0 = 无限/永久的可配置语义。

#### 文件操作的并发安全契约：Read-before-Write + mtime 防覆盖

• Read-before-Write 契约：Edit 和 Write 必须先 Read 过这个文件，未读直接拒绝
• mtime 防覆盖：Read 之后磁盘 mtime 变了就拒绝写
• 内容兜底比较：Windows 云同步等场景下 mtime 可能误改，全量 Read 时用内容字节比较兜底
• 写后状态更新：Edit/Write 成功后更新 fileStateCache 的 mtime 和内容

#### 流式 COS 集成：大目录传输不落盘

全流式架构：

• 上传：tar 进程的 stdout 直接 pipe 到 multipart 上传的分片流，每片 10 MiB
• 下载：Range GET 分片拉取后直接 pipe 到 untar 进程的 stdin，边下边解
• 凭证管理：临时凭证按请求传入，服务端不持有任何长期凭证

#### Agent内置工具

• Subagent类工具：Agent工具，用户创建子Agent，explore，general-purpose等
• 任务规划工具：TaskCreate、TaskGet、TaskUpdate、TaskList
• 通用搜索检索类：WebSearch，WebFetch，KnowledgeSearch等
• 通用办公类：图片识别，语音，视频类

#### 平台开发工具&connector

• 平台官方工具和connector
• 用户自定义工具和connector

权限&安全

Agent harness 的安全重点不是"让模型保证不犯错"，而是：模型负责建议和决策，harness 负责边界、权限、隔离、审计和最终执行控制。真正可靠的实现一定是：最小权限 + 工具校验 + 沙箱隔离 + 人工审批 + 全链路审计。

#### ADP权限体系

ADP平台实现三级分层权限架构（企业级-空间级-应用级）配合角色权限矩阵与资源配额管控，实现了功能+数据双维度的精细化权限隔离。

#### ADP安全设计考虑

执行环境安全

• 内核级隔离：基于 AGS Cube 安全沙箱
• session隔离：为每个sessionid启动沙箱实例隔离
• 凭证不落地沙箱：真实凭证不落沙箱，留在云端可信区，进程获取不到

数据安全

• skill内容安全：平台深度融合腾讯科恩实验室与云鼎实验室的安全检测能力，覆盖构建、注册、授权、执行、审计全生命周期安全闭环
• 注册阶段：异步安全扫描，扫描内容覆盖 Skill 描述、Prompt、脚本、依赖、配置、工具声明等
• 执行阶段：实时安全检测，对工具调用、命令执行、网络访问、文件读写等行为做实时检测和拦截
• 输出给用户的数据：通过天御安全实时审核，预防涉黄，涉政，广告等
• 密钥&凭证管理：有专门凭证管理服务，沙箱内不存储正式的凭证数据
• 用户沙箱workspace数据：沙箱整体执行环境通过快照保存和恢复；实例长期不用，沙箱销毁，workspace数据通过cos保存和恢复

Prompt injection 防护

• system prompt 明确：外部内容不能覆盖系统/开发者指令
• 外部消息标记为 untrusted，而不是当作用户指令
• 高风险工具调用不能只因外部文本要求而执行
• connector 返回内容不要直接拼进 tool policy
• 对"请求泄露密钥/改权限/关闭安全策略"等意图做拦截

多 Agent 安全

• AgentType 工具权限隔离：不同 agent 有不同 tools / disallowedTools
• Fresh subagent 零上下文：指定 subagent_type 的新 agent 不自动继承主会话全部上下文，降低敏感上下文扩散

可观测

Transcript：记录完整会话、工具调用、工具结果、Agent 执行轨迹

Sidechain Transcript：subagent/background agent 独立记录，避免污染主会话，也支持恢复

LLM Gateway Transcript：用于记录一次或多次模型调用的完整请求/响应轨迹，包含 prompt、messages、model、参数、响应、token、耗时、错误等信息，用于调试、审计、回放和问题定位

Agent 身份追踪：记录 agentId、agentType、teamName、parentSessionId

Tool Use / Tool Result 记录：记录模型调用了什么工具、参数是什么、工具返回什么

API Request/Session ID：每次 API 请求有 traceid，微服务内部通过context传递tranceid

Usage 统计：统计 token、tool use count、duration 等

ADP快速上手

智能工作台

面向Agent的使用者，开箱即用。腾讯云智能体开发平台：https://adp.cloud.tencent.com/adp/

Claw模式

面向Agent的企业开发者，它更像运行在平台上的托管智能体。企业可以预先配置 Agent 的提示词、工具、skill、MCP、权限、发布版本，然后通过 API、控制台、工作流或业务系统调用它。

#### 集成方式：Agent构建在ADP平台，对话集成ADP的对话接口

适合想快速使用 Agent 能力的企业。在 ADP 控制台里完成 Agent 创建、skill 配置、MCP 工具配置、提示词调试、发布管理；自己的业务系统只集成运行时对话 API。

适合场景：

• 企业没有计划自建智能体平台
• Agent 数量相对有限
• 更关注快速上线、低研发成本、低运维成本
• 需要可视化配置、调试、发布和管理能力
• 典型例子：企业官网接入售前咨询 Agent、OA / ITSM 接入内部问答 Agent、客服系统接入工单辅助 Agent、知识库系统接入知识问答 Agent

#### 集成方式：Agent的构建配置和对话使用全部API集成

适合企业开发自己的智能体平台，面向企业内部团队、客户或开发者提供 Agent 创建、配置、发布和运行能力。ADP 同时提供配置端 API 和运行时对话 API，企业可以在自己的平台中完成 Agent 全生命周期管理。

适合场景：

• 企业要开发自己的智能体平台，提供给内部团队、客户或开发者使用。

• 已经有自己的控制台、权限体系、租户体系、审批流程、审计体系。

• 需要把 Agent 创建、skill 配置、MCP 工具配置、提示词管理等能力集成进自己的产品。

• Agent 数量多、业务线多、租户多，需要自动化批量管理。

• 希望对外提供一套自己的 Agent 开发平台、Agent 市场或低代码平台。

• 需要配置端 API + 运行时 API 一起开放，支持开发者完整集成。

典型例子：

• 大型集团建设统一智能体平台，让各业务线自助创建 Agent。

• SaaS 厂商在自己的产品里提供“自定义智能体”能力。

• 企业低代码平台集成 Agent 编排和发布能力。

• ISV 面向客户提供多租户 Agent 创建、配置、运行能力。

API：

• Agent 管理端 API：也叫管控面API（Control Plane API）：https://cloud.tencent.com/document/product/1759

- Agent运行时API：也叫数据面API（Data Plane API）：

• WebSocket：https://cloud.tencent.com/document/product/1759/129365
• SSE：https://cloud.tencent.com/document/product/1759/129202

附录-业界对Harness 的相关文章