使用说明

AI股票推荐器

用于股票分析和投资组合推荐的多代理人工智能系统。该平台使用谷歌的代理开发工具包（ADK）和A2A（代理到代理）协议，其中Host Agent协调专门的子代理提供股票分析、投资组合报告分析和投资建议。

组件

组件	技术栈	端口	用途
前端	React 19、TypeScript、Tailwind CSS、Firebase Auth	3000	具有聊天、认证、配置文件和投资组合视图的用户界面
主机代理	FastAPI、Google ADK、A2A SDK、SQLAlchemy	10001	编排代理、服务REST API、管理会话
股票分析代理	谷歌ADK、A2A SDK、yfinance、困惑AI	10002	分析股票、获取市场数据、生成推荐
股票报告分析代理	Google ADK、A2A SDK、PyMuPDF	10003	分析上传的投资组合PDF和财务文档
MCP服务器	FastMCP、yfinance、pandas_ta	stdio	为代理商提供股票数据工具（价格、新闻、技术）
PostgreSQL	PostgreSQL 15	5432	用户、会话、消息、推荐
瑞迪斯	Redis	6379	针对长时间运行的代理操作的异步任务跟踪

先决条件

python >= 3.12
Node.js >= 18
Docker&Docker编写 （适用于PostgreSQL）
瑞迪斯 （本地安装或Docker）
Google API密钥 （适用于ADK制剂的Gemini API）
Firebase项目 （用于身份验证）

1.数据库设置

通过Docker Compose启动PostgreSQL：

cd backend
docker-compose up -d

这将以以下方式启动PostgreSQL 15实例：

数据库： finance_a2a
用户： postgres
密码： password
端口： 5432

这 init.sql 脚本自动运行并创建： users, conversation_sessions, conversation_messages，以及 agent_states 桌子。

应用迁移（如果需要）

cd backend/host_agent
python apply_migration.py

2.MCP服务器设置

MCP服务器通过以下方式向代理提供股票市场数据工具模型上下文协议.它作为一个 stdio子流程 它由Host Agent和Stock Analyser Agent生成，不需要单独启动。

环境变量

cd mcp
cp .env.example .env

变量	描述
`FINNHUB_API_KEY`	Finnhub API密钥（可选，当前未使用——数据来自yfnance）
`ANTHROPIC_API_KEY`	仅在运行独立MCP客户端测试时需要

MCP工具暴露

工具	说明
`get_stock_symbol_lookup(query)`	搜索最匹配的股票代码
`get_stock_news(symbol)`	获取某只股票的最新新闻文章
`get_price_history(symbol, period, interval)`	RSI、MACD、布林带的历史价格
`search(query, search_type)`	雅虎财经搜索报价或新闻
`get_stock_info(symbol)`	全面的股票信息（估值、财务、资产负债表）
`get_stock_recommendations(symbol)`	分析师对股票的建议
`get_US_market_news()`	最新美国市场新闻摘要

MCP提示

提示	描述
`stock_analysis`	完整的股票分析工作流程（品种查找、信息、技术、推荐）
`market_overview`	全面的市场概况

代理商如何呼叫MCP

两者 主机代理 和 股票分析代理 使用Google ADK将MCP服务器作为子进程生成 MCPToolset 随着 StdioConnectionParams:

from google.adk.tools.mcp_tool.mcp_toolset import MCPToolset, StdioConnectionParams
from mcp import StdioServerParameters

connection_params = StdioConnectionParams(
    server_params=StdioServerParameters(
        command=sys.executable,          # current Python interpreter
        args=["/path/to/mcp/server.py"], # path to MCP server script
        env=mcp_env,
    )
)
stock_mcp_tool = MCPToolset(connection_params=connection_params)

这 MCP_DIRECTORY 配置变量（在Host Agent和Stock Analyser Agent中）指向 mcp/ 文件夹。Host Agent直接使用MCP工具进行投资组合绩效价格查询，而Stock Analyser Agent在其ADK代理中使用它们进行全面的股票分析。

3.后端设置

3a。主机代理（端口10001）

前端与之通信的中央FastAPI服务器。它通过A2A协议协调其他代理。

cd backend/host_agent

# Create and activate virtual environment
python -m venv .venv
source .venv/bin/activate

# Install dependencies
pip install -r ../requirements.txt
pip install google-adk a2a-sdk python-dotenv uvicorn firebase-admin \
            sqlalchemy psycopg2-binary redis slowapi httpx nest_asyncio \
            boto3 PyMuPDF requests

# Configure environment
cp env.example .env
# Edit .env with your values (see table below)

# Run
python __main__.py

Host Agent环境变量

变量	必填	默认	描述
`GOOGLE_API_KEY`	是	--	Google Gemini API密钥
`DATABASE_URL`	是的	`postgresql://postgres:password@localhost:5432/finance_a2a`	PostgreSQL连接字符串
`FIREBASE_PROJECT_ID`	是	--	用于身份验证的Firebase项目ID
`FIREBASE_SERVICE_ACCOUNT_PATH`	是	--	Firebase服务帐户JSON路径
`HOST_AGENT_PORT`	没有	`10001`	Host Agent API的端口
`STOCK_ANALYSER_AGENT_URL`	没有	`http://localhost:10002`	股票分析代理URL
`STOCK_REPORT_ANALYSER_AGENT_URL`	没有	`http://localhost:10003`	股票报告分析器代理URL
`MCP_DIRECTORY`	否	（本地路径）	路径 `mcp/` 目录
`REDIS_URL`	没有	`redis://localhost:6379`	用于异步任务跟踪的Redis URL
`ENVIRONMENT`	没有	`local`	`local` 或 `production`

API关键终结点

方法	端点	描述
`POST`	`/api/login`	Firebase ID令牌登录，返回/创建用户
`POST`	`/api/chats/init`	初始化新的聊天会话
`POST`	`/api/chats`	发送消息并获得响应
`POST`	`/api/chats/stream`	发送带有流式响应的消息
`POST`	`/api/chats/async`	提交消息以进行异步处理
`GET`	`/api/chats/tasks/{task_id}`	轮询异步任务状态
`GET`	`/api/profile`	获取当前用户配置文件
`PUT`	`/api/users/{user_id}/profile`	更新用户配置文件
`GET`	`/api/users/{user_id}/statistics`	获取用户使用统计数据
`GET`	`/api/sessions/{session_id}/messages`	获取会话的聊天记录
`GET`	`/api/portfolio-performance/{session_id}`	获取投资组合绩效数据
`GET`	`/api/latest-portfolio-performance/{user_id}`	用户的最新投资组合表现
`GET`	`/api/user-recommendations/{user_id}`	获取用户的所有股票推荐
`GET`	`/agents/status`	检查连接的远程代理的状态
`GET`	`/health`	健康检查

3b。库存分析仪代理（端口10002）

作为一个独立的A2A兼容代理运行，使用Google ADK+MCP工具执行股票分析。

cd backend/stockanalyser_agent

# Create and activate virtual environment
python -m venv .venv
source .venv/bin/activate

# Install dependencies (uses pyproject.toml)
pip install -e .

# Configure environment
cp .env.example .env
# Edit .env with your GOOGLE_API_KEY and PERPLEXITY_API_KEY

# Run
python __main__.py

股票分析器代理环境变量

变量	必填	描述
`GOOGLE_API_KEY`	是	Google Gemini API密钥
`PERPLEXITY_API_KEY`	是	用于研究查询的困惑AI API密钥
`GOOGLE_GENAI_USE_VERTEXAI`	否	设置为 `TRUE` 使用Vertex AI而不是API键

代理开始 端口10002 并暴露A2A协议端点。它与技能相吻合 stock_analyse --“对股票行情进行详细分析。给出买入或卖出的建议。”

3c。股票报告分析仪代理（端口10003）

处理上传的PDF投资组合报表和财务文件。

cd backend/stockreport_analyser_agent

# Create and activate virtual environment
python -m venv .venv
source .venv/bin/activate

# Install dependencies (uses pyproject.toml)
pip install -e .

# Configure environment (uses same Google API key)
# Create a .env file with GOOGLE_API_KEY

# Run
python __main__.py

代理开始 端口10003 凭借技能 stock_report_analyse --分析股票报告、收益表、季度报告和其他财务文件

4.前端设置

前端是一个带有Firebase身份验证和Tailwind CSS的React+TypeScript应用程序。

cd frontend

# Install dependencies
npm install

# Configure environment
cp env.example .env
# Edit .env with your Firebase config and API URL

# Run development server
npm start

应用程序开始于 http://localhost:3000.

前端环境变量

变量	必填	描述
`REACT_APP_API_BASE_URL`	是	Host Agent API URL（默认值： `http://localhost:10001/api`)
`REACT_APP_FIREBASE_API_KEY`	是	Firebase Web API密钥
`REACT_APP_FIREBASE_AUTH_DOMAIN`	是	Firebase身份验证域
`REACT_APP_FIREBASE_PROJECT_ID`	是	Firebase项目ID
`REACT_APP_FIREBASE_STORAGE_BUCKET`	是	Firebase存储桶
`REACT_APP_FIREBASE_MESSAGING_SENDER_ID`	是	Firebase消息发送者ID
`REACT_APP_FIREBASE_APP_ID`	是	Firebase应用程序ID

Firebase设置

在以下位置创建Firebase项目 Firebase控制台
启用 电子邮件/密码 和谷歌身份验证下的登录提供程序
获取web应用程序配置并填写前端 .env
下载服务帐户JSON密钥并设置 FIREBASE_SERVICE_ACCOUNT_PATH 在Host Agent中 .env

5.启动一切（地方发展）

按以下顺序启动服务：

# Terminal 1 - Database
cd backend && docker-compose up -d

# Terminal 2 - Redis (if not using Docker)
redis-server

# Terminal 3 - Stock Analyser Agent
cd backend/stockanalyser_agent && source .venv/bin/activate && python __main__.py

# Terminal 4 - Stock Report Analyser Agent
cd backend/stockreport_analyser_agent && source .venv/bin/activate && python __main__.py

# Terminal 5 - Host Agent (start after remote agents are up)
cd backend/host_agent && source .venv/bin/activate && python __main__.py

# Terminal 6 - Frontend
cd frontend && npm start

验证

前端：http://localhost:3000
Host Agent API：http://localhost:10001/health
股票分析代理：http://localhost:10002/health
代理连接：http://localhost:10001/agents/status

代理通信流程

前端向Host Agent发送带有Firebase身份验证令牌的聊天消息(POST /api/chats)
Host Agent验证令牌，在PostgreSQL中管理会话
根据用户意图，Host Agent通过A2A协议委托给适当的子代理
子代理使用MCP工具（通过yfinance获取股票数据）和Google Gemini（LLM推理）生成分析
结果通过A2A流回Host Agent，Host Agent将结果持久化到数据库，并将响应返回给前端
对于投资组合绩效跟踪，Host Agent直接调用MCP工具来获取当前股票价格