Skip to main content

Client actions

Client actions let the agent trigger behavior in the application that's embedding the agent SDK — your web app, mobile app, or WebView — rather than calling a backend API.

Use them when the side-effect lives in the client: navigating to a page, opening a modal, focusing an input, updating local UI state, or any other app-specific behavior that doesn't make sense as a server-side HTTP call.

How they work​

Client actions don't make network requests from Stellar. When the agent decides to call one, the SDK emits an actionExecuted event on the conversation. Your app listens for that event, reads the action's name and arguments from the payload, and decides what to do.

This means the agent and your app share an interface: the agent picks the action and supplies the arguments; your app implements the behavior. Stellar doesn't validate that an actionExecuted event was handled — that's the embedding application's responsibility.

Name and description​

The name and description are how the agent decides when to call the action. Pick names that describe what should happen in the app:

Name: navigate_to_orders
Description: Opens the orders page in the app. Use when the caller asks to see their orders or wants to make a change to an existing order.

The SDK delivers the name as actionName in the event payload. Your handler maps it to the corresponding app behavior.

Parameters schema​

Define a parameters schema for any arguments your app needs. The agent collects these from the conversation and sends them to the client; the SDK delivers them as requestBody (JSON) on the actionExecuted event.

{
  "type": "object",
  "properties": {
    "order_id": {
      "type": "string",
      "description": "The order ID to open, e.g. ORD-12345"
    }
  },
  "required": ["order_id"]
}

If a client action takes no parameters, leave the schema empty.

Handling the event in your app​

The SDK docs cover the event-handler pattern in detail — see Voice conversations and Text chat for examples. The shape is the same in both: subscribe to actionExecuted, switch on actionName, parse requestBody, and perform the side-effect.

Phase restriction​

Client actions are in-call only — they're emitted to the live SDK connection, so they can't fire during post-call wrap-up. The Conversation phases selector will only let you choose In call.

When to reach for a different type​

  • The action should happen on your backend, not in the client → use an API call.
  • The action should hang up the call → use an end call.
  • The action should transfer the caller → use a handover.

Next steps​