⚡️ Build, run, and ship agents — any framework, anywhere

💬 Chat • 🧪 Workbench • 🏗️ AgentOS • 🗄️ DB • 🚦 CI/CD • 🔐 Self-Hosted • 🧑‍💻 Full code access

---

Financial Insights Specialist Agent

An advanced AI agent for comprehensive financial market analysis, built with Agno framework and xpander.ai platform.

This agent leverages OpenAI's GPT-5.2 with high reasoning effort and the Alpha Vantage MCP (Model Context Protocol) to provide deep financial insights, stock analysis, market trends, and investment recommendations.

Features

• Real-Time Market Data: Direct integration with Alpha Vantage API via MCP
• Advanced AI Reasoning: Uses OpenAI GPT-5.2 with high reasoning effort for in-depth analysis
• Comprehensive Analysis: Technical indicators, fundamentals, trend analysis, and positioning
• Storage & Events: Built-in state management and event handling via xpander.ai platform
• Long-Running Tasks: Support for background task execution and monitoring
• Async Operations: High-performance async execution for concurrent data fetching

What This Agent Can Do

Financial Analysis

Ask this agent questions like:

• "Analyze the current situation of AAPL stock and suggest entry points"
• "What's the technical outlook for TSLA over the next month?"
• "Compare the valuation metrics of MSFT vs GOOGL"
• "Give me a risk-adjusted analysis of QQQ ETF"
• "What sectors are showing strength in the current market?"
• "Analyze the earnings trends for semiconductor stocks"

Additional Capabilities

• Daily Market Reports: Automatically send email reports with market intelligence, watchlist performance, and momentum indicators
• Visual Content: Generate custom financial charts and infographics using nano-banana (Google's image generation model, available as a built-in tool)
• Automated Notifications: Schedule recurring analysis reports and alerts based on market conditions

Architecture

This agent uses:

1. Alpha Vantage MCP: Provides real-time and historical market data via Model Context Protocol
2. xpander.ai Platform: Handles storage, events, and task management for long-running operations
3. OpenAI GPT-5.2: High reasoning effort model for deep financial analysis
4. Agno Framework: Agent orchestration and tool integration
5. Built-in Tools (provided by xpander.ai):
   • Send Email: Automated email reports and notifications
   • nano-banana: Google's image generation model for creating custom financial charts and visualizations
   • Code Interpreter: Python execution for complex calculations
   • Sleep: Scheduled tasks and delayed operations

nano-banana use cases:

• Generate custom stock charts with technical indicators
• Create infographics for earnings reports
• Visualize portfolio allocation and performance
• Design branded financial presentations

Files Structure

• xpander_handler.py - Main agent handler with MCP integration
• requirements.txt - Python dependencies (core + dev)
• Dockerfile - Container deployment configuration
• .env.example - Template for environment variables
• Makefile - Development commands
• LICENSE - MIT License
• assets/ - Screenshots and examples
• images/ - Logos and branding

Prerequisites

• Python 3.12+
• xpander.ai CLI
• OpenAI API key (for GPT-5.2)
• Alpha Vantage API key (get free key)
• xpander.ai account (sign up)

Quick Start

1. Clone and Install

git clone <this-repo>
cd financial-insights-specialist
python3 -m venv .venv
source .venv/bin/activate
make install

2. Configure Environment

Copy .env.example to .env and fill in your API keys:

cp .env.example .env

Required environment variables:

# xpander.ai Platform (get from app.xpander.ai)
XPANDER_API_KEY="your_xpander_api_key"
XPANDER_ORGANIZATION_ID="your_org_id"
XPANDER_AGENT_ID="your_agent_id"

# Alpha Vantage (get your FREE key from alphavantage.co/support/#api-key)
ALPHAVANTAGE_API_KEY="your_alphavantage_key"

# OpenAI (required for GPT-5.2)
OPENAI_API_KEY="your_openai_key"

3. Load Template in xpander.ai

Visit the template page and import it to your xpander.ai account. This will automatically set up the agent configuration.

4. Run Locally

Install the xpander.ai CLI:

npm install -g xpander-cli
xpander login

Run the agent locally for testing:

xpander agent dev

5. Deploy to xpander.ai

Deploy your code to replace the serverless template and run it in the cloud:

xpander agent deploy

Your agent will be live and accessible via the xpander.ai platform!

Optional: Test with Docker

docker build . -t financial-insights-agent
docker run --env-file .env financial-insights-agent

Example Output

Stock Analysis

When you ask: "How would you summarize the current situation of QQQ stock, and based on that analysis, what buy entry levels or conditions would make the most sense for an investor considering a position now?"

The agent provides:

1. Current Price & Movement: Real-time price, daily change, volume analysis
2. Trend & Positioning: Moving averages, 52-week range, technical positioning
3. Market Context: Valuation relative to historical averages
4. Entry Strategy: Specific price levels and conditions for optimal entry
5. Risk Assessment: Considerations based on current market positioning

Daily Market Reports

The agent can automatically generate and email comprehensive daily reports featuring:

• Major Market Trends: Key themes and developments (e.g., AI Infrastructure Supercycle)
• Watchlist Performance: Track your portfolio with price, change, and momentum indicators
• Technical Signals: Bullish crossovers, bearish signals, and neutral positions
• Professional Formatting: Clean, executive-ready reports with charts and visualizations

Why xpander.ai?

Focus on your agent logic, not infrastructure. xpander.ai provides everything you need to run production-grade agents in the cloud:

Zero Infrastructure Hassle

Deploy your agent code and let xpander.ai handle:

• Serverless Execution: No servers to manage, scale automatically with demand
• Built-in Storage: Persistent state, conversation history, and agent memory
• Event System: Real-time webhooks and event-driven workflows
• Task Queue: Long-running background tasks with progress tracking
• Monitoring & Logs: Full observability out of the box
• CI/CD Pipeline: Deploy with a single command (xpander agent deploy)

Production-Ready Features

• Multi-Model Support: Switch between OpenAI, Anthropic, Fireworks, Google, and more
• API & Chat Interface: REST API + built-in chat UI for testing
• Access Control: Team management and API key security
• Cost Tracking: Monitor token usage and costs per agent
• Self-Hosted Option: Deploy on your own infrastructure if needed

Contributing

Contributions are welcome! Please:

1. Follow the existing code style
2. Add type hints to all functions
3. Test your changes locally before submitting
4. Update documentation as needed

License

MIT License - see LICENSE file for details.

Support

• Xpander.ai Documentation
• Agno Framework Docs
• Alpha Vantage API Docs
• Issues

Acknowledgments

Built with:

• Agno Framework by xpander.ai
• Alpha Vantage for financial data
• OpenAI GPT-5.2 for AI reasoning
• xpander.ai Platform for agent infrastructure