智能体嵌入
嵌入的限制与错误
嵌入智能体的各项上限、错误码，以及目前不支持的能力。
本页列出嵌入时会碰到的上限和错误码。标注「策略」的值由你为智能体配置的嵌入策略决定，其余是平台固定值。
上限
签发令牌
| 项目 | 限制 |
|---|---|
令牌有效期 ttl_seconds | 60 到 3600 秒。不传时用策略的默认值，且不能超过策略的有效期上限（ttl_max_seconds，同样在 60 到 3600 之间）。 |
external_user_id | 1 到 128 个字符，只能包含字母、数字和 _ . : @ -。 |
system_message | 文本块总计不超过 8192 字节（UTF-8）。 |
metadata | 最多 16 个键；键 1 到 64 个字符，值为不超过 512 个字符的字符串。 |
会话预算 budget_cents | 0 到策略的会话预算上限；不传时用策略的默认值。 |
allowed_origins | 必须是策略 allowed_origins 的子集。 |
策略
| 项目 | 限制 |
|---|---|
来源白名单 allowed_origins | 最多 50 条。只接受 https 来源；通配写法 https://*.example.com 只匹配一级子域名，不含端口。开启 allow_localhost 后额外允许 http://localhost 和 http://127.0.0.1。 |
每个终端用户的活跃会话数 max_active_sessions_per_user | 1 到 100。只计运行中的会话，不计空闲的历史会话。 |
每个终端用户每分钟请求数 per_user_rate_per_min | 1 到 600。 |
被封禁的终端用户 blocked_end_users | 最多 1000 个。 |
月度上限 monthly_cap_cents | 以分计；null 表示不设上限。 |
触顶动作 on_cap | stop_new_sessions：拒绝新建会话，返回 EMBED_MONTHLY_CAP_REACHED；alert_only：只告警，不拦截。 |
月度花费按 UTC 自然月统计。
会话与消息
| 项目 | 限制 |
|---|---|
| 附件 | 每条消息最多 5 个，单个不超过 10 MB。只支持内联：PNG、JPEG、GIF、WebP 作为图片，PDF、TXT、MD 作为文档，不会上传为会话文件。 |
推荐问题 startScreen.prompts | 最多显示 4 个。 |
| 会话标题 | 不超过 500 个字符。 |
| 创建会话时的初始事件 | 最多 50 条，只能是纯文本的用户消息。 |
| 会话预算 | 达到令牌上的 budget_cents 后，会话不再接受新的工作，只接受工具确认和中断。 |
错误
错误从两处到达页面：接口返回的错误体，以及 Kit 自身产生的错误。传输错误通过 praxis.error 事件的 detail 交给你，字段为 code、status、retryable 和 message；会话加载或发送失败可能只有 message，按错误码分支前先检查 code 是否存在。
EMBED_* 错误码
| 错误码 | HTTP | 含义 | 可重试 | 建议处理 |
|---|---|---|---|---|
EMBED_TOKEN_EXPIRED | 401 | 令牌已过期。 | 否 | Kit 会自动调用 getToken 换新令牌并重试一次；持续出现说明你的令牌服务返回了已过期的令牌。 |
EMBED_TOKEN_REVOKED | 401 | 令牌已被吊销。 | 否 | Kit 不再刷新，对话进入终止状态。让用户重新进入页面，由你的服务重新签发。 |
EMBED_ORIGIN_NOT_ALLOWED | 403 | 页面来源不在白名单内。 | 否 | 把页面来源加入策略的 allowed_origins，并确认签发令牌时的 allowed_origins 包含它。 |
EMBED_USER_BLOCKED | 403 | 该终端用户被封禁。 | 否 | 在策略的 blocked_end_users 中确认并移除，或提示用户联系你。 |
EMBED_RATE_LIMITED | 429 | 每分钟请求数或同时运行的会话数超限，或达到匿名每日会话上限。 | 是 | 请求限流时稍后重试；并发超限时等待运行结束或中断运行，或调高 max_active_sessions_per_user。归档空闲历史不会释放运行名额；每日上限在下个 UTC 日恢复。 |
EMBED_BUDGET_EXHAUSTED | 402 | 会话预算耗尽，或达到匿名每日花费上限。 | 否 | 会话预算耗尽时开始新会话，或调高签发时的 budget_cents；匿名每日上限需等待额度恢复。 |
EMBED_MONTHLY_CAP_REACHED | 402 | 月度上限已到，且触顶动作为 stop_new_sessions。 | 否 | 调高 monthly_cap_cents，或把 on_cap 改为 alert_only；下个 UTC 月自动恢复。 |
EMBED_FIELD_NOT_ALLOWED | 400 | 创建会话时带了嵌入令牌不允许的字段，或初始事件格式不被允许；也用于策略不允许的 agent_override。 | 否 | 只传标题、时区和纯文本的初始用户消息。 |
相关的通用错误码
| 错误码 | HTTP | 含义 | 可重试 |
|---|---|---|---|
INVALID_PARAMS | 400 | 请求参数不合法，信息会指出是哪个字段，例如 Invalid external_user_id、system_message exceeds 8192 bytes。 | 否 |
NOT_FOUND | 404 | 授权、策略或请求的资源不存在或不可访问；Hosted 凭证无效、过期或已使用也返回此码。 | 否 |
UNAUTHENTICATED | 401 | 凭证缺失或无效，包括已停用的可公开 key。 | 否 |
AGENT_NOT_FOUND / SESSION_NOT_FOUND | 404 | 找不到智能体或会话。 | 否 |
SESSION_FORBIDDEN / PERMISSION_DENIED / READ_ONLY | 403 | 调用方无权执行此操作；终端用户的资源隔离也可能以 404 隐藏资源。 | 否 |
INVALID_STATE / SESSION_CONFLICT / AGENT_ARCHIVED / SESSION_ARCHIVED | 409 | 智能体或会话当前状态不允许此操作。 | 否 |
INVALID_PAGE_TOKEN | 400 | 分页或事件游标无效。 | 否 |
EVENT_CONTENT_UNAVAILABLE | 404 | 事件内容不可用。 | 否 |
EVENT_CONTENT_CORRUPT | 500 | 存储的事件内容无法正确读取。 | 否 |
UPSTREAM_UNAVAILABLE | 502 | 上游服务不可用。 | 是 |
INTERNAL | 500 | 未分类的服务端错误。 | 否 |
Kit 自身产生的错误码
这些错误没有对应的接口响应，status 为 0 或接口状态码。
| 错误码 | 含义 | 可重试 |
|---|---|---|
network_error | 网络请求失败。 | 是 |
http_error | 响应不是已知的错误体。status 为 429 或 5xx 时可重试。 | 视状态码 |
invalid_token | getToken 返回了空令牌。 | 是 |
invalid_response | 响应不是合法 JSON，或历史分页没有前进。 | 否 |
invalid_stream | 事件流不是 SSE，或某条数据不是合法 JSON。 | 否 |
stream_disconnected | 事件流在没有取消的情况下中断。Kit 最多重连 5 次。 | 是 |
event_cursor_not_found | 历史中找不到续传位置。 | 否 |
callback_error | 事件回调抛出了异常。 | 否 |
aborted / disposed | 操作被取消，或元素已移除。 | 否 |
getToken 失败时，Kit 按 1、2、4 秒的间隔最多重试 3 次，之后令牌状态变为过期并发出 praxis.error。
暂不支持
以下能力在嵌入里尚未提供：
- 按消息切换模型
- 工具模式
- 语音输入
- entities、commands、widgets
- 按终端用户的记忆