嵌入智能体

把一个实时的 Buda 智能体直接呈现给你的用户——托管 iframe URL 或原生嵌入令牌，全程无需暴露你的 API 密钥。

让你的用户用上真正的智能体，又不暴露你的密钥。 你的后端签发一个短期嵌入凭证，作用域限定在一个会话和一个外部用户上；前端只用这个凭证与 Buda 通信。你的 sk_ API 密钥永远不离开你的服务器。

它有两种形式：

iframe URL（/embed-urls）——一个现成的、由 Buda 托管的对话界面，你只需把它放进 <iframe>。
原生令牌（/embed-sessions）——一个短期令牌，供你自己的界面（移动应用、小程序、扩展程序）调用嵌入 JSON 端点。

两者都在服务端用你的 API 密钥创建。两者都会过期。

iframe 与原生令牌的对比

	iframe URL（`/embed-urls`）	原生令牌（`/embed-sessions`）
你得到	一个完整的 `embedUrl`，用作 iframe 的 `src`	一个 `token` 加上嵌入 API 的 URL
界面	由 Buda 托管的对话页面	由你自行构建对话界面
最适合	网站、门户、后台管理面板	移动应用、小程序、扩展程序
前端调用	无（托管页面已处理）	`/api/v1/embed/chat-sessions/{sessionId}`

切勿直接 iframe /api/v1/embed/...——那些是 JSON API，不是页面。只有返回的 embedUrl 才适合用作 iframe 的 src。

生成嵌入 URL（iframe）

从你的后端签发 URL

curl -X POST https://buda.im/api/v1/spaces/YOUR_SPACE_ID/agents/YOUR_AGENT_ID/embed-urls \
  -H "Authorization: Bearer sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "externalUserId": "customer-123",
    "displayName": "Kelly",
    "ttlSeconds": 3600,
    "mode": "chat"
  }'

响应中包含 embedUrl、sessionId 和 expiresAt：

{
  "embedUrl": "https://buda.im/embed/api-claw/SESSION_ID#token=SHORT_LIVED_TOKEN",
  "sessionId": "SESSION_ID",
  "expiresAt": "2026-05-26T12:00:00.000Z"
}

把它用作 iframe 的 `src`

<iframe
  src="https://buda.im/embed/api-claw/SESSION_ID#token=SHORT_LIVED_TOKEN"
  title="Buda Agent"
  allow="microphone"
  style="width: 400px; height: 600px; border: 0;"
></iframe>

令牌承载在 URL 的 哈希片段（hash fragment） 中，因此它不会随首次页面请求被发送到服务器——托管页面在浏览器中读取它，并仅将其用于嵌入 JSON 调用。

生成原生令牌

对于你完全掌控的界面，签发一个会话并只下发令牌：

curl -X POST https://buda.im/api/v1/spaces/YOUR_SPACE_ID/agents/YOUR_AGENT_ID/embed-sessions \
  -H "Authorization: Bearer sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "externalUserId": "wechat-openid-oABC123",
    "displayName": "Kelly",
    "ttlSeconds": 3600,
    "mode": "chat"
  }'

只向客户端返回 token、sessionId 和嵌入 API 的 URL。随后客户端用该令牌发送消息并轮询回复：

# 发送一条消息
curl -X POST https://buda.im/api/v1/embed/chat-sessions/SESSION_ID/messages \
  -H "Authorization: Bearer EMBED_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "message": "How do I reset my device?", "mode": "chat" }'

# 轮询智能体回复
curl https://buda.im/api/v1/embed/chat-sessions/SESSION_ID \
  -H "Authorization: Bearer EMBED_TOKEN"

令牌有效期与外部用户

externalUserId（必填）——你自己为终端用户分配的 ID（客户 ID、设备 ID 或微信 openid）。Buda 用它来标记会话；终端用户无需 Buda 账户。
ttlSeconds——令牌的有效时长。最小 60，最大 86400（24 小时），默认 3600（1 小时）。
sessionId——传入一个已有的会话 ID 以延续对话；省略它则开启新会话。
mode——提示模式（chat、agent、thinking 或 build-app）。

令牌过期后，从你的后端签发一个新的。

安全

把 sk_ 密钥留在服务端。 只有短期嵌入凭证才应到达浏览器或设备。
按用户限定作用域。 一个嵌入凭证映射到一个 externalUserId 和一个会话——它无法触及你其他的空间或智能体。
让它过期。 使用尽可能短的 ttlSeconds 并按需刷新，而不是签发长期令牌。
令牌与会话绑定。 用于其他 sessionId 的令牌会被以 403 拒绝。

嵌入智能体

iframe 与原生令牌的对比

生成嵌入 URL（iframe）

从你的后端签发 URL

把它用作 iframe 的 `src`

生成原生令牌

令牌有效期与外部用户

安全

相关内容

API Claw（爪）

身份认证

REST API

On this page