Multi-Agent Workshop

Small CrewAI examples that show two common agent orchestration patterns:

• sequential_research_handoff_demo.py: a fixed research -> edit handoff
• hierarchical_manager_research_demo.py: a manager-led workflow that delegates work across specialist agents

The repo is intentionally compact and uses a local custom web search tool so the execution flow is easy to inspect.

What This Project Includes

• A custom DuckDuckGo / DDGS-backed search tool
• A sequential multi-agent handoff example
• A hierarchical manager example
• Local CrewAI runtime storage configuration
• A .gitignore that excludes secrets, virtualenvs, and local runtime artifacts

Requirements

• Python 3.11 or newer
• A Gemini API key
• macOS / Linux shell commands below assume bash or zsh

Installation

Create and activate a virtual environment:

python3 -m venv .venv
source .venv/bin/activate

Install dependencies:

pip install "crewai[google-genai]" pydantic ddgs

Environment Setup

Create a local .env file from the example:

cp .env.example .env

Then set your Gemini API key in .env:

GEMINI_API_KEY=your_api_key_here

.env is ignored by Git and will not be committed.

Running the Examples

Activate the virtual environment first:

source .venv/bin/activate

Run the sequential handoff example:

python sequential_research_handoff_demo.py

Run the hierarchical manager example:

python hierarchical_manager_research_demo.py

Execution Patterns

Sequential

Process.sequential runs tasks in a fixed order.

In this repo:

1. The researcher gathers information
2. The editor rewrites the result into an executive summary

Use sequential when you already know the workflow order.

Hierarchical

Process.hierarchical introduces a manager that decides which agent should handle the work.

In this repo:

• The manager LLM delegates across market research, metrics, and executive writing roles

Use hierarchical when task routing should be decided dynamically.

Project Files

• sequential_research_handoff_demo.py: fixed two-agent handoff
• hierarchical_manager_research_demo.py: manager-led delegation example
• project_overview_slide.md: a presentation slide summary
• multi_agent_workshop_qr.svg: QR code for the GitHub repository

Notes

• The examples use live web search, so output quality depends on current search results.
• The examples use Gemini models through CrewAI's Google GenAI provider.
• Both scripts disable CrewAI telemetry and store runtime SQLite data in a local .crewai_storage/ directory.

Troubleshooting

Missing Gemini provider

If CrewAI reports that the Google Gen AI provider is unavailable, reinstall with:

pip install "crewai[google-genai]"

Missing API key

If Gemini calls fail immediately, verify that .env contains:

GEMINI_API_KEY=your_api_key_here

Search returns weak or noisy results

That is usually a live web-search quality issue rather than a framework problem. Re-running later or adjusting the prompts can help.

High memory usage during local experimentation

CrewAI itself is not especially heavy in this repo, but browser tabs, editor helper processes, and OS speech services can cause memory pressure during demos or development.