README.md

metadata

title: Researcher Agent
emoji: 🔬
colorFrom: blue
colorTo: purple
sdk: docker
pinned: false
license: mit

Research Service

Financial research service implementing Google's A2A (Agent-to-Agent) protocol. Uses TRUE MCP protocol (subprocess + JSON-RPC) to fetch data from 6 MCP servers and returns aggregated research data for SWOT analysis.

Architecture

┌─────────────────────────────────────────────────────────────────┐
│  Research Service                                               │
│  ┌───────────────────────────────────────────────────────────┐  │
│  │  A2A Server (FastAPI + JSON-RPC 2.0)                      │  │
│  │  ┌─────────────────────────────────────────────────────┐  │  │
│  │  │  MCP Client (TRUE MCP: subprocess + JSON-RPC)       │  │  │
│  │  │  ┌──────────┐ ┌──────────┐ ┌──────────┐            │  │  │
│  │  │  │Financials│ │Volatility│ │  Macro   │            │  │  │
│  │  │  └──────────┘ └──────────┘ └──────────┘            │  │  │
│  │  │  ┌──────────┐ ┌──────────┐ ┌──────────┐            │  │  │
│  │  │  │Valuation │ │   News   │ │Sentiment │            │  │  │
│  │  │  └──────────┘ └──────────┘ └──────────┘            │  │  │
│  │  └─────────────────────────────────────────────────────┘  │  │
│  └───────────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────────┘

TRUE MCP Protocol

This service uses TRUE MCP protocol with proper handshake:

1. Send initialize request (id=1)
2. Receive initialization response
3. Send notifications/initialized notification
4. Send tools/call request (id=2)
5. Parse JSON-RPC response

Each MCP server is called via subprocess + stdio, following the official MCP specification.

A2A Protocol

This agent implements the Google A2A Protocol using JSON-RPC 2.0 over HTTP.

Endpoints

Endpoint	Method	Description
/	POST	JSON-RPC 2.0 endpoint
/.well-known/agent.json	GET	Agent card
/health	GET	Health check

JSON-RPC Methods

message/send

Start a new research task.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "message/send",
  "params": {
    "message": {
      "parts": [{"type": "text", "text": "Research Tesla"}]
    }
  }
}

tasks/get

Get task status and results. Includes partial_metrics during WORKING status for real-time streaming.

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tasks/get",
  "params": {"taskId": "abc-123-def"}
}

tasks/cancel

Cancel a running task.

Data Sources

MCP Server	Data Source	Metrics
Financials	SEC EDGAR	Revenue, margins, debt, EPS
Volatility	Yahoo Finance, FRED	Beta, VIX, historical volatility
Macro	FRED	GDP growth, interest rates, inflation, unemployment
Valuation	Yahoo Finance	P/E, P/B, P/S, EV/EBITDA, PEG
News	Tavily	Recent news articles
Sentiment	Finnhub, Reddit	Composite sentiment score

Environment Variables

FRED_API_KEY=xxx        # For macro indicators
FINNHUB_API_KEY=xxx     # For sentiment analysis
TAVILY_API_KEY=xxx      # For news search
METRIC_DELAY_MS=300     # Delay between metric emissions (ms)

Local Development

# Install dependencies
pip install -r requirements.txt

# Run the server
python app.py

Server runs on http://localhost:7860

Usage from Main SWOT Agent

The main SWOT Analysis Agent connects to this server via A2A protocol:

# In main agent (Research Gateway)
A2A_RESEARCHER_URL = "https://vn6295337-researcher-agent.hf.space"

# Send research request
response = requests.post(A2A_RESEARCHER_URL, json={
    "jsonrpc": "2.0",
    "id": 1,
    "method": "message/send",
    "params": {"message": {"parts": [{"type": "text", "text": "Research TSLA Tesla"}]}}
})

License

MIT