集成指南

把 Builder 产出的 practice agent_id 嵌进已有应用（小程序、H5、自有后端）。
写法对齐：腾讯云 IM「前提条件 → 分步接入 → 跑通测试」；不是从零讲概念。

若还没有 agent_id，先完成 快速开始。

---

前提条件

项	要求
已 provision	持有稳定 agent_id（同名幂等，勿每次新建不同名）
API 基址	测服优先；客户端勿写死生产 /api
Token 归属	服务端持有用户/服务 token；前端只调你自己的 BFF，或使用既有小程序会话体系

---

路径 A · 母婴馆小程序（学员主路径）

与现网一致：改环境里的练习 Agent ID，走测服。

1. 用 Builder / SDK 拿到 agent_id。
2. 在小程序配置（如 src/config/env.js）写入：
   • babyAgentId = 该 agent_id
   • USE_TEST_API = true（或等价测服开关）
3. 开发态打开会话，发一句主路径测题，确认进链回复。

更细的学员向对接说明由教学平台 / 教练发放。手册摘要见 4. 接入与集成。

---

路径 B · 自有后端调 Chat

POST {BASE}/api/agents/{agent_id}/chat
Authorization: Bearer <token>
Content-Type: application/json

注意	说明
agent_id	必须是你的 practice Agent；不要写官网小悦 ID
会话	按现网约定传 conversation / 消息体（以 OpenAPI /docs 为准）
密钥	Token 放服务端；勿打进前端 bundle

先用 curl / Postman 打通一条，再写业务封装——与 Dify「先第一条调用再分类型」同序。

---

路径 C · 知识库 / 自有 HTTP 插件（G3）

kb = client.create_knowledge(name="业务FAQ", description="学员自有材料")
client.ingest_knowledge_text(kb.knowledge_base_id, content="……", title="faq.txt")

plugin = client.register_http_plugin(
    name="my_catalog_search",
    url="https://学员自己的API/search",  # 或相对路径 /api/...
    method="GET",
)

client.attach(
    agent_id=agent_id,
    knowledge_base_ids=[kb.knowledge_base_id],
    mounted_plugins=[plugin.name],
    knowledge_rag_enabled=True,
)

平台不提供业务 API；只提供注册与挂载。图内也可用 http 节点直调（见 节点参考）。

---

路径 D · CI / 脚本重复灌装

同名 agent_name → 幂等更新。断言 visibility == practice 与 entrypoint。

---

路径 E · Cursor / IDE（AI 代调）

适合「人写意图，AI 调接口」：

1. 配置 MCP：见 构建应用 · MCP。
2. 把规格（规格模板）交给 AI。
3. AI 调 builder_provision，把返回的 agent_id 交回你接路径 A/B。

硬约束与扣子/我们架构一致：只打 Builder，禁 seed，禁改 production。

---

集成验收清单

• [ ] 测服基址正确，未误打生产
• [ ] agent_id 来自 Builder，且在控制台「我的练习」可见
• [ ] 客户端主路径试聊通过
• [ ] Token / 密钥未进公开仓库

---

下一步

目标	文档
换行业、自带图、MCP 细节	构建应用
字段与错误	API 参考