broadie 1.0.11

A powerful multi-agent framework with persistence, API server, and agent-to-agent communication

Broadie

A powerful multi-agent framework developed by the Broad Institute for building intelligent, collaborative AI systems with persistence, API integration, and agent-to-agent communication.

Overview

Broadie enables you to create sophisticated AI agent systems that can work together, remember conversations, integrate with external services, and communicate with other agents. Whether you're building a simple chatbot or a complex multi-agent workflow, Broadie provides the infrastructure you need.

Key Features

• Two Usage Modes: JSON configuration for quick setup or programmatic Python API for advanced customization
• Agent Collaboration: Main agents coordinate with specialized sub-agents
• Persistent Memory: Agents remember conversations and learn from interactions
• Tool Integration: Built-in tools for file operations, Google Drive, Slack, and more
• API Server: REST and WebSocket endpoints for web integration
• Agent Communication: Secure peer-to-peer agent discovery and function calls
• Multiple AI Models: Support for Google Gemini, Vertex AI, and more

Installation

pip install broadie

Before you begin (5‑minute setup)

Follow these simple steps to prepare your computer. Even if you’re new to Python, this will guide you through.

1. Check your Python version

• Broadie supports Python 3.9–3.12. We recommend Python 3.11 for the best compatibility.
• Check your version:
  • macOS/Linux: python3 --version (or python --version)
  • Windows (PowerShell/CMD): python --version
• If you don’t have Python or it’s older than 3.9:
  • Download: https://www.python.org/downloads/
  • Or use pyenv (advanced users on macOS/Linux): https://github.com/pyenv/pyenv

2. Create a project folder

• macOS/Linux:
  • mkdir -p ~/broadie-quickstart && cd ~/broadie-quickstart
• Windows (PowerShell):
  • mkdir $HOME\broadie-quickstart; cd $HOME\broadie-quickstart

3. Create a virtual environment

• macOS/Linux:
  • python3 -m venv .venv
  • Activate: source .venv/bin/activate
• Windows (PowerShell):
  • python -m venv .venv
  • Activate: .venv\Scripts\Activate.ps1

4. Upgrade pip and install Broadie

• python -m pip install -U pip
• pip install broadie

5. Create a minimal agent config (my_agent.json) Copy this into a new file named my_agent.json in your project folder:

{
  "name": "helpful_assistant",
  "description": "A helpful AI assistant",
  "instruction": "You are a helpful AI assistant that can answer questions and help with tasks."
}

Note: You can omit the model block — Broadie defaults to Google Gemini gemini-2.0-flash. To use a different model, you can add a model section later.

6. Set your model API key

• Broadie uses Google Gemini by default. Set an environment variable before serving:
  • macOS/Linux (bash/zsh): export GOOGLE_API_KEY=your_google_api_key
  • Windows (PowerShell): $env:GOOGLE_API_KEY = "your_google_api_key"
  • Get a key: https://ai.google.dev/

7. Start Broadie and open the UI

• broadie serve my_agent.json
• Open your browser at: http://localhost:8000/

That’s it — you’re ready to use the Quick Start below.

Quick Start

Option 1: JSON Configuration (Simple Setup)

Perfect for getting started quickly or creating agents without custom logic.

1. Create an agent configuration (my_agent.json):

{
  "name": "helpful_assistant",
  "description": "A helpful AI assistant",
  "instruction": "You are a helpful AI assistant that can answer questions and help with tasks."
}

Note: You can omit the model block — by default Broadie will use Google Gemini gemini-2.0-flash. To override, include an explicit model in your JSON, for example:

{
  "name": "helpful_assistant",
  "description": "A helpful AI assistant",
  "instruction": "You are a helpful AI assistant that can answer questions and help with tasks.",
  "model": { "provider": "google", "name": "gemini-2.0-flash" }
}

2. Run your agent:

broadie run my_agent.json

Option 2: Programmatic Python API (Advanced)

Use this approach when you need custom tools, complex logic, or want to extend agent capabilities.

from broadie import Agent, SubAgent, tool

# Define custom tools that your agents can use
@tool(name="analyze_data", description="Analyze data and return insights")
def analyze_data(data: str) -> str:
    # Your custom analysis logic here
    return f"Analysis complete: {data} shows positive trends"

@tool(name="generate_report", description="Generate a formatted report")
def generate_report(findings: str) -> str:
    return f"# Report\n\n{findings}\n\n*Generated by Broadie*"

# Create a specialized sub-agent
class AnalystAgent(SubAgent):
    def build_config(self):
        return {
            "name": "data_analyst",
            "description": "Specializes in data analysis",
            "instruction": "You are a data analysis expert. Use your tools to analyze data and provide insights."
        }

# Create the main coordination agent
class ResearchCoordinator(Agent):
    def build_config(self):
        return {
            "name": "research_coordinator", 
            "description": "Coordinates research tasks",
            "instruction": "You coordinate research tasks, delegating analysis to specialists and compiling results.",
            "sub_agents": [AnalystAgent()]
        }

# Use your agent
async def main():
    agent = ResearchCoordinator()
    response = await agent.process_message("Analyze our Q4 sales data and generate a report")
    print(response)

When to Use Each Approach

JSON Configuration

• Best for: Quick prototypes, simple agents, configuration-driven workflows
• Limitations: Cannot add custom tools or complex logic
• Use cases: Customer support bots, FAQ assistants, content generators

Python API

• Best for: Production systems, custom integrations, complex workflows
• Advantages: Full customization, custom tools, advanced logic, integration with existing systems
• Use cases: Data analysis pipelines, API integrations, complex business workflows

Enable Google Vertex AI and configure keys

To run Broadie with Google Gemini (via Vertex AI) you need to:

1. Create or choose a Google Cloud project

• Go to Google Cloud Console: https://console.cloud.google.com/
• Create a new project or pick an existing one. Note the Project ID (e.g., broad-cloud-eng-scratch).

2. Enable the Vertex AI API

• In Cloud Console, open “APIs & Services” → “Library” and enable “Vertex AI API”.
• Or via gcloud:
  • gcloud config set project YOUR_PROJECT_ID
  • gcloud services enable aiplatform.googleapis.com

3. Get a Google API key for Gemini

• Visit Google AI Studio: https://ai.google.dev/
• Create an API key and copy it; you’ll use it as GOOGLE_API_KEY.

4. Choose a Vertex AI region

• We recommend us-central1 for Gemini models.
• Set GOOGLE_CLOUD_REGION accordingly.

5. Set environment variables

• macOS/Linux (bash/zsh):
  • export GOOGLE_API_KEY="your_google_api_key"
  • export GOOGLE_CLOUD_PROJECT_ID="your-project-id"
  • export GOOGLE_CLOUD_REGION="us-central1"
• Windows (PowerShell):
  • $env:GOOGLE_API_KEY = "your_google_api_key"
  • $env:GOOGLE_CLOUD_PROJECT_ID = "your-project-id"
  • $env:GOOGLE_CLOUD_REGION = "us-central1"

6. Optional: save into a .env file for local development

GOOGLE_API_KEY=your_google_api_key
GOOGLE_CLOUD_PROJECT_ID=your-project-id
GOOGLE_CLOUD_REGION=us-central1

Notes

• Broadie defaults to the Gemini model "gemini-2.0-flash" if you don’t specify a model in your config.
• Ensure your selected region supports the model you use.
• If you use gcloud Application Default Credentials for other Google services, run: gcloud auth application-default login

Configuration

Environment Setup

Create a .env file with your API keys and settings:

# Required: AI Model Access
GOOGLE_API_KEY=your_google_api_key_here

# Optional: Agent-to-Agent Communication
A2A_ENABLED=true
A2A_AGENT_ID=my_agent_001
A2A_AGENT_NAME=my_helpful_agent

# Optional: Database (defaults to SQLite)
DB_DRIVER=sqlite
DB_NAME=broadie.db

# Optional: Slack Integration
SLACK_BOT_TOKEN=xoxb-your-slack-token
SLACK_CHANNEL=#general

# Optional: Google Drive Integration  
GOOGLE_DRIVE_CREDENTIALS_PATH=/path/to/credentials.json

Built-in Tools

Broadie agents automatically have access to powerful built-in tools:

File Operations

• Read, write, and edit files
• List directories and search content

Google Drive Integration (when configured)

• Search documents and spreadsheets
• Read and write Google Docs
• Create and update Google Sheets

Slack Integration (when configured)

• Send messages to channels
• Search message history
• Upload files and create threads

Task Management

• Create and manage todo lists
• Track progress across conversations

CLI Commands

# Initialize a new project with templates
broadie init my_project

# Run an agent from JSON config
broadie run agent.json

# Run an agent from Python code
broadie run module.path:MyAgent

# Start API server for web integration
broadie serve agent.json

# Create agent configurations
broadie create agent customer_support
broadie create sub-agent data_analyzer

# List available project templates
broadie templates

API Integration

Start a web server to integrate agents with your applications:

broadie serve my_agent.json

This provides:

• Web UI: Visit http://localhost:8000/ to chat with your agent in the browser
• REST API: POST /agents/{id}/invoke for function calls
• WebSocket: /ws for real-time chat
• Health Check: GET /health for monitoring

Agent-to-Agent Communication

Agents can discover and communicate with each other for complex workflows:

# Agent A can invoke functions on Agent B
result = await coordinator_agent.invoke_peer_agent(
    "analyst_agent_id", 
    "analyze_sales_data",
    {"data": sales_data, "period": "Q4"}
)

Project Templates

Get started faster with built-in templates:

• simple: Single agent for basic tasks
• integration: Agent with API integration capabilities
• generic: Multi-agent system template
• support: Customer support system with specialized agents

broadie init --template support my_support_system

Example Use Cases

Customer Support System

broadie init --template support customer_help
cd customer_help
# Configure your API keys in .env
broadie serve main.json

Data Analysis Pipeline

# Create agents for data ingestion, analysis, and reporting
# Each agent specializes in one aspect of the pipeline
# Main agent coordinates the workflow

Content Generation Workflow

# Research agent gathers information
# Writer agent creates content  
# Editor agent reviews and refines
# Coordinator manages the entire process

Support and Documentation

• Issues: GitHub Issues
• Documentation: docs.broadie.ai
• Community: GitHub Discussions

Contributing

We welcome contributions! See CONTRIBUTING.md for development setup, testing, and contribution guidelines.

License

This project is licensed under the MIT License - see the LICENSE file for details.

---

Developed by the Broad Institute - Empowering researchers and developers with intelligent agent systems.