Pydantic AI Tool Interfaces
Relevant source files
The following files were used as context for generating this wiki page:
Pydantic AI Tool Interfaces within the Agentic Trading System provide a modular framework for wrapping external capabilities into structured, typed tools that an AI agent can utilize for financial decision-making. These interfaces enable agents to observe market data, execute trade reasoning, and interact with external APIs—such as Interactive Brokers or PostgreSQL databases—using the pydantic-ai library to ensure structured output and decision explainability.
Sources: PLAN.md:1-12, agent.py:8-16
The system architecture focuses on "composable" strategies where trading logic is treated as data-driven jobs. These tools facilitate multi-step workflows, allowing agents to annotate reasoning (e.g., "momentum breakout") and store logs for historical backtesting and optimization.
Sources: PLAN.md:73-80, PLANNING.md:5-10
Tool Architecture and Patterns
The project utilizes pydantic-ai to define tools as typed wrappers around external capabilities. Every tool conforms to the ToolCall and ToolResponse pattern, ensuring that the agent receives structured data instead of raw text.
Sources: PLAN.md:61-69
Agent-Tool Interaction Flow
The following diagram illustrates how an agent utilizes financial tools to process a user request and interact with market data.
The diagram shows the flow from a user prompt to the execution of specific Python functions decorated as tools.
Sources: agent.py:34-75
Core Tool Implementation
Tools are implemented using the @finance_agent.tool decorator, which registers Python functions as available actions for the AI agent. These tools typically handle data acquisition and visualization.
Sources: agent.py:34-35, agent.py:60-61
Data Acquisition Tools
The system includes tools to interface with financial APIs like yfinance to retrieve historical market information.
| Tool Name | Parameters | Purpose |
|---|---|---|
pull_historical_data | ticker, start, end | Downloads ticker data and saves to CSV. |
plot_time_series | csv_file, column, title | Generates a PNG plot from stored CSV data. |
Sources: agent.py:34-75
Trading Logic Interfaces (Planned)
The system defines specific "trading verbs" that tools must implement to support both paper and live trading modes.
- Long Strategy Tools:
buy_to_open,sell_to_close. - Short Strategy Tools:
sell_to_open,buy_to_close. - Monitoring Tools:
check_open_positions,check_daily_pnl,check_daily_data_usage. - Reporting Tools:
generate_pre_market_report,generate_daily_report.
Sources: PLANNING.md:14-32, agent.py:19-32
Integration with Backtrader Strategies
The Pydantic AI tools are designed to work alongside backtrader strategies. While the tools handle the agentic reasoning and external API calls, the backtrader engine handles the technical execution and indicator calculations.
Sources: PLAN.md:1-10, strategies/moving_average_crossover.py:175-185
Structured Decision Logic
Agents utilize indicators (like those found in Backtrader) to make decisions that are then passed through the tool interface.
class LongAgent(BaseAgent):
def decide(self, market_data: dict) -> dict:
# Example logic for long strategy
if market_data["price"] > market_data["moving_average"]:
return {
"action": "buy_to_open",
"reason": "Price above moving average",
}
return {
"action": "sell_to_close",
"reason": "Price below moving average",
}
Sources: agent.py:100-117
Data Persistence and Logging
A critical component of the tool interface is the VectorLoggerTool. This planned tool is responsible for annotating decisions for vector search, allowing the system to use pgvector to store and retrieve decision logs.
Sources: PLAN.md:10-12, PLAN.md:67-68
Database Interaction Flow
The strategies implemented in the project (such as risk_adverse.py and moving_average_crossover.py) demonstrate how tools interact with a PostgreSQL backend to retrieve OHLC data for analysis.
The sequence shows the data retrieval pattern used by both agent tools and backtesting strategies.
Sources: strategies/risk_adverse.py:483-490, strategies/moving_average_crossover.py:440-445
Conclusion
Pydantic AI Tool Interfaces serve as the bridge between the high-level reasoning of the Agentic Trading System and the low-level execution of trading strategies and data providers. By enforcing strict typing and structured outputs, these interfaces ensure that trade decisions are explainable, reproducible via backtesting, and ready for deployment across different operation modes including Replay, Paper Trading, and Live Trading.
Sources: PLAN.md:1-12, PLAN.md:46-52