程序化访问 Prompt Template 的完整指南
Prompt Builder 的功能远不止创建单个模板，它提供了三种程序化访问方式，让你轻松将 CRM 数据（如合并字段、流程、关联列表、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 payload = new Map{
'Input:Case' => new Map{ 'id' => c.Id }
};
items.add(new AiJobRunItem(
AiJobRunId = jobRun.Id,
Status = 'Ready',
Input = JSON.serialize(payload)
));
insert as user items;
// Input 格式: {"Input:Case":{"id":""}}
// Response 格式: {"promptResponse":""} 步骤 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 监听 AiJobRunStatusEvent，仅处理 Completed 状态的事件：
trigger AiJobRunStatusEventTrigger on AiJobRunStatusEvent (after insert) {
Set completedJobRunIds = new Set();
for (AiJobRunStatusEvent e : Trigger.new) {
if (e.Status == 'Completed' && String.isNotBlank(e.AiJobRunIdentifier)) {
completedJobRunIds.add((Id) e.AiJobRunIdentifier);
}
}
// 调用 Handler
} Handler — 处理已完成项目
Handler 的核心逻辑非常清晰：
- 查询
AiJobRunItem WHERE AiJobRunId IN :completedJobRunIds AND Status = 'Completed' - 提取 Input JSON → 解析 caseId：
{"Input:Case":{"id":""}} - 提取 Response JSON → 解包 promptText：
{"promptResponse":""} - 将结果写回，例如作为 CaseComment
生产环境注意事项
真正上线时，有几个常见陷阱需要提前规避：
- 去重：平台事件可能被重新投递，务必按
AiJobRunId + ParentId进行去重。 - 失败处理：项目可能以
Status='Failed'结束，查询时需同时处理成功和失败的记录，避免遗漏。 - 异步写回：如果接近 10,000 条限制，建议将写回操作转移到
Database.Batchable或Queueable，防止超时。 - 异常处理：始终捕获异常——未捕获的异常会导致整个事件批次失败；平台会重试 9 次，之后直接禁用订阅，一旦错过则无法恢复。
完整工作流
将整个流程串联起来，就是一条清晰的流水线：
- 创建 AiJobRun (New) →
- 创建 AiJobRunItem 列表 (Ready) →
- 更新为 ReadyToStart →
- 订阅 AiJobRunStatusEvent (Completed) →
- 处理结果：解析 Input 获取源记录 Id → 解析 Response 获取 LLM 文本 → 写回
从单个模板调用到数千条记录的批量处理，Prompt Builder 提供了一套既强大又受控的方式，将生成式 AI 无缝嵌入 Salesforce 工作流。只要掌握这些接口和约束，你就可以放心让 AI 在后台自动处理大量重复性任务，真正释放生产力。