agent-action-input-slot-extraction

# 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

1. List every invocable input the action exposes. For each, ask: what's the canonical type? what synonyms or formats might appear? is it required?
2. Write a **specific** description per input. Include format, examples, reject clauses. Treat the description as the LLM's instruction manual for that slot.
3. Build a sample-utterance test set: 10–20 utterances per slot covering typical, edge-case, and adversarial phrasings.
4. For required slots, configure a re-prompt template that names the missing slot and gives an example.
5. 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?).
6. Run the test utterances through the agent test harness (Agent Builder → Test in App). Record extraction accuracy per slot.
7. Iterate on the descriptions until extraction accuracy crosses your bar (typically ≥95% for high-stakes actions, lower for low-stakes).

---

## Review Checklist

- [ ] Each input has a description that includes format + examples + reject clauses
- [ ] Picklist/enum inputs enumerate values with synonym disambiguation
- [ ] Lookup/Id inputs are taken as names, resolved inside the action
- [ ] Required-slot re-prompts configured with slot name and example
- [ ] Test-utterance suite covers ≥10 utterances per slot
- [ ] Accuracy measured and meets the action's stakes

---

## Salesforce-Specific Gotchas

1. **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.
2. **Date inputs default to the running user's timezone** — "next Tuesday" relative to which timezone? Specify in the description.
3. **Required + no value extracted = agent emits a built-in re-prompt** — Often phrased awkwardly. Always override.
4. **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.
5. **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