立刻智能体平台 API 文档

概述

立刻智能体平台提供统一的 HTTP API 接口，允许外部系统通过标准 HTTP 请求调用 AI 智能问答能力。系统基于知识库向量检索 + 大语言模型的 RAG 架构，确保回答精准可靠。

调用流程

Base URL

https://agent.likelic.com/api/v1

认证方式

所有 API 请求必须在 HTTP Headers 中携带以下两个认证字段，且两个凭证必须属于同一企业：

认证校验规则

智能对话接口 Core

POST /api/v1/chat

向智能体发送问题并获取 AI 回答。支持指定提示词模板和流式/非流式输出模式。

请求参数 (JSON Body)

关键词转人工（企业微信）

若企业已在控制台配置「企业微信 → 人工客服转接」（开启转人工推送并填写群机器人 Webhook、触发词），则开放 API 与网页组件、控制台 Chat 共用同一套触发词：当用户 question 中包含任一条触发词时，本次请求不会调用大模型，而是创建/续接人工会话，并向企微群推送卡片。

• session_id：首条转人工请求可不传，响应中的 session_id 须保存；后续用户与人工沟通过程中请继续传入同一 session_id，追问会推送到同一企微群线程。
• 响应：data.human_mode === true 表示已进入人工模式；data.answer 为提示文案；data.human_session_db_id 为内部会话主键（与群内卡片「会话记录ID」一致，供排障或对接工单）。
• 退出人工：用户发送结束类话术（与控制台人工会话一致）且传入当前 session_id 时，可结束会话并回到 AI。
• 流式：转人工在流式、非流式下均在调用模型之前判定；命中转人工时返回普通 JSON（非 SSE）。
• 按 API Key 控制：专业版及以上在「API 设置 → 管理密钥权限」中可关闭某密钥的转人工，或指定仅使用某条企微「人工客服转接」配置（多配置时避免串线）。基础版（Lite）无企业微信菜单，亦不展示该项，开放 API 侧沿用默认转人工策略（若企业未配企微则不会命中）。

非流式输出 (stream: false)

完整等待模型生成后一次性返回结果，适用于后台任务、批处理等场景。

请求示例（首次对话）

curl -X POST https://agent.likelic.com/api/v1/chat \
  -H "Content-Type: application/json" \
  -H "X-Customer-Code: your_customer_code" \
  -H "X-API-Key: sk-your-api-key-here" \
  -d '{
    "question": "你们的退货政策是什么？",
    "template_id": "Abc123Def456GhiJkl789Mnop"
  }'

请求示例（多轮对话，续接会话）

curl -X POST https://agent.likelic.com/api/v1/chat \
  -H "Content-Type: application/json" \
  -H "X-Customer-Code: your_customer_code" \
  -H "X-API-Key: sk-your-api-key-here" \
  -d '{
    "question": "那退款需要多长时间到账？",
    "template_id": "Abc123Def456GhiJkl789Mnop",
    "session_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }'

响应示例

{
  "success": true,
  "data": {
    "answer": "根据我们的退货政策，您可以在收到商品后 7 天内申请无理由退货...",
    "session_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "sources": [
      {
        "question": "退货政策有什么规定？",
        "score": 0.92
      }
    ],
    "model": "qwen-plus",
    "tokensUsed": 486,
    "responseTime": 1523
  }
}

响应字段说明

人工客服回复轮询 GET /api/v1/human-replies

在 human_mode 为 true 且拿到与 /chat 相同的 session_id 后，可用本接口轮询企微群内回复。鉴权与 Chat 一致：X-Customer-Code、X-API-Key。

查询参数

响应 data.messages[]

curl -G "https://agent.likelic.com/api/v1/human-replies" \
  -H "X-Customer-Code: your_customer_code" \
  -H "X-API-Key: sk-your-api-key-here" \
  --data-urlencode "session_id=a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  --data-urlencode "since_id=0"

流式输出 (stream: true)

以 SSE (Server-Sent Events) 格式实时推送生成内容，适用于前端实时展示打字效果等交互场景。

请求示例（流式 + 首次会话，需传入 session_id 以记录连续对话）

curl -X POST https://agent.likelic.com/api/v1/chat \
  -H "Content-Type: application/json" \
  -H "X-Customer-Code: your_customer_code" \
  -H "X-API-Key: sk-your-api-key-here" \
  -d '{
    "question": "如何申请退款？",
    "template_id": "Abc123Def456GhiJkl789Mnop",
    "session_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "stream": true
  }'

流式响应格式

响应 Content-Type 为 text/event-stream，数据以 SSE 格式逐行推送：

data: {"content":"根据"}

data: {"content":"我们"}

data: {"content":"的退货"}

data: {"content":"政策，"}

data: {"content":"..."}

data: [DONE]

JavaScript 流式调用示例

// 若需记录连续会话，流式首次请求需传入 session_id（流式响应不包含 session_id）
const sessionId = crypto.randomUUID();
const response = await fetch('https://agent.likelic.com/api/v1/chat', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Customer-Code': 'your_customer_code',
    'X-API-Key': 'sk-your-api-key-here'
  },
  body: JSON.stringify({
    question: '如何申请退款？',
    template_id: 'Abc123Def456GhiJkl789Mnop',
    session_id: sessionId,
    stream: true
  })
});

const reader = response.body.getReader();
const decoder = new TextDecoder();
let result = '';

while (true) {
  const { done, value } = await reader.read();
  if (done) break;

  const chunk = decoder.decode(value);
  const lines = chunk.split('\n');

  for (const line of lines) {
    if (line.startsWith('data: ') && line !== 'data: [DONE]') {
      const json = JSON.parse(line.slice(6));
      result += json.content;
      console.log(json.content); // 实时输出
    }
  }
}

Python 调用示例

import requests
import json

url = "https://agent.likelic.com/api/v1/chat"
headers = {
    "Content-Type": "application/json",
    "X-Customer-Code": "your_customer_code",
    "X-API-Key": "sk-your-api-key-here"
}

# 非流式调用（首次对话，不传 session_id）
resp = requests.post(url, headers=headers, json={
    "question": "你们的退货政策是什么？",
    "template_id": "Abc123Def456GhiJkl789Mnop"
})
data = resp.json()["data"]
session_id = data["session_id"]  # 保存用于后续多轮对话
print(data["answer"])

# 多轮对话（传入首次返回的 session_id）
resp = requests.post(url, headers=headers, json={
    "question": "那退款需要多长时间到账？",
    "template_id": "Abc123Def456GhiJkl789Mnop",
    "session_id": session_id
})
print(resp.json()["data"]["answer"])

# 流式调用（若需记录连续会话，首次请求需传入 session_id，因流式响应不包含 session_id）
import uuid
stream_session_id = str(uuid.uuid4())
resp = requests.post(url, headers=headers, json={
    "question": "还有其他注意事项吗？",
    "template_id": "Abc123Def456GhiJkl789Mnop",
    "session_id": stream_session_id,
    "stream": True
}, stream=True)

for line in resp.iter_lines():
    if line:
        decoded = line.decode("utf-8")
        if decoded.startswith("data: ") and decoded != "data: [DONE]":
            data = json.loads(decoded[6:])
            print(data["content"], end="", flush=True)

知识库写入接口 KB

POST /api/v1/knowledge/entries

从外部系统向本企业知识库新增一条问答对，鉴权与 Chat 相同（X-Customer-Code + X-API-Key）。校验通过后先写入 MySQL并立即返回成功；向量嵌入与 Qdrant 同步在后台异步执行（与控制台 Excel 批量导入的第二阶段一致），稍后在智能对话中即可检索到该条。

请求参数 (JSON Body)

本接口请求体上限 512 KB（大于通用 v1 的 100 KB）。

成功响应示例

{
  "success": true,
  "data": {
    "id": 12345,
    "category": "产品说明",
    "created_by": "crm_sync",
    "updated_by": null,
    "vector_sync": "queued",
    "message": "Entry saved to database. Vector embedding sync runs asynchronously; ..."
  }
}

配额不足示例（403）

{
  "success": false,
  "message": "Knowledge base entry limit reached for your plan (...)",
  "data": { "limit": 10000, "current": 10000, "remaining": 0 }
}

{
  "success": false,
  "message": "Cannot create new category: ...",
  "data": {
    "max_categories": 10,
    "current_category_count": 10,
    "existing_categories": ["分类A", "分类B"]
  }
}

请求示例

curl -X POST https://agent.likelic.com/api/v1/knowledge/entries \
  -H "Content-Type: application/json" \
  -H "X-Customer-Code: your_customer_code" \
  -H "X-API-Key: sk-your-api-key-here" \
  -d '{
    "question": "如何重置密码？",
    "answer": "请在登录页点击「忘记密码」并按邮件指引操作。",
    "category": "账户与安全",
    "keywords": "password,reset,login",
    "answer_image": "https://example.com/help/screenshot.png"
  }'

更新单条知识（PUT）

PUT /api/v1/knowledge/entries/:id

使用创建接口返回的 data.id 作为路径参数 :id，更新同一条问答。请求体字段与 POST 相同，另可选传 updated_by（最大 100 字符）作为本次修改人标识。若不传 answer_image，则保留该条原有配图。

更新成功响应示例

{
  "success": true,
  "data": {
    "id": 12345,
    "category": "产品说明",
    "created_by": "crm_sync",
    "updated_by": "operator_a",
    "vector_sync": "queued",
    "message": "Entry updated. Vector embedding sync runs asynchronously; ..."
  }
}

curl -X PUT https://agent.likelic.com/api/v1/knowledge/entries/12345 \
  -H "Content-Type: application/json" \
  -H "X-Customer-Code: your_customer_code" \
  -H "X-API-Key: sk-your-api-key-here" \
  -d '{
    "question": "如何重置密码？",
    "answer": "请在登录页点击「忘记密码」并按邮件指引操作。",
    "category": "账户与安全",
    "keywords": "password,reset",
    "updated_by": "operator_a"
  }'

合作客商写入 WEWORK PARTNER

POST /api/v1/wework/partner-companies/import

从外部系统批量写入合作客商主数据，鉴权与 Chat 相同（X-Customer-Code + X-API-Key）。按 (租户, company_code) upsert：company_code 已存在则合并更新，不存在则新增。行为与控制台「导入合作公司」Excel 导入完全一致。

请求参数 (JSON Body)

顶层字段 rows 为数组，非空且不超过 5000 行；每行字段如下：

行级校验

缺少 company_code 或 company_name、或 company_status 非法的行会被跳过并计入 data.skipped，跳过原因逐条列在 data.errors（不影响其余有效行写入）。

请求示例

curl -X POST https://agent.likelic.com/api/v1/wework/partner-companies/import \
  -H "Content-Type: application/json" \
  -H "X-Customer-Code: your_customer_code" \
  -H "X-API-Key: sk-your-api-key-here" \
  -d '{
    "rows": [
      {
        "company_code": "C1001",
        "company_name": "示例科技有限公司",
        "company_short_name": "示例科技",
        "sales_name": "张三",
        "tracker_name": "李四",
        "company_status": "已合作"
      },
      {
        "company_code": "C1002",
        "company_name": "另一家公司",
        "company_status": "trial"
      }
    ]
  }'

成功响应示例

{
  "success": true,
  "data": {
    "inserted": 1,
    "updated": 1,
    "skipped": 0,
    "errors": []
  }
}

含跳过行的响应示例

{
  "success": true,
  "data": {
    "inserted": 2,
    "updated": 0,
    "skipped": 1,
    "errors": ["第 3 行：缺少公司代码"]
  }
}

错误示例

// 未启用 wework_partner，或调用方 Key 未获授权 → 403
{ "success": false, "message": "开放 API「合作客商写入」未在系统设置中启用" }
{ "success": false, "message": "当前 API Key 未被授权调用「合作客商写入」接口" }

// rows 缺失/非数组，或超过 5000 行 → 400
{ "success": false, "message": "缺少 rows 数组" }
{ "success": false, "message": "单次最多导入 5000 行" }

企微绩效议题同步 WEWORK QA

GET /api/v1/wework/qa/issues

供外部系统（如部门管理系统）轮询拉取已评分的企微绩效议题，写入自有业务库。鉴权与 Chat / 知识库相同（X-Customer-Code + X-API-Key），无需 IP 白名单。

查询参数（列表）

列表按 sync_at ASC, id ASC 排序，便于增量游标推进。响应 meta 含 page、limit、total、retention_from（生效保留起始日）；传入 sync_since 时另回显 meta.sync_since。

列表响应 data[] 字段

列表响应示例

{
  "success": true,
  "data": [
    {
      "id": 12345,
      "company_name": "示例科技有限公司",
      "company_status": "已合作",
      "summary": "客户反馈产品无法登录",
      "start_time": "2026-06-24T10:30:00",
      "customer_name": "张三",
      "status": "resolved",
      "score_total": 85,
      "assess_status": "success",
      "primary_staff_name": "李四",
      "staffs": [
        { "name": "李四", "effective_reply_count": 3 },
        { "name": "王五", "effective_reply_count": 1 }
      ],
      "created_at": "2026-06-24T10:35:00",
      "sync_at": "2026-06-24T10:40:00"
    }
  ],
  "meta": {
    "page": 1,
    "limit": 50,
    "total": 128,
    "retention_from": "2026-05-25",
    "sync_since": "2026-06-24T10:00:00"
  }
}

推荐同步流程

1. 首次全量：不传 sync_since，按 page 分页直至 data 为空；每条以 id upsert。
2. 增量轮询（建议 5–15 分钟）：sync_since = 上次 max(sync_at) - 1 分钟（重叠防漏）；同一 id 再次出现则 UPDATE。
3. 停服恢复：沿用旧 sync_since 即可补回期间变更。
4. 多页：同一 sync_since 下若 total > limit，继续 page=2,3,... 直至拉完本批。

请求示例（增量拉取）

curl -G "https://agent.likelic.com/api/v1/wework/qa/issues" \
  -H "X-Customer-Code: your_customer_code" \
  -H "X-API-Key: sk-your-api-key-here" \
  --data-urlencode "sync_since=2026-06-24T10:00:00" \
  --data-urlencode "page=1" \
  --data-urlencode "limit=100"

单条详情 GET /api/v1/wework/qa/issues/:id

GET /api/v1/wework/qa/issues/:id

返回字段与列表项相同，用于按 ID 补拉或校验。路径参数 :id 为议题 ID。

curl "https://agent.likelic.com/api/v1/wework/qa/issues/12345" \
  -H "X-Customer-Code: your_customer_code" \
  -H "X-API-Key: sk-your-api-key-here"

成功返回 { "success": true, "data": { ... } }；不存在、未评分或超出保留期返回 404。

错误码说明

错误响应格式

{
  "success": false,
  "message": "具体错误描述"
}

频率限制

为保障服务稳定性，每个 API Key 拥有独立的频率限制配置。系统在认证通过后，根据该 Key 的设定进行限流：

限流规则

限流响应头

每次 API 请求的响应中都会包含以下 Headers，方便客户端感知当前额度：

最佳实践

安全建议

调用建议