Skip to content
AgentSurvey

模型、工具、知识库抽象

模型、工具、知识库抽象

目标

AgentSurvey 应支持模型解耦、工具可扩展、知识库可配置，避免业务逻辑绑定某个 LLM provider 或单一 RAG 实现。

Model Gateway

实现采用 LiteLLM 作为统一多 provider 网关（详见 05_tech_stack_decision.md）；下面的 ModelProviderAdapter 是其上的项目内抽象接口。

ModelConfig

export type ModelConfig = {
  provider: "openai" | "anthropic" | "google" | "azure_openai" | "ollama" | "vllm" | "custom";
  model: string;
  temperature?: number;
  max_tokens?: number;
  top_p?: number;
  timeout_ms?: number;
  retry_policy?: RetryPolicy;
  structured_output?: boolean;
  tool_calling?: boolean;
};

Model Roles

不同任务可以使用不同模型：

export type StudyModelRoles = {
  interviewer_model: ModelConfig;
  extraction_model: ModelConfig;
  synthesis_model: ModelConfig;
  safety_model?: ModelConfig;
  embedding_model?: EmbeddingConfig;
};

建议：

  • interviewer_model 注重对话质量和工具调用。
  • extraction_model 注重结构化输出稳定性。
  • synthesis_model 注重长上下文和总结质量。
  • embedding_model 注重成本和检索效果。

Provider Adapter

export interface ModelProviderAdapter {
  generateText(input: GenerateTextInput): Promise<GenerateTextOutput>;
  generateStructured<T>(input: StructuredInput<T>): Promise<T>;
  stream(input: StreamInput): AsyncIterable<StreamEvent>;
  countTokens?(input: unknown): Promise<number>;
}

Tool Registry

工具不是 prompt 里的字符串，而是注册对象。

export type ToolDefinition = {
  id: string;
  name: string;
  display_name: string;
  description: string;
  tool_type: "interaction" | "retrieval" | "extraction" | "export" | "analysis" | "governance";
  input_schema: JsonSchema;
  output_schema: JsonSchema;
  version: string;
  execution_mode: "frontend" | "backend" | "hybrid";
  risk_level: "low" | "medium" | "high";
};

MVP 内置工具

1. render_interaction

用途：前端渲染交互组件。

Agent -> tool call -> frontend UI -> user result -> harness

2. retrieve_knowledge

用途：检索 project/study KB。

输入：query、top_k、filters。

输出：chunks、citations、source metadata。

3. extract_fields

用途：根据 output schema 抽取结构化字段。

输入：session_id、field_ids、transcript range。

输出：field values、confidence、evidence。

4. conclude_interview

用途：结束访谈。

输入：reason、summary、remaining_missing_fields。

输出：session completed event。

5. export_results

用途：导出 JSON/CSV/Notion。

输入：study_id、format、filters。

输出：export artifact。

Tool Execution Modes

frontend

由前端执行，例如：

  • render_interaction；
  • file picker；
  • local UI approval。

backend

由后端执行，例如：

  • retrieve_knowledge；
  • extract_fields；
  • export_results；
  • PII redaction。

hybrid

前后端共同执行，例如：

  • file upload；
  • image annotation；
  • prototype task tracking。

Study-level Tool Policy

每个 study 应能配置：

export type StudyToolPolicy = {
  enabled_tools: string[];
  disabled_tools: string[];
  tool_configs: Record<string, unknown>;
  interaction_limits?: {
    max_interactions_per_session?: number;
    max_modal_interactions?: number;
  };
  approval_required?: string[];
};

Knowledge Base 抽象

KB Scope

export type KnowledgeBaseScope = "workspace" | "project" | "study";

KBConfig

export type KBConfig = {
  id: string;
  name: string;
  scope: KnowledgeBaseScope;
  retrieval_enabled: boolean;
  chunking_strategy: "fixed" | "semantic" | "markdown";
  embedding_model: EmbeddingConfig;
  top_k: number;
  score_threshold?: number;
  citation_required: boolean;
};

Retrieval Result

export type RetrievalResult = {
  query: string;
  chunks: Array<{
    chunk_id: string;
    document_id: string;
    title: string;
    content: string;
    score: number;
    metadata?: Record<string, unknown>;
  }>;
};

RAG 使用原则

Agent 不应每轮都检索。建议触发条件：

  1. 用户询问产品/概念细节。
  2. Agent 需要解释某个研究刺激物。
  3. 需要引用项目背景。
  4. 需要根据用户 segment 使用不同说明。
  5. 需要判断回答是否和知识库事实冲突。

配置界面建议

Model Settings

  • provider；
  • interviewer model；
  • extraction model；
  • synthesis model；
  • temperature；
  • max tokens；
  • fallback；
  • cost limit。

Tool Settings

  • 启用/禁用工具；
  • 每个工具的参数；
  • 交互组件上限；
  • 是否需要 approval；
  • 风险等级。

Knowledge Settings

  • 选择 KB；
  • 选择 retrieval scope；
  • top_k；
  • citation policy；
  • KB version。

重要边界

  1. Agent 不应能调用未启用工具。
  2. Tool input 必须 schema validate。
  3. Tool result 必须持久化。
  4. 高风险工具必须支持 approval/audit。
  5. 模型调用要记录 provider/model/token/cost。
  6. 知识库检索结果要记录来源，便于调试 hallucination。