Invocable Apex: writing actions worth trusting

The previous lesson called out the backing-action layer as the truth source. This lesson is about what makes one trustworthy. Backing actions are how the agent does anything real. The shape Agent Script expects is Invocable Apex in three pieces:

public with sharing class VerifyCustomer {

    // 1. Input class. Every field is @InvocableVariable.
    public class ActionInput {
        @InvocableVariable(required=true)
        public String email;
    }

    // 2. Output class. Same pattern.
    public class ActionOutput {
        @InvocableVariable public String customer_id;
        @InvocableVariable public String verified;
    }

    // 3. The invoke method. Bulk shape: list-in, list-out.
    @InvocableMethod(label='Verify Customer'
        description='Verifies a customer by email...')
    public static List<ActionOutput> invoke(List<ActionInput> inputs) {
        List<ActionOutput> results = new List<ActionOutput>();
        for (ActionInput inp : inputs) {        // not "in" (reserved!)
            ActionOutput out = new ActionOutput();
            // ... real logic ...
            results.add(out);
        }
        return results;
    }
}

The four rules

1. Always bulk. List<Input> to List<Output>. The framework passes one input at a time in practice, but the contract must be lists.
2. Reserved names. Loop variable cannot be in (Apex reserved keyword). @InvocableVariable field names cannot be model, description, or label.
3. Truthful nulls. Return '' for "not found" and 'false' for "no". Not 'stub_response' or 'TODO'. Placeholder strings cause what the trace logs as SMALL_TALK grounding: the LLM decides the output looks bogus and falls back to its training prior instead of the actual return value.
4. Deterministic. Given the same input, return the same output. The planner caches and re-uses results in the same turn.

Backing actions must be conservative. If they can lie even by accident, every defensive layer above them is built on sand.