调用已经挂载好的 Karmen AI。

01 / 架构

对外是 Karmen 实例，对内是能力编排层。

一个 API Key 只调用一个已部署的 Karmen 实例。Karmen 可以在内部更新能力组合，而接入方继续使用同一个地址、Key 和 v1 合同。

02 / 快速开始

五分钟完成服务器接线。

1. 1
   在工作台部署 Karmen 实例

   选择服务板块，配置身份、职责、知识和权限。

2. 2
   获取 API Key

   进入岗位的“接入与密钥”，点击“生成 Karmen API Key”。完整值只显示一次，只保存到目标网站的服务器秘密变量。

3. 3
   先检查连接，再发送测试消息

   连接检查不调用模型；真实聊天必须另外验收。

先在目标系统的服务器秘密变量中设置以下两项。将示例域名替换为工作台提供的实际 API 地址，保留末尾的 /v1；Key 使用工作台签发的完整值。

KARMEN_BASE_URL=https://your-karmen-api.example/v1
KARMEN_API_KEY=REPLACE_IN_SERVER_SECRET_SETTINGS

curl "$KARMEN_BASE_URL/connection" \
  -H "Authorization: Bearer $KARMEN_API_KEY"

curl "$KARMEN_BASE_URL/chat" \
  -H "Authorization: Bearer $KARMEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "requestId": "req_0123456789abcdef0123456789abcdef",
    "userId": "crm-user-1842",
    "message": "请介绍这项服务。"
  }'

03 / 身份验证

每一次请求都使用服务器 API Key。

把 Key 放在 HTTP 的 Authorization 请求头中。不要把 Key 放进网页 JavaScript、HTML、手机安装包、Git 仓库、知识文件或 URL。

Authorization: Bearer YOUR_KARMEN_API_KEY

一个 Key 固定绑定一个 Karmen 实例。需要让另一个网站或 CRM 使用不同实例时，请在工作台为对应实例生成新的 Key，不要共享管理员账号。

04 / 完整教程

发送第一条消息，再继续一段会话。

发送第一条消息

第一次调用不提交 conversationId。userId 应来自你自己系统中已经登录的用户，requestId 用于避免同一次请求被重复执行。

curl "$KARMEN_BASE_URL/chat" \
  -H "Authorization: Bearer $KARMEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "requestId": "req_0123456789abcdef0123456789abcdef",
    "userId": "crm-user-1842",
    "message": "请介绍这项服务。"
  }'

{
  "reply": "Karmen 实例返回的回答",
  "conversationId": "conv_0123456789abcdef0123456789abcdef",
  "sources": []
}

继续一段会话

保存第一次响应中的 conversationId。同一用户继续提问时，把它原样提交；不要把甲用户的会话 ID 交给乙用户。

curl "$KARMEN_BASE_URL/chat" \
  -H "Authorization: Bearer $KARMEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "requestId": "req_fedcba9876543210fedcba9876543210",
    "userId": "crm-user-1842",
    "conversationId": "conv_0123456789abcdef0123456789abcdef",
    "message": "请继续说明合作流程。"
  }'

Node.js

发送前将已鉴权用户、原业务 requestId、可选 conversationId 和完整请求体保存到你的服务器任务记录。以下 savedRequestJSON 是该记录中已保存的 JSON 字符串；不要在每次尝试时生成新 ID。

const response = await fetch(`${process.env.KARMEN_BASE_URL}/chat`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.KARMEN_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: savedRequestJSON
});

if (!response.ok) throw new Error(`Karmen request failed: ${response.status}`);
const result = await response.json();

Python

saved_request_json 同样来自发送前持久保存的完整请求体，保留原ID和属性顺序。

import json, os, urllib.request

payload = saved_request_json.encode("utf-8")

request = urllib.request.Request(
    os.environ["KARMEN_BASE_URL"] + "/chat",
    data=payload,
    method="POST",
    headers={
        "Authorization": "Bearer " + os.environ["KARMEN_API_KEY"],
        "Content-Type": "application/json"
    }
)

with urllib.request.urlopen(request, timeout=30) as response:
    result = json.load(response)

05 / API 参考

当前公开 v1 只有两个服务器端点。

请求体只接受 requestId、userId、message 和可选 conversationId。固定 JSON 响应便于业务系统保存，但当前不接受任意输出 Schema。

requestId 与提供的 conversationId 须匹配 ^[A-Za-z0-9_-]{16,100}$。消息最多20,000个Unicode字符，JSON请求体最多262,144字节，并使用 Content-Type: application/json。

06 / CRM

CRM 只管理客户映射，不管理内部模型。

CRM tenant_id + authenticated user_id
              ↓
管理员预先绑定的 Karmen job key
              ↓
POST /v1/chat
              ↓
保存 conversationId、reply、sources

同一业务动作获准重试时，使用已持久保存的原 requestId 和完整请求体，保留属性顺序。CRM 必须把 conversationId 绑定到原用户，禁止跨用户复用。

07 / 能力边界

没有写进合同的能力，不会被假装成已接通。

当前支持管理员验证、确认为只读并批准到该实例的 MCP 工具。仅活动绑定及允许清单可用；凭据由服务端保管，网关负责参数校验、调用上限与审计。没有获批绑定时不调用工具。接入方不能提交 tools、任意 URL 或写操作；管理员确认不等于证明第三方工具绝无副作用，生产连接仍须验收。

08 / 可靠调用

错误处理与速率限制。

已完成的同ID同请求体返回缓存；request_in_progress 表示处理中，request_outcome_uncertain 表示结果未知，request_id_conflict 表示请求体不同。超时、网络失败或结果未知时，停止自动重发并交管理员核对；当前没有公开请求查询端点。

错误响应中的 requestId 是新生成的诊断追踪号，不是原业务幂等号。分别保存两者；不要用错误追踪号或默认生成的新 UUID 重发原业务。

当前服务器 Key 的连接检查限制为每分钟 60 次；聊天还会受到实例、访客和服务并发限制。遇到 429 时必须遵循响应中的等待时间。

09 / 资源

文档与机器合同保持在同一版本。