API 合约草案

说明

本文件定义 MVP 所需的核心 API。可用 REST、tRPC 或 GraphQL 实现。下面以 REST 风格表达。

Projects

Create Project

POST /api/projects

Request:

{
  "name": "AI Agent 用户调研平台需求验证",
  "description": "验证 AgentSurvey 平台化方向的用户需求",
  "research_context": "目标用户是产品经理、用户研究员、创业团队",
  "default_language": "zh-CN"
}

Response:

{
  "id": "proj_123",
  "name": "AI Agent 用户调研平台需求验证",
  "created_at": "2026-06-22T10:00:00Z"
}

List Projects

GET /api/projects

Studies

Create Study

POST /api/projects/{project_id}/studies

Request:

{
  "name": "第一轮需求发现访谈",
  "description": "了解目标用户当前调研流程、痛点和对 AgentSurvey 的兴趣"
}

Update Study Config

PUT /api/studies/{study_id}/config

Request:

{
  "research_brief": {
    "goal": "验证 AgentSurvey 平台化方向是否有需求",
    "target_participants": ["产品经理", "用户研究员", "创业者"],
    "language": "zh-CN"
  },
  "objectives": [
    {
      "id": "obj_current_workflow",
      "title": "了解当前调研流程",
      "priority": "must",
      "success_criteria": ["知道当前使用哪些工具", "知道主要流程步骤"]
    },
    {
      "id": "obj_pain_points",
      "title": "识别主要痛点",
      "priority": "must",
      "success_criteria": ["识别至少一个具体痛点", "获得具体例子"]
    }
  ],
  "enabled_tools": ["render_interaction", "extract_fields", "conclude_interview"],
  "output_schema_id": "schema_123",
  "agent_config_id": "agent_123"
}

Publish Study

POST /api/studies/{study_id}/publish

Response:

{
  "public_url": "https://app.example.com/interview/abc123",
  "public_slug": "abc123",
  "status": "published"
}

Sessions

Create Session from Public Link

POST /api/public/studies/{public_slug}/sessions

Request:

{
  "participant_metadata": {
    "source": "shared_link",
    "role": "product_manager"
  }
}

Response:

{
  "session_id": "sess_123",
  "status": "active"
}

Send Message

POST /api/sessions/{session_id}/messages

Request:

{
  "content": "我现在主要用 Typeform 加人工访谈。"
}

Response 为流式。wire 层采用 AG-UI 事件协议（后端 LangGraph 经 AG-UI 推送、前端 assistant-ui 消费）；下面的 message.delta / tool.call / message.completed 是业务语义视图，落地时映射到对应的 AG-UI 事件类型。示意 SSE：

event: message.delta
data: {"content":"明白"}

event: tool.call
data: {"tool_name":"render_interaction","tool_input":{...}}

event: message.completed
data: {"turn_id":"turn_123"}

Submit Interaction Result

POST /api/sessions/{session_id}/interactions/{interaction_id}/submit

Request:

{
  "status": "submitted",
  "value": {
    "selected_option_ids": ["manual_analysis", "low_response_quality"]
  },
  "client_context": {
    "duration_ms": 8200,
    "device": "desktop"
  }
}

Response:

{
  "ok": true,
  "next_event_stream": "/api/sessions/sess_123/stream"
}

Output Schema

Create Output Schema

POST /api/projects/{project_id}/output-schemas

Request:

{
  "name": "需求发现输出结构",
  "fields": [
    {
      "id": "main_pain_point",
      "name": "main_pain_point",
      "label": "主要痛点",
      "type": "string",
      "description": "用户当前最强烈的调研痛点",
      "required": true,
      "evidence_required": true,
      "confidence_threshold": 0.75
    },
    {
      "id": "pain_intensity",
      "name": "pain_intensity",
      "label": "痛点强度",
      "type": "integer",
      "required": true,
      "evidence_required": true
    }
  ]
}

Results

Get Study Sessions

GET /api/studies/{study_id}/sessions

Get Session Detail

GET /api/sessions/{session_id}

Response:

{
  "session": {...},
  "transcript": [...],
  "tool_calls": [...],
  "extracted_fields": [...]
}

Get Extracted Fields

GET /api/studies/{study_id}/extracted-fields

Query params:

field_name；
status；
min_confidence；
session_id。

Update Extracted Field

PATCH /api/extracted-fields/{field_id}

Request:

{
  "value": "人工整理成本高",
  "status": "accepted",
  "review_note": "人工确认字段准确"
}

Knowledge Base

Create KB

POST /api/projects/{project_id}/knowledge-bases

Add Document

POST /api/knowledge-bases/{kb_id}/documents

Request:

{
  "title": "产品概念说明",
  "source_type": "text",
  "content": "AgentSurvey 是一个..."
}

Retrieve Knowledge

内部 tool API：

POST /api/tools/retrieve-knowledge

Request:

{
  "study_id": "study_123",
  "query": "AgentSurvey 的核心能力是什么？",
  "top_k": 5
}

Export

Export Study Results

POST /api/studies/{study_id}/exports

Request:

{
  "format": "csv",
  "include_transcript": false,
  "include_evidence": true
}

Response:

{
  "export_id": "export_123",
  "status": "processing"
}

Streaming Event Types

以下为业务语义事件；wire 层映射到 AG-UI 事件协议（详见 ../03_architecture/05_tech_stack_decision.md）。

export type StreamEvent =
  | { type: "message.delta"; content: string }
  | { type: "message.completed"; turn_id: string }
  | { type: "tool.call"; tool_call_id: string; tool_name: string; tool_input: unknown }
  | { type: "interaction.render"; interaction: InteractionToolCall }
  | { type: "extraction.completed"; fields: ExtractedField[] }
  | { type: "session.completed"; summary: string }
  | { type: "error"; message: string };

API 设计原则

Public participant API 和 admin API 分离。
Runtime event 可通过 SSE/WebSocket 传输。
Tool call/result 必须有 ID。
所有写操作应记录 audit log。
Admin API 应支持按 project/study 过滤。
Export 用异步任务。
Extraction update 必须保留 review history。