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
