Install & Compatibility
Where this runs
tested against v3.16.1 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 0.596s · 88.5MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 10.4s · import 0.531s · 86MB
91MB installed
● package 91MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Action
✓ from rasa_sdk import Action
✗ from rasa_sdk.actions import Action
Action is directly exported from the top-level rasa_sdk package since 2.x.
CollectingDispatcher
✓ from rasa_sdk.executor import CollectingDispatcher
✗ from rasa_sdk.dispatcher import Dispatcher
The primary dispatcher for custom actions is CollectingDispatcher, found in rasa_sdk.executor.
Tracker
✓ from rasa_sdk.tracker import Tracker
✗ from rasa_sdk import Tracker
While sometimes imported from the top-level, it's safer and more explicit to import from its module.
FormValidationAction
✓ from rasa_sdk.forms import FormValidationAction
✗ from rasa_sdk.forms import FormAction
FormAction was deprecated in Rasa 3.x and replaced by FormValidationAction for improved validation logic.
SlotSet
✓ from rasa_sdk.events import SlotSet
✗ from rasa_sdk.forms import SlotSet
All event classes like SlotSet are found in the rasa_sdk.events module.
This example defines a simple custom action `ActionHelloWorld` that responds with a greeting. It demonstrates importing `Action`, `Tracker`, `CollectingDispatcher`, and `SlotSet`, along with the required `name()` and `run()` methods. The `run` method is made `async` to align with modern Rasa practices, though it's not strictly required for simple actions. To use this action, save it as `actions.py` and run it with `rasa run actions` in a separate terminal while your Rasa bot is running. The action name must be added to your `domain.yml`.
from typing import Any, Text, Dict, List
from rasa_sdk import Action, Tracker
from rasa_sdk.executor import CollectingDispatcher
from rasa_sdk.events import SlotSet
class ActionHelloWorld(Action):
def name(self) -> Text:
return "action_hello_world"
async def run(self, dispatcher: CollectingDispatcher,
tracker: Tracker,
domain: Dict[Text, Any]) -> List[Dict[Text, Any]]:
user_name = tracker.get_slot("name")
if not user_name:
user_name = "there"
dispatcher.utter_message(text=f"Hello {user_name}! This is a custom action.")
return [SlotSet("name", user_name)]
# To run this, save it as actions.py and then run `rasa run actions` in your terminal.
# Ensure your Rasa project's endpoints.yml is configured to point to this action server.
Debug
Known issues
breakingMajor version 3.x introduced significant changes from 2.x, particularly for form validation. The `FormAction` class was deprecated, replaced by `FormValidationAction` for better modularity.fixMigrate form validation logic from `FormAction`'s `validate` methods to dedicated `FormValidationAction` classes. Review official Rasa documentation for detailed migration guides.
affects: 3.0.0 and above (from 2.x)
gotchaThe `rasa-sdk` version should ideally match the major version of your `rasa` Open Source installation (e.g., `rasa-sdk==3.x.x` with `rasa==3.x.x`). Mismatched versions can lead to unexpected behavior or `ProtocolError`.fixAlways install `rasa-sdk` with a version compatible with your `rasa` Open Source installation. Check the Rasa documentation for compatibility matrices. For example, `pip install 'rasa-sdk==3.*'` if your Rasa Open Source version is 3.
affects: All versions
gotchaCustom action server must be running and accessible by the Rasa Open Source server. Common issues include the action server not running, incorrect endpoint configuration in `endpoints.yml`, or port conflicts.fixEnsure `rasa run actions` is running in a separate process. Verify that `endpoints.yml` has the correct URL for your action server (default is `http://localhost:5055/webhook`). Check action server logs for errors.
affects: All versions
gotchaThe `name()` method in your `Action` class must return a string that exactly matches the action name specified in your `domain.yml` file and used in your stories/rules.fixDouble-check for typos or inconsistencies between the `name()` method's return value and your `domain.yml`. An unregistered action will result in an `AgentException`.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'rasa_sdk.actions'
Attempting to import `Action` from an incorrect sub-module path.
fixImport `Action` directly from the `rasa_sdk` package: `from rasa_sdk import Action`.
rasa.core.agent.AgentException: Action 'my_custom_action' is not a registered custom action.
The Rasa Open Source server cannot find the custom action. This usually means the custom action server is not running, not configured correctly, or the action name is mismatched.
fix1. Run the action server: `rasa run actions`. 2. Verify `endpoints.yml` points to the correct action server URL (e.g., `action_endpoint: url: "http://localhost:5055/webhook"`). 3. Ensure the `name()` method in your custom action returns the exact string 'my_custom_action'.
TypeError: run() missing 1 required positional argument: 'tracker'
The `run` method in your custom action has an incorrect signature, missing one of the required arguments (`dispatcher`, `tracker`, or `domain`).
fixEnsure the `run` method signature matches: `async def run(self, dispatcher: CollectingDispatcher, tracker: Tracker, domain: Dict[Text, Any]) -> List[Dict[Text, Any]]:`
Could not connect to the custom action server at 'http://localhost:5055/webhook'. Is the server running?
The Rasa Open Source server failed to establish a connection with the custom action server.
fix1. Start your custom action server using `rasa run actions`. 2. Check the port and host in `endpoints.yml` and ensure it matches where your action server is listening. 3. Verify no firewall or network issue is blocking the connection. 4. Check action server logs for startup errors.
Upgrade
Version history
3.16.1latest on PyPI · released Apr 16, 2026
Audit
Dependencies
pythonrequiredRequires Python 3.10 to 3.13. Note that Rasa Open Source itself has similar Python version constraints, and it's essential for both to be compatible.
rasarequiredrasa-sdk is designed to work with Rasa Open Source. While not a direct pip dependency, it's a runtime dependency and major versions of rasa-sdk should match those of rasa.