convex-agents-tools

Sstobo's avatarfrom Sstobo

Enables agents to call external functions, APIs, and database operations through tool definitions. Use this when agents need to fetch data, perform actions, or integrate with external services while maintaining clean separation.

⭐5stars🔀0forks📁View on GitHub🕐Updated Oct 18, 2025⬇️2downloads

When & Why to Use This Skill

Convex Agents Tools is a comprehensive framework designed to bridge the gap between LLM reasoning and actionable execution. It empowers Claude agents to perform external function calls, interact with third-party APIs, and execute complex database operations through structured tool definitions. By leveraging Zod for schema validation and providing built-in support for autonomous multi-step operations, this skill allows developers to build sophisticated, reliable agents that can interact with real-world data and services while maintaining a clean separation of concerns.

Use Cases

  • Dynamic Database Management: Enable agents to query, update, or delete records in a Convex database based on natural language instructions.
  • Third-Party API Integration: Connect agents to external services like Stripe for payments, Slack for notifications, or GitHub for repository management to automate cross-platform tasks.
  • Autonomous Multi-step Workflows: Build agents that can independently decide which tools to use and in what sequence to resolve complex, multi-layered user queries.
  • Human-in-the-Loop Operations: Design systems where agents perform background research or data preparation and pause for human approval before executing sensitive operations.
name"Convex Agents Tools"
description"Enables agents to call external functions, APIs, and database operations through tool definitions. Use this when agents need to fetch data, perform actions, or integrate with external services while maintaining clean separation."

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