The @convex-dev/agent component is a Convex backend component for building AI agent applications that integrate language models with persistent conversation management, tool execution, and real-time streaming. This component provides the core infrastructure for managing AI agents, conversation threads, message history, vector embeddings, and file storage.
This page introduces the component's architecture, installation process, package structure, and fundamental concepts. For detailed usage of specific features, see:
Sources: README.md1-81 package.json1-18
Install the component package in your Convex project:
Sources: docs/getting-started.mdx14-20 README.md11-13
Create a convex.config.ts file in your convex/ folder and register the agent component:
Run npx convex dev to generate the component's type definitions. This step must complete successfully before defining agents.
Sources: docs/getting-started.mdx22-38
The repository includes an interactive setup script that installs dependencies, builds the component, and configures LLM API keys:
The setup script (setup.cjs1-182) handles:
Sources: setup.cjs1-182 package.json20
The package provides four primary entry points with distinct purposes:
| Export Path | Types Path | Purpose |
|---|---|---|
@convex-dev/agent | dist/client/index.d.ts | Core Agent class, message management, thread operations |
@convex-dev/agent/validators | dist/validators.d.ts | Convex validators for messages, threads, and related types |
@convex-dev/agent/react | dist/react/index.d.ts | React hooks for UI integration and message rendering |
@convex-dev/agent/test | src/test.ts | Testing utilities including mockModel |
Sources: package.json44-70
The component has the following peer dependencies that must be installed in your project:
React is marked as optional, allowing the component to be used in backend-only scenarios without React dependencies.
Sources: package.json71-82
The build process (package.json27) compiles TypeScript sources into the dist/ directory:
dist/
├── client/ # Core agent functionality
├── validators.js # Runtime validators
├── react/ # React integration
└── component/ # Convex component backend
Sources: package.json27 package.json40-43
The architecture consists of four layers: client applications interact with the Agent SDK through React hooks or direct API calls; the Agent SDK provides high-level abstractions for AI interactions; the Convex Component persists data in specialized tables; and external services provide LLM and embedding capabilities.
Sources: High-level Diagram 1
An Agent is the primary abstraction for AI interactions. Each agent encapsulates:
openai.chat("gpt-4o-mini"))Example agent definition:
Agents can generate text, stream responses, generate structured objects, and manage their own message history. For comprehensive agent configuration options, see Creating and Configuring Agents.
Sources: docs/getting-started.mdx39-53 example/convex/modelsForDemo.ts9-31
A Thread represents a linear conversation history that groups related messages. All messages in the Agent component belong to exactly one thread. Threads support:
userIdtitle and summaryorder and stepOrder fieldsCreating a thread:
Thread management is detailed in Thread Management.
Sources: docs/threads.mdx1-43 docs/getting-started.mdx64-66
Messages are the fundamental units of communication stored in the messages table. Each MessageDoc contains:
message field: the AI SDK ModelMessage with role and contentorder and stepOrder: dual-sequence identifiers for orderingstatus: lifecycle state ("pending", "success", "failed")agentName: the agent that created the messagemetadata: optional fields like usage, reasoning, warningsembeddingId: reference to vector embedding (if enabled)fileIds: references to stored filesThe order field increments with each prompt, while stepOrder tracks multi-step reasoning within the same prompt cycle. This allows grouping related messages (e.g., tool calls and their results) that occurred in response to a single user input.
For message structure and operations, see Message Structure and Ordering.
Sources: docs/messages.mdx1-12 docs/threads.mdx8-11
Messages transform through multiple formats during their lifecycle:
ModelMessage objects from the AI SDKMessageDoc with metadata via serializeMessageModelMessage via toModelMessage for AI SDK callsUIMessage via toUIMessage for client renderingThe UIMessage type extends the AI SDK's base type with additional fields like order, status, key, and agentName for easier UI development.
Sources: High-level Diagram 2, docs/messages.mdx87-112
Tools enable agents to execute functions during multi-step reasoning. The createTool function wraps JavaScript functions to make them available to language models:
Tools receive a ToolCtx context object with access to the agent, thread, Convex context, and authentication information. The agent executes tools automatically when the LLM requests them, continuing up to maxSteps iterations.
For tool execution patterns and multi-step reasoning, see Tools and Tool Execution.
Sources: docs/getting-started.mdx50
The component implements a polling-based streaming system that avoids WebSocket complexity while providing real-time updates:
Server-side streaming:
DeltaStreamer batches and throttles updates (50-100ms) to reduce database writesstreamingMessages and streamDeltas tablesClient-side streaming:
useSmoothText hook provides adaptive character-by-character displaycombineUIMessages merges sequential updates and handles tool state transitionsThis architecture enables real-time streaming UIs across multiple clients without persistent connections.
For streaming implementation details, see Streaming Architecture.
Sources: High-level Diagram 4
The Convex backend component defines the following tables:
| Table | Purpose | Key Indexes |
|---|---|---|
messages | Stores all conversation messages | by_threadId_order_stepOrder, by_userId, by_agentName |
threads | Thread metadata and ownership | by_userId_creationTime, by_creationTime |
streamingMessages | Active streaming state | by_streamId, by_order, by_threadId |
streamDeltas | Incremental streaming updates | by_streamId_cursor |
files | File metadata and reference counts | by_sha256, by_storageId |
embeddings_N | Vector embeddings (dimension-specific) | by_table_userId_threadId, vector index |
Each embeddings_N table supports a specific vector dimension (128, 256, 512, 1024, 1536, 3072, 4096), enabling hybrid text and vector search across message history.
Sources: High-level Diagram 1
The Agent class wraps component functions to provide a high-level API. Direct component access is available via components.agent for advanced use cases.
For the complete component API reference, see Component API Overview.
Sources: High-level Diagram 1
After running npx convex dev, the component generates type definitions:
The generated components object provides type-safe access to all component queries, mutations, and actions.
Sources: docs/debugging.mdx67-73
The following example demonstrates basic agent usage:
This creates an agent, generates a response to a prompt within a thread, and returns the text. The prompt and response are automatically saved to the messages table.
Sources: docs/getting-started.mdx56-71
The Agent Playground provides a web interface for debugging agents, browsing threads, inspecting messages, and testing context retrieval. Access it locally via:
Or use the hosted version at https://get-convex.github.io/agent/
For playground setup and features, see Agent Playground.
Sources: README.md9 playground/package.json1-14
The repository includes a full example application demonstrating:
Run the example:
Sources: README.md66-73
agent/
├── src/
│ ├── client/ # Core Agent SDK implementation
│ ├── react/ # React hooks and utilities
│ ├── component/ # Convex backend component
│ └── test.ts # Testing utilities
├── example/ # Example application
│ ├── convex/ # Backend functions
│ └── ui/ # React frontend
├── playground/ # Agent Playground web UI
└── docs/ # Documentation
Sources: package.json40-43
Refresh this wiki
This wiki was recently refreshed. Please wait 2 days to refresh again.