Agents

This document covers the spec-driven agent surface added by the agentic-RAG expansion. The legacy CrewAI research crew (under alphaswarm/agents/crew.py) coexists with the new runtime; both register routes under /agents/* in the FastAPI gateway.

Concepts

• AgentSpec — declarative blueprint (Pydantic). Holds role, system_prompt, tools, model, memory, RAG clauses, guardrails, output_schema, cost / call caps, and annotations. Defined in alphaswarm/agents/spec.py.
• AgentRuntime — executor that turns a spec into a real run with full telemetry. Defined in alphaswarm/agents/runtime.py.
• Registry — process-wide name → AgentSpec map. Discovered built-ins are registered at import time; YAML files under configs/agents/ are auto-loaded on first lookup. Declared in alphaswarm/agents/registry.py.
• Reproducibility — every spec is hash-locked and snapshotted into agent_spec_versions on first use. Every run records a spec_version_id so it can be deterministically replayed.

The four teams

Team	Specs	Page
Research	research.news_miner, research.equity, research.universe	alphaswarm_docs/research-agents.md
Selection	selection.stock_selector	alphaswarm_docs/selection-agents.md
Trader	trader.signal_emitter	alphaswarm_docs/trader-agents.md
Analysis	analysis.step, analysis.run, analysis.portfolio (+ reflector)	alphaswarm_docs/analysis-agents.md

Inspiration-rehydration personas (Phase 2026-04-29)

Nine new spec-driven agents added by the rehydration. Each ships as a YAML in configs/agents/ and uses one or more of the new analytics tools in alphaswarm/agents/tools/analytics_tools.py.

Spec name	Role	Tools
research.regime_analyst	ADX trend/range gate	regime_classifier_tool, historical_volatility
research.composite_voter	TradFi-style indicator consensus	multi_indicator_vote_tool
research.basis_momentum_analyst	Commodity basis screening	factor_screen_tool, realised_vol_tool
research.cointegration_analyst	Pair stat-arb	cointegration_tool, historical_volatility
research.intraday_momentum_analyst	Gao 2018 intraday plays	realised_vol_tool, regime_classifier_tool
selection.cross_asset_skew_screener	Cross-asset skew factor	factor_screen_tool
analysis.queue_position_analyst	HFT metric explainer	hft_metrics_tool
analysis.cointegration_basket_finder	Universe-wide pair search	cointegration_tool
research.options_greeks_explainer	Bachelier + inverse Greeks	option_greeks_tool, option_spread_tool

Composite pipeline: see alphaswarm/agents/graph/builder.py::build_quant_research_pipeline_graph which chains composite_voter → regime_analyst → cointegration_analyst → risk_simulator → emit_signal_event/reject_decision_log with the existing risk-simulator approval gate.

Run lifecycle

Persistence

Table	Purpose
agent_specs	Logical agent (latest version pointer)
agent_spec_versions	Immutable hash-locked spec snapshot
agent_runs_v2	One row per run
agent_run_steps	One row per step (LLM / tool / RAG / memory / guardrail)
agent_run_artifacts	Sidecar artifacts referenced by a run
agent_evaluations + agent_eval_metrics	Eval harness results
agent_annotations	User/agent annotations for optimisation

REST surface

GET  /agents/specs                              — list registered specs
GET  /agents/specs/{name}                       — spec detail (full payload)
GET  /agents/specs/{name}/versions              — version history
POST /agents/runs/v2/sync                       — synchronous run
GET  /agents/runs/v2                            — list runs (filter by spec/status)
GET  /agents/runs/v2/{id}                       — full trace incl. steps
POST /agents/runs/v2/{id}/replay                — replay against snapshotted spec
GET  /agents/evaluations                        — list eval reports

Guardrails

AgentSpec.guardrails (parsed by AgentRuntime._guardrail_check):

• cost_budget_usd — hard ceiling per run (raises GuardrailViolation).
• rate_limit_per_minute — TODO: enforced at the call site.
• max_calls — caps the number of LLM round-trips per run.
• forbidden_terms — strings that must not appear in the output.
• require_rationale — output must include a rationale-style key.
• min_confidence — output's confidence field must clear this floor.

Don'ts

• Don't bypass AgentRuntime.run for spec-driven agents — telemetry, guardrails, cost caps, and agent_runs_v2 rely on it.
• Don't mutate agent_spec_versions rows — they are immutable.
• Don't write a new spec without registering it (decorator or YAML); the LangGraph builders look up by name and will skip unknown specs.