DOCS · 官方文档

把你的业务系统接进 Agent 中枢

这份文档同时面向使用者和开发者。使用者先理解业务场景如何拆成中枢配置，开发者再按接口契约、工具源、SDK、签名和部署文档完成技术接入。

QUICKSTART

先选评估路径

最快了解百灵中枢的方式是在线体验：不用安装、不需要模型 key，注册后直接进入自己的独立租户，看路由、工具源、任务、审计和平台能力如何组织。需要验证完整技术闭环时，再用 Docker Demo 在自己的机器上启动中枢、MySQL 和 demo 业务系统。

1. 在线体验

适合产品评估、后台心智验证和多租户能力预览。注册后进入自己的租户控制台；公开在线环境不建议接入真实生产系统或填写生产密钥。

进入在线体验

2. Docker Demo

适合技术验证。它会启动完整本地环境，跑通业务系统暴露工具、Agent 调工具、业务侧审批、trace 和 smoke 验证。

查看 Docker Demo

第一次评估先读使用者指南

如果你还没确定自己的业务应该从哪个场景接入，先看「使用者指南」。它用业务负责人和产品经理能理解的方式说明：百灵中枢解决什么问题、后台每个菜单对应什么配置、配完后把什么交给开发者。

阅读使用者指南

bailinghub
$ docker compose up --build

完成 Console: http://localhost:18900/console/
完成 Demo route: demo_support
完成 Demo business tools: /.well-known/bailing/tools.json

全新 Ubuntu/Debian 服务器可以用一键安装脚本启动 Docker Demo：curl -fsSL https://www.bailinghub.com/install.sh | sh。脚本只封装 Docker 安装、开源分发包下载、生成 .env 和 docker compose up -d --build，完整说明见 Docker Demo 文档。

完整 demo 业务系统、审批闭环、故障排障和 smoke 流程见 Docker Demo 文档。

1
建模型凭证。在控制台「模型凭证」填 OpenAI 兼容端点与 key。配置完成后，内置 llm 调度目标即可使用。
2
建触发路由。在「触发路由」定义业务场景、调度目标、会话策略、知识、工具、送达和预算。
3
发接入方钥匙。在「接入方」创建业务系统 token，并限定它能触发哪些路由。
4
触发任务。业务系统调用 POST /run，拿到 job_id 后轮询 GET /jobs/{job_id}，或配置 callback / delivery 接收结果。
MENTAL MODEL

先理解五个对象

路由

一个业务场景。它决定请求进来后用哪个大脑、怎么续聊、注入哪些知识、允许哪些工具、结果送往哪里。

接入方

一个业务系统的钥匙。中枢用它做鉴权、路由白名单、限速与预算约束。

调度目标

一个可被路由选择的大脑插座。可以是内置 LLM，也可以是远端 executor 或后续更多适配器。

工具源

业务系统暴露给 Agent 的可调接口清单。中枢把它编译成统一 ToolDefinition，再套治理闸门。

SDK

业务侧生成工具 spec、签发票据、验签、验 callback、实现授权探针和主动调中枢的接入包。当前覆盖 PHP、Node、Python、Java、Go、.NET；其他语言按同一契约接入。

知识库

领域资料的检索入口。路由选择知识库后，中枢在派发前检索并注入上下文。

对话总账

中枢自己的状态库。消息、trace、审计、审批和任务记录都在这里，Agent 会话只是可重建缓存。

ROUTES

触发路由：把一个业务场景配完整

后台「触发路由」页负责定义 Agent 任务的编排规则。业务侧只需要传一个稳定的 route，中枢负责选择目标、装配上下文、执行工具治理、记录 trace，并把结果回送。

基础与大脑

配置场景标识、展示名称、调度目标、模型凭证、系统提示词和预算。场景标识是业务调用时的稳定路由 key。

知识

选择知识库和检索参数。知识故障按降级处理，不阻断任务主流程。

送达

结果可通过轮询、callback webhook 或送达适配器返回业务侧。callback 建议开启 HMAC 验签。

工具治理

路由只暴露被 allow 白名单命中的工具 scope。高风险工具进入审批，批准后只放行对应调用快照。

字段说明建议
route业务调用使用的场景标识。用稳定、短小、可读的英文名，例如 order_assistant。
target调度目标。默认可使用 llm。先用内置 LLM 跑通，再按需接远端 executor。
session_policy会话策略：新会话、按业务 key 续聊、固定会话。客服、订单跟进等多轮场景使用按 key 续聊。
knowledge路由级知识检索配置。只给需要资料增强的路由开启，避免无意义成本。
tools路由可见的工具源和 scope 白名单。按最小权限开放，先只开放只读查询工具。
HTTP API

业务系统与中枢的接口契约

详细字段说明、回调载荷和机器可读 schema 已拆到 API 契约 子页。这里保留最小调用形状，方便第一次接入快速定位。

业务系统只通过稳定 HTTP 契约和中枢对话。不要 import 中枢代码，也不要让中枢直接依赖业务库结构。

POST/run
{
  "request_id": "order-10001-ai-001",
  "route": "order_assistant",
  "input": "帮我分析这个订单为什么迟迟未发货",
  "metadata": {
    "tenant_id": "t_100",
    "operator_uid": "u_42",
    "order_id": "SO20260701001"
  },
  "callback": "https://biz.example.com/ai/callback"
}
GET/jobs/{job_id}
{
  "id": "job_...",
  "status": "queued | running | done | error",
  "result": { "summary": "...", "detail": {} },
  "error": null
}
POST业务侧 callback URL
X-Bailing-Signature: sha256=<hmac>
X-Bailing-Timestamp: 1782912000

{
  "job_id": "job_...",
  "route": "order_assistant",
  "status": "done",
  "result": { "summary": "..." }
}

调用方鉴权使用接入方 token。callback / delivery 的验签密钥由路由或接入方配置提供，业务侧必须先验签再消费结果。

约束说明
request_id业务侧幂等键。同一接入方下重复提交同一个 request_id 不应产生重复任务。
metadata业务上下文，只消费对象形态。不要把 JSON 字符串塞进 detail / metadata，避免不同语言二次解析不一致。
callback适合 fire-and-forget 场景。需要强一致展示时，业务侧仍应按 job_id 做兜底查询。
TOOLS

工具源：让 Agent 安全调用业务接口

工具源完整接入、OpenAPI 扩展字段、SDK 与验签说明已拆到 工具源文档 子页。

工具源不是把所有接口丢给大模型，而是把业务明确允许的接口声明成 ToolDefinition。中枢统一做白名单、风险、限流、审计、审批和签名出口，业务侧继续负责最终权限裁决。

OpenAPI + ACC

业务系统发布 OpenAPI，并用 x-agent-capability 声明 scope、risk、subject、approval、execution 等 Agent 触达治理语义。

SDK 方式

当前 SDK 覆盖 PHP、Node、Python、Java、Go、.NET，产出同一份工具 spec，并提供工具调用验签、callback 验签、票据签发、授权探针和 HubClient。

Agent 友好工具设计

从查询、预检、申请、真实执行、批量执行五类工具开始拆，不需要把后台 CRUD 原样全部暴露给 Agent。

自动刷新

工具源可以配置 spec URL。业务新增接口后，发布新的 tools.json，中枢刷新后自动对账并审计变化。

业务授权

中枢负责 reach，业务负责 authority。工具请求带 X-Bailing-On-Behalf-Of，业务按自家权限表裁决。

最小 tools.json 形状

GET/.well-known/bailing/tools.json
{
  "openapi": "3.1.0",
  "info": { "title": "订单系统工具", "version": "1.0.0" },
  "paths": {
    "/orders/{id}": {
      "get": {
        "operationId": "order.get",
        "summary": "查询订单",
        "x-agent-capability": {
          "version": 1,
          "enabled": true,
          "scope": "order.read",
          "risk": { "level": "low" },
          "subject": { "required": true }
        }
      }
    }
  }
}

业务侧验签与授权

POST业务工具接口
X-Bailing-Signature: sha256=<hmac>
X-Bailing-Timestamp: 1782912000
X-Bailing-Tool: order.get
X-Bailing-Job-Id: job_...
X-Bailing-On-Behalf-Of: u_42

不要只验签就放行。验签只能证明请求来自中枢，不能证明这个用户此刻有权限操作这条业务数据。业务系统必须用 on_behalf_of 进入自己的权限表做二次裁决。

SDK 与任意语言接入

当前 SDK

PHP、Node、Python、Java、Go、.NET SDK 都围绕同一套 wire 契约提供 spec 生成、工具调用验签、callback 验签、票据签发、授权探针和 HubClient。

其他语言

不需要等待官方 SDK：只要能发布 OpenAPI + x-agent-capability ACC 声明，并实现 HMAC 验签，就能作为工具源接入。

GETPHP SDK 下载
curl -O {中枢地址}/connect/bailing-connect-php.tgz
curl -O {中枢地址}/connect/bailing-connect-php7.tgz

完整 SDK 用法见 SDK 文档。SDK 是开发便利层，不是接入前提；稳定契约始终是 OpenAPI + ACC（x-agent-capability）+ HMAC 验签。

如果你正在判断 MCP Server、Agent Runtime、审批系统、共享执行控制和业务后端各自应该承担什么，请阅读 MCP 选中工具之后，到安全执行之间还缺什么？

KNOWLEDGE

知识库：把业务资料注入路由

知识库入库、查询和删除接口已拆到 知识库文档 子页。

知识库用于把文档、FAQ、制度、商品资料等变成可检索上下文。业务侧可以通过推送 API 同步资料，也可以在后台配置数据源连接器拉取。

PUT/kb/{kb_id}/docs/{source_key}
{
  "title": "售后退款规则",
  "content": "markdown 或纯文本内容",
  "metadata": {
    "tenant_id": "t_100",
    "source": "help-center"
  }
}
GET/kb/{kb_id}/docs
{
  "items": [
    { "source_key": "refund-rule", "status": "ready", "chunk_count": 8 }
  ]
}
DELETE/kb/{kb_id}/docs/{source_key}
{ "ok": true }

知识库 token 仍然来自接入方。建议每个业务系统只拿自己需要的知识库权限，路由再决定是否检索注入。

APPROVALS

审批意图：高风险动作交给业务侧裁决

审批意图投递、业务侧裁决和 args_hash 快照约束已拆到 审批意图文档 子页。

审批不是必须发生在中枢后台。中枢负责暂停高风险工具调用、固化参数快照、生成审批意图，并接收业务侧的批准或驳回决策。业务侧负责谁能审、在哪审、走几级审。

POST业务侧审批意图接收 URL
{
  "kind": "tool_approval_request",
  "approval_id": 123,
  "job_id": "job_...",
  "route": "store_ops",
  "subject": "tenant_1:user_1001",
  "provider": "demo-business",
  "tool": "inventory.adjust",
  "scope": "store.inventory.write",
  "risk": "high",
  "args": { "store_id": 8, "sku_id": 10086, "delta": -20 },
  "args_hash": "sha256:..."
}
POST/approvals/{approval_id}/decision
{
  "kind": "tool_approval_decision",
  "schema_version": "bailing.approval-decision.v1",
  "approval_id": 123,
  "job_id": "job_...",
  "args_hash": "sha256:...",
  "decision_id": "oa:approval:9001",
  "decision": "approved",
  "approver": "user_2002",
  "comment": "确认处理"
}

批准时必须回传 args_hash。中枢只放行已冻结的同一份调用快照，业务侧审批期间如果参数被改动，本次批准不应生效。

SECURITY

安全边界

中枢管 reach

哪些工具能被 Agent 看见、哪些路由能调用、频率和预算是多少，由中枢统一治理。

业务管 authority

某个用户能不能操作某条数据，由业务系统按自己的权限、租户、状态机做最终裁决。

审批不绑定中枢后台

高风险动作会形成审批意图。生产环境可以把审批交给业务侧流程，中枢控制台只是兜底车道。

trace 一等公民

任务、工具调用、审批、模型调用、送达都进入统一 trace，方便调试和审计。

OPERATIONS

部署与运维

生产部署、密钥注入、集中限速、DB 调度和观测检查清单已拆到 部署运维文档 子页。

生产环境推荐 Node 22 + MySQL，敏感配置通过环境变量或密钥管理器注入。MySQL 后端启用集中限速、任务账本、审计、审批意图、知识库和控制台配置。

生产配置

设置 BAILING_ENV=production，按 .env.example 注入数据库、服务 token、模型凭证、告警与对象存储配置。

数据库结构

执行 npm run db:init 初始化和同步结构。SQL 文件按序号演进，结构版本可在 /version 查看。

控制台账号

执行 npm run admin:create -- admin 创建后台账号，登录 /console/ 做路由、凭证、接入方、工具源配置。

健康检查

GET /health 返回服务状态，GET /version 返回应用版本、契约版本与数据库结构版本。

控制台配置，官网读文档

后台页面里的「开发文档」入口会跳转到本页对应章节。控制台负责配置和调试，官网负责完整说明和接口阅读。

看触发路由 看工具源 看知识库