The Kapruka Agent was designed as a complete AI system rather than a single chatbot prompt. It separates product knowledge from deterministic business data, decomposes compound requests into specialist routes, carries structured context through explicit graph state, and records every important step for inspection through Langfuse.
Case Study
Project Overview
Built an AI concierge platform for gift discovery and delivery planning across the Kapruka domain. The system crawls and indexes product data, routes compound requests across specialist agents, retrieves product knowledge through RAG, answers deterministic logistics questions through relational CRM tools, and preserves user context through short-term and distilled long-term memory.
Challenge Framing
Gift discovery requests often combine personal preferences, product questions, delivery locations, time-slot constraints, customer details, and follow-up references. A single retrieval prompt cannot reliably manage all of these concerns while preserving memory, grounding, and operational accuracy.
Solution Strategy
I designed a LangGraph supervisor architecture that recalls context, produces structured route decisions, fans requests out to specialist agents, retrieves products from Qdrant, queries CRM and logistics data from Supabase, merges agent outputs, and writes useful conversation details back into memory.
Project Highlights
Gallery
Selected screens show the visible product experience and the operational surfaces behind each project. Projects without captured assets keep a structured placeholder until real screenshots are available.
End-to-end architecture connecting the client, FastAPI, LangGraph supervisor, specialist agents, memory layers, product retrieval, CRM data, ingestion workflows, and observability.
Relational and vector-enabled schema covering user profiles, conversation memory, semantic facts, delivery zones, slots, couriers, product rules, and fulfilment history.
The runtime overview surfaces traced graph nodes, total model costs, token usage, model activity, and execution trends.
Cost analytics break down model spend, trace volume, observations, environments, users, and use cases.
Node-level traces expose recall, supervisor routing, product retrieval, profile actions, response merging, and memory writes for each request.
Router, recall, synthesis, catalogue, direct-agent, and memory-distillation prompts are versioned outside the application with local runtime fallbacks.
The concierge begins a birthday-gift conversation with a grounded product recommendation retrieved from the Kapruka catalogue.
The agent retains the birthday context and refines recommendations after learning that the recipient prefers chocolates and cakes.
A follow-up request retrieves more cake choices while preserving the ongoing product-selection context.
The concierge recalls the selected products and confirms their latest catalogue prices before continuing toward order planning.
Customer and address details are routed to the CRM and logistics path to check district coverage and return available time slots.
The agent interprets a natural-language time preference, preserves the selected products, and prepares the delivery plan for the final evening slot.
Tech Stack
Context engineering, memory distillation, multi-agent routing, LangGraph orchestration, retrieval engineering, state management, semantic caching, CRM tools, logistics reasoning, and AI observability.
Key Features
A structured router classifies requests, extracts parameters, supports up to three routes, repairs common logistics misroutes, and fans compound requests out to specialist agents.
Recent turns, distilled user facts, conversation episodes, and reusable procedures are stored separately so each memory type can follow its own retrieval and retention policy.
The product path combines Qdrant-based RAG, a semantic CAG cache, parent-child retrieval, and CRAG expansion when first-pass evidence is weak.
Delivery coverage, courier capacity, slot availability, product constraints, and fulfilment history are resolved through relational data instead of generated from unverified text.
Langfuse captures graph traces, model calls, prompt versions, token usage, latency, cost, routing decisions, and memory operations.
Architecture
Each layer stays explicit so reviewers can quickly understand where interface, orchestration, persistence, and service responsibilities live.
A web-based concierge interface communicates with a FastAPI service that exposes chat, streaming, health, graph, and memory endpoints.
LangGraph manages recall, supervisor routing, specialist execution, response merging, state transitions, and memory write-back.
Qdrant stores the Kapruka product knowledge base and semantic answer cache, with parent-child retrieval and confidence-based corrective expansion.
Supabase PostgreSQL stores user profiles, CRM records, logistics tables, conversation turns, semantic facts, episodes, and procedures.
A Playwright crawler converts Kapruka product pages into structured records, while Tavily provides live external information when required.
Langfuse monitors graph execution, model behaviour, costs, latency, prompts, user journeys, and errors.
System Flow
The pipeline section keeps the most important engineering steps visible without collapsing them into generic bullet lists.
Render Kapruka product pages, extract structured metadata, and save catalogue records as JSONL and markdown documents.
Split product records through parent-child chunking, generate embeddings, and persist retrieval units into Qdrant.
Load recent turns and long-term semantic facts before the supervisor produces validated route decisions for each request.
Run product retrieval, CRM and logistics actions, direct concierge generation, or live web search based on the selected routes.
Combine parallel specialist responses, return one coherent answer, store the turn, and distil durable facts when the memory policy is triggered.
Record graph nodes, prompts, tokens, costs, latency, tool actions, and memory behaviour for debugging and optimisation.
Timeline
This timeline keeps the implementation story concise: what was framed first, what was hardened next, and what ultimately made the project production-ready.
Built the Kapruka crawler, structured product documents, evaluated chunking approaches, and created the Qdrant product collection.
Introduced session-scoped short-term turns, semantic user facts, token-budgeted recall, memory distillation, and additional episodic and procedural stores.
Implemented the supervisor, specialist routes, reducer-backed branch outputs, compound-request fan-out, and merged response synthesis.
Modelled users, delivery zones, slots, couriers, product rules, and delivery history as structured relational data and exposed them through agent tools.
Added semantic caching, corrective retrieval, parent-child context expansion, FAQ cache warming, and evidence-aware answer generation.
Connected Langfuse tracing and prompt management, then built the gift concierge UI for end-to-end product and delivery demonstrations.
Challenges
Each challenge is tied to a concrete design choice and a specific outcome.
Solution
Designed a structured router that can emit multiple validated routes and fan them out to separate specialist nodes.
Outcome
The system can answer product and logistics concerns together without forcing one agent to handle unrelated data sources.
Solution
Separated recent-turn memory from distilled semantic facts and applied a strict token budget with short-term and long-term allocation.
Outcome
Follow-up requests retain useful personal context while keeping recall controlled and inspectable.
Solution
Added a Qdrant-backed semantic CAG cache with similarity matching, TTL expiry, and duplicate cleanup.
Outcome
Repeated and paraphrased questions can bypass full retrieval and generation.
Solution
Introduced a heuristic confidence score and expanded retrieval from four to eight results when evidence quality fell below the threshold.
Outcome
The product agent can recover from weak first-pass retrieval without requiring a separate reranking service.
Solution
Stored coverage, slots, courier availability, delivery rules, and historical signals in relational tables queried through a dedicated CRM tool.
Outcome
Operational responses are grounded in deterministic business data rather than model assumptions.
Solution
Instrumented router calls, graph nodes, retrieval operations, memory generation, latency, token usage, costs, and prompts through Langfuse.
Outcome
Agent behaviour can be inspected at node level, making failures and performance bottlenecks easier to identify.
Results
The emphasis here is signal, not decoration: key numbers, verifiable outcomes, and the context needed to interpret them responsibly.
96
Product Records
Structured JSONL and markdown product documents prepared for vector ingestion.
11K+
Logistics Records
Delivery zones, slots, couriers, product rules, and historical delivery records.
4
Agent Routes
CRM, product RAG, web search, and direct concierge execution paths.
4
Memory Layers
Short-term, semantic fact, episodic, and procedural memory stores.
Key Results
Business Impact
Context is assembled from recent turns, semantic facts, product evidence, CRM records, route state, and specialist outputs instead of being stored as one unstructured prompt string.
Parent-child retrieval, semantic caching, corrective expansion, and source-specific tools improve grounding while keeping product and operational knowledge separate.
Delivery feasibility, capacity, product restrictions, and customer information are resolved through relational queries rather than generated assumptions.
Node-level traces, prompt versions, costs, tokens, latency, and routing decisions make the agent easier to debug and optimise.
The architecture leaves clear room for transactional ordering, payment integration, richer evaluation datasets, automated reranking, and additional specialist agents.
Continue
