How get-convex/agent works
Project Type and Purpose
• This is a TypeScript-based library package (“@convex-dev/agent”) for building AI-driven agents on top of the Convex platform.
• It provides client-side components (in both raw client and React flavors), serverless Convex functions (the “agent workflows”), and examples/playground frontends demonstrating how to wire everything together.
High-Level Architectural Overview
Break the system into these primary layers:
A. Frontend UIs
• “example/ui” (React + Vite/Tailwind)
• “playground/src” (full demo app with UI components, context editors, etc.)
B. Client-Side Library
• src/client: low-level API wrappers (thread/message management, streaming, file operations)
• src/react: React hooks & utilities for optimistic updates, streaming deltas, UI message conversion
C. Convex Backend
• example/convex: serverless functions (agents, threads, messages, files, RAG, rate-limiting, usage tracking, workflows)
• src/component: the core “component” code (schema, business logic, streams, threads, tools)
D. Persistence & Services
• Convex database (threads, messages, vectors for RAG, file metadata)
• File storage (for uploaded/generated files)
• External LLM providers (OpenAI, Anthropic, etc.)
• Optional external services (vector stores, other APIs when used as Tools)
Component Relationships & Data Flow
1. User interacts with Frontend UI →
2. UI calls React hooks (src/react) or raw client APIs (src/client) →
3. Client library issues streaming RPCs / function calls to Convex Backend →
4. Convex server functions execute:
a. Manage convo context (threads/messages) in Convex DB
b. Optionally perform RAG/vector search
c. Call out to LLM provider or user-supplied Tools
d. Persist results, update threads/messages, handle rate-limiting & usage tracking
e. Stream deltified responses back over websockets
5. Client receives and applies deltas → UI re-renders incremental agent output
6. File operations go through file storage and update Convex DB references
Key Architectural Patterns & Principles
• Serverless Functions: Each agent/workflow step is a stateless Convex function.
• Event-Driven & Streaming: Uses websocket-based delta streams for real-time sync.
• Layered Separation: Clear boundary between UI, client APIs, backend logic, and persistence.
• Composable Tools: Agent workflows call Tools (external or internal Convex functions) via a unified interface.
• RAG Integration: Hybrid vector/text search co-located with message context.
• Cross-Cutting: Rate limiting and usage tracking as pluggable components.