A browser sandbox for retrieval-backed agents

vector-db-agent-sandbox is a Next.js app we built to try retrieval-backed agents against a vector database from a browser. It pairs a small agent UI with a client for a separate vector database service that stores text as embeddings and answers questions from the closest matches. In earlier commits the query agent was called the "Chromia VectorDB Query Agent"; it was later renamed to "Crypto Research Agent".

Two agents

The sandbox exposes two agents, defined in src/lib/types.ts:

• Crypto Research Agent (vector-query) takes a question and sends it to the service's text_conversation endpoint with top_k: 3, so the answer is grounded in the three closest stored passages.
• VectorDB Data Ingestion Agent (vector-data-ingestion) takes a block of text and sends it to the text_embedding endpoint, which embeds and stores it. The UI shows a toast once the write succeeds.

The client in src/lib/api.ts also has a searchText helper for the text_search endpoint, which returns raw matches without generating an answer.

Example data

To make the sandbox usable on first load, the repo ships example prompts and seed passages. The ingestion examples are short historical overviews of Bitcoin, Ethereum, Solana and Chromia. The query examples ask things like "How does Chromia's blockchain work?" or "Compare Solana and Cardano". The idea is that you ingest a few passages, then ask questions and see how retrieval changes the answer.

Agent patterns

src/app/actions.tsx is a server actions module built on the Vercel AI SDK (generateText, generateObject) with gpt-4o-mini as the default model. It implements several agent patterns in one place: multi-step tool use (with mathjs as a calculator tool), sequential processing, routing, parallel processing, orchestrator-worker and evaluator-optimizer. Each returns the final text along with the intermediate steps and token usage, which the UI renders in separate tabs. In the current wiring the two visible agents call the vector service directly, and the pattern implementations sit alongside them for experiments.

UI and limits

The interface is built with shadcn/ui components, has a separate mobile output panel, and shows a token counter and completion indicator. Server actions are rate limited per client with Upstash's sliding-window limiter, set to 10 requests per day, so a public demo cannot run up model costs.

Recent maintenance

The app has had two maintenance updates since it was built: a dependency update to address React Server Components CVEs, and a typing fix for motion easings so the build type-checks.