Overview

info

Sub Agents are currently in beta and are available starting from Rasa 3.14.0.

Rasa can serve as an intelligent orchestrator, coordinating a network of multiple sub agents to handle different tasks. Two types of sub agents are currently supported:

1. ReAct Sub Agent: A built-in autonomous sub agent that has access to one or more MCP (Model Context Protocol) servers. It operates in a ReAct loop, dynamically choosing which tools to invoke based on the conversation context.
2. External Sub Agent: An external sub agent connected via the A2A (Agent-to-Agent) protocol.

How Rasa Interacts with Sub Agents

Sub agents are always invoked as part of a flow execution. When a user triggers a flow that contains an autonomous step, Rasa orchestrates the sub agent interaction through a detailed process:

1. Agent State Check: The system checks if the sub agent is already running and in an interrupted state, resuming it if necessary.

2. Agent Invocation: Rasa prepares comprehensive context data (see Context Sharing below) and invokes the sub agent sharing the created context with the sub agent.

3. Retry Logic: If the sub agent encounters recoverable errors, Rasa automatically retries up to 3 times with exponential backoff.

4. Response Handling: Based on the sub agent's response status, Rasa takes different actions:

   • INPUT_REQUIRED: Response to the user with the sub agent's message and pauses the flow to wait for user input
   • COMPLETED: Response to the user and continues to the next flow step
   • FATAL_ERROR: Cancels the current flow and triggers error handling

5. State Management: The system maintains sub agent state for proper resumption and cleanup, including handling interruptions when users digress to other flows or use conversation repair. When interrupted, the orchestrator:

   • Pauses the sub agent's execution
   • Stores its current state and context
   • Allows the new flow to proceed
   • Offers to resume the interrupted sub agent when the digression is complete

6. Event Integration: Any slot updates or events returned by the sub agent are integrated back into the conversation state.

The specific completion mechanism depends on the sub agent type. ReAct sub agents use built-in tools to signal completion, while external sub agents signal completion through their own protocols. See ReAct Sub Agent and External Sub Agent for more details.

This orchestration ensures robust, stateful interactions between the Rasa agent and its sub agents, with proper error handling and context preservation throughout the conversation.

Context Sharing

To ensure sub agents have the information needed to perform their tasks effectively, Rasa shares comprehensive context with each sub agent:

• Current user message: The latest user input that triggered the sub agent
• Conversation history: A readable transcript of the entire conversation up to that point
• Slot values: All current slot values from the conversation, filtered to exclude system slots and include only relevant data
• Event history: The complete sequence of events that have occurred in the conversation
• Agent metadata: Context IDs for maintaining state across sub agent interactions (especially for external sub agents connected via A2A)

This rich context allows sub agents to understand the conversation flow, access relevant information, and make informed decisions about how to proceed.

Bidirectional Data Flow: Sub agents can also provide structured results alongside their response messages. These structured results can be converted into slot updates (via customization) and integrated back into the conversation state, allowing the orchestrator to access and use the data collected by the sub agent in subsequent flow steps.

The specific input shared with sub agents and how their output is processed can be customized. See Customization for details.

How to Use Sub Agents

To use sub agents in your assistant, invoke them from your flow steps using autonomous steps. An autonomous step delegates control to a sub agent for a specific part of the conversation, allowing it to reason independently using tools (such as MCP servers) or by connecting with an external agent via the A2A protocol.

See Flow Steps: Autonomous Steps for details on how to configure and use this feature in your flows.

Configuration

All sub agents share common configuration requirements that must be set up before they can be used in your flows.

Sub Agent Directory Structure

Each sub agent must be configured in its own dedicated subdirectory within your project:

your_project/
├── config.yml
├── domain/
├── data/flows/
└── sub_agents/
    └── your_agent_name/
        ├── config.yml
        └── [additional files as needed]

By default, Rasa looks for a sub_agents directory. To use a different directory name, specify the sub agent directory via the CLI argument --sub-agents.

Configuration File

Every sub agent must have a config.yml file in its directory with the following mandatory structure:

agent:
  name: your_agent_name
  protocol: [A2A|RASA]  # Optional: protocol for agent connections, default 'RASA'
  description: "Brief description of what this agent does"

configuration:
  module: "path.to.custom.module"  # Optional: custom module for sub agent customization

Required Configuration Keys

The following keys are required in every sub agent's config.yml:

• agent.name: The name of the agent (must be unique and must not clash with any flow name)
• agent.description: A brief description of the sub agent's capabilities

Optional Configuration Keys

The following common configuration keys are optionsl in every sub agent's config.yml:

• agent.protocol: Determines the protocol used for connections:

  • A2A for external sub agents
  • RASA for ReAct sub agents (default)

  Note: If you want to use an external sub agent, make sure to set agent.protocol to A2A.

• configuration.module: Path to a custom module for sub agent customization.

Protocol-Specific Configuration

The config.yml file contains additional settings depending on the sub agent type:

• External Sub Agents (A2A): Require an agent_card path or URL.
• ReAct Sub Agents (RASA): Support LLM configuration, prompt templates, timeouts, and MCP server connections.

For detailed configuration options specific to each sub agent type, see:

• External Sub Agent Configuration
• ReAct Sub Agent Configuration

Customization

How Rasa interacts with sub agents can be customized to fit your use case. To customize sub agents, you first need to create a custom sub agent class that inherits from the appropriate base class and overrides the necessary methods.

Creating a Custom Sub Agent

The specific base class depends on the sub agent type:

• ReAct Sub Agents: Inherit from MCPOpenAgent (general-purpose) or MCPTaskAgent (task-specific)
• External Sub Agents: Inherit from A2AAgent

For detailed implementation examples, see:

• ReAct Sub Agent Customization
• External Sub Agent Customization

Input Processing Customization

Override the process_input method to customize how the sub agent receives and processes user input. A common use case is to filter slots so that the sub agent only receives relevant information, preventing it from being overwhelmed with unnecessary data.

The process_input method receives an AgentInput object as input:

class AgentInput(BaseModel):
    """A class that represents the schema of the input to the agent."""

    id: str  # unique identifier for the agent input
    user_message: str  # the message sent by the user
    slots: List[AgentInputSlot]  # list of slots containing information extracted during the conversation
    conversation_history: str  # full conversation dialogue history as a string
    events: List[Event]  # list of events (e.g., SlotSet events)
    metadata: Dict[str, Any]  # additional custom metadata provided with the input
    timestamp: Optional[str] = None  # optional timestamp indicating when the input was created

class AgentInputSlot(BaseModel):
    """A class that represents the schema of the input slot to the agent."""

    name: str  # name of the slot
    value: Any  # value assigned to the slot
    type: str  # type of the slot (e.g., text, float, categorical)
    allowed_values: Optional[List[Any]] = None  # optional list of allowed values for the slot, if applicable

The function should return an object of type AgentInput, which means you can modify the input that will be received by the sub agent.

Output Processing Customization

Override the process_output method to customize how the sub agent's responses are processed and integrated back into your system. A common use case is to extract structured data from the sub agent's response and store it in slots for use by downstream flows.

The process_output method receives an AgentOutput object as input:

class AgentOutput(BaseModel):
    """A class that represents the schema of the output from the sub agent."""

    id: str  # unique identifier for the sub agent execution session
    status: AgentStatus  # current status of the sub agent (e.g., running, completed, failed)
    response_message: Optional[str] = None  # contains the response generated by the sub agent to be sent back to the user
    events: Optional[List[SlotSet]] = None  # any Rasa events like `SlotSet` events that should be executed on the tracker once the sub agent releases control
    structured_results: Optional[List[List[Dict[str, Any]]]] = None  # list of results returned by all tool invocations while the sub agent was active
    metadata: Optional[Dict[str, Any]] = None  # additional metadata about the sub agent's execution that can be used for logging or debugging
    timestamp: Optional[str] = None  # timestamp indicating when the sub agent completed its execution
    error_message: Optional[str] = None  # contains any error messages if the sub agent encountered issues during execution

The function should return an object of type AgentOutput, which means you can modify the output created by the sub agent with more enriched information.

For more information about the SlotSet event, see the SlotSet documentation.

Protocol-Specific Customization

For additional customization options specific to each sub agent type, see:

• ReAct Sub Agent Customization
• External Sub Agent Customization