Agent API Profile

完整 ResearchX API 覆盖管理、会话、资产、文件、容器和公开展示等多类场景。外部大模型不应直接面对全部接口。推荐先实现本页定义的精简 profile，用少量稳定能力完成数据分析闭环。

如果要把本 profile 交给外部模型直接加载，可使用 ResearchX API Skill 中的 SKILL.md 模板。它是面向其他模型和编排器的用户文档模板，不是平台内置 skill。

Profile 目标

减少模型需要选择的 endpoint 数量。
避免模型误用 admin、展示或内部接口。
让每个工具都有明确输入、输出和恢复策略。
为未来 MCP server、TypeScript SDK 或 Python SDK 提供稳定边界。

推荐工具集

工具	对应接口	用途
`list_projects`	`GET /api/projects`	选择可访问项目
`get_project`	`GET /api/projects/{projectId}`	确认项目状态和能力
`list_workspace_files`	`GET /api/projects/{projectId}/agent-workspace`	浏览或搜索数据和结果
`upload_workspace_file`	`POST /api/projects/{projectId}/agent-workspace`	上传数据、脚本或配置
`read_workspace_file`	`GET /api/projects/{projectId}/agent-workspace/content`	读取文本结果
`download_workspace_file`	`GET /api/projects/{projectId}/agent-workspace/download`	下载图片、表格和二进制结果
`list_analysis_agents`	`GET /api/projects/{projectId}/agents`	查看可创建的分析 Agent
`create_analysis_task`	`POST /api/projects/{projectId}/agent-tickets`	创建异步分析任务
`watch_task`	`GET /api/projects/{projectId}/agent-tickets/stream`	监听任务状态
`get_task_result`	`GET /api/projects/{projectId}/agent-tickets/{ticketId}`	获取任务详情和 artifacts
`list_permission_requests`	`GET /api/projects/{projectId}/tool-permission-requests`	发现待审批工具请求
`preview_permission_change`	`GET /api/projects/{projectId}/tool-permission-requests/{requestId}/diff-preview`	审查写入或修改
`approve_permission_request`	`POST /api/projects/{projectId}/tool-permission-requests/{requestId}/approve`	批准执行
`deny_permission_request`	`POST /api/projects/{projectId}/tool-permission-requests/{requestId}/deny`	拒绝执行

不建议默认暴露的能力

Admin 接口。
用户删除、项目归档、批量删除等破坏性接口。
全量模型配置写入接口。
未经过白名单的 MCP 工具管理接口。
直接删除 workspace 文件的能力，除非调用方明确授权。

工具行为约定

外部 Agent profile 应统一遵守：

所有工具必须带 projectId，除非是登录或列项目。
文件路径使用 workspace 相对路径，不使用宿主机绝对路径。
写入前优先使用 reports/、results/、scripts/、data/ 这些目录。
所有异步任务都返回 ticket_id 并进入 watch_task。
任何 pending 权限请求都必须显式批准或拒绝。
终态为 failed 时必须读取 task detail 后再决定是否重试。

建议的 MCP 工具描述

如果把此 profile 封装成 ResearchX MCP server，工具描述应强调输入输出边界。例如：

{
  "name": "create_analysis_task",
  "description": "Create an asynchronous ResearchX analysis task in a project. Use this for long-running data analysis that should produce files in the project workspace.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "projectId": { "type": "string" },
      "title": { "type": "string" },
      "intentSummary": { "type": "string" },
      "files": {
        "type": "array",
        "items": { "type": "string" }
      },
      "expectedOutputs": {
        "type": "array",
        "items": { "type": "string" }
      }
    },
    "required": ["projectId", "title", "intentSummary"]
  }
}

最小调度循环

外部 Agent 可以按这个循环执行：

list_projects
upload_workspace_file
create_analysis_task
watch_task
if pending permission: preview_permission_change -> approve or deny
if awaiting user input: ask caller, then answer through conversation question API
if succeeded: get_task_result -> list_workspace_files -> read/download outputs
if failed: get_task_result -> summarize failure and retry only when safe

成熟度说明

当前 profile 可以先作为文档约定使用。后续可以把它落成专门的 MCP server 或 SDK。实现时应从 OpenAPI registry 自动校验 endpoint、参数和响应结构，避免 profile 与实际 API 漂移。

Agent API Profile

On this page