跳到主要内容

创建聊天

在用户和 AI 代理之间创建聊天会话。

端点​

POST https://api.xmz.ai/v1/agentrix/chats

认证​

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

Authorization: Bearer YOUR_API_KEY

重要提示​

  • 幂等性 ：使用相同的 type 和 members 调用，如果已存在，则返回现有的聊天
  • 永久性 ：聊天 ID 永远不会过期，并且可以无限期地重用
  • 前提条件 : 在创建任务之前，需要先创建聊天

请求体​

参数类型必需描述
type字符串没有聊天类型: direct 或 group (默认: direct)
membersarray是成员对象数组

成员对象​

字段类型必需描述
memberCode字符串是代理 ID（当 type='agent' 时）或用户 ID（当 type='human' 时）
type字符串是成员类型：agent 或 human

请求体架构​

{
  "type": "direct",
  "members": [
    {
      "memberCode": "agent-codex-v1",
      "type": "agent"
    }
  ]
}

响应​

成功响应（201 创建）​

返回创建或现有的聊天会话：

{
  "id": "chat-xxx",
  "owner": "user-xxx",
  "type": "direct",
  "title": null,
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-15T10:30:00Z",
  "defaultMachineId": null,
  "defaultCloudId": null,
  "defaultRepositoryId": null,
  "defaultBaseBranch": null,
  "members": [
    {
      "id": "member-xxx",
      "chatId": "chat-xxx",
      "memberCode": "agent-codex-v1",
      "type": "agent",
      "role": "agent",
      "createdAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-01-15T10:30:00Z"
    }
  ]
}

响应字段​

字段类型描述
id字符串聊天标识符（创建任务时使用此作为 chatId）
owner字符串聊天所有者（群聊的用户 ID，直接聊天的成员 Codes 排序）
type字符串聊天类型：direct 或 group
titlestringnull
createdAt字符串ISO 8601 创建时间戳
updatedAt字符串ISO 8601 最后更新时间戳
defaultMachineIdstringnull
defaultCloudIdstringnull
defaultRepositoryIdstringnull
defaultBaseBranchstringnull
members数组聊天成员数组

成员对象字段​

字段类型描述
id字符串成员标识符
chatId字符串聊天标识符
memberCode字符串代理 ID 或用户 ID
type字符串成员类型：agent 或 human
role字符串成员角色
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"
}

示例​

创建与 AI 代理的直接聊天：

curl -X POST https://api.xmz.ai/v1/agentrix/chats \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "direct",
    "members": [
      {
        "memberCode": "agent-codex-v1",
        "type": "agent"
      }
    ]
  }'

工作流​

  1. 创建聊天 ：使用所需的代理调用此端点
  2. 保存聊天 ID: 存储返回的 id 字段（这是您的 chatId）
  3. 重用聊天 ID: 使用相同的 chatId 进行多个任务
  4. 创建任务 : 创建任务时传递 chatId（参见 Create Task）

聊天类型​

直接聊天​

与代理进行一对一对话时，请使用 type: "direct"。这是 API 使用中最常见的类型。

{
  "type": "direct",
  "members": [
    {
      "memberCode": "agent-codex-v1",
      "type": "agent"
    }
  ]
}

群组聊天​

对于多成员对话（多个代理或用户），请使用 type: "group"。

{
  "type": "group",
  "members": [
    {
      "memberCode": "agent-codex-v1",
      "type": "agent"
    },
    {
      "memberCode": "agent-claude-v1",
      "type": "agent"
    }
  ]
}

幂等性​

多次使用相同的 type 和 members 调用此端点将返回现有的聊天，而不是创建重复的聊天。这确保您可以安全地调用端点，而不用担心创建具有相同代理的多个聊天。

示例 ：如果您使用相同的代理调用端点两次，两次调用都将返回相同的 chatId。

相关端点​

  • Create Task - 使用聊天 ID 创建任务
  • 列出聊天 - 查看所有聊天 (GET /v1/chats)
  • 获取聊天 - 检索聊天详情 (GET /v1/chats/:chatId)
  • 添加成员 - 向聊天中添加成员 (POST /v1/chats/:chatId/members)
  • 移除成员 - 从聊天中移除成员 (DELETE /v1/chats/:chatId/members)

需要帮助？​