Agentforce APIs 和 SDKs 开发指南

2026-07-15 18

版权

本文内容由阿里云实名注册用户自发贡献，版权归原作者所有，阿里云开发者社区不拥有其著作权，亦不承担相应法律责任。具体规则请查看《阿里云开发者社区用户服务协议》和《阿里云开发者社区知识产权保护指引》。如果您发现本社区中有涉嫌抄袭的内容，填写侵权投诉表单进行举报，一经查实，本社区将立刻删除涉嫌侵权内容。

简介： Agentforce 完整 API 和 SDK 生态指南。涵盖构建工具（Agent Script/DX/Python SDK）、测试工具（Testing Center/DX/Testing API）、对话工具（Agent API/Custom Connections/Mobile SDK/Enhanced Chat），以及 Agent API 深度实战：从创建 External Client App、获取 Token 到启动会话、发送同步/流式消息、处理 Citations、传递 Agent 变量、故障排查全流程。

Agentforce APIs 和 SDKs

功能与 API 总览

Agentforce 提供完整的 API 和 SDK 生态，围绕三大核心活动组织：构建 Agent、测试 Agent 和使用/对话 Agent。

注意：从 2026 年 4 月开始，Agent 的 topics 现已更名为 subagents（子代理），功能上没有变化。

功能与 API 总览

构建 Agent

工具说明
Agent Script脚本语言，结合自然语言的灵活性和程序化控制的可靠性
Agentforce DXSalesforce CLI 和 VS Code 专业代码工具，用于编写、预览、测试 Agent
Agentforce Python SDK程序化创建、管理和部署 AI Agent

测试 Agent

工具格式自定义评估
Testing Center（UI）CSV否
Agentforce DX（CLI）YAML✅ 是
Testing API（代码）XML✅ 是

对话 Agent

工具说明
Agent APIREST API：启动会话、发送消息（同步/流式）、结束会话、提交反馈
Custom Connections连接外部聊天客户端，支持结构化响应格式
Agentforce Mobile SDK原生 iOS/Android 移动端 AI Agent 集成
Enhanced Chat v2Service Cloud 面向客户的 Web 聊天（JavaScript API + 上下文事件）
Enhanced In-App Chat SDK移动端消息传递，支持 Agent 到人工客服无缝升级

其他资源

ADL API —— 程序化创建和管理 Data Library
Export Session Tracing Data (OTel API) —— 提取 Agent 会话 Trace 的统一 JSON 视图

Agent API 入门

使用 Agent API 可以直接通过 REST API 与 AI Agent 进行通信：启动会话、发送消息、接收响应、结束会话。API 要求创建一个支持客户端凭据流的外部客户端应用（ECA）。

注意：Agent API 不支持类型为 "Agentforce（Default）" 的 Agent。

步骤 1：创建 External Client App（ECA）

设置 → External Client Apps Manager → New External Client App
指定名称和联系邮箱，选择 Enable OAuth
添加四个 OAuth 范围：api、refresh_token/offline_access、chatbot_api、sfap_api
启用：Client Credentials Flow、Issue JWT-based access tokens for named users
取消选择：Require secret for Web Server Flow、Require secret for Refresh Token Flow、Require PKCE
在 Policy 标签页中：启用 Client Credentials Flow，将 Run As 设为至少具有 API Only 访问权限的用户

步骤 2：获取凭据

Settings 标签页 → OAuth Settings → Consumer Key and Secret → 复制两个值。

步骤 3：创建 Token

curl https://{MY_DOMAIN_URL}/services/oauth2/token \ --header 'Content-Type: application/x-www-form-urlencoded' \ --data-urlencode 'grant_type=client_credentials' \ --data-urlencode 'client_id={CONSUMER_KEY}' \ --data-urlencode 'client_secret={CONSUMER_SECRET}'


响应中复制 `access_token` 值，用于所有后续 API 调用。`MY_DOMAIN_URL` 从设置 → My Domain → Current My Domain URL 获取。

![创建应用和获取凭据](https://sfdcvideotest.oss-cn-beijing.aliyuncs.com/media/ADG001/slide_178/image.png)

### 步骤 4：调用 API — 启动会话

`curl -X POST https://api.salesforce.com/einstein/ai-agent/v1/agents/{AGENT_ID}/sessions \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer {ACCESS_TOKEN}' \
  --data '{
    "externalSessionKey": "{RANDOM_UUID}",
    "instanceConfig": { "endpoint": "https://{MY_DOMAIN_URL}" },
    "streamingCapabilities": { "chunkTypes": ["Text"] },
    "bypassUser": true
  }'`

参数说明：

AGENT_ID —— Agent 的 18 字符 ID（见下方获取方式）
RANDOM_UUID —— 任意 UUID，用于在事件日志中追踪对话
bypassUser: true —— 使用 Agent 关联的用户（客户端凭据流通常设为 true）

响应内容：sessionId（后续所有消息调用必需）、Agent 初始欢迎消息（type: "Inform"）、_links（消息流、会话、结束端点 URL）。

启动会话

获取 Agent ID

Builder 类型获取方式
Legacy Builder在 Agent Overview Page 的浏览器 URL 末尾复制 18 字符 ID
New BuilderSOQL 查询 SELECT Id FROM BotDefinition WHERE DeveloperName = 'Agent_Name'

获取 Agent ID

Agent API 会话生命周期和示例

会话生命周期

POST /agents/{ID}/sessions — 创建会话 → 获取 sessionId
POST /sessions/{ID}/messages — 发送同步消息（完整响应）
POST /sessions/{ID}/messages/stream — 发送流式消息（SSE，实时）
DELETE /sessions/{ID} — 结束会话
POST /sessions/{ID}/feedback — 提交反馈（GOOD/BAD + 文本）

同步消息 vs 流式消息

模式端点适用场景
同步/messages简单用例，一次性获取完整响应
流式（SSE）/messages/stream实时聊天体验，逐块显示响应（Accept: text/event-stream）

流式消息的事件类型（按顺序）

ProgressIndicator —— "Working on it"（动作进行中）
TextChunk —— 增量文本块："Here"、" are"、" two cases..."
Inform —— 完整消息，含 citedReferences、feedbackId
EndOfTurn —— 本轮响应完成，无更多事件

会话生命周期和消息类型

发送消息示例

`# 同步消息
curl -X POST 'https://api.salesforce.com/einstein/ai-agent/v1/sessions/{SESSION_ID}/messages' \
--header 'Authorization: Bearer {ACCESS_TOKEN}' \
--data '{"message": {"sequenceId": 1, "type": "Text", "text": "Show me cases for Lauren Bailey."}}'

结束会话

curl -X DELETE 'https://api.salesforce.com/einstein/ai-agent/v1/sessions/{SESSION_ID}' \
--header 'x-session-end-reason: UserRequest' \
--header 'Authorization: Bearer {ACCESS_TOKEN}'

提交反馈

curl -X POST '.../sessions/{SESSION_ID}/feedback' \
--data '{"feedbackId": "...", "feedback": "GOOD", "text": "Great response"}'`


### 处理引用（Citations）

Inform 消息中的 `citedReferences` 数组包含引用源。内联引用使用 `inlineMetadata` 对象：`claim`（引用文本）+ `location`（字符偏移位置），用于在 UI 中渲染内联来源标注。

![发送消息和反馈](https://sfdcvideotest.oss-cn-beijing.aliyuncs.com/media/ADG001/slide_183/image.png)

## 发送 Agent 变量

在启动会话或发送消息时，可以传入上下文变量和自定义变量。Agent 可以在后续对话轮次中使用这些变量。

`"variables": [
  {
    "name": "$Context.EndUserLanguage",
    "type": "Text",
    "value": "en_US"
  },
  {
    "name": "team_descriptor",
    "type": "Text",
    "value": "The Greatest Team"
  }
]`

变量规则：

上下文变量（$Context 前缀）在会话启动后默认为只读 —— 仅在创建会话时设置
例外：$Context.EndUserLanguage 可在发送消息调用中修改
自定义变量：省略 __c 后缀（Conversation_Key__c → $Context.Conversation_Key）

启用 API 访问：Agentforce Builder 中勾选 "Allow value to be set by API"。Metadata API 中设置 ConversationVariable.visibility 为 external。

发送 Agent 变量

API 注意事项和故障排查

注意事项和故障排查

重要约束

不支持 "Agentforce（Default）" 类型 Agent
使用量影响信用消费（参见 Generative AI Usage and Billing）
120 秒超时 —— 超时返回 HTTP 500
Government Cloud：使用 api.gov.salesforce.com 替代 api.salesforce.com
始终使用 My Domain URL（如 mydomain.my.salesforce.com），而非浏览器中的 lightning.force.com

HTTP 错误速查

错误码原因解决方案
400无效的 Agent ID验证 Agent ID 是否正确
401授权问题检查应用创建、OAuth 范围、Token 生成
404错误的 Token 或端点验证 Token 和 URL；Government Cloud 检查域名
423会话已锁定API 仅支持一次一个请求，确保无并发请求
500多种原因"Unsupported Media Type" → 加 Content-Type: application/json；"EngineConfigLookupException" → 使用 My Domain URL；"HttpServerErrorException" → 验证 Agent ID；超时 → 超过 120 秒

API 注意事项和错误参考

Agentforce API 生态为你提供了将智能 Agent 集成到任何应用中的全部工具 —— 从构建、测试到部署和对话，覆盖完整的开发生命周期。

Agentforce APIs 和 SDKs 开发指南