AxonX

简体中文

English

简体中文

English

Appearance

任务 API ​

任务提交、状态、日志和血缘查询共用 Job 协议。先查询注册定义，再提交输入；对特定执行使用 task_id 与 run_id 等待。

任务 API调用示意

调用约定 ​

以下均为 POST /jobs/{name}，请求体是 {"arguments":{...}}。远程转发时在封装顶层添加 target，不能放进 arguments。每个响应使用 JobResponse，表格默认值依据当前内置配置和 Step。部署可修改 Job Schema，运行服务的 /jobs 是最终依据。

所有示例 JSON 均为结构示例；任务、会话、文件路径与哈希必须替换为本服务实际返回的值。完整通用 TaskStatus 字段见 Task 协议。

接口清单 ​

Job用途
list_installed_task_definitions枚举当前 Python 环境中的内置与插件 Task。
get_task_definition查询一个注册定义及输入输出 Schema。
submit启动独立子进程运行 Task。
wait_task等待提交返回的特定执行结束。
list_task_ids列出存在状态文件的任务身份。
list_task_statuses列出状态快照。
status读取一个任务的当前状态。
read_task_log按有界字节窗口读取日志。
stream_task持续跟踪进度与日志直到任务停止。
get_task_graph读取包含所选 Task 的依赖图。
get_task_context为 Agent 提供任务路径、状态与关系上下文。
cancel请求取消本服务管理的活跃 worker。
delete_tasks删除终态或 metadata-only Task 与关联文件。

list_installed_task_definitions ​

枚举当前 Python 环境中的内置与插件 Task。

无公开业务参数；使用 {"arguments":{}}。

请求

json
{
  "arguments": {}
}

响应

answer 是 TaskDefinition 数组。每项含 name、source（native/plugin）、plugin、task_type、description、input_schema、output_schema。

json
{
  "answer": [],
  "success": true,
  "metadata": {}
}

行为与失败情况

输出按注册名排序。某个插件类型错误或缺少详细类 docstring，可能使完整目录查询失败。

get_task_definition ​

查询一个注册定义及输入输出 Schema。

参数类型必填默认值约束与含义
taskstring是—（省略）Task 注册名，不是 Task ID；minLength=1

只接受表中业务字段。

请求

json
{
  "arguments": {
    "task": "demo"
  }
}

响应

answer 是一个 TaskDefinition；Schema 是 JSON Schema，不是任务执行结果。

json
{
  "answer": {
    "name": "demo",
    "source": "native",
    "plugin": null,
    "task_type": "base",
    "description": "Demonstrate synchronous Task execution with a small arithmetic workflow.",
    "input_schema": {
      "type": "object",
      "required": ["x", "y"]
    },
    "output_schema": {
      "type": "object"
    }
  },
  "success": true,
  "metadata": {}
}

行为与失败情况

上面的 Schema 为节选；完整 Schema 以接口返回为准。未知注册名返回业务失败。

submit ​

启动独立子进程运行 Task。

参数类型必填默认值约束与含义
taskstring是—（省略）Task 注册名，不是 Task ID

submit 的 Schema 允许额外字段；除 task 外的字段作为 Task 输入传递，由对应 input_cls 校验，未知输入字段会失败。

请求

json
{
  "arguments": {
    "task": "demo",
    "task_name": "api-demo",
    "x": 1,
    "y": 2
  }
}

响应

answer 是 TaskHandle：task_id、run_id、task。success=true 表示提交成功。

json
{
  "answer": {
    "task_id": "base#demo#api-demo",
    "run_id": "f5caee3a7b3c40849d0fb3bdc0f0cd23",
    "task": "demo"
  },
  "success": true,
  "metadata": {}
}

行为与失败情况

所有 Task 输入字段跟 task 同级传入；demo 的 x、y 必填，fail=false。

通用 Task 输入由具体 Task 的 input_schema 一并公布：

输入类型默认值规则
task_namestring/nullnull省略或空字符串产生匿名名；固定名为 1–32 个英文字母、数字或连字符
source_tasksstring空字符串完整上游 Task ID，以英文逗号分隔；不是字符串数组
demo.x / demo.yinteger必填两个运算输入；提交时字段名是 x/y，没有 demo 前缀
demo.failbooleanfalse内置失败演示开关；不是全部 Task 的通用参数

插件 Task 的研究参数以 get_task_definition 返回为准，不能把 demo 字段套到其他注册名上。通用 task_name 可省略，source_tasks 默认为空字符串。固定名称只能替换已结束任务，活跃目录产生 FileExistsError；必须保存 run_id。

wait_task ​

等待提交返回的特定执行结束。

参数类型必填默认值约束与含义
task_idstring是—（省略）完整 Task ID；minLength=1
run_idstring是—（省略）提交返回的本次执行 ID；minLength=1
poll_intervalnumber否1轮询间隔，单位秒；exclusiveMinimum=0

只接受表中业务字段。

请求

json
{
  "arguments": {
    "task_id": "base#demo#api-demo",
    "run_id": "f5caee3a7b3c40849d0fb3bdc0f0cd23"
  }
}

响应

answer 是终态 TaskStatus；只有 state=succeeded 时 success=true。

json
{
  "answer": {
    "task_id": "base#demo#api-demo",
    "run_id": "f5caee3a7b3c40849d0fb3bdc0f0cd23",
    "task_type": "base",
    "task_name": "demo",
    "state": "succeeded",
    "config": {
      "task_name": "api-demo",
      "source_tasks": "",
      "x": 1,
      "y": 2,
      "fail": false
    },
    "created_at": "2026-10-02T00:00:00Z",
    "started_at": null,
    "finished_at": null,
    "pid": null,
    "exit_code": 0,
    "error": "",
    "result": {},
    "steps": [],
    "log_path": ""
  },
  "success": true,
  "metadata": {}
}

行为与失败情况

poll_interval 默认 1 秒，没有业务超时参数。客户端 timeout 应覆盖等待时间。run_id 与目录当前执行不一致时失败，不能用旧 run_id 等待新任务。

list_task_ids ​

列出存在状态文件的任务身份。

无公开业务参数；使用 {"arguments":{}}。

请求

json
{
  "arguments": {}
}

响应

answer 是字符串 Task ID 数组。

json
{
  "answer": ["base#demo#api-demo"],
  "success": true,
  "metadata": {}
}

行为与失败情况

metadata-only 目录没有状态时不进入此列表；列表不是全历史执行清单。

list_task_statuses ​

列出状态快照。

无公开业务参数；使用 {"arguments":{}}。

请求

json
{
  "arguments": {}
}

响应

answer 是 TaskStatus 数组，按 created_at 与 task_id 倒序。

json
{
  "answer": [],
  "success": true,
  "metadata": {}
}

行为与失败情况

不提供服务器分页与筛选参数。需要筛选时由客户端按类型、状态和配置处理。

status ​

读取一个任务的当前状态。

参数类型必填默认值约束与含义
task_idstring是—（省略）完整 Task ID

Schema 未禁止额外字段；不要据此假定额外字段会被使用。

请求

json
{
  "arguments": {
    "task_id": "base#demo#api-demo"
  }
}

响应

answer 是 TaskStatus：身份、config、state、时间、pid、exit_code、error、steps、log_path。

json
{
  "answer": {
    "task_id": "base#demo#api-demo",
    "run_id": "f5caee3a7b3c40849d0fb3bdc0f0cd23",
    "task_type": "base",
    "task_name": "demo",
    "state": "queued",
    "config": {
      "task_name": "api-demo",
      "source_tasks": "",
      "x": 1,
      "y": 2,
      "fail": false
    },
    "created_at": "2026-10-02T00:00:00Z",
    "started_at": null,
    "finished_at": null,
    "pid": null,
    "exit_code": 0,
    "error": "",
    "result": {},
    "steps": [],
    "log_path": ""
  },
  "success": true,
  "metadata": {}
}

行为与失败情况

不存在或只有 metadata 的任务没有状态时返回 KeyError 业务失败。queued/running 不是终态。

read_task_log ​

按有界字节窗口读取日志。

参数类型必填默认值约束与含义
task_idstring是—（省略）完整 Task ID
offsetinteger否-1日志读取起始字节偏移；-1 读取尾部；minimum=-1
limitinteger否65536最多读取的字节数；minimum=1024, maximum=262144

Schema 未禁止额外字段；不要据此假定额外字段会被使用。

请求

json
{
  "arguments": {
    "task_id": "base#demo#api-demo",
    "offset": -1,
    "limit": 65536
  }
}

响应

answer 是 TaskLogChunk：content、start_offset、next_offset、file_size、has_more_before、has_more_after、reset。

json
{
  "answer": {
    "content": "Demo result=3\n",
    "start_offset": 0,
    "next_offset": 14,
    "file_size": 14,
    "has_more_before": false,
    "has_more_after": false,
    "reset": false
  },
  "success": true,
  "metadata": {}
}

行为与失败情况

offset=-1 读取尾部；offset=0 从头开始。limit 单位字节，不是行数。UTF-8 解码后字符串长度不能代替 next_offset；持续读取用返回的 next_offset。

stream_task ​

持续跟踪进度与日志直到任务停止。

参数类型必填默认值约束与含义
task_idstring是—（省略）完整 Task ID；minLength=1
poll_intervalnumber否0.5轮询间隔，单位秒；exclusiveMinimum=0

只接受表中业务字段。

请求

json
{
  "arguments": {
    "task_id": "base#demo#api-demo"
  }
}

响应

普通调用 answer 是终态 TaskStatus；SSE 有 progress/log，最终 result 携带相同状态。success 按 exit_code==0 设置。

json
{
  "answer": {
    "task_id": "base#demo#api-demo",
    "run_id": "f5caee3a7b3c40849d0fb3bdc0f0cd23",
    "task_type": "base",
    "task_name": "demo",
    "state": "succeeded",
    "config": {
      "task_name": "api-demo",
      "source_tasks": "",
      "x": 1,
      "y": 2,
      "fail": false
    },
    "created_at": "2026-10-02T00:00:00Z",
    "started_at": null,
    "finished_at": null,
    "pid": null,
    "exit_code": 0,
    "error": "",
    "result": {},
    "steps": [],
    "log_path": ""
  },
  "success": true,
  "metadata": {}
}

行为与失败情况

默认 poll_interval=0.5 秒。普通 HTTP 调用也会等待到终态，日志事件不会全部装进 answer；实时显示应使用 /events。

get_task_graph ​

读取包含所选 Task 的依赖图。

参数类型必填默认值约束与含义
task_idstring是—（省略）完整 Task ID

只接受表中业务字段。

请求

json
{
  "arguments": {
    "task_id": "base#demo#api-demo"
  }
}

响应

answer 含 root_id、selected_id、nodes、edges；节点区分 missing、provisional。

json
{
  "answer": {
    "root_id": "base#demo#api-demo",
    "selected_id": "base#demo#api-demo",
    "nodes": [
      {
        "task_id": "base#demo#api-demo",
        "kind": "base",
        "task_name": "demo",
        "created_at": "2026-10-02T00:00:00+00:00",
        "parent_ids": [],
        "state": "queued",
        "missing": false,
        "provisional": true
      }
    ],
    "edges": []
  },
  "success": true,
  "metadata": {}
}

行为与失败情况

图来自 status/metadata 中的 source_tasks，只呈现记录关系，不会执行 DAG。节点结构详见任务血缘文档；此例仅展示顶层形状。

get_task_context ​

为 Agent 提供任务路径、状态与关系上下文。

参数类型必填默认值约束与含义
task_idstring是—（省略）完整 Task ID；minLength=1

只接受表中业务字段。

请求

json
{
  "arguments": {
    "task_id": "base#demo#api-demo"
  }
}

响应

answer 含 task_id、status、metadata_exists、metadata_path、log_path、graph、relations。relations 包括 direct_upstream、ancestors、direct_downstream、missing、provisional。

json
{
  "answer": {
    "task_id": "base#demo#api-demo",
    "status": {
      "task_id": "base#demo#api-demo",
      "run_id": "f5caee3a7b3c40849d0fb3bdc0f0cd23",
      "task_type": "base",
      "task_name": "demo",
      "state": "queued",
      "config": {
        "task_name": "api-demo",
        "source_tasks": "",
        "x": 1,
        "y": 2,
        "fail": false
      },
      "created_at": "2026-10-02T00:00:00Z",
      "started_at": null,
      "finished_at": null,
      "pid": null,
      "exit_code": 0,
      "error": "",
      "result": {},
      "steps": [],
      "log_path": ""
    },
    "metadata_exists": false,
    "metadata_path": "base/base#demo#api-demo/metadata.json",
    "log_path": null,
    "graph": {
      "root_id": "base#demo#api-demo",
      "selected_id": "base#demo#api-demo",
      "nodes": [
        {
          "task_id": "base#demo#api-demo",
          "kind": "base",
          "task_name": "demo",
          "created_at": "2026-10-02T00:00:00+00:00",
          "parent_ids": [],
          "state": "queued",
          "missing": false,
          "provisional": true
        }
      ],
      "edges": []
    },
    "relations": {
      "direct_upstream": [],
      "ancestors": [],
      "direct_downstream": [],
      "missing": [],
      "provisional": ["base#demo#api-demo"]
    }
  },
  "success": true,
  "metadata": {}
}

行为与失败情况

metadata_exists 是图中节点已发布元数据的判断，不能仅靠任务提交成功推断产物存在。

cancel ​

请求取消本服务管理的活跃 worker。

参数类型必填默认值约束与含义
task_idstring是—（省略）完整 Task ID

Schema 未禁止额外字段；不要据此假定额外字段会被使用。

请求

json
{
  "arguments": {
    "task_id": "base#demo#api-demo"
  }
}

响应

answer 是布尔值；true 表示本次完成取消，false 表示没有取消。

json
{
  "answer": false,
  "success": true,
  "metadata": {}
}

行为与失败情况

已终态或没有可取消的管理进程返回 false；success=true 与 answer=false 可同时出现。取消研究任务不等于取消 Agent 轮次。

delete_tasks ​

删除终态或 metadata-only Task 与关联文件。

参数类型必填默认值约束与含义
task_idsarray是—（省略）待删除的完整 Task ID 列表；minItems=1, uniqueItems=True

Schema 未禁止额外字段；不要据此假定额外字段会被使用。

请求

json
{
  "arguments": {
    "task_ids": ["base#demo#api-demo"]
  }
}

响应

answer 是实际删除成功的 Task ID 列表。

json
{
  "answer": ["base#demo#api-demo"],
  "success": true,
  "metadata": {}
}

行为与失败情况

活跃任务、非法 ID、不存在任务或受管理的执行会被跳过；比较请求与返回列表，不能将 success=true 理解为全部已删。

失败响应示例 ​

Schema 失败在执行前返回 HTTP 422，例如 wait_task 缺 run_id；Task 执行或查询异常通常返回 HTTP 200 与 success=false。未知 Task 注册名示例：

json
{
  "answer": "ValueError: Unknown Task: missing. Available: demo",
  "success": false,
  "metadata": {}
}

Available 列表由实际安装环境生成。wait_task 返回失败任务状态时 answer 仍是 TaskStatus，state=failed/cancelled，并保留 error 与 exit_code；不能假定失败 answer 永远是字符串。

删除和取消存在“请求有效但没有变更”的结果：delete_tasks 的 answer=[]、cancel 的 answer=false 可以与 success=true 同时出现，客户端应显示实际变更数量。

相关文档 ​

实现依据：axonx/config/default.yaml、axonx/steps/task/ 与 axonx/components/service/http/jobs.py。

Agent-native quant research.

AxonX · FlowLLM-AI