I gave my Rasa Mantle agent an Azure OpenAI embedding model, so it could search its reference documents, and rasa train stopped with ModuleNotFoundError: No module named 'azure.cognitiveservices'. The agent doesn’t use voice at all, yet Rasa wanted Azure’s speech package. Here’s why that happens on Rasa Pro 3.22.0, and the fix: one package.
What I Was Doing
I was building Rasa Tutorial — Part 6: References: Answer from Your Documents, on Rasa Pro 3.22.0 with Claude Sonnet 5.5. Claude has no embedding model, so I added an Azure OpenAI one to integrations.yml: a model group with provider: azure, pointing to a text-embedding-3-small deployment:
integrations.yml (excerpt)
- id: reference_embeddings
models:
- provider: azure
deployment: text-embedding-3-small
api_base: https://YOUR-RESOURCE-NAME.openai.azure.com/
api_version: v1
api_key: ${AZURE_API_KEY}
Then I named that group in agent.yml, so Rasa would use it for references:
agent.yml (excerpt)
knowledge_answering:
embeddings: reference_embeddings
And I trained the agent:
Terminal
rasa train
What I Expected
A new agent package, with a references index built from my one Markdown file. Rasa’s integrations.yml reference uses the same keys for an Azure OpenAI model group: provider: azure, deployment, api_base, api_version and api_key.
What I Got
After its usual notes, rasa train stopped with an error and a long traceback:
Output (the lines that matter)
2026-11-21 13:03:21 ERROR rasa.__main__ - [error ] ModuleNotFoundError: No module named 'azure.cognitiveservices' event_key=cli.exception.general_exception
…
ModuleNotFoundError: No module named 'azure.cognitiveservices'
The end of the traceback shows where the import came from:
What I Checked
Reading the traceback from the bottom up was the check that mattered:
- The last frame is Rasa’s Azure text-to-speech engine,
rasa/api/voice/tts/v1/azure.py, importingazure.cognitiveservices.speech. That’s the Azure Speech SDK. - The frames above it are Rasa’s configuration check. It takes the group named in
knowledge_answering.embeddingsand first makes sure it isn’t a speech group. To find out, it loads the speech engine registered under the group’s provider name, andazureis also the name of Rasa’s Azure speech engine. - The rasa-pro package lists
azure-cognitiveservices-speechonly in its optionalchannelsextra, so a plainuv pip install rasa-prodoesn’t install it.
Rasa’s docs show provider: azure for Azure OpenAI model groups and don’t mention the speech package for them. Rasa Pro 3.22.0 was the newest release when I checked, so there was no fixed version to upgrade to.
Why It Happens
Rasa Pro 3.22.0 uses the provider name azure for two things: Azure OpenAI models and Azure’s speech engines. When rasa train checks a model group your agent uses, it first asks whether that group is a speech group, and for azure that question loads the Azure speech engine. The engine’s code imports the Azure Speech SDK as soon as it loads. The check is ready for a configuration error, not for a missing package, so without the SDK the whole check crashes instead of moving on.
The Fix
Install the Azure Speech SDK in the project’s virtual environment. In the project folder, with the virtual environment turned on (source .venv/bin/activate), run:
Terminal
uv pip install azure-cognitiveservices-speech
Output
Resolved 8 packages in 1.57s
Downloading azure-cognitiveservices-speech (2.9MiB)
Downloaded azure-cognitiveservices-speech
Prepared 1 package in 1.65s
Installed 1 package in 5ms
+ azure-cognitiveservices-speech==1.53.1
It installed version 1.53.1, which is within the range Rasa Pro 3.22.0 asks for in its channels extra (1.53 or later, below 1.54).
After the Fix
I ran rasa train again with nothing else changed. It finished, wrote the references index from my one document and saved the agent package:
The agent then answered questions from its reference document in the Rasa Inspector, as Part 6 shows.
Common Mistakes
| Mistake | Do this instead |
|---|---|
| Installing the package with the virtual environment turned off | Turn on the project’s .venv first, so rasa finds the package. |
Removing the embeddings setting to make training pass | Without it, Rasa embeds with OpenAI’s text-embedding-3-large and needs an OpenAI key. Install the package instead. |
Troubleshooting
| Problem | Fix |
|---|---|
| The same error after installing | Go to the project folder, run source .venv/bin/activate, install the package again, then run rasa train. |
FAQ
Does my agent need voice for this?
No. Rasa loads the package to check your configuration. The agent still runs as a text agent, and you don’t need an Azure Speech resource.
Does this happen with an Azure OpenAI chat model too?
Rasa’s validation code runs the same check on the model group named in orchestrator.model_group, so a provider: azure chat model goes through it as well. I hit it with an embeddings group.
Should I install rasa-pro[channels] instead?
That extra includes the same package, plus SDKs for channels such as Slack, Telegram and Twilio. You need it only if you use those channels; the check needs just the one package.
Conclusion
On Rasa Pro 3.22.0, a model group with provider: azure goes through a speech-group check that imports the Azure Speech SDK. Installing azure-cognitiveservices-speech in the project’s virtual environment lets the check finish, and rasa train works.
Additional Resources
- integrations.yml reference (Rasa docs)
- agent.yml reference: knowledge_answering (Rasa docs)
- rasa-pro on PyPI
- azure-cognitiveservices-speech on PyPI
Related
- Rasa Tutorial — Part 6: References: Answer from Your Documents
- Rasa Tutorial for Beginners: Mastering Rasa Pro in Python, with every part of the series
Rasa, Azure and other names mentioned are trademarks of their respective owners. JD Bots isn’t affiliated with or endorsed by Rasa Technologies or Microsoft.
