Agentforce APIs 和 SDKs 开发指南

Agentforce APIs 和 SDKs 完整指南：12 个 API/功能总览表、Agent API 从零入门（External Client App 创建+Token+开始会话+发送同步/流式消息+结束会话+反馈+变量传递）、会话生命周期、Agent ID 获取（新旧 Builder）、API 注意事项（超时/Government Cloud/计费）、HTTP 错误排查参考（400/401/404/423/500）。...

首页/ 文章列表/ Agentforce APIs 和 SDKs 开发指南
📅 2026/7/22 ✍️ ponybai 🏷️ agentforce, salesforce, api

Agentforce APIs 和 SDKs 概览

s174

借助 Agentforce APIs 和 SDKs 加速你的 Agentforce 集成。构建可信且可定制的 AI 助手。

注意：从 2026 年 4 月开始，topics 更名为 subagents（子代理），功能不变。

功能与 API 总览

s175
功能/API描述BuildTestUse
Agent Script构建 Agent 的脚本语言✓
Agentforce DXSalesforce CLI + VS Code Pro-Code 工具✓✓✓*
Agentforce Python SDK编程式 Agent 创建和管理✓
Testing API编程式测试自动化✓
Agent API通过 REST API 与 Agent 对话✓
Custom Connections连接外部聊天客户端到 Agent API✓
Agentforce Mobile SDK集成 Agentforce 到移动应用✓
Enhanced Chat v2创建客户 Web 聊天体验✓
ADL API编程式管理 Data Library

*Agentforce DX 提供 agent preview CLI 命令用于测试目的。

构建、测试、对话与移动集成

s176

构建 Agent：Agent Script（自然语言+程序化控制）、Agentforce DX（CLI+VS Code）、Python SDK（编程式创建管理部署）。

测试 Agent：Testing Center（UI/CSV）、Agentforce DX（CLI/YAML/支持自定义评估）、Testing API（代码/XML/支持自定义评估）。

对话集成：Agent API（REST API 直接对话）、Enhanced Chat v2（Service Cloud Web 聊天）、Mobile SDK（原生 iOS/Android 集成）、In-App Chat SDK（移动应用内消息体验，支持人工接管）。

动作构建：Actions 是 Agent 执行任务和交互数据的构建块。参见 Build and Enhance Agentforce Actions。

Agent API 入门

s177

Agent API 让你通过 REST API 与 AI Agent 直接通信：开始会话、发送消息、接收响应、结束会话。

注意：Agent API 不支持 "Agentforce (Default)" 类型的 Agent。

设置：创建 App + 获取凭据 + Token

s178

前提条件：Agentforce 已启用，至少一个 Agent 已激活。

Step 1 - 创建 External Client App：Setup > External Client Apps Manager > New。启用 OAuth，添加 4 个 Scope（api/refresh_token,offline_access/chatbot_api/sfap_api）。启用 Client Credentials Flow + Issue JWT Web Token。Run As 设为有 API Only 权限的用户。

Step 2 - 获取凭据：App Settings > OAuth Settings > Consumer Key and Secret。复制保存。

Step 3 - 创建 Token：

curl https://{MY_DOMAIN_URL}/services/oauth2/token \
  --data-urlencode grant_type=client_credentials \
  --data-urlencode client_id={CONSUMER_KEY} \
  --data-urlencode client_secret={CONSUMER_SECRET}
# 从响应中复制 access_token

调用 API：开始会话

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

关键参数：bypassUser=true 使用 Agent 关联的用户；externalSessionKey 是随机 UUID 用于追踪会话。

成功响应包含：sessionId（后续消息必需）、messages（Agent 欢迎消息）、_links（消息流/结束端点 URL）。

重要：使用 My Domain URL（如 domain.my.salesforce.com）而非 Lightning URL。Government Cloud 使用 api.gov.salesforce.com。

获取 Agent ID

s180

Legacy Agentforce Builder：从 Agent Overview Page 的 URL 末尾复制 18 位 ID。
New Agentforce Builder：使用 SOQL 查询 BotDefinition：SELECT Id FROM BotDefinition WHERE DeveloperName='Agent_Name'。

Agent API 会话生命周期与示例

s181

完整生命周期：开始会话 → 发送消息（同步/流式） → 结束会话。Agent 在整个会话中跟踪上下文。

会话生命周期与消息类型

s182

同步消息（适合简单场景，一次返回完整响应）vs 流式消息（适合实时聊天，块增量到达）。流式使用 SSE（Server-Sent Events）协议。

流式消息事件类型：ProgressIndicator（处理中指示）→ TextChunk（文本块，逐个词到达）→ Inform（完整消息）→ EndOfTurn（本轮结束）。ValidationFailureChunk 表示验证失败需移除之前渲染的块。

Citations（引用）：citedReferences 数组含引用来源。支持内联引用（inlineMetadata 含 location 字节偏移）。

发送消息、结束会话与反馈

s183

发送同步消息

curl 'https://api.salesforce.com/einstein/ai-agent/v1/sessions/{SESSION_ID}/messages' \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -d '{"message":{"sequenceId":1,"type":"Text","text":"Show cases for Lauren Bailey."}}'

结束会话

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

提交反馈

curl 'https://api.salesforce.com/einstein/ai-agent/v1/sessions/{SESSION_ID}/feedback' \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -d '{"feedbackId":"9247bbd8-...","feedback":"GOOD","text":"Email looks great"}'

反馈保存在 Data 360 中，可用于审计和改进。返回 HTTP 201。

发送 Agent 变量

s184

在开始会话或发送消息时传递上下文变量和自定义变量：

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

变量控制：在 Agentforce Builder 中勾选"Allow value to be set by API"。通过 Metadata API 设置 visibility=external。Context 变量（$Context 前缀）默认会话开始后不可编辑（除 EndUserLanguage）。

Metadata API 变量字段：dataType、developerName、includeInPrompt、visibility（internal/external）。

API 注意事项与问题排查

s185

API 注意事项与 HTTP 错误参考

s186

注意事项

  • 不支持 "Agentforce (Default)" 类型
  • 120 秒超时，超时返回 HTTP 500
  • Government Cloud 使用 api.gov.salesforce.com
  • API 调用消耗 Credit，参见 Generative AI Usage and Billing
HTTP含义常见原因与解决方案
400Bad RequestAgent ID 无效 → 验证 ID 正确
401Unauthorized授权问题 → 检查 Token 和设置步骤
404Not FoundToken 或端点错误；Government Cloud 未用 gov 端点
423Session Locked同一会话有请求正在进行（一次一个请求）
500Internal ErrorContent-Type 未设 application/json；My Domain 端点错误（EngineConfigLookupException）；Agent ID 错误（HttpServerErrorException）

Postman Collection 是最快的入门方式：Agent API Postman Collection。完整参考见 Agent API Reference。