Open Managed Agents

在 AI Agent 从实验走向生产的过程中，基础设施的复杂性往往成为最大阻碍。Open Managed Agents (OMA) 是一个开源的 AI 代理元工具包，旨在作为 Claude Managed Agents 的完全替代方案。它提供了一套标准化的平台层，处理会话管理、沙箱执行、内存持久化、凭证隔离及崩溃恢复等棘手问题，让开发者只需专注于代理逻辑本身。

核心亮点：一套代码，双端部署

OMA 的最大优势在于其环境无关性。相同的工具包、业务逻辑和 API 接口，可以在两种截然不同的环境中无缝运行：

只需更改环境变量，无需修改任何代码即可切换部署目标。

架构设计：元工具包 vs 工具包

OMA 采用分层架构，清晰分离了“平台能力”与“代理逻辑”：

1. 基础设施层：提供事件日志、沙箱执行环境、持久化存储。
2. 元工具包层 (Meta-Harness)：
   • 生命周期管理：处理会话创建、暂停、恢复。
   • 安全隔离：凭证加密存储、沙箱进程隔离。
   • 通信机制：WebSocket 广播、崩溃自动恢复。
3. 工具包层 (Harness)：
   • 上下文工程：决定哪些历史消息发送给模型。
   • 缓存策略：控制哪些内容需要缓存以节省 Token。
   • 模型调用：执行具体的 LLM 推理循环。

快速开始：自托管部署

OMA 提供了极简的本地启动流程，默认使用 SQLite 和本地子进程沙箱：

# 1. 克隆项目
git clone https://github.com/open-ma/open-managed-agents.git
cd open-managed-agents

# 2. 配置环境变量
cp .env.example .env
# 生成必要密钥
echo "BETTER_AUTH_SECRET=$(openssl rand -hex 32)" >> .env
echo "PLATFORM_ROOT_SECRET=$(openssl rand -base64 32)" >> .env

# 3. 一键启动
docker compose up -d

# 4. 验证健康状态
curl localhost:8787/health

# 5. 访问控制台 UI
open http://localhost:8787

开发自定义工具包 (Harness)

当默认逻辑无法满足需求时，你可以编写自定义 Harness。OMA SDK 提供了简洁的 API，让你直接访问运行时上下文：

// my-harness.ts
import { defineHarness, generateText, stepCountIs } from "@open-managed-agents/sdk";

export default defineHarness({
  name: "research-agent",

  async run(ctx) {
    // 1. 获取历史消息
    let messages = ctx.runtime.history.getMessages();
    
    // 2. 自定义上下文过滤：只保留搜索和抓取结果
    messages = keepOnly(messages, ["web_search", "web_fetch"]);
    
    // 3. 设置缓存策略：最近 3 条消息设为临时缓存
    markLastN(messages, 3, { cacheControl: "ephemeral" });
    
    // 4. 执行推理循环
    const result = await generateText({
      model: ctx.model,
      system: ctx.systemPrompt,
      messages,
      tools: ctx.tools, // 平台自动注入可用工具
      stopWhen: stepCountIs(50), // 最大步数限制
      onStepFinish: async ({ text }) => {
        // 实时广播消息给前端
        if (text) ctx.runtime.broadcast({
          type: "agent.message",
          content: [{ type: "text", text }],
        });
      },
    });

    // 5. 上报用量统计
    await ctx.runtime.reportUsage?.(result.usage.inputTokens, result.usage.outputTokens);
  },
});

部署自定义 Harness：

oma deploy --harness my-harness.ts --agent agent_abc123

关键特性详解

• 凭证隔离与安全：所有 API Key 和敏感信息均经过加密存储，并在沙箱环境中按需注入，防止泄露。
• 崩溃恢复：基于事件日志（Event Log）架构，即使进程重启或容器重建，代理也能从断点处继续执行，保持会话状态一致。
• 实时通信：内置 WebSocket 支持，前端可实时接收代理的思考过程、工具调用结果及最终输出。
• 兼容 CMA API：提供 /v1/agents 和 /v1/sessions 等标准接口，现有基于 Claude Managed Agents 开发的应用可低成本迁移。

Open Managed Agents 填补了开源社区在“生产级 AI 代理基础设施”领域的空白。它不仅提供了一个可运行的平台，更定义了一套标准的代理开发范式。