四种调用入口与运行身份
组织内创建的 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 把密钥:
GET /api/v2/bots/{agent_id}/access/keys:列出密钥名称、脱敏前缀后缀与最近使用时间。POST /api/v2/bots/{agent_id}/access/keys:传{"name": "crm-backend"},完整密钥仅在创建响应中返回一次。DELETE /api/v2/bots/{agent_id}/access/keys/{key_id}:立即吊销密钥。
使用 Agent API 密钥调用时,服务端强制实施三层限制:
- 接口白名单:仅放行所属 Agent 的创建会话(
POST /api/v2/bots/{agent_id}/chats)、创建/查询 Turn(POST/GET /api/v2/agent/chats/{chat_id}/turns)、查询单轮快照与取消 Turn;访问 MCP、知识库或密钥管理接口一律返回403。 - 身份资格校验:每次请求实时检查 Agent 服务身份处于启用状态,且其角色不含组织管理权限。
- 会话严格隔离:每条 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,建议保持知识库只读并关闭非必要的写连接与沙箱能力。
访客限流与总用量控制
匿名公开接口内置两层固定令牌桶限流,避免单个访客耗尽资源:
- 单客户端 IP:每分钟 60 次(覆盖创建会话与发起提问)。
- 单访客会话:每分钟 20 次(覆盖发起提问)。
超限时返回 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