An action is something the agent does in your systems during a call. Actions are what make an agent worth deploying; without them you have a very expensive answering machine.

​
What an action looks like

An action has a name, a description of when to use it, and the information it needs. The agent decides when to call it based on the conversation.
The description is not decoration — it is how the agent decides whether this is the right moment. “Log a maintenance ticket” alone produces agents that log tickets before collecting anything useful.

​
Designing actions that work

Keep the parameter list short. Every required parameter is a question the caller must answer before anything happens. Three is comfortable, six is an interrogation. Make optional things optional. If the ticket can be logged without a floor number, do not require one. Agents are diligent about required fields and will keep asking. Name the moment in the description. “Use once you have X, Y, and Z” is more effective than any amount of instruction elsewhere. Return something the agent can say. An action that returns {"id": 4417} lets the agent read back a reference number. One that returns {"ok": true} leaves it with nothing useful to confirm.
Design the return value for speech. The agent reads it aloud, so a long identifier like TCK-2026-08-A4417-XZ is painful over the phone. Short numeric references work far better.

​
Read actions and write actions

Read actions fetch information — order status, account balance, opening hours. They are safe to call speculatively and can run early in a call. Write actions change something — creating a ticket, cancelling an order. They deserve more care. Have the agent confirm before calling a write action that is hard to reverse:

​
Failure handling

Actions fail — your system is down, the record does not exist, the request times out. Say what the agent should do:
An agent that has not been told how to handle a failure will improvise, and the improvisation is often a confidently invented reference number. Always specify the failure path for write actions.

​
Latency

Every action happens while the caller waits in silence. Under about a second is unnoticeable; beyond two or three seconds the caller starts wondering whether the line dropped. For slow actions, have the agent say what it is doing before calling — “let me check that for you” buys several seconds of natural silence. See Latency.

Writing instructions

Instructions decide when actions fire.

Handoff

The action every line needs.