## 1. Project Overview & Quickstart (RasaHQ/rasa)
## File: README.md
Rasa Open Source
## 🚀 The Future of Rasa: Hello Rasa
**Building reliable AI agents just got easier.**
[**Hello Rasa**](https://hello.rasa.ai/?utm_source=github&utm_medium=website&utm_campaign=) is our new interactive playground for prototyping AI agents. It combines LLM fluency with the reliability of business logic using our **CALM** (Conversational AI with Language Models) engine.
### Why switch to Hello Rasa?
* **No setup required:** Open the playground, pick a template (Banking, Telecom, Support), and start building in your browser.
* **No NLU training:** We have moved beyond intents. The LLM handles dialogue understanding while you define the business flows.
* **Built-in copilot:** A specialized AI assistant helps you generate code, debug flows, and expand your agent instantly.
* **Production ready:** Hello Rasa is not just a toy. Export your agent to the Rasa Platform when you are ready to scale.
### Core concepts
* **CALM:** Combines LLM flexibility with strict business logic. The LLM understands the user; the code enforces the rules.
* **Flows:** Describe logical steps (e.g., collect money, transfer funds) rather than rigid dialogue trees.
* **Inspector:** See real-time decision-making. No black boxes.
👉 **[Start building for free at Hello Rasa](https://hello.rasa.ai/?utm_source=github&utm_medium=website&utm_campaign=)**
---
## 🧠 Join the Agent Engineering Community
We are building a home for people shipping real-world AI agents.
Agent Engineering is evolving faster than any single framework. This is a vendor-neutral space to discuss architectures, memory, orchestration, and safety with builders across the industry.
### What you get:
* **Network:** Meet engineers building production agents
* **Learn:** Discuss practical patterns, not just theory
* **Access:** Direct influence on the Hello Rasa roadmap and early access to features
| Channel | Purpose |
| :--- | :--- |
| **#agent-design** | Architectures, reasoning, memory, testing |
| **#showcase** | Show your builds, demos, and repos |
| **#ask-anything** | Debugging and workflow questions |
👉 **[Join the Community](https://info.rasa.com/community?utm_source=github&utm_medium=website&utm_campaign=)**
---
# Rasa Open Source (Legacy)
> **Note:** The documentation and installation instructions below apply to the classic Rasa Open Source framework. For the latest CALM-based experience, see the [Hello Rasa](#-the-future-of-rasa-hello-rasa) section above.
Rasa is an open source machine learning framework for automating text and voice-based conversations. With Rasa, you can build contextual assistants on:
- Facebook Messenger
- Slack
- Google Hangouts
- Webex Teams
- Microsoft Bot Framework
- Rocket.Chat
- Mattermost
- Telegram
- Twilio
- Your own custom conversational channels
Rasa helps you build contextual assistants that can handle layered conversations with lots of back-and-forth.
### 📚 Resources
- 🤓 [Read the docs](https://rasa.com/docs/rasa/)
- 😁 [Install Rasa](https://rasa.com/docs/rasa/installation/environment-set-up)
- 🚀 [Learn all about Conversational AI](https://learning.rasa.com/)
- 🏢 [Explore the enterprise platform](https://rasa.com/product/rasa-platform/)
## Development Internals & Contributing
We are happy to receive contributions. Please review our [Contribution Guidelines](CONTRIBUTING.md) before getting started.
### Installation for Development
Rasa uses **Poetry** for packaging and dependency management.
1. **Install Poetry**: Follow the [official guide](https://python-poetry.org/docs/#installation).
2. **Build from source**:
```bash
make install
```
*Note for macOS users*: If you run into compiler issues, try `export SYSTEM_VERSION_COMPAT=1` before installation.
### Running Tests
Make sure you have development requirements installed:
```bash
make prepare-tests-ubuntu # Ubuntu/Debian
make prepare-tests-macos # macOS
make test # Run tests
```
### Releases
Rasa follows Semantic Versioning.
* **Major**: Incompatible API changes
* **Minor**: Backward-compatible functionality
* **Patch**: Backward-compatible bug fixes
For full details on our release cadence and maintenance policy, visit our [Product Release and Maintenance Policy](https://rasa.com/rasa-product-release-and-maintenance-policy/).
## License
Licensed under the Apache License, Version 2.0. Copyright 2022 Rasa Technologies GmbH. [Copy of the license](https://www.google.com/search?q=LICENSE.txt).
---
## File: changelog/12685.doc.md
Corrected [action server api](https://rasa.com/docs/rasa/pages/action-server-api/) sample in docs.
---
## File: changelog/12721.doc.md
Updated tracing documentation to include tracing in the action server and the REST Channel.
---
## File: changelog/README.md
This directory contains "newsfragments" which are short files that contain a small
**Markdown**-formatted text that will be added to the next `CHANGELOG`.
The `CHANGELOG` will be read by **users**, so this description should be aimed
to Rasa OSS users.
Make sure to use full sentences in the **past or present tense** and use
punctuation, examples:
Slots will be correctly interpolated if there are lists in custom response templates.
Previously this resulted in no interpolation.
Each file should be named like `..md`, where
`` is an issue / PR number, and `` is one of:
* `feature`: new user facing features, like new command-line options and new behavior.
* `improvement`: improvement of existing functionality, usually without requiring user intervention.
* `bugfix`: fixes a reported bug or security vulnerability.
* `doc`: documentation improvement, like rewording an entire section or adding missing docs.
* `removal`: feature deprecation or feature removal.
* `misc`: fixing a small typo or internal change, will not be included in the changelog.
So for example: `123.feature.md`, `456.bugfix.md`.
If your change fixes an issue, use the issue number here. If there is no issue,
then after you submit the PR with your changes and get the PR number, you can add a
changelog using that PR number instead.
If you are not sure what issue type to use, don't hesitate to ask in your PR.
`towncrier` preserves multiple paragraphs and formatting (code blocks, lists,
and so on), but for entries other than `features` it is usually better to stick
to a single paragraph to keep it concise. You can install `towncrier` and then
run `towncrier --draft` if you want to get a preview of how your change will look
in the final release notes.
---
## File: data/README.md
These are some example training data files for a simple bot in the restaurant domain.
They are in the format of the services rasa NLU can emulate, e.g. when you download an export
of your app from one of these services it should look like one of these files.
[examples/rasa](examples/rasa): examples in the native rasa NLU format
[examples/luis](examples/luis): in LUIS format
[examples/wit](examples/wit): in wit format
[examples/api](examples/api): this is a dir and in Dialogflow format
---
## File: docs/docs/action-server/actions.mdx
---
id: actions
sidebar_label: Actions
title: Actions
---
When a Rasa assistant calls a custom action, it sends a request to the action server.
Rasa only knows about whatever events and responses come back in the request response;
it's up to the action server to call the correct code based on the action name that Rasa provides.
To better understand what happens when Rasa calls a custom action, consider
the following example:
You have deployed a weather bot to both Facebook and Slack. The user
can ask for the weather with the intent `ask_weather`. There is a slot `location`
which will be filled if the user has specified a location.
The action `action_tell_weather` will use an API to get the weather forecast ,
using a default location if the user doesn't specify one.
The action will set the `temperature` to the maximum temperature of the weather forecast.
The message returned will differ according to the channel they are using.
:::info Compressed body in HTTP requests
Rasa has the capability to compress the HTTP request body for custom actions.
By default, this option is off to keep backward compatibility with older versions of
custom action servers which did not receive the compressed body in the HTTP request for custom actions.
To enable this option, set environment variable COMPRESS_ACTION_SERVER_REQUEST to `True`.
Rasa SDK versions `3.2.2`, `3.3.1`, `3.4.1` and upwards,
support both compressed and non-compressed body in the HTTP request for
running custom action server. There is no additional setup required.
:::
## Custom Action Input
Your action server receives the following payload from the Rasa server:
```
/* Detailed source-code truncated for AI context efficiency. */
```
### `next_action`
The `next_action` field tells your action server what action to run.
Your actions don't have to be implemented as classes, but they do have
to be callable by name.
In the example case, your action server should run the action `action_tell_weather`.
### `sender_id`
The `sender_id` tells you the unique ID of the
user having the conversation. Its format varies according to the input channel.
What it tells you about the user also depends on the input channel and how
the user is identified by the channel.
In the example case, the `sender_id` is not used for anything.
### `tracker`
The `tracker` contains information about the conversation, including a history of events
and a record of all slots:
- `sender_id`: The same `sender_id` as is available in the top level of the payload
- `slots`: Each slot in your bot's domain and its value at the current time
- `latest_message`: The attributes of the latest message
- `latest_event_time`: The timestamp at which the last event was added to the tracker
- `followup_action`: The action called was a forced follow up action
- `paused`: Whether the conversation is currently paused
- `events`: A list of all previous [events](./events.mdx)
- `latest_input_channel`: The input channel from which the last user message was received
- `active_form`: The name of the currently active form, if any
- `latest_action_name`: The name of the last action the bot executed
In the example case, your custom action uses the value of the `location` slot (if it is set)
to get the weather forecast. It also checks the `latest_input_channel` property
and formats the message payload so that it will display correctly in Facebook Messenger.
### `domain`
The `domain` is a json representation of your `domain.yaml` file.
It is unlikely that a custom action
will refer to its contents, as they are static and do not indicate the state
of the conversation.
You can control if an action should receive a domain or not.
Visit [selective-domain](../domain.mdx#select-which-actions-should-receive-domain)
### `version`
This is the version of the Rasa server. A custom action
is also unlikely to refer to this, although you might use it in a
verification step if your action server
is only compatible with certain Rasa versions.
## Custom Action Output
The Rasa server expects a dictionary of `events` and `responses` as a response
to a custom action call.
### `events`
[Events](./events.mdx) are how your action server can influence the conversation.
In the example case, your custom action should store the maximum temperature
in the `temperature` slot, so it needs to return a [`slot` event](./events.mdx#slot). To set the
slot and do nothing else, your response payload would look like this:
```json
{
"events": [
{
"event": "slot",
"timestamp": null,
"name": "temperature",
"value": "30"
}
],
"responses": []
}
```
Note that events will be applied to the tracker in the order you list them; with `slot`
events, the order won't matter, but with other event types it can.
### `responses`
A response can be of any of the response types described in the
[documentation on rich responses](../responses.mdx#rich-responses).
See the response sample of the [API spec](/pages/action-server-api) for the expected formats.
In the example case, you want to send the user a message with the weather forecast.
To send a regular text message, the response payload would look like this:
```json
{
"events": [
{
"event": "slot",
"timestamp": null,
"name": "temperature",
"value": "30"
}
],
"responses": [
{
"text": "This is your weather forecast!"
}
]
}
```
However, you want to make use of your channels' specific capabilities. Since
the `latest_input_channel` was Facebook, you add a response with
a custom payload that will be rendered as a media message according to Facebook's API spec.
Your response payload then looks like this:
```json
{
"events": [
{
"event": "slot",
"timestamp": null,
"name": "temperature",
"value": "30"
}
],
"responses": [
{
"text": "This is your weather forecast!"
},
{
"attachment": {
"type": "template",
"payload": {
"template_type": "media",
"elements": [
{
"media_type": "weather_forcast.gif",
"attachment_id": ""
}
]
}
}
}
]
}
```
When this response is sent back to
the Rasa server, Rasa will apply the `slot` event and two responses to the tracker,
and return both messages to the user.
## Special Action Types
There are special action types that are automatically triggered under certain circumstances, namely [default actions](../default-actions.mdx)
and [slot validation actions](../slot-validation-actions.mdx).
These special action types have predefined naming conventions that must be followed to maintain the automatic triggering behavior.
You can customize a default action by implementing a custom action with exactly the same name.
Please see the [docs on default actions](../default-actions.mdx) for the expected behavior of each action.
Slot validation actions are run on every user turn, depending on whether a form is active or not.
A slot validation action that should run when a form is not active must be called `action_validate_slot_mappings`.
A slot validation action that should run when a form is active must be called `validate_