> ## Documentation Index
> Fetch the complete documentation index at: https://oma-codex-339-workspace-permissions.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Open Managed Agents 概述

> 预构建、可配置的智能体框架，运行在你控制的基础设施中。最适合长时间运行的任务和异步工作。

Open Managed Agents 提供两种构建方式，每种方式适用于不同的使用场景：

|         | 消息 API         | Open Managed Agents        |
| ------- | -------------- | -------------------------- |
| **是什么** | 直接访问模型提示功能     | 预构建、可配置的智能体框架，运行在你控制的基础设施上 |
| **最适合** | 自定义智能体循环和细粒度控制 | 长时间运行的任务和异步工作              |

Open Managed Agents 提供了运行自主智能体所需的运行框架和基础设施。你无需构建自己的智能体循环、工具执行和运行时，而是获得一个由你管理的环境，智能体可以在其中安全地读取文件、运行命令、浏览网页和运行代码。该框架支持内置的提示缓存、上下文压缩以及其他性能优化，以实现高质量、高效的智能体输出。

<Note>
  OMA 是开源、自托管的实现。数据库、对象存储、模型凭证和环境运行器均由部署者管理；文档中提到的“云环境”指由你的 OMA 部署配置的 E2B 或兼容运行器。
</Note>

<CardGroup cols={3}>
  <Card title="快速入门" href="/docs/zh/quickstart">
    创建你的第一个智能体会话
  </Card>

  <Card title="启动会话" href="/docs/zh/sessions">
    创建会话并发送你的第一个事件
  </Card>

  <Card title="参考" href="/docs/zh/reference">
    事件类型、速率限制、CLI 标志以及其他查询表
  </Card>
</CardGroup>

## 核心概念

Open Managed Agents 围绕四个概念构建：

| 概念                  | 描述                                         |
| ------------------- | ------------------------------------------ |
| **智能体（Agent）**      | 模型、系统提示、工具、MCP 服务器和技能                      |
| **环境（Environment）** | 会话运行位置的配置：由 OMA 部署配置的云沙箱，或在你自己的基础设施上自托管的沙箱 |
| **会话（Session）**     | 在环境中运行的智能体实例，执行特定任务并生成输出                   |
| **事件（Event）**       | 你的应用程序与智能体之间交换的消息（用户轮次、工具结果、状态更新）          |

## 工作原理

<Steps>
  <Step title="创建智能体">
    定义模型、系统提示、工具、MCP 服务器和技能。只需创建一次智能体，即可在多个会话中通过 ID 引用它。
  </Step>

  <Step title="创建环境">
    配置智能体的运行位置：由环境运行器提供的云沙箱，或在你自己的基础设施上运行的[自托管沙箱](/docs/zh/self-hosted-sandboxes)。
  </Step>

  <Step title="启动会话">
    启动一个引用你的智能体和环境配置的会话。
  </Step>

  <Step title="发送事件并流式传输响应">
    将用户消息作为事件发送。智能体自主运行工具，并通过服务器发送事件（SSE）流式传输返回结果。事件历史记录在服务端持久化，并可完整获取。
  </Step>

  <Step title="引导或中断">
    在执行过程中发送额外的用户事件来引导智能体，或中断它以改变方向。
  </Step>
</Steps>

## 何时使用 Open Managed Agents

Open Managed Agents 最适合需要以下条件的工作负载：

* **长时间运行的执行：** 运行数分钟或数小时、包含多次工具调用的任务
* **云基础设施：** 预装软件包并具有网络访问权限的安全沙箱
* **自托管执行：** 在你控制的基础设施上运行沙箱，以满足合规性或数据驻留要求
* **最少的基础设施：** 无需构建自己的智能体循环、沙箱或工具执行层
* **有状态会话：** 跨多次交互的持久化文件系统和对话历史记录
* **计划执行：** 通过[计划部署](/docs/zh/scheduled-deployments)按 cron 计划定期运行智能体

## 支持的工具

Open Managed Agents 提供一组内置工具：

* **Bash：** 在沙箱中运行 shell 命令
* **文件操作：** 在沙箱中读取、写入、编辑、glob 和 grep 文件
* **网页搜索和获取：** 搜索网页并从 URL 检索内容
* **MCP 服务器：** 连接到外部工具提供方

请参阅[工具](/docs/zh/tools)了解完整列表和配置选项。

## Beta 功能访问

<Note>
  Open Managed Agents 仍处于测试阶段。所有托管智能体端点都需要 `managed-agents-2026-04-01` Beta 请求头。兼容 SDK 会自动设置该请求头；各版本之间可能会优化行为以改进输出。
</Note>

要开始使用，你需要：

1. 一个可访问的 OMA 部署和工作区 API 密钥
2. 在所有请求中添加 `managed-agents-2026-04-01` Beta 请求头
3. 一个配置完成且可以启动会话的环境

MCP 隧道和梦境能力仍在规划中。当前版本尚未提供完整的梦境 API；请以[梦境](/docs/zh/dreams)页面顶部的实现状态说明为准。

Open Managed Agents 在设计上是有状态的：会话可以长时间运行，在暂停后恢复，并在你的部署中存储对话历史记录、沙箱状态和输出。数据保留、加密和合规边界由部署者控制；你可以随时通过 API [删除会话](/docs/zh/session-operations#deleting-a-session)，并单独删除上传的[文件](/docs/zh/files)。