Building Finnie — A Production-Grade Multi-Agent AI System for Financial Awareness

Democratizing access to high-quality financial literacy requires much more than wrapping an LLM prompt with a chat interface. Personal finance demands high precision, strict contextual guardrails, real-time data integration, and absolute system resilience. To bridge this gap, I developed Finnie — AI Finance Assistant, an open-source, production-grade multi-agent system built to act as an intelligent gateway for financial education, awareness, and decision-making.

In this deep-dive post, we will explore Finnie’s underlying architecture, how it leverages advanced software engineering patterns like circuit breakers and fail-closed guardrails, and how comprehensive telemetry turns complex multi-agent handovers into an observable engineering flow.

🏗️ 1. The Multi-Agent Orchestration Architecture

At the core of Finnie is an orchestration topology powered by LangGraph and Claude 3.5 Sonnet. Financial questions are multi-faceted; a user might ask for a definition of an asset class in one sentence and demand a breakdown of their real-time stock portfolio in the next.

Finnie manages this by splitting responsibilities across a centralized supervisor graph containing six specialized autonomous agents:

Finance Q&A Agent: Answers core conceptual financial queries, backed by a local FAISS vector store for Retrieval-Augmented Generation (RAG) and FRED macroeconomic data.
Portfolio Analysis Agent: Ingests asset holdings (shares, cost basis) and interfaces with live financial tools to evaluate risk and performance metrics.
Market Analysis Agent: Evaluates sector heatmaps, real-time ticker data, and index movements.
Goal Planning Agent: Runs compounding interest calculations and creates detailed, algorithmic roadmaps for financial milestones (e.g., retirement, savings targets).
News Synthesizer Agent: Fetches live financial headlines to parse sentiment and current event impacts.
Tax Education Agent: Demystifies tax brackets, structural regulations, and common deduction mechanics.

🔒 2. Hardening the Edge: Fail-Closed Guardrails and Circuit Breakers

A production system handling sensitive information cannot afford unfiltered routing or brittle API dependencies. Finnie implements two powerful design patterns to handle these operational edge cases:

A. Fail-Closed Guardrails

Before any query hits the agent graph, it must pass through a two-stage guardrail pipeline. First, a local string blocklist immediately intercepts and strips obvious NSFW or out-of-scope terms without executing a costly LLM call. Second, a rapid classification prompt validates whether the query aligns with the financial learning scope.

Crucially, this architecture is fail-closed. If the guardrail code encounters an internal system error, a timeout, or ambiguous classification results, it default-rejects the request with a polite, pre-defined fallback message rather than risking an unpredictable output.

B. Per-Provider Circuit Breakers

Finnie aggregates data from four external APIs: yFinance, Alpha Vantage, FRED, and NewsAPI. To prevent downstream cascading failures if one of these services suffers an outage or severe rate-limiting, every external data client is wrapped in a stateful Circuit Breaker.

If a specific client encounters successive failures, its breaker trips OPEN, instantly routing future user requests to an elegant degraded placeholder or cached response. While open, the breaker manages asynchronous background checks using a HALF-OPEN probing state, seamlessly closing the circuit once the upstream provider stabilizes.

📊 3. Telemetry, Observability, and the RePPIT Framework

To scale Finnie from a standard prototype into an enterprise-ready system, I integrated the RePPIT framework (pioneered by Mihail Eric). RePPIT provided the structural skeleton necessary to build advanced features into our runtime loop smoothly:

Systematic Evals: Evaluates router classification correctness and output accuracy.
Arize Phoenix Tracing: Deep telemetry embedded throughout the entire execution graph.

By running a centralized dashboard on the Arize Phoenix platform, the entire application becomes fully transparent. We track user requests end-to-end, monitoring metrics like latency and coupon/token consumption.

More importantly, it grants visual clarity into the chain of handovers between the router, the specialized agents, and the underlying LLMs. Instead of guessing how an agent loops or passes context, developers get a crystal-clear waterfall view of every node transition.

🔮 4. The Engineering Roadmap

While the architecture is stable and live, production systems require constant iteration. Future development cycles on Finnie are focused on optimizing two critical vectors:

Fixing RAG Latency: Redesigning text-embedding token pipelines and search indices to minimize Time-To-First-Token (TTFT) when fetching from our local knowledge base.
User-Specific Conversation History: Implementing a multi-session database cache to allow agents to pull historical context over multiple separate sessions, enhancing custom planning continuity.

🚀 Get Involved!

Finnie is live, open-source, and ready for you to experiment with. Whether you want to test its resilience, analyze your portfolio, or audit the multi-agent graphs, I would love your feedback!