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;

// 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
});

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;
  }
});

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 };
  }
});

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;
  }
});

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

// Step 1: Mutation saves message and schedules generation
export const sendMessage = mutation({
  args: { threadId: v.string(), prompt: v.string() },
  handler: async (ctx, { threadId, prompt }) => {
    const { messageId } = await saveMessage(ctx, components.agent, {
      threadId,
      prompt
    });
    await ctx.scheduler.runAfter(0, internal.chat.generateResponse, {
      threadId,
      promptMessageId: messageId
    });
    return messageId;
  }
});

// Step 2: Action generates response
export const generateResponse = internalAction({
  args: { threadId: v.string(), promptMessageId: v.string() },
  handler: async (ctx, { threadId, promptMessageId }) => {
    await agent.generateText(ctx, { threadId }, { promptMessageId });
  }
});

// Shorthand for Step 2:
export const generateResponse = agent.asTextAction();

// Text generation
const result = await agent.generateText(ctx, { threadId }, { prompt });

// Structured output
const result = await agent.generateObject(
  ctx,
  { threadId },
  {
    prompt: 'Extract user info',
    schema: z.object({ name: z.string(), email: z.string() })
  }
);

// Stream text (see STREAMING.md)
const result = await agent.streamText(ctx, { threadId }, { prompt });

// Multiple messages
const result = await agent.generateText(
  ctx,
  { threadId },
  {
    messages: [
      { role: 'user', content: 'Context message' },
      { role: 'user', content: 'Actual question' }
    ]
  }
);

import { listUIMessages, paginationOptsValidator } from '@convex-dev/agent';

export const listMessages = query({
  args: { threadId: v.string(), paginationOpts: paginationOptsValidator },
  handler: async (ctx, args) => {
    return await listUIMessages(ctx, components.agent, args);
  }
});

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

const { results, status, loadMore } = useUIMessages(
  api.chat.listMessages,
  { threadId },
  { initialNumItems: 20 }
);

const agent = new Agent(components.agent, {
  name: 'Agent Name',
  languageModel: openai.chat('gpt-4o-mini'),
  textEmbeddingModel: openai.embedding('text-embedding-3-small'),
  instructions: 'System prompt...',
  tools: {
    /* tools */
  },
  stopWhen: stepCountIs(10), // Or maxSteps: 10

  // Context options (see CONTEXT.md)
  contextOptions: {
    recentMessages: 100,
    excludeToolMessages: true,
    searchOptions: { limit: 10, textSearch: false, vectorSearch: false }
  },

  // Storage options
  storageOptions: { saveMessages: 'promptAndOutput' }, // 'all' | 'none'

  // Handlers
  usageHandler: async (ctx, { usage, model, provider, agentName }) => {},
  contextHandler: async (ctx, { allMessages }) => allMessages,
  rawRequestResponseHandler: async (ctx, { request, response }) => {},

  // Call settings
  callSettings: { maxRetries: 3, temperature: 1.0 }
});