自动化

暂停运行

仅可暂停正在运行或等待中的工作流。

仅可暂停正在运行或等待中的工作流;脚本返回 OPERATION_NOT_SUPPORTED,其他状态返回 RUN_INVALID_STATE。

POST /automation/v1/runs/{id}/suspend

鉴权

Authorization: Bearer $PRAXIS_API_KEY

请求字段

参数类型说明
path: idstring必填;运行 ID(run_)。

application/json

不接受额外字段。 object

示例

先设置以下环境变量,使用你自己的资源:

: "${RUN_ID:?Set RUN_ID}"
curl --fail-with-body -X POST "https://api.deepraxis.ai/automation/v1/runs/${RUN_ID}/suspend" \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{}'
import { createAutomationClient } from '@deepractice-ai/praxis-sdk/automation';

function env(name: string): string {
  const value = process.env[name];
  if (!value) throw new Error(`Set ${name}`);
  return value;
}
const automation = createAutomationClient({
  apiKey: env('PRAXIS_API_KEY'),
  baseUrl: 'https://api.deepraxis.ai',
  maxRetries: 0,
  timeoutMs: 90_000,
});
const result = await automation.runs.suspend({
  "path": {
    "id": env("RUN_ID")
  },
  "body": {}
});
console.log(result);

响应

HTTP 200

Success

application/json

字段类型说明
idstring必填 / 必有;不透明运行 ID。新建非确定性 ID 为 run_ + 10 位 base36 毫秒时间前缀 + 64 位 hex DO ID,共 78 字符;旧随机 ID 为 46 字符,历史及确定性 ID 仍有效。同毫秒内不保证创建顺序。
kind"script" / "workflow"必填 / 必有;编排类型。script 为 TypeScript 脚本,一次执行;workflow 为 YAML 工作流,由步骤组成,可等待事件、定时器或子运行并可暂停。
numbernull / number必填 / 必有;运行在其脚本或工作流内的递增序号;临时运行为 null。
definitionnull / object必填 / 必有;运行所属的脚本或工作流 {namespace, name};临时运行(直接传 source)为 null。
definition(分支2).namespacestring必填 / 必有;脚本或工作流的命名空间。
definition(分支2).namestring必填 / 必有;脚本或工作流的名字。
targetnull / string必填 / 必有;创建时 target 参数的原文(如 acme/report@latest);临时运行为 null。
resolved_versionnull / string必填 / 必有;target 解析到的精确版本号;临时运行为 null。
source_digestnull / string必填 / 必有;临时运行的源码摘要,可用于读取源码;由已发布定义启动的运行为 null。
language"ts" / "yaml"必填 / 必有;源码语言。ts 表示 TypeScript 脚本;yaml 表示工作流 YAML。
status"running" / "completed" / "faulted" / "cancelled" / "pending" / "waiting" / "suspended"必填 / 必有;运行状态。pending 已创建尚未开始;running 执行中;waiting 工作流在等待事件、定时器或子运行;suspended 工作流被暂停;cancelled 已取消;faulted 失败,error 给出原因;completed 成功完成,output 为结果。后三种是终态。
progressnull / object必填 / 必有;运行报告的最新进度 {label, current, total, updated_at};未报告为 null。
progress(分支2).labelstring必填 / 必有;进度说明文字,例如当前阶段。
progress(分支2).currentnull / number必填 / 必有;已完成的数量;未报告为 null。
progress(分支2).totalnull / number必填 / 必有;总量;未知为 null。
progress(分支2).updated_atstring必填 / 必有;进度最近一次更新的时间(RFC 3339 UTC)。
current_waitnull / object必填 / 必有;运行当前未完成的等待点;不在等待为 null。
current_wait(分支2).idstring必填 / 必有;等待点 ID,前缀 wait_;完成事件等待点时作为路径中的 wait_id。
current_wait(分支2).run_idstring必填 / 必有;所属运行 ID(run_ 前缀)。
current_wait(分支2).kind"event" / "timer" / "child"必填 / 必有;等待类型。event 等待外部事件,可通过 runs.completeWait 提交;timer 等待到达 resume_at;child 等待子运行结束。
current_wait(分支2).state"cancelled" / "open" / "resolved" / "expired"必填 / 必有;等待点状态。open 仍在等待;resolved 已被满足;expired 已超过 expires_at;cancelled 已被取消,不会再被满足。
current_wait(分支2).tasknull / object必填 / 必有;产生该等待的工作流步骤 {reference, name};没有对应步骤为 null。
current_wait(分支2).task(分支2).referencestring必填 / 必有;步骤的 JSON Pointer,例如 /do/2/wait_payment。
current_wait(分支2).task(分支2).namestring必填 / 必有;步骤名,即工作流 YAML 中的键。
current_wait(分支2).resume_atnull / string必填 / 必有;kind=timer 时恢复运行的时刻(RFC 3339 UTC);其它类型为 null。
current_wait(分支2).event_typenull / string必填 / 必有;kind=event 时等待的事件类型;其它类型为 null。
current_wait(分支2).child_run_idnull / string必填 / 必有;kind=child 时被等待的子运行 ID;其它类型为 null。
current_wait(分支2).created_atstring必填 / 必有;等待点创建时间(RFC 3339 UTC)。
current_wait(分支2).expires_atnull / string必填 / 必有;等待点到期时间(RFC 3339 UTC);没有期限为 null。
current_wait(分支2).resolved_atnull / string必填 / 必有;等待点被满足的时间(RFC 3339 UTC);尚未满足为 null。
countersobject必填 / 必有;运行的累计计数。 不接受额外字段。
counters.callsnumber必填 / 必有;脚本发出的调用总数。
counters.action_callsnumber必填 / 必有;其中调用动作的次数。
counters.child_runsnumber必填 / 必有;启动的子运行数。
counters.tasks_completednumber必填 / 必有;工作流已完成的步骤数。
counters.tasks_totalnull / number必填 / 必有;工作流顶层步骤总数;脚本运行为 null。
inputnull / string / number / boolean / object / JSON[]必填 / 必有;任意 JSON 值:null、布尔、数字、字符串、数组或对象。
input(分支5).*null / string / number / boolean / object / JSON[]递归 JSON 值。
input(分支6)[]null / string / number / boolean / object / JSON[]递归 JSON 值。
outputnull / string / number / boolean / object / JSON[]必填 / 必有;任意 JSON 值:null、布尔、数字、字符串、数组或对象。
output(分支5).*null / string / number / boolean / object / JSON[]递归 JSON 值。
output(分支6)[]null / string / number / boolean / object / JSON[]递归 JSON 值。
errornull / object必填 / 必有;运行失败(faulted)时的错误详情;未失败为 null。
error(分支2).typestring必填 / 必有;平台错误类别,或工作流 raise 定义的完整 URI,原样保留。
error(分支2).codenull / string必填 / 必有;稳定错误码,可按码分支处理;没有为 null。
error(分支2).titlestring必填 / 必有;错误的简短标题。
error(分支2).detailnull / string必填 / 必有;错误的详细说明;没有为 null。
error(分支2).sourcenull / object必填 / 必有;错误发生的位置:工作流步骤或脚本调用;未知为 null。
error(分支2).source(分支2).kind"call" / "task"必填 / 必有;位置类型。task 表示工作流步骤;call 表示脚本中的调用。
error(分支2).source(分支2).referencestring可选;task 类型时:出错步骤的 JSON Pointer。
error(分支2).source(分支2).seqnumber可选;call 类型时:出错调用的序号(与 Call.seq 对应)。
error(分支2).source(分支2).actionobject可选;出错的动作 {name, revision};错误来自动作时才有。 不接受额外字段。
error(分支2).source(分支2).action.namestring必填 / 必有;动作全名 ns/name。
error(分支2).source(分支2).action.revisionstring必填 / 必有;执行的动作修订 ID(actr_ 前缀)。
error(分支2).request_idstring / null可选;导致失败的下游响应 X-Request-Id;没有下游响应标识时为 null 或省略。
error(分支2).errorsobject[]可选;逐字段校验错误;pointer 使用 RFC 6901 指向字段,detail 为中文修正说明。
error(分支2).errors[].pointerstring必填 / 必有;RFC 6901 字段指针。TypeScript 源码诊断为 /source(脚本)或 /implementation/source(动作);行列另见 line/column,不拼在指针后。
error(分支2).errors[].detailstring必填 / 必有;中文修正说明,指出该位置出了什么问题以及怎样改。
error(分支2).errors[].hintstring可选;可选的补充提示,给出下一步可执行的动作(例如改用另一个接口)。
error(分支2).errors[].lineinteger可选;行号,从 1 起;仅有源码位置时返回。 minimum: 1
error(分支2).errors[].columninteger可选;列号,从 1 起;仅有源码位置时返回。 minimum: 1
error(分支2).statusnumber可选;工作流 raise 声明的 HTTP 风格状态;可省略,平台错误可能不提供。
initiatorobject必填 / 必有;网关注入的主体 {type, id},表示谁发起或操作;本服务不解析名字,名字由控制台批量解析。 不接受额外字段。
initiator.type"user" / "api_key" / "agent" / "run" / "trigger"必填 / 必有;主体类型。user 为登录用户;api_key 为平台 API Key;agent 为智能体;run 为由运行本身(例如父运行)执行的操作;trigger 为触发器。
initiator.idstring必填 / 必有;主体标识,含义随 type 而定:用户 ID、API Key ID、智能体 ID、运行 ID 或触发器 ID;按不透明字符串处理。
channel"run" / "console" / "api" / "internal" / "trigger"必填 / 必有;请求进入平台的渠道。console 为控制台(经 BFF);api 为公开 API 调用;internal 为平台内部服务调用;run 为由另一个运行创建的子运行;trigger 为触发器启动。
ownerstring必填 / 必有;所属租户,由网关注入;按不透明字符串处理。
parentnull / object必填 / 必有;派生本运行的父运行 {id, number, definition};根运行为 null。
parent(分支2).idstring必填 / 必有;父运行 ID(run_ 前缀)。
parent(分支2).numbernull / number必填 / 必有;父运行在其定义内的序号;父运行是临时运行时为 null。
parent(分支2).definitionnull / object必填 / 必有;父运行所属的脚本或工作流 {namespace, name};临时运行为 null。
parent(分支2).definition(分支2).namespacestring必填 / 必有;父运行所属定义的命名空间。
parent(分支2).definition(分支2).namestring必填 / 必有;父运行所属定义的名字。
parent_run_idstring / null必填 / 必有;派生出本运行的父运行 id;根运行为 null
root_run_idstring必填 / 必有;运行树根运行的 ID;根运行自身指向自己。
depthnumber必填 / 必有;运行树中的深度:根运行为 0,每一层子运行加 1,最大 10。
attachnull / "wait" / "detach"必填 / 必有;子运行与父运行的关系。wait 表示父运行等待子运行结束,且子运行的截止时间不晚于父运行;detach 表示父运行不等待,也不会因父运行取消而被取消;根运行为 null。
deadline_atstring必填 / 必有;运行的截止时间(RFC 3339 UTC):创建时间加 deadline_seconds(脚本默认且最多 300 秒,工作流默认 86400 秒、最多 604800 秒),等待型子运行不晚于父运行截止前 1 秒。
created_atstring必填 / 必有;运行创建时间(RFC 3339 UTC)。
started_atnull / string必填 / 必有;开始执行的时间(RFC 3339 UTC);仍在排队为 null。
ended_atnull / string必填 / 必有;进入终态的时间(RFC 3339 UTC);尚未结束为 null。
updated_atstring必填 / 必有;运行记录最近一次更新的时间(RFC 3339 UTC)。
heartbeat_atnull / string必填 / 必有;执行器最近一次存活信号的时间(RFC 3339 UTC);尚未开始为 null。
cancel_requested_atnull / string必填 / 必有;收到取消请求的时间(RFC 3339 UTC);未取消为 null。
cancelled_bynull / object必填 / 必有;请求取消的主体;未取消或非人为取消为 null。
cancelled_by(分支2).type"user" / "api_key" / "agent" / "run" / "trigger"必填 / 必有;主体类型。user 为登录用户;api_key 为平台 API Key;agent 为智能体;run 为由运行本身(例如父运行)执行的操作;trigger 为触发器。
cancelled_by(分支2).idstring必填 / 必有;主体标识,含义随 type 而定:用户 ID、API Key ID、智能体 ID、运行 ID 或触发器 ID;按不透明字符串处理。
cancel_reasonnull / "user" / "parent_cancelled" / "deadline" / "executor_lost"必填 / 必有;取消原因。user 为用户取消;parent_cancelled 为父运行被取消而级联取消;deadline 为超过截止时间;executor_lost 为执行器丢失;未取消为 null。
suspend_requested_atnull / string必填 / 必有;请求暂停工作流的时间(RFC 3339 UTC);未暂停为 null。
suspended_bynull / object必填 / 必有;请求暂停的主体;未暂停为 null。
suspended_by(分支2).type"user" / "api_key" / "agent" / "run" / "trigger"必填 / 必有;主体类型。user 为登录用户;api_key 为平台 API Key;agent 为智能体;run 为由运行本身(例如父运行)执行的操作;trigger 为触发器。
suspended_by(分支2).idstring必填 / 必有;主体标识,含义随 type 而定:用户 ID、API Key ID、智能体 ID、运行 ID 或触发器 ID;按不透明字符串处理。
queued_msnull / number必填 / 必有;从创建到开始执行的排队毫秒数;尚未开始为 null。
run_msnull / number必填 / 必有;实际执行毫秒数,不含等待点上的等待时间;结束后固定。
wait_msnull / number必填 / 必有;在等待点上累计等待的毫秒数;尚无等待为 null。
usageobject / null必填 / 必有;仅单个运行详情(含 expand)返回;列表为 null。运行本身不收费;这里是运行中调用模型、搜索等能力产生的实扣,按调用归因;未评级的用量稍后计入。汇总超时(1.5 秒)或失败时为 null,详情仍返回 200。
usage(分支1).currency"USD"必填 / 必有;金额币种,固定为 USD。
usage(分支1).coststring必填 / 必有;仅本运行自身的已评级实扣(不含子运行),美元十进制字符串,精确到 6 位小数;没有用量时为 0.000000。 pattern: "^[0-9]+\.[0-9]{6}$"
usage(分支1).pending_eventsinteger必填 / 必有;本运行自身尚未评级的用量事件数,金额稍后才计入。 minimum: 0
usage(分支1).by_serviceobject[]必填 / 必有;本运行按服务拆分的实扣,每项为 service 与 cost(6 位小数美元字符串);没有用量时为空数组。
usage(分支1).by_service[].servicestring必填 / 必有;产生用量的服务名,例如 router 或 search。
usage(分支1).by_service[].coststring必填 / 必有;该服务已评级实扣的美元十进制字符串,精确到 6 位小数。 pattern: "^[0-9]+\.[0-9]{6}$"
usage(分支1).tree_coststring / null必填 / 必有;仅根运行返回整棵运行树的已评级实扣(含自身),6 位小数美元字符串;子运行为 null。
rerun_ofnull / string必填 / 必有;重跑来源:本运行是对哪个运行(run_ ID)的重跑;否则为 null。
labelsobject必填 / 必有;用户标签与系统标签;触发器运行支持 64 个用户标签,系统标签不占用名额。
triggerobject / null必填 / 必有;启动本运行的触发器 {id, name};不是触发器启动时为 null。
trigger(分支1).idstring必填 / 必有;启动本运行的触发器 ID(trg_ 前缀)。
trigger(分支1).namestring必填 / 必有;启动本运行的触发器名称。
cancel_messagestring / null必填 / 必有;用户提供的取消备注(1–500 字符);未提供时为 null,cancel_reason 枚举不变。
input_truncatedboolean可选;列表省略外置 input 时为 true,此时 input 为 null;内联值不变,运行详情返回完整值。
output_truncatedboolean可选;列表省略外置 output 时为 true,此时 output 为 null;内联值不变,运行详情返回完整值。

实测响应

HTTP 200

{
  "id": "run_00mv67mkw52c7fa90cc9649b1053e66fd836b071f289acb667ff8ca853e65bc4608e9a45bd",
  "kind": "workflow",
  "number": null,
  "definition": null,
  "target": null,
  "resolved_version": null,
  "source_digest": "1f559f7323adda4865d889639a4d878eab97e1ce3e542c68ea4022af4cd0f7fa",
  "language": "yaml",
  "status": "suspended",
  "progress": null,
  "current_wait": {
    "id": "wait_wf-eebc9ef34869206fa1bcc1e2ae6375990a7ab34c5ad485ac98a4f189c4b37346",
    "run_id": "run_00mv67mkw52c7fa90cc9649b1053e66fd836b071f289acb667ff8ca853e65bc4608e9a45bd",
    "kind": "event",
    "state": "open",
    "task": {
      "reference": "/do/0/ready",
      "name": "ready"
    },
    "resume_at": null,
    "event_type": "ready",
    "child_run_id": null,
    "created_at": "2026-10-13T04:57:56.982Z",
    "expires_at": "2026-10-14T04:57:50.405Z",
    "resolved_at": null
  },
  "counters": {
    "calls": 0,
    "action_calls": 0,
    "child_runs": 0,
    "tasks_completed": 0,
    "tasks_total": 1
  },
  "input": {},
  "output": null,
  "error": null,
  "initiator": {
    "type": "api_key",
    "id": "key_3e00b8984967"
  },
  "channel": "api",
  "owner": "tnt_3a9759864ccb4e00",
  "trigger": null,
  "parent": null,
  "parent_run_id": null,
  "root_run_id": "run_00mv67mkw52c7fa90cc9649b1053e66fd836b071f289acb667ff8ca853e65bc4608e9a45bd",
  "depth": 0,
  "attach": null,
  "deadline_at": "2026-10-14T04:57:50.405Z",
  "created_at": "2026-10-13T04:57:50.405Z",
  "started_at": "2026-10-13T04:57:56.933Z",
  "ended_at": null,
  "updated_at": "2026-10-13T04:57:58.173Z",
  "heartbeat_at": null,
  "cancel_requested_at": null,
  "cancelled_by": null,
  "cancel_reason": null,
  "cancel_message": null,
  "suspend_requested_at": "2026-10-13T04:57:58.173Z",
  "suspended_by": {
    "type": "api_key",
    "id": "key_3e00b8984967"
  },
  "queued_ms": 6528,
  "run_ms": null,
  "wait_ms": null,
  "usage": null,
  "rerun_of": null,
  "labels": {
    "namespace": "docs-samples",
    "name": "sample-run-1791867412840-b05e8a"
  }
}

错误码

HTTP错误码与说明
400INVALID_PARAMS:请求参数、路径、游标或请求体格式无效。
404RUN_NOT_FOUND:运行不存在或当前租户不可见。
409OPERATION_NOT_SUPPORTED:该资源类型不支持此操作。 RUN_INVALID_STATE:当前状态不允许执行该动作。
defaultRFC 9457 automation problem. 429 includes Retry-After.

鉴权错误与通用错误 · 排查时保留响应头 X-Request-Id。

导出

本页内容