> ## Documentation Index
> Fetch the complete documentation index at: https://docs.veadk.xyz/llms.txt
> Use this file to discover all available pages before exploring further.
# 创建定时任务
> 创建周期或一次性任务并返回任务定义与状态
任务默认启用，创建成功后会按计划调用模型与工具，并将任务和执行结果保存到 TOS。核对消息、触发时间与访问权限后再提交；如需先保存而不执行，将 `enabled` 设为 `false`
需要使用 AgentKit CLI 0.54.0 部署并[启用定时任务](/productions/api-reference/preview/zh/harness-runtime/cronjobs/overview)的 Harness Runtime
`schedule.cron` 与 `schedule.at` 必须且只能设置一个非 null 值。创建启用的一次性任务时，`at` 必须在未来且包含时区偏移
建议提供稳定的 `idempotency_key`。相同键和相同请求返回同一任务，状态仍为 `201`；相同键对应不同请求返回 `422`。省略幂等键时，每次请求都会新建任务
`harness` 使用本页的任务覆盖结构，未提供字段继承部署配置。每次执行使用独立会话，最终输出保存在 TOS
## OpenAPI
````yaml productions/api-reference/openapi/zh/harness-runtime.json POST /harness/cronjobs
openapi: 3.1.0
info:
title: Harness Runtime
version: agentkit-cli 0.54.0 / SDK 0.8.0 / ADK 2.2.0
description: >-
AgentKit CLI 0.54.0 部署的 Harness Runtime，基于 VeADK 1.0.8、AgentKit SDK 0.8.0 与
Google ADK 2.2.0 核验；定时任务另需启用配置
servers:
- url: http://localhost:8000
description: 本地服务
security:
- {}
- RuntimeBearer: []
tags:
- name: 服务与应用
- name: 会话
- name: 智能体运行
- name: 制品
- name: 记忆
- name: 评测 · 开发服务
- name: 调试 · 开发服务
- name: 兼容接口
- name: Harness 定时任务
paths:
/harness/cronjobs:
post:
tags:
- Harness Runtime cronjobs
summary: 创建定时任务
description: 创建周期或一次性任务并返回任务定义与状态
operationId: harness_cronjob_create
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CronjobCreateRequest'
examples:
recurring:
summary: 周期任务
value:
name: daily-report
prompt: Summarize recent activity
schedule:
cron: 0 9 * * *
timezone: Asia/Shanghai
idempotency_key: daily-report-v1
one-time:
summary: 一次性任务，调用时必须改为未来时间
value:
name: one-time-report
prompt: Summarize recent activity
schedule:
at: '2026-10-01T09:00:00+08:00'
idempotency_key: one-time-report-v1
overrides:
summary: 任务配置覆盖，替换 MCP 地址与凭证
value:
name: daily-report
prompt: Summarize recent activity
schedule:
cron: 0 9 * * *
timezone: Asia/Shanghai
idempotency_key: custom-report-v1
harness:
system_prompt: Produce a concise operational report
max_llm_calls: 8
mcp_servers:
- protocol: streamable-http
endpoint: https://mcp.example.com/mcp
api_key:
responses:
'201':
description: 成功；相同幂等请求再次提交也返回 201
content:
application/json:
schema:
$ref: '#/components/schemas/Cronjob'
example:
name: daily-report
prompt: Summarize recent activity
schedule:
cron: 0 9 * * *
at: null
timezone: Asia/Shanghai
enabled: true
timeout_seconds: 1800
misfire_policy: latest
misfire_grace_seconds: 120
harness: null
cronjob_id: 0e58ff7f7dcbf348c252fc70e7fdb587
revision: 1
created_at: '2026-09-16T00:00:00Z'
updated_at: '2026-09-16T00:00:00Z'
next_run_at: '2026-09-16T01:00:00Z'
active: null
last_run: null
'401':
description: 部署网关要求的服务访问凭证缺失或无效，具体响应由网关决定
'422':
description: 请求参数、调度配置或幂等键校验失败
content:
application/json:
schema:
$ref: '#/components/schemas/CronjobRequestError'
examples:
field:
value:
detail:
- loc:
- path
- job_id
msg: String should match pattern
type: string_pattern_mismatch
value:
value:
detail: Idempotency key already belongs to a different request
security:
- HarnessServiceAuth: []
x-codeSamples:
- lang: cURL
source: |-
curl --request POST "${HARNESS_URL}/harness/cronjobs" \
--header "Authorization: Bearer ${HARNESS_TOKEN}" \
--header "Content-Type: application/json" \
--data '{"name": "daily-report", "prompt": "Summarize recent activity", "schedule": {"cron": "0 9 * * *", "timezone": "Asia/Shanghai"}, "idempotency_key": "daily-report-v1"}'
- lang: Python
source: >-
import json
import os
from urllib.request import Request, urlopen
base_url = os.environ["HARNESS_URL"]
headers = {"Authorization": "Bearer " + os.environ["HARNESS_TOKEN"]}
headers["Content-Type"] = "application/json"
data = json.dumps({'name': 'daily-report', 'prompt': 'Summarize
recent activity', 'schedule': {'cron': '0 9 * * *', 'timezone':
'Asia/Shanghai'}, 'idempotency_key': 'daily-report-v1'}).encode()
request = Request(base_url + f"/harness/cronjobs", headers=headers,
method="POST", data=data)
with urlopen(request) as response:
print(json.load(response))
- lang: JavaScript
source: >-
const baseUrl = process.env.HARNESS_URL;
const headers = { Authorization: `Bearer
${process.env.HARNESS_TOKEN}` };
headers["Content-Type"] = "application/json";
const response = await fetch(`${baseUrl}/harness/cronjobs`, {
method: "POST",
headers,
body: JSON.stringify({"name": "daily-report", "prompt": "Summarize recent activity", "schedule": {"cron": "0 9 * * *", "timezone": "Asia/Shanghai"}, "idempotency_key": "daily-report-v1"}),
});
if (!response.ok) throw new Error(await response.text());
console.log(await response.json());
components:
schemas:
CronjobCreateRequest:
properties:
name:
type: string
maxLength: 128
minLength: 1
title: Name
description: 任务名称，1–128 个字符
prompt:
type: string
maxLength: 65536
minLength: 1
title: Prompt
description: 每次执行发送给智能体的消息，1–65536 个字符
schedule:
$ref: '#/components/schemas/CronjobSchedule'
description: 触发计划
harness:
anyOf:
- $ref: '#/components/schemas/CronjobHarnessOverrides'
- type: 'null'
description: 任务级配置覆盖；使用 AgentKit CLI 部署版的字段，例如 mcp_servers
enabled:
type: boolean
title: Enabled
default: true
description: 是否启用后续调度
timeout_seconds:
type: integer
maximum: 10800
minimum: 1
title: Timeout Seconds
default: 1800
description: 单次执行超时，单位为秒；超时记为 failed，不自动重试该次执行
misfire_policy:
type: string
enum:
- latest
- skip
title: Misfire Policy
default: latest
description: latest 补跑最近一次错过的触发；skip 仅在该次触发未超出宽限时间时执行。两者均不逐次补跑所有历史触发
misfire_grace_seconds:
type: integer
maximum: 86400
minimum: 0
title: Misfire Grace Seconds
default: 120
description: skip 策略允许的最大延迟，单位为秒
idempotency_key:
anyOf:
- type: string
maxLength: 128
minLength: 1
- type: 'null'
title: Idempotency Key
description: 可选幂等键。相同键和相同请求返回同一任务；同键不同请求返回 422。省略时每次创建新任务
additionalProperties: false
type: object
required:
- name
- prompt
- schedule
title: CreateJob
description: 创建任务的请求；未声明字段会被拒绝
Cronjob:
type: object
properties:
name:
type: string
maxLength: 128
minLength: 1
title: Name
description: 任务名称，1–128 个字符
prompt:
type: string
maxLength: 65536
minLength: 1
title: Prompt
description: 每次执行发送给智能体的消息，1–65536 个字符
schedule:
$ref: '#/components/schemas/CronjobSchedule'
description: 触发计划
harness:
anyOf:
- $ref: '#/components/schemas/CronjobHarnessPublicOverrides'
- type: 'null'
enabled:
type: boolean
title: Enabled
description: 是否启用后续调度
timeout_seconds:
type: integer
maximum: 10800
minimum: 1
title: Timeout Seconds
description: 单次执行超时，单位为秒；超时记为 failed，不自动重试该次执行
misfire_policy:
type: string
enum:
- latest
- skip
title: Misfire Policy
description: latest 补跑最近一次错过的触发；skip 仅在该次触发未超出宽限时间时执行。两者均不逐次补跑所有历史触发
misfire_grace_seconds:
type: integer
maximum: 86400
minimum: 0
title: Misfire Grace Seconds
description: skip 策略允许的最大延迟，单位为秒
cronjob_id:
type: string
description: 所属任务 ID
pattern: ^[a-f0-9]{32}$
revision:
type: integer
description: 任务修订号
created_at:
type: string
description: 任务创建时间，UTC
format: date-time
updated_at:
type: string
description: 任务最近更新时间，UTC
format: date-time
next_run_at:
anyOf:
- type: string
description: 下次计划触发时间，UTC；没有后续触发时为 null
format: date-time
- type: 'null'
active:
anyOf:
- $ref: '#/components/schemas/CronjobRun'
- type: 'null'
description: 当前排队、运行中或正在保存最终结果的执行
last_run:
anyOf:
- $ref: '#/components/schemas/CronjobRunSummary'
- type: 'null'
description: 最近已保存到历史的执行摘要
required:
- name
- prompt
- schedule
- harness
- enabled
- timeout_seconds
- misfire_policy
- misfire_grace_seconds
- cronjob_id
- revision
- created_at
- updated_at
- next_run_at
- active
- last_run
CronjobRequestError:
type: object
properties:
detail:
anyOf:
- type: string
- type: array
items:
$ref: '#/components/schemas/CronjobValidationError'
description: 业务校验错误说明或字段校验错误列表
required:
- detail
CronjobSchedule:
properties:
cron:
anyOf:
- type: string
- type: 'null'
title: Cron
description: 五字段 cron 表达式，依次为分钟、小时、日、月、星期；必须有未来八年内的触发时间
at:
anyOf:
- type: string
format: date-time
- type: 'null'
title: At
description: 包含时区偏移的 ISO 8601 时间；启用任务时必须在未来，与 cron 二选一
timezone:
type: string
title: Timezone
default: Asia/Shanghai
description: IANA 时区名称，用于解释 cron；at 使用其自身的偏移，但此字段仍须是有效时区
additionalProperties: false
type: object
title: Schedule
description: 周期或一次性计划，cron 与 at 必须且只能选择一个非 null 值
oneOf:
- required:
- cron
properties:
cron:
type: string
at:
type: 'null'
- required:
- at
properties:
at:
type: string
format: date-time
cron:
type: 'null'
CronjobHarnessOverrides:
properties:
model_name:
type: string
title: Model Name
default: ''
description: 本次任务使用的推理模型名称
tools:
type: string
title: Tools
default: ''
description: >-
逗号分隔的内置工具名称；CLI 0.54.0 默认部署支持的 13
个名称、用途与依赖见[内置工具](/productions/api-reference/preview/zh/harness-runtime/tools)
mcp_servers:
items:
$ref: '#/components/schemas/CronjobMcpServer'
type: array
title: Mcp Servers
description: 远程 MCP 服务列表；也接受编码为 JSON 的列表字符串
skills:
type: string
title: Skills
default: ''
description: 逗号分隔的 SkillHub slug、技能空间 ID 或空间:技能引用
system_prompt:
type: string
title: System Prompt
default: ''
description: 任务执行时使用的智能体指令
runtime:
type: string
enum:
- adk
- codex
title: Runtime
default: adk
description: 智能体运行后端
registry_space_id:
type: string
title: Registry Space Id
default: ''
description: A2A 智能体注册空间 ID
registry_endpoint:
type: string
title: Registry Endpoint
default: ''
description: A2A 智能体注册服务地址
registry_region:
type: string
title: Registry Region
default: ''
description: A2A 智能体注册服务区域
registry_top_k:
type: integer
minimum: 1
title: Registry Top K
default: 3
description: 检索的候选智能体数量，至少为 1
max_llm_calls:
anyOf:
- type: integer
minimum: 1
- type: 'null'
title: Max Llm Calls
description: 单次执行最大模型调用次数，至少为 1
additionalProperties: false
type: object
title: JobHarnessOverrides
description: 该任务每次执行时应用的配置，仅应用显式提供的字段，未提供字段继承已部署智能体
CronjobHarnessPublicOverrides:
properties:
model_name:
type: string
title: Model Name
description: 本次任务使用的推理模型名称
tools:
type: string
title: Tools
description: >-
逗号分隔的内置工具名称；CLI 0.54.0 默认部署支持的 13
个名称、用途与依赖见[内置工具](/productions/api-reference/preview/zh/harness-runtime/tools)
mcp_servers:
type: array
items:
$ref: '#/components/schemas/CronjobMcpServerPublic'
description: 任务使用的 MCP 服务，凭证已脱敏
skills:
type: string
title: Skills
description: 逗号分隔的 SkillHub slug、技能空间 ID 或空间:技能引用
system_prompt:
type: string
title: System Prompt
description: 任务执行时使用的智能体指令
runtime:
type: string
enum:
- adk
- codex
title: Runtime
description: 智能体运行后端
registry_space_id:
type: string
title: Registry Space Id
description: A2A 智能体注册空间 ID
registry_endpoint:
type: string
title: Registry Endpoint
description: A2A 智能体注册服务地址
registry_region:
type: string
title: Registry Region
description: A2A 智能体注册服务区域
registry_top_k:
type: integer
minimum: 1
title: Registry Top K
description: 检索的候选智能体数量，至少为 1
max_llm_calls:
anyOf:
- type: integer
minimum: 1
- type: 'null'
title: Max Llm Calls
description: 单次执行最大模型调用次数，至少为 1
additionalProperties: false
type: object
title: CronjobHarnessPublicOverrides
description: 该任务每次执行时应用的配置，仅应用显式提供的字段，未提供字段继承已部署智能体
CronjobRun:
type: object
properties:
cronjob_id:
type: string
description: 所属任务 ID
pattern: ^[a-f0-9]{32}$
run_id:
type: string
description: 执行 ID，用于读取或取消该次执行
pattern: ^[0-9]{13}-[a-f0-9]{20}$
revision:
type: integer
description: 本次执行使用的任务修订号
scheduled_at:
type: string
description: 计划触发时间，UTC
format: date-time
created_at:
type: string
description: 执行记录创建时间，UTC
format: date-time
prompt:
type: string
description: 本次执行的消息
harness:
anyOf:
- $ref: '#/components/schemas/CronjobHarnessPublicOverrides'
- type: 'null'
timeout_seconds:
type: integer
description: 本次执行的超时秒数
state:
type: string
description: 执行状态
enum:
- queued
- running
- succeeded
- failed
- cancelled
- skipped
- interrupted
owner:
anyOf:
- type: string
description: 执行本次任务的副本标识；尚未开始时为 null
- type: 'null'
started_at:
anyOf:
- type: string
description: 执行开始时间，UTC；尚未开始时为 null
format: date-time
- type: 'null'
completed_at:
anyOf:
- type: string
description: 执行结束时间，UTC；尚未结束时为 null
format: date-time
- type: 'null'
lease_until:
anyOf:
- type: string
description: 当前执行有效期截止时间，UTC；尚未开始时为 null
format: date-time
- type: 'null'
cancel_requested:
type: boolean
description: 是否已请求取消本次执行
output:
type: string
description: 执行输出；失败时为空。成功输出最大 1 MiB
error:
type: string
description: 失败、取消、跳过或中断的说明；无错误时为空字符串
coalesced_from:
type: string
description: 补跑合并涉及的最早错过时间，UTC；仅发生触发合并时提供
format: date-time
required:
- cronjob_id
- run_id
- revision
- scheduled_at
- created_at
- prompt
- harness
- timeout_seconds
- state
- owner
- started_at
- completed_at
- lease_until
- cancel_requested
- output
- error
CronjobRunSummary:
type: object
properties:
run_id:
type: string
description: 执行 ID，用于读取或取消该次执行
pattern: ^[0-9]{13}-[a-f0-9]{20}$
state:
type: string
description: 执行状态
enum:
- succeeded
- failed
- cancelled
- skipped
- interrupted
scheduled_at:
type: string
description: 计划触发时间，UTC
format: date-time
completed_at:
anyOf:
- type: string
description: 执行结束时间，UTC；尚未结束时为 null
format: date-time
- type: 'null'
error:
type: string
description: 失败、取消、跳过或中断的说明；无错误时为空字符串
required:
- run_id
- state
- scheduled_at
- completed_at
- error
CronjobValidationError:
properties:
loc:
items:
anyOf:
- type: string
- type: integer
type: array
title: Location
description: 校验失败字段的位置
msg:
type: string
title: Message
description: 校验失败原因
type:
type: string
title: Error Type
description: 校验错误代码
input:
title: Input
ctx:
type: object
title: Context
type: object
required:
- loc
- msg
- type
title: ValidationError
CronjobMcpServer:
properties:
protocol:
type: string
enum:
- streamable-http
- sse
title: Protocol
default: streamable-http
description: MCP 传输协议
endpoint:
type: string
title: Endpoint
description: HTTP(S) 地址，不允许用户名、密码、URL 片段或控制字符
api_key:
anyOf:
- type: string
format: password
writeOnly: true
- type: 'null'
title: Api Key
description: MCP 服务凭证，必须为单行字符串；会保存在任务存储中，读取接口仅返回脱敏值
additionalProperties: false
type: object
required:
- endpoint
title: McpServerConfig
description: 该任务可连接的远程 MCP 服务
CronjobMcpServerPublic:
properties:
protocol:
type: string
enum:
- streamable-http
- sse
title: Protocol
description: MCP 传输协议
endpoint:
type: string
title: Endpoint
description: HTTP(S) 地址，不允许用户名、密码、URL 片段或控制字符
api_key:
anyOf:
- type: string
- type: 'null'
description: 已配置的非空凭证返回 ********；未提供凭证时可省略或为 null
additionalProperties: false
type: object
required:
- endpoint
title: CronjobMcpServerPublic
description: 该任务可连接的远程 MCP 服务
securitySchemes:
RuntimeBearer:
type: http
scheme: bearer
description: 本地未配置网关时可不提供；云部署使用 Runtime API Key 或部署要求的用户池 JWT，不能使用模型 API Key
HarnessServiceAuth:
type: http
scheme: bearer
description: 服务鉴权 Harness 的 Runtime 访问凭证，例如 Runtime API Key；共享 OAuth 部署不支持后台定时任务
````