Add Tools

Use this path when the model needs to inspect data, call services, or perform actions owned by your application.

Goal

By the end, you should have:

• one Zod-backed tool
• an agent with that tool registered
• a low turn limit
• a clear permission boundary around side effects

Path

1. Read Creating Tools to define a tool with input validation.
2. Read Tool Schemas to understand how Zod schemas become provider tool definitions.
3. Read Tools on Agents to register tools on an agent.
4. Read Tool Results to understand what gets sent back to the model.
5. Read Tool Errors to decide when to return an expected result and when to throw.

Minimal Shape

import { AgentBuilder, createTool } from "@anvia/core";
import { OpenAIClient } from "@anvia/openai";
import { z } from "zod";

const lookupOrder = createTool({
  name: "lookup_order",
  description: "Look up an order by order id.",
  input: z.object({
    orderId: z.string(),
  }),
  async execute({ orderId }) {
    return { orderId, status: "shipped" };
  },
});

const model = new OpenAIClient({ apiKey }).completionModel("gpt-5");

const agent = new AgentBuilder("support", model)
  .instructions("Use tools when order status is needed.")
  .tool(lookupOrder)
  .defaultMaxTurns(3)
  .build();

Production Notes

• Keep permission checks inside your tool code.
• Return explicit values for expected product states such as not_found.
• Throw only when the workflow should fail or be retried.
• Start with low turn limits and increase only when the workflow needs it.

Add Next