Hierarchical

Agents are organized in a tree-like structure, with higher-level agents (supervisors) coordinating specialist agents.

Overview

Hierarchies shine when you need structured decision flows, explicit quality checks, and clear ownership of each step. Supervisors break work into pieces, delegate to the right specialists, and assemble the final answer.

Demo Scenario: Multi-Level Research System

This runnable example builds a three-layer hierarchy to research a topic:

1. Coordinator – orchestrates the workflow and talks to the user

2. Research agent – performs web searches using the platform's search tool

3. Information compiler – formats raw findings into a polished summary

The coordinator delegates research to the specialist, forwards those notes to the compiler, then delivers the final write-up.

Diagram

Implementation Steps

1. Create the research and information compiler agents

   from glaip_sdk import Agent
   from langchain_core.tools import BaseTool
   
   class WebSearchTool(BaseTool):
       name = "web_search"
       description = "Search the web"
       def _run(self, query: str) -> str:
           # Your web search implementation
           return "Search results..."
   
   research_agent = Agent(
       name="research_agent",
       instruction="""You are a research specialist. Use the web_search tool to gather up-to-date information and cite sources.""",
       tools=[WebSearchTool],
   )
   
   information_compiler = Agent(
       name="information_compiler",
       instruction="""You are an analyst who turns raw research notes into clear, well-structured summaries. Use Markdown and include URLs.""",
   )

2. Create the coordinator with sub-agents and workflow instructions

   coordinator = Agent(
       name="coordinator",
       instruction="""You oversee a hierarchical research system with two sub-agents:
       - "research_agent" gathers information
       - "information_compiler" formats the findings
   
       Workflow:
       1. Delegate the user's topic to research_agent
       2. Review the research output
       3. Forward the raw notes to information_compiler for formatting
       4. Deliver the final summary back to the user""",
       agents=[research_agent, information_compiler],
   )

3. Run the hierarchy on a topic and perform cleanup

   topic = "Latest developments in artificial intelligence for healthcare in 2025"
   coordinator.run(f"Please research and summarize: {topic}")
   
   # Cleanup only needed if agents were deployed
   # coordinator.delete()
   # information_compiler.delete()
   # research_agent.delete()

How to Run

From the repository root glaip-sdk/python/glaip-sdk:

poetry run python examples/multi-agent-system-patterns/hierarchical/hierarchical.py

Ensure your .env contains:

OPENAI_API_KEY=your-openai-key-here

Output

───────────────────────────── 🤖 coordinator  ✓ · 47s ─────────────────────────────╮
│ Latest Developments in Artificial Intelligence (AI) for Healthcare (2025)       │
│                                                                                 │
│ • Personalized treatment planning: multi-modal AI models tailor therapies.      │
│ • AI-powered diagnostics: FDA approvals continue to accelerate.                 │
│ • Operational efficiency: intelligent clinical coding and automation at scale.  │
│                                                                                 │
│ Sources: Stanford HAI 2025 Index, WHO digital health briefing, AMA reports.     │
╰─────────────────────────────────────────────────────────────────────────────────╯

Notes

• Add reviewers or domain specialists as additional hierarchy levels for more rigorous validation.

• Swap the web_search tool for a custom integration if your platform exposes a different search capability.

• Monitor each delegated run with the CLI --verbose flag or renderer callbacks to debug coordination steps.

Related Documentation

• Agents guide — Configure nested agents, memory, and runtime overrides.

• Tools guide — Manage catalog tools such as web_search.

• Automation & scripting — Run hierarchical workflows in CI pipelines.

• Security & privacy — Apply tool-output sharing and PII policies across supervisor chains.