Anthropic Tool Calling — Configuración

Módulo de tool calling listo para integrar en Next.js App Router usando la API de Anthropic. Es independiente de los módulos Text Generation y Chat.

AI
 ↓
Tool
 ↓
Database/API
 ↓
Result
 ↓
AI

Qué incluye

Definición de tools (schema + lógica de ejecución)
Múltiples tools
Ejecución de tools con validación del input contra el schema de cada una
Resultados de las tools devueltos al modelo
Manejo de errores de tools (errores de validación, errores de ejecución, límite de iteraciones)

Dependencias

Este módulo usa:

@anthropic-ai/sdk
ajv — validación con JSON schema para los inputs de las tools

No se instalan automáticamente: agregalos al package.json de tu proyecto como lo hacés normalmente.

Mapa de archivos

Archivo	Se ejecuta en	Para qué sirve
`types.ts`	ambos	Tipos compartidos, valores por defecto y formatos de error
`tools.ts`	servidor	Editalo. Registrá tus tools acá (schema + lógica de ejecución)
`service.ts`	servidor	Loop interno modelo↔tool, validación y normalización de errores
`actions.ts`	servidor	Server Action: importala en server components
`.env.local`	—	Variables de entorno

Configuración

Copiá todos los archivos a tu proyecto (ubicación sugerida: lib/ai/anthropic/tool-calling/).
Agregá tu clave en .env.local:
```
ANTHROPIC_API_KEY=sk-ant-...
```
Asegurate de que @anthropic-ai/sdk y ajv estén en tus dependencias.
Registrá tus tools en tools.ts (mirá más abajo).

Registrar una tool

Agregá esto al final de tools.ts:

registerTool({
  definition: {
    name: "get_order_status",
    description: "Look up the status of an order by its ID",
    input_schema: {
      type: "object",
      properties: {
        orderId: { type: "string", description: "The order ID" },
      },
      required: ["orderId"],
    },
  },
  execute: async (input: { orderId: string }) => {
    const order = await db.orders.findUnique({ where: { id: input.orderId } });
    if (!order) throw new Error(`Order ${input.orderId} not found`);
    return { status: order.status, updatedAt: order.updatedAt };
  },
});

input_schema es un JSON schema estándar: es lo que el modelo ve para decidir cómo llamar a la tool, y también lo que service.ts usa para validar el input del modelo antes de ejecutar execute().
Si lanzás un error dentro de execute(), la ejecución se detiene y se devuelve un tool_execution_error. No hace falta manejar los errores por tu cuenta más allá de lanzarlos.

Uso

Ejecutar un prompt con tools disponibles (server component / server action)

import { runWithTools } from "@/lib/ai/anthropic/tool-calling/actions";

const result = await runWithTools("What's the status of order #4821?");

if (result.error) {
  // result.error.code, result.error.message, result.error.toolName (if tool-related)
} else {
  console.log(result.data.text);       // the model's final answer
  console.log(result.data.toolCalls);  // [{ toolName, input, output }]
}

Manejo de errores

type AIErrorCode =
  | "invalid_request"
  | "authentication_error"
  | "rate_limited"
  | "overloaded"
  | "network_error"
  | "tool_validation_error"
  | "tool_execution_error"
  | "max_iterations_exceeded"
  | "unknown_error";

interface AIError {
  code: AIErrorCode;
  message: string;
  retryAfter?: number; // present when code === "rate_limited"
  toolName?: string;   // present for tool_validation_error / tool_execution_error
}

El loop se detiene de inmediato ante el primer error de validación o de ejecución de una tool: no reintenta ni le pide al modelo que se autocorrija. max_iterations_exceeded significa que el modelo siguió pidiendo tools más allá de DEFAULT_MAX_TOOL_ITERATIONS (5, se puede sobrescribir con options.maxToolIterations); suele ser señal de que una tool quedó en loop o de que hay que ajustar el prompt.