Prompt Builder 程序化访问+批处理指南 | AiJobRun 完整 Apex 代码

Prompt Builder 概述

Prompt Builder 简化用户日常任务——将生成式 AI 驱动的提示词模板集成到工作流中。创建和管理合并 CRM 数据的提示词模板（记录字段、Flow、相关列表、Apex）。在记录页面启用生成式体验，或构建 Agentforce Actions 来生成摘要、描述和其他字段值。

本文介绍编程式调用提示词模板、批量处理和通过 Metadata API 在 Org 之间迁移模板。

编程式访问 Prompt Templates

访问方式	API/方法	适用场景
Connect REST API	Prompt Template Generations 资源	第三方 Web 应用集成
Connect in Apex	`ConnectApi.EinsteinLLM` 类	Apex 代码中调用模板（同步）
Invocable Actions	Generate Prompt Response Action	Flow/Process Builder 中调用
Metadata API	`GenAiPromptTemplate` + `GenAiPromptTemplateActv`	Sandbox ↔ Production Org 迁移模板

参考资源：Prompt Template Generations Resource、EinsteinLLM Class、Generate Prompt Response Invocable Action。

Prompt Template 批处理

使用 Prompt Template Batch Processing 异步生成大量提示词模板响应。适用于不阻塞用户交互的后台场景——例如每晚对 Service Cloud Case 积压进行摘要处理。

核心对象：AiJobRun（批处理任务）和 AiJobRunItem（单个输入项）。Status 生命周期：New → Ready → ReadyToStart → InProgress → Completed/Failed。

三步批处理模式与注意事项

前提：Prompt Template（DeveloperName=Summarize_Case）已存在，声明 Case SObject 输入变量。用户分配 Prompt Template User 权限集。

Step 1：创建 AiJobRun

AiJobRun jobRun = new AiJobRun(
    JobType = 'PromptTemplate',
    Target  = 'Summarize_Case',  // Prompt Template DeveloperName（推荐，跨 Org 稳定）
    Status  = 'New'
);
insert as user jobRun;

Step 2：创建 AiJobRunItem 列表

List cases = [SELECT Id FROM Case LIMIT 200];
List items = new List();
for (Case c : cases) {
    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;

Step 3：启动批处理

jobRun.Status = 'ReadyToStart';
update as user jobRun;
// 提交后不能再修改 jobRun 或 items

关键注意事项

类别	规则
不可变性	状态变为 InProgress 后：不能改 AiJobRunId 和 Input、非 null 字段（status 除外）不能改、不能删除 AiJobRun 或其 Items
状态限制	InProgress/Completed/Failed 三种状态用户不可更改。启动批处理需将状态设为 ReadyToStart
速率限制	每个 AiJobRun 最多 1,000 Items（原生批处理模型 10,000）；Apex 中 24 小时内最多启动 5 个 AiJobRun
处理顺序	多个 ReadyToStart 的 AiJobRun 按 CreatedDate 时间顺序处理。但间隔数秒内更新时顺序可能不严格

提示：第三步必须在同一 Apex 事务中完成。对于接近 10,000 条上限的运行，用 Database.Batchable 包装 Step 2。

Job Monitoring 与 Platform Events

平台在状态变为 InProgress/Completed/Failed 时发布 AiJobRunStatusEvent。通过 Platform Event Trigger 订阅并过滤 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);
        }
    }
    if (!completedJobRunIds.isEmpty()) {
        AiJobRunStatusEventHandler.handleCompletedJobs(completedJobRunIds);
    }
}

Handler 处理逻辑

查询已完成的 AiJobRunItem → 解析 Input JSON（{"Input:Case":{"id":"<CaseId>"}}）提取源记录 ID → 解析 Response JSON（{"promptResponse":"<LLM text>"}）提取生成文本 → 写入目标对象（如 CaseComment）：

public static void handleCompletedJobs(Set completedJobRunIds) {
    List items = [SELECT Id, Input, Response FROM AiJobRunItem
        WHERE AiJobRunId IN :completedJobRunIds AND Status = 'Completed'];
    for (AiJobRunItem item : items) {
        String text = extractPromptResponse(item.Response);  // 解析 {"promptResponse":"..."}
        Id caseId = extractCaseId(item.Input);               // 解析 {"Input:Case":{"id":"..."}}
        if (text != null && caseId != null) {
            comments.add(new CaseComment(ParentId=caseId, IsPublished=false, CommentBody=text.left(3500)));
        }
    }
    insert as system comments;
}

JobType 取值：Apex 创建 → PromptTemplate；Flow（Prompt Template Batch Generation action）→ GeneratePromptAsyncIA。

生产环境注意：Platform Events 可重复投递——Handler 应去重（按 AiJobRunId+ParentId）。单独 Items 可能以 Failed 状态完成，应查询并表面化而非静默跳过。对于接近 10,000 条上限的运行，将写回操作放入 Database.Batchable 或 Queueable。

Agentforce Prompt Builder 程序化访问与批处理指南