|
| 1 | +--- |
| 2 | +title: "Frontend Actions" |
| 3 | +sidebarTitle: "Frontend Actions" |
| 4 | +description: "Enable your agent to trigger client-side behaviors like opening modals, navigating pages, or displaying notifications." |
| 5 | +--- |
| 6 | + |
| 7 | +import { Callout } from 'mintlify'; |
| 8 | + |
| 9 | +## What are Frontend Actions? |
| 10 | + |
| 11 | +Frontend Actions allow your AI agent to trigger client-side behaviors in your application. Instead of just responding with text, the agent can initiate UI interactions—opening modals, navigating to pages, showing notifications, or calling custom functions in your app. |
| 12 | + |
| 13 | +## How Frontend Actions Work |
| 14 | + |
| 15 | +When the agent determines a frontend action should be triggered, it invokes the action as a tool call. Your client application receives this via the SDK's real-time events. The tool call events include the trigger function identifier and any parameters, which your app interprets and executes. |
| 16 | + |
| 17 | +## Adding a Frontend Action |
| 18 | + |
| 19 | +1. In Agent Builder, open the **Tools** section. |
| 20 | +2. Switch to the **Frontend Actions** tab. |
| 21 | +3. Click **+ Add Frontend Action**. |
| 22 | +4. Configure the action: |
| 23 | + - **Name*** – display name for the action (e.g., "Open Settings Modal") |
| 24 | + - **Description*** – explain what the action does so the agent knows when to use it |
| 25 | + - **Trigger Function*** – the function or method identifier your client app will handle (e.g., `openSettingsModal`) |
| 26 | + - **Parameters** – optional parameters the action accepts |
| 27 | +5. Save to register the action. |
| 28 | + |
| 29 | +## Using Frontend Actions |
| 30 | + |
| 31 | +### Enable/Disable per Agent |
| 32 | + |
| 33 | +Each frontend action has a toggle to enable or disable it for the current agent. Once enabled, the agent can use the action based on its description—even without explicit mention in instructions. |
| 34 | + |
| 35 | +### Referencing in Instructions (Optional) |
| 36 | + |
| 37 | +While enabled actions are automatically available to the agent, you can reference them in instructions to provide additional context about when to use them. This helps the agent make better decisions, especially when: |
| 38 | + |
| 39 | +- Multiple actions could apply to similar situations |
| 40 | +- You want to specify exact conditions for triggering an action |
| 41 | +- The action description alone may not capture all nuances |
| 42 | + |
| 43 | +To insert an action reference: |
| 44 | + |
| 45 | +1. Type `@` in the Instructions Editor. |
| 46 | +2. Navigate to the **Frontend Actions** category. |
| 47 | +3. Select an action to insert a reference. |
| 48 | + |
| 49 | +**Syntax:** `@action:triggerFunctionName` (e.g., `@action:openModal`) |
| 50 | + |
| 51 | +<Callout type="tip"> |
| 52 | +You can also copy the syntax from the Frontend Actions list and paste it directly into the Instructions Editor. |
| 53 | +</Callout> |
| 54 | + |
| 55 | +## Registering Frontend Actions |
| 56 | + |
| 57 | +To handle these tool calls, register your action handlers with the UIKit component. Create a mapping of action names to callback functions, where each key matches a trigger function defined in your agent's configuration, and each value is a function that executes when that action is invoked. |
| 58 | + |
| 59 | +Pass this mapping to the message list or AI assistant chat component using the `aiAssistantTools` property (or equivalent setter method depending on your platform). When the agent triggers a tool call, UIKit automatically routes it to your registered handler, passing along any arguments the agent provided. |
| 60 | + |
| 61 | +This approach lets you: |
| 62 | + |
| 63 | +- Dynamically update UI elements based on agent decisions |
| 64 | +- Trigger navigation, modals, or other app-specific behaviors |
| 65 | +- Execute business logic in response to conversational context |
| 66 | + |
| 67 | + |
| 68 | +## Common Use Cases |
| 69 | + |
| 70 | +- **Navigation** – guide users to specific pages or sections |
| 71 | +- **Modals/Dialogs** – open forms, confirmations, or detail views |
| 72 | +- **Notifications** – display success messages or alerts |
| 73 | +- **Form Actions** – pre-fill forms or trigger submissions |
| 74 | +- **UI State** – toggle sidebars, expand sections, or change views |
| 75 | + |
| 76 | +## Orphaned Actions |
| 77 | + |
| 78 | +If a frontend action is deleted, renamed, or disabled after being referenced in instructions, it will display with a warning indicator. Update your instructions to use the correct action name or remove the orphaned reference. |
| 79 | + |
| 80 | +## Best Practices |
| 81 | + |
| 82 | +- Write clear descriptions so the agent understands when to trigger each action. |
| 83 | +- Use consistent naming conventions for trigger functions across your app. |
| 84 | +- Handle missing or invalid parameters gracefully in your client code. |
| 85 | +- Test actions in the Test console to verify the agent triggers them appropriately. |
| 86 | +- Keep the number of actions manageable—too many options can confuse the agent's decision-making. |
0 commit comments