Agentforce APIs 和 SDKs 开发指南

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 开发指南
📅 2026/7/4 ✍️ ponybai 🏷️ agentforce, salesforce, api
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 入门

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

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

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

  1. 设置 → External Client Apps Manager → New External Client App
  2. 指定名称和联系邮箱，选择 Enable OAuth
  3. 添加四个 OAuth 范围：api、refresh_token/offline_access、chatbot_api、sfap_api
  4. 启用：Client Credentials Flow、Issue JWT-based access tokens for named users
  5. 取消选择：Require secret for Web Server Flow、Require secret for Refresh Token Flow、Require PKCE
  6. 在 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 获取。

创建应用和获取凭据

步骤 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 会话生命周期和示例

会话生命周期

会话生命周期

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

同步消息 vs 流式消息

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

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

  1. ProgressIndicator —— "Working on it"（动作进行中）
  2. TextChunk —— 增量文本块："Here"、" are"、" two cases..."
  3. Inform —— 完整消息，含 citedReferences、feedbackId
  4. 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 中渲染内联来源标注。

发送消息和反馈

发送 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 集成到任何应用中的全部工具 —— 从构建、测试到部署和对话，覆盖完整的开发生命周期。