ADR-0004: Agent-Framework

Kontext

ADR-0003 legt eine Multi-Agent-DAG fest mit typisierten Inputs/Outputs, Tool-Use, Provider-Diversität und einer Coordinator-Orchestrierung. Wir brauchen ein Framework, das diese Anforderungen abdeckt, ohne große Mengen an unbenötigter Komplexität mitzubringen.

Entscheidungstreiber

• Multi-Provider-Support (siehe ADR-0005): Anthropic, OpenAI, Google, Groq, Mistral, Ollama als austauschbare Modelle.
• Type-Safety: Pydantic-Modelle für jeden Agent-Output, deterministische Schema-Validation.
• Konsistente Tool-Use-Semantik über alle Provider hinweg.
• MCP-Integration (siehe ADR-0006) — Standard-Schnittstelle für externe Tools.
• Schlankheit: möglichst wenig Framework-Magie, kein riesiger Ökosystem-Lock-in.
• Observability: Tool-Calls, Token-Counts, Latenzen, Reasoning auslesbar (für Decision-Log).
• Reife & Pflege: aktive Maintainer, nicht-experimentell.

Betrachtete Optionen

Entscheidung

Wir wählen Option A: Pydantic AI als Agent-Framework.

Konkrete Nutzung

• Jeder Sub-Agent aus ADR-0003 ist eine pydantic_ai.Agent-Instanz mit eigenem result_type (Pydantic-Modell) und eigener Tool-Liste.
• Der Coordinator ist kein Pydantic-AI-Agent, sondern normaler Python-Code, der die Sub-Agents in der DAG-Reihenfolge aufruft. Begründung: Coordinator hat kein LLM-Reasoning — er ist deterministische Orchestrierung. So bleibt die Workflow-Logik transparent und debuggbar.
• Async-Execution: Sub-Agents werden async aufgerufen; asyncio.gather für parallele Schritte (Research+Analyst, Critic+Risk-Assessment).
• Per-Run-Context wird via deps_type / RunContext an Agents übergeben — enthält DB-Handles, Run-ID, Watchlist-Konfiguration.
• Tools: typisierte Python-Funktionen via @agent.tool; MCP-Server via Pydantic-AI MCP-Client-Adapter (siehe ADR-0006).
• Outputs persistieren wir vor jedem Schritt — Decision-Log fängt jeden Agent-Output (siehe ADR-0012).

Beispiel-Skizze (Pseudo-Code)

research_agent = Agent(
    model=research_model,           # konfigurierbar pro Agent
    deps_type=RunDeps,
    result_type=ResearchReport,
    system_prompt=RESEARCH_PROMPT,
    tools=[tavily_search, tavily_extract, sec_edgar_filing],
)

analyst_agent = Agent(
    model=analyst_model,
    deps_type=RunDeps,
    result_type=QuantSnapshot,
    tools=[get_eod_prices, compute_indicators, get_fundamentals],
)

# Coordinator (deterministische Python-Logik, kein LLM)
async def coordinate(watchlist: Watchlist, trigger: TriggerType) -> RunSummary:
    shortlist = await screener_agent.run(...)
    research, quant = await asyncio.gather(
        research_agent.run(shortlist.tickers, deps=deps),
        analyst_agent.run(shortlist.tickers, deps=deps),
    )
    strategy = await strategy_agent.run(research=research.data, quant=quant.data, deps=deps)
    critic, risk = await asyncio.gather(
        critic_agent.run(strategy.data, deps=deps),
        risk_agent.run(strategy.data, deps=deps),
    )
    return persist_run_summary(...)

Konsequenzen

Positiv

• Schlanker Stack, wenig Magie. Workflow ist normaler Python-Code, voll debugbar.
• Multi-Provider und Type-Safety in einem Paket.
• Direkte Anbindung an Pydantic-Schemas — passt zur Verifikations-Strategie (ADR-0003 Schicht 1).
• MCP-Integration vereinfacht Tool-Wiederverwendung (ADR-0006).

Negativ / Trade-offs

• Kein eingebauter Graph-Compiler — wenn die DAG sehr viel komplexer wird (Cycles, Conditional Edges in großer Zahl), wird der Coordinator-Code unübersichtlich. Mitigation: Bei dieser Komplexität separates Orchestrierungs-Modul oder Migration zu LangGraph erwägen.
• Abhängigkeit von einem relativ jungen Framework. Mitigation: API ist klein und vollständig replazierbar, sollte Pydantic AI stagnieren.
• Provider-Konfiguration und Modell-IDs sind Pydantic-AI-spezifische Strings — leichter Lock-in. Mitigation: Eigene AgentModelSpec-Schicht (siehe ADR-0005), die Provider-Konfiguration entkoppelt.