Skip to content

Nested SuperAgents Tutorial

Objective

This tutorial demonstrates how to correctly use nested super agents within the AI Refinery SDK. Nested super agents occur when a SuperAgent (or FlowSuperAgent) includes other super agents in its agent_list. This enables hierarchical orchestration of complex workflows where high-level coordination delegates specific tasks to specialized sub-workflows.

The tutorial walks through a portfolio construction system that uses a SuperAgent to coordinate overall portfolio strategy, which in turn delegates sector analysis to a FlowSuperAgent that manages subsector-specific flows.

Tutorial Workflow

This tutorial demonstrates a three-tier agent hierarchy:

  1. Top Level: Portfolio Construction Agent (SuperAgent) - orchestrates the overall investment strategy
  2. Middle Level: Sector Strategy Advisor (FlowSuperAgent) - manages sector-specific analysis
  3. Bottom Level: Technology Subsector Flow (FlowSuperAgent) - handles technology subsector details

Portfolio Investment Advisor

Tutorial Description

We will create an AI system that constructs diversified investment portfolios by analyzing multiple market sectors and subsectors. The system uses nested super agents to organize the workflow hierarchically: a main SuperAgent coordinates the overall portfolio construction, delegating sector analysis to a FlowSuperAgent, which in turn delegates technology subsector analysis to another nested FlowSuperAgent.

Important Note: Circular Dependency Restriction

Critical Rule: When using nested super agents, you must avoid circular dependencies. This means:

  • No super agent may reference itself in its agent_list, either directly or indirectly through a chain of other super agents
  • If Super Agent A calls Super Agent B, and Super Agent B calls Super Agent C, then C cannot call A, B, or any agent that eventually leads back to A or B

Violating this rule will cause runtime failure in the workflow.

Agent Workflow Overview

The figure below depicts the hierarchical structure managed by the nested super agents. The outer box represents the SuperAgent, the middle box shows the FlowSuperAgent for sector strategy, and the inner box illustrates the nested FlowSuperAgent for technology subsectors.

┌─────────────────────────────────────────────────────────────┐
│ Portfolio Construction Agent (SuperAgent)                   │
│                                                             │
│  ┌───────────────────────────────────────────────────────┐  │
│  │ Sector Strategy Advisor (FlowSuperAgent)              │  │
│  │                                                       │  │
│  │  Tech Planner ──┐                                     │  │
│  │                 │                                     │  │
│  │                 ├─→ Healthcare Planner                │  │
│  │                 │         ↓                           │  │
│  │                 │    Energy Planner                   │  │
│  │  ┌──────────────┘         ↓                           │  │ 
│  │  │            Commodities Planner                     │  │
│  │  │                                                    │  │
│  │  │  ┌───────────────────────────────────────────┐     │  │
│  │  └─→│ Technology Subsector Flow (FlowSuperAgent)│     │  │
│  │     │                                           │     │  │
│  │     │  AI Subsector Planner                     │     │  │
│  │     │  Semiconductors Subsector Planner         │     │  │
│  │     └───────────────────────────────────────────┘     │  │
│  └───────────────────────────────────────────────────────┘  │
│                                                             │
│  Recommender Agent → Author Agent                           │
└─────────────────────────────────────────────────────────────┘

Example Queries

  • "Create a balanced portfolio for moderate risk tolerance with exposure to technology and healthcare."
  • "What's a good investment strategy focusing on AI and semiconductor companies?"
  • "Build me a diversified portfolio including energy and commodities sectors."
  • "I want to invest in technology with a focus on emerging AI companies. What do you recommend?"

Steps

1. Configuration File

To implement nested super agents, we'll create a YAML configuration that defines the hierarchical structure. Pay careful attention to how super agents reference each other while avoiding circular dependencies.

First, define all the utility agents that will be used across the various super agent levels:

utility_agents: # List of all the utility agents used in all the super agents in the workflow
  - agent_class: PlanningAgent
    agent_name: "Tech Planner" # To be used in the Sector Strategy Advisor
    agent_description: "Plan investment strategies in the technology sector." # Describes the goal of the agent

  - agent_class: PlanningAgent
    agent_name: "Healthcare Planner" # To be used in the Sector Strategy Advisor
    agent_description: "Plan investment strategies in the healthcare sector."

  - agent_class: PlanningAgent
    agent_name: "Energy Planner" # To be used in the Sector Strategy Advisor
    agent_description: "Plan investment strategies in the energy sector."

  - agent_class: PlanningAgent
    agent_name: "Commodities Planner" # To be used in the Sector Strategy Advisor
    agent_description: "Plan investment strategies in the commodities market."

  - agent_class: PlanningAgent
    agent_name: "AI Subsector Planner" # To be used in the Technology Subsector Flow
    agent_description: "Develop recommendations for AI-related companies within the technology sector."

  - agent_class: PlanningAgent
    agent_name: "Semiconductors Subsector Planner" # To be used in the Technology Subsector Flow
    agent_description: "Develop recommendations for semiconductor companies within the technology sector."

  - agent_class: SearchAgent
    agent_name: "Recommender Agent" # To be used directly in the Portfolio Construction Agent
    agent_description: "Search the web for stock and fund recommendations."

  - agent_class: AuthorAgent
    agent_name: "Author Agent" # To be used directly in the Portfolio Construction Agent
    agent_description: "Compile and format the final investment guide."
    config: # Some utility agent classes, such as the AuthorAgent, have additional configuration parameters
      memory_attribute_key: "investment_plan"
      leading_questions:
        - question: "Portfolio composition"
          prompt: "Describe the proposed portfolio allocation across asset classes."
        - question: "Market rationale"
          prompt: "Explain the market reasoning behind each recommendation."
        - question: "Risk assessment"
          prompt: "Summarize the potential risks and mitigation strategies for the portfolio."

Now define the super agents in hierarchical order, starting from the innermost (most specialized) and working outward:

Level 3 (Innermost): Technology Subsector Flow

super_agents:
  - agent_class: FlowSuperAgent # Innermost FlowSuperAgent only involves utility agents
    agent_name: "Technology Subsector Flow"
    agent_description: "Handles detailed investment planning for technology subsectors such as AI and semiconductors."
    config:
      goal: "Generate refined recommendations for technology subsectors to enhance sector-level insights."
      agent_list:
        - agent_name: "AI Subsector Planner"
        - agent_name: "Semiconductors Subsector Planner"

Level 2 (Middle): Sector Strategy Advisor

This FlowSuperAgent includes the nested Technology Subsector Flow in its workflow:

  - agent_class: FlowSuperAgent
    agent_name: "Sector Strategy Advisor" # Name for your FlowSuperAgent
    agent_description: "Analyzes and recommends sector-specific investment opportunities."
    config:
      goal: "Generate sector-level investment strategies across technology, healthcare, energy, and commodities."
      agent_list: # List of agents defining the execution flow and nodes for this FlowSuperAgent
        - agent_name: "Tech Planner"
          next_step:
            - "Technology Subsector Flow"  # Nested FlowSuperAgent
            - "Healthcare Planner"

        - agent_name: "Healthcare Planner"
          next_step:
            - "Energy Planner"

        - agent_name: "Energy Planner"
          next_step:
            - "Commodities Planner"

        - agent_name: "Commodities Planner"

        - agent_name: "Technology Subsector Flow"  # Define the nested agent as a node

Level 1 (Outermost): Portfolio Construction Agent

The top-level SuperAgent coordinates the entire workflow by including the Sector Strategy Advisor:

  - agent_class: SuperAgent
    agent_name: "Portfolio Construction Agent" # Name for your SuperAgent
    agent_description: "Expert in constructing diversified investment portfolios based on sector insights."
    config:
      goal: "Construct a comprehensive investment portfolio by aggregating insights from all strategy advisors."
      steps: # The list of tasks for the SuperAgent to follow iteratively matching agents from agent_list to each task
        - Collect sector strategies
        - Synthesize into a global investment outlook recommendation
        - Produce final diversified portfolio report
      agent_list: # List of agent names which the SuperAgent can call
        - agent_name: "Sector Strategy Advisor"  # Nested FlowSuperAgent
        - agent_name: "Recommender Agent"
        - agent_name: "Author Agent"
      exit: "Author Agent"
      max_turns: 12

Finally, register the main SuperAgent with the orchestrator:

orchestrator:
  agent_list:
    - agent_name: "Portfolio Construction Agent"  # The top-level SuperAgent is now registered with the orchestrator

Configure memory settings to control session persistence:

memory_config:
  save_config:
    auto_load: false  # Start each session fresh without loading previous conversations

2. Python File

Now create the Python script to run the nested super agent system:

"""
This script demonstrates how to use nested super agents
to create a hierarchical portfolio construction workflow.

The Portfolio Construction Agent (SuperAgent) delegates to
Sector Strategy Advisor (FlowSuperAgent), which in turn
delegates to Technology Subsector Flow (FlowSuperAgent).
"""
import asyncio
import os

from air import AsyncAIRefinery
from air.utils import async_print


async def process_query(query, project, client):
    """
    Process a single query using a new DistillerClient instance.
    Ensures each query is independent by using a unique session UUID.
    """
    # Generate a unique identifier for this session using process ID
    session_uuid = f"temp_user_{os.getpid()}"

    async with client(
        project=project,
        uuid=session_uuid,
    ) as dc:
        # Send query to the nested super agent system
        responses = await dc.query(query=query)
        print(f"-------\nQuery: {query}")

        # Iterate through streaming responses from agents in the hierarchy
        async for response in responses:
            role = response.get("role", "Unknown Agent")  # Agent name
            content = response.get("content", "No content")  # Agent's reply
            await async_print(f"\n<<< Response from {role} >>>")
            await async_print(content)
            await async_print("-" * 20)

        # Clear all stored memory for this session so next run is clean
        await dc.reset_memory()
        await async_print("Memory reset complete.")
        await async_print("Query handled successfully.")
        await async_print("-" * 20)


async def nested_superagent_demo(api_key):
    """
    Demonstrates running nested super agents for portfolio construction.
    Each query is processed sequentially with a fresh session.
    """
    # Register the project from its YAML configuration
    client = AsyncAIRefinery(
        api_key=api_key
    )
    client.create_project(
        config_path="nested_superagent_portfolio.yaml",
        project="portfolio_advisor",
    )

    # Example queries to run through the nested super agent system
    queries = [
        "Create a balanced portfolio with focus on technology, especially AI and semiconductors, plus some healthcare exposure."
    ]

    # Process each query one by one
    for query in queries:
        await process_query(query, "portfolio_advisor", client)


if __name__ == "__main__":
    # Load API_KEY and ACCOUNT from local environment variables
    api_key = str(os.getenv("API_KEY"))

    # Entry point: run the asynchronous demo function
    asyncio.run(nested_superagent_demo(api_key))