DEX801

课程介绍

好，同学们，咱们这节课来看看怎么给Agentforce创建动作，还有怎么把这些动作做得更强大、更好用。这块内容其实不复杂，咱们一步一步说。 首先，创建动作，咱们有四种不同的方法。你可以用Apex REST类，这就像对外提供一个接口，让Agentforce能调到你写好的后端逻辑。或者你也可以用Apex控制器方法，这个更贴近页面，适合跟界面相关的操作。另外，你还可以直接写一个命名的SOQL查询，这样Agentforce就能直接查数据，简单直接。最后，你还可以用Apex可调用方法，这种方法特别灵活，专门就是为了让外部系统，比如Agentforce，来调用你的Apex代码。 这些就是创建动作的基础路径，你可以根据需求选适合的。 那创建好以后，怎么能让这些动作更好用呢？咱们有三个增强手段。 第一个叫Lightning Types，这是用来处理复杂界面的。如果动作需要用户填一些比较复杂的表单，或者展示一些结构化的信息，你就可以定义Lightning类型，让界面更友好。 第二个是全局副本，这个主要是为了提高可用性。你可以给动作起一个更好懂、更通用的名字和描述，这样不管是谁在哪个地方用，都能一眼看明白这个动作是干嘛的。 第三个是Apex引用，这个让你在写动作的时候，可以直接内联引用Apex代码里的片段，比如一个常量的值或者一个方法的返回类型，不用再硬编码，维护起来更省心，也更精准。 所以总结一下，创建动作有四种方式：REST类、控制器方法、命名查询和可调用方法。想让动作更好，就记住三个增强点：复杂界面用Lightning Types，通用易懂靠全局副本，精准引用用Apex引用。 好，这一章就到这里，大家消化一下，有问题随时提。

课程章节

本课程共有 9 个章节

• 1

  Create & Enhance Actions Overview

  第 220 页

  好，我们来看看这一页幻灯片。它讲的是在Agentforce里，怎么去创建和增强一个行动。别担心，这些词听起来有点技术，我会用最直白的方式给你讲明白。 首先，，创建行动，一共有四种方法。 第一种和第二种，分别是 ，Apex REST， 和 ，Aura Utiled， ——对，这个名字你可能不太熟悉，简单说，它们都是基于你现有的Apex代码或者一些Aura组件。这两种方法最酷的地方是，它们会借助，生成式人工智能，，自动帮你生成符合 OpenAPI 标准的文档，然后直接部署到 API 目录里。这样，Agent就能顺畅地找到并调用这些接口了。对于有一定开发基础，又不想手写文档的同学来说，非常省力。 第三种叫，命名查询，。这就像在后台的设置界面里，直接写一条 SOQL 查询语句，然后把这条查询保存成一个行动。不用写类、不用部署，声明一下就能用。非常适合只会写点查询、不太会编程的初级管理员。 第四种是，Invocable方法，，这就是直接在 Apex 方法前面加一个 `@InvocableMethod` 注解，这样一来，流程、聊天机器人，包括我们现在说的Agent，都可以直接调用它。它是最直接的代码集成方式，适合有开发经验的同事。 说完创建，我们再看看，增强，行动，也就是让已经创建好的行动变得更好用、更强大。这里有三种方法。 第一，，Lightning Types，，它的作用是给复杂的界面操作改善用户体验。比如你的行动会打开一个表单，用了它就能让这个表单看起来更好填、更智能。 第二，，Global Copy，，这很实用，就是给行动增加一个“复制”功能。你可以把一个行动快捷复制成另一个，不用重复配置。 最后，，Apex Citations，，它能够为你的行动提供内联的源属性，方便追溯代码来源，也帮助Agent更精准地理解这个行动到底是干什么的。 最后要记牢，这些方法没有哪个是绝对最好的。你选哪种，取决于你的，用例场景，和，技能水平，。简单查询就用命名查询，有现成的Apex就选Invocable或者Apex REST，需要改善体验就增强一下。 这样梳理下来，是不是清楚多了？我们接着看下一张。

  ▶ 播放视频 查看详情
• 2

  Apex REST Actions:

  第 221 页

  同学们，这节课我们来看看一个非常实用的工具——Agentforce Vibes扩展。 想象一下，你写好了Apex REST类，想让它在Agentforce里被直接调用，变成智能代理能用的操作，怎么办？以前可能需要手写接口文档，现在不用了，Agentforce Vibes可以帮你用生成式AI，快速为你的Apex REST类生成标准的OpenAPI v3文档。整个过程很流畅，我来一步步给你说说。 首先，你手里已经有了写好或检索到的Apex REST类。接着，Vibes扩展会自动分析这个类里的方法和结构，利用生成式AI直接生成一份OpenAPI文档，你就得到了一个精确描述接口的规范文件。然后呢，系统还会对这个文档进行验证，确保它准确无误，减少错误。 验证通过之后，你只需要一键，就能把这个类和生成的元数据部署到你所在组织的API目录中。这样，你的API就正式注册了。最后一步，你可以在Agentforce Builder里，基于这个类的方法直接创建代理操作，让Agent在流程中像调用普通工具一样去使用这个REST API。这样，从代码到能够被Agent调用的接口，一条线就全打通了。 这个扩展大大简化了以前繁琐的手动文档编写和配置工作，让Apex REST类能快速变成Agentforce里的智能操作，是不是很方便？大家有时间可以亲自试一下这个Vibes扩展。

  ▶ 播放视频 查看详情
• 3

  Prerequisites & Generation Workflow

  第 222 页

  好的同学，我们来看这一页的内容，讲的是如何创建一个Apex REST操作，放到Agentforce里用。 首先，你要装上Agentforce Vibes扩展包，这是必须的。如果你还想做API的治理和验证，可以选装MuleSoft for Agentforce扩展包，这个不强制。 你的Apex类要满足三个条件：第一，必须有 @RestResource 这个注解；第二，要设置好共享规则；第三，至少要有一个HTTP方法注解，比如 @HttpGet 或 @HttpPost 这类的。注意，托管包里那些类是识别不出来的，得是你自己项目里的类。 整个流程分成10步，从创建DX项目开始，一直到最后把操作部署到API目录里，然后你就能确认这个操作是不是真的可用了。 如果你改动了Apex类，需要重新生成操作的话，有两个选项。一个是“覆盖”，就是直接把旧的替换掉；另一个是“手动合并”，选这个会打开一个差异视图，里边每个文件都带时间戳，方便你对比着改。 最后提一句，API的描述信息，它是取自YML文件顶层的description字段，可不是直接拿ML里面的描述，这个别搞混了。 好了，这页的核心就是这些，我们下一部分继续。

  ▶ 播放视频 查看详情
• 4

  Verify OpenAPI Spec & Extension Fields

  第 223 页

  嗨，同学，咱们接着看今天这一页内容。它讲的是什么呢？就是当我们为 Salesforce 里的 Apex REST 类生成了一份 OpenAPI 规范文档之后，一定要做的一件事：，仔细验证这份文档，确保它在“意思”上跟我们写的 REST 类完全一致，。 你别小看这一步，文档要是有偏差，后面不管是给别人调用、做测试，还是丢给 Agentforce 之类的平台去自动集成，都会出问题。所以咱们得像个质检员一样，把几个关键点一一核对清楚。 --- ，首先，要确认几个大原则：， - 这份规范必须是用 ，OpenAPI v3.0.0， 格式写的，这是目前最通用的标准。 - 服务器地址，也就是 `servers` 那一项，要设成 ，`/services/apexrest`，。因为 Salesforce 的 REST 服务都挂在这个路径下。 - 然后，所有 API 的访问路径，必须跟你 Apex 类上用 `@RestResource(urlMapping='...')` 定义的路由，一模一样，。路径前面不需要重复 `/services/apexrest`，因为服务器根路径已经配好了。 --- ，接着，咱们要挨个检查这几个部分的语义是否匹配：， 1. ，路径参数， 比如你的 URL 是 `/Account/{Id}`，那 OpenAPI 里就要有对应的 `{Id}` 参数，而且类型要跟 Apex 方法的参数类型一致。不能多了，也不能少了。 2. ，HTTP 方法和请求路径， Apex 里你用 `@HttpGet`、`@HttpPost` 等注解定义了方法，那 OpenAPI 里每个路径下的对应操作（get、post 等）就不能搞混。路径本身也要完全对上。 3. ，查询参数， 如果你的方法里通过 `RestContext.request.params` 获取参数，那么 OpenAPI 就要把这些参数列出来，写上名字、是否必填、类型是什么。尤其是那些不传就报错的，一定要标记成 `required`。 4. ，必填字段， 在请求体里，如果某个字段在 Apex 里做了非空校验，或者逻辑上必须传，那么在 OpenAPI 的 `requestBody` 的 schema 中，这个字段也要标成 `required`。 5. ，参数和字段的类型， 数字就是 `integer` 或 `number`，字符串是 `string`，布尔是 `boolean`，日期时间要对应到正确的 `format`，比如 `date-time`。别出现 Apex 里字段是数值，结果文档里写的是字符串类型，那调用方就可能传错数据。 6. ，请求体的形状， OpenAPI 里 `requestBody` 描述的 JSON 结构，要跟 Apex 反序列化时用的那个类或 Map 的结构完全一致。包括嵌套对象、数组这些复杂形状，都得到一个字段一个字段地核实。 7. ，成功响应（2XX 状态码）， 我们这里只重点验证 2 开头的成功响应就行了，因为课件里提到了范围 200–299。检查一下 OpenAPI 里定义的响应状态码是不是在这个范围内，不能把 200 写成了 201，或者漏掉了 204 这种无内容响应。 8. ，响应体的结构， 跟请求体类似，Apex 代码里 return 的对象序列化后是什么 JSON 形状，OpenAPI 的 `responses` 里就要原原本本地描述出来。最好用一个实际的返回样例去比对一下，一看结构就清楚了。 --- 你把上面这些点都逐项核对过了，如果全部匹配，那这份 OpenAPI 文档在语义上就跟你的 Apex REST 类是相同的，值得信任。以后哪怕代码改了，也记得回来更新文档，再做一次这样的验证。这样，无论是团队协作、自动化测试，还是让 Agentforce 这样的智能体来调用你的接口，都不会因为文档不准确而掉坑里。 好，这一页的重点就是这些，咱们消化一下，有问题随时问。

  ▶ 播放视频 查看详情
• 5

  OAS Objects Reference & SFDC Extensions

  第 224 页

  好，我们来看一下这一页内容，它讲的是如果你想让一个Apex REST API变成Agentforce里可以直接调用的动作，那你写OpenAPI规范的时候，有一些非常严格的格式要求。这些要求不难理解，但如果你不了解，可能就会卡住。 首先，记住一个固定地址：所有这种对外的REST服务的服务器地址，必须是单一个的 `/services/apexrest`。你不能自己随便写一个别的路径，Salesforce强制要求所有通过Apex暴露出来的REST接口，都要放在这个入口下。 接下来，路径这一项，必须和你Apex类上用 `@RestResource(urlMapping='...')` 声明的那个路径完全一致。注意，是完全一样，大小写、斜杠什么的一个字都不能错。 另外还有一点要注意，有些常见的OpenAPI字段是不允许出现在这里的。比如说，路径项里不能有 `server`，操作的设置里不能有 `callback`，参数里不能出现 `cookie` 类型的参数。你写规范的时候直接把这些避开就行。 为了能让Salesforce识别出这个动作是可以在Agent里面用的，我们还需要用到一组Salesforce自己提供的扩展字段。这些字段都以 `x-sfdc` 开头，相当于是给标准OpenAPI加上了Salesforce专用的标记。 这里面最重要的有四个： - `x-sfdc-isAgentAction`，这是必须设置的，而且值一定要是true，它告诉平台“这是一个代理可调用的动作”。 - `x-sfdc-isUserInput`，也是必须的，用来标记哪些字段是需要由用户自然语言来提供输入的。 - `x-sfdc-isDisplayable`，还是必须的，控制这个动作的输出能不能在前端直接展示给用户。 - `x-sfdc-isPii`，这个是可选的，如果你的动作会处理个人敏感信息，就要标上。 最后一点，你要在Salesforce里创建一个“外部服务注册”的元数据，也就是`ExternalServiceRegistration`，把刚才写好的那个OpenAPI规范登记进去，并且把它的`registrationProviderType`设置成`Custom`。这样一来，这个API才会出现在API目录里，也才会被Agent识别成可以执行的动作。 概括一下，核心就是四件事：服务器地址固定用 `/services/apexrest`；路径要跟代码里的urlMapping一模一样；避开那几个禁止的参数字段；必填那三个Salesforce扩展标记。做到了，你的Apex REST就能无缝变成一个代理的动作了。

  ▶ 播放视频 查看详情
• 6

  Validation Tools, Rulesets & Limits

  第 225 页

  同学们，咱们今天来聊一个很实用的工具，叫做 ，MuleSoft for Agentforce 扩展包，。别被这么长的名字吓到，你可以把它想象成一个智能工具箱，专门帮我们在做API集成的时候，少踩坑、多省心。 这个扩展包到底帮咱们解决了哪些头疼的问题呢？主要是三个。 第一个，它能帮你做，设计的验证和检查，，就像一个语法老师。它内置了两个“治理规则集”，你一听这名字可能有点懵。简单来说，就是两套自动检查规则。 * 第一套规则叫 ，Salesforce API主题和操作支持规则，。它的作用是盯着你的API文档，确保上面有代理操作必需的那些元数据。少了一样，它就会提醒你，防止你后续操作报错。 * 第二套规则叫 ，Salesforce Apex REST最佳实践规则，。如果你是用Apex写REST接口，这套规则会检查你的代码质量，确保你写出来的接口是符合最佳实践的，更稳定、更高效。 第二个，它带了一个，API控制台，。这是个好东西！你开发完一个接口，想测试一下通不通，不用自己费劲写代码去调。在这个控制台里，你可以轻松地用真实数据，甚至是模拟数据来测试你的API端点，看看返回结果对不对，非常方便。 但是，用这个工具的时候，有几个特别重要的“坑”，或者说限制，我得提前告诉你。 1. ，API目录的限制是通用的，：任何API目录本身的限制，在这里都适用，你得心里有数。 2. ，ApexRest类，它“藏”起来了，：有一种叫 ，ApexRest， 类型的服务资源，它在那个“外部服务”的设置界面里是看不见的。你别到时候找不到，以为它丢了。 3. ，部署要分开做，：你部署一个服务资源的时候，它不会自动把相关的Apex类一起部署过去。这两步得分开做，千万别忘了。 4. ，托管包里的类，不管，：如果你引用了托管包里的Apex类，这个工具是检查不到的，它被排除在外了。 最后，送你一个非常重要、能救命的操作铁律：，在你停用或者删除任何一个API之前，必须、一定要先从代理操作里把它移除掉！， 顺序反了，就可能会出问题。记住了吗？这可是实践中的关键一步。

  ▶ 播放视频 查看详情
• 7

  Create Actions: Multiple Approaches

  第 226 页

  同学们好，今天这一章，我们聚焦在一个非常实用的环节——怎么去创建和增强 Agentforce 里的代理动作。一共有四个关键主题，我们一个一个来看。 第一个，叫 ，AuraEnabled 控制器方法，。大家知道，在 Salesforce 里，我们可以用 Apex 写后台代码，然后给方法加上 `@AuraEnabled` 注解，让它能被前端调用。现在更厉害了，通过 Agentforce 里的 Vibes 工具，能够自动为这些方法生成一份 OpenAPI 文档，一生成，这个方法就摇身一变，成了一个对外公开的代理操作，外面系统可以直接按标准接口来调它。 第二个，是 ，命名查询 API，。这个工具允许我们把一条写好的 SOQL 查询，直接命名、封装成一个代理操作。你不需要再写多余的 Apex 代码，只要把查询定义好，Agentforce 就能把它当成一个动作来调用。这样一来，获取数据就跟点菜一样简单。 第三个，，Apex 的 InvocableMethod 注解，。这个方法上标一个 `@InvocableMethod`，你的 Apex 代码就能无缝对接流程、甚至直接成为代理的动作，集成起来非常直接，几乎不用额外配置。 第四个，是 ，Lightning Types，。有时候我们想让代理操作的输入界面或输出展示更漂亮、更贴合业务需求。这时就可以用 Lightning Types，来给这些操作的输入和输出定制一套自己的 UI，交互体验一下就好起来了。 这四个主题，就是我们打造强大代理动作的基础工具箱。掌握了它们，你就可以灵活地把现有功能变成代理可直接动用的能力。好，这节课就先梳理到这里，后面我们会逐一深入练习。

  ▶ 播放视频 查看详情
• 8

  AuraEnabled Controller Actions & Limits

  第 227 页

  同学们好，我们接着来看怎样用 Apex 控制器来为 Agent 创建动作。这个方法其实和咱们之前学过的 Apex REST 动作很相似，底层都是生成 OpenAPI 文档然后接入 API 目录，只不过这里专门针对的是带有 @AuraEnabled 注释的方法。 简单说，你写一个 Apex 类，里面的方法用 @AuraEnabled 修饰——这是为了让它既能被 Lightning 组件调用，也能被 Agentforce 识别。写好之后，用 Agentforce 提供的 Vibes 扩展，它可以自动帮你生成符合 OAS v3 标准的 OpenAPI 文档。接着，把这个文档和你的类一起部署到 API 目录里，Agent 就能通过目录发现并调用这个动作了。 但要记住，API 目录有数量限制。万一部署的次数多了达到了上限，怎么办呢？不能直接硬删，需要先去代理里，把那些不再使用的操作从动作列表中移除，然后才可以把对应的类从 API 目录里卸载或删除掉。这样就能安全地腾出空间。 至于更多细节，比如 @AuraEnabled 注释的详细用法、注意事项，大家可以去参考官方文档里的“AuraEnabled 注释参考”和“Lightning 组件指南”。好，这部分就是通过 Apex 控制器创建动作的要点，大家理解了吗？

  ▶ 播放视频 查看详情
• 9

  Named Query API Actions

  第 228 页

  好的同学们，今天我们来看一个很实用的小工具——命名查询API。简单说，它让你可以直接在系统里写一段自定义的SOQL查询，然后把它变成一个智能助手可调用的操作，整个过程完全不用写代码。 怎么做呢？首先，你要在设置里把“命名查询”这个功能打开。打开之后，就可以创建你的查询了。建好的查询会出现在一个叫做“API目录”的地方，但别忘了，你必须手动把它激活，它才能真正生效。 激活之后，怎么变成代理操作呢？来，我们进入Agentforce的资产设置里，新创建一个操作。在引用操作类型里选择“API”，然后在类别里选择“Salesforce Named Query API”，再关联到你刚才建好的那个查询。 注意一点，实际运行这个查询的用户，必须对查询里涉及的数据有“读”的权限，否则会失败。 那它最大的好处是什么？就是让你不写一行 Apex 代码，就能把数据查询能力开放给智能助手。是不是超方便？这就是命名查询API的妙用。

  ▶ 播放视频 查看详情