Agentic AI Research Agent

Problem

An agent that answers in one shot is impossible to debug and hard to trust. I wanted the reasoning visible while it happens, every run permanently replayable afterwards, and the whole system runnable with no API key and no database so it could be demonstrated anywhere.

What I built

• A reason-and-act loop where each turn returns exactly one JSON object — a tool call or a final answer — which is executed, observed and fed back until the agent answers or hits its step limit.
• Three tools behind one interface: keyword search over an editable knowledge base, a calculator, and a clock.
• A chat frontend that streams thoughts, tool calls and observations over server-sent events as they happen.
• An admin console with run history and filters, a full step-by-step trace per run, usage statistics, and a rich-text knowledge-base editor.
• Tool on/off switches that the agent loop reads before every run.

Technical decisions & trade-offs

• The calculator is a hand-written recursive-descent parser rather than eval, because model output is untrusted input and arithmetic is not worth an injection surface.
• Tool toggles are enforced twice — disabled tools are left out of the prompt and rejected at execution time if the model asks anyway.
• The model sits behind a one-method interface with a deterministic mock beside the real provider, so the agent loop is testable offline with no key and no network.
• Storage sits behind a driver interface: hosted Postgres in one mode, a single JSON file in the other. Everything above the driver is storage-agnostic, so a third backend is one new class.
• The whole trace is stored as JSON in one row. Reads are a single query and the step shape can evolve without a migration; the cost is not being able to query inside steps in SQL, so statistics aggregate in application code.
• Server-sent events rather than WebSockets: the traffic is one-directional, it is plain HTTP with nothing to tune in a proxy, and the browser reconnects on its own.
• Row-level security is on with no policies at all — the server-side key bypasses it by design, so a leaked public key can read and write nothing.

Challenges solved

• Models drift off format, so the parser tolerates code fences and stray prose, and a failed parse records an error step and re-prompts within the same step budget instead of failing the run.
• The knowledge base keeps rich HTML for authors and a derived plain-text copy for retrieval, so formatting survives without polluting what the agent searches.
• Editor images upload to object storage and come back as URLs rather than being inlined as base64, which would have bloated every row carrying a picture.

Outcome

A complete agent stack that runs fully offline in mock mode with no key and no database, and against hosted Postgres and a real model when configured. Every run is replayable step by step.