{"id":8580,"library":"rasa-sdk","title":"Rasa SDK","description":"Rasa SDK is the companion library to Rasa Open Source, enabling developers to write custom actions for their Rasa-powered chatbots. It provides the necessary interfaces and classes (like Action, Tracker, Dispatcher) to interact with the Rasa dialogue management and NLU components. Version 3.16.1 is the current stable release, with frequent updates for bug fixes and minor features, often in sync with Rasa Open Source releases.","status":"active","version":"3.16.1","language":"en","source_language":"en","source_url":"https://github.com/rasahq/rasa-sdk","tags":["chatbot","rasa","sdk","custom actions","ai","conversational-ai"],"install":[{"cmd":"pip install rasa-sdk","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Requires 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.","package":"python","optional":false},{"reason":"rasa-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.","package":"rasa","optional":false}],"imports":[{"note":"Action is directly exported from the top-level rasa_sdk package since 2.x.","wrong":"from rasa_sdk.actions import Action","symbol":"Action","correct":"from rasa_sdk import Action"},{"note":"The primary dispatcher for custom actions is CollectingDispatcher, found in rasa_sdk.executor.","wrong":"from rasa_sdk.dispatcher import Dispatcher","symbol":"CollectingDispatcher","correct":"from rasa_sdk.executor import CollectingDispatcher"},{"note":"While sometimes imported from the top-level, it's safer and more explicit to import from its module.","wrong":"from rasa_sdk import Tracker","symbol":"Tracker","correct":"from rasa_sdk.tracker import Tracker"},{"note":"FormAction was deprecated in Rasa 3.x and replaced by FormValidationAction for improved validation logic.","wrong":"from rasa_sdk.forms import FormAction","symbol":"FormValidationAction","correct":"from rasa_sdk.forms import FormValidationAction"},{"note":"All event classes like SlotSet are found in the rasa_sdk.events module.","wrong":"from rasa_sdk.forms import SlotSet","symbol":"SlotSet","correct":"from rasa_sdk.events import SlotSet"}],"quickstart":{"code":"from typing import Any, Text, Dict, List\n\nfrom rasa_sdk import Action, Tracker\nfrom rasa_sdk.executor import CollectingDispatcher\nfrom rasa_sdk.events import SlotSet\n\nclass ActionHelloWorld(Action):\n\n    def name(self) -> Text:\n        return \"action_hello_world\"\n\n    async def run(self, dispatcher: CollectingDispatcher,\n            tracker: Tracker,\n            domain: Dict[Text, Any]) -> List[Dict[Text, Any]]:\n\n        user_name = tracker.get_slot(\"name\")\n        if not user_name:\n            user_name = \"there\"\n        \n        dispatcher.utter_message(text=f\"Hello {user_name}! This is a custom action.\")\n\n        return [SlotSet(\"name\", user_name)]\n\n# To run this, save it as actions.py and then run `rasa run actions` in your terminal.\n# Ensure your Rasa project's endpoints.yml is configured to point to this action server.","lang":"python","description":"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`."},"warnings":[{"fix":"Migrate form validation logic from `FormAction`'s `validate` methods to dedicated `FormValidationAction` classes. Review official Rasa documentation for detailed migration guides.","message":"Major version 3.x introduced significant changes from 2.x, particularly for form validation. The `FormAction` class was deprecated, replaced by `FormValidationAction` for better modularity.","severity":"breaking","affected_versions":"3.0.0 and above (from 2.x)"},{"fix":"Always 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.","message":"The `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`.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure `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.","message":"Custom 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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Double-check for typos or inconsistencies between the `name()` method's return value and your `domain.yml`. An unregistered action will result in an `AgentException`.","message":"The `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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Import `Action` directly from the `rasa_sdk` package: `from rasa_sdk import Action`.","cause":"Attempting to import `Action` from an incorrect sub-module path.","error":"ModuleNotFoundError: No module named 'rasa_sdk.actions'"},{"fix":"1. 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'.","cause":"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.","error":"rasa.core.agent.AgentException: Action 'my_custom_action' is not a registered custom action."},{"fix":"Ensure the `run` method signature matches: `async def run(self, dispatcher: CollectingDispatcher, tracker: Tracker, domain: Dict[Text, Any]) -> List[Dict[Text, Any]]:`","cause":"The `run` method in your custom action has an incorrect signature, missing one of the required arguments (`dispatcher`, `tracker`, or `domain`).","error":"TypeError: run() missing 1 required positional argument: 'tracker'"},{"fix":"1. 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.","cause":"The Rasa Open Source server failed to establish a connection with the custom action server.","error":"Could not connect to the custom action server at 'http://localhost:5055/webhook'. Is the server running?"}]}