Chat API

向你的 mind 发送消息并接收 AI 生成的回复。Chat API 同时支持无状态 completion 和带自动历史管理的有状态多轮对话。

有状态 Chat(推荐)

创建持久化对话,服务端自动管理历史、上下文压缩和滚动摘要。无需在每次请求中发送完整的消息历史。

创建 Chat

创建一个绑定到某个 mind 的新有状态对话。

Endpoint: POST /api/v1/chats

必须且只能提供一种非空选择：mindId、mindIds 或 audienceIds。混合选择返回 400；空的可选数组不会覆盖单个 Mind。UUID 不区分大小写，重复 ID 会被忽略。创建对话最多接受 1 MiB JSON（包括转义字符）；超过限制会在数据库或方案权限处理之前返回 413。响应为私有数据，不缓存。

Headers:

Authorization: Bearer minds_your_api_key
Content-Type: application/json

请求体:

{
  "name": "My Conversation",
  "mindId": "your-mind-id"
}

响应 (201):

{
  "data": {
    "id": "601af953-3837-49c1-a31e-4fdbfa82ac04",
    "name": "My Conversation",
    "description": null,
    "createdAt": "2026-04-04T12:45:24.078Z",
    "minds": [
      {
        "id": "4774888e-0a03-40d7-979b-39b47c4c049c",
        "name": "Ada Lovelace",
        "discipline": "mathematician and computer scientist"
      }
    ]
  }
}

发送消息

向已有 chat 发送消息。服务端会自动处理对话历史、上下文窗口压缩和滚动摘要。

Endpoint: POST /api/v1/chats/{chatId}/messages

单个和多个 Mind 的对话都会遵守各 Mind 已保存的 knowledge_only 策略及工作区的网页研究限制。受限 Mind 使用当前问题、已训练的人物设定和检索到的相关 Mind 知识；内部工具、客户端工具、先前对话上下文及复制的 Study 资料都不会进入其回答上下文。检索到相关证据时，回答中的 metadata.knowledgeRetrieval.status 为 grounded；没有可用证据或检索失败时为 fallback。多个 Mind 的回答会在各 messages[] 项目的 metadata 中分别报告该状态。

工作区的网页研究权限与 knowledge_only 相互独立：关闭该权限会移除网页搜索和链接分析工具，但使用 auto 的 Mind 仍保留用户提供的资料和对话历史。上述回答上下文限制适用于使用 knowledge_only 的 Mind。

滚动记忆从最后一条已涵盖消息的 ID 之后继续，而不依赖可能随复制的 Study 上下文变化而移动的位置。生成的摘要行不计入对话轮次；所有者编写的系统备注仍可用于 v1 对话。如果其他请求已修改后台任务所依据的已存摘要，该任务的结果将被丢弃。

如果滚动摘要失败或未返回叙述正文，回退处理会保留此前的摘要和有效的已存事实，并附上新对话片段的简短摘录。 回退处理每次最多摘录30条新纳入的消息，并且只将这些消息标记为已涵盖。其余消息仍可在后续更新中处理。请求压缩依据已存消息 ID，避免重复已涵盖的摘录，同时保留最近的消息、优先保留的证据以及复制的 Study 上下文。

主持器通过 Mind ID 识别参与者。显示名称相同的 Mind 仍是不同的候选者，发言次数限制和连续发言检查均按 ID 执行。主持器可能在所有 Mind 回答之前结束讨论。

意外生成失败会返回不含提供商内部详情的通用 500，并为失败回答申请退还预留额度。此前已生成的回答和已保存的消息不会回滚。明确的模型能力拒绝仍返回 400，附带 data.errorType: "unsupported_model_capability"。对于多 Mind 对话，可选的后台摘要不会延迟已保存的回答，也不会使其变成错误响应。

消息请求也受 1 MiB JSON 限制；超限会在数据库或方案权限处理前返回 413。响应为私有数据，不缓存。只有对话所有者可以发消息。托管工作区会在每次请求时重新验证当前工作区和所关联 Mind/Audience 的授权；权限被撤销时，会在保存或计费前返回 404。

下方响应示例针对单个 Mind。多 Mind 对话返回 messages[]，Study 对话返回 outputData。设置 role: "system" 可保存上下文备注，不触发生成或消耗消息额度；响应为 { messageId, role: "system" }。

Headers:

Authorization: Bearer minds_your_api_key
Content-Type: application/json

请求体:

{
  "content": "What are the latest advancements in solar panel technology?"
}

有状态聊天的模型选择顺序为:每次请求的覆盖、团队首选提供方(如果已配置且有资格使用)、产品默认值。在此 endpoint 上,部分覆盖会以 400 Bad Request 拒绝;请同时发送 model 和 provider,或两者都不发送。

响应:

{
  "content": "Recent advancements in solar panel technology include perovskite cells with 30%+ efficiency...",
  "messageId": "cmnkbsddh00033v01ptk9t4et"
}

多轮示例

使用有状态 chat 时,每次只发送新消息即可。服务端会记住所有内容:

# Step 1: Create a chat
CHAT=$(curl -s -X POST "https://getminds.ai/api/v1/chats" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Research Session", "mindId": "your-mind-id" }')

CHAT_ID=$(echo $CHAT | jq -r '.data.id')

# Step 2: Send messages (server manages history automatically)
curl -X POST "https://getminds.ai/api/v1/chats/$CHAT_ID/messages" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "content": "What are the top marketing trends?" }'

# Step 3: Follow up (the mind remembers the previous exchange)
curl -X POST "https://getminds.ai/api/v1/chats/$CHAT_ID/messages" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "content": "Which of those would work best on a small budget?" }'

工作原理:

• 每条消息都会持久化到数据库
• 对于历史较长的单个 Mind 对话，最近8条消息保留完整内容
• 较早的轮次使用可用的已存摘要，并补充尚未涵盖的消息摘录
• 摘要会丢失细节；很长的历史记录或较大的消息仍可能达到模型的上下文限制。

删除对话

DELETE /api/v1/chats/{chatId}

只有所有者可以永久删除对话及其消息。Minds 和 Audiences 会保留。成功时返回 204，无响应体，请勿将其解析为 JSON。凭证缺失或无效返回 401，他人拥有的对话返回 403，不存在的对话返回 404（包括在最终写入前被删除或转移的对话）。删除响应使用 Cache-Control: private, no-store。

无状态 Completion

用于单次请求,或当你想自行管理对话历史时。

发送消息

向 mind 发送消息并接收回复。

Endpoint: POST /api/v1/minds/{mindId}/completion

Headers:

Authorization: Bearer minds_your_api_key
Content-Type: application/json

请求体

{
  "messages": [
    {
      "role": "user",
      "content": "What are the latest advancements in solar panel technology?"
    }
  ]
}

参数

响应

{
  "messageId": "msg_550e840029b141d4a716446655440000",
  "content": "Recent advancements in solar panel technology include perovskite cells with 30%+ efficiency, bifacial panels that capture light from both sides, and integrated storage systems...",
  "metadata": {
    "ragCitations": [
      {
        "id": "abc123",
        "displaySource": "Mind knowledge",
        "similarity": 0.89
      }
    ]
  }
}

单条消息示例

提出一个问题:

curl -X POST "https://getminds.ai/api/v1/minds/mind-id/completion" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "role": "user",
        "content": "What are the top 3 marketing trends for 2025?"
      }
    ]
  }'

多轮对话

通过带上之前的消息来保留对话上下文:

curl -X POST "https://getminds.ai/api/v1/minds/mind-id/completion" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "role": "user",
        "content": "What are the top marketing trends?"
      },
      {
        "role": "assistant",
        "content": "The top trends are AI personalization, short-form video, and community building..."
      },
      {
        "role": "user",
        "content": "How can I implement AI personalization on a budget?"
      }
    ]
  }'

多轮对话建议:

• 每次请求都带上完整对话历史
• 顺序很重要:消息应按时间先后排列
• user 与 assistant role 交替出现
• 最后一条消息应始终来自 user

文件附件

附加文件、文档、图片和链接,为 mind 提供上下文。Mind 会将处理后的内容作为对话的一部分接收。

附加文件

通过 user 消息中的 metadata.attachedFiles 数组添加文件:

无状态补全请求应使用自己上传的文件、带有效签名的聊天文件 URL，或通过上传者的 Study 共享的上下文。无权访问的工作区文件会返回 403 Upload access denied（流式模式下为错误帧）。外部 HTTP(S) URL 保留自身的访问令牌，不会根据任意存储路径重新签名。请将示例中的 your-user-id 替换为自己的用户 ID，并使用上传端点返回的路径。

curl -X POST "https://getminds.ai/api/v1/minds/mind-id/completion" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "role": "user",
        "content": "Please review this document and summarize the key points",
        "metadata": {
          "attachedFiles": [
            {
              "url": "https://example.com/quarterly-report.pdf",
              "name": "Q4 2025 Report",
              "type": "application/pdf"
            },
            {
              "path": "chat/your-user-id/meeting-notes.docx",
              "name": "Strategy Meeting Notes"
            }
          ]
        }
      }
    ]
  }'

附件格式

每个附件对象支持:

注意: url 与 path 二选一,不要同时提供。

支持的文件类型

文档:

• PDF (.pdf) - 文本抽取 + 扫描页的 OCR
• Word (.docx) - 全文抽取
• Text (.txt、.md) - 直接文本内容
• CSV/Excel (.csv、.xlsx) - 表格抽取

图片:

• PNG、JPG、WEBP - OCR + 视觉分析
• 支持图像理解的 vision 能力

外部 URL:

• 使用 Firecrawl 抓取网页(JS 渲染 + 截图)
• 自动转换为 markdown

处理流程

文件在送达 mind 前会自动处理:

1. 下载 - 从 URL 或 Supabase 存储获取文件
2. 抽取 - 抽取内容(PDF 中的文本、图片 OCR 等)
3. 注入 - 将处理后的内容加入对话上下文
4. 回复 - Mind 同时看到你的消息和文件内容

处理限制:

• 超时:每个文件 30 秒
• 文件并行处理
• 处理失败的文件以友好的兜底消息呈现

多文件示例

{
  "messages": [
    {
      "role": "user",
      "content": "Compare these two proposals and recommend which one to pursue",
      "metadata": {
        "attachedFiles": [
          {
            "url": "https://example.com/proposal-a.pdf",
            "name": "Proposal A - Cloud Migration",
            "type": "application/pdf"
          },
          {
            "url": "https://example.com/proposal-b.pdf",
            "name": "Proposal B - On-Prem Upgrade",
            "type": "application/pdf"
          },
          {
            "path": "chat/your-user-id/budget-analysis.xlsx",
            "name": "Budget Comparison"
          }
        ]
      }
    }
  ]
}

对话历史中的文件附件

在有附件的对话中继续交互时,历史中应包含带附件的原始消息:

{
  "messages": [
    {
      "role": "user",
      "content": "Analyze this sales data",
      "metadata": {
        "attachedFiles": [
          {
            "url": "https://example.com/sales-q4.csv",
            "name": "Q4 Sales Data"
          }
        ]
      }
    },
    {
      "role": "assistant",
      "content": "Based on the Q4 sales data, I can see that revenue increased by 23% compared to Q3..."
    },
    {
      "role": "user",
      "content": "What were the top 3 performing products?"
    }
  ]
}

注意: 文件只在首次附加时处理一次。同一对话中的后续消息会引用已处理好的内容。

网页链接

对网页和外部内容,使用 url 字段:

{
  "messages": [
    {
      "role": "user",
      "content": "Summarize the key findings from this research paper",
      "metadata": {
        "attachedFiles": [
          {
            "url": "https://arxiv.org/pdf/2103.12345.pdf",
            "name": "AI Research Paper",
            "type": "application/pdf"
          }
        ]
      }
    }
  ]
}

针对网页的特别说明:

• 重度依赖 JavaScript 的站点使用 Firecrawl 渲染
• 捕获截图以提供视觉上下文
• 内容转换为清洁的 markdown

错误处理

若文件处理失败:

• Mind 将收到一条兜底消息,提示文件已附加但处理失败
• 对话正常继续
• 超时错误显示 [Processing timeout - file may be too large]
• 其他错误显示 [Processing failed - file uploaded but analysis unavailable]

这确保即便处理失败,mind 仍能感知到你尝试附加的文件。

初始消息(问候)

若传入空的 messages 数组或不传 messages,mind 将自我介绍:

curl -X POST "https://getminds.ai/api/v1/minds/mind-id/completion" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": []
  }'

响应:

{
  "content": "Hi! I'm Sarah, a marketing director with 15 years of experience in B2B SaaS. I specialize in growth marketing and data-driven strategies. What can I help you with today?"
}

Model Override

你可以通过传入 model 参数,选择性覆盖无状态 completion 请求使用的 AI 模型。这适用于基准测试、成本优化或测试不同模型的行为。有状态聊天和 panel endpoint 会进行更严格的覆盖校验:请同时发送 model 和 provider。

curl -X POST "https://getminds.ai/api/v1/minds/mind-id/completion" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "role": "user",
        "content": "What are your thoughts on sustainable packaging?"
      }
    ],
    "model": "gpt-6-luna"
  }'

未指定 model 时使用服务端默认模型。

Provider

请传入上表列出的模型之一。已停用的 ID 会被转发(见下文),其他任何模型都会返回 400 Bad Request。provider 会基于常见模型名前缀自动识别(claude- → Anthropic、gemini- → Google、gpt-/o1/o3/o4 → OpenAI)。

Your own model

如需运行微调模型或自托管模型，由团队管理员将其添加为团队模型连接（OpenAI Chat Completions、OpenAI Responses 或 Anthropic Messages 协议）并完成验证。然后发送该连接的 ID 和当前修订版本，而不是 model 和 provider：

{
  "messages": [...],
  "modelConnection": { "id": "3f6c1e2a-5b7d-4c1e-9a0f-2d8e4b6a1c90", "revision": 3 }
}

GET /api/v1/model-connections 会列出你团队的连接及其修订版本和已验证的能力。连接需要支持文本和流式输出；发送 response_format 时还需要结构化输出，请求使用工具时还需要工具调用。如果你的端点失败，请求也会失败：Minds 绝不会切换到自己的模型。图片和其他媒体会以 MODEL_CONNECTION_MEDIA_UNVERIFIED 被拒绝。有状态聊天消息（/chats/{chatId}/messages）不接受连接。

Structured Output

使用 response_format 参数请求保证符合特定 schema 的 JSON 响应。它遵循 OpenAI 风格的结构化输出模式,适用于从对话中抽取结构化数据。

JSON Schema 模式

强制模型输出符合你 schema 的有效 JSON:

curl -X POST "https://getminds.ai/api/v1/minds/mind-id/completion" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "role": "user",
        "content": "Analyze the sentiment of this text: I love this product, it exceeded all my expectations!"
      }
    ],
    "response_format": {
      "type": "json_schema",
      "json_schema": {
        "name": "sentiment_analysis",
        "description": "Sentiment analysis result",
        "schema": {
          "type": "object",
          "properties": {
            "sentiment": {
              "type": "string",
              "enum": ["positive", "negative", "neutral"]
            },
            "confidence": {
              "type": "number",
              "minimum": 0,
              "maximum": 1
            },
            "keywords": {
              "type": "array",
              "items": { "type": "string" }
            }
          },
          "required": ["sentiment", "confidence", "keywords"]
        }
      }
    }
  }'

响应:

{
  "content": "{\"sentiment\": \"positive\", \"confidence\": 0.95, \"keywords\": [\"love\", \"exceeded\", \"expectations\"]}",
  "parsed": {
    "sentiment": "positive",
    "confidence": 0.95,
    "keywords": ["love", "exceeded", "expectations"]
  }
}

JSON Object 模式

强制 JSON 输出但不做 schema 校验:

curl -X POST "https://getminds.ai/api/v1/minds/mind-id/completion" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "role": "user",
        "content": "List 3 marketing ideas as JSON"
      }
    ],
    "response_format": {
      "type": "json_object"
    }
  }'

Response Format 类型

JSON Schema 字段

支持的 Schema 特性

支持以下 JSON Schema 特性:

• 类型:string、number、integer、boolean、array、object、null
• 约束:enum、minimum、maximum、minLength、maxLength、minItems、maxItems
• 结构:properties、required、items、additionalProperties
• 元数据:description(用于引导模型)

说明

• Tool(RAG、网络搜索等)与结构化输出可共同工作 —— mind 在生成结构化响应前仍可检索自己的知识库
• parsed 字段为方便使用直接给出解析后的 JSON 对象;content 则为原始 JSON 字符串
• 所有主要 provider(OpenAI、Anthropic、Google)都支持结构化输出
• 对于复杂 schema,建议添加 description 字段来引导模型输出

Tool Calling

让 mind 在对话中调用你自定义的函数。它遵循 OpenAI 兼容的 function calling 模式,可通过外部 tool 和 API 扩展 mind 的能力。

工作方式

1. 定义 tool:传入带名称、描述和 JSON Schema 参数的 tool 定义
2. Mind 决策 根据对话决定何时调用你的 tool(或你通过 tool_choice 强制调用)
3. API 返回 tool 调用:响应中包含带 tool 名称和生成参数的 tool_calls
4. 执行 tool:在你的应用中运行 tool 并拿到结果
5. 回传结果:在下一条消息中以 role: "tool" 带上结果
6. Mind 回复 将 tool 结果整合进最终回复

基础示例

带 tool 的请求:

curl -X POST "https://getminds.ai/api/v1/minds/mind-id/completion" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "role": "user",
        "content": "What is the weather in Berlin?"
      }
    ],
    "tools": [
      {
        "name": "get_weather",
        "description": "Get current weather for a city",
        "parameters": {
          "type": "object",
          "properties": {
            "city": {
              "type": "string",
              "description": "City name"
            },
            "units": {
              "type": "string",
              "enum": ["celsius", "fahrenheit"],
              "description": "Temperature units"
            }
          },
          "required": ["city"]
        }
      }
    ]
  }'

响应:

{
  "content": "",
  "tool_calls": [
    {
      "id": "call_abc123",
      "name": "get_weather",
      "arguments": {
        "city": "Berlin",
        "units": "celsius"
      }
    }
  ]
}

执行 tool 并回传结果:

curl -X POST "https://getminds.ai/api/v1/minds/mind-id/completion" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "role": "user",
        "content": "What is the weather in Berlin?"
      },
      {
        "role": "assistant",
        "content": "",
        "tool_calls": [
          {
            "id": "call_abc123",
            "name": "get_weather",
            "arguments": {
              "city": "Berlin",
              "units": "celsius"
            }
          }
        ]
      },
      {
        "role": "tool",
        "tool_call_id": "call_abc123",
        "content": "{\"temperature\": 18, \"condition\": \"partly cloudy\", \"humidity\": 65}"
      }
    ],
    "tools": [
      {
        "name": "get_weather",
        "description": "Get current weather for a city",
        "parameters": {
          "type": "object",
          "properties": {
            "city": { "type": "string" },
            "units": { "type": "string", "enum": ["celsius", "fahrenheit"] }
          },
          "required": ["city"]
        }
      }
    ]
  }'

最终响应:

{
  "content": "The current weather in Berlin is 18°C and partly cloudy, with 65% humidity."
}

Tool 定义 Schema

每个 tool 必须遵循如下结构:

{
  "name": "tool_name",
  "description": "Clear description of when and how to use this tool",
  "parameters": {
    "type": "object",
    "properties": {
      "param1": {
        "type": "string",
        "description": "What this parameter does"
      }
    },
    "required": ["param1"]
  },
  "strict": true
}

必填字段:

可选字段:

Tool Choice 模式

通过 tool_choice 参数控制 mind 何时、如何调用 tool:

示例:

// Let the mind decide
{
  "messages": [...],
  "tools": [...],
  "tool_choice": "auto"
}

// Force a specific tool
{
  "messages": [...],
  "tools": [...],
  "tool_choice": {
    "name": "search_database"
  }
}

// Require at least one tool call
{
  "messages": [...],
  "tools": [...],
  "tool_choice": "required"
}

并行 Tool 调用

默认情况下,mind 可在单轮中调用多个 tool 以提升效率:

{
  "content": "",
  "tool_calls": [
    {
      "id": "call_1",
      "name": "get_customer",
      "arguments": { "id": "CUST-001" }
    },
    {
      "id": "call_2",
      "name": "get_customer",
      "arguments": { "id": "CUST-002" }
    }
  ]
}

要禁用并行调用、强制顺序执行:

{
  "messages": [...],
  "tools": [...],
  "parallel_tool_calls": false
}

Tool 消息格式

回传 tool 结果时,使用 tool role:

{
  "role": "tool",
  "tool_call_id": "call_abc123",
  "content": "{\"result\": \"success\", \"data\": {...}}"
}

工具结果应放在对应的助手消息之后，并保留该消息的 tool_calls。使用返回的调用 ID 和名称，每个结果只提交一次。格式错误的参数、未知调用 ID、不匹配的工具名称、重复结果以及缺失的客户端结果都会在生成前返回 400。

内置 Tool 与用户 Tool

Minds 提供自动执行的服务端内置 tool:

关键区别:

• 内置 tool:服务端执行,结果包含在 content 和 metadata 中,绝不在 tool_calls 中返回。
• 用户 tool:在 tool_calls 中返回供你执行。结果需以 tool 消息回传。

你无法覆盖或禁用内置 tool。用户 tool 是叠加的 —— 用于扩展 mind 的能力。

完整多 Tool 示例

一个带多个自定义 tool 的法律助理 mind:

curl -X POST "https://getminds.ai/api/v1/minds/mind-id/completion" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "role": "user",
        "content": "Create a new case for Schmidt vs. Mueller and search for similar precedents"
      }
    ],
    "tools": [
      {
        "name": "create_case",
        "description": "Create a new legal case in the system",
        "parameters": {
          "type": "object",
          "properties": {
            "title": {
              "type": "string",
              "description": "Case title (parties involved)"
            },
            "practice_area": {
              "type": "string",
              "enum": ["corporate", "litigation", "employment", "ip"],
              "description": "Legal practice area"
            },
            "client_id": {
              "type": "string",
              "description": "Client identifier"
            }
          },
          "required": ["title", "practice_area"]
        }
      },
      {
        "name": "search_precedents",
        "description": "Search legal database for similar cases",
        "parameters": {
          "type": "object",
          "properties": {
            "keywords": {
              "type": "array",
              "items": { "type": "string" },
              "description": "Search keywords"
            },
            "practice_area": {
              "type": "string",
              "description": "Filter by practice area"
            },
            "max_results": {
              "type": "integer",
              "minimum": 1,
              "maximum": 50,
              "description": "Maximum number of results"
            }
          },
          "required": ["keywords"]
        }
      }
    ],
    "parallel_tool_calls": true
  }'

带并行 tool 调用的响应:

{
  "content": "",
  "tool_calls": [
    {
      "id": "call_1",
      "name": "create_case",
      "arguments": {
        "title": "Schmidt vs. Mueller",
        "practice_area": "litigation"
      }
    },
    {
      "id": "call_2",
      "name": "search_precedents",
      "arguments": {
        "keywords": ["Schmidt", "Mueller"],
        "practice_area": "litigation",
        "max_results": 10
      }
    }
  ]
}

最佳实践

1. 写清晰的描述:description 字段至关重要。明确说明每个 tool 的使用时机与原因。

   ❌ "description": "Search database"
   ✅ "description": "Search the legal precedents database for similar cases based on keywords and practice area"
   

2. 为参数添加描述:帮助 mind 理解每个参数的作用。

   "case_id": {
     "type": "string",
     "description": "Unique case identifier in format CASE-YYYY-NNNN"
   }
   

3. 对受限取值使用 enum:

   "status": {
     "type": "string",
     "enum": ["pending", "active", "closed", "archived"]
   }
   

4. 设置校验约束:

   "priority": {
     "type": "integer",
     "minimum": 1,
     "maximum": 5,
     "description": "Priority level (1=lowest, 5=highest)"
   }
   

5. 启用 strict 模式:保持 strict: true(默认),确保 mind 生成合法参数。
6. 返回结构化的 tool 结果:用 JSON 让结果易于解析:

   {
     "role": "tool",
     "tool_call_id": "call_123",
     "content": "{\"success\": true, \"case_id\": \"CASE-2026-001\", \"created_at\": \"2026-03-30T23:00:00Z\"}"
   }
   

7. 优雅处理错误:在 tool 结果中返回错误详情:

   {
     "role": "tool",
     "tool_call_id": "call_123",
     "content": "{\"success\": false, \"error\": \"Case already exists\", \"error_code\": \"DUPLICATE_CASE\"}"
   }
   

限制

• 每次请求最多 128 个 tool
• Tool 名称必须唯一,且不能与内置 tool 名冲突
• Tool 执行发生在客户端 —— 你需自行运行并保障 tool 的安全
• Tool 结果必须回传到对话历史,mind 才能据此回复

JSON Schema 支持

parameters 字段支持标准的 JSON Schema 特性:

类型:

• string、number、integer、boolean、array、object、null

校验:

• enum —— 限制为特定取值
• minimum、maximum —— 数值范围
• minLength、maxLength —— 字符串长度
• minItems、maxItems —— 数组大小
• pattern —— 正则校验
• format —— 字符串格式(如 "date-time"、"email"、"uri")

结构:

• properties —— 对象属性
• required —— 必填字段
• items —— 数组元素 schema
• additionalProperties —— 是否允许额外属性

高级校验示例:

{
  "name": "schedule_meeting",
  "description": "Schedule a meeting with a client",
  "parameters": {
    "type": "object",
    "properties": {
      "title": {
        "type": "string",
        "minLength": 1,
        "maxLength": 200
      },
      "date": {
        "type": "string",
        "format": "date-time",
        "description": "Meeting date and time in ISO 8601 format"
      },
      "attendees": {
        "type": "array",
        "items": {
          "type": "string",
          "format": "email"
        },
        "minItems": 1,
        "maxItems": 20
      },
      "duration_minutes": {
        "type": "integer",
        "minimum": 15,
        "maximum": 480,
        "description": "Meeting duration (15-480 minutes)"
      }
    },
    "required": ["title", "date", "attendees"]
  }
}

工作原理

1. 上下文加载

当你发送消息时,mind 会:

• 加载其 system prompt 和配置
• 自动检索其知识库以获取相关信息
• 综合考虑对话历史

2. 处理

Mind 会:

• 在上下文中分析你的消息
• 基于检索到的知识生成回答并附上 citation
• 按需调用额外 tool(网络搜索、图像生成等)
• 生成符合其人格的回复

3. 响应生成

Mind 会:

• 生成体现其专长的回复
• 附上 citation,当使用知识库或网络来源时
• 返回消息,并可选带上元数据(citations、images 等)

元数据

响应可包含额外元数据:

图片

当 mind 生成或展示图片时:

{
  "content": "Here are some logo concepts...",
  "metadata": {
    "images": [
      {
        "id": "img_123",
        "url": "https://...",
        "filename": "Logo Concept 1",
        "description": "Modern minimalist logo with blue gradient",
        "source": "generated"
      }
    ]
  }
}

知识 Citation

当 mind 从知识库或网络搜索中检索到信息时:

{
  "content": "Based on recent research, solar panel efficiency has improved significantly...",
  "metadata": {
    "ragCitations": [
      {
        "id": "9bf44ab0-9d83-42ec-b941-c0ab7610e949",
        "displaySource": "Mind knowledge",
        "similarity": 0.85
      },
      {
        "id": "external-web-123",
        "displaySource": "https://example.com/solar-research",
        "similarity": 0.92
      }
    ]
  }
}

Citation 字段:

• id - 来源的唯一标识
• displaySource - 人类可读的来源名称或 URL
• similarity - 相关性分数(0-1),反映该来源与问题的契合度

Mind 会在回复前自动检索知识库,并在其答案基于特定来源时附上 citation。

访问控制

你可以与以下 mind 对话:

• 拥有 - 你创建的 mind
• 被授权 - 团队成员分享给你的 mind
• 所在成员 - 你所属团队 workspace 中的 mind
• 公共 mind - 公开可访问的 mind

尝试访问无权限的 mind 会返回:

{
  "statusCode": 403,
  "statusMessage": "Access denied"
}

响应格式

文本响应

大多数响应是纯文本:

{
  "content": "Based on current trends, I recommend focusing on..."
}

结构化响应

部分 mind 可能返回结构化内容:

{
  "content": "Here's my analysis:\n\n1. Trend: AI Personalization\n   - Impact: High\n   - Timeline: 6-12 months\n\n2. Trend: Short-form Video\n   - Impact: Very High\n   - Timeline: Immediate"
}

空内容带元数据的响应

有时仅返回元数据(例如图像生成):

{
  "content": "",
  "metadata": {
    "images": [...]
  }
}

最佳实践

要具体

❌ "Tell me about marketing"
✅ "What are the most cost-effective digital marketing channels for a B2B SaaS startup with a $5K monthly budget?"

提供上下文

✅ "We're launching a sustainable fashion brand targeting Gen Z. What social media strategy would you recommend?"

善用追问

充分利用对话记忆:

User: "What are the top trends?"
Assistant: "The top trends are..."
User: "Which of these would work best for a small budget?"
Assistant: "For a small budget, I'd focus on..."

引用知识

如果你上传了知识,主动引用:

✅ "Based on our brand guidelines, what tone should we use for this campaign?"

错误响应

400 Bad Request

缺少或无效的 Mind ID:

{
  "statusCode": 400,
  "statusMessage": "Mind ID is required"
}

不支持的 provider:

{
  "statusCode": 400,
  "statusMessage": "Unsupported provider: 'invalid'. Supported providers: openai, anthropic, google."
}

名称不明确且未指定 provider:

{
  "statusCode": 400,
  "statusMessage": "Cannot auto-detect provider for model 'my-model'. Please specify a 'provider' parameter (openai, anthropic, or google)."
}

401 Unauthorized

API key 无效。

403 Forbidden

无权访问 Mind:

{
  "statusCode": 403,
  "statusMessage": "Access denied"
}

404 Not Found

Mind 不存在:

{
  "statusCode": 404,
  "statusMessage": "Mind not found"
}

使用说明

• v1 API 按已认证账户执行可配置限流（默认每分钟 300 个请求）
• 请读取 RateLimit-Limit 和 RateLimit-Remaining，在 429 后遵循 Retry-After
• 生成请求会消耗大量资源，请限制并行 completion 数量

下一步

• 了解 latency 与性能
• 了解 错误与 rate limit
• 创建你的第一个 mind
• 上传 knowledge 以增强回复
• 阅读 API 概览