> ## Documentation Index > Fetch the complete documentation index at: https://docs.qoder.com/llms.txt > Use this file to discover all available pages before exploring further. # 创建 Deployment > 创建一个定时或手动触发的 Deployment，将 Agent 按 cron 调度或手动执行。 `POST /api/v1/cloud/deployments` 创建一个新的 Deployment。Deployment 将 Agent 绑定到 cron 调度（或纯手动触发）、一个 Environment 和一组初始事件。创建后状态为 `active`，如果配置了 schedule 会立即按计划执行。 ## 请求头 | 头部 | 必选 | 说明 | | --------------- | -- | ------------------ | | `Authorization` | 是 | `Bearer ` | | `Content-Type` | 是 | `application/json` | ## 请求体 | 字段 | 类型 | 必选 | 说明 | | ----------------------- | --------------- | -- | --------------------------------------------------------------------------------------------------------------------------- | | `name` | string | 是 | Deployment 名称（最长 256 字符） | | `description` | string | 否 | 描述信息 | | `agent` | string 或 object | 是 | Agent 引用。纯字符串 `"agent_xxx"`（使用最新版本）或对象 `{"id": "agent_xxx", "type": "agent", "version": 2}`（锁定版本）。对象形式必须包含 `type: "agent"`。 | | `environment_id` | string | 是 | Environment ID（`env_` 前缀） | | `schedule` | object | 否 | Cron 调度配置。不传则为纯手动触发（响应中 schedule 为 `null`）。见下方 **Schedule 对象**。 | | `initial_events` | array | 是 | 每次运行时发送给 Agent 的事件数组（1–50 个）。每个事件必须含 `type` 字段。允许类型：`user.message`、`user.define_outcome`、`system.message`。 | | `resources` | array | 否 | 附加到每次 session 的资源（如 `github_repository`、`file`、`memory_store`）。默认 `[]`。 | | `vault_ids` | array | 否 | 注入凭据的 Vault ID 列表。默认 `[]`，最多 50 个。 | | `metadata` | object | 否 | 自定义字符串键值元数据（最多 16 个 key，key ≤64 字符，value ≤512 字符）。value 必须是字符串。 | | `environment_variables` | string | 否 | Deployment 级环境变量，会注入到该 Deployment 创建的 Session 中。格式为以 `;` 或换行分隔的 `KEY=VALUE` 字符串。Self-hosted Environment 不支持。 | ### Schedule 对象 | 字段 | 类型 | 必选 | 说明 | | ------------ | ------ | -- | -------------------------------- | | `type` | string | 是 | 必须为 `"cron"` | | `expression` | string | 是 | 标准 5 段 cron 表达式（如 `"0 9 * * *"`） | | `timezone` | string | 是 | IANA 时区（如 `"Asia/Shanghai"`） | ### environment\_variables 校验 `environment_variables` 复用创建 Session 的校验规则：变量名必须匹配 `[A-Za-z_][A-Za-z0-9_]*`，保留名称/前缀会被拒绝，重复 key 会被拒绝，并受总大小限制。响应会返回按 key 排序并以换行连接的规范化字符串。 ## 示例请求 ```bash theme={null} curl -X POST "https://api.qoder.com/api/v1/cloud/deployments" \ -H "Authorization: Bearer $QODER_PAT" \ -H "Content-Type: application/json" \ -d '{ "name": "api-doc-verification-deployment", "description": "Deployment created for API documentation verification", "agent": "agent_019ebb21ef8e7df6a559052c94875160", "environment_id": "env_019e49a1780171daac1e6b01f290ac2b", "schedule": { "type": "cron", "expression": "0 9 * * *", "timezone": "Asia/Shanghai" }, "initial_events": [ { "type": "user.message", "content": [ { "type": "text", "text": "Generate today'\''s status report" } ] } ], "resources": [], "vault_ids": [], "metadata": { "team": "platform" }, "environment_variables": "FEATURE_FLAG=on;LOG_LEVEL=info" }' ``` ## 示例响应 **HTTP 200 OK** ```json theme={null} { "agent": { "id": "agent_019ebb21ef8e7df6a559052c94875160", "type": "agent", "version": 1 }, "archived_at": null, "created_at": "2026-06-14T08:58:01Z", "description": "Deployment created for API documentation verification", "environment_id": "env_019e49a1780171daac1e6b01f290ac2b", "environment_variables": "FEATURE_FLAG=on\nLOG_LEVEL=info", "id": "dep_019ec55a2b687b3f94eee77dd77e4b2a", "initial_events": [ { "content": [ { "type": "text", "text": "Generate today's status report" } ], "type": "user.message" } ], "metadata": { "team": "platform" }, "name": "api-doc-verification-deployment", "paused_reason": null, "resources": [], "schedule": { "expression": "0 9 * * *", "timezone": "Asia/Shanghai", "type": "cron", "upcoming_runs_at": [ "2026-06-15T01:00:00Z", "2026-06-16T01:00:00Z", "2026-06-17T01:00:00Z", "2026-06-18T01:00:00Z", "2026-06-19T01:00:00Z" ] }, "status": "active", "type": "deployment", "updated_at": "2026-06-14T08:58:01Z", "vault_ids": [] } ``` ## 响应字段 | 字段 | 类型 | 说明 | | --------------------------- | ------------- | ------------------------------------------------ | | `id` | string | Deployment 唯一标识（`dep_` 前缀） | | `type` | string | 固定值 `"deployment"` | | `name` | string | Deployment 名称 | | `description` | string 或 null | 描述 | | `agent` | object | Agent 引用：`{id, type, version}` | | `environment_id` | string | 关联的 Environment ID | | `schedule` | object 或 null | 调度配置，含 `upcoming_runs_at`（纯手动时为 null） | | `schedule.expression` | string | Cron 表达式 | | `schedule.timezone` | string | IANA 时区 | | `schedule.type` | string | 固定 `"cron"` | | `schedule.upcoming_runs_at` | array | 未来 5 次调度时间（UTC，ISO 8601） | | `schedule.last_run_at` | string | 上次执行时间（首次运行后出现） | | `initial_events` | array | 每次运行时发送的事件 | | `resources` | array | 附加资源 | | `vault_ids` | array | 关联的 Vault ID 列表 | | `metadata` | object | 自定义字符串键值元数据 | | `environment_variables` | string | 规范化后的 `KEY=VALUE` 行，会注入到该 Deployment 创建的 Session | | `status` | string | `"active"` 或 `"paused"` | | `paused_reason` | object 或 null | 暂停原因（如 `{"type":"manual"}`） | | `archived_at` | string 或 null | 归档时间（ISO 8601）或 null | | `created_at` | string | 创建时间（ISO 8601） | | `updated_at` | string | 最后更新时间（ISO 8601） | ## CMA 对齐 本端点对齐 Anthropic CMA `POST /v1/deployments` 规范。主要差异： * `agent` 字段同时接受字符串和对象形式（CMA 仅要求对象形式）。 * `environment_variables` 是 Qoder Deployment 扩展字段，会保存在 Deployment 模板上，并复制到 Deployment Run 创建的 Session。 * 响应中 schedule 对象含 `upcoming_runs_at` 字段（未来 5 次触发时间）。 ## 错误码 | HTTP | type | 触发条件 | | ---- | ----------------------- | ------------------------------------------------------------------------------------------------------------------------- | | 400 | `invalid_request_error` | 缺少必填字段、对象形式 `agent` 缺少 `type: "agent"`、无效 cron 表达式、metadata 或 environment\_variables 无效、未知事件类型，或引用的 Agent/Environment 已归档 | | 401 | `authentication_error` | PAT 无效或过期 | | 404 | `not_found_error` | Agent 或 Environment 不存在 | 完整错误信封说明详见 [错误参考](/zh/cloud-agents/api/conventions/errors)。 ## 相关 分页查询账号下的所有 Deployment。 查看单个 Deployment 的详细信息。 修改名称、调度、资源等可变字段。 所有 API 错误码与错误信封约定。