Agentforce Prompt Builder 程序化访问与批处理指南
程序化访问 Prompt Template
Prompt Builder 让你创建和管理能整合 CRM 数据的提示模板（merge fields、flows、related lists、Apex）。有三种程序化访问方式：
| 方式 | 适用场景 | 关键接口 |
|---|---|---|
| Connect REST API | 外部 Web 应用集成 | Prompt Template Generations Resource。请求：指定模板 + 输入参数。响应：生成文本 + 引用（citations） |
| Connect in Apex | 组织内 Apex 代码集成 | ConnectApi.EinsteinLLM.generateMessagesForPromptTemplate()。传入开发者名称 + 输入参数，获取生成文本和可选引用（citationMode: 'post_generation'） |
| Invocable Actions | 平台级集成（Flow Builder 等） | Generate Prompt Response Invocable Action。从 Flow Builder、Process Builder 或其他可调用上下文中调用 |
跨组织部署：使用 Metadata API 的 GenAiPromptTemplate（模板定义）和 GenAiPromptTemplateActv（激活状态）在 Sandbox 和 Production 组织之间部署。
Prompt Template 批处理（Batch Processing）
使用AiJobRun和AiJobRunItem对象异步生成大规模响应。典型用例：夜间总结 Case 积压、批量内容生成、批量翻译、大规模记录充实。
三步批处理模式
步骤 1 — 创建 AiJobRun：
AiJobRun jobRun = new AiJobRun( JobType = 'PromptTemplate', Target = 'Summarize_Case', // DeveloperName 推荐用于跨组织可移植性 Status = 'New' ); insert as user jobRun;步骤 2 — 创建 AiJobRunItem 记录（每个输入记录一条）：
Map<String, Object> payload = new Map<String, Object>{ 'Input:Case' => new Map<String, Object>{ 'id' => c.Id } }; items.add(new AiJobRunItem( AiJobRunId = jobRun.Id, Status = 'Ready', Input = JSON.serialize(payload) )); insert as user items; // Input 格式: {"Input:Case":{"id":"<CaseId>"}} // Response 格式: {"promptResponse":"<LLM text>"}步骤 3 — 翻转为 ReadyToStart：
jobRun.Status = 'ReadyToStart'; update as user jobRun; // 此后不可更改（不可变性规则生效）关键约束
| 约束 | 说明 |
|---|---|
| 不可变性 | 一旦进入 InProgress，AiJobRunId/Input 字段不可更改，不能删除 |
| 状态变更 | InProgress、Completed、Failed —— 用户无法更改 |
| 速率限制 | 标准：1,000 条/AiJobRun；原生批处理模型：10,000 条/AiJobRun；Apex：最多 5 个 AiJobRun/24 小时 |
| 处理顺序 | 多个 ReadyToStart 作业按 CreatedDate 排列；如秒级内更新，精确顺序不保证 |
作业监控和平台事件
使用AiJobRunStatusEvent平台事件监控作业完成状态。事件在每个状态转换时触发：InProgress → Completed → Failed。
事件 Schema
AiJobRunIdentifier（父 Id）、Status、JobType、Target。
Trigger — 过滤 Completed 事件
trigger AiJobRunStatusEventTrigger on AiJobRunStatusEvent (after insert) { Set<Id> completedJobRunIds = new Set<Id>(); for (AiJobRunStatusEvent e : Trigger.new) { if (e.Status == 'Completed' && String.isNotBlank(e.AiJobRunIdentifier)) { completedJobRunIds.add((Id) e.AiJobRunIdentifier); } } // 调用 Handler }Handler — 处理已完成项目
- 查询 AiJobRunItem WHERE AiJobRunId IN :completedJobRunIds AND Status = 'Completed'
- 提取 Input JSON → 解析 caseId：
{"Input:Case":{"id":"<CaseId>"}} - 提取 Response JSON → 解包 promptText：
{"promptResponse":"<LLM text>"} - 将结果写回（如作为 CaseComment）
生产环境注意事项
- 去重：平台事件可能被重新投递 —— 按 AiJobRunId + ParentId 去重
- 失败处理：项目可能以 Status='Failed' 结束 —— 与成功记录一起查询
- 异步写回：对接近 10,000 条的限制，将写回操作转移到 Database.Batchable 或 Queueable
- 异常处理：始终捕获异常 —— 未捕获异常会导致事件批次失败；9 次重试后平台会禁用订阅
完整模式
- 创建 AiJobRun (New) → 2. 创建 AiJobRunItem 列表 (Ready) → 3. 更新为 ReadyToStart
- 订阅 AiJobRunStatusEvent (Completed) → 5. 处理结果：解析 Input 获取源记录 Id → 解析 Response 获取 LLM 文本 → 写回
Prompt Builder 从单个模板调用到数千条记录的批量处理，为你提供了强大、受管控的方式将生成式 AI 整合到 Salesforce 工作流中。
发布来源：Agentforce Prompt Builder 程序化访问与批处理指南 | Salesforce CRM 中文站