TL;DR

This publication presents Agentic Forex AI, a fully containerized multi-agent system that automates daily forex market analysis using news streams, technical indicators, and rule-based validation. It integrates FastAPI, Streamlit, and Prometheus-based observability for a real-time, interactive decision-support dashboard. The solution demonstrates how open-source orchestration of AI agents can produce trustworthy recommendations (BUY / SELL / AVOID) with traceable logic, logs, and performance metrics—deployable via Docker and Railway.

Abstract

Agentic Forex AI represents the culmination of the Agentic AI Developer Capstone Project, transforming a modular multi-agent prototype into a production-grade, observable, and reliable forex decision-support system. It integrates five coordinated agents — Market, News, Strategy, Validation, and Email — to generate daily recommendations across 20 major and minor currency pairs.

Each recommendation is derived from real-time market data (via yFinance) and sentiment cues (via RSS news parsing), validated through safety guards, and automatically delivered to users through an email notification pipeline. The system is fully containerized, combining FastAPI for orchestration, Streamlit for visualization, and Prometheus for monitoring and metrics collection.

Beyond its technical implementation, the project demonstrates key principles of responsible AI deployment: input validation, operational resilience, performance logging, and transparent observability. Deployed via Docker and Railway, it showcases how open, reproducible architectures can bridge the gap between intelligent automation and production reliability in real-world financial applications.

1. Introduction

Purpose and Motivation

Forex traders and analysts often rely on fragmented tools—such as economic calendars, RSS feeds, and chart patterns—to make time-sensitive decisions. Agentic Forex AI unifies these signals into a reproducible, explainable multi-agent system that delivers consistent, transparent recommendations daily.

Why This Matters

By automating routine analysis and embedding observability, the system:

• Reduces manual monitoring time for traders.
• Encourages explainable automation in financial analytics.
• Demonstrates best practices for real-world agentic AI deployment.

This system illustrates how modular AI design, when integrated with strong guardrails and documentation, can move from experimentation to reliability — a critical leap for any production-grade intelligent assistant.

2. System Architecture

2.1 Overview

The architecture unifies five operational layers inside a Docker container:

---

2.2 Multi-Agent Workflow

The agent pipeline operates as a single coordinated workflow triggered through safe_run_pipeline_once(). Each agent contributes independently but communicates synchronously — ensuring that a network or data failure in one agent doesn’t collapse the system.

---

2.3 Tools Layer Overview

The tools layer abstracts functionality, promoting reusability and consistency across agents. Each tool handles its own error management and logging — an important feature for reliable production pipelines.

---

2.4 Supported Pairs

Major Pairs:
EURUSD, USDJPY, GBPUSD, USDCHF, AUDUSD, USDCAD, NZDUSD

Minor Pairs:
EURGBP, EURJPY, GBPJPY, EURCHF, EURAUD, AUDJPY,
GBPCHF, NZDJPY, CADJPY, AUDNZD, EURCAD, CHFJPY, GBPAUD, AUDCAD, GBPCAD

All pairs are validated by input_validation.py using dynamic whitelisting to prevent unsupported or malformed currency symbols.

2.5 Orchestration Framework

Agent interactions are coordinated through a lightweight orchestration layer implemented in graph.py. This layer:

• Defines the execution order of Market → News → Strategy → Validation → Email
• Ensures synchronous communication between agents
• Provides the safe_run_pipeline_once() wrapper for resilient execution
• Includes guardrails such as timeouts, retry handling, exception capture, and fallback outputs
• Logs structured traces for every major step to support debugging and evaluation

The orchestration framework is supported by additional modules that reinforce stability and predictability:

• pipeline_safety.py — enforces timeout protection, retry logic, and safe execution wrappers for each stage.
• validation_guard.py — performs runtime checks, input validation, and controlled fallback behavior.

Together, these components coordinate all agents in a predictable, fault-tolerant workflow while keeping the system modular and easy to extend.

2.6 Human-in-the-Loop (HITL) Integration

While the system runs autonomously, several intentional checkpoints allow human review and intervention:

• Streamlit Dashboard: Users can inspect market data, news signals, and generated recommendations.
• Email Agent: Users receive recommendations via email, allowing manual validation before taking action.
• Validation Guard: Rejects malformed input, reducing operator error.
• Trace Logs: Provide full transparency so users can audit decisions step-by-step.

This balance of automation + human review ensures safe and explainable deployment of AI in financial contexts.

2.7 User-Centered Design Decisions

Agentic Forex AI incorporates several user-focused design principles to ensure clarity, transparency, and ease of use. The Streamlit dashboard emphasizes clean visual hierarchy, presenting market data, news signals, and recommendations in an intuitive layout that supports quick decision-making. Errors and warnings are surfaced directly to the user through descriptive messages and real-time status indicators, reducing confusion during failure scenarios. The system’s modular visualizations, interactive controls, and trace logs were designed to help users understand why a recommendation was generated, strengthening trust and explainability.

3. Implementation Details

The system’s modular architecture ensures flexibility, clear role separation, and easy extensibility. The agents follow event-driven logic, reacting to market or news changes and recording every run as structured trace data.

3.1 Core Stack

Each technology was selected for its reliability and open-source support, enabling transparent deployment and easy contribution from the developer community.

---

3.2 Repository Structure

├── api.py                         # FastAPI backend (main API routes)
├── dashboard.py                   # Streamlit dashboard UI
├── Dockerfile                     # Docker image configuration
├── requirements.txt               # Python dependencies
├── supervisord.conf               # Supervisor config for API + Dashboard
├── README.md                      # Project documentation
│
├── src/
│   ├── agents/
│   │   ├── market_agent.py        # Fetches forex candles via yfinance
│   │   ├── news_agent.py          # Parses news from FXStreet, Investing.com, DailyFX
│   │   ├── strategy_agent.py      # Combines data → issues BUY/SELL/AVOID
│   │   └── email_agent.py         # Sends daily strategy report to Gmail
│   │
│   ├── tools/
│   │   ├── yfinance_tool.py       # Handles price data retrieval
│   │   ├── rss_tool.py            # RSS parsing and cleaning
│   │   ├── strategy_tools.py      # Core logic for combining market + news data
│   │   └── email_tool.py          # Email sending utility (smtplib-based)
│   │
│   ├── guardrails/
│   │   ├── input_validation.py    # Validates currency pairs and API input
│   │   ├── pipeline_safety.py     # Safe execution wrapper for resilience
│   │   └── validation_guard.py    # Ensures runtime safety & fallback logic
│   │
│   ├── utils/
│   │   └── logger.py              # Logging utilities with Loguru
│   │
│   ├── graph.py                   # Defines multi-agent pipeline graph
│   ├── schemas.py                 # Pydantic models (Candle, NewsItem, Recommendation)
│   └── main.py                    # Entry point for multi-agent orchestration
│
├── data/
│   ├── traces/                    # JSON logs of each pipeline execution
│   └── samples/                   # Example test data or responses
│
├── tests/
│   ├── test_agents.py             # Unit tests for each agent
│   ├── test_pipeline.py           # Integration tests across agents
│   └── test_end_to_end.py         # End-to-end system tests 

This structure promotes maintainability and traceability. The clear separation between agents, tools, guards, and utilities ensures that future developers can extend or modify components with minimal friction.

4. Implementation & Testing

4.1 Testing Strategy

Agentic Forex AI uses a layered testing strategy to validate behavior from individual components up to full system runs.

Coverage Goal: ≥ 70% of all core functions under src/agents/ and src/tools.

Current coverage (measured via pytest --cov=src) is ~56% overall, with higher coverage on critical modules such as validation, schemas, orchestration (graph.py), and core tools (yfinance_tool.py, news_tool.py). Additional tests are planned for agent wrappers and pipeline safety fallbacks.

Example run:

pytest --maxfail=1 --disable-warnings -q --cov=src

4.2 Evaluation & Logging

Each pipeline run logs structured JSON traces in /data/traces/ including timestamps, execution durations, validation flags, pair symbols, and email confirmations. This detailed logging ensures full traceability and helps evaluate both correctness and system health over time.

4.3 Resilience & Fault Tolerance

The system includes several resilience mechanisms:

• Retry logic for RSS requests and yFinance retrieval
• Timeout protection through pipeline_safety.py
• Graceful fallback behavior when news feeds are unavailable
• Input validation preventing unsupported currency pairs
• Structured error logging in /data/traces/

These resilience features ensure that transient network failures or malformed data do not break the pipeline.

5. Monitoring and Observability

5.1 Prometheus Metrics Integration

Metrics exposed at /api/metrics include:

• api_request_total — tracks total API requests.
• api_request_latency_seconds — measures response latency.
• api_health_status — reports application health (1 = healthy, 0 = degraded).

These metrics enable proactive monitoring and performance tuning. With Prometheus (and optional Grafana dashboards), developers can track agent activity, request behavior, and overall system health in real time.

5.2 Additional Observability Signals

Agentic Forex AI provides further visibility through lightweight, developer-friendly observability features:

• Structured Trace Logs: Each pipeline run generates a JSON trace in data/traces/, capturing agent execution order, timestamps, fallback logic, and validation outcomes.
• Loguru Runtime Logging: Detailed logs record warnings, failure points, and agent-level events to support quick debugging.
• Health Endpoint: The /api/health route exposes the real-time status of the system, allowing both users and monitoring tools to detect degraded or failing states early.

Together, these mechanisms ensure full transparency into pipeline behavior and support reliable, production-grade operation.

6. Prerequisites & Requirements

To run or extend Agentic Forex AI, users should have:

System Requirements

• Python 3.10+
• 4 GB RAM Minimum
• Docker installed (optional but recommended)

Python Dependencies

Installed automatically via requirements.txt:

• FastAPI, Uvicorn
• Streamlit
• feedparser
• yfinance
• Pydantic
• Prometheus client
• Loguru

Knowledge Prerequisites

Users should be familiar with:

• Basic Python scripting
• REST APIs
• JSON data formats
• Fundamentals of financial candles & forex terminology
• Running Docker containers (optional)

7. Reproducibility and Deployment

7.1 Local Run

To build and run the project locally:

docker build -t forex-ai .
docker run -p 8501:8501 -p 8000:8000 forex-ai

Access the application via:

• Dashboard: http://localhost:8501
• API Health: http://localhost:8000/api/health

This design ensures complete reproducibility across environments. Developers can reproduce the exact deployment with a single Docker command, ensuring consistent results and dependency isolation.

---

7.2 Cloud Deployment (Railway)

1. Connect your GitHub repository to Railway.

2. Select Dockerfile as the deployment method.

3. Set the environment variable:

   API_URL=https://<your-railway-app>.up.railway.app/api

4. Deploy your project.

5. Verify the logs — you should see messages like:

   success: api entered RUNNING state
   success: dashboard entered RUNNING state

The Railway integration allows one-click CI/CD deployment, turning the local agentic system into a continuously running cloud service.

8. Limitations and Future Work

While the current version focuses on reliability and modularity, future enhancements aim to introduce ML-based sentiment models, streaming data ingestion, and scalable container orchestration — paving the way toward a fully autonomous trading assistant.

9. Conclusion

Agentic Forex AI embodies the principles of safety, stability, and explainability, delivering practical value in real-world decision-making contexts. It serves as a demonstration of how AI systems can achieve transparency, traceability, and operational robustness while serving an applied domain, such as financial analytics.

10. Maintenance & Support Status

Agentic Forex AI is an actively maintained technical asset, and improvements will be released as the system evolves. The following areas are monitored:

• API stability (breaking changes will be versioned)
• Agent performance (market/news/strategy)
• Error logs & trace outputs
• Dependency updates (yFinance, feedparser, FastAPI, Prometheus client)
• Security patches and bug fixes

Planned support includes:

• Regular updates to all tools and agents
• Migration guides when major changes occur
• Continuous improvement informed by community and Ready Tensor feedback

Support Channels:

Users can report bugs, request enhancements, or seek support through the GitHub Issues tab in the project repository. All reported items are reviewed regularly as part of ongoing maintenance.

11. License Rationale (CC BY-SA)

The Creative Commons Attribution-ShareAlike (CC BY-SA) license was selected to align with the project’s open innovation goals. It allows anyone to use, adapt, and distribute this work, provided proper credit is given and derivative works are shared under identical terms. This ensures collective improvement while maintaining attribution integrity. The “ShareAlike” clause encourages transparent evolution of the system, reinforcing Ready Tensor’s mission of open, reproducible AI development.

12. Resources

• GitHub Repository: https://github.com/Sarah-Mashhood/forex-agentic-ai
• Live Demo (Railway): https://forex-agentic-ai.up.railway.app
• Prometheus Endpoint: /api/metrics
• Health Endpoint: /api/health

13. Demo