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):

```agentscript
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:

```agentscript
topic 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:

```agentscript
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

```agentscript
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

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

### Pattern 3: Personalized Recommendations

```agentscript
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:

```agentscript
# ❌ 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