接入选型与快速开始

根据你的集成目标,在五种官方入口中选出最匹配的一条,并在几分钟内跑通首次调用。所有公开 REST 接口的完整参数与响应字典统一以 API 参考 为准,本栏目只写端到端编排与非 OpenAPI 协议。

五种接入方式怎么选

把「谁来生成最终回答」和「是否需要编排平台资源」拆开看,选型一目了然:

接入方式 协议与入口 适用场景 推荐鉴权 延伸指南
声明式配置 API /api/v2/workspaces/{id}/agents
/knowledge-bases/config
/connections
用 IaC / CI / 后台程序创建、局部修改、预演与同步 Agent、知识库和外部连接 组织 API Key 或 OAuth 声明式配置
原生 Turn 对话 API /api/v2/bots/{id}/chats
/api/v2/agent/chats/{id}/turns
保留多轮上下文、获取结构化 parts[]、句级引用证据、工具确认与 PDF 导出 API Key / Agent API Key / OAuth 对话与异步 Turn
OpenAI 兼容接口 POST /v1/chat/completions 复用现有 OpenAI SDK、LangChain 或 Chat UI,零改造切换为 ApeMind Agent 回答 API Key OpenAI 兼容接口
MCP Server POST /mcp/(Streamable HTTP) 让 Cursor、Claude Code 或自研 Agent 直接检索 ApeMind 知识库、图谱与外部连接,由你的 Agent 生成回答 API Key 或 OAuth MCP 接入与工具参考
A2A 1.0 协议 /v1/a2a/bots/{id}(JSON-RPC + SSE) 多智能体编排框架通过标准 Agent Card 发现并异步调度 ApeMind Agent 组织 API Key A2A 1.0 协议接入
接口字典在哪里?

实时同步的全部 REST 路径、字段类型、枚举值与在线调试都在 API 参考(对应部署的 /api/openapi.json)。本栏目的每一篇只覆盖跨接口状态机、权限边界、非显而易见的运行约束以及 OpenAPI 未覆盖的协议(/mcp/、A2A、CLI 评测闭环)。

环境与入口约定

SaaS 与私有化部署共享同一套 API 契约,只需替换根域名:

资源 SaaS 正式环境 私有化部署
API 根地址 https://apemind.ai https://<APEMIND_HOST>
MCP Server https://apemind.ai/mcp/ https://<APEMIND_HOST>/mcp/
OpenAI 兼容根地址 https://apemind.ai/v1 https://<APEMIND_HOST>/v1
OpenAPI 规范 https://apemind.ai/api/openapi.json https://<APEMIND_HOST>/api/openapi.json

本文及本栏目示例统一使用以下环境变量:

export APEMIND_BASE_URL="https://apemind.ai"
export APEMIND_ORG_ID="<ORGANIZATION_ID>"
export APEMIND_API_KEY="<API_KEY>"

十分钟最小集成闭环

下面以「准备一个可问答的 Agent 并获取带证据的回答」为例,串起最典型的服务端接入步骤:

  1. 签发凭据并确认组织 ID

    在目标组织的设置页创建组织服务账号并签发 API Key,或在个人设置中为该组织创建 API Key。验证凭据和当前身份:

    curl --fail-with-body \
      -H "Authorization: Bearer ${APEMIND_API_KEY}" \
      "${APEMIND_BASE_URL}/api/v2/auth/user"
  2. 声明式创建知识库并上传文档

    推荐通过声明式配置接口创建知识库(先加 ?dry_run=true 预演),随后上传文件并等待索引就绪。完整状态机见知识库入库与检索编排。

    curl --fail-with-body \
      -X POST "${APEMIND_BASE_URL}/api/v2/workspaces/${APEMIND_ORG_ID}/knowledge-bases/config" \
      -H "Authorization: Bearer ${APEMIND_API_KEY}" \
      -H "Content-Type: application/json" \
      -d '{
        "metadata": {"title": "产品文档库"},
        "spec": {"enable_vector": true, "enable_fulltext": true}
      }'
  3. 声明式创建 Agent 并挂载知识库

    通过 POST /api/v2/workspaces/{org_id}/agents 一次写清模型、人设与知识库权限(spec.model: "default" 自动使用组织默认对话模型):

    curl --fail-with-body \
      -X POST "${APEMIND_BASE_URL}/api/v2/workspaces/${APEMIND_ORG_ID}/agents" \
      -H "Authorization: Bearer ${APEMIND_API_KEY}" \
      -H "Content-Type: application/json" \
      -d '{
        "metadata": {"title": "产品顾问"},
        "spec": {
          "model": "default",
          "instructions": "基于知识库准确回答产品问题并给出出处。",
          "capabilities": {
            "knowledge": {
              "scope": "listed",
              "bases": {"<KB_ID>": {"default": true}},
              "level": "view"
            }
          }
        }
      }'
  4. 发起提问并读取回答

    需要快速接入已有 SDK 时直接调 OpenAI 兼容端点;需要完整工具轨迹、交互确认与结构化引用时走原生 Turn API(详见对话与异步 Turn 集成):

    curl --fail-with-body \
      -X POST "${APEMIND_BASE_URL}/v1/chat/completions?bot_id=<AGENT_ID>&language=zh-CN" \
      -H "Authorization: Bearer ${APEMIND_API_KEY}" \
      -H "Content-Type: application/json" \
      -d '{
        "model": "apemind",
        "messages": [{"role": "user", "content": "退换货时限是几天?"}]
      }'

关于 CLI 与历史路径命名

下一步