定时任务

Deployment 把 Agent 变成一个可以按计划自动运行的任务：绑定 cron 调度与初始指令，每次触发时平台自动创建一个新会话执行。适合日报生成、数据巡检、定期同步这类无人值守的工作。没有 cron 的 Deployment 也可以只用于手动触发（manual-only）。

创建 Deployment

deployment=$(curl -sS "$BASE_URL/v1/deployments" \
  -H "Authorization: Bearer $ZHIPUAI_API_KEY" \
  -H "zai-version: 2026-05-26" \
  -H "zai-beta: managed-agents-2026-05-26" \
  -H "content-type: application/json" \
  -d @- <<EOF
{
  "name": "Daily report",
  "agent": "$AGENT_ID",
  "environment_id": "$ENVIRONMENT_ID",
  "schedule": {
    "type": "cron",
    "expression": "0 9 * * 1-5",
    "timezone": "Asia/Shanghai"
  },
  "initial_events": [
    {
      "type": "user.message",
      "content": [
        { "type": "text", "text": "生成昨日销售日报，保存到 /mnt/session/outputs/report.md" }
      ]
    }
  ]
}
EOF
)

DEPLOYMENT_ID=$(jq -r '.id' <<< "$deployment")

字段说明

字段	必填	说明
name	是	非空名称
agent	是	Agent ID 字符串（跟随最新版本），或对象形态固定版本 / 带 override：`{"type": "agent", "id": "...", "version": 3}`
environment_id	是	运行环境；须为自有且未归档的 Environment。Deployment 只保存引用，每次触发按环境当前配置固化进新会话；环境被归档或删除后，下一次触发失败
schedule	否	`{"type": "cron", "expression", "timezone"}`；省略则为 manual-only。expression 为 5 段 cron 且须存在未来触发点，相邻触发默认间隔 ≥5 分钟；timezone 当前仅支持 Asia/Shanghai（默认）
initial_events	是	非空的 user.message 列表，内容块支持 text / image（不支持 document）；image 只接受 `source.type=base64`，且 Agent 模型须支持图片输入，见事件与流式输出。每次触发都以这组事件启动新会话
resources	否	与会话相同：file ≤500 个 + memory_store ≤8 个
vault_ids	否	MCP / 环境变量凭据引用
description / metadata	否	用途说明与自定义元数据（≤16 个 string 键值）

如果 Agent 配置或本次 override 挂载了 Skill，tools 必须同时包含 agent_toolset_20260601，否则创建或更新返回 400。响应中的 agent.version 是创建时固定（pin）下来的真实版本号。schedule.upcoming_runs_at 最多返回接下来 5 个计划时间，下次触发取第一项；manual-only 时 schedule 为 null。

部署触发时通常没有客户端在线。自定义工具和 always_ask 不会被接口拒绝，但没人回结果或批准时，会话会停在 requires_action。无人值守的定时任务应只用内置工具和 always_allow 的 MCP，凭据走 vault_ids。

记忆让定时任务有连续性

每次触发都是全新会话，默认不共享任何状态。挂载 read_write 的 Memory Store 后，Agent 可以记住上次运行处理到哪里：

{
  "resources": [
    {
      "type": "memory_store",
      "memory_store_id": "memstore_xxxxxxxx",
      "access": "read_write",
      "instructions": "运行结束时把本次处理的截止位置写入 /state/checkpoint.md"
    }
  ]
}

查看运行记录

每次触发（定时或手动）产生一条 DeploymentRun，记录触发上下文与创建的会话：

curl -sS "$BASE_URL/v1/deployment_runs?deployment_id=$DEPLOYMENT_ID" \
  -H "Authorization: Bearer $ZHIPUAI_API_KEY" \
  -H "zai-version: 2026-05-26" \
  -H "zai-beta: managed-agents-2026-05-26"

Run 的关键字段：trigger_context（type 为 schedule 或 manual，schedule 触发含 scheduled_at）、session_id（该次运行创建的会话；刚返回时可能为 null，通常数秒后填上）、error（异步失败摘要，成功为 null）、agent（本次运行实际使用的 Agent 版本）。列表支持 deployment_id、has_error、trigger_type、created_at[gte] / created_at[lte] 过滤，limit 默认 50。单条详情用 GET /v1/deployment_runs/:runId。 session_id 出现后，用 GET /v1/sessions/:id/events 查看执行过程，用 GET /v1/files?scope_id=<session_id> 下载产出。

手动触发

curl -sS -X POST "$BASE_URL/v1/deployments/$DEPLOYMENT_ID/run" \
  -H "Authorization: Bearer $ZHIPUAI_API_KEY" \
  -H "zai-version: 2026-05-26" \
  -H "zai-beta: managed-agents-2026-05-26"

手动运行直接插入一条 run，不影响后续定时计划；暂停期间也允许手动触发。适合调试 initial_events 与验证产出，无需等到下一个调度点。

暂停、恢复与归档

操作	语义
POST /v1/deployments/:id/pause	停止后续定时触发；手动 run 仍允许
POST /v1/deployments/:id/unpause	以当前时间为锚重算 schedule.upcoming_runs_at；暂停期间漏掉的触发不会补跑
POST /v1/deployments/:id	更新 name / schedule / initial_events 等；改 schedule 同样以当下为锚重算
POST /v1/deployments/:id/archive	终态且幂等；归档后不再触发、不可手动 run（409），历史 run 仍可查询

列表 GET /v1/deployments 支持 agent_id、status（active / paused）、created_at[gte] / created_at[lte]、include_archived 过滤。

下一步

记忆

让跨运行状态可持久

事件与流式输出

分析每次运行的执行过程

文件

下载运行产出

本页对应 OpenAPI

Deployment 与 Deployment Run

开始使用

定义 Agent

配置运行环境

运行会话

上下文与记忆

自动化

参考

创建 Deployment

字段说明

记忆让定时任务有连续性

查看运行记录

手动触发

暂停、恢复与归档

下一步

记忆

事件与流式输出

文件

本页对应 OpenAPI

​创建 Deployment

​字段说明

​记忆让定时任务有连续性

​查看运行记录

​手动触发

​暂停、恢复与归档

​下一步

记忆

事件与流式输出

文件

本页对应 OpenAPI

创建 Deployment

字段说明

记忆让定时任务有连续性

查看运行记录

手动触发

暂停、恢复与归档

下一步