broadie 1.0.13

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.

What is Broadie?

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
• Web Interface: Chat with your agents through a web browser
• Agent Communication: Secure peer-to-peer agent discovery and function calls
• Multiple AI Models: Support for Google Gemini, Vertex AI, and more

---

🚀 Quick Start (5 minutes)

Step 1: Install Broadie

pip install broadie

System Requirements: Python 3.9–3.12 (Python 3.11 recommended)

Step 2: Get Your Google API Key

1. Visit Google AI Studio
2. Create an API key
3. Set it as an environment variable:

macOS/Linux:

export GOOGLE_API_KEY="your_google_api_key"

Windows PowerShell:

$env:GOOGLE_API_KEY = "your_google_api_key"

Step 3: Create Your First Agent

Create a file called 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."
}

Step 4: Start Chatting

broadie serve my_agent.json

Open your browser to: http://localhost:8000/

🎉 That's it! You now have a working AI agent with a web interface.

---

📖 Usage Guide

There are two ways to use Broadie, depending on your needs:

Option 1: JSON Configuration (Recommended for Beginners)

Best for: Quick prototypes, simple agents, getting started
Limitations: Cannot add custom tools or complex logic

Create agents using simple JSON files:

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

Commands:

# Chat in terminal
broadie run my_agent.json

# Start web interface  
broadie serve my_agent.json

Option 2: Python API (Advanced)

Best for: Production systems, custom tools, complex workflows
Advantages: Full customization, custom tools, advanced logic

Create agents programmatically with custom 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"

# 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."
        }

# 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 and delegate to specialists.",
            "sub_agents": [AnalystAgent()]
        }

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

---

⚙️ Configuration

Basic Setup (.env file)

Create a .env file in your project directory:

# Required: Google API Key
GOOGLE_API_KEY=your_google_api_key

# Optional: Advanced settings
A2A_ENABLED=true
DB_DRIVER=sqlite
SLACK_BOT_TOKEN=xoxb-your-slack-token
GOOGLE_DRIVE_CREDENTIALS_PATH=/path/to/credentials.json

Advanced Google Cloud Setup

For production or advanced use cases:

1. Create Google Cloud Project: Visit Google Cloud Console
2. Enable Vertex AI API: In "APIs & Services" → "Library"
3. Set additional variables:

export GOOGLE_CLOUD_PROJECT_ID="your-project-id"
export GOOGLE_CLOUD_REGION="us-central1"

---

🛠️ 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

---

🔔 Enabling Notifications/Destinations

Broadie agents can send notifications, alerts, and messages to multiple destinations including Slack, email, webhooks, and more. The destination system provides powerful routing, environment-based configuration, and multi-target broadcasting.

Quick Setup

Slack Notifications

Set these environment variables to enable Slack notifications:

# Option 1: Using Slack Bot Token (Recommended)
SLACK_BOT_TOKEN=xoxb-your-slack-bot-token

# Option 2: Using Slack Webhook URL  
SLACK_WEBHOOK_URL=https://hooks.slack.com/services/YOUR/WEBHOOK/URL

# Default channel for notifications
BROADIE_DEFAULT_SLACK_CHANNEL=#general

Email Notifications

Configure SMTP settings for email notifications:

EMAIL_SMTP_HOST=smtp.gmail.com
EMAIL_SMTP_PORT=587
EMAIL_SMTP_USER=[e-mail]
EMAIL_SMTP_PASSWORD=your-app-password
EMAIL_FROM_ADDRESS=[e-mail]
EMAIL_FROM_NAME="Broadie Agent"
EMAIL_USE_TLS=true

Agent Configuration

Configure destinations in your agent JSON files or Python code:

JSON Configuration

{
  "name": "notification_agent",
  "instruction": "You can send notifications to multiple channels",
  "destinations": {
    "primary": {
      "type": "slack", 
      "target": "#general",
      "enabled": true
    },
    "alerts": {
      "type": "slack",
      "target": "#alerts", 
      "enabled": true
    },
    "escalation": {
      "type": "email",
      "target": "[e-mail]",
      "enabled": true
    },
    "notifications": {
      "type": "multi",
      "target": [
        {"type": "slack", "target": "#updates"},
        {"type": "email", "target": "[e-mail]"}
      ],
      "enabled": true
    }
  }
}

Python Configuration

from broadie import Agent

class NotificationAgent(Agent):
    def build_config(self):
        return {
            "name": "notification_agent",
            "instruction": "You can send notifications",
            "destinations": {
                "primary": {
                    "type": "slack",
                    "target": "#general"
                },
                "alerts": {
                    "type": "webhook", 
                    "target": "https://api.company.com/alerts",
                    "settings": {
                        "method": "POST",
                        "headers": {
                            "Authorization": "${API_TOKEN}"
                        }
                    }
                }
            }
        }

Environment Variable Overrides

Override any destination configuration using environment variables:

# Override primary destination
BROADIE_AGENT_NAME_PRIMARY_TARGET=#development
BROADIE_AGENT_NAME_PRIMARY_TYPE=slack

# Override alert settings  
BROADIE_AGENT_NAME_ALERTS_TARGET=https://webhook.site/unique-id
BROADIE_AGENT_NAME_ALERTS_TYPE=webhook

# Global defaults
BROADIE_DEFAULT_SLACK_CHANNEL=#general
BROADIE_DEFAULT_EMAIL_RECIPIENT=[e-mail]

Using Notification Tools

Agents automatically have access to notification tools with context-aware formatting:

In Agent Code

# Send a notification
await agent.respond("Task completed successfully")

# Send an alert
await agent.alert("System error detected!")

# Escalate an issue
await agent.escalate("Manual intervention required")

# Broadcast to multiple destinations
await agent.broadcast("System maintenance starting", ["primary", "alerts"])

As Tools (agents can call these)

# Agents can use these tools in their responses:
# - send_notification("message", severity="info")
# - send_alert("critical issue detected") 
# - escalate_issue("needs human intervention")
# - broadcast_message("announcement", ["primary", "notifications"])
# - test_notification_destinations()

🎯 Context-Aware Response Formatting

Broadie automatically formats responses appropriately based on how you're interacting:

Context	Format	Features
CLI (broadie run)	Plain Text	Simple, readable text output
Web UI (broadie serve)	Markdown	Rich formatting, links, emphasis
API Calls	JSON	Structured data with metadata
Slack Notifications	Block Kit	Rich Slack blocks and formatting
Email Notifications	HTML	Professional email layout
Webhooks	JSON	Structured payloads for integration

🔀 Dual/Tri Response Pattern

When notifications are configured, Broadie supports dual response patterns:

1. Primary Response: Formatted for your current interface (CLI, Web UI, API)
2. Notification Responses: Simultaneously sent to configured channels with appropriate formatting

Example: CLI with Slack Notifications

• You see: Plain text response in terminal
• Team sees: Rich Slack blocks in #alerts channel
• Both happen automatically based on agent configuration!

Destination Types

Slack Destinations

{
  "type": "slack",
  "target": "#channel-name", 
  "settings": {
    "username": "Broadie Bot",
    "icon_emoji": ":robot_face:",
    "rich_formatting": true
  }
}

Email Destinations

{
  "type": "email",
  "target": "[e-mail]",
  "settings": {
    "subject_template": "[Broadie] {category}: {message}",
    "html_formatting": true,
    "include_metadata": true
  }
}

Webhook Destinations

{
  "type": "webhook", 
  "target": "https://api.company.com/notifications",
  "settings": {
    "method": "POST",
    "headers": {
      "Authorization": "${WEBHOOK_TOKEN}",
      "Content-Type": "application/json"
    },
    "timeout": 30
  }
}

Multi Destinations (Broadcast)

{
  "type": "multi",
  "target": [
    {"type": "slack", "target": "#alerts"},
    {"type": "email", "target": "[e-mail]"},
    {"type": "webhook", "target": "https://monitor.company.com/alerts"}
  ]
}

Message Context & Metadata

All notifications support rich context:

await agent.respond(
    "User login successful",
    severity="info",
    category="security", 
    tags=["auth", "login"],
    metadata={
        "user_id": "12345",
        "ip_address": "192.168.1.1"
    },
    user_id="john.doe",
    session_id="session-abc-123"
)

Testing & Troubleshooting

Test your notification setup:

# Test all destinations
results = await agent.test_destinations()

# Get destination information  
info = agent.get_destination_info()

# Send to specific destination for testing
await agent.destination_resolver.send(
    "Test message", 
    destination_type="primary"
)

Production Best Practices

1. Environment Variables: Use environment variables for sensitive configuration
2. Fallback Destinations: Always configure a fallback destination
3. Rate Limiting: Be mindful of API rate limits for external services
4. Error Handling: Monitor failed delivery attempts
5. Testing: Test destinations regularly in production

---

🖥️ Commands & API

CLI Commands

# Create new project from template
broadie init my_project

# Chat with agent in terminal
broadie run agent.json

# Start web interface
broadie serve agent.json

# Generate agent configs
broadie create agent customer_support

# List all templates
broadie templates

Web Interface

When you run broadie serve, you get:

• Chat UI: http://localhost:8000/ - Web interface for chatting
• REST API: POST /agents/{id}/invoke - Programmatic access
• WebSocket: /ws - Real-time communication
• Health Check: GET /health - Service monitoring

---

🏗️ Advanced Features

Multi-Agent Communication

Agents can work together in 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

Jump-start with built-in templates:

# Customer support system
broadie init --template support my_support_system

# Data integration specialist  
broadie init --template integration my_data_agent

# Generic multi-agent system
broadie init --template generic my_system

Example Use Cases

Customer Support: Multi-agent system with specialized support, escalation, and knowledge base agents

Data Analysis: Pipeline with ingestion, analysis, and reporting agents working together

Content Creation: Research, writing, and editing agents coordinating content workflows

---

📚 Learn More

Documentation & Support

• Documentation: docs.broadie.ai
• GitHub Issues: Report bugs & request features
• 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