Market Digest Agent (Paper-Trading, News-Driven)

A cautious, rules-driven market agent that:

1. Scans macro headlines (Mediastack),
2. Maps news → candidate tickers (Finnhub),
3. Applies conservative trade rules,
4. Optionally places paper orders (Alpaca).

The agent prefers not to trade unless conviction is high. Skipping is always allowed.

---

✨ What this agent does

• First inspects the paper trading account and market clock (Alpaca).
• Scans macro news using a prioritized keyword list (e.g., “FOMC”, “CPI”, “beats estimates”, “merger”, “FDA approval”, etc.).
• Builds a candidate ticker list from headlines and proxy ETFs (e.g., XLF, TLT, NVDA, XLE).
• For each ticker:
  • Pulls quotes, company news, and earnings context (Finnhub).
  • Optionally checks intraday bars (Alpaca Market Data v2).
• Applies risk & sizing guardrails and, only if warranted, submits one paper order (Alpaca).

---

🧱 Architecture (high level)

• This agent (you’re reading its README) is a Python module that uses:
  • google-adk (LlmAgent) for reasoning & tool orchestration.
  • MCPToolset to call your MCP server over HTTP.
• MCP server (separate service) provides tools:
  • Mediastack: news_headlines, news_get
  • Finnhub: symbol_search, quote, company_news, earnings_*
  • Alpaca (paper): paper_account, paper_clock, paper_positions, paper_open_orders, paper_submit_order, paper_cancel_order, paper_quote, paper_bars

This README is for the agent, not the MCP server. Ensure your MCP server is running and reachable at AGENT_MCP_URL.

---

✅ Requirements

• Python: 3.10+
• Packages (add to your requirements.txt):
  • google-adk
  • litellm
  • python-dotenv

Example requirements.txt:

google-adk
litellm
python-dotenv

---

🔧 Configuration

Create a .env in the agent’s project root:

# Model (via LiteLLM routing)
MARKET_AGENT_MODEL=openai/gpt-4o
OPENAI_API_KEY=sk-...

# MCP endpoint (HTTP Streamable)
# If you’re tunneling to a remote service: ssh -N -L 8181:127.0.0.1:8000 ubuntu@<EC2_IP>
# Then set:
AGENT_MCP_URL=http://localhost:8181/mcp

# Optional: if your environment needs to inject extra import roots for the agent
MARKET_MCP_PYTHONPATH=/opt/market-mcp

Heads-up: If you previously used AGENT_MCPP_URL (with two “P”s), correct it to AGENT_MCP_URL. The agent code reads AGENT_MCP_URL.

---

🚀 Quickstart

1. Install deps

   python -m venv .venv . .venv/bin/activate pip install -r requirements.txt

2. Confirm MCP server is reachable

   Using your local tunnel or a direct local service:

   curl -sS -i -X POST http://localhost:8181/mcp -H 'content-type: application/json' -d '{}'

   You should receive a 200/202 response (GET to /mcp often returns 400; that’s normal for the streaming endpoint).

3. Run the agent from Python

   Example runner (save as run_agent.py)

   from agent import root_agent # the file containing your agent code snippet prompt = "market digest" result = root_agent.run(prompt) if hasattr(root_agent, "run") else root_agent.chat(prompt) if hasattr(root_agent, "chat") else root_agent(prompt) print(result)

   Then:

   python run_agent.py

Different google-adk versions expose different call methods (run, chat, or __call__). The example above tries them in a safe order.

---

🧠 Behavior & Workflow (summary)

• First action (always):
  • paper_account() → check equity, buying_power, flags.
  • paper_clock() → only consider trades if is_open (or within ~10 min of open).
• Macro scan (strictly sequential; never batch):
  • For each prioritized term, call news_headlines(keywords=TERM, limit=5).
  • Deduplicate by URL/title; cap to ~20 headlines total.
  • If headlines look important but vague, fetch details via news_get for that term.
  • Fallback: news_headlines("markets", 5) if signal is thin.
• Map news → tickers:
  • Extract company/brand names; resolve ambiguity via symbol_search.
  • Add thoughtful proxy tickers (e.g., rates → XLF/KRE/ITB/TLT; chips/AI → NVDA/AMD/AVGO/TSM/ASML; oil/tensions → XLE/XOM/CVX).
  • Keep ≤ 12 candidates; prioritize recent/high-signal.
• Per-ticker:
  • quote(symbol); company_news(symbol, 2d); earnings via earnings_expectations or earnings_results.
  • If needed, intraday context with paper_bars(symbol, "1Min", 60).
• Trade decision (paper only):
  • Require both: (A) strong catalyst and (B) confirming price action or attractive R/R.
  • If uncertain → do not trade.
• Risk & sizing:
  • Max 2 new positions per day.
  • Skip if open orders or oversized exposure exist (paper_open_orders, paper_positions).
  • Default size: min(5% of buying_power, $2,000), using notional when possible.
  • Prefer BRACKET for longs: take_profit ≈ +4%, stop_loss ≈ -2%.
• Order placement (if any):
  • One order only, type="market" for liquid names, time_in_force="DAY".
  • client_order_id="md-<SYMBOL>-<YYYYMMDD-HHMM>".
  • Confirm via paper_open_orders(limit=20).
• Output:
  • Executive summary, Trade decisions, Ticker drill-down, US macro pulse.
  • Concise, factual; inline sources/time when available.
• Constraints:
  • Never batch across tickers/endpoints; max ~25 tool calls.
  • Note errors briefly and continue.
  • If closed or low conviction → no trades.

---

🧩 Tool Filter (for this agent)

The agent will only use these MCP tools:

• Finnhub: symbol_search, quote, company_news, earnings_expectations, earnings_calendar, earnings_results
• Mediastack: news_headlines, news_get
• Alpaca (paper): paper_account, paper_clock, paper_positions, paper_open_orders, paper_submit_order, paper_cancel_order, paper_quote, paper_bars
• Misc: ping

Ensure your MCP server actually exposes these (use the MCP Inspector to verify ListTools).

---

🔐 Safety & Paper-Only Guardrails

• The agent is paper-only by design.
• It will not trade if the market is closed or conviction is low.
• Caps new positions and sizes; prefers bracket risk controls.
• You may still want to add account-level safeguards (e.g., permissions or MCP-side validation).

---

🧪 Example prompts

• “market digest”
• “market digest — focus on chips and CPI”
• “market digest; skip trades today, just research” (you can customize the instruction block if you want stricter behavior)

---