showcase/shell-docs/src/content/docs/integrations/built-in-agent/server-tools.mdx
Server tools are functions that run on your backend that the Built-in Agent can invoke. They're defined using defineTool() with Zod schemas for type-safe parameters.
import { BuiltInAgent, defineTool } from "@copilotkit/runtime/v2";
import { z } from "zod";
const getWeather = defineTool({
name: "getWeather",
description: "Get the current weather for a location",
parameters: z.object({
location: z.string().describe("The location's name"),
}),
execute: async ({ location }) => {
// Your implementation here
return { temperature: 72, condition: "sunny", location };
},
});
const builtInAgent = new BuiltInAgent({
model: "openai:gpt-5.4-mini",
tools: [getWeather],
maxSteps: 2 //Important for tool calls
});
Tools can return any JSON-serializable value. The agent uses the response to continue the conversation.
Pass an array of tools — the agent chooses which to call based on the user's request:
const searchDocs = defineTool({
name: "searchDocs",
description: "Search the documentation for relevant articles",
parameters: z.object({
query: z.string().describe("The search query"),
}),
execute: async ({ query }) => {
const results = await search(query);
return { results, count: results.length };
},
});
const createTicket = defineTool({
name: "createTicket",
description: "Create a support ticket",
parameters: z.object({
title: z.string().describe("Ticket title"),
priority: z.enum(["low", "medium", "high"]).describe("Ticket priority"),
description: z.string().describe("Detailed description of the issue"),
}),
execute: async ({ title, priority, description }) => {
const ticket = await db.tickets.create({ title, priority, description });
return { ticketId: ticket.id, status: "created" };
},
});
const builtInAgent = new BuiltInAgent({
model: "openai:gpt-5.4-mini",
tools: [searchDocs, createTicket], // [!code highlight]
maxSteps: 2
});
Use nested objects, arrays, enums, and optional fields for sophisticated tool parameters:
const bookFlight = defineTool({
name: "bookFlight",
description: "Search for and book flights",
parameters: z.object({
trip: z.object({
origin: z.string().describe("Origin airport code (e.g., SFO)"),
destination: z.string().describe("Destination airport code (e.g., JFK)"),
date: z.string().describe("Departure date in YYYY-MM-DD format"),
}),
passengers: z.array(
z.object({
name: z.string(),
seatPreference: z.enum(["window", "middle", "aisle"]).optional(),
})
).describe("List of passengers"),
class: z.enum(["economy", "business", "first"]).default("economy"),
}),
execute: async ({ trip, passengers, class: seatClass }) => {
const flights = await searchFlights(trip, seatClass);
return { flights, passengerCount: passengers.length };
},
});
Throw errors or return error objects from your tool — the agent will see the error and can inform the user or try a different approach:
const getUser = defineTool({
name: "getUser",
description: "Look up a user by email",
parameters: z.object({
email: z.string().email().describe("The user's email address"),
}),
execute: async ({ email }) => {
const user = await db.users.findByEmail(email);
if (!user) {
throw new Error(`No user found with email: ${email}`); // [!code highlight]
}
return { id: user.id, name: user.name, role: user.role };
},
});
By default, the agent performs a single step. If your agent needs to chain tool calls (e.g., search first, then create a ticket), set maxSteps:
const builtInAgent = new BuiltInAgent({
model: "openai:gpt-5.4-mini",
maxSteps: 5, // [!code highlight]
tools: [searchDocs, createTicket, getUser],
});
With maxSteps: 5, the agent can:
searchDocs to find relevant infocreateTicket with details from the search