This project demonstrates an agent-based trading system simulation featuring distinct agents for trading logic and risk management, communicating via the Agent-to-Agent (A2A) protocol. It includes a web-based simulator UI to configure, run, and visualize trading strategy performance.

Disclaimer: ⚠️ This application is intended for educational and demonstration purposes only. It does not constitute financial, investment, legal, or trading advice. Trading involves significant risk, and you could lose your entire investment. Do not use this application for actual trading decisions or with real money. Use at your own risk.

• Modular Agent Architecture: Separates concerns into distinct services:
  • AlphaBot: Implements a trading strategy (Simple Moving Average - SMA crossover) and proposes trades. Built using the Google Agent Development Kit (ADK).
  • RiskGuard: Evaluates trade proposals from AlphaBot against configurable risk rules (max position size, max portfolio concentration). Also built using ADK.
  • Simulator UI: A FastAPI-based web application to configure simulation parameters, run the simulation, and visualize results using Plotly.
• Agent-to-Agent (A2A) Communication: Leverages the open A2A protocol for standardized, interoperable communication between the AlphaBot and RiskGuard agents. This allows agents built with different frameworks (like ADK in this case) to discover capabilities and interact securely.
• Configurable Simulation: Adjust parameters for market conditions (initial price, volatility, trend), trading strategy (SMA periods, trade quantity), and risk rules.
• Portfolio Tracking: Simulates portfolio changes (cash, shares, total value) based on executed trades.
• Visualization: Displays simulation results, including price action, SMA indicators, portfolio value, and trade execution markers on interactive charts.
• Local & Cloud Deployment: Includes scripts for easy local execution and deployment to Google Cloud Run.
• Containerized Services: Dockerfiles provided for building container images for each service, facilitated by Google Cloud Build.

The system consists of three main services interacting via HTTP and the A2A protocol:

1. Simulator UI (FastAPI):

   • Serves the web interface to the user.
   • Takes simulation parameters from the user.
   • Runs the market simulation loop.
   • For each step, it calls the AlphaBot service (A2A tasks/send) with current market data and portfolio state.
   • Receives trade decisions (approved/rejected trades or status updates) back from AlphaBot.
   • Updates the portfolio state based on executed trades.
   • Visualizes the results.

2. AlphaBot (ADK/Python):

   • Receives A2A requests from the Simulator.
   • Analyzes market data (calculates SMAs) to determine a potential trade signal (BUY/SELL).
   • If a trade is proposed, it calls the RiskGuard service (A2A tasks/send via a2a_risk_tool.py) with the trade proposal and portfolio state.
   • Receives the risk assessment result (approved/rejected) from RiskGuard.
   • Updates its internal state (_should_be_long).
   • Returns the final trade decision (including risk assessment outcome) back to the Simulator via an A2A response, potentially using artifacts.

3. RiskGuard (ADK/Python):

   • Receives A2A requests from AlphaBot containing a trade proposal and portfolio state.
   • Evaluates the proposal against configured risk rules (rules.py).
   • Returns the risk assessment result (approved/rejected with reason) back to AlphaBot via an A2A response, typically within an artifact.

graph LR
    User[Browser User] -- HTTP --> SimUI(Simulator UI<br>FastAPI);
    SimUI -- A2A (tasks/send) --> AlphaBot(AlphaBot Agent<br>ADK);
    AlphaBot -- A2A (tasks/send) --> RiskGuard(RiskGuard Agent<br>ADK);
    RiskGuard -- A2A Response --> AlphaBot;
    AlphaBot -- A2A Response --> SimUI;

This project utilizes the A2A protocol for the critical communication link between the trading logic (AlphaBot) and the risk assessment logic (RiskGuard). Here's how it applies the core A2A concepts:

• A2A Server: Both AlphaBot and RiskGuard act as A2A Servers, exposing HTTP endpoints defined by the A2A specification.
• A2A Client:
  • The Simulator UI acts as a client when initiating a task with AlphaBot (tasks/send).
  • AlphaBot acts as a client when sending a trade proposal task to RiskGuard (tasks/send).
• Task: The primary unit of work.
  • The Simulator sends a task to AlphaBot containing market/portfolio data.
  • AlphaBot sends a sub-task to RiskGuard containing the proposed trade details.
• Message/Part: Data like market state, portfolio details, and trade proposals are exchanged within A2A Messages using appropriate Parts (likely DataPart for structured JSON).
• Artifact: RiskGuard returns its assessment (approved/rejected with reason) as an Artifact within the A2A response to AlphaBot. AlphaBot may also use artifacts to return structured results to the Simulator.
• Agent Card: While not explicitly fetched dynamically in this simplified local setup, in a real-world scenario, AlphaBot could discover RiskGuard's capabilities and endpoint URL by fetching its agent.json file (Agent Card). The ADK framework handles much of the underlying A2A protocol implementation details.

This demonstrates how A2A enables modularity, allowing specialized agents to collaborate effectively.

• Python (Version 3.11+ recommended)
• Google Cloud SDK (gcloud) (Required for Cloud Run deployment)

1. Clone the repository:

   git clone https://github.com/kweinmeister/agentic-trading
   cd agentic-trading

2. Install Python dependencies: Create a virtual environment (recommended):

   python -m venv venv
   source venv/bin/activate # On Windows use `venv\Scripts\activate`

   Install all requirements for local development and testing:

   pip install -r requirements.txt

The easiest way to run all services locally is using the provided script:

./deploy_local.sh

This script will:

• Start the RiskGuard service (Default: http://127.0.0.1:8080)
• Start the AlphaBot service (Default: http://127.0.0.1:8081)
• Start the Simulator UI service (Default: http://127.0.0.1:8000)

Wait for the script to report that all services have started, then access the Simulator UI in your browser at http://127.0.0.1:8000.

To stop the services, use the kill command shown in the script's output or Ctrl+C if you run the commands manually.

Ensure development dependencies are installed:

pip install -r requirements-dev.txt

Run tests using pytest:

pytest tests/

This application includes scripts and configuration for deployment to Google Cloud Run.

The deploy_cloud_run.sh script automates the deployment of all three services to Cloud Run, making them publicly accessible.

Before running:

1. Set your Google Cloud Project ID: Edit the script and replace "your-gcp-project-id" with your actual project ID, or set the PROJECT_ID environment variable.
2. Authenticate gcloud: Ensure you are logged in with the necessary permissions (gcloud auth login, gcloud config set project YOUR_PROJECT_ID).
3. Enable APIs: The script attempts to enable required APIs (Cloud Run, Cloud Build, Artifact Registry). Ensure your account has permission to do this.

Run the script:

./deploy_cloud_run.sh

The script will:

1. Create a Google Artifact Registry repository (if it doesn't exist).
2. Build container images for RiskGuard, AlphaBot, and Simulator using Google Cloud Build (cloudbuild-*.yaml files) and push them to Artifact Registry.
3. Deploy each service to Cloud Run, configuring necessary environment variables (RISKGUARD_SERVICE_URL, ALPHABOT_SERVICE_URL) for inter-service communication.
4. Output the final URL for the Simulator UI.

Important Security Note: The public deployment script makes your services accessible to anyone on the internet. For production or sensitive environments, you must secure your deployment. Consider using Google Cloud Identity-Aware Proxy (IAP) or other authentication/authorization mechanisms to control access.

• Default Parameters: Default settings for SMA periods, risk limits, simulation parameters, and local service URLs are defined in common/config.py.
• Service URLs (Deployment): When deploying to Cloud Run, the deployment scripts automatically pass the necessary service URLs (RISKGUARD_SERVICE_URL, ALPHABOT_SERVICE_URL) as environment variables to the dependent services (AlphaBot needs RiskGuard's URL, Simulator needs both).
• Environment Variable PORT: The Dockerfiles and Cloud Run use the standard PORT environment variable (automatically provided by Cloud Run) to determine the listening port.

Contributions are welcome! Please feel free to submit pull requests or open issues.

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.