ADG001

课程介绍

同学们，今天我们来看看Agentforce数据库这一块的内容。 简单来说，Agentforce数据库就是把人工智能和你自己那些信得过的业务数据连接起来。你想啊，AI如果只依赖公开的、通用的信息，有时候给出的答案就不够准，甚至还会胡说。但如果把AI连到你自己的客户资料、订单记录、产品信息这些可靠的数据源上，那它给出的结果就会准确得多，也更贴合你的实际业务。这就是Agentforce数据库要做的事情。 那怎么去管理这些数据库呢？就要说到ADL Connect API了。这个API可以让我们用编程的方式，去创建和管理Agentforce数据库，而不是只能在界面上点点点。这样，你可以把数据库的搭建集成到自己的自动化流程或者脚本里去，非常灵活。 好，那本章我们要做好哪些准备工作呢？就是这几个先决条件。你跟着一步步来就能把环境搭好。 首先你要安装Salesforce CLI。这个是什么？就是Salesforce的命令行工具，我们后面很多操作都要在终端里敲命令来完成，比如登录、创建资源等等。 然后还要装一个叫jq的小工具，它专门用来处理JSON格式的数据。因为API返回的基本都是JSON，用jq可以很方便地解析、提取我们需要的信息。 接下来，你需要有一个测试用的组织，也就是我们常说的Org。你可以创建一个Scratch Org或者用现有的开发版组织，别直接在生产环境里折腾，先用测试环境练手最安全。 还有一个重点，我们要创建一个外部客户端应用程序。这个应用需要配置好OAuth范围，也就是告诉Salesforce，这个客户端能访问哪些资源。比如，你要授权它读取数据库、管理相关服务，就得配上正确的scope。然后，你自然会拿到客户端凭证，比如client ID和client secret。 最后一步，就是拿这些凭证去换取一个访问令牌。有了这个令牌，后面的API调用才能顺利通过认证。 这些先决条件听起来可能有点绕，但其实就是准备工具、建个测试环境、拿到权限这几个事儿。你跟着做一遍就会发现，逻辑很清晰。好，这一节先到这里，我们下节继续深入配置。

课程章节

本课程共有 9 个章节

• 1

  ADL API Prerequisites & Setup

  第 210 页

  同学们，我们来看下一个环节：怎么把 ADL API 的环境给搭起来。这块儿听起来步骤不少，别担心，我带着大家一步一步走一遍，你就清楚了。 首先呢，我们要准备几件工具。第一个是 Salesforce CLI，咱们在命令行里跟 Salesforce 交互的基本工具，这个你应该已经装好了。第二个是 jq，它是一个命令行下处理 JSON 的小能手，后面解析接口返回的数据时会用到，因为它输出特别整洁。然后你还需要一个测试用的 PDF 文件，这是我们后续要拿来做文档处理的素材。最后还得有个配置好的测试组织，也就是一个可以随便折腾的 Developer Edition 或者沙盒环境。 好，有了这些，咱们进到 Salesforce 设置里，创建一个外部客户端应用程序。这是什么意思呢？就是我们要让外部系统（比如你本地的脚本）能够代表自己调用 Salesforce 的 API，这需要用到客户端凭据流。在设置的应用管理器里，新建一个连接应用，勾选上“客户端凭据流”，并给它配置标准的 OAuth 范围。注意这里的范围要包含 `chatter_api`，因为我们最终要访问 Connect REST API，它跟 Chatter 能力是绑定的，所以这个权限必须勾上。同时建议把 `api`、`refresh_token` 这些常用的也加上。配置好以后，启用它，让它支持 JWT 令牌，这样我们就拿到了一对消费者密钥和消费者 secret。 接下来，我们就要用 curl 实战了。打开终端，先用刚才拿到的消费者密钥和 secret 去换一个访问令牌。命令大概长这样：用你的消费者 key:secret 作为基本认证，向 Salesforce 的 OAuth 令牌端点发一个 POST 请求，指明 grant_type 是 client_credentials。这个请求返回的 JSON 里就会包含 access_token。我们可以用 jq 把它提取出来存成环境变量，方便后面用。 拿到令牌之后，先别急着干别的，先验证一下连通性。你可以调用一个简单的数据库端点，比如查询一下组织信息，或者用 Connect API 访问一下 `/services/data/v63.0/connect/communities` 试试，看到 200 的返回就说明一切就绪。 最后，在终端里设两个 shell 变量，一个叫 LIBRARY_NAME，你自己起一个唯一的库名称，比如 `my_doc_lib_001`；另一个叫 TEST_PDF_PATH，指向你准备好的那个测试 PDF 文件的路径。这样后面我们跑脚本的时候直接引用这些变量就行，不用反复改命令。 你看，其实就是准备工具、建连接应用、拿令牌、验证、设置变量这五步。整个流程走下来，我们的环境就准备好了，下一节就可以开始真正调用 ADL API 去创建文档库、上传内容了。有什么问题随时叫停我哦。

  ▶ 播放视频 查看详情
• 2

  File Library Example

  第 211 页

  同学，我们来看一下这一页的内容。它讲的是一个完整的例子：怎么一步一步创建一个基于文件的数据库，我们叫它 SFDRIVE 类型，然后上传 PDF 文件到 Salesforce 帮我们管理的一个 S3 存储桶里，接着触发索引，再不断去检查状态，直到这个知识库完全准备好，可以投入使用。整个过程覆盖了从创建到最终添加更多文件的整个生命周期。 咱们可以把它想象成，你要建一个电子图书馆。首先你得有个书架，也就是这个基于文件的数据库。你得告诉系统：“嘿，我要建一个 SFDRIVE 类型的库。” 这一步创建完成之后，它就会在底层给你分配好 Salesforce 管理的存储空间，相当于一个云端的硬盘，专门给你放文件。 接着，你得往里面放书，对吧？这里就是把你的 PDF 文件上传到那个存储桶里。上传完之后，这些文件只是躺在那里，系统还不能立刻理解里面的内容，所以需要“触发索引”。索引的过程，就好比是图书管理员给每本书编目录、贴标签，这样以后你问问题，系统才能快速找到相关内容。 但是编目录需要时间，你不能上传完马上就去用，得等它建好。所以我们要做“轮询”，也就是隔一会儿就去问一下：“嗨，建好了没有？”直到它返回状态说“我准备好了”，这时候你的知识库才算真正就绪，可以开始回答用户的问题了。 最后，整个生命周期还包括后续的维护，比如添加新的 PDF 文件进去，系统也会自动重新索引，更新知识库。所以你不用担心后续扩内容的事。 这样讲，是不是清晰多了？这个流程就是我们用 Agentforce 打造一个内部知识问答专家时，最基础也最关键的一步。

  ▶ 播放视频 查看详情
• 3

  File Library: Create, Wait & Get Upload URLs

  第 212 页

  同学们，我们来看看怎么创建一个文件库，其实步骤很简单。你只需要向数据库端点发一个 POST 请求，把 sourceType 指定为 SFDRIVE，就能获取到一个 libraryId。不过在上传文件之前，还得等一个叫 Data 360 的资源配置完成。这时候你可以调用一个准备端点，它会告诉你资源是否就绪，最长可能要等 120 秒。一旦准备好，你就可以为每个文件申请一个预签名的上传 URL 了：提供文件名，接口会返回一个 S3 的上传地址、必要的请求头，以及稍后要用来索引的文件路径。一次最多可以申请 1000 个文件的 URL。如果资源还没准备好，你会收到 HTTP 400 的响应，别担心，这只是提醒你需要继续轮询，再等一会儿就好。

  ▶ 播放视频 查看详情
• 4

  File Library: Upload, Index & Poll

  第 213 页

  嗨，同学，我们接着来看这张Slide。它讲的是怎么把文件上传到Agentforce的知识库，并让它可用。这个流程不复杂，咱们一步步走。 首先，你会拿到一个预签署的S3 URL，就像一张特殊的通行证，允许你直接把文件放进指定的云存储位置。用PUT请求上传文件时，记得带上从上传URL响应里解析出来的那些请求头——这就好比进大楼要出示对应的证件，缺了可不行。 上传成功之后，服务器会返回HTTP 200，代表文件已经稳稳当当地传上去了。但这只是第一步，文件虽然放上去了，Agentforce还不知道有这个新知识呢。所以你要主动告诉系统：“喂，我这有个新文件，请帮我建立索引。”怎么做呢？就是把文件的路径和大小等信息，通过一个POST请求发到专门的索引端点，这就相当于按下了“开始处理”的按钮。 接下来，系统就开始在后台吭哧吭哧地干活了。你不能一直等着不动，得每隔10秒去轮询一下状态端点，就像时不时去厨房看一眼菜做好了没有。状态端点会告诉你当前进展，它会返回几个阶段的状况。 特别要留意的是“SearchIndex”这个阶段。要让搜索能正常工作，文件内容需要先被分成小块，再转成向量嵌入，这叫分块和嵌入。只有这个SEN状态完成，SearchIndex才算真正搞定。 那怎么知道整个流程结束呢？你要关注一个叫“ALL_STAGES_SUCCES”的信号，它表示ADL管道已经全部跑通了。但是要注意，即使收到了这个信号，有时候SearchIndex的处理可能还在进行中，就像菜已经上桌了，但最后的点缀还没做完。所以最好继续观察，直到确认搜索索引也构建完毕，知识库状态变成“就绪”。 等一切就绪后，你就可以放心地往知识库里添加更多文件了，整个流程很清晰，对吧？简单总结就是：上传文件、触发索引、轮询等待、确认就绪。记住这四步，你就能轻松地把外部知识喂给Agentforce了。

  ▶ 播放视频 查看详情
• 5

  File Library: Add More Files

  第 214 页

  好，我们接着来看。当你已经创建好一个知识库，并且上传了第一个文件之后，如果再要往里面加更多的文件，流程其实跟第一个文件很像，但有一个非常关键的区别，这个一定要听清楚。 区别在哪儿呢？对于第一个文件，我们在上传到S3之后，是需要单独调用一个叫 `/indexing` 的端点来触发搜索索引的。但之后添加的其他文件，咱们就不需要再走这一步了。你只需要这么做：还是先为新文件获取一个预签名的上传URL，把它传到S3，然后，紧接着，直接调用 `/files` 端点来注册它。对，就是换成 `/files` 端点，而不是 `/indexing`。 为什么这样就行了呢？因为 `/files` 这个端点很智能，它自己就会自动触发搜索索引的“重新水化”——通俗点说，就是自动帮你把索引刷新好，把新文件的内容纳入搜索范围，你完全不用再去手动调一次索引接口了。所以，那个单独的索引步骤，真的只是第一个文件才需要。 你调完 `/files` 端点之后，系统会返回一个简单的响应，里面会告诉你 `filesAccepted: 1`，意思就是“好了，文件已经被接受并注册了”，非常直接。 整体上来看，整个知识库的完整生命周期，取决于你往里面加多少个文件，大概会经历6到9个步骤。这些步骤里，你会接触到的关键端点就这几个：创建库、检查准备状态、生成文件上传URL、索引（记住，只有第一个文件才需要），还有状态轮询，以及最后这个文件注册。这样梳理下来，再添加文件是不是就简单多了？

  ▶ 播放视频 查看详情
• 6

  Knowledge Library Example

  第 215 页

  同学们，我们来看这个例子。这里演示的是怎么创建一个基于知识文章的搜索库，也就是知识类型的库。它专门用来给咱们的知识文章内容建立索引，好让Agentforce快速检索到。 和之前讲的文件库相比，知识库有个不一样的地方——你必须明确告诉它要索引知识对象的哪些字段。举个简单的例子，你可能会选择索引文章的标题、摘要或者正文内容，让搜索更精准。 这里要特别提醒一点：有两个主要的索引字段一旦创建完毕，就再也不能更改了。也就是说，你在设置的时候一定要想清楚，到底把哪两个字段作为核心的索引字段，事后是没法反悔的。 另外，为了便于管理和合规，咱们还可以给这个库划定一个范围，让它只针对某些特定的数据类别来索引。这样，不同团队看到的知识范围就能隔离开，治理起来也更安全。 这就像给Agentforce搭建了一个专属的、可管控的知识书架，它只在这个书架里找答案，既高效又体贴。你理解了吗？

  ▶ 播放视频 查看详情
• 7

  Create Knowledge Library with Data Categories

  第 216 页

  同学，我们来看这一页，内容是关于创建知识库时一个非常重要的步骤。 你可以把这个过程想象成什么呢？就像你要开一家顶级的图书馆，在把成千上万本书放上书架之前，你首先得决定按什么方式来找书最方便，对吧？是按书名？还是按作者？ 知识库也是同样的道理，在最开始创建它的时候，你必须为它指定，两个，“主索引字段”，也就是这里的 `primaryIndexField 1` 和 `primaryIndexField 2`。 这有两个非常重要的点，你可得记住了。 第一，，这两个字段是必需的，而且一旦创建，就永远不能改了，。就像你决定按书名和作者来找书，图书馆一旦开张，这个基础规则就不能动了。所以，创建前一定要想好，哪两个字段是你未来查找知识最关键的。 第二，，这两个字段必须是 `KnowledgeKAV` 这个标准对象上真实存在的，而且是文本类型的字段，，别选错了数据类型。 除了主索引，你还可以选择性地用数据类别来缩小知识库的范围，让它更专注。这就像你把图书馆里的某几排书架，单独划成“历史专区”或“科技专区”。这里有一个规则要留意：如果你要按分类来选，要么用类别的名称，格式是 `上层分组.分类名称` 这样的，要么就用类别ID，，只能二选一，不能混着用，。 当你把这些基础配置好，点击创建之后，系统就会在后台开始忙活了。它会自动，触发索引和轮询操作，，把现有的知识文章，根据你刚才定的那两个主索引字段，整理进“图书馆”里。你只需要等它，直到状态变成“准备好”就行了。 等知识库准备好之后，你如果想改点东西，比如调整要索引的内容字段，或者修改刚才的数据类别配置，是可以的，用 ，`PATCH`， 这个更新操作就能改。但请再次记住，，那两个主索引字段，是无论如何都不能再改了，。 最后，怎么知道它现在的状态呢？用 ，`GET`， 请求去查一下它的详细信息和状态就行。如果有一天这个知识库不用了，想删掉它，也是用删除操作。但是，有一个前提条件：，必须没有任何活跃的Agent、Flow或是其他东西在引用着这个知识库，。你得先停掉那些引用，才能把它删干净。 怎么样，这样讲是不是清晰多了？创建知识库的关键，就在于一开始就把那个“不可变”的搜索基础——那两个主索引字段给定好了。

  ▶ 播放视频 查看详情
• 8

  Export Session Tracing Data

  第 217 页

  好，咱们今天来聊聊 Agentforce 里面一个非常实用的功能，叫做“会话跟踪 OTel API”。 您可以把 Agentforce 的每一次会话，想象成一段完整的旅程——从客户第一个问题，到最后解决问题，中间会经历好多步。那这个 API 呢，就是帮我们把这段旅程从头到尾，清清楚楚地记录下来，而且是用一种行业标准的格式，叫 OpenTelemetry 格式。 这样做有一个最大的好处，就是您可以把 Agentforce 会话里的所有细节，放到一个统一的视图里去查看，不再是东一块西一块。它会把会话里的每一轮对话、每一条消息、每次调用大模型的过程、每一个执行的动作，还有最终打出的指标分数和用户反馈，全部缝合在一起，变成一个完整的“杨森视图”。这里的“杨森视图”其实就是指一个单一、统一的整体视图。 具体来说，输出里都包含什么呢？ 您能看得到代理交互的每一步： 比如，第几轮对话（我们叫回合），里面具体有哪些消息； 再比如，这个过程中调用了多少次大模型，是哪个模型，回答了些什么； 还会记录下代理执行了哪些动作，是查询订单了，还是创建案例了； 最后还会带上性能指标，比如响应时间，以及用户丢过来的反馈是👍还是👎。 这些数据拿到之后，您下一步就可以把它们导入到您熟悉的可观察性平台，像是 Splunk、Datadog、New Relic，或者任何支持 OTLP 协议的收集器里。 这样一来，您不用登录 Salesforce 各种菜单去拼凑信息，直接在运维工具里就能看到整条会话的健康状况。哪个环节慢了，哪个大模型回复不准，是不是某个动作经常失败，全都一目了然。 所以简单说，Agentforce 会话跟踪 OTel API 就是一条管道，把 AI 会话的“黑盒”变成了透明、结构化、可追踪的数据，让运营团队和开发团队都能更方便地分析和优化代理的表现，听起来是不是很棒？ 咱们再接着往下看下一个细节。

  ▶ 播放视频 查看详情
• 9

  OTel API: Setup, Query & Export

  第 218 页

  同学们，今天我们来看一下Agentforce里一个挺有用的新功能——OTel API。简单来说，它就是给你提供了一个GET接口，你只要调一下，就能把一个完整的会话跟踪数据拿出来。 那它拿出来的是什么格式呢？是OpenTelemetry的ResourceSpans格式。可能有些同学还不熟这个，没关系，你就把它理解成一种业内标准的、专门用来记录分布式追踪的结构化数据就行了。通俗点说，就是你跟Agentforce一整轮对话的记录，包括每一步发生了什么，都会被完整保存，然后打包成这个标准格式给你。 当然，要用这个API，你需要先在Agentforce那边打开两个开关：一个是“会话跟踪”，另一个是“审核/反馈”。这两个功能启动了，系统才会开始帮你把对话细节收集起来。 身份验证这块，它用的是ECA，通过OAuth 2.0来做的。也就是说，你得先拿到令牌，然后带着令牌去调接口，安全性是有保障的。 最方便的是，你可以直接用“会话ID”来查。比如你在自己的应用里记录了用户的一个对话ID，那你想看这次对话里到底发生了什么，就直接拿这个ID去查API，返回的结果里就会包含全部信息——每一轮的对话、用户说了什么、助手回了什么、幕后的LLM调用记录、执行了哪些动作、耗了多少时间等等指标，甚至可以带出你提前关联好的用户反馈数据。而且这些数据是直接按照OpenTelemetry的标准给你的，所以你根本不需要再做任何格式转换，直接就能灌到任何一个兼容OTLP的可观察性平台里去，比如你可以配一个OTLP收集器，让它定期轮询这个API，然后你还可以在这中间做一些数据丰富，再转发到Datadog之类的监控工具里，很方便地做分析和告警。 不过既然是Beta阶段，有一些限制我们还是要知道的。第一，目前一次只能查一个会话的数据，不支持批量；第二，它只保留最近72小时的数据，太久以前的就拉不到了；第三，因为底层用的是Connect API，所以会有速率限制，你调得太频繁可能会被限流；第四，这个功能强依赖数据云（Data Cloud），如果数据云那边有什么变动，也会直接影响到它。 好，总的来记就是：这是一个“把Agentforce对话透明化”的工具，用标准格式把每一步都暴露给你，方便你做监控和调试。想用的话，先把Agentforce里的两个开关打开，然后拿会话ID去调接口就行，注意一下Beta阶段的这几个限制就好了。这样讲是不是就清楚多了？

  ▶ 播放视频 查看详情