Skip to main content

​
Silvia Agent Architecture Overview

​
Main Chat Agent

Location: app/api/chat/route.ts + app/api/chat/tools.ts The Silvia agent is powered by Claude Sonnet 4.5 and operates as a conversational AI with access to specialized financial tools. The agent uses a tool-calling architecture where it can invoke specific functions to access user data, perform calculations, and trigger background analyses.

​
Key Features

  • Token Management: Implements 1M context window with automatic message trimming to stay within limits
  • Caching Strategy: Uses Anthropic’s prompt caching for system prompts, tools, and conversation history to reduce costs and latency
  • Retry Logic: Built-in retry mechanism with exponential backoff for handling API failures
  • Tool Execution: Sequential tool calling with comprehensive debugging and timeout protection (30s per tool)

​
Core Tool Categories

  1. Financial Data Tools: Get portfolio metrics, holdings, accounts, transactions, goals
  2. Scenario Tools: Create and manage deep financial analyses (createScenario, getScenarios, getScenarioById)
  3. Radar Tools: Set up monitoring schedules (createRadarEvent, getRadarEvents, deleteRadarEvent)
  4. Document Tools: Search vault documents, chat history, reference materials
  5. Market Tools: Web search via Exa API for real-time financial news

​
Scenarios System

Location: app/scenarios + AWS Backend Scenarios enable complex “what-if” financial analysis that can take 1-10 minutes to complete. When a user asks analytical questions requiring simulation or deep research, the agent uses the createScenario tool.

​
Workflow

  1. User Request: Agent determines if question requires scenario analysis
  2. Creation: Posts to AWS backend (NEXT_PUBLIC_SCENARIOS_API_URL/consultations)
  3. Processing: Backend analyzes user data, runs simulations, generates charts
  4. Polling: Frontend polls status endpoint every 5 seconds for updates
  5. Completion: Results displayed with charts, analysis, and code executions

​
Integration with Chat

  • Agent creates scenarios via tool call when needed
  • Scenarios conditionally disabled via scenariosEnabled flag in chat settings
  • Users can ask follow-up questions by clicking “Ask Follow-up” which loads scenario context into chat

​
Radar System

Location: app/radar + AWS Backend Radar provides proactive monitoring of portfolio conditions on recurring schedules (daily, weekly, monthly). It runs analyses automatically and generates alerts when conditions are met.

​
Architecture

  • Schedules: User-defined monitoring rules with specific prompts (e.g., “Alert when portfolio risk exceeds 15%”)
  • Execution: AWS Lambda runs scheduled analyses using user’s financial data
  • Results: Posted to radar feed where users can view insights
  • Integration: Radar can automatically create scenarios for deeper analysis

​
Two-Feed System

  1. SilviaFeed: AI-generated portfolio insights and market commentary
  2. RadarFeed: User-configured alerts and monitoring results

​
Internal API Endpoints

Location: app/api/internal Background processes that sync financial data:
  • process-holdings-sync: Syncs investment holdings from Plaid
  • process-transactions-sync: Syncs bank transactions
  • process-snaptrade-holdings-sync: Syncs SnapTrade holdings (alternative provider)
  • process-recurring-transactions: Identifies and categorizes recurring expenses
These run on schedules (typically daily) to keep user data fresh without manual intervention.

​
Data Flow Summary

​
Key Design Decisions

  1. Async Processing: Long-running analyses (scenarios, radar) happen in background to avoid API timeouts
  2. Polling Strategy: Frontend polls for updates rather than WebSockets for simplicity
  3. Tool Isolation: Each tool has timeout protection and error handling to prevent cascade failures
  4. Conditional Features: Scenarios can be toggled per-chat session based on user preference