ADG001

课程介绍

同学们，咱们来看一下怎么在 Agentforce 里管理代理的状态。其实很简单，你不需要每次都跑到网页界面里去点来点去。我们可以直接从 VS Code，或者用命令行来激活或停用一个代理。 一旦你激活了代理，它就会立刻出现在你配置好的那些连接渠道上，比如你的官网聊天窗口、手机应用或者消息平台，用户就能直接跟它对话了。而当你停用某个代理时，系统会先关闭所有正在进行中的用户交互，然后代理就不再对外可用了。所以停用之前最好确认一下，是不是还有用户在对话，免得把人家聊一半的会话给掐断了。 另外还有一个很方便的功能：你可以直接通过 VS Code 或命令行，就把代理在你们组织的 Agentforce Builder 界面里打开。也就是说，你不用到处找那个设置页面，敲一条命令或者在编辑器里点一下，就直接进到图形化的编辑界面里，接着修改代理的逻辑、回复什么的，非常高效。 好，这就是关于代理激活、停用以及打开 Builder 的操作方式，大家可以在工具里自己试一下。

课程章节

本课程共有 10 个章节

• 1

  Activate, Deactivate & Open in Builder

  第 164 页

  同学们，咱们现在来看看怎么把建好的代理激活，让它真正跑起来。简单说，激活代理之后，那些连接了这个代理的渠道——比如网页聊天、消息服务——才能让用户开始和代理对话。 如果你是在VS Code里干活，操作很方便。在项目文件里找到Bot或者BotVersion的元数据文件，右键一点，就会弹出一个菜单，里面有“激活”和“停用”，选一下就好了。要是你喜欢敲命令行，可以用`sf agent activate`来激活，它会给你列出一堆可用的代理，你从列表里选一个就行；想停用的话，就用`sf agent deactivate`，同样选一个就好。 还有，万一你想快速修改代理的设置，也可以直接在VS Code里，找到那个.agent后缀的代理文件，右键选择“在Agentforce Builder中打开”，它马上就会在浏览器里打开那个代理的可视化编辑器。或者用CLI命令：`sf org open`，带上`--api-name`加上代理的API名称，或者用`--authoring-bundle`来指定打包好的文件，效果是一样的，也会在浏览器里打开编辑器。 最后还有一点很贴心，打开浏览器的时候你可以灵活选择——指定用什么浏览器、要不要用无痕模式，或者干脆只给你显示一个URL，你自己复制到想要的浏览器里。这样，不管你是想测试还是随时改配置，都特别方便。激活这件事，就这些，你们试一下就明白了。

  ▶ 播放视频 查看详情
• 2

  Use Metadata to Move an Agent

  第 165 页

  同学们，我们来看这张幻灯片。它讲的是怎么把做好的代理，从一个环境搬到另一个环境，比如我们从测试用的沙盒搬到正式的生产环境。 你可以想象成搬家。你在这个沙盒里已经把代理训练好了，就像装修好了一个房子，现在要把它整体打包运到另一个地方。那怎么运呢？就是用代理的元数据，也就是描述这个代理的所有配置信息。你只要从沙盒里把这些元数据检索出来，下载到你的本地电脑，然后再部署到生产组织里就行了。 但这里有一个关键点，就是代理元数据的类型，它不一样。我们分三种：草稿状态的代理、已经提交的代理，还有旧的代理。它们的元数据格式和你能修改的程度，都不一样。起草的代理还在设计阶段，比较灵活，你可以随意编辑；已提交的代理就固定了，像一个正式的版本，只能通过特定方式更新；而旧代理呢，是指以前老版本的代理，它的元数据结构更早一些，可能工具支持上会有些差别。 所以咱们在迁移之前，一定得搞清楚自己的代理是哪种状态。不然你可能会发现，明明想移动，结果格式不对，或者部署过去没法用。 好了，这一页的核心就是：代理迁移靠元数据，先检索、再部署；同时要留意代理的三种元数据类型，它们决定了你能做什么、不能做什么。掌握这个，你就能轻松地把代理从测试环境送到真实战场了。

  ▶ 播放视频 查看详情
• 3

  Understanding Agent Metadata Types

  第 166 页

  同学们，咱们今天来看看代理的三种类型，这在部署元数据时特别关键，一定要弄明白。 第一种叫草稿代理，它只用到一个叫 AiAuthingBundle 的组件，特点是能随时编辑，很灵活。第二种是委托代理，它除了 AiAuthingBundle，还用到了 Bot 和 BotVersion 这两个组件，但它被锁定了，你不能直接改，得创建新版本才行。第三种是遗留代理，它只依赖 Bot 和 BotVersion，没有提交阶段。 好，这里有个常见坑要注意：版本不匹配。如果你保存的内容比提交的多，版本就对不上了。怎么找正确的对应关系呢？去检查 guardle-met.html 文件里的目标元素，它标明了哪个 BotVersion 和 GenAiPlannerBundle 版本，对应着你手里那个 AiAuthingBundle 版本。记住这个排查方法，以后遇到问题就不会抓瞎了。

  ▶ 播放视频 查看详情
• 4

  Move Agent to New Org: Steps 1–4

  第 167 页

  同学们，咱们今天来说一说，怎么把 Agentforce 从开发环境搬到生产环境，也就是部署的前四个步骤。你记住，这几个步骤就像打包搬家，第一步先把钥匙配好，第二步把家当清单列出来，第三步把东西核对清楚，第四步是万一清单有出入时的补救办法。 第一步，咱们要用 Salesforce CLI 把本地环境搭起来。很简单，打开命令行，先用 `sf org login` 连上你的源组织，也就是开发用的沙盒，然后再同样用 `sf org login` 连上目标组织，比如生产环境。这样两个地方的“钥匙”就都有了，后面才能互相传东西。 第二步，创建一个标准的 Salesforce DX 项目。核心就是一个清单文件，我们管它叫 manifest。你可以直接用命令 `sf project generate` 或者手动建一个 `package.xml`，这个清单就相当于你准备搬走哪些东西的列表。 第三步，就来写这个 `package.xml` 清单。针对 Agentforce，最常见的写法有三种。第一种是“全搬”模式，用通配符星号把所有代理都列进去，但是提醒你，要是组织特别大，代理特别多，用通配符可能会拖慢部署，悠着点用。第二种是“精准搬运”，只搬一个具体的代理版本，这时候你要在清单里指定三个关键成员：`BotVersion`、`GenAiPlannerBundle` 和 `AiAuthingBundle`，一个都不能少。第三种情况是“版本对不上号”——比方说你在开发时保存了好几次，但提交发布的次数跟保存次数不一样，就叫不匹配的版本。这时候你的清单就得针对这种不匹配的版本来写，不能按常规方式来。 第四步是可选的，但很救命。当真的遇到版本不匹配的时候，你需要找出正确的映射关系。怎么做呢？去查一个叫 `guardle-meta.html` 的文件，它藏在你的项目里，打开后找目标元素，它会告诉你到底哪个保存版本对应哪个提交版本，你就照着它给出的映射去修正清单，这样部署才不会报错。 好了，前四步讲完，其实就是“连上两头、建好清单、按三种类型去定义、出错了查映射”。你先把这四步弄熟，后面部署就稳了。

  ▶ 播放视频 查看详情
• 5

  Move Agent to New Org: Steps 5–7

  第 168 页

  同学们，接下来我们看看部署代理的最后几步，也就是步骤5到7。这部分主要就是把我们做好的代理，从开发环境搬到正式使用的环境里去。 首先，我们需要准备一个“清单文件”，这就像一张打包清单，用来告诉系统我们要把哪些东西从源组织里卸载掉，然后部署到目标组织。为什么是卸载呢？其实这是部署流程的一个环节，我们先把要部署的元数据列出来，系统会按清单处理。别担心，这不是真的删除，而是部署的一部分。 接着，有个可选的操作，就是更新代理里的用户名。你可能会问，为什么要换用户名？因为代理在开发环境中用的是开发者的用户名，但到生产环境，很可能要用一个专用的集成用户。如果是草稿状态的代理，我们可以通过字符串替换来改用户名。具体的做法是，在 `sfdx-project.json` 这个项目配置文件里设置替换属性。这样部署的时候，通过环境变量把源组织的用户名自动替换成目标组织的用户名。但要注意，这个方法只对草稿状态的代理有效。如果代理已经提交了，就不能直接编辑了，必须创建一个新的版本才行。所以，最好在代理还是草稿的时候就做好这个替换。 准备工作做好了，就可以真正开始部署了。我们用这个命令：`sf project deploy start`。听起来很简单对吧？但要记住一个关键点：，千万不要手动去修改我们从源组织检索到的元数据文件，。你可能会想，“我直接改一下文件不是更方便？”但是这么做很容易出错，而且会破坏部署的完整性。正确的做法是让部署命令自动根据清单和环境变量来做替换。确保检索的元数据保持原样。 部署完成之后，我们的代理就到了目标组织里。但工作还没完，我们还需要配置代理用户和相关的权限。你可以直接在目标组织里手动设置一个代理用户，分配好权限。也可以用一个叫“组织创建代理用户”的命令，自动创建一个新的代理用户。这个命令会帮你生成一个专用的用户，省去手动配置的麻烦。 总的来说，这几步就是：用清单部署，如果需要就通过配置自动换用户名，然后执行部署命令，最后配好用户权限。整个过程注意别乱改元数据，草稿时代理灵活调整，提交后就只能走版本更新了。这样，你的代理就能顺利地在生产环境中跑起来，为业务服务了。 同学们，还有什么不清楚的地方吗？我们休息一下，下一节讲如何监控代理的表现。

  ▶ 播放视频 查看详情
• 6

  Manifest Examples Summary

  第 169 页

  今天我们来看看在 Agentforce 里部署代理时，必须了解的三种主要表现模式。别被“表现模式”这个词吓到，其实就是三种不同的部署策略，每种都有自己的适用场景，我慢慢说给你听。 第一种叫全代理模式。它的思路很简单粗暴：对所有相关的内容都使用外卡来匹配。外卡大家应该知道，像星号那种，代表“全部”。这样做的好处是一次搞定所有东西，但问题也随之而来——如果你的组织很大，元数据非常多，这种全盘扫描就很容易导致超时。所以实际工作中我们不建议一直用全代理模式，更好的做法是明确列出你要部署的特定类型，这样不但稳定，速度也快得多。 第二种是单代理版本模式。当你需要把某一个确定版本地的代理部署到生产环境时，就要用这种模式了。在这个模式下，你会非常精确地指定出一个已提交的版本，并且把跟它关联的几个核心成员一起带上：BotVersion，也就是机器人本身的主体版本；GenAiPlannerBundle，它负责智能规划和决策；还有AiAuthingBundle，它管身份认证和授权。除了这三巨头，你还得把相关的支持元数据也一起声明出来，比如 Apex 类、Flow 流等等。这样一来，部署的内容就很聚焦，不会多也不会漏。 第三种叫版本不匹配模式。它的场景比较特殊：当你发现 AiAuthingBundle 的版本号跟 Bot 或 BotVersion 的版本号不一致时，就需要用这种模式来处理。举个例子，可能认证包不小心升了级，但机器人版本还没同步上去，这时部署就会遇到冲突。版本不匹配模式就是专门应对这种“不同步”情况的，它能帮你有针对性地处理好版本差异，保证部署顺利进行。 这里我还要特别强调一个命名惯例，大家一定要记清楚，因为很容易搞混。BotVersion，也就是机器人主版本，它的命名后缀是用点v加数字，比如 .v1、.v2。GenAiPlannerBundle 这个规划器包呢，它的后缀是下划线v加数字，像 _v1、_v2。而 AiAuthingBundle 认证包的后缀却只是下划线加数字，没有 v，比如 _1、_2。这三种不同的命名规则反映了它们各自的升级路径和依赖关系，千万不能写错，否则部署工具会识别不了。 最后，有一条黄金法则你要记住：无论你要部署哪个特定版本，都得先把完整代理部署上去，然后再去做版本的逐步更新。千万不要跳过“完整代理”这一步，直接去推送单个版本，那样很容易导致环境不一致或功能缺失。好，这三种模式和命名习惯你理解了吗？后续实操中再慢慢体会，这些原则会帮你在大型组织里避免很多麻烦。

  ▶ 播放视频 查看详情
• 7

  Troubleshoot Agentforce DX Issues

  第 170 页

  好，我们接下来看这一页幻灯片的内容。这一部分其实是在帮大家打预防针，告诉你一个现实：在使用 Agentforce DX 构建代理的过程中，你几乎不可能一帆风顺，各个阶段都可能蹦出问题。我们就像拼乐高一样，从生成创作捆绑包开始，再到写代理脚本，然后发布到组织，跟着跑测试，部署元数据……这一整套流程走下来，每个环节都藏着出错的可能。 这章呢，就是专门把这些最常见的问题汇集起来了，而且给出了对应的解决方案。它覆盖了哪些阶段呢？我给大家捋一捋： 首先是，环境设置，。这是最容易翻车的起点，可能你权限没配好，或者 Dev Hub 没启用，或者 CLI 没连上正确的开发环境，都是这种问题。 然后是，代理脚本错误，。我们写那个 `.agent` 文件时，语法拼错了，或者引用了不存在的主题、没定义的技能，甚至缩进不对，都会报错。 ，创作捆绑包问题，也挺常见，生成的时候可能因为源文件损坏，或者配置不完整，导致 bundle 打不出来。 ，发布阶段，，你觉得脚本写好了，想推送到组织里，结果网络问题、依赖版本冲突、或者元数据格式不兼容，也会失败。 ，同步/检索，，比如你想把组织里已经建好的代理拽回本地继续开发，发现拉不下来，或者拉下来的文件乱码了。 ，预览/调试，，你在 Agent Builder 里点预览，结果代理卡在那儿不动，或者回复驴唇不对马嘴，这都是调试时常遇到的问题。 最后是，测试，，我们写测试用例去验证代理行为，结果断言总是失败，或者找不到 mock 的数据。 你看，这么多环节，每个都有对应的坑。这章就是把这些坑一个一个指出来，然后把脱坑的方法教给你。所以你在后面实际动手的时候，如果遇到报错了，别慌，回到这里查一查，大概率能找到对症的解法。 好，这一页就讲到这里，我们继续往下。

  ▶ 播放视频 查看详情
• 8

  Setup, Script & Authoring Bundle Issues

  第 171 页

  同学们，咱们今天来看看在搭建 Agentforce 的时候，经常会碰到的一些环境设置小麻烦，以及怎么快速把它们搞定。 先说一个最常见的坑——明明跟着步骤走，结果代理脚本一验证就报错。很多时候，问题就出在缩进上，它跟写 YAML 文件特别像，多一个空格、少一个空格都会直接报错。另外还容易漏掉冒号，或者用了一些没提前声明好的变量，再或者写了 Agentforce 还不支持的表达式。那怎么办呢？你如果用的是 VS Code 插件开发，它会直接在报错的地方给你标出来，一眼就能看到哪里不对劲，改起来就很快。 还有种情况，脚本验证明明通过了，一预览却失败了。这个大概率是因为你那个配置块里，没有指定一个有效的默认代理用户，系统找不到谁来执行，自然就预览不出来。 再聊聊创作捆绑包的问题。如果你用生成的方式创建代理，结果发现生成了个空文件——这通常是因为缺少了代理规范。反过来，要是你写的规范太模糊，系统不知道你到底想让它做什么，那它生成的代理就很难用。所以现在咱们都推荐用创作捆绑包的工作流程来创建代理，不要再留恋以前那种老方法了，新的工作流更稳定，也更省事儿。 当然了，一切的前提是，你的组织里得先启用 Einstein 和 Agentforce 的功能，而且临时组织定义文件里得写对了功能开关，不然好多能力压根就没开起来。 把这些小地方都注意到了，后面你调试代理的时候能少走很多弯路。好，这页内容就说到这儿，大家有什么问题随时提。

  ▶ 播放视频 查看详情
• 9

  Publish, Sync & Preview Issues

  第 172 页

  同学们，咱们现在看的这一页，讲的是创作捆绑包在发布、同步、预览和调试时的一些关键点，都是实操里很容易踩坑的地方，我来给你细细说一下。 首先，最重要的一个提醒：发布创作捆绑包的时候，它是不会帮你把里面涉及的Apex类或者各种流（Flow）一块儿部署出去的。你一定要记得，在点击发布之前，先把这些Apex类和流单独部署好。要不然你的代理跑起来就会缺胳膊少腿，直接报错。所以顺序往往是：先部署Apex和流，再发布捆绑包。 接下来看同步的问题。有时候你会碰到代理的配置和捆绑包里的内容对不上，这时就需要用到一种带通配符的检索方式，也就是外卡，把所有版本的创作捆绑包都拉出来。然后，你再把那个叫AiAuthingBundle的东西，以及你的Bot和Bot版本的完整清单，统统对应到已经提交的代理上。这样就相当于做了一次全量对齐，保证代理身上挂的就是你最新设定的版本，不会落下什么组件。 再来说预览和调试。这里有一个特别容易混淆的地方。当你只是想快速验证一下代理的脚本对话逻辑，不希望它真的去执行任何操作——比如说调用外部接口、修改数据——你就选，模拟模式，。这个模式下，代理只动嘴皮子，不动手，测试起来很安全。但是，如果你要做完整的集成测试，希望用Apex Replay调试器一步一步跟踪代码执行，那就必须切换到，实时模式，。一定要记住，Apex调试器只在实时模式下才能工作，模拟模式里它是无效的。所以，一旦你要定位代码里的bug，先确认你是不是在实时模式，否则再怎么设断点也没用。 最后是管理预览会话。有时候你可能开了好几个预览窗口，系统里就会留下多个活跃的会话。这个时候你需要把活动会话都列出来，通过指定会话ID去操作。建议大家顺手把那些已经不用的会话及时停掉，免得它们占着资源，还可能跟新会话冲突，造成一些奇怪的错误。 好了，这页的要点就这么多。简单小结一下：发布前单独部署Apex和流，同步用外卡拿着清单对齐，模拟模式测逻辑、实时模式加调试器，多会话要记得清理。把这些细节记在心上，操作起来就不会手忙脚乱了。我们接着看下一部分内容。

  ▶ 播放视频 查看详情
• 10

  Testing & CI/CD Issues

  第 173 页

  同学们，今天咱们来聊聊在CI/CD流程里测试Agent时常见的一些坑和解决技巧。 首先，要测试Agent，你必须先把它，发布，出去。在持续集成这种自动化环境里，我们一般不采用网页登录，而是用，基于JWT的身份验证，，这样更安全也更适合机器对机器。同时要确保你的Agent是，已激活，的状态。有时候你会碰到Expressc测试超时的问题，别急着重跑，可以利用，代理测试恢复，功能来查询进度和状态，这样更聪明。 如果看到测试的，指标分数很低，，这往往说明你给Agent的指令或者动作描述太模糊了，它没理解清楚。这时候就要回头，优化措辞，，并且多用，Agent预览，去查看它的推理过程，看它到底卡在哪一步。 当测试脚本跑完，千万要检查一下，退出代码，，它能帮你分清到底是执行过程中出了错误，还是断言没通过。另外，一定要养成看，实际输出结果，的习惯，不要只看测试过没过。 最后给大家几个特别实用的提示：做之前先，验证你的组织，是否正确；代理发布后记得，刷新，一下；留意，临时组织的格式，有没有问题；还有，多利用VS Code里边的，“问题”选项卡，，语法错误一眼就能看到，能省好多时间。 这样一来，你在CI/CD里测试Agent时就能少踩雷，排查问题也更顺手。好了，这个要点咱们就先说到这里。

  ▶ 播放视频 查看详情