Agent Action Input Slot Extraction
Activate when the agent invokes an Apex/Flow action correctly but with the wrong arguments — date misread, account id missing, picklist value paraphrased, phone number truncated. The skill produces tuned input-variable descriptions, utterance-level test cases, and a re-prompt policy for ambiguous or missing inputs.
Before Starting
Gather this context before working on anything in this domain:
- The action's invocable definition: each input variable's
name, type, description, and required flag. The description is the primary signal the LLM uses to extract values; vague descriptions → wrong slots.
- Real user utterances. Synthetic test cases miss the verbal patterns users actually produce ("schedule it for next Tuesday afternoon, ish").
- Whether the action is a one-shot invocation or part of a multi-turn flow. Multi-turn allows re-prompts; one-shot must succeed-or-fail with the first utterance.
Core Concepts
How slot extraction works
When the agent recognizes that an action should be invoked, it constructs an LLM prompt containing:
- The action's invocable input variables and their descriptions
- The user's utterance(s)
- The conversation context
The LLM extracts values for each input variable and validates them against the input type. Missing required inputs trigger a re-prompt cycle.
The description field is the lever. A description like "Date" gets misread for any date in the utterance. "The customer's preferred appointment date in ISO 8601 (YYYY-MM-DD); reject relative phrases like 'next week'" constrains extraction.
Types and coercion
| Input type | Extraction behavior | Common failure |
|---|
Date | LLM parses natural language → ISO date | "next Tuesday" parses inconsistently across timezones |
DateTime | Same + time-of-day | Vague times ("afternoon") get pinned to noon by default |
String | Free-form | Verbose users put unrelated content in the slot |
Picklist (Apex enum / Flow choice) | LLM matches utterance to one of the values | Synonyms get rejected unless described |
Id (lookup) | LLM extracts a name; the action must resolve to an Id | LLM hallucinates IDs starting with valid prefixes |
Boolean | Affirmative/negative cues | Negation in mid-sentence ("no, wait, yes") |
Re-prompt strategy
When a required slot can't be extracted, the agent re-prompts: "What date should I schedule the appointment for?". The re-prompt template should be configured per input. Without configuration, the agent generates a generic prompt that often confuses the user.
For ambiguous extraction (two plausible values), the better pattern is to confirm: "Did you mean Tuesday March 12 or March 19?".
Common Patterns
Pattern: explicit format constraint in description
When to use: Date, datetime, phone, id, anything with a canonical format.
How it works: Description includes the format and an explicit reject clause. "Account record ID; must be exactly 18 alphanumeric characters starting with '001'. Reject names or fragments."
Why not the alternative: A description of "Account ID" alone causes the LLM to hallucinate IDs from account names.
Pattern: enumerate picklist values inline
When to use: Apex enum or Flow choice as input.
How it works: Description lists every valid value with disambiguation. "Severity: one of LOW (cosmetic, no impact), MEDIUM (workaround exists), HIGH (production blocked). Synonyms: 'critical' = HIGH; 'minor' = LOW."
Why not the alternative: Without enumeration, the LLM matches user phrasing to the closest type member, often wrong ('urgent' → MEDIUM when policy says HIGH).
Pattern: name-to-Id resolution outside the LLM
When to use: Action takes a record Id but users speak in names.
How it works: Define the input as a String accountName. Inside the Apex/Flow action, resolve to Id via SOQL with proper escaping and ambiguity handling. Never let the LLM emit IDs.
Decision Guidance
| Situation | Recommended Approach | Reason |
|---|
| User must specify an exact date | Date input + ISO-format description + reject relatives | Relative phrasing parses inconsistently |
| Action takes a lookup record | String name input; Apex resolves to Id | LLMs hallucinate IDs; resolution belongs in Apex |
| Required slot may be missing | Configure re-prompt text per input | Generic re-prompt confuses users |
| Multiple plausible values for a slot | Disambiguate via confirmation prompt before action | Action with wrong slot is worse than slow action |
| Free-form note text | String with no constraint description | LLM extracts the user's verbatim sentence; no extraction logic needed |
Recommended Workflow
- List every invocable input the action exposes. For each, ask: what's the canonical type? what synonyms or formats might appear? is it required?
- Write a specific description per input. Include format, examples, reject clauses. Treat the description as the LLM's instruction manual for that slot.
- Build a sample-utterance test set: 10–20 utterances per slot covering typical, edge-case, and adversarial phrasings.
- For required slots, configure a re-prompt template that names the missing slot and gives an example.
- For lookup-type slots, change the input from
Id to String <name> and resolve inside the action; document the lookup ambiguity policy (first match? prompt for clarification? abort?).
- Run the test utterances through the agent test harness (Agent Builder → Test in App). Record extraction accuracy per slot.
- Iterate on the descriptions until extraction accuracy crosses your bar (typically ≥95% for high-stakes actions, lower for low-stakes).
Review Checklist
Salesforce-Specific Gotchas
- Description text is the primary lever; the variable name is secondary —
String d with description "appointment date" extracts as well as String appointmentDate with the same description. Don't rely on naming.
- Date inputs default to the running user's timezone — "next Tuesday" relative to which timezone? Specify in the description.
- Required + no value extracted = agent emits a built-in re-prompt — Often phrased awkwardly. Always override.
- Hallucinated IDs validate as the right shape but reference no record — Apex must check existence and surface a clear error to the agent loop, not silently fail.
- Picklist values must match exactly — The LLM may emit "high" when the picklist value is "HIGH". Apex enum coercion fails. Normalize case in the action.
Output Artifacts
| Artifact | Description |
|---|
| Tuned invocable input definitions | Updated description= strings on every input |
| Test-utterance suite | YAML/CSV: utterance → expected slot values |
| Re-prompt template per slot | Per-input override of the generic agent re-prompt |
| Resolution policy for lookup inputs | Documented in the action's class header |
Related Skills
- agentforce/agent-actions — for the broader action design and invocation flow
- agentforce/agentforce-tool-use-patterns — for when an action call leads into another tool call
- agentforce/agentforce-eval-harness — for measuring extraction accuracy at scale
- agentforce/custom-agent-actions-apex — for Apex implementation patterns of name-to-Id resolution