Files · Google Gemini Knowledge Agent for eBay SMB Seller Support

# Google Gemini Knowledge Agent for eBay SMB Seller Support
 
> A knowledge agent powered by Google Gemini that instantly answers buyer questions by pulling live data from your eBay seller account.
 
## Overview
 
This recipe builds a Gemini-powered agent that helps eBay sellers quickly respond to buyer inquiries about orders, listings, shipping, and policies. It uses:
 
- **Google Gemini** (Vertex AI) via `@google/genai` for natural language generation
- **Voyage AI** embeddings for semantic search across listing descriptions and FAQs
- **pgvector** on **Neon PostgreSQL** for vector similarity search
- **REAA packages**: session-continuity, context-window-planner, agent-memory, llm-cache, structured-repair-core
- **Langfuse** for observability and tracing
 
## Architecture
 
```
POST /api/chat → AgentOrchestrator.processMessage()
  ├── Cache check (llm-cache) — return cached response on hit
  ├── Load/create session (session-continuity)
  ├── Embed user query (VoyageAI)
  ├── Parallel RAG retrieval
  │   ├── searchListings (pgvector cosine similarity)
  │   └── searchFaqs (pgvector cosine similarity)
  ├── Memory retrieval (agent-memory)
  ├── Fetch eBay data (orders + listings)
  ├── Context packing (context-window-planner)
  ├── Gemini generation (Vertex AI)
  │   └── Structured output repair (structured-repair-core)
  ├── Memory extraction and storage (agent-memory)
  ├── Cache the response
  └── Trace to Langfuse
```
 
## Prerequisites
 
- Node.js >= 22
- pnpm
- A PostgreSQL database with pgvector extension (e.g., Neon)
- Google Cloud project with Vertex AI enabled
- Voyage AI API key
- eBay Developer API credentials
- Langfuse account (optional, for observability)
 
## Getting started
 
```bash
pnpm install
pnpm dev
```
 
## Environment variables
 
Copy `.env.example` to `.env` and fill in:
 
| Variable | Description |
|----------|-------------|
| `DATABASE_URL` | PostgreSQL connection string |
| `VOYAGE_API_KEY` | Voyage AI API key |
| `EBAY_API_KEY` | eBay Developer API key |
| `EBAY_OAUTH_TOKEN` | eBay OAuth access token |
| `GOOGLE_CLOUD_PROJECT` | GCP project ID |
| `GOOGLE_CLOUD_LOCATION` | GCP location (e.g., us-central1) |
| `GOOGLE_GENAI_USE_ENTERPRISE` | Must be `true` for Vertex AI |
| `GOOGLE_APPLICATION_CREDENTIALS` | Path to GCP service account JSON |
| `GEMINI_MODEL` | Gemini model ID (default: gemini-2.5-flash) |
| `LANGFUSE_PUBLIC_KEY` | Langfuse public key |
| `LANGFUSE_SECRET_KEY` | Langfuse secret key |
| `LANGFUSE_BASE_URL` | Langfuse API base URL |
| `SESSION_TOKEN_BUDGET` | Max tokens per session (default: 4096) |
 
## API Reference
 
### POST /api/chat
 
Send a message to the knowledge agent.
 
**Request body:**
```json
{
  "sessionId": "optional-session-id",
  "message": "Where is my order?"
}
```
 
**Response:**
```json
{
  "sessionId": "session-uuid",
  "response": "Your order #123 was shipped on Monday...",
  "sources": [
    { "type": "order", "content": "Order #123: SHIPPED" }
  ]
}
```
 
### GET /api/chat?sessionId=<id>
 
Retrieve message history for a session.
 
### DELETE /api/chat?sessionId=<id>
 
End a session and run memory maintenance.
 
## Project layout
 
```
app/api/chat/route.ts    — API route handlers (POST/GET/DELETE)
src/lib/                 — Database + external API clients
src/services/            — Business logic services
src/types/               — TypeScript interfaces and Zod schemas
tests/                   — Vitest test suite
```
 
## Tests
 
```bash
pnpm test
```
 
Runs vitest with coverage. All external calls are mocked.
 
## License
 
MIT — see [LICENSE](./LICENSE).