Convex Agents Tools

Purpose

Equips agents with the ability to take actions beyond text generation. Tools allow agents to call Convex functions, external APIs, and complex operations.

When to Use This Skill

• Agents need to query or modify database data
• Integrating with external APIs
• Creating human-in-the-loop workflows
• Agents autonomously deciding what actions to take
• Chaining tool calls for multi-step operations

Define Tools

Create Convex-aware tools:

import { createTool } from "@convex-dev/​agent";
import { z } from "zod";

export const getUserDataTool = createTool({
  description: "Fetch user information by email",
  args: z.object({
    email: z.string().email().describe("The user's email address"),
  }),
  handler: async (ctx, { email }): Promise<string> => {
    const user = await ctx.runQuery(api.users.getUserByEmail, { email });
    return user ? JSON.stringify(user) : "User not found";
  },
});

Configure Agent with Tools

const agentWithTools = new Agent(components.agent, {
  name: "Database Agent",
  languageModel: openai.chat("gpt-4o-mini"),
  tools: {
    getUserData: getUserDataTool,
  },
  maxSteps: 5, // Allow tool calls
});

Enable Automatic Tool Calling

export const autonomousAgent = action({
  args: { threadId: v.string(), request: v.string() },
  handler: async (ctx, { threadId, request }) => {
    const { thread } = await agentWithTools.continueThread(ctx, { threadId });

    const result = await thread.generateText(
      { prompt: request },
      { maxSteps: 10 } // Allow up to 10 tool calls
    );

    return result.text;
  },
});

Key Principles

• Use Zod for validation: .describe() on fields helps LLMs understand parameters
• Explicit return types: Always annotate handler return types
• Automatic history: Tool calls and results saved automatically in thread
• Context binding: Create tools inside actions where you have access to userId, etc.

Next Steps

• See fundamentals for agent setup
• See workflows for orchestrating multi-step operations
• See context for tool-aware context management