AI Development
10 min read

Building Deterministic AI Agent Pipelines with LangChain, Zod, and pgvector

A deep dive into architecting resilient autonomous AI agent workflows that eliminate hallucinated tool arguments using runtime schema guardrails and semantic vector caching.

Deterministic AI agent pipeline with LangChain and Zod guardrails

1. The Non-Deterministic AI Challenge

While foundation models like Claude 3.5 Sonnet and GPT-4o excel at unstructured reasoning, enterprise production systems require deterministic predictability.

When an autonomous agent is authorized to write to databases, charge credit cards, or issue API requests, a hallucinated argument or missing parameter causes production downtime.

The solution is not more prompt engineering—it is structural software engineering: wrapping non-deterministic inference inside deterministic compiler guardrails.

---

2. Schema Guardrails with Pydantic & Zod

Every tool exposed to an LLM must have an unambiguous, strongly-typed parameter schema. In our engineering stack, we enforce dual-layer validation:

from pydantic import BaseModel, Field, EmailStr
from typing import Literal

class IssueInvoiceToolSchema(BaseModel): customer_id: str = Field(..., description="UUID of the customer in CRM") amount_cents: int = Field(..., gt=100, le=5000000, description="Amount in USD cents (min $1.00)") currency: Literal["USD", "EUR", "GBP"] = Field(default="USD") memo: str = Field(..., min_length=5, max_length=120)

If the LLM returns an invalid payload (e.g. negative amount or missing memo), the execution framework intercepts the payload before dispatching to the financial gateway.

---

3. Self-Correction & Reflection Loops

Rather than failing the user request when an agent outputs a schema error, modern agent runtimes execute an automated reflection loop:

try:
    validated_args = IssueInvoiceToolSchema.model_validate_json(raw_tool_call.arguments)
    return await execute_invoice_dispatch(validated_args)
except ValidationError as e:
    correction_prompt = f"Your previous tool call failed validation: {e.errors()}. Please self-correct and re-emit valid arguments."
    corrected_call = await agent.retry_with_feedback(correction_prompt)

This reflection architecture provides automated self-correction and deterministic schema enforcement across multi-turn reasoning workflows before any state mutations occur.

---

4. Hybrid Search with pgvector & BM25

Retrieval-Augmented Generation (RAG) often fails when relying solely on vector cosine similarity:
  • Pure vector search struggles with exact keywords, part numbers, and alphanumeric codes.
  • Pure keyword search fails on conceptual queries and semantic synonyms.
  • By combining PostgreSQL pgvector with full-text search using Reciprocal Rank Fusion (RRF), we achieve superior recall:

    WITH semantic_search AS (
      SELECT id, rank() OVER (ORDER BY embedding <=> query_vector) as rank_sem
      FROM knowledge_chunks
      ORDER BY embedding <=> query_vector
      LIMIT 25
    ),
    keyword_search AS (
      SELECT id, rank() OVER (ORDER BY ts_rank_cd(search_vector, query_tsquery) DESC) as rank_kw
      FROM knowledge_chunks
      WHERE search_vector @@ query_tsquery
      LIMIT 25
    )
    SELECT COALESCE(s.id, k.id) as chunk_id,
           COALESCE(1.0 / (60 + s.rank_sem), 0.0) +
           COALESCE(1.0 / (60 + k.rank_kw), 0.0) as rrf_score
    FROM semantic_search s
    FULL OUTER JOIN keyword_search k ON s.id = k.id
    ORDER BY rrf_score DESC
    LIMIT 8;
    

    ---

    5. Semantic Caching for Latency & Cost Reduction

    Enterprise AI applications experience frequent semantically identical queries. By implementing a Redis semantic cache with a 0.94 cosine similarity threshold, we bypass model inference entirely for repeated queries, eliminating redundant token consumption and achieving fast memory cache retrieval.