【Managed Agent】#0 概览

ManagedAgent（MA）是A\出品的Agent容器化和管理基建服务，提供预构建的、可配置的Agent运行时环境（也称作Agent Harness）。

Claude Managed Agents provides the harness and infrastructure for running Claude as an autonomous agent. Instead of building your own agent loop, tool execution, and runtime, you get a fully managed environment where Claude can read files, run commands, browse the web, and execute code securely. The harness supports built-in prompt caching, compaction, and other performance optimizations for high-quality, efficient agent outputs.

概括来说，Managed Agent的特性可以归为三个：Stateful Session、Pre-built Agent Harness和Cloud Deploy，下面逐一展开。

Stateful Session

Messages API提供了向模型发送推理请求并获取结果的能力，是一个无状态的接口。也就是说，两次发送消息给Messages API，模型并不知道上次请求的上下文，因此需要使用者自己组织和管理上下文消息，并在发送消息前转为API的message格式完整发送。

与Messages API不同，MA可以创建有状态的运行环境，并且具有持久化的能力。MA Environment包含了完整的file system、network config、env config、browser等操作系统能力，作为一个沙盒环境存在：Agent可以在沙盒环境中执行相关动作，而宿主环境不会受到Agent的破坏。Stateful Session可以视为Agent会话在逻辑层的管理对象，在物理上包含了运行环境和Agent运行时。

Pre-built Agent Harness

Harness

Harness是Agent的脚手架和外部信息感知接口，包含的内容可以从Agent、LLM Gateway、控制面三部分来讲。

Agent

Agent可以用Agent = {BaseModel, SystemPrompt, Knowledge, Plugin}来表示。

BaseModel指的是模型，模型决定了理解和驾驭Harness的程度。能力越强的模型，对于同一套Harness下进行的任务的理解程度更高，健壮性和泛化性也更好。

SystemPrompt是系统提示词，它对Agent效果的影响广泛：

• 系统提示词会定义Agent的行为约定和问题处理方式，有时还会定义角色设定和性格，这会影响Agent如何去做一个任务，因此优化系统提示词一直是一项重要的工作；
• 系统提示词放在所有上下文顶部，注意力关注度更高。按照渐进式披露的思路，无论是Knowledge还是Skills，都可以从系统提示词中得到更好的索引和使用；
• 系统提示词的组织会影响Cache命中率。当前的KVCache以前缀Cache为主，组织系统提示词时按immutable-stable-dynamic来组织，能更好地使前缀命中，降低成本。

Knowledge是一类特殊的可插拔提示词。它可以解决模型知识cutoff的问题，给出更接近实时的事实；也可以更好地处理稀疏知识，减少幻觉。Knowledge的另外一大作用是提供专业知识，例如法律条文，让Agent处理更专业的内容。

Plugin是所有Agent外挂能力的总称，包含Tools、Skills，以及其他通过MCP与外部交互的接口。Plugin给了Agent可扩展的感知和行动能力——有了这些工具，Agent就真正可以去操作例如邮箱、浏览器等外部应用。

LLM Gateway

用来聚合不同的大模型供应商，使Harness可以使用不同的模型能力；Gateway中还会提供不同的Prompt组装策略，提高提示词缓存利用率，降低成本；它的另一个作用是提供上下文压缩的能力，在保持必要上下文的基础上压缩无用上下文，让Agent保持充足的使用空间。

控制面

控制面负责对Managed Agent中的各类对象进行统一定义、编排和治理，使Agent不再只是一个临时运行的模型调用进程，而成为可以被工程化管理的应用。

从抽象上看，控制面管理的是系统的期望状态与实际运行状态：用户声明一个Agent应当使用什么Harness、运行在什么Environment、具备哪些能力以及受到哪些约束；控制面则负责创建所需资源、调度执行实例、持续观察运行状态，并在失败、暂停、扩缩容或配置变化时，使实际状态重新收敛到期望状态。

控制面的职责主要包括以下几个方面。

对象定义与工程化管理

控制面首先定义Managed Agent对外暴露的资源模型，并为这些资源提供创建、更新、版本化、发布、复制、回滚和删除等工程化能力。

从用户视角看，核心对象可以抽象为下面的层级表示：

ManagedAgent
├── Harness
│   ├── Agent
│   ├── Skills
│   └── Knowledge
└── Environment
    ├── Environment Variables
    ├── Runtime Dependencies
    ├── Filesystem
    ├── Shell
    ├── Network
    └── Other Operating System Capabilities

其中，Harness描述Agent如何思考、获取信息和执行任务，Environment描述这些动作在什么环境中发生。

Agent是Harness中的核心决策单元，通常包含模型选择、系统指令、行为约定和能力配置。Skills和Knowledge可以在逻辑上视为Agent能力的一部分，但在工程实现上更适合作为可独立版本化、复用和挂载的资源，由Harness在运行时加载。

这种设计既允许用户将Agent、Skills和Knowledge打包为一个完整应用，也允许多个Agent共享同一套Skill、知识库或运行环境，避免所有配置都固化在一个不可拆分的镜像中。

控制面还需要管理不同对象之间的依赖关系。例如，一个Harness可以引用特定版本的Agent、Skills和Knowledge；一个 Environment可以引用基础镜像、依赖集合、网络策略和Secret；一个正在运行的Session则固定其使用的配置版本，从而保证运行过程可复现，并支持后续审计和回滚。

生命周期管理

控制面管理Agent及其运行环境从定义到执行结束的完整生命周期，包括创建、部署、启动、暂停、恢复、终止、归档和回收等。

一个Managed Agent的运行过程通常不只是简单的“开始”和“结束”，还可能处于排队、资源准备、运行、等待用户输入、等待审批、暂停、恢复、失败重试或取消等状态。因此，控制面需要维护明确的状态机，并规定每种状态可以接收哪些操作。

例如：

Created
  → Queued
  → Provisioning
  → Running
  → WaitingInput / WaitingApproval / Suspended
  → Running
  → Completed / Failed / Cancelled

生命周期管理的对象不仅包括Agent本身，也包括Session、Run、Sandbox、定时任务以及运行过程中创建的临时资源。控制面需要保证这些对象能够被可靠地创建和销毁，并避免因为进程退出、网络中断或节点故障而产生失控的孤儿资源。

运行时状态控制

Managed Agent在运行过程中可能持续数分钟、数小时甚至更长时间，因此平台必须能够在任务执行期间对其进行动态控制。

控制面需要支持查看当前执行状态、向运行中的Agent追加消息、修改任务方向、暂停或恢复执行、批准高风险动作、取消任务，以及在必要时强制终止运行环境。

这些控制指令不会直接替代Harness的推理逻辑，而是作为外部事件传递给运行时，由Harness根据当前状态决定如何响应。例如，用户补充的新要求可以在下一轮模型调用时进入上下文；暂停指令可以阻止新的工具调用；终止指令则需要停止Harness，并撤销或回收相关执行资源。

因此，控制面负责“是否允许继续运行以及运行到什么状态”，Harness则负责“在当前约束下下一步具体做什么”。

资源调度

控制面负责为Agent分配执行所需的计算、存储和网络资源。

不同Agent任务对资源的需求差异很大：简单的信息处理任务可能只需要较小的CPU和内存；代码编译、浏览器自动化、数据分析或多Agent协作则可能需要更高配置的运行环境。控制面需要根据Environment声明、任务优先级、租户配额和当前集群容量，将任务调度到合适的Worker或Sandbox中。

资源调度通常包括：

CPU / Memory / GPU 分配
Sandbox 创建与回收
持久化存储挂载
任务排队与优先级
并发数和租户配额
超时与资源租约
定时任务和事件触发
跨节点或跨区域调度
资源使用计量

对于长时间运行的Agent，控制面还需要避免将Session与某个具体进程或节点永久绑定。当Worker故障或资源需要迁移时，平台应能够根据持久化状态和检查点，在其他节点上重新恢复运行。

可靠性

可靠性管理的目标保证失败能够被发现、隔离、恢复，并且不会造成不可控的重复副作用。

控制面需要识别不同类型的故障，包括模型调用失败、工具调用超时、Harness崩溃、Sandbox失联、节点故障、网络中断、资源耗尽以及任务逻辑长时间无进展。对于不同故障，平台应采用不同的恢复策略，例如自动重试、重新调度、从检查点恢复、降级模型、等待人工处理或终止任务。

为了支持可靠恢复，控制面通常需要管理：

Run 与 Attempt
Checkpoint
Heartbeat
Timeout
Retry Policy
Failure Classification
Idempotency Key
Lease
Dead-letter Queue
Compensation Record

尤其对于会修改外部系统的工具调用，简单地重新执行整个任务可能导致重复发送邮件、重复付款或重复写入数据。因此，控制面与Harness需要共同维护工具调用的唯一标识和提交状态，使恢复过程能够区分“尚未执行”“执行中断”“已执行但结果未返回”等不同情况。

扩展性

控制面需要支持系统在Agent数量、Session数量、工具类型和运行环境不断增长时继续稳定运行。

扩展性一方面体现在基础设施层，包括多Worker水平扩展、任务分片、队列隔离、多租户资源管理和跨区域部署；另一方面也体现在能力模型上，即允许平台不断接入新的模型供应商、Harness实现、Skill、Knowledge Source、Tool、MCP Server和Sandbox类型。

为了避免控制面与某一种Harness或Environment强耦合，不同组件之间应通过稳定的接口和协议交互。例如，控制面只需要知道如何创建、启动、暂停、查询和销毁一个运行时实例，而不必理解Harness内部具体采用ReAct、Plan-and-Execute还是多Agent Workflow。

这种接口隔离使平台可以在不改变上层Agent定义和管理方式的情况下，替换底层模型、升级Harness或接入私有执行环境。

安全控制

安全控制负责限制Agent能够感知和影响的范围，防止其访问未授权数据、执行危险指令或产生无法回退的外部副作用。

安全边界需要贯穿Agent定义、Harness、Environment和工具调用的完整链路，包括：

用户与租户身份认证
Agent和工具权限
Secret注入与轮换
文件系统访问边界
网络入口与出口策略
命令和系统调用限制
资源使用上限
敏感数据隔离
高风险操作审批
运行时终止与熔断
审计与数据保留策略

对于发送消息、删除数据、修改生产环境、支付或发布内容等高风险操作，平台可以要求Human-in-the-loop审批。Harness可以提出动作请求，但只有在控制面确认权限和审批状态后，执行面才真正执行相关操作。

因此，安全控制并不只是过滤一组危险命令，而是对“谁可以让哪个Agent，在什么环境中，以什么身份，对哪些资源执行什么动作”进行完整约束。

可观测性与成本治理

控制面需要持续记录Agent的执行轨迹，使运行过程能够被查看、调试、评估和审计。

可观测性不仅包括模型输入与输出，还应覆盖Session、Run、模型调用、上下文压缩、Skill 加载、知识检索、工具调用、Sandbox操作、错误重试和人工干预等完整链路。

平台通常需要提供以下观测维度：

Session/Run/Step状态
模型调用延迟与Token使用量
Prompt Cache命中情况
上下文长度与压缩记录
工具调用参数、结果和耗时
Sandbox的CPU、内存和网络使用量
错误类型与重试次数
人工审批和干预记录
Agent版本之间的效果差异
任务成功率与最终产出质量

在成本治理方面，控制面需要统一统计模型费用、计算资源费用、存储费用和外部工具费用，并允许按租户、项目、Agent、Session或任务进行合并整理。平台还可以设置单次任务预算、每日额度和异常成本告警，并在预计费用超过限制时暂停或终止任务。

总体而言，控制面承担的是Managed Agent中所有“管理”相关的职责。Harness负责驱动一次具体的Agent执行，Environment提供实际的动作空间，而控制面则在它们之上维护定义、版本、状态、资源、权限和运行秩序。

正是控制面的存在，使Agent从一个依赖单进程和临时上下文的程序，转变为可部署、可调度、可恢复、可扩展、可观测和可审计的生产级工作负载。

Pre-built

Pre-built将Agent需要的环境和Harness打包成可分发的镜像，能做到像Docker一样：不同Agent之间环境隔离、Agent的生命周期可管理、事件可观测以及执行可控。

• 对于用户侧，有助于快速部署并使用一种Agent进行任务；
• 对于Agent平台服务，可以像云上的资源一样管理Agent；
• 对于应用方，可以工程化地管理和打包一类Agent应用，托管到Managed Agent平台，无需考虑Agent复杂的底层，专注于应用开发。

Cloud Deploy

MA的另一大特点是云端管理。也就是说，整套Agent和沙箱环境都在云端进行部署和运行，这使Agent具备了执行异步任务和长时间任务的时间空间和硬件条件。