Agent Example - AI-Powered News Dashboard

A full-stack application demonstrating an AI-powered personalized news aggregation system using Azure OpenAI, Flock orchestrator, and Next.js.

🏗️ Architecture Overview

This repository contains two main components:

1. Agent Backend (agent_backend/) - Python-based AI orchestration system using Flock
2. News Dashboard (news-dashboard/) - Next.js 15 frontend with real-time updates

How It Works

1. User logs in with their news category interests (Sports, Politics, Finance, Technology)
2. Frontend sends user profile to the agent backend via HTTP API
3. Agent backend uses AI agents to:
   • Break down user interests into search tasks
   • Research news from multiple sources using MCP servers (DuckDuckGo, Yahoo Finance, web readers)
   • Generate personalized news summaries for each category
4. Results are published as artifacts that the frontend polls and displays in real-time

📋 Prerequisites

• Python: 3.13 or higher
• Node.js: 18.17.0 or higher
• pnpm: Latest version (for frontend package management)
• uv: Python package installer (for backend dependencies)
• Azure OpenAI: Valid Azure OpenAI deployment and credentials

🚀 Getting Started

1. Clone the Repository

git clone https://github.com/whiteducksoftware/news_agents_events_demo.git
cd news_agents_events_demo

2. Set Up the Agent Backend

Install Dependencies

The backend uses uv for dependency management. If you don't have uv installed:

# Install uv (macOS/Linux)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Or using pip
pip install uv

Then install the project dependencies:

cd agent_backend
uv sync

Configure Environment Variables

Create a .env file in the agent_backend directory with your Azure OpenAI credentials:

# Required: Azure OpenAI Configuration
AZURE_OPENAI_API_KEY=your_azure_openai_api_key
AZURE_OPENAI_ENDPOINT=https://your-resource-name.openai.azure.com/
AZURE_OPENAI_API_VERSION=2024-02-15-preview

# Optional: Model Configuration (default is used if not specified)
# The model specified in code is "azure/gpt-4.1-swedencentral"
# Ensure your Azure deployment matches this model

Important Notes:

• The backend is configured to use the Azure OpenAI model azure/gpt-4.1-swedencentral
• Ensure your Azure OpenAI deployment has this model available
• The Flock framework will automatically use these environment variables for Azure authentication

Run the Backend

# From the agent_backend directory
uv run python main.py

The backend will start on port 8344 by default and includes:

• AI orchestration with multiple specialized agents
• MCP (Model Context Protocol) server integrations for:
  • DuckDuckGo web search
  • Yahoo Finance news
  • Website content reading
• Dashboard v2 interface for monitoring

3. Set Up the News Dashboard Frontend

Install Dependencies

cd news-dashboard
pnpm install

Configure Environment Variables

Create a .env.local file in the news-dashboard directory:

# Required: Agent Backend API Base URL
NEXT_PUBLIC_API_BASE_URL=http://localhost:8344

# Optional: WebSocket URL (for future real-time features)
# NEXT_PUBLIC_WS_URL=ws://localhost:8080

Environment Variables Explained:

• NEXT_PUBLIC_API_BASE_URL: The base URL of the agent backend server
  • Used for publishing user login events
  • Used for polling news artifacts
  • Default: http://localhost:8344

Run the Frontend

# Development mode
pnpm dev

# Production build
pnpm build
pnpm start

The frontend will be available at http://localhost:3000.

🎯 Usage

1. Start the Backend: Ensure the agent backend is running on port 8344
2. Start the Frontend: Open http://localhost:3000 in your browser
3. Login: Click "Login as Demo User" (no credentials needed)
4. Explore: The system will automatically:
   • Send your demo user profile to the backend
   • Trigger AI agents to research news topics
   • Poll for new articles and display them in categorized columns
   • Show articles with headlines, summaries, and source links

Demo User Profile

The demo user is preconfigured with the following interests:

• Sports: Soccer, Football
• Politics: Elections, Climate Policy
• Finance: Stock Market, Cryptocurrency
• Technology: AI, Software Development

📁 Project Structure

news_agents_events_demo/
├── agent_backend/
│   ├── main.py                  # Main orchestrator with AI agents
│   ├── pyproject.toml           # Python dependencies
│   ├── .python-version          # Python version (3.13)
│   └── agent_backend.egg-info/  # Package metadata
│
└── news-dashboard/
    ├── app/
    │   ├── page.tsx             # Main page (login/dashboard)
    │   ├── layout.tsx           # Root layout
    │   ├── globals.css          # Global styles
    │   ├── api/
    │   │   ├── publish/         # Proxy for publishing to backend
    │   │   └── artifacts/       # Proxy for fetching artifacts
    │   ├── components/
    │   │   ├── Dashboard.tsx    # Main dashboard with news columns
    │   │   ├── LoginScreen.tsx  # Login interface
    │   │   ├── Navbar.tsx       # Navigation bar
    │   │   ├── NewsCard.tsx     # Individual news article card
    │   │   └── NewsColumn.tsx   # Category news column
    │   └── contexts/
    │       ├── AuthContext.tsx  # Authentication state
    │       └── UserProfileContext.tsx  # User profile management
    ├── lib/
    │   ├── types.ts             # TypeScript type definitions
    │   └── websocket.ts         # HTTP polling client
    ├── package.json             # Frontend dependencies
    └── next.config.ts           # Next.js configuration

🔧 Technology Stack

Backend

• Language: Python 3.13
• Framework: Flock (AI orchestration)
• AI: Azure OpenAI GPT-4
• MCP Servers:
  • duckduckgo-mcp-server - Web search
  • yahoo-finance-mcp - Financial news
  • @just-every/mcp-read-website-fast - Web scraping
• API: FastAPI (included in Flock)

Frontend

• Framework: Next.js 15 (App Router)
• Language: TypeScript
• Styling: Tailwind CSS 4
• UI: React 19
• State: React Context API
• HTTP Client: Fetch API

🤖 AI Agents Architecture

The backend uses a multi-agent system with specialized roles:

1. Task Master Agent

   • Consumes: User login messages
   • Publishes: Category-specific search tasks
   • Role: Breaks down user interests into actionable research tasks

2. Category Researchers (4 specialized agents)

   • Sports Topics Researcher
   • Politics Topics Researcher
   • Finance Topics Researcher
   • Technology Topics Researcher
   • Each uses MCP tools to search and summarize news

3. MCP Server Integration

   • Web search via DuckDuckGo
   • Financial data from Yahoo Finance
   • Website content extraction for article summaries

🔄 Data Flow

User Login → Frontend
    ↓
HTTP POST to /api/publish
    ↓
Agent Backend receives UserLoggedInMessage
    ↓
Task Master Agent creates SearchRequest artifacts
    ↓
Category Researcher Agents process tasks
    ↓
NewsList artifacts published
    ↓
Frontend polls /api/artifacts
    ↓
Dashboard displays news cards

🐛 Troubleshooting

Backend Issues

Problem: Backend fails to start

• Solution: Verify Python 3.13 is installed: python --version
• Solution: Ensure Azure OpenAI credentials are correct in .env
• Solution: Check that uv is installed: uv --version

Problem: "Model not found" error

• Solution: Verify your Azure OpenAI deployment has the gpt-4.1-swedencentral model
• Solution: Update the model name in main.py line 123 if using a different deployment

Problem: MCP servers fail to start

• Solution: Ensure uvx and npx are in your PATH
• Solution: Check internet connectivity for downloading MCP servers

Frontend Issues

Problem: "API_BASE_URL is not configured" error

• Solution: Create .env.local with NEXT_PUBLIC_API_BASE_URL
• Solution: Ensure the backend is running on the specified port

Problem: No news articles appearing

• Solution: Check backend logs for AI agent errors
• Solution: Verify network connectivity to the backend
• Solution: Open browser DevTools → Network tab to check API calls

Problem: Port 3000 already in use

• Solution: Change the port: pnpm dev -- -p 3001

📝 Development Notes

Backend Development

• The backend uses asyncio for concurrent agent execution
• Agents prevent self-triggering to avoid infinite loops
• All message types are Pydantic models for validation
• The system supports dashboard v2 for real-time monitoring

Frontend Development

• Uses HTTP polling instead of WebSockets for artifact retrieval
• Polling interval is 2 seconds (configurable in websocket.ts)
• Artifacts are deduplicated by ID to prevent duplicate displays
• The UI supports infinite scrolling in news columns

🔐 Security Considerations

• Never commit .env or .env.local files (they're gitignored)
• Store Azure OpenAI credentials securely
• In production, use proper authentication instead of demo login
• Implement rate limiting for API endpoints
• Use HTTPS in production environments