功能与 API 总览

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

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

构建 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 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。

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 秒

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