Defensive Agent Architecture

Schema Injection: SearchParams.model_json_schema() is passed into the LLM's tool/function calling definition.

Deterministic Invocation: The LLM outputs a JSON payload matching SearchParams.

Execution & Validation: fetch_live_content validates the arguments, dispatches the HTTP call within a strict 4-second window, and deserializes the results into ContentChunk objects.

Context Injection: The serialized chunks and their respective ids are injected back into the LLM context for synthesis and citation grounding.

This pattern addresses a critical failure mode in AI engineering: the fragility of connecting probabilistic language models to deterministic production systems.

The Problems It Solves
Hallucinated Tool Inputs: LLMs frequently drift or generate malformed parameters (e.g., requesting -10 or 1,000,000 items, or passing unparseable types). Defining the input via SearchParams forces the model to conform to strict boundaries (ge=1, le=10), catching invalid tool requests before they hit your infrastructure.

Agent Hanging and Runaway Costs: Without rigid timeouts, a lagging external API or vector index will cause the agent to hang indefinitely. This blocks server threads, degrades user experience, and inflates cloud costs. The explicit 4-second timeout enforces a deterministic upper bound on wait times.

Cascading Application Crashes: Unhandled HTTP errors (429 rate limits, 500 server crashes) crash naive agent runtimes. Swallowing these failures into a structured fallback (return []) allows the agent to handle missing data gracefully rather than throwing an uncaught exception.