integrations.yml

integrations.yml is required at the project root. It defines named model groups, the channels customers reach the agent through, optional MCP tool servers, and optional OpenTelemetry tracing and metrics. agent.yml orchestrator names which group runs the agent. The file is copied into the model archive at rasa train, and each section is read from the place that suits what it configures:

Section	Read from	Effect
`channels`	The live project directory	Change channel settings and restart.
`mcp_servers`	The live project directory	Change MCP URLs or auth and restart so connections reopen.
`model_groups` named by `orchestrator.model_group`	The live project directory	Restart after changing the models inside that group. Changing which group `agent.yml` names needs a retrain.
`model_groups` used by embeddings	The packaged snapshot	Retrain after changing a reference embedder.
`tracing`	The live project directory	Optional Langfuse, OTLP, or Jaeger tracing; restart to pick up changes.
`metrics`	The live project directory	Optional OTLP metrics export; restart to pick up changes.

The agent’s LLM and reference embedder use the same model-group syntax, but have different lifecycles. The LLM group is resolved from the live project at startup. Reference embeddings are resolved from the packaged snapshot because query vectors must match the vectors built at training time.

integrations.yml

model_groups:
  - id: main_model
    models:
      - provider: openai
        model: gpt-5.1
        api_base: https://api.openai.com/v1
        api_key: ${OPENAI_API_KEY}

channels:
  rest: { enabled: true }
  inspector: { enabled: true }

# Optional — tracing (Langfuse, OTLP, or Jaeger)
# tracing:
#   type: langfuse
#   public_key: ${LANGFUSE_PUBLIC_KEY}
#   private_key: ${LANGFUSE_SECRET_KEY}
#   host: https://cloud.langfuse.com

# Optional — OTLP metrics
# metrics:
#   type: otlp
#   endpoint: localhost:4317
#   insecure: true

That is a complete, working file. Everything else is optional.

Provider examples

agent.yml orchestrator.model_group names one of the groups below. orchestrator.max_prompt_tokens is optional and defaults to 8000. Provider, model, credentials, and provider-specific options belong on the group. A leftover llm: section is invalid. provider: openai, azure, and self-hosted have dedicated clients. Any other value is passed through to LiteLLM, so a provider LiteLLM supports works by naming it and its model. OpenAI

integrations.yml

model_groups:
  - id: main_model
    models:
      - provider: openai
        model: gpt-5.1
        api_key: ${OPENAI_API_KEY}

channels:
  rest: { enabled: true }
  inspector: { enabled: true }

Anthropic

integrations.yml

model_groups:
  - id: main_model
    models:
      - provider: anthropic
        model: claude-sonnet-4-5-20250929
        api_key: ${ANTHROPIC_API_KEY}

channels:
  rest: { enabled: true }
  inspector: { enabled: true }

Google Gemini

integrations.yml

model_groups:
  - id: main_model
    models:
      - provider: gemini
        model: gemini-2.5-pro
        api_key: ${GEMINI_API_KEY}

channels:
  rest: { enabled: true }
  inspector: { enabled: true }

Azure OpenAI. Name the deployment rather than the model, and give the endpoint and API version:

integrations.yml

model_groups:
  - id: main_model
    models:
      - provider: azure
        deployment: my-gpt-deployment
        api_base: https://my-resource.openai.azure.com/
        api_version: "2024-10-21"
        api_key: ${AZURE_OPENAI_API_KEY}

channels:
  rest: { enabled: true }
  inspector: { enabled: true }

Self-hosted, OpenAI-compatible. For vLLM, Ollama, TGI, or anything else serving the OpenAI API shape. provider, model, and api_base are all required:

integrations.yml

model_groups:
  - id: main_model
    models:
      - provider: self-hosted
        model: mistralai/Mistral-7B-Instruct-v0.3
        api_base: http://localhost:8000/v1
        api_key: ${LOCAL_LLM_API_KEY}

channels:
  rest: { enabled: true }
  inspector: { enabled: true }

model is the name your server advertises, and api_base points at the OpenAI-compatible route, usually ending in /v1. Omit api_key if the server takes no key. A present api_key: ${LOCAL_LLM_API_KEY} is sent to the provider even when that variable is unset (the unsubstituted ${…} string), so keyless servers must not declare the key.

Secrets

Sensitive values in config files use environment-variable references — never literal secrets. Write the whole field as ${ENV_VAR_NAME} with no extra text:

api_key: ${OPENAI_API_KEY}

Put the real value in the process environment (for example a project .env that your shell loads before rasa train / rasa run). Unset ${VAR} placeholders are forwarded as-is to the provider; omit api_key for keyless self-hosted servers instead of pointing at a missing variable. On a model entry, these keys must use ${…} when present — including when nested under oauth::

Key	Typical use
`api_key`	Provider API key
`aws_access_key_id` / `aws_secret_access_key` / `aws_session_token`	Bedrock / SageMaker
`client_id` / `client_secret` / `token_url`	OAuth (for example Azure Entra ID)
`public_key` / `private_key`	Langfuse tracing
`secret`	A2A JWT secret

rasa train and live LLM / embeddings load reject literal values for those keys.

`channels`

Declares the channels customers reach the agent through.

channels:
  rest: { enabled: true }
  inspector: { enabled: true }

Each key is a channel name from the built-in channel registry. Values may be:

Form	Meaning
`{ enabled: true }`	Enable with defaults
`{ enabled: true, <key>: <value>, … }`	Enable with those keyword arguments
`{ enabled: false }`	Disabled: kept in the file but not registered
(empty / null)	Enable with defaults

The enabled flag is stripped before the remaining keys are handed to the channel. A non-boolean enabled, or an entry that is neither a mapping nor empty, raises at load.

rest and inspector are the practical minimum: rest is what the evaluation runner talks to, and inspector is required for rasa inspect. A project with no channels: block registers no channels at all.

${VAR} references inside channels: are expanded when the file is read, so channel credentials can come from the environment.

Voice channels

A voice channel takes asr: and tts: sub-mappings, and that is where speech recognition and synthesis are configured. Each takes a name: selecting the engine, plus that engine’s own settings:

integrations.yml

model_groups:
  - id: main_model
    models:
      - provider: openai
        model: gpt-5.1
        api_key: ${OPENAI_API_KEY}

channels:
  browser_audio:
    enabled: true
    server_url: localhost:5005
    asr:
      name: deepgram
      language_map:
        en-US:
          language: en
          model: flux-general-en
    tts:
      name: deepgram
      language_map:
        en-US:
          model: aura-2-asteria-en

Engine	Built-in names
`asr.name`	`deepgram`, `azure`
`tts.name`	`deepgram`, `azure`, `cartesia`, `rime`

Every key besides name goes to that engine, so the available settings are the engine’s own. language_map keys the model and language off the conversation language, which is how both engines take their settings. name also accepts a Python module path, which loads a custom engine implementing from_config_dict.

Deepgram Flux for speech recognition

Flux is the model family to reach for on a live voice agent. It does turn detection inside the ASR rather than inferring it from silence, so the agent takes its turn on the signal the recogniser already has. Naming a flux- model selects it. The engine reads the model name out of language_map and switches to the Flux API on its own, so there is nothing else to declare:

integrations.yml

model_groups:
  - id: main_model
    models:
      - provider: openai
        model: gpt-5.1
        api_key: ${OPENAI_API_KEY}

channels:
  browser_audio:
    enabled: true
    server_url: localhost:5005
    asr:
      name: deepgram
      language_map:
        en-US:
          language: en
          model: flux-general-en
      eot_threshold: 0.8
      eot_timeout_ms: 5000
    tts:
      name: deepgram
      language_map:
        en-US:
          model: aura-2-asteria-en

The two turn-detection knobs are optional:

Key	Range	Default	Effect
`eot_threshold`	0.5 to 0.9	0.7	Confidence needed to call end of turn. Lower responds faster and interrupts more.
`eot_timeout_ms`	500 to 10000	5000	Ceiling on silence before the turn is ended regardless.

A Flux config takes these two keys and no others. Anything unrecognised fails the load rather than being ignored, so a typo surfaces at startup. The same asr: / tts: shape applies to every voice channel, including jambonz, audiocodes, twilio_media_streams, and genesys. What differs between them is the telephony connection: server_url, and any credentials that provider needs.

`model_groups`

Required. Named model configurations used by the agent’s LLM and, when configured, the references embedder.

model_groups:
  - id: main_model
    models:
      - provider: openai
        model: gpt-5.1
        api_key: ${OPENAI_API_KEY}
  - id: reference_embeddings
    models:
      - provider: openai
        model: text-embedding-3-large

agent.yml orchestrator.model_group names the group that runs the agent. Point agent.yml at an embeddings group by id:

agent.yml

agent:
  persona: You are a helpful assistant.

orchestrator:
  model_group: main_model

references:
  embeddings: reference_embeddings

Every model-group reference must name a group declared here. Naming an undeclared group fails validation. Changing the models inside the orchestrator group requires a restart. Changing orchestrator.model_group, or a reference embeddings group, requires retraining. A group with one model is the usual orchestrator setup. Without a router block, only models[0] is used — extra models are ignored, there is no fallback, and rasa data validate warns. Set router when the group should select among multiple models.

`mcp_servers`

Optional. A list of named MCP servers a skill can import tools from with mcp/<server-name>:<tool-name> in import_tools. Each entry needs a unique name and a url. Auth, if any, is one of token, api_key, oauth, or module at the top level of that entry. Secrets must use ${ENV_VAR} form — literal secret strings are rejected.

integrations.yml

mcp_servers:
  - name: banking
    url: http://localhost:8000/mcp/
    token: ${MCP_BANKING_TOKEN}

Key	Required	Description
`name`	Yes	Server id used in `mcp/<name>:<tool>`. Letters, digits, `_`, `.`, and `-`. Must be unique. Tool names are stricter — see `import_tools`.
`url`	Yes	MCP server endpoint.
`type`	No	`http` or `https`. When omitted, inferred only from an `http://` or `https://` URL. Other schemes (or a missing scheme) are rejected.
`token`	No	Bearer token (`${ENV_VAR}`).
`api_key`	No	API key (`${ENV_VAR}`). Optional `header_name` / `header_format` override how it is sent.
`oauth`	No	Client-credentials OAuth mapping (`token_url`, `client_id`, `client_secret`, optional `scope` / `audience` / `timeout`).
`module`	No	Dotted path to a custom auth strategy class.
`tool_timeout`	No	Per-call timeout in seconds for tools on this server. When omitted, falls back to `tool_timeout` in `agent.yml`, then to `10`.
`meta_map`	No	Optional `_meta` payload built for each tool call. See `meta_map`.

Use at most one of token, api_key, oauth, or module per server. Omit all four when the server needs no auth. Auth examples are in Auth examples.

Auth examples

Bearer token

integrations.yml

mcp_servers:
  - name: banking
    url: http://localhost:8000/mcp/
    token: ${MCP_BANKING_TOKEN}

API key

integrations.yml

mcp_servers:
  - name: catalog
    url: https://catalog.example.com/mcp/
    api_key: ${MCP_CATALOG_API_KEY}
    # header_name: X-API-Key
    # header_format: "{key}"

OAuth2 client credentials

integrations.yml

mcp_servers:
  - name: payments
    url: https://payments.example.com/mcp/
    oauth:
      token_url: https://auth.example.com/oauth/token
      client_id: mantle-agent
      client_secret: ${MCP_PAYMENTS_CLIENT_SECRET}
      # scope: tools.read
      # audience: https://payments.example.com

Custom module

integrations.yml

mcp_servers:
  - name: internal
    url: https://internal.example.com/mcp/
    module: my_package.auth.CustomMcpAuth

`meta_map`

Optional. Builds an MCP _meta object on each tool call without exposing those values to the LLM:

integrations.yml

mcp_servers:
  - name: banking
    url: http://localhost:8000/mcp/
    token: ${MCP_BANKING_TOKEN}
    tool_timeout: 30
    meta_map:
      static:
        api_version: "v2"
        source: "rasa_agent"

static is a mapping of fixed string key/value pairs always sent in _meta.

How skills use a server

Allowlist only the tools you need in the skill’s import_tools:

skills/check_balance/skill.md

import_tools:
  - mcp/banking:get_balance

See Import MCP tools for a short walkthrough and skill.md → import_tools for collision and load-failure rules.

Validation

rasa train and rasa data validate check this file:

Code	Cause
`mantle.validation.config.missing_integrations`	No `integrations.yml` at the project root
`mantle.validation.config.unexpected_llm`	An `llm:` section is still present. Set `orchestrator.model_group` in `agent.yml` instead.
`mantle.validation.config.unknown_model_group`	`orchestrator.model_group` or an embeddings reference names a group that is not declared, or `model_groups:` is missing or empty
`mantle.validation.config.unused_model_group_models`	A group lists more than one model and has no `router` (warning)
`mantle.validation.config.invalid_tracing`	Invalid or unsupported `tracing:` section
`mantle.validation.config.invalid_metrics`	Invalid or unsupported `metrics:` section
`mantle.validation.config.invalid_mcp_server`	A `mcp_servers:` entry is invalid (shape, auth, URL, secrets)
`mantle.validation.config.duplicate_mcp_server_name`	Two `mcp_servers:` entries share the same `name`
`mantle.validation.config.invalid_event_broker`	Invalid `event_broker:` section
`mantle.validation.config.invalid_timer_store`	Invalid `timer_store:` section
`mantle.validation.config.invalid_model_server`	Invalid `rasa_model_server:` section (the remote model server)

Tracing

Optional. Configure under tracing: in integrations.yml. Supported types: langfuse, otlp, and jaeger. Restart the process after changing this section. Span catalog: Observability. tracing: takes a single tracer, or a list with at most one langfuse entry and at most one otlp or jaeger entry. See Langfuse with OTLP or Jaeger. Tracing is read only from integrations.yml. A tracing: block in endpoints.yml is ignored, and startup logs a warning. If the tracing: section is invalid, rasa train reports it and rasa run starts without tracing.

Langfuse

tracing:
  type: langfuse
  public_key: ${LANGFUSE_PUBLIC_KEY}
  private_key: ${LANGFUSE_SECRET_KEY}
  host: https://cloud.langfuse.com

Key	Required	Notes
`type`	yes	Must be `langfuse`.
`public_key`	yes	Must use a `${ENV_VAR}` reference — literal secrets are rejected.
`private_key`	yes	Must use a `${ENV_VAR}` reference — literal secrets are rejected.
`host`	yes	Langfuse Cloud or your self-hosted URL.
`environment`	no	Optional Langfuse environment name (lowercase, digits, `-`/`_`).
`timeout`	no	HTTP timeout in seconds (maps to `LANGFUSE_TIMEOUT`).
`debug`	no	Enable Langfuse debug logging (`LANGFUSE_DEBUG`).
`release`	no	Release/version tag attached to traces (`LANGFUSE_RELEASE`).
`sample_rate`	no	Trace sampling rate between 0 and 1 (`LANGFUSE_SAMPLE_RATE`).
`media_upload_thread_count`	no	Media upload thread pool size (`LANGFUSE_MEDIA_UPLOAD_THREAD_COUNT`).

public_key and private_key must use ${ENV_VAR} references — literal secrets are rejected at validation and apply time. Those references are kept as literal strings when integrations.yml is parsed (they are not expanded like channel credentials). They are resolved when Langfuse configures at CLI startup; if a variable is unset, resolution is best-effort and may leave the literal ${VAR} in the process environment, so tracing is skipped rather than aborting startup. Use rasa data validate to catch invalid shape or key syntax before deploy. Install the monitoring extra (pip install rasa-pro[monitoring]), set LANGFUSE_PUBLIC_KEY and LANGFUSE_SECRET_KEY, then enable the block. Example agents ship it commented out so local defaults stay key-free.

OTLP

tracing:
  type: otlp
  endpoint: localhost:4317
  insecure: true

Key	Required	Notes
`type`	yes	Must be `otlp`.
`endpoint`	yes	Collector gRPC endpoint (`host:port`).
`insecure`	no	Use an insecure channel when `true`.
`root_certificates`	no	Path to a CA bundle for TLS.
`service_name`	no	Service name reported to the collector.

Jaeger

tracing:
  type: jaeger
  host: localhost
  port: 4317

Key	Required	Notes
`type`	yes	Must be `jaeger`.
`host`	no	Agent host (default `localhost`).
`port`	no	Collector OTLP gRPC port (default `4317`).
`username` / `password`	no	Optional credentials, sent as a Basic `Authorization` header. When set, `insecure` is required.
`insecure`	no	`false` exports over TLS; `true` sends spans and credentials unencrypted. Defaults to `true` when no credentials are set.
`root_certificates`	no	Path to a CA bundle for TLS. Uses the system trust store when omitted.
`service_name`	no	Service name reported to Jaeger.
`sync_export`	no	`true` exports each span immediately. Omit it, or set null, to keep batched export.

With credentials, set insecure: false so they are not sent in plaintext:

tracing:
  type: jaeger
  host: jaeger.example.com
  port: 4317
  username: ${JAEGER_USERNAME}
  password: ${JAEGER_PASSWORD}
  insecure: false
  root_certificates: certs/ca.pem

Langfuse with OTLP or Jaeger

List both tracers to send LLM traces to Langfuse and spans to a collector:

tracing:
  - type: langfuse
    public_key: ${LANGFUSE_PUBLIC_KEY}
    private_key: ${LANGFUSE_SECRET_KEY}
    host: https://cloud.langfuse.com
  - type: otlp
    endpoint: localhost:4317
    insecure: true

Each entry takes the same keys as its single-tracer form above. Declaring two langfuse entries, or both otlp and jaeger, is a validation error.

Metrics

Optional. Export OpenTelemetry metrics to an OTLP collector:

metrics:
  type: otlp
  endpoint: localhost:4317
  insecure: true

Key	Required	Notes
`type`	yes	Must be `otlp`.
`endpoint`	yes	Collector gRPC endpoint (`host:port`).
`insecure`	no	Use an insecure channel when `true`.
`root_certificates`	no	Path to a CA bundle for TLS.
`service_name`	no	Service name reported to the collector.

Metrics can be enabled without configuring tracing. Metric catalog: Metrics. Metrics are read only from integrations.yml. A metrics: block in endpoints.yml is ignored, and startup logs a warning. If the metrics: section is invalid, rasa train reports it and rasa run starts without metrics.

`event_broker`

Optional. Stream conversation events to a broker. Read only from integrations.yml; an event_broker: block in endpoints.yml is ignored, and startup logs a warning. Omit the section to publish no events.

event_broker:
  type: pika
  url: ${RABBITMQ_URL}
  username: ${RABBITMQ_USERNAME}
  password: ${RABBITMQ_PASSWORD}
  queues:
    - rasa_events

Key	Required	Notes
`type`	no	`pika` (the default), `sql`, `file`, `kafka`, `concurrent_kafka`, or the import path of a custom event broker class. A custom path must import successfully at train and must subclass `EventBroker`.
`url`	for `pika`, `kafka`, and `concurrent_kafka`	Broker address. For `kafka` and `concurrent_kafka`, a list of `url[:port]` bootstrap servers is also valid (a comma-separated string still works). `file` uses `path` instead; `sql` uses `url` as the database host when it is not sqlite. Do not set `host` for `pika` or `sql` — it conflicts with how those brokers are constructed.
`username`	for `pika`	RabbitMQ username. Required even when `url` is an `amqp://` URI; credentials in that URI are not read at construction.
`password`	for `pika`	RabbitMQ password. Required even when `url` is an `amqp://` URI.

Other keys are the ones that broker type already accepts (queues, topic, path, and so on).

`timer_store`

Optional. Store background session timers. Read only from integrations.yml; a timer_store: block in endpoints.yml is ignored, and startup logs a warning. Omit the section to keep timers in memory.

timer_store:
  type: redis
  host: localhost
  port: 6379
  db: 2
  password: ${REDIS_PASSWORD}

Key	Required	Notes
`type`	no	`in_memory` (the default), `redis`, or the import path of a custom timer store class. A custom path must import successfully at train and must subclass `SessionTimerStore`.
`host`	no	Redis host (default `localhost`). `url` is a deprecated alias for `host`.
`port`	no	Redis port (default `6379`).
`password`	no	Redis password.
`db`	no	Redis database number (default `2`).
`key_prefix`	no	Alphanumeric prefix for timer keys.
`poll_interval`	no	Seconds between checks for expired timers (default `1.0`).
`socket_timeout`	no	Seconds before a Redis command times out (default `10`).

The shared Redis connection keys also apply: username, use_ssl, ssl_certfile, ssl_keyfile, ssl_ca_certs, deployment_mode, endpoints, and sentinel_service. Any value can be a ${VAR} placeholder, including port and db.

`rasa_model_server`

Optional. Pull a trained model from a server at startup, and again every wait_time_between_pulls seconds. This is the remote model server. It is not the models list inside a model_groups entry. Read only from integrations.yml. A models: block in endpoints.yml is ignored, and startup logs a warning. A top-level models: block in integrations.yml fails train (mantle.validation.config.invalid_model_server); move it to rasa_model_server:. Omit the section to load a local model (rasa train, then rasa run --model) or use --remote-storage.

rasa_model_server:
  url: http://my-server.example/models/default@latest
  token: ${MODEL_SERVER_TOKEN}
  wait_time_between_pulls: 10

Key	Required	Notes
`url`	yes	HTTP(S) URL the model archive is pulled from. Blank or non-URL values fail train and startup; `${VAR}` placeholders expand at runtime.
`token`	no	Token sent as a query parameter with each pull.
`token_name`	no	Query parameter name for `token`. Defaults to `token`.
`params`	no	Extra query parameters sent with each pull.
`headers`	no	Extra HTTP headers sent with each pull.
`basic_auth`	no	HTTP basic auth for the pull: `username` and `password`.
`cafile`	no	Path to a CA bundle for TLS verification (same key as `endpoints.yml` `models:`).
`wait_time_between_pulls`	no	Seconds between refresh pulls. `0` pulls once at startup and does not refresh. Defaults to 100 when omitted.

Any value can be a ${VAR} placeholder, including wait_time_between_pulls.

File Reference

Language

Tools

Customizations

Runtime

Observability

Prompts

Schemas

integrations.yml

Provider examples

Secrets

`channels`

Voice channels

Deepgram Flux for speech recognition

`model_groups`

`mcp_servers`

Auth examples

`meta_map`

How skills use a server

Validation

Tracing

Langfuse

OTLP

Jaeger

Langfuse with OTLP or Jaeger

Metrics

`event_broker`

`timer_store`

`rasa_model_server`

See also

​Provider examples

​Secrets

​channels

​Voice channels

​Deepgram Flux for speech recognition

​model_groups

​mcp_servers

​Auth examples

​meta_map

​How skills use a server

​Validation

​Tracing

​Langfuse

​OTLP

​Jaeger

​Langfuse with OTLP or Jaeger

​Metrics

​event_broker

​timer_store

​rasa_model_server

​See also

Provider examples

Secrets

`channels`

Voice channels

Deepgram Flux for speech recognition

`model_groups`

`mcp_servers`

Auth examples

`meta_map`

How skills use a server

Validation

Tracing

Langfuse

OTLP

Jaeger

Langfuse with OTLP or Jaeger

Metrics

`event_broker`

`timer_store`

`rasa_model_server`

See also