创建任务

使用 AI 代理开始新任务以执行您的需求。

端点

POST https://api.xmz.ai/v1/agentrix/tasks/start

认证

需要在授权头中提供 API 密钥：

Authorization: Bearer YOUR_API_KEY

先决条件

在创建任务之前，您必须首先创建一个聊天会话。聊天会话提供执行任务的上下文和代理。详情请参阅创建聊天 。

执行模式

任务可以在三种模式下执行：

1. 云模式 : 任务在 Agentrix 云基础设施上运行（需要 cloudId + message）
2. 本地模式 : 任务在您的本地机器上运行（需要 machineId + encryptedMessage + dataEncryptionKey）
3. 子任务模式 : 任务继承父任务的执行上下文（需要 parentTaskId）

请求体

核心必填字段

参数	类型	必需	描述
chatId	字符串	是	聊天标识符（参见创建聊天 ）

执行模式（选择一项）

云模式

参数	类型	必需	描述
cloudId	字符串	是*	云集群标识符
message	对象	是*	带有 role 和 content 的用户消息

本地模式

参数	类型	必需	描述
machineId	字符串	是*	本地机器标识符
encryptedMessage	字符串	是*	Base64 加密的消息负载
dataEncryptionKey	字符串	是*	Base64 加密密钥
cwd	字符串	否	工作目录
forceUserCwd	布尔值	否	强制使用用户当前工作目录（无工作树）

子任务模式

参数	类型	必需	描述
parentTaskId	字符串	是*	父任务 ID（继承执行上下文）

*需要一种执行模式

可选配置

参数	类型	描述
customTitle	字符串	自定义任务标题（1-200个字符）
agentId	字符串	特定代理 ID（默认为第一个聊天代理）
repositoryId	字符串	关联仓库标识符
baseBranch	字符串	Git 分支名称
repositorySourceType	字符串	仓库源类型： 临时 、 目录或 git-server

响应

成功响应（201 创建）

{
  "taskId": "task-xxx",
  "chatId": "chat-xxx",
  "agentId": "agent-xxx",
  "userId": "user-xxx",
  "state": "pending",
  "machineId": null,
  "cloudId": "cloud-xxx",
  "repositoryId": null,
  "baseBranch": null,
  "title": null,
  "customTitle": "My Task",
  "userCwd": null,
  "forceUserCwd": null,
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-15T10:30:00Z"
}

响应字段

字段	类型	描述
taskId	字符串	唯一任务标识符
chatId	字符串	聊天标识符
agentId	字符串	执行任务的代理标识符
userId	字符串	创建任务的用户标识符
state	字符串	任务状态（例如，pending，running，completed）
machineId	string	机器 ID（如果本地模式）
cloudId	string	云 ID（如果云模式）
repositoryId	string	仓库 ID
baseBranch	string	Git 分支名称
title	string	自动生成的任务标题
customTitle	string	用户提供的自定义标题
userCwd	string	工作目录
forceUserCwd	boolean	强制用户工作目录标志
createdAt	字符串	ISO 8601 创建时间戳
updatedAt	字符串	ISO 8601 最后更新时间戳

错误响应

400 错误请求

{
  "code": "INVALID_REQUEST",
  "error": "validation_error",
  "message": "Invalid request parameters"
}

401 未授权

{
  "code": "UNAUTHORIZED",
  "error": "unauthorized",
  "message": "Invalid or missing API key"
}

404 未找到

{
  "code": "CHAT_NOT_FOUND",
  "error": "not_found",
  "message": "Chat not found"
}

示例

示例 1：云模式任务

创建一个在云基础设施上运行的任务，具有仓库上下文：

curl -X POST https://api.xmz.ai/v1/agentrix/tasks/start \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "chatId": "chat-xxx",
    "cloudId": "cloud-xxx",
    "message": {
      "role": "user",
      "content": "Fix the authentication bug in login.ts"
    },
    "customTitle": "Fix login bug",
    "repositoryId": "repo-xxx",
    "baseBranch": "develop"
  }'

示例 2：子任务模式

创建一个子任务，从父任务继承执行上下文：

curl -X POST https://api.xmz.ai/v1/agentrix/tasks/start \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "chatId": "chat-xxx",
    "parentTaskId": "task-parent-xxx",
    "message": {
      "role": "user",
      "content": "Add unit tests for the fixed code"
    },
    "customTitle": "Add tests"
  }'

示例 3：简单云任务

创建一个不带仓库上下文的基本任务：

curl -X POST https://api.xmz.ai/v1/agentrix/tasks/start \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "chatId": "chat-xxx",
    "cloudId": "cloud-xxx",
    "message": {
      "role": "user",
      "content": "Explain how async/await works in JavaScript"
    }
  }'

工作流

1. 创建聊天 （前提条件）：使用创建聊天来建立聊天会话
2. 保存 chatId：存储返回的聊天 ID 以便在任务创建中使用
3. 创建任务 ：使用 chatId 和执行模式调用此端点
4. 保存 taskId：存储返回的任务 ID 以便监控进度
5. 监控进度 ：使用 WebSocket 或轮询来跟踪任务状态

相关端点

• 创建聊天 - 创建任务所需的必要前提条件
• 创建分享链接 - 与他人分享任务结果
• 列出任务 - 查看您所有的任务 (GET /v1/tasks)
• 继续任务 - 继续一个已暂停的任务（POST /v1/tasks/:taskId/resume）
• 取消任务 - 取消一个正在运行的任务（POST /v1/tasks/:taskId/cancel）
• 停止任务 - 停止任务执行（POST /v1/tasks/:taskId/stop）

需要帮助？

• 查看 API 概览 获取一般 API 信息
• 了解创建聊天进行聊天设置
• 在 GitHub 上报告问题