The mechanism
An action = an API description (OpenAPI-shaped) + auth config + prompts metadata, packaged into an agent/plugin. At run time the model DECIDES to invoke it (matching the user's ask to the action's description), builds parameters from conversation context, calls YOUR endpoint, and weaves the response into the answer. Two properties follow:
- Invocation is probabilistic — descriptions are the interface; vague descriptions get your action called wrongly or not at all. Treat the description text as API design, not documentation garnish.
- Conversation context flows out — parameters are derived from what the user said (data-boundary concept's agent edge). The endpoint list IS the additional boundary; review it like a DLP destination.
Auth: the decision that shapes everything
| Pattern | Meaning | Use when |
|---|---|---|
| OAuth on-behalf-of the user | The API sees the actual user's identity/permissions | Line-of-business systems with real per-user authz — the default choice |
| Service identity (agent's own) | Everyone using the agent acts as ONE principal | Only with explicit scoping + audit; this is where 'the agent can do what no asker could' risk lives |
| API key | A shared secret pretending to be auth | Legacy only; vault it, rotate it, plan its funeral |
The review question that catches most issues: can the action let a user achieve something their own permissions would deny? If yes, that's not integration, that's privilege escalation with a chat UI.
Consequence design (write-actions especially)
Idempotency for retries (the model may re-invoke), confirmation prompts surfaced to the user before commits ('create this ticket?' — supported patterns exist; use them for writes), rate limits on your endpoint (a popular agent is a load test you didn't schedule), and structured errors (the model relays your error text — write it for humans).
What to watch (proofs)
- The egress registry: every action's endpoint + auth mode, exported — the agents-module registry's action column; this list answers 'where can conversation data travel'.
- Your API's own logs: calls arriving with expected identities (OBO users vs the agent principal) — the auth-pattern claim, verified server-side.
- The escalation test: a user without rights in the backend attempts the action through chat — denial proves the authz chain; success is a finding with a severity rating.
- Invocation quality: action-called-when-expected rates from agent run telemetry — mis-invocation clusters mean description rework (the probabilistic-interface tax, paid consciously).