Skip to main content

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:

TypeWhat it does
API callFetches or updates data in your external systems in real-time — for example, looking up order details or checking account balances
Static responseReturns fixed text the agent can share consistently, such as business hours or policy details
HandoverTransfers 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 available in every state. You can restrict which states can use a particular action using strict state separation. This prevents inappropriate action usage in certain 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)

Action access is configured from the Dialogue Builder: 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.

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​