Actions

Actions are operations your agent can perform during conversations. They allow your agent to interact with external systems, provide structured responses, or transfer conversations to human agents.

Types of actions

Stellar supports three types of actions:

Type	What it does
API call	Fetches or updates data in your external systems in real-time — for example, looking up order details or checking account balances
Static response	Returns fixed text the agent can share consistently, such as business hours or policy details
Handover	Transfers the conversation to a human agent via phone or queue

Creating an action

1. Navigate to the Actions tab on your agent
2. Click Add Action
3. Select the action type
4. Configure the action settings

Restricting action access per state

By default, all 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 should be available in. This prevents actions from being called in unintended conversation contexts.

Example restrictions:

• 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 unrestricted / globally accessible)

Action access is configured from the Dialogue Builder. With Strict State Separation enabled, click on a state, then select which actions are available in the Available actions for this step section. 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, remember that actions remain globally accessible by default. You must explicitly restrict them to the appropriate states — otherwise the agent may call actions from states where they don't make sense. See what to do after enabling strict state separation.

Limiting executions per conversation

You can limit how many times an action can complete successfully within a single conversation using the Max successful calls per conversation setting. This prevents duplicate side-effects — for example, ensuring a create_case action only creates one case per conversation, even if the AI attempts to call it again.

How it works:

• 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 receive a 2xx HTTP response — failed calls (4xx, 5xx, network errors) do not consume a slot.
• Once the limit is reached, subsequent calls return an error to the agent, which can then 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

:::note 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 conversation 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 cannot be enabled for 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 — always use Secrets management (Manage > Secrets).

Next steps

• Configure API connections to share base URLs and auth across multiple actions
• Set up guardrails to ensure safe action usage
• Set up evaluation rules to automatically assess conversation quality
• Review conversations to see how actions are being used