afv-library/skills/developing-agentforce/references/action-prompt-templates.md

Prompt Template Actions

Invoking Salesforce Prompt Templates as actions within Agent Script.

---

Overview

Prompt Template Actions let agents invoke Salesforce Prompt Templates via the generatePromptResponse:// protocol. The agent passes structured inputs to the template and receives a generated promptResponse output — keeping content generation in the template while the agent manages conversation flow.

When to use: Personalized responses, summarization, content generation, recommendations — anything where an LLM prompt template produces better output than static Flow logic.

---

Action Definition (Agentforce Assets)

Define the action in Setup > Agentforce > Action Definitions (or via metadata API):

actions:
  Generate_Personalized_Schedule:
    description: "Generate a personalized schedule using a prompt template"
    inputs:
      "Input:email": string
        description: "User's email address"
        is_required: True
      "Input:preferences": string
        description: "User's scheduling preferences"
        is_required: False
    outputs:
      promptResponse: string
        description: "The personalized schedule generated by the template"
        is_used_by_planner: True
    target: "generatePromptResponse://Generate_Personalized_Schedule"

Critical syntax rules

Rule	Example
Target protocol	"generatePromptResponse://TemplateName"
Input names must be quoted	"Input:email" not Input:email
Input prefix is Input:	Matches the template's input field API name
Output field is always promptResponse	Single string output from the template

---

Agent Script Invocation

Reference the action definition in your .agent file:

subagent schedule_generation:
  reasoning:
    actions:
      generate_schedule: @actions.Generate_Personalized_Schedule
        with "Input:email"=@variables.user_email
             "Input:preferences"=...
        set @variables.schedule = @outputs.promptResponse

Input binding patterns (same as regular actions):

• @variables.user_email — variable binding (data from prior turns)
• ... — LLM slot-filling (extract from conversation)
• "professional" — fixed value (business rule constant)

---

Grounded Data Integration

Templates can include data providers (Apex classes, Flows) that supply contextual data for personalized responses. The grounding happens inside the template — Agent Script only needs to pass the lookup key:

actions:
  Get_Product_Recommendations:
    description: "Generate personalized product recommendations based on purchase history"
    inputs:
      "Input:customerId": string
        description: "Customer ID for personalization"
        is_required: True
    outputs:
      promptResponse: string
        description: "Personalized recommendations grounded in customer data"
    target: "generatePromptResponse://Product_Recommender"

The template itself (configured in Prompt Builder) includes:

• Data Provider: Apex class fetching customer purchase history
• Grounding: Recent orders, preferences, browsing history
• Template instructions: How to format recommendations using the grounded data

---

Common Patterns

Pattern 1: Content Generation

generate_email: @actions.Generate_Email_Response
  with "Input:customerMessage"=@variables.user_message
       "Input:tone"="professional"
       "Input:context"=@variables.case_context
  set @variables.email_draft = @outputs.promptResponse

Pattern 2: Summarization

summarize: @actions.Summarize_Conversation
  with "Input:conversationHistory"=@variables.chat_history
       "Input:maxLength"="500"
  set @variables.summary = @outputs.promptResponse

Pattern 3: Personalized Recommendations

recommend: @actions.Get_Product_Recommendations
  with "Input:customerId"=@variables.customer_id
       "Input:category"=...
  set @variables.recommendations = @outputs.promptResponse

---

Known Limitation: run Keyword with Prompt Templates

Chained actions using run may not properly map "Input:X" parameters:

# ❌ MAY NOT WORK — run + prompt template input binding:
process: @actions.create_order
  with customer_id=@variables.customer_id
  run @actions.Generate_Order_Summary
    with "Input:orderId"=@variables.order_id    # Input binding may fail

# ✅ WORKAROUND — call as primary action instead:
generate_summary: @actions.Generate_Order_Summary
  with "Input:orderId"=@variables.order_id      # Works as primary action
  set @variables.summary = @outputs.promptResponse

---

Common Errors

Error	Cause	Fix
SyntaxError on input binding	Missing quotes on parameter name	Use "Input:email" not Input:email
Template not found	Wrong protocol or template name	Verify generatePromptResponse://ExactTemplateName
Empty promptResponse	Template inactive or missing required inputs	Activate template in Setup, check all is_required: True inputs are bound
Input not mapped	API name mismatch	Input field name after Input: must exactly match template's input API name

---

Checklist

• Template exists in org and is active
• Input field API names match template configuration exactly
• All is_required: True inputs are bound (via ..., @variables, or fixed)
• promptResponse output is captured with set
• Template response quality tested with representative inputs
• If using grounded data: data provider returns expected records