Actions

Actions are operations your agent can perform during a conversation. They cover everything from calling an external API and sending an SMS, to transferring the caller to a human, to ending the call.

Types of actions

Stellar supports six action types:

Type	What it does
API call	Fetches or updates data in an external system over HTTP — e.g., looking up an order or creating a ticket
Static response	Returns fixed text the agent can read out consistently, such as business hours or a policy snippet
Handover	Transfers the conversation to a human agent over phone or SIP
Send text message	Sends an SMS through a messaging channel
End call	Hangs up the call when the conversation is naturally over
Client action	Emits a typed event to the application embedding the agent SDK

Shared and agent-specific actions

Actions live in one of two places:

• Shared actions live under a Custom API or MCP integration. Any agent can link a shared action, and when you change it, every agent linking it picks up the change.
• Agent-specific actions live on a single agent. They're the right home for behaviors that aren't external services, like static responses, end-call rules, agent-specific handover scripts, and client events, plus one-off API calls that will only ever be used by this one agent.

Not sure which to reach for? See choosing between them.

Add an action

Open the agent's Actions tab and click + Add action. The picker shows two paths:

• Pick a source to link a shared action from one of your integrations.
• Add an agent specific action to create an agent-local action. You'll pick the type (API call, static response, handover, etc.) and fill in the configuration.

When you add a shared action, the linked action will use the integration's URL, auth, and any output variables defined on it. You can still override per-agent fields on the binding (see below).

Per-agent fields on shared actions

A shared action's name, description, URL, method, headers, and output variables are owned by the integration. Each agent that links it can override:

• Parameters schema — what the agent collects before calling
• Request body template — how parameters and conversation variables are shaped into the request
• Conversation phases — when the action is available
• Allowed states — which states can call the action
• Max successful calls per conversation — how many times the action can complete

These overrides are per-binding — changing them on one agent doesn't affect any other agent linking the same shared action.

Restricting action access per state

By default, actions are globally accessible — they can be called from any state. When you enable strict state separation, you must explicitly configure which states each action is available in. This prevents actions from being called in unintended conversation contexts.

For example:

• process_refund should only be available in the "Billing Support" state
• create_support_ticket should only be available in the "Technical Support" state
• transfer_to_human should be available in all states — leave it unrestricted

Action access is configured from the Dialogue Builder. With strict state separation enabled, click on a state, then select which actions are available in Available actions for this step. When viewing an action in the action editor, you can see which states it's restricted to, but you can only edit this from the state editor.

warning

When enabling strict state separation, actions remain globally accessible by default. You must explicitly restrict each action to the appropriate states, otherwise the agent may call them from states where they don't make sense. See what to do after enabling strict state separation.

Limiting executions per conversation

The Max successful calls per conversation setting caps how many times an action can complete successfully within a single conversation. Use this to prevent duplicate side-effects — for example, ensuring a create_case action only creates one case per conversation, even if the agent attempts to call it again.

• Set a limit between 1 and 1000. Leave the field empty for unlimited.
• Only successful executions count toward the limit. For API call actions, this means calls that received a 2xx response — failed calls (4xx, 5xx, network errors) don't consume a slot.
• Once the limit is reached, subsequent calls return an error to the agent, which can explain to the caller that the action has already been completed.
• The counter resets with each new conversation.

When to use it:

• Preventing duplicate operations: Set to 1 for actions that create records, process payments, or trigger workflows that should only happen once.
• Capping retries: Set to 2 or 3 for actions where a few retries are acceptable but unlimited calls would be problematic.

Best-effort guard

This limit is enforced in-memory during the conversation. For operations where duplicate execution would be critical (e.g., payment processing), also implement idempotency at your API level using idempotency keys.

Action availability by conversation phase

Each action has a Conversation phases setting that controls which phases it can be used during:

Phase	When it applies
In call	During the live call, while the caller is connected
Post-call	After the caller disconnects, during post-conversation wrap-up tasks

By default, new actions are available during the In call phase only. To allow an action during wrap-up — for example, an API call that logs the conversation outcome to your CRM — select Post-call in the Conversation phases multi-select.

Restrictions:

• End call and Handover actions can only be used during the In call phase — they can't run post-call since the caller has already disconnected.
• At least one phase must be selected.

Testing actions

Test each action in the Playground by having a conversation that triggers the action. The event feed shows when the action was called, what parameters were sent, what response was received, and any errors that occurred.

Common issues:

• Agent doesn't call the action — The description may be unclear, the agent may lack enough context, or the action is restricted to the wrong states.
• API errors — Check the URL, credentials, and that the parameter schema matches what your API expects.
• Wrong parameters sent — Refine the parameter descriptions in the schema and review the conversation to see what the customer provided.

Best practices

Name actions clearly. Use descriptive names that say what the action does: get_order_status, create_support_ticket, cancel_subscription — not action1 or api_call.

Write detailed descriptions. The description is how the agent decides when to call an action. Be specific about what it does, when to use it, and what information it needs.

Keep actions focused. Each action should do one thing well. If an API handles multiple operations, create separate actions for each.

Chain actions for multi-step workflows. Use output variables to pass data between actions. For example, a lookup_customer action can store the returned customer_id, which a subsequent get_orders action then uses.

Use secrets for credentials. Never hardcode API keys in URLs or headers — store them as secrets and reference them from your integration's auth or from the action's headers.

Next steps

• Integrations — connect external services and define shared actions
• Guardrails — keep actions in safe bounds
• Evaluation rules — automatically assess conversation quality
• Review conversations — see how actions are being used in real conversations