convex-agent

Convex Agent Component

Build AI agents with persistent message history, tool calling, real-time streaming, and durable workflows.

Installation

npm install @convex-dev/agent

// convex/convex.config.ts
import { defineApp } from 'convex/server';
import agent from '@convex-dev/agent/convex.config';

const app = defineApp();
app.use(agent);
export default app;

Run npx convex dev to generate component code before defining agents.

Core Concepts

Agent Definition

// convex/agents.ts
import { Agent } from '@convex-dev/agent';
import { openai } from '@ai-sdk/openai';
import { components } from './_generated/api';

const supportAgent = new Agent(components.agent, {
  name: 'Support Agent',
  languageModel: openai.chat('gpt-4o-mini'),
  textEmbeddingModel: openai.embedding('text-embedding-3-small'), // For vector search
  instructions: 'You are a helpful support assistant.',
  tools: { lookupAccount, createTicket },
  stopWhen: stepCountIs(10) // Or use maxSteps: 10
});

Basic Usage (Two Approaches)

Approach 1: Direct generation (simpler)

import { createThread } from '@convex-dev/agent';

export const chat = action({
  args: { prompt: v.string() },
  handler: async (ctx, { prompt }) => {
    const threadId = await createThread(ctx, components.agent);
    const result = await agent.generateText(ctx, { threadId }, { prompt });
    return result.text;
  }
});

Approach 2: Thread object (more features)

export const chat = action({
  args: { prompt: v.string() },
  handler: async (ctx, { prompt }) => {
    const { threadId, thread } = await agent.createThread(ctx);
    const result = await thread.generateText({ prompt });
    return { threadId, text: result.text };
  }
});

Continue Existing Thread

export const continueChat = action({
  args: { threadId: v.string(), prompt: v.string() },
  handler: async (ctx, { threadId, prompt }) => {
    // Message history included automatically
    const result = await agent.generateText(ctx, { threadId }, { prompt });
    return result.text;
  }
});