Agentic Trading Architecture
Relevant source files
The following files were used as context for generating this wiki page:
The Agentic Trading Architecture is a modular, tool-based framework designed for building, testing, and deploying autonomous trading strategies. Built using pydantic-ai, the system enables structured agents to reason over market data, make explainable trade decisions, and interact with external trading interfaces through a standardized tool-calling pattern. Sources: PLAN.md:1-11, agent.py:10-15
The architecture prioritizes composability and explainability, treating trading strategies as data-driven jobs. It supports multiple operational modes, including historical data replay for backtesting, paper trading with live market feeds, and live execution through brokers like Interactive Brokers. Sources: PLAN.md:46-52, PLANNING.md:4-11
Core Components
The system is structured into several functional directories that separate logic, memory, and execution. Sources: PLAN.md:15-25
Agents
Agents are the decision-making units of the system. They inherit from a BaseAgent and implement specific logic to observe market ticks and return structured TradeDecision objects. Sources: PLAN.md:17, agent.py:91-105
- LongAgent: Decides to
buy_to_openorsell_to_closebased on price relation to moving averages. Sources: agent.py:112-126 - ShortAgent: Decides to
sell_to_openorbuy_to_closefor short-selling strategies. Sources: agent.py:133-147 - ReportAgent: Generates daily summaries including P&L, open positions, and data usage. Sources: agent.py:155-174
Tools
Tools are typed wrappers around external capabilities, following the ToolCall / ToolResponse pattern. They allow agents to interact with the outside world. Sources: PLAN.md:54-65
| Tool | Description |
|---|---|
InteractiveBrokersClientTool | Submits, cancels, and monitors orders. |
MarketDataTool | Subscribes to live or historical data feeds. |
ReportGeneratorTool | Summarizes positions, risk, and P&L. |
VectorLoggerTool | Annotates decisions for vector-based retrieval. |
pull_historical_data | Fetches data from providers like yfinance and saves as CSV. |
plot_time_series | Visualizes market data for analysis. |
| Sources: PLAN.md:58-63, agent.py:34-82 |
Logic and Data Flow
The following diagram illustrates the high-level interaction between market data, the agent's reasoning process, and the execution of trades.
The agent observes streaming or replayed market data, makes a decision, and stores both the action and the reasoning for auditability. Sources: PLAN.md:10-13, PLANNING.md:14-22
Execution Environment
The system operates across three distinct stages of the trading lifecycle. Sources: PLAN.md:46-52
Backtesting and Replay
The replay/ engine simulates historical trades for a given agent. It requires the definition of take-profit levels, stop-loss levels, and position sizing, which are considered the "art" of the strategy. Sources: PLAN.md:19, PLANNING.md:4-9
Paper and Live Trading
These modes use live market data. Paper trading simulates execution without financial risk, while live trading hooks into Interactive Brokers for real execution. Both modes utilize the same set of agent tools for consistency. Sources: PLAN.md:49-51, PLANNING.md:14-23
The sequence demonstrates the asynchronous flow between reasoning and execution, ensuring all steps are logged to a vector-backed database. Sources: PLAN.md:10-13, PLANNING.md:14-30
Memory and Reporting
The architecture incorporates a persistent memory layer using Postgres with pgvector to store decision logs and embeddings. This enables vector search over historical trading decisions to improve future strategy optimization. Sources: PLAN.md:20, PLAN.md:32
The reporting module handles both pre-market and end-of-day operations:
- Pre-market: Generates reports using web-scraping (e.g., via MCP servers).
- Post-market: Summarizes daily P&L, open positions, and data consumption.
Sources: PLANNING.md:25-30, agent.py:155-165
Philosophy
The Agentic Trading System is built on the philosophy that trading strategies are "composable tools." Strategies are broken down into small, independently testable units that can participate in multi-step workflows or meta-strategies. Determinism in backtesting and explainability in live trading are central to the architecture's design. Sources: PLAN.md:84-91
Summary: The Agentic Trading Architecture provides a robust framework where agents leverage specialized tools and persistent memory to execute strategies across replay and live environments. By using structured reasoning and logging, it ensures that every trade is backed by an explainable decision process. Sources: PLAN.md:7-13, PLAN.md:84-91