选择目标部署提供的集成接口
业务系统调用智能体实例时，可以使用目标部署提供的 Invoke API；自有消息系统需要双向长连接时，可以使用目标部署提供的 WebSocket 接入。文件上传作为 Invoke API 的辅助接口，为调用提供限时文件 URL。生产接入前，以目标部署的 API 调用 页面和交付资料为准，并向平台提供方确认适用版本、兼容范围和弃用通知方式。
接口分类
三类公开接口分别用于智能体调用、消息系统接入和调用文件上传。
| 接口 | 用途 | 外部集成定位 | 使用边界 |
|---|---|---|---|
| Invoke API | 调用一个智能体实例、管理调用任务和上传调用文件 | 业务系统调用 | 使用目标部署中智能体实例 API 调用 页面提供的地址和 Token |
| WebSocket 接入 | 把自有消息系统连接到一个 WebSocket 渠道账号 | 自有消息系统接入 | 使用目标部署提供的协议版本和绑定到渠道账号的 WebSocket Token |
| 媒体上传和读取 | 为 Invoke API 提供 URL 型文件输入 | 调用文件上传 | 文件大小、TTL、MIME 和存储行为取决于部署配置 |
区分接口和能力的调用方向
在一体化智能体运行与协同平台（AgentWorks）中，Invoke API、WebSocket、MCP、用户工具包和子代理连接的对象不同，不能互换使用。
| 机制 | 调用方向 | 用途和边界 |
|---|---|---|
| Invoke API | 业务系统 → AgentWorks 智能体实例 | 发送提示词、继续 API 会话、接收流式响应并处理中断 |
| WebSocket | 自有消息系统 ↔ AgentWorks 渠道账号 | 通过长连接交换消息、工具事件和中断；渠道账号负责把消息路由到智能体实例 |
| MCP | AgentWorks 智能体 → 外部 MCP Server | 发现并调用远程工具、API 或数据资源 |
| 用户工具包 | AgentWorks 智能体 → API 或 WebSocket 调用方 → AgentWorks | 智能体发出工具中断，调用方执行业务操作并返回结果 |
| 子代理 | AgentWorks 主智能体 → 已有 AgentWorks 智能体实例 | 由模型发起异步委托，并通过 后台任务查看状态和结果 |
| A2A | 独立智能体 ↔ 独立智能体 | AgentWorks 不提供 Agent Card 或 A2A 任务端点；不要把 Invoke API、WebSocket 或子代理当作 A2A 兼容接口 |
需要把外部工具提供给 AgentWorks 智能体时，使用 MCP 或用户工具包。子代理只用于委托给已有 AgentWorks 智能体实例。
在外部流程中划分运行责任
能够按照 Invoke API 契约发送请求的业务应用或编排系统，可以把一个 AgentWorks 智能体实例作为流程中的智能体步骤。外部流程通过 Invoke API 提交任务、继续会话并处理中断；AgentWorks 负责执行每次智能体调用。
| 关注点 | AgentWorks 负责 | 外部流程负责 |
|---|---|---|
| 智能体运行 | 按照智能体模板和实例配置调用模型和能力 | 保存业务状态和当前流程步骤 |
| 流程控制 | 在一次运行中调用工具或委托子代理 | 决定固定顺序、条件分支和并行关系 |
| 响应和中断 | 返回内容、流式事件和待处理中断 | 设置重试次数、超时、成本预算和终止条件 |
| 会话和副作用 | 在同一 session_id 下继续智能体对话 | 记录业务副作用，避免重复执行，并保存流程执行与 session_id 的对应关系 |
AgentWorks 提供通用 Invoke API，不提供 LangGraph、ADK 或 CrewAI 的专用适配器。使用这些框架时，保留原有流程和运行环境，由集成方把框架输入转换为 Invoke 请求，并管理状态对应关系、错误处理和跨系统追踪。自有消息系统需要双向长连接时，使用 WebSocket 接入；不要用 WebSocket 代替外部流程的状态管理。
选择 Invoke API
业务系统需要请求/响应、SSE、会话、中断或文件输入时，使用 Invoke API：
POST /api/agents/Invoke
Authorization: Bearer agt_... 或 dbg_...正式 agt_ 绑定一个智能体实例。临时 dbg_ 仅用于调试，并在页面显示的有效期后失效。客户端必须读取响应信封中的 success_response、http_status_code 和 data.reason，不能只判断外层 HTTP 200。
端点和字段见 Invoke API 参考。
选择 WebSocket 接入
自有消息系统需要双向长连接、流式回复、工具事件和中断时，使用 WebSocket 接入。连接采用 Bridge 协议 infini.bridge.v1：
GET /ws/v1
Sec-WebSocket-Protocol: infini.bridge.v1, bearer.<base64url_token>也可以先以 infini.bridge.v1 升级，再在目标部署配置的鉴权超时内发送 In-Band auth。wst_ 只鉴权一个 WebSocket 渠道账号；渠道账号的绑定目标决定消息进入智能体实例还是智能体模板。
创建渠道账号和验证连接见通过 WebSocket 接入智能体；帧字段、鉴权方式、中断、心跳和错误码见 WebSocket API 参考。
只使用目标部署提供的集成接口
外部自动化应使用目标部署明确提供的 Invoke API、WebSocket 接入和文件上传接口，不要捕获并重放控制台页面发出的管理请求。需要批量管理或 CI/CD 能力时，请使用目标部署明确提供的管理接口；如果目标部署没有提供此类接口，请继续通过控制台完成管理操作。
与自定义智能体框架集成
一体化智能体运行与协同平台（AgentWorks）运行在控制台中配置的智能体模板、能力和智能体实例。需要保留 LangGraph、CrewAI 或其他框架的自定义执行循环时，请在外部系统中运行该框架，并通常通过 Invoke API 调用 AgentWorks 智能体实例。如果接入方是需要双向长连接的自有消息系统，可以使用 WebSocket。无论选择哪种接口，外部系统都需要自行管理原有执行循环。