Agents > Oz 云 Agent 与编排

Oz 平台概览

Oz 平台为云代理提供了 CLI、API/SDK、编排、环境和可观测性。

云代理运行在 Oz 平台上。该平台为您提供了一种统一的方式来触发工作、编排并跟踪任务、执行代理（在可选的环境中，或在宿主机上），以及检查结果以实现团队可见性。一等集成可自动将外部事件（如 Slack 消息、GitHub PR 或 CI 失败）与云代理连接起来。

大多数生产设置遵循相同的流程

触发器启动（调度、集成事件、CI 步骤、webhook、API 调用或手动运行）。
Warp 的编排层创建一个云代理任务并跟踪其生命周期。
代理在宿主机上执行，可选择在环境中执行，并使用所需的配置和凭据。
任务会生成一个持久化记录（状态、元数据、转录、输出），供您的团队审查和管理。

Oz Platform architecture showing Trigger, Agent, Environment, and Artifacts components

Oz Platform detailed architecture showing components, triggers, orchestrator, and agent runners

下面的章节描述了驱动此流程的 Oz 平台基元，以及它们是如何组合的。

核心概念

在深入了解组件之前，先统一几个术语很有帮助

触发器 (Trigger)：启动工作的事件（例如：cron、Slack @提及、PR 打开、CI 失败、“立即运行”）。
任务 (Task)： Warp 跟踪的工作单元。任务包括输入、状态、元数据和执行记录（运行位置、操作内容以及产生的输出）。
上下文 (Context)：附加到任务的额外输入（例如：Slack 消息、PR 元数据、CI 日志、仓库差异）。
输出 (Outputs)： 任务产生的内容（例如：创建了 PR、发布了 Slack 回复、发出报告，或者仅仅是转录和总结）。

实际上：触发器创建任务；任务在宿主机上（可选在环境中）执行；任务产生输出。

Oz CLI

Oz CLI 是用于在非交互模式下运行代理的无头界面。它通常用于没有交互式 UI 的 CI、脚本和服务器环境中。对于交互式工作流，请使用 Warp 桌面应用中内置的代理。

CLI 的一个关键属性是它与云端连接。即使代理是在本地机器或 CI 中启动的，它也会将进度报告给 Warp 的服务器。这实现了团队可见性、会话共享（在支持的情况下）以及通过 API 进行的编程跟踪。

何时使用 CLI

使用 CLI 的场景

您希望在任何地方运行代理（本地机器、CI 运行器、远程开发盒、服务器）。
外部系统正在编排运行（例如 GitHub Actions、自定义自动化、事件工具）。
您需要在不需要 Warp 桌面的情况下进行任务可观测性和审计。

它如何融入 Oz 平台

根据命令的不同，CLI 通常会

以您的身份（或适用时的团队成员身份）进行身份验证。
通过在编排器中创建任务来开始工作（可以直接通过 CLI 命令，也可以间接通过集成/调度）。
将进度流式传输回 Warp，以实现实时可观测性和持久记录。
可选地附加环境和其他配置。

示例（无环境）

您也可以不使用环境，在本地运行代理，使用如下命令

oz agent run ...

Warp Orchestrator（编排器）

编排层管理云代理任务的生命周期。它创建任务，跟踪状态转换，并且是记录正在运行的内容和已运行内容的系统。

编排器的作用

编排器

在 Warp 的服务器（云控制平面）上运行。
在触发器（集成、调度、API 调用或显式启动）触发时创建任务。
跟踪生命周期状态（创建 → 运行中 → 完成/失败）及相关元数据。
通过 Oz CLI 和 REST API 公开任务生命周期操作（创建任务、查询历史记录以及检查状态/输出）。
为编排器 API 之上的编程使用提供 SDK（TypeScript/Python）。

团队何时使用 API/SDK

团队通常在以下情况使用 API/SDK

从自定义内部系统（事件工具、机器人、内部自动化）触发代理。
构建内部仪表板或监控（成功率、运行时间、失败原因）。
协调多次运行（扇出、分片、排队、重试、应用层速率限制）。
创建将任务视为构建块的更高级别工作流。

环境

环境定义了代理应在其中运行的执行上下文。

环境通常包括

Docker 镜像（工具链和运行时）。
一个或多个仓库（或工作区定义）。
启动命令和配置（设置步骤、依赖安装、引导）。
可选的环境变量和其他运行时设置。

环境是可选的

代理可以在没有环境的情况下运行（例如，针对现有的本地检出或 CI 工作区）。当团队想要更强的可重复性、隔离性和标准化时，通常会转向环境。

何时使用环境

建议在以下情况下使用环境

代理需要一致的工具链（lint 工具、构建工具、语言运行时）。
您希望在 CI 和云执行之间实现可重复的执行。
您希望在整个团队中实现标准执行（相同的仓库状态规则，相同的设置步骤）。
您希望减少跨任务的“在我的机器上能运行”的可变性。

Oz API 和 SDK

Oz 代理 API 是 Oz 平台的 HTTP 接口。它允许您从任何系统（CI、cron、后端服务、内部工具）创建和检查云代理任务，而无需使用 Warp 桌面应用。

您可以使用 API 执行的操作

通过提交提示词和可选配置（模型、环境、MCP 服务器、基础提示词等）来运行代理。
通过列出任务并随时间跟踪状态转换（例如：QUEUED → INPROGRESS → SUCCEEDED/FAILED）来监控执行。
通过获取任务的完整详细信息（包括原始提示词、创建者/来源元数据、会话链接和已解析的代理配置）来检查结果和来源。

Oz SDK

Oz 提供官方 Python 和 TypeScript SDK，它们包装了 Oz API，并具有

类型化的请求/响应（自动完成，减少模式错误）
内置重试和超时（具有每个请求的覆盖项）
映射到 API 状态码的一致错误类型
当您需要标头/状态/自定义解析时用于原始响应的帮助程序

如果您正在构建集成（CI、Slack 机器人、内部工具、编排器），SDK 通常是最快且最安全的起点。

SDK 与原生 REST

当您想要强类型、标准化错误处理和简单的并发模式时，请使用 SDK。
当您想要最少的依赖项或完全控制 HTTP 客户端时，请使用原生 REST。

执行宿主

宿主机描述了代理实际执行的位置。Warp 支持多种执行模型，具体取决于您的安全、合规和运营要求。

Warp 托管执行

使用 Warp 托管

Warp 在 Warp 管理的基础设施上运行环境。
对于那些想要最简单设置且不需要在网络边界内进行执行的团队，这是默认模型。
有关更多详细信息，请参阅 Warp 托管执行。

自托管执行

使用自托管

代理在客户管理的基础设施上运行。
Oz 编排器仍然管理生命周期和可观测性。
当团队希望代码和执行保持在自己的系统上，而不是被克隆或在 Warp 的云中执行时，会使用此方案。

集成

集成将外部事件连接到云代理任务。当第三方系统中发生事件时，Warp 会创建带有相关上下文的任务并自动启动它。

Warp 支持两种集成模型

一等集成 — Warp 端到端地管理事件订阅和上下文提取。
自定义集成 — 您处理事件获取和过滤，然后调用 API 或 SDK 来创建任务。

一等集成

可以通过简单的设置流程（例如通过 CLI）配置一等集成

oz integration create …

Warp 向第三方系统注册 webhook，接收事件，提取上下文（负载、元数据、链接、日志），并创建一个任务 — 可选择在环境中创建。

一等集成提取的上下文示例

Slack：消息文本、频道、线程和用户身份
GitHub：PR 元数据、差异、标签和检查结果
CI：日志、作业元数据和工件

自定义集成

对于自定义集成，您拥有 webhook 和事件处理逻辑。您的系统接收事件，应用您需要的任何过滤或增强，然后调用 Oz API（直接或通过 SDK）来创建任务。生成的任务仍然是一个完整的云代理运行 — 像任何其他任务一样可观察、可管理且可审计。

自定义集成适合以下情况

您有内部事件源（自定义工具、专有系统）。
在触发代理之前，您需要自定义过滤、路由或增强。
您希望围绕触发器实现自己的权限、排队或治理。

密钥

云代理通常需要凭据才能访问外部系统（API、云提供商、数据库、内部工具、MCP 服务器）。Warp 提供了一个密钥存储库，可以在运行时注入密钥，以便代理可以使用经过身份验证的工具，而不会在日志或 UI 中暴露密钥值。

密钥的用途

在大多数部署中，密钥用于

API 密钥和令牌（GitHub、Slack、Linear、内部 API）。
共享团队凭据（云提供商、CI 身份）。
数据库凭据（只读查询机器人、报告）。
MCP 服务器所需的凭据（静态令牌/密钥）。

作用域和控制

目前，密钥支持两个作用域

团队密钥： 团队可用的共享凭据（对共享基础设施有用）。
个人密钥：绑定到个人的凭据（当行动必须归因于特定人员时非常有用）。

管理与可观测性

云代理的设计使得任务执行对团队可见。

当任务正在执行时，代理会将进度和状态报告回 Warp。完成后，任务会保留一份持久化记录，供审查和调试。

Warp 提供了多个可观测性界面

管理 UI：列出任务、状态、时间、元数据和历史记录。
代理会话共享：授权的队友可以连接到正在运行的任务进行监控，并在支持的情况下进行引导。
API 和 SDK：查询任务历史记录、构建监控并生成报告。

访问控制

访问控制是模型的一部分

团队可以限制谁可以运行、查看或干预代理任务。
同时，组织可以在适当时启用系统范围的可见性，以进行审计和运营。

集中式配置

云代理设置通常包括共享配置，例如

Warp 支持集中式配置，因此无论在何处启动任务，这些设置都会一致地应用。

当同一个工作流可以从多个地方（例如 Slack、CI 和调度）触发时，这特别有用。团队无需在系统间复制设置，只需将配置保存在一处，并在各个触发器中重复使用即可。

使用或不使用 Warp 应用来使用 Oz 平台

云代理不需要 Warp 的桌面终端。团队可以使用以下方式操作云代理工作流

Oz CLI — 从脚本、CI 或终端运行代理
Oz Web 应用 — 位于 oz.warp.dev 的可视化界面，用于管理运行、调度、环境和集成（可在手机上使用）
会话共享 — 连接到正在运行的任务进行监控或引导
管理 UI — 查看代理活动和运行历史记录
API 和 SDK — 用于自定义集成的编程访问

如果您的团队也使用 Warp 的终端，您将获得一个额外的工作流

通过 CLI 启动的任务可以移交给交互式会话进行审查、编辑或继续。
当您需要人工检查点（最终编辑、验证、合并决策）而不丢失云代理运行的审计追踪时，这非常有用。