构建自定义 AI 代理 — Agent API 入门
欢迎来到 Build Custom AI Agents with Agent API。本模块介绍如何通过 REST API 将 Agentforce 集成到您的网站中。我们将涵盖完整的集成流程：启用 Agentforce、创建外部客户端应用并配置 OAuth、获取 Consumer Key 和 Consumer Secret、生成认证令牌、创建代理会话、发送同步和流式消息，以及了解会话生命周期管理和 API 超时等注意事项。
学习目标
完成本模块后，您将能够：
- 描述如何开始使用 Agent API
- 使用 Agent API 启动与 AI 代理的会话
- 管理会话生命周期
开始使用 Agent API
您是一名开发人员，负责将 Agentforce 集成到公司网站上，让 Salesforce AI 代理帮助客户快速获得有用的回复。Agent API 就是答案 — 它通过 REST API 调用简化工作流程并增强用户交互。从高层次看，连接 Agentforce 与 Agent API 需要三个步骤：
- 创建一个 Salesforce 应用用于身份认证
- 生成令牌实现安全 API 访问
- 向代理发起 API 请求
步骤 1：启用 Agentforce 并激活代理
首先，在 Salesforce org 中启用 Agentforce。这是关键前提。启用后，至少需要激活一个代理，该代理将成为 API 调用的目标。
重要提示：Agent API 不支持 "Agentforce (Default)" 类型的代理。必须为 API 集成创建并激活一个自定义代理。
步骤 2：创建外部客户端应用和 OAuth 配置
第二步是在 Salesforce 中创建一个外部客户端应用（External Client App），用于处理 客户端凭证流程（Client Credential Flow）。这是一个服务器到服务器的 OAuth 2.0 流程，无需用户交互，非常适合后端集成场景。在应用配置中启用 OAuth 并为 Agent API 访问配置适当的 OAuth 范围。
步骤 3 和 4：获取凭据和生成令牌
步骤 3 — 获取 Consumer Key 和 Consumer Secret：应用设置完成后，在外部客户端应用配置中找到 Consumer Key 和 Consumer Secret。这些凭据对于认证 API 调用至关重要。
步骤 4 — 创建令牌（Token）：所有 Agent API 调用都需要令牌进行认证。使用 Consumer Key、Consumer Secret 和 Salesforce 域名创建令牌，令牌将在每个 API 请求的 Authorization 头中传递。
发起第一次 API 调用
现在是最令人兴奋的部分 — 真正调用 Agent API。需要收集：Salesforce 域名 URL、创建的令牌、要交互的代理 ID。使用 curl 或 HTTP 客户端创建一个新的代理会话，成功后会收到包含 Session ID 和会话元数据的响应。Session ID 至关重要 — 它是该会话中所有后续消息的基础标识。
同步消息 vs. 流式消息
Agent API 支持两种消息处理模式：
- 同步消息（Synchronous）：完整响应在单次调用中返回。适用于批处理、表单提交等需要一次性获取完整响应的场景。
- 流式消息（Streaming）：响应逐步传递，可在生成过程中向用户显示部分内容。更适合实时聊天对话场景。
无论哪种模式，完成后请关闭会话。
注意事项
在开始构建之前请注意：
- 数据用量：Agent API 使用会影响积分消耗。查看 Generative AI Usage and Billing 文档了解详情。
- API 超时：Agent API 有 120 秒超时限制。超时返回 HTTP 500。对长时间操作建议使用流式模式在超时窗口内接收增量更新。
资源
- Agent API 开发者指南 — developer.salesforce.com/docs/einstein/genai/guide/agent-api.html
- Agent API 参考文档
- Postman Collection: Agent API
- Trailhead: Agentforce 基础