数据分析 API Cookbook

本页提供面向外部 Agent 的数据分析调用样例。示例默认已获得 Bearer token，并把项目 ID 记为 {projectId}。

上传 CSV 并创建分析任务

适用场景：用户提供一个 CSV，希望 ResearchX 生成统计摘要、图表和结论。

调用步骤：

上传文件到 workspace。
查看可用 agent。
创建 agent ticket。
监听 ticket stream。
读取结果报告。

上传文件：

curl -X POST "$BASE_URL/api/projects/{projectId}/agent-workspace" \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@./input.csv" \
  -F "path=data" \
  -F "conflict_policy=overwrite"

path 是目标父目录；文件名来自上传文件本身。上面的请求会把 input.csv 保存为 data/input.csv。

创建任务：

{
  "task_type": "data_analysis",
  "title": "Analyze uploaded CSV",
  "intent_summary": "Inspect data/input.csv, summarize columns, compute descriptive statistics, and write reports/summary.md.",
  "priority": "normal",
  "conversation_id": "conv_123",
  "add_to_conversation": true,
  "input": {
    "source": "external_api",
    "files": ["data/input.csv"],
    "expected_outputs": ["reports/summary.md", "reports/figures"]
  }
}

task_type 应来自 GET /api/projects/{projectId}/agents 返回的可用 Agent 定义；这里的 data_analysis 只是示例分类。如果要指定某个已安装 Agent，可在 input 中加入该定义的 agent_definition_id。

如果希望任务卡片和结果回流到会话，需要先创建或选择 conversation，并同时提供 conversation_id 与 add_to_conversation: true。

成功判断：

ticket 状态为 succeeded 或 partial_succeeded。
GET /api/projects/{projectId}/agent-tickets/{ticketId}?mode=full 返回 artifacts。
workspace 中存在 reports/summary.md 或其它约定输出。

读取结果 Markdown

适用场景：任务完成后，外部系统需要读取报告内容。

GET /api/projects/{projectId}/agent-workspace/content?path=reports/summary.md

推荐处理：

如果返回二进制或预览受限，改用 download 接口。
如果文件不存在，先搜索 workspace：

GET /api/projects/{projectId}/agent-workspace?query=summary&limit=20

下载图表或结果压缩包

适用场景：需要把图片、表格或结果文件交给外部系统。

GET /api/projects/{projectId}/agent-workspace/download?path=reports/figures/plot.png
GET /api/projects/{projectId}/agent-workspace/download?path=results/result.csv

建议 Agent 在任务提示中要求输出稳定路径，例如：

Please save the final report to reports/summary.md and plots to reports/figures/.

这样外部调用方可以用固定路径读取。

处理工具权限请求

适用场景：分析任务需要写入报告、修改脚本、运行命令或调用需要确认的 MCP 工具。

发现请求：

GET /api/projects/{projectId}/tool-permission-requests?status=pending

查看 diff：

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

成功判断：

permission request 变为 approved 或 executed。
原 ticket stream 后续出现 ticket_updated。
如果请求被拒绝，ticket 可能失败、等待重规划或要求用户补充。

使用容器环境跑分析

适用场景：需要固定 Python/R/生信工具环境。

检查容器状态：

GET /api/projects/{projectId}/container/status
GET /api/projects/{projectId}/container/options

启用并启动容器：

{
  "image": "researchx-runtime:latest",
  "container_cpu_count": 4,
  "container_memory_mb": 8192
}

对应接口：

POST /api/projects/{projectId}/container/enable
POST /api/projects/{projectId}/container/start

注意事项：

容器内项目根路径固定为 /workspace。
输出文件应写回 /workspace/reports 或 /workspace/results。
如果容器启动失败，读取 GET /api/projects/{projectId}/container/events。

失败后收集诊断信息

适用场景：ticket 状态为 failed，需要判断能否重试。

收集顺序：

GET /api/projects/{projectId}/agent-tickets/{ticketId}?mode=full
查看 latest_run.failure_code 和 latest_run.failure_message
查看 events 中 level 为 error 的记录
查看 artifacts 是否已有部分结果
如果使用容器，查看 container events 或 build logs

建议重试条件：

输入文件路径错误：修正路径后新建 ticket。
权限请求被拒绝：重新确认需求后新建 ticket。
容器不可用：修复容器后重试。
模型响应失败或临时服务错误：短暂等待后重试。

使用 MCP 工具补充能力

适用场景：外部数据库、实验系统或企业工具通过 MCP 暴露给 ResearchX。

常用接口：

GET /api/projects/{projectId}/mcp/servers
POST /api/projects/{projectId}/mcp/servers
POST /api/projects/{projectId}/mcp/servers/{serverId}/test
GET /api/projects/{projectId}/mcp/servers/{serverId}/tools

建议配置：

只暴露任务需要的工具。
对会写入外部系统的工具开启确认。
把 allowed_tools 和 confirmation_tools 设成明确列表。

Chat 方式完成轻量分析

适用场景：任务较短，不需要独立 ticket 生命周期。

POST /api/projects/{projectId}/chat

请求中可以附带 workspace 文件引用，让会话 Agent 读取数据。外部系统应消费 SSE 事件，等待 done 后再读取会话消息和 workspace 输出。

如果任务可能运行较久、需要取消、需要独立 artifact 或需要可靠状态跟踪，优先使用 agent ticket。

数据分析 API Cookbook

On this page