Agent Operations

Admin reference. Not indexed.

How Agents Work

Three specialised agents call google/gemini-2.5-flash via the Lovable AI Gateway:

• Intake — parses the user brief into structured goals + scope.
• Data Scout — matches scope to registered data_sources, fetches and grounds indicators.
• Synthesis — computes scores, drafts recommendations, emits KG triples.

Agent Run Lifecycle

1. created — row inserted, quota consumed.
2. planning → collecting → analysing → synthesising.
3. completed — result written, neighbourhood scores updated.
4. failed — error captured in agent_runs.error; quota refunded.

Each transition writes a row to agent_steps for live streaming.

Cost Tracking

Every run accumulates llm_tokens_used and cost_eur on agent_runs. Targets:

• Quick Scan — ≤ €0.05/run
• Full Assessment — ≤ €0.40/run
• Deep Dive — ≤ €1.80/run

Troubleshooting

• Run stuck in planning — Lovable AI Gateway 429; auto-retries 3×, then fails.
• Score = NULL on completed run — Synthesis returned insufficient evidence; check agent_steps.detail.
• Quota errors — call consume_run_quota manually with service role to inspect.

Data Source Management

Admin → Data Sources to register a new portal. Set coverage_cities, indicators_provided, and a sync_schedule cron. Test with the "Dry run" button before activating.