Agent 访问密钥与网站嵌入

将配置好的 Agent 对外暴露给业务后端或网站访客:既可以签发只限调用单个 Agent 的专属 API 密钥,也可以开启免登录公开链接与网站聊天气泡。控制台界面操作见分享、公开访问与网站嵌入。

四种调用入口与运行身份

组织内创建的 Agent 在落库时自动获得独立的服务身份(归属该 Agent,不随创建成员离职失效)。无论从哪种入口进入,运行时都以该 Agent 的服务身份访问已授权的知识库与外部连接;区别在于谁有资格调用以及附加的安全边界:

入口 鉴权方式 受 audience 约束 典型地址 / 端点
工作区内对话 成员登录会话 / 组织 API Key 是(maintainers 或 org) /workspace/agents/{agent_id}/chats
Agent API 密钥 Authorization: Bearer <AGENT_KEY> 否(独立开关,无需开启公开访问) POST /api/v2/bots/{agent_id}/chats 与 Turn 接口
公开链接 免登录(自动签发访客会话 Token) 否(由访问点 enabled + 组织公开开关控制) /a/{widget_id}
网站嵌入 免登录(与公开链接共用访问点) 否(与公开链接一致) widget.js 气泡脚本或 /embed/widgets/{widget_id} iframe

只有独立 Agent(visibility = standalone)支持访问点与 Agent API 密钥;具有组织管理权限的 Agent 禁止开启公开访问或签发公开调用权限。

Agent API 密钥(三层最小权限隔离)

当你只想把某一个 Agent 暴露给外部后端(而不想把整个组织的 API Key 交出去)时,使用 Agent API 密钥。管理接口仅接受浏览器会话或 OAuth(不接受 API Key),每个 Agent 最多 20 把密钥:

使用 Agent API 密钥调用时,服务端强制实施三层限制:

  1. 接口白名单:仅放行所属 Agent 的创建会话(POST /api/v2/bots/{agent_id}/chats)、创建/查询 Turn(POST/GET /api/v2/agent/chats/{chat_id}/turns)、查询单轮快照与取消 Turn;访问 MCP、知识库或密钥管理接口一律返回 403。
  2. 身份资格校验:每次请求实时检查 Agent 服务身份处于启用状态,且其角色不含组织管理权限。
  3. 会话严格隔离:每条 Chat 绑定创建它的密钥,密钥 A 无法读取密钥 B、公开访客或工作区成员的会话记录。

公开链接、网站嵌入与匿名访客边界

公开链接和网站嵌入共用该 Agent 唯一的访问点(通过 GET / PUT / DELETE /api/v2/bots/{agent_id}/access 管理,同样只接受浏览器或 OAuth 会话)。前提条件:所属组织已开启公开访问(organization.public_enabled = true),且 Agent 服务身份已启用、不含组织管理权限。

<!-- 方式 1:右下角聊天气泡脚本 -->
<script src="https://apemind.ai/widget.js" data-widget="<WIDGET_ID>" async></script>

<!-- 方式 2:内嵌 iframe -->
<iframe src="https://apemind.ai/embed/widgets/<WIDGET_ID>" style="width:100%;height:640px;border:0;"></iframe>

嵌入脚本和 iframe 不限制来源域名(历史字段 allowed_domains 仅为兼容保留,不参与拦截)。需要按身份限制访问时,请改用工作区内使用或 Agent API 密钥。

匿名访客能力矩阵与 platform_access 真实行为

能力 工作区成员 匿名访客(公开链接 / 嵌入)
平台内置知识库工具 按 Agent 配置 按 Agent 配置(MCP 模式下挂载默认内置工具集)
代码模式沙箱与平台临时 Key(platform_access) 开启 workspace 时启用并按轮签发临时 Key 按 Agent 配置同步启用:当 Agent 开启代码模式(platform_access: true)时,访客轮次同样在沙箱内运行,并按轮签发受限于 Agent 自身服务身份与本轮超时的临时平台 Key
Agent 挂载的技能与连接 按 Agent 配置 按 Agent 自身服务身份授权执行
成员私有第三方 MCP 服务 按 Agent 配置 不可用(服务端自动剥离)
附件上传 可用 不可用
推理过程与工具调用展示 可见 默认隐藏;仅在访问点 appearance 中显式开启 show_reasoning / show_tool_calls 时返回脱敏投影(工具只显示分类与状态,不含参数与输出)
开启公开访问前核对 platform_access

访问点响应中的只读字段 platform_access 直接反映该 Agent 是否处于代码模式(即启用了 spec.capabilities.workspace,且非历史 platform_access: false 兼容配置)。虽然平台已禁止带组织管理权限的 Agent 公开,且临时 Key 无法发起嵌套代码模式调用,但只要 platform_access: true,匿名访客仍可通过提示词让 Agent 以自身服务身份调用其获授权的平台接口或外部连接。对外公开的客服/文档类 Agent,建议保持知识库只读并关闭非必要的写连接与沙箱能力。

访客限流与总用量控制

匿名公开接口内置两层固定令牌桶限流,避免单个访客耗尽资源:

超限时返回 HTTP 429 与 Retry-After 响应头,且单个访客耗尽额度不影响其他访客。如果需要为某个公开 Agent 或 Agent API 密钥单独设置总用量上限,平台管理员可以在「平台管理 › 配额与限流」中针对该 Agent 的服务身份配置 api.chat_turn 与模型 Token 限流策略,调整即时生效无需重新发布。

在多级反向代理或纯内网环境中,客户端真实 IP 解析依赖 FORWARDED_ALLOW_IPS 配置,运维配置方法见容量规划、高可用与会话亲和。

CLI 快速管理访问点

通过 OAuth 登录的 apemind CLI 可直接管理访问点配置(--public on 与 delete 需显式 --confirm,所有写命令支持 --dry-run):

# 查看访问点状态(含 widget_id、org_public_enabled 与 platform_access)
apemind agent access get "${AGENT_ID}" --workspace "${APEMIND_ORG_ID}"

# 开启公开访问并定制欢迎语
apemind agent access set "${AGENT_ID}" --public on --title "产品助手" --confirm

# 下线并立即关闭所有已打开的访客会话
apemind agent access delete "${AGENT_ID}" --confirm

下一步