中文EN
ResearchX Docs
中文

LLM API 操作手册

面向大模型和自动化 Agent 的 ResearchX API 调用流程

LLM API 操作手册

本文面向需要通过 API 操作 ResearchX 的大模型、自动化 Agent 和外部编排系统。目标不是枚举所有接口，而是说明如何把项目、工作区、会话、Agent 工单、容器和权限确认串成一个稳定的数据分析闭环。

完整接口结构可在 /swagger 和 /openapi.json 查看。本页描述推荐调用方式和状态处理策略。

如果要给外部模型或自动化 Agent 配置可直接加载的 skill，可使用 ResearchX API Skill 中的 SKILL.md 模板。它是用户文档中的可复制模板，不是 ResearchX 内置全局 skill。

能力模型

ResearchX 对外操作时可以理解为六个核心对象：

  • Project：隔离单元，所有数据、会话、Agent 任务和文件都归属于项目。
  • Workspace：项目本地工作目录，上传数据、脚本、Agent 输出和可下载结果都在这里。
  • Conversation：交互上下文，适合让模型通过聊天工具链完成分析。
  • Agent Ticket：异步任务单元，适合长时分析、批处理、结构化执行和结果回流。
  • Container：项目执行环境，在容器内项目目录固定为 /workspace。
  • Tool Permission：工具安全审批机制，用于写文件、改文件、执行命令或调用需要确认的 MCP 工具。

最小数据分析闭环

推荐外部 Agent 先实现这一条链路：

  1. 调用登录接口并保存返回的 token，后续请求使用 Authorization: Bearer <token>。
  2. 创建或选择项目。
  3. 上传数据到项目 workspace。
  4. 查看可用 agents、actions、runtimes 和模型。
  5. 创建 agent ticket 或发送项目 chat 请求。
  6. 监听 SSE 进度。
  7. 处理权限请求或补充问题。
  8. 获取 ticket detail、消息和 artifacts。
  9. 读取或下载 workspace 中的结果文件。
POST /api/auth/login
GET /api/projects
POST /api/projects/{projectId}/agent-workspace
GET /api/projects/{projectId}/agents
POST /api/projects/{projectId}/agent-tickets
GET /api/projects/{projectId}/agent-tickets/stream
GET /api/projects/{projectId}/agent-tickets/{ticketId}?mode=full
GET /api/projects/{projectId}/agent-workspace/content?path=reports/summary.md

Agent Ticket 状态机

外部 Agent 应按状态处理，而不是按固定等待时间处理。

状态含义推荐动作
submitted已提交继续监听或轮询
validating校验输入和能力继续监听
queued等待调度继续监听
dispatching正在派发执行继续监听
running正在执行继续监听，按需读取增量事件
awaiting_user_input等待用户问题或确认查询 question/permission 请求
retry_waiting等待重试窗口继续监听，必要时展示等待原因
partial_succeeded部分成功获取 detail 和 artifacts，判断是否需要后续任务
succeeded成功结束获取结果和 workspace 输出
failed失败结束获取 events、failure message 和日志
cancelling正在取消继续监听
cancelled已取消停止等待

推荐轮询与流式策略

优先使用 SSE：

GET /api/projects/{projectId}/agent-tickets/stream

事件类型为 agent_ticket，数据里包含 ticket_id、status、detail_changed 和 conversation_changed。如果 SSE 断开，使用最后收到的事件 ID 通过 last-event-id header 重新连接，并通过 ticket detail 补齐状态。

备用轮询：

GET /api/projects/{projectId}/agent-tickets/{ticketId}?mode=compact
GET /api/projects/{projectId}/agent-tickets/{ticketId}?mode=full

compact 适合状态刷新，full 适合结束后获取完整事件、artifacts 和 action executions。

权限确认流程

当任务需要写文件、改文件、执行命令或调用受保护 MCP 工具时，可能产生权限请求。

GET /api/projects/{projectId}/tool-permission-requests?status=pending
GET /api/projects/{projectId}/tool-permission-requests/{requestId}/diff-preview
POST /api/projects/{projectId}/tool-permission-requests/{requestId}/approve
POST /api/projects/{projectId}/tool-permission-requests/{requestId}/deny

处理规则：

  • 只有当请求仍是 pending 时才批准或拒绝。
  • 对 write 和 edit 先读取 diff preview。
  • 对 bash 审查命令摘要、目标路径和执行目的。
  • 对 mcp 确认远端工具名和参数。
  • 批准后继续监听原 ticket 或 conversation stream。

用户补充问题

当任务状态进入 awaiting_user_input，也可能是 Agent 需要用户选择或补充信息。

GET /api/projects/{projectId}/conversation-question-requests?status=pending
POST /api/projects/{projectId}/conversation-question-requests/{requestId}/answer
POST /api/projects/{projectId}/conversation-question-requests/{requestId}/reject

外部 Agent 应把问题展示给用户或上游系统。不要自行伪造用户选择，除非调用方明确授权。

Workspace 文件策略

工作区路径使用项目内相对路径。容器内固定根路径为 /workspace，API 侧使用相对路径，例如 data/input.csv 或 reports/summary.md。

常用接口：

GET /api/projects/{projectId}/agent-workspace?path=data
GET /api/projects/{projectId}/agent-workspace?query=summary&limit=20
POST /api/projects/{projectId}/agent-workspace
GET /api/projects/{projectId}/agent-workspace/content?path=reports/summary.md
PUT /api/projects/{projectId}/agent-workspace/content
GET /api/projects/{projectId}/agent-workspace/download?path=reports/figures/plot.png

建议：

  • 上传原始数据放在 data/。
  • 分析脚本放在 scripts/。
  • 报告、表格和图片放在 reports/ 或 results/。
  • 不要手动写入 .agent/。

错误处理

所有 JSON API 应按统一 envelope 处理：

{
  "ok": false,
  "error": {
    "code": "REQUEST_400_BAD_REQUEST",
    "message": "Human readable error",
    "request_id": "req_xxx"
  }
}

推荐策略：

  • 401：重新登录或刷新 token。
  • 403：停止自动重试，提示权限不足或项目成员关系不满足。
  • 404：重新列项目、文件或 ticket，避免使用过期 ID。
  • 409：通常是会话已有运行、资源冲突或状态不可变，等待后重试或切换 conversation。
  • 500：记录 request_id，读取 ticket events 或容器日志后再决定是否重试。

当前边界

当前 API 足以支撑 MVP 级外部自动化数据分析闭环，但不是所有架构目标都已落地。Temporal engine run、完整资源租约、CWL/DAG 数据分析编排和 DataObjectID 级血缘仍属于演进方向。外部 Agent 应优先依赖当前稳定对象：project、workspace、conversation、agent ticket、tool permission 和 container。

On this page

LLM API 操作手册能力模型最小数据分析闭环Agent Ticket 状态机推荐轮询与流式策略权限确认流程用户补充问题Workspace 文件策略错误处理当前边界