ClouisleClouisle

Agent API

管理 AI Agent、发布控制、聊天交互与统计查询

端点总览

Agent API 提供 Agent 生命周期管理、聊天交互与统计查询能力。基础路径为 /api/v1/agents。

方法路径用途
GET/api/v1/agents列出当前用户可访问的 Agent
POST/api/v1/agents创建新 Agent
GET/api/v1/agents/{agent_id}获取 Agent 详情（含完整配置）
PUT/api/v1/agents/{agent_id}更新 Agent 配置
DELETE/api/v1/agents/{agent_id}永久删除 Agent
POST/api/v1/agents/{agent_id}/publish发布 Agent
POST/api/v1/agents/{agent_id}/unpublish取消发布
POST/api/v1/agents/{agent_id}/duplicate复制 Agent（副本固定为 private + draft）
GET/api/v1/agents/{agent_id}/media/video-status查询异步视频生成任务状态
GET/api/v1/agents/{agent_id}/public获取聊天页所需的公开 Agent 信息
POST/api/v1/agents/{agent_id}/chat非流式聊天
POST/api/v1/agents/{agent_id}/chat/streamSSE 流式聊天
POST/api/v1/agents/{agent_id}/chat/runs创建持久运行（202 Accepted）
GET/api/v1/agents/{agent_id}/chat/runs/{run_id}/stream订阅运行事件流（after_sequence 断点续读）
POST/api/v1/agents/{agent_id}/chat/runs/{run_id}/stop协作式终止运行
POST/api/v1/agents/{agent_id}/messages/{message_id}/regenerate重新生成
POST/api/v1/agents/{agent_id}/messages/{message_id}/edit/stream编辑用户消息并生成分支
GET/api/v1/agents/{agent_id}/messages/{message_id}/versions查询消息版本
POST/api/v1/agents/{agent_id}/messages/{message_id}/switch-version切换版本
GET/api/v1/agents/{agent_id}/conversations查询当前用户在该 Agent 下的会话
GET/api/v1/agents/conversations/my查询当前用户的全部会话
GET/api/v1/agents/conversations/{conversation_id}获取会话及其消息
PATCH/api/v1/agents/conversations/{conversation_id}重命名会话
DELETE/api/v1/agents/conversations/{conversation_id}删除会话
DELETE/api/v1/agents/conversations/{conversation_id}/messages/{message_id}删除单条消息
GET/api/v1/agents/{agent_id}/stats查询 Agent 统计概览
GET/api/v1/agents/{agent_id}/stats/trends查询趋势数据
GET/api/v1/agents/{agent_id}/stats/tool-usage查询工具使用统计

认证

所有端点需要已认证的 JWT 用户会话。聊天端点额外支持 API Key（需绑定 Agent 权限）。

所需权限范围：

范围用途
agent:read列出和查看 Agent
agent:create创建 Agent
agent:update更新 Agent
agent:delete删除 Agent
agent:publish发布或取消发布 Agent
agent:chat与 Agent 聊天
conversation:read查询会话与会话消息
conversation:delete删除会话与会话内消息

列出 Agent

GET /api/v1/agents

获取当前用户可访问的全部 Agent，支持分页、团队筛选、状态筛选与关键词搜索。

查询参数

参数类型必填默认值说明
pageinteger否1页码
page_sizeinteger否20每页数量
team_idstring否-按团队 UUID 筛选
statusstring否-按状态筛选：draft、published
visibilitystring否-按可见性筛选：private、team、public（向后兼容值）
keywordstring否-按名称或描述搜索
own_onlyboolean否false仅显示当前用户创建的 Agent

请求示例

curl -X GET "https://your-domain.com/api/v1/agents?page=1&page_size=20" \
  -H "Authorization: Bearer YOUR_TOKEN"

响应字段

字段类型说明
idstringAgent UUID
namestring名称
descriptionstring描述
iconstring图标 emoji 或 URL
avatar_urlstring头像 URL
teamobject团队信息（id、name、avatar_url）
modelobject模型信息（id、name、provider、model_id），未设置时为 null
statusstringdraft 或 published
visibilitystringprivate 或 team
conversation_countinteger会话数量
message_countinteger消息数量
created_byobject创建者信息（id、username、avatar_url）
created_atstringISO 8601 时间戳
updated_atstringISO 8601 时间戳

成功响应（200 OK）

{
  "code": 0,
  "data": {
    "items": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "Customer Support Agent",
        "description": "Helps customers with common questions",
        "icon": "🤖",
        "avatar_url": "https://example.com/avatar.png",
        "team": {
          "id": "team-123",
          "name": "Support Team",
          "avatar_url": "https://example.com/team.png"
        },
        "model": {
          "id": "model-456",
          "name": "GPT-4",
          "provider": "openai",
          "provider_display_name": "OpenAI",
          "model_id": "gpt-4"
        },
        "status": "published",
        "visibility": "team",
        "conversation_count": 156,
        "message_count": 1234,
        "created_by": {
          "id": "user-001",
          "username": "alice",
          "avatar_url": "https://example.com/avatars/alice.jpg"
        },
        "created_at": "2026-02-11T10:00:00Z",
        "updated_at": "2026-02-11T15:30:00Z"
      }
    ],
    "total": 42,
    "page": 1,
    "page_size": 20
  },
  "msg": "success"
}

获取 Agent 详情

GET /api/v1/agents/{agent_id}

获取指定 Agent 的完整配置，包括系统提示词、工具配置、知识库关联与 RAG 参数。

路径参数

参数类型必填说明
agent_idstring是Agent UUID

请求示例

curl -X GET "https://your-domain.com/api/v1/agents/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer YOUR_TOKEN"

响应字段

在列出 Agent的列表字段基础上，详情接口额外返回完整配置：

字段类型说明
model_idstring团队模型 UUID
system_promptstring系统提示词
max_iterationsinteger最大工具调用迭代次数（1–200，默认 5）
hide_tool_callsboolean聊天界面隐藏工具调用详情
hide_message_actionsboolean隐藏 Token 用量/速度统计
hide_reasoningboolean隐藏推理过程
tools_configarray工具配置列表（type/name/tool_id/server_id/skill_id/config）
enable_attachmentsboolean启用文件和图片附件
enable_user_input_requestboolean启用模型可调用 ask_user 工具
enable_memoryboolean启用跨会话记忆
rag_modestringRAG 模式：off、auto、agentic（关联知识库时默认 agentic；响应中的 knowledge_bases 为空时规范化为 off）
variablesarray聊天输入变量定义
knowledge_basesarray响应中的关联知识库配置（含 knowledge_base、retrieval_top_k、score_threshold、search_mode）

成功响应（200 OK）

{
  "code": 0,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Customer Support Agent",
    "description": "Helps customers with common questions",
    "system_prompt": "You are a helpful customer support agent...",
    "max_iterations": 5,
    "hide_tool_calls": false,
    "tools_config": [
      {
        "type": "builtin",
        "name": "web_search"
      }
    ],
    "enable_memory": false,
    "rag_mode": "agentic",
    "knowledge_bases": [
      {
        "id": "kb-assoc-001",
        "knowledge_base": {
          "id": "kb-789",
          "name": "Product Documentation",
          "description": "Product docs and FAQs",
          "icon": "📚",
          "document_count": 156
        },
        "retrieval_top_k": 5,
        "score_threshold": 0.3,
        "search_mode": "hybrid"
      }
    ],
    "status": "published",
    "visibility": "team",
    "created_at": "2026-02-11T10:00:00Z",
    "updated_at": "2026-02-11T15:30:00Z"
  },
  "msg": "success"
}

错误响应（404 Not Found）

{
  "code": 6200,
  "data": {
    "agent_id": "550e8400-e29b-41d4-a716-446655440000"
  },
  "msg": "Agent not found"
}

创建 Agent

POST /api/v1/agents

创建新的 AI Agent，创建后默认为 draft 状态，需调用发布端点使其可用。

请求体

{
  "name": "Customer Support Agent",
  "description": "Helps customers with common questions",
  "avatar_url": "https://example.com/avatar.png",
  "team_id": "team-123",
  "model_id": "model-456",
  "system_prompt": "You are a helpful customer support agent...",
  "max_iterations": 5,
  "hide_tool_calls": false,
  "tools_config": [
    {
      "type": "builtin",
      "name": "web_search"
    }
  ],
  "enable_memory": false,
  "rag_mode": "agentic",
  "knowledge_base_configs": [
    {
      "knowledge_base_id": "kb-789",
      "retrieval_top_k": 5,
      "score_threshold": 0.3,
      "search_mode": "hybrid"
    }
  ],
  "visibility": "team"
}

请求字段

字段类型必填说明
namestring是名称（最多 100 字符）
descriptionstring否描述（最多 500 字符）
iconstring否图标 emoji 或 URL（最多 500 字符）
avatar_urlstring否头像 URL
team_idstring是团队 UUID
model_idstring否团队模型 UUID；未设置时使用团队默认模型
system_promptstring否系统提示词/指令
max_iterationsinteger否最大工具调用迭代次数（1–200，默认 5）
hide_tool_callsboolean否聊天界面隐藏工具调用详情（默认 false）
hide_message_actionsboolean否隐藏 Token 用量/速度统计（默认 false）
hide_reasoningboolean否隐藏推理/思维链（默认 false）
tools_configarray否工具配置（type/name/tool_id/server_id/skill_id/config）
tools_credentialsobject否工具凭证（API 密钥、Token 等）
enable_attachmentsboolean否启用文件和图片附件（默认 false）
attachment_configobject否附件限制配置
enable_user_input_requestboolean否启用 ask_user 工具（默认 false）
enable_memoryboolean否启用跨会话记忆（默认 false）
memory_configobject否记忆配置
context_compression_configobject否上下文压缩配置
enable_image_generationboolean否启用图片生成工具（默认 false）
image_generation_configobject否图片生成配置
enable_video_generationboolean否启用视频生成工具（默认 false）
video_generation_configobject否视频生成配置
rag_modestring否RAG 模式：off、auto、agentic（关联知识库时默认 agentic；无知识库时规范化为 off）
knowledge_base_configsarray否创建/更新时提交的知识库配置（knowledge_base_id、retrieval_top_k、score_threshold、search_mode）；为空时强制 rag_mode 为 off
variablesarray否聊天输入变量定义
opening_messagestring否聊天开场消息
suggested_questionsarray否推荐问题列表
visibilitystring否private 或 team（默认 private；历史值 public 会按 team 处理）

请求示例

curl -X POST "https://your-domain.com/api/v1/agents" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Customer Support Agent",
    "description": "Helps customers with common questions",
    "team_id": "team-123",
    "model_id": "model-456",
    "system_prompt": "You are a helpful customer support agent...",
    "tools_config": [{"type": "builtin", "name": "web_search"}],
    "knowledge_base_configs": [
      {
        "knowledge_base_id": "kb-789",
        "retrieval_top_k": 5,
        "score_threshold": 0.3,
        "search_mode": "hybrid"
      }
    ],
    "rag_mode": "agentic"
  }'

成功响应（200 OK）

{
  "code": 0,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Customer Support Agent",
    "description": "Helps customers with common questions",
    "status": "draft",
    "visibility": "team",
    "team": {
      "id": "team-123",
      "name": "Support Team",
      "avatar_url": null
    },
    "model_id": "model-456",
    "model": {
      "id": "model-456",
      "name": "GPT-4",
      "provider": "openai",
      "provider_display_name": "OpenAI",
      "model_id": "gpt-4"
    },
    "created_at": "2026-02-11T10:00:00Z",
    "created_by": {
      "id": "user-001",
      "username": "alice",
      "avatar_url": null
    }
  },
  "msg": "Agent created successfully"
}

错误响应（1001 Validation Error）

{
  "code": 1001,
  "data": {
    "errors": [
      {
        "field": "name",
        "message": "Name is required"
      },
      {
        "field": "model_id",
        "message": "Invalid model ID"
      }
    ]
  },
  "msg": "Validation failed"
}

创建后 Agent 为 draft 状态，需调用发布端点才能用于聊天。

更新 Agent

PUT /api/v1/agents/{agent_id}

更新已有 Agent 的配置。所有字段均为可选，仅需包含要更新的字段。

路径参数

参数类型必填说明
agent_idstring是Agent UUID

请求体

{
  "name": "Updated Agent Name",
  "description": "Updated description",
  "system_prompt": "Updated system prompt...",
  "max_iterations": 8,
  "tools_config": [
    {"type": "builtin", "name": "web_search"},
    {"type": "builtin", "name": "code_interpreter"}
  ],
  "rag_mode": "auto"
}

请求示例

curl -X PUT "https://your-domain.com/api/v1/agents/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Agent Name",
    "max_iterations": 8
  }'

成功响应（200 OK）

{
  "code": 0,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Updated Agent Name",
    "max_iterations": 8,
    "updated_at": "2026-02-11T16:00:00Z"
  },
  "msg": "Agent updated successfully"
}

删除 Agent

DELETE /api/v1/agents/{agent_id}

永久删除指定 Agent，操作不可恢复。

路径参数

参数类型必填说明
agent_idstring是Agent UUID

请求示例

curl -X DELETE "https://your-domain.com/api/v1/agents/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer YOUR_TOKEN"

成功响应（200 OK）

{
  "code": 0,
  "data": null,
  "msg": "Agent deleted successfully"
}

错误响应（6200 Not Found）

{
  "code": 6200,
  "data": {
    "agent_id": "550e8400-e29b-41d4-a716-446655440000"
  },
  "msg": "Agent not found"
}

发布 Agent

POST /api/v1/agents/{agent_id}/publish

将 Agent 状态设置为 published，使其可用于聊天。发布操作不校验模型是否配置（模型校验在后续聊天/访问路径中以错误码 6202 提示）。

路径参数

参数类型必填说明
agent_idstring是Agent UUID

请求示例

curl -X POST "https://your-domain.com/api/v1/agents/550e8400-e29b-41d4-a716-446655440000/publish" \
  -H "Authorization: Bearer YOUR_TOKEN"

成功响应（200 OK）

{
  "code": 0,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "published"
  },
  "msg": "Agent published successfully"
}

发布端点仅设置状态，不校验模型。后续聊天时若 Agent 处于 draft 状态，会返回 6202 Agent not published。

取消发布 Agent

POST /api/v1/agents/{agent_id}/unpublish

将 Agent 状态设置为 draft，使其不可用于聊天。

路径参数

参数类型必填说明
agent_idstring是Agent UUID

请求示例

curl -X POST "https://your-domain.com/api/v1/agents/550e8400-e29b-41d4-a716-446655440000/unpublish" \
  -H "Authorization: Bearer YOUR_TOKEN"

成功响应（200 OK）

{
  "code": 0,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "draft"
  },
  "msg": "Agent unpublished successfully"
}

复制 Agent

POST /api/v1/agents/{agent_id}/duplicate

在同一个团队内复制一个已有 Agent，并复制以下内容：

  • 提示词：系统提示词、开场消息、推荐问题、powered_by_text
  • 配置：工具、附件、记忆、上下文压缩、rag_mode、变量、迭代上限
  • 媒体生成：图片与视频生成设置（出于安全考虑，两份配置中的 allow_model_override 都会被移除）
  • 知识库：全部知识库关联及其检索参数

需要该 Agent 的访问权限以及团队的 agent:create 权限。

副本固定创建为 visibility: private、status: draft，名称在被复制名称后追加 " (Copy)"。复制后需要重新发布才能用于聊天。工具凭证（tools_credentials）不会被复制——副本中的工具需要重新配置密钥后才能调用外部服务。

路径参数

参数类型必填说明
agent_idstring是要复制的 Agent UUID

成功响应（200 OK）

返回新建的 AgentOut（status 为 draft）：

{
  "code": 0,
  "data": {
    "id": "new-agent-uuid",
    "name": "Customer Support Agent (Copy)",
    "status": "draft",
    "visibility": "private"
  },
  "msg": "Agent duplicated successfully"
}

查询视频生成状态

GET /api/v1/agents/{agent_id}/media/video-status?task_id={task_id}

轮询由 Agent 发起的异步视频生成任务，需要 agent:read 与 Agent 访问权限。Agent 必须启用视频生成（enable_video_generation），否则返回 400（业务码 1002，video_generation_not_enabled_for_agent）。

查询参数

参数类型必填说明
task_idstring是视频生成任务 ID

响应沿用 Agent 聊天中 media_result 视频结果的形状，客户端据此决定是否继续轮询：

{
  "code": 0,
  "data": {
    "kind": "media.video",
    "success": true,
    "prompt": "",
    "model": "veo-3",
    "model_ref": "video-model-uuid",
    "task_id": "video-task-uuid",
    "status": "succeeded",
    "progress": 100,
    "video": {
      "url": "/api/v1/upload/files/generated-videos/2026/09/9a8b7c6d5e4f_55667788.mp4",
      "asset_ref": "a1b2",
      "format": "mp4"
    },
    "estimated_time": null,
    "requires_polling": false,
    "poll_interval_ms": 3000,
    "poll_timeout_s": 120,
    "error": null
  },
  "msg": "success"
}
字段说明
status归一化后的任务状态；success 仅在未失败且无 error 时为 true。
progress任务进度百分比（未提供时为 null）。
video完成后的视频对象（url、asset_ref、format），未完成时为 null。
requires_pollingtrue 表示任务仍处于排队/运行状态，应继续按 poll_interval_ms 轮询。
poll_interval_ms / poll_timeout_s取自 Agent video_generation_config，默认 3000 / 120。

受保护的视频 URL 必须携带当前 JWT 或 API Key 获取。

获取公开 Agent 信息

GET /api/v1/agents/{agent_id}/public

返回聊天页所需的公开视图：名称、描述、图标、开场消息、推荐问题、变量定义与附件开关。该路由由 chat.py 实现，但挂载在 /api/v1/agents 下，且不需要 agent:read 权限。

路径参数

参数类型必填说明
agent_idstring是Agent UUID

鉴权行为

路由声明的是可选认证依赖，但实际调用仍要求已认证身份（未认证返回 401 not_authenticated）；认证后的可见范围是：

  • private：创建者、超级管理员；无创建者的历史数据回退为「该 Agent 所属团队的成员」。
  • team（含历史值 public）：该 Agent 所属团队的成员；超级管理员绕过校验。

成功响应（200 OK）

{
  "code": 0,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Customer Support Agent",
    "description": "Helps customers with common questions",
    "icon": "🤖",
    "avatar_url": "https://example.com/avatar.png",
    "opening_message": "Hi! How can I help you today?",
    "suggested_questions": ["What are your business hours?"],
    "powered_by_text": null,
    "variables": [],
    "enable_attachments": false,
    "attachment_config": null,
    "hide_tool_calls": false,
    "hide_message_actions": false,
    "hide_reasoning": false,
    "created_by": {
      "id": "user-001",
      "username": "alice",
      "avatar_url": null
    }
  },
  "msg": "success"
}

与 GET /api/v1/agents/{agent_id} 不同，此响应不包含模型、系统提示词、工具配置和统计字段。

错误错误码说明
403 Forbidden6201当前用户无权查看该 Agent
404 Not Found6200Agent 不存在

聊天（非流式）

POST /api/v1/agents/{agent_id}/chat

向 Agent 发送消息并同步接收完整响应。适合短响应场景；长任务推荐使用 SSE 流式端点。

路径参数

参数类型必填说明
agent_idstring是Agent UUID

请求体

{
  "message": "营业时间是什么？",
  "conversation_id": "conv-123",
  "file_urls": [
    {
      "asset_id": "asset-456",
      "url": "https://your-domain.com/api/v1/upload/files/general/2026/09/7f3a1c9d2b10_a1b2c3d4.pdf",
      "filename": "7f3a1c9d2b10_a1b2c3d4.pdf",
      "size": 1048576,
      "mime_type": "application/pdf"
    }
  ],
  "variables": {
    "customer_tier": "premium"
  }
}

使用上传响应中的 url、filename、size 和 mime_type 原样提交，不要根据 asset_id 自行拼接 /upload/files/{asset_id}。生成媒体的 asset_ref 仅在对应会话或工作流运行范围内有效，受保护 URL 需要带当前 JWT 或 API Key 获取。

请求字段

字段类型必填说明
messagestring是用户消息（最多 32000 字符）
imagesarray否视觉图片（asset_id 或 asset_ref、type、url）
filesarray否已解析文件（已弃用，使用 file_urls）
file_urlsarray否上传响应中的 Asset 元数据（asset_id、filename、url、size、mime_type）
conversation_idstring否会话 UUID；未提供时自动创建新会话
variablesobject否聊天输入表单的变量值
history_overridearray否覆盖会话历史（用于版本切换/重新生成）

请求示例

curl -X POST "https://your-domain.com/api/v1/agents/550e8400-e29b-41d4-a716-446655440000/chat" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "What are your business hours?",
    "conversation_id": "conv-123"
  }'

成功响应（200 OK）

{
  "code": 0,
  "data": {
    "conversation_id": "conv-123",
    "message": {
      "id": "msg-456",
      "conversation_id": "conv-123",
      "role": "assistant",
      "content": "Our business hours are Monday-Friday, 9 AM to 5 PM EST.",
      "tool_calls": [],
      "tool_name": null,
      "model_used": "gpt-4",
      "token_usage": {
        "prompt": 150,
        "completion": 25,
        "total": 175
      },
      "duration_ms": 2300,
      "rag_context": [
        {
          "document_id": "doc-789",
          "document_name": "Business Hours Policy",
          "chunk_id": "chunk-012",
          "content": "Business hours: Monday-Friday, 9 AM to 5 PM EST",
          "score": 0.95
        }
      ],
      "created_at": "2026-02-11T16:00:00Z",
      "version_number": 1,
      "version_count": 1
    },
    "usage": {
      "prompt": 150,
      "completion": 25,
      "total": 175
    }
  },
  "msg": "success"
}

聊天（流式）

POST /api/v1/agents/{agent_id}/chat/stream

以 SSE（Server-Sent Events）流式返回响应。请求体与非流式端点相同，无 stream 开关参数。

请求示例

curl -X POST "https://your-domain.com/api/v1/agents/550e8400-e29b-41d4-a716-446655440000/chat/stream" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "What are your business hours?",
    "conversation_id": "conv-123"
  }'

SSE 事件格式

event: message_start
data: {"conversation_id": "conv-123", "message_id": "msg-456"}

event: content_delta
data: {"delta": "Our"}

event: content_delta
data: {"delta": " business"}

event: content_delta
data: {"delta": " hours"}

event: rag_context
data: {"contexts": [{"document_name": "FAQ", "content": "...", "score": 0.95}]}

event: message_end
data: {"usage": {"prompt_tokens": 150, "completion_tokens": 25, "total_tokens": 175}, "timing": {"first_token_ms": 320, "duration_ms": 2300, "tokens_per_second": 10.9}}
事件说明
message_start消息开始，返回 conversation_id 和 message_id
content_delta增量文本片段
rag_contextRAG 检索上下文（文档名、内容、相关度评分）
message_end消息结束，返回 Token 用量与耗时指标

SSE 客户端需按 text/event-stream 解析事件流。详见 SSE 流式事件。

重新生成

POST /api/v1/agents/{agent_id}/messages/{message_id}/regenerate

重新生成指定消息的响应。请求体结构同聊天端点，可使用 history_override 调整历史上下文。

编辑消息并生成分支

POST /api/v1/agents/{agent_id}/messages/{message_id}/edit/stream

编辑用户消息并生成分支响应，以 SSE 流式返回。

查询消息版本

GET /api/v1/agents/{agent_id}/messages/{message_id}/versions

查询指定消息的所有版本（含重新生成与编辑产生的历史分支）。

切换版本

POST /api/v1/agents/{agent_id}/messages/{message_id}/switch-version

切换到指定版本作为当前活跃消息。

Agent 会话

会话端点注册在 agents 路由器上，因此路径中的会话段解析为 /api/v1/agents/conversations/...。所有这些路由都以已认证用户（Conversation.user）为范围：别人的会话一律按「不存在」处理（返回 404，错误码 6210）。

团队/管理视角的会话列表与详情另有一套 /api/v1/conversations 路由（GET 列表、GET 详情、单条/批量删除、统计），见会话 API。本节只覆盖用户自身的会话。

查询某 Agent 下我的会话

GET /api/v1/agents/{agent_id}/conversations

返回当前用户在该 Agent 下的会话。需要 conversation:read 与 Agent 访问权限（check_agent_access）。

参数类型必填默认值说明
searchstring否-按标题或会话 ID 模糊匹配（contains）
created_afterstring (ISO 8601)否-仅返回该时间之后创建的会话
created_beforestring (ISO 8601)否-仅返回该时间之前创建的会话
sort_bystring否updated_at排序字段：created_at、updated_at、message_count（其他取值回退为 updated_at）
pageinteger否1页码（最小 1）
page_sizeinteger否20每页条数（1–100）

结果按排序字段降序排列，返回 PageData[ConversationListOut] 信封（items、total、page、page_size），其中 agent_name/agent_icon 由该 Agent 补全。

查询我的全部会话

GET /api/v1/agents/conversations/my

跨 Agent 返回当前用户的所有会话。需要 conversation:read。

参数类型必填默认值说明
agent_idstring否-按 Agent UUID 筛选
pageinteger否1页码
page_sizeinteger否20每页条数

响应同样是 PageData[ConversationListOut]；Agent 已被删除时 agent_name 与 agent_icon 为 null。

获取会话

GET /api/v1/agents/conversations/{conversation_id}

返回会话及其可见消息（每条消息带 version_count）。需要 conversation:read，且仅所有者可读。

响应数据是 ConversationWithMessages：ConversationOut 字段（id、agent_id、agent_name、agent_icon、title、variables、message_count、token_usage、created_at、updated_at）加上 messages（MessageOut[]，消息结构见聊天 API）。

更新会话

PATCH /api/v1/agents/conversations/{conversation_id}

重命名会话。需要 conversation:read，且仅所有者可更新。

{
  "title": "更新后的会话标题"
}
字段类型必填说明
titlestring否新标题（1–200 字符）

不传 title 时会话保持不变；成功响应的 msg_key 为 conversation_updated。

删除会话

DELETE /api/v1/agents/conversations/{conversation_id}

永久删除会话（消息级联删除）。需要 conversation:delete，且仅所有者可删除。删除前会先把该 Agent 的 conversation_count 与 message_count 递减。

{
  "code": 0,
  "data": {
    "id": "conv-123"
  },
  "msg": "Conversation deleted successfully"
}

删除单条消息

DELETE /api/v1/agents/conversations/{conversation_id}/messages/{message_id}

删除会话中的一条消息。需要 conversation:delete，且消息必须属于调用者的会话。会话的 message_count 与 token_usage 会在同一个行锁事务中随消息删除一起更新，因此并发删除不会导致计数漂移。

错误错误码说明
404 Not Found6210会话不存在或不属于当前用户
404 Not Found6211消息不存在或不属于该会话
{
  "code": 0,
  "data": {
    "id": "msg-456"
  },
  "msg": "Message deleted successfully"
}

Agent 统计

GET /api/v1/agents/{agent_id}/stats

查询 Agent 在指定时间范围内的使用统计概览。

路径参数

参数类型必填说明
agent_idstring是Agent UUID

查询参数

参数类型必填默认值说明
periodstring否7d时间范围：24h、7d、30d、all

请求示例

curl -X GET "https://your-domain.com/api/v1/agents/550e8400-e29b-41d4-a716-446655440000/stats?period=30d" \
  -H "Authorization: Bearer YOUR_TOKEN"

成功响应（200 OK）

{
  "code": 0,
  "data": {
    "period": "30d",
    "overview": {
      "total_conversations": 156,
      "total_messages": 1234,
      "user_messages": 620,
      "assistant_messages": 610,
      "tool_messages": 4,
      "active_users": 23
    },
    "tokens": {
      "prompt_tokens": 250000,
      "completion_tokens": 206789,
      "total_tokens": 456789
    },
    "performance": {
      "avg_response_time_ms": 2300,
      "first_token_ms": {
        "p50": 1200,
        "p95": 9000,
        "avg": 2500,
        "samples": 480
      }
    },
    "tools": {
      "tool_call_count": 512
    },
    "health": {
      "completed": 90,
      "failed": 6,
      "stopped": 4,
      "interrupted": 3,
      "unrecognised": 0,
      "in_flight": 2,
      "total": 103,
      "success_rate": 0.8738
    },
    "interventions": {
      "steer": 12,
      "stop": 3,
      "follow_up": 5,
      "total": 20
    }
  },
  "msg": "success"
}

health 字段统计该 Agent 各运行终态与进行中状态：

字段说明
completed / failed / stopped达到对应终态的运行次数。
interrupted终态。 执行该运行的 Worker 丢失（崩溃、重启、驱逐），运行未能完成。计入 total 并降低 success_rate。
unrecognised未识别状态。数据库中存入的状态不在当前构建版本枚举中（通常由其他版本写入）。单独统计以显式展示枚举漂移，避免计入已知状态桶或造成请求 500。
in_flight非终态进行中运行（queued、running、stopping、completing、waiting）。不计入 total，也不计入 success_rate 分母。
total终态总数：completed + failed + stopped + interrupted。
success_rate成功率：completed / total（无终态运行时为 0）。

趋势数据

GET /api/v1/agents/{agent_id}/stats/trends

按周期返回时钟对齐的时间点网格：24h 为 24 个小时点，7d 为 7 个日点，30d 为 30 个日点。

{
  "code": 0,
  "data": {
    "period": "24h",
    "granularity": "hour",
    "data": [
      {
        "timestamp": "2026-09-13T13:00:00+08:00",
        "label": "13:00",
        "conversations": 12,
        "messages": 87,
        "tokens": 32100,
        "avg_response_time_ms": 2150.5,
        "first_token_p50_ms": 1180.0,
        "first_token_p95_ms": 8700.0
      }
    ]
  },
  "msg": "success"
}

first_token_p50_ms 与 first_token_p95_ms 在该时间点没有测量样本时为 null，用于让延迟折线断开而不是掉到 0。

工具使用统计

GET /api/v1/agents/{agent_id}/stats/tool-usage

tools[].name 为内部工具标识，display_name 为本地化显示名（MCP 工具按服务前缀渲染）。工具按调用次数降序排列，total_calls 为全部工具调用次数之和。

{
  "code": 0,
  "data": {
    "period": "7d",
    "tools": [
      {
        "name": "web_search",
        "display_name": "联网搜索",
        "count": 312
      }
    ],
    "total_calls": 512
  },
  "msg": "success"
}

统计端点为只读聚合，不会枚举 MCP 工具（不做无超时网络调用），因此 display_name 对 MCP 工具是「服务前缀 + 工具名」形式，无需连接 MCP 服务。

其他统计端点

所有统计端点均须使用 /api/v1 前缀，均要求有效的 JWT 当前用户，并通过 check_agent_access 校验访问权限：

端点说明参数
GET /api/v1/agents/{agent_id}/stats/trends趋势数据period: 24h/7d/30d
GET /api/v1/agents/{agent_id}/stats/tool-usage工具使用统计period: 24h/7d/30d/all

period 边界行为：概览与工具使用端点对 24h/7d/30d 之外的任何取值一律按 all 处理；趋势端点对非 24h/7d 的取值一律按 30d 处理。

访问控制：统计端点调用 check_agent_access(..., require_write=True) —— 超级管理员放行；private Agent 仅创建者可读（无创建者的历史 Agent 回退为团队范围，且要求团队管理员）；team/public Agent 需要团队访问权限，且非创建者须为团队管理员（管理员）。换句话说，Agent 统计是管理/监控视角的数据，普通团队成员无法读取。被拒返回 403，资源不存在返回 404。

访问边界

  • Agent 必须处于 published 状态才能用于聊天。
  • API Key 需具备对应权限；若 API Key 绑定了特定 Agent，只能访问白名单内的 Agent ID。
  • Agent 的附件限制、工具迭代上限与模型配额在 API 调用时仍然生效。

错误码

错误码消息说明
6200Agent not foundAgent 不存在
6201Access denied当前用户无权访问该 Agent
6202Agent not publishedAgent 处于 draft 状态
3000Permission denied权限不足
1001Validation failed请求数据无效
5104Duplicate nameAgent 名称已占用

当前端点未实现单独限流，无速率限制中间件。

相关文档

这篇文章对你有帮助吗？

本页目录

端点总览认证列出 Agent查询参数请求示例响应字段成功响应（200 OK）获取 Agent 详情路径参数请求示例响应字段成功响应（200 OK）错误响应（404 Not Found）创建 Agent请求体请求字段请求示例成功响应（200 OK）错误响应（1001 Validation Error）更新 Agent路径参数请求体请求示例成功响应（200 OK）删除 Agent路径参数请求示例成功响应（200 OK）错误响应（6200 Not Found）发布 Agent路径参数请求示例成功响应（200 OK）取消发布 Agent路径参数请求示例成功响应（200 OK）复制 Agent路径参数成功响应（200 OK）查询视频生成状态查询参数获取公开 Agent 信息路径参数鉴权行为成功响应（200 OK）聊天（非流式）路径参数请求体请求字段请求示例成功响应（200 OK）聊天（流式）请求示例SSE 事件格式重新生成编辑消息并生成分支查询消息版本切换版本Agent 会话查询某 Agent 下我的会话查询我的全部会话获取会话更新会话删除会话删除单条消息Agent 统计路径参数查询参数请求示例成功响应（200 OK）趋势数据工具使用统计其他统计端点访问边界错误码相关文档