Agentforce Data Library 管理与 OTel 会话追踪指南

ADL API 前提条件和设置

Agentforce Data Libraries（ADL）通过将 AI 功能连接到受信任的数据源来增强准确性。ADL Connect API 让你能程序化地创建和管理 Data Library。

安装准备

Salesforce CLI —— 开发和构建自动化
jq —— JSON 解析工具（brew install jq）
测试 PDF 文件 —— 用于第一个 Data Library 的任意 PDF
测试组织 —— 已配置 Data Libraries

External Client App 配置

OAuth 范围：chatter_api、api、web、refresh_token/offline_access。启用 Client Credentials Flow 和 JWT-based access tokens。

获取 Access Token

RESPONSE=$(curl -s -X POST "$SF_INSTANCE_URL/services/oauth2/token" \
  -d "grant_type=client_credentials" \
  -d "client_id=$SF_CLIENT_ID" \
  -d "client_secret=$SF_CLIENT_SECRET")
ACCESS_TOKEN=$(echo $RESPONSE | jq -r '.access_token')
ORG_URL=$(echo $RESPONSE | jq -r '.instance_url')

验证连接

curl "$ORG_URL/services/data/v66.0/einstein/data-libraries" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

文件库（File Library）完整示例

创建一个基于文件的 Data Library（SFDRIVE 类型），上传 PDF 文件到 Salesforce 管理的 S3 存储桶，触发索引，并轮询直到库就绪可用。

步骤 1 — 创建文件库（SFDRIVE）

POST /services/data/v66.0/einstein/data-libraries
Body: {"masterLabel": "...", "developerName": "...",
       "groundingSource": {"sourceType": "SFDRIVE"}}
Response: JSON with libraryId and groundingSource fields

步骤 2 — 等待上传就绪

GET /services/data/v66.0/einstein/data-libraries/$LIBRARY_ID/upload-readiness?waitMaxTime=120000

库需要配置 Data 360 资源后才能上传文件。轮询最多 2 分钟；预期响应：{"ready": true}。

步骤 3 — 获取预签名上传 URL

POST /services/data/v66.0/einstein/data-libraries/$LIBRARY_ID/file-upload-urls
Body: {"files": [{"fileName": "file1.pdf"}]}
Response: uploadUrls (presigned S3 URL + filePath + headers)

最多 1000 个文件。如果在 Data 360 资源就绪前调用，返回 HTTP 400。

步骤 4 — 上传文件到 S3

curl -X PUT "$PRESIGNED_URL" $UPLOAD_HEADERS --data-binary @$FILE_NAME

预期：HTTP Status 200。文件存储在 Salesforce 管理的 AWS S3 存储桶中。

步骤 5 — 触发索引

POST /services/data/v66.0/einstein/data-libraries/$LIBRARY_ID/indexing
Body: {"uploadedFiles": [{"filePath": "...", "fileSize": 12345}]}
Response: {"status": "IN_PROGRESS"}

步骤 6 — 轮询直到就绪

GET /services/data/v66.0/einstein/data-libraries/$LIBRARY_ID/status

每 10 秒轮询一次。退出条件：status == "READY" 或 "FAILED" 或所有阶段全部 SUCCESS。READY 需要 SearchIndex 完成分块/嵌入。通常等待几分钟。

添加更多文件

对已有库添加更多文件的流程类似，但使用 /files 端点而非 /indexing：

# 获取新文件的上传 URL
POST /services/data/v66.0/einstein/data-libraries/$LIBRARY_ID/file-upload-urls

# 上传到 S3（同步骤 4）

# 注册新文件（自动触发搜索索引重建）
POST /services/data/v66.0/einstein/data-libraries/$LIBRARY_ID/files
Body: {"uploadedFiles": [{"filePath": "...", "fileSize": 12345}]}
Response: {"filesAccepted": 1}

关键区别：/files 端点自动触发搜索索引重建，不需要为额外文件单独调用 /indexing。

知识库（Knowledge Library）示例

创建基于知识的 Data Library（KNOWLEDGE 类型），索引 Knowledge 文章字段。需要指定要索引的 Knowledge 对象字段，其中两个主索引字段创建后不可变。

创建知识库

POST /services/data/v66.0/einstein/data-libraries
Body: {
  "groundingSource": {
    "sourceType": "KNOWLEDGE",
    "knowledgeConfig": {
      "primaryIndexField1": "Title",       // 必填，不可变
      "primaryIndexField2": "Summary",     // 必填，不可变
      "contentFields": ["UrlName"]          // 额外索引字段
    }
  }
}

所有字段必须存在于 KnowledgeKAV 上且为文本类型（STRING 或 TEXTAREA）。

数据类别（Data Categories）配置（可选）

启用数据类别规则以实现管控：

"isDataCategoryRuleEnabled": true,
"dataCategorySelectionNames": ["Products.Hardware", "Products.Software"]

格式：groupDeveloperName.categoryDeveloperName。

库创建后的操作

索引和轮询：同文件库的 /indexing 流程
PATCH 更新：PATCH /data-libraries/{id} 可更新 contentFields 和数据类别
GET 详情：GET /data-libraries/{id}
DELETE 删除：DELETE /data-libraries/{id} 如被活跃资源引用则不能删除

导出会话追踪数据（OTel API Beta）

Agentforce Session Trace OTel API 以 OpenTelemetry 格式提取 Agent 完整会话 Trace 的统一 JSON 视图。输出包含 Agent 交互的每一步：轮次、消息、LLM 调用、动作、指标分数和反馈。

前提条件

组织中已启用 Agentforce
启用 Agentforce Session Tracing + Audit and Feedback

使用流程

# 1. OAuth 2.0 认证（ECA）
# 2. 提交 REST API 查询
GET /services/data/v66.0/einstein/audit/otel/{session-id}
# 返回完整会话 Trace，OTel ResourceSpans 格式
# 3. 导出——原生 OTel 格式，无需转换

OTLP Collector 配置示例

Receivers：salesforce_otel → endpoint + oauth2client 认证
Processors：batch（10s 超时）+ attributes（添加 source=salesforce）
Exporters：otlp/datadog → api.datadoghq.com（DD-API-KEY）
Pipeline：traces → receivers → processors → exporters

Beta 限制

仅支持单会话查询（每次一个 Session ID），无批量查询
适用 Connect API 标准速率限制
仅返回最近 72 小时内的会话数据
需要 Data 360（Data Cloud）

典型用例：调试、自定义评估、第三方可观察性导出、自动化 Trace 收集。

ADL API 和 OTel API 为你提供了对 Agent 数据源的程序化控制和 Agent 行为的完整可见性——从 Data Library 管理到会话 Trace 导出。