[{"_1":2,"_125":-5,"_126":-5},"loaderData",{"_3":4,"_124":-5},"routes/libros/ai_sdk",{"_5":6,"_7":8,"_15":16,"_20":21,"_25":26,"_71":72,"_73":74,"_75":76,"_77":76,"_78":76,"_79":76,"_80":76,"_81":-5,"_82":83,"_101":102,"_103":104,"_120":121},"content","# Capítulo 6: Tools — Dándole Manos al Modelo\n\nEn el capítulo anterior aprendiste a obtener datos estructurados del modelo. Pero hay un límite: solo puede generar información que ya \"conoce\".\n\n¿Qué pasa cuando necesitas que consulte tu base de datos? ¿Que busque productos en tu inventario? ¿Que procese una devolución?\n\nNecesitas **tools** — herramientas que el modelo puede ejecutar.\n\n## Código Primero\n\n```typescript\nimport { tool } from 'ai';\nimport { z } from 'zod';\n\nconst consultarInventario = tool({\n description: 'Consulta la disponibilidad de un producto en el inventario',\n inputSchema: z.object({\n producto: z.string().describe('Nombre o código del producto')\n }),\n execute: async ({ producto }) => {\n const inventario = {\n 'taladro-dewalt': { nombre: 'Taladro DeWalt 20V', stock: 8, precio: 2899 },\n 'pintura-comex': { nombre: 'Pintura Comex Vinimex 19L', stock: 23, precio: 1250 },\n };\n\n const item = inventario[producto.toLowerCase()];\n if (!item) return { encontrado: false, mensaje: 'Producto no encontrado' };\n\n return {\n encontrado: true,\n nombre: item.nombre,\n stock: item.stock,\n precio: `$${item.precio} MXN`\n };\n }\n});\n```\n\nUn tool tiene tres partes:\n- `description`: Le dice al modelo cuándo usarlo\n- `inputSchema`: Parámetros tipados con Zod\n- `execute`: La función que corre cuando el modelo lo llama\n\n## Cambios en AI SDK v6\n\n| v4/v5 | v6 |\n|-------|-----|\n| `parameters: z.object({...})` | `inputSchema: z.object({...})` |\n| `maxSteps: 5` | `stopWhen: stepCountIs(5)` |\n| Aprobación manual | `needsApproval: true` built-in |\n| Sin control de output | `toModelOutput` para reducir tokens |\n\n```bash\nnpx @ai-sdk/codemod v6\n```\n\n## El Comportamiento por Defecto\n\nPor defecto, `streamText` hace **UNA sola generación**. Si el modelo llama un tool, el flujo termina ahí:\n\n```\nUsuario: \"¿Tienen taladros DeWalt?\"\n ↓\nModelo: \"Necesito usar consultarInventario\"\n ↓\nSDK ejecuta: execute({ producto: 'taladro-dewalt' })\n ↓\nTool retorna: { stock: 8, precio: '$2,899 MXN' }\n ↓\nFIN. El modelo NO genera texto de respuesta.\n```\n\nEl cliente recibe el tool output, pero **no hay respuesta textual**.\n\n## stopWhen: Habilitando Multi-Step\n\nPara que el modelo use el resultado y genere respuesta, necesitas `stopWhen`:\n\n```typescript\n// app/routes/api.ferreteria.ts\nimport { streamText, stepCountIs, tool } from 'ai';\nimport { openai } from '@ai-sdk/openai';\nimport { z } from 'zod';\n\nconst consultarInventario = tool({\n description: 'Consulta stock y precio de un producto',\n inputSchema: z.object({\n producto: z.string()\n }),\n execute: async ({ producto }) => {\n return { nombre: producto, stock: 15, precio: '$299 MXN' };\n }\n});\n\nconst buscarProductos = tool({\n description: 'Busca productos por término',\n inputSchema: z.object({\n termino: z.string(),\n categoria: z.enum(['herramientas', 'plomeria', 'electricidad']).optional()\n }),\n execute: async ({ termino }) => {\n return [\n { nombre: 'Taladro DeWalt', precio: '$2,899 MXN' },\n { nombre: 'Taladro Makita', precio: '$2,450 MXN' },\n ];\n }\n});\n\nexport async function action({ request }) {\n const { messages } = await request.json();\n\n const result = streamText({\n model: openai('gpt-4o-mini'),\n system: `Eres el asistente de Ferretería San José.\n Ayudas a clientes a encontrar productos.\n Precios en pesos mexicanos.`,\n messages,\n tools: { consultarInventario, buscarProductos },\n stopWhen: stepCountIs(3), // CRÍTICO: sin esto no hay respuesta\n });\n\n return result.toUIMessageStreamResponse();\n}\n```\n\n`stepCountIs(3)` significa: \"continúa hasta 3 pasos máximo\". Ahora el flujo es:\n\n```\nUsuario: \"¿Tienen taladros DeWalt?\"\n ↓\nSDK ejecuta el tool\n ↓\nstopWhen evalúa: ¿seguimos? Sí\n ↓\nModelo genera: \"Sí, tenemos el Taladro DeWalt 20V a $2,899 MXN\"\n```\n\n## Renderizando Tools en el Cliente\n\nLos tool calls aparecen en `message.parts`:\n\n```typescript\nimport { useChat } from '@ai-sdk/react';\nimport { useState } from 'react';\n\nexport default function FerreteriaChat() {\n const [input, setInput] = useState('');\n const { messages, sendMessage, status } = useChat();\n\n return (\n

\n {messages.map((m) => (\n

\n {m.parts.map((part, i) => {\n if (part.type === 'text') {\n return {part.text};\n }\n\n if (part.type === 'tool-consultarInventario') {\n if (part.state === 'input-streaming') {\n return

⚙️ Consultando inventario...

;\n }\n if (part.state === 'output-available') {\n return (\n

\n {part.output.nombre} - Stock: {part.output.stock}\n

\n );\n }\n }\n\n return null;\n })}\n

\n ))}\n\n \n

\n );\n}\n```\n\nEstados de un tool call:\n- `input-streaming`: Recibiendo parámetros\n- `output-available`: Tool terminó, resultado listo\n- `approval-requested`: Esperando aprobación humana\n\n## Human-in-the-Loop: needsApproval\n\n`needsApproval` sirve para confirmar antes de ejecutar acciones sensibles:\n\n```typescript\nconst procesarDevolucion = tool({\n description: 'Procesa la devolución de un producto',\n inputSchema: z.object({\n codigoVenta: z.string(),\n montoReembolso: z.number()\n }),\n // Devoluciones mayores a $500 requieren confirmación\n needsApproval: async ({ montoReembolso }) => montoReembolso > 500,\n execute: async ({ codigoVenta, montoReembolso }) => {\n return {\n exito: true,\n mensaje: `Reembolso de $${montoReembolso} MXN procesado`,\n referencia: `DEV-${Date.now()}`\n };\n }\n});\n```\n\nEn el cliente, manejas la aprobación:\n\n```typescript\nconst { addToolApprovalResponse } = useChat();\n\n// En el render cuando part.state === 'approval-requested':\n

¿Confirmar devolución de ${part.input.montoReembolso} MXN?

\n \n \n

\n```\n\n## Optimización: toModelOutput\n\nCuando un tool retorna mucha data, el modelo consume tokens innecesarios:\n\n```typescript\nconst buscarProductos = tool({\n description: 'Busca productos en el catálogo',\n inputSchema: z.object({ termino: z.string() }),\n execute: async ({ termino }) => {\n const productos = await db.producto.findMany({\n where: { nombre: { contains: termino }},\n include: { imagenes: true, variantes: true } // Mucha data\n });\n return productos; // Objeto completo para el cliente\n },\n\n // Lo que recibe el modelo (reducido)\n toModelOutput: async (productos) => {\n return productos.map(p =>\n `- ${p.nombre}: $${p.precio} MXN`\n ).join('\\n');\n }\n});\n```\n\n- `execute` retorna data completa → El cliente muestra cards con imágenes\n- `toModelOutput` retorna resumen → El modelo genera respuesta sin gastar tokens extra\n\n## Preview: ToolLoopAgent\n\nEn el próximo capítulo veremos agentes en detalle. La diferencia clave:\n\n| `streamText` + tools | `ToolLoopAgent` |\n|---------------------|-----------------|\n| 1 paso por defecto | 20 pasos por defecto |\n| Necesitas `stopWhen` siempre | Continúa automático |\n| Chat interactivo | Tareas autónomas |\n\n```typescript\nimport { ToolLoopAgent, stepCountIs } from 'ai';\n\nconst asistente = new ToolLoopAgent({\n model: openai('gpt-4o-mini'),\n instructions: 'Eres el asistente de Ferretería San José.',\n tools: { consultarInventario, buscarProductos },\n stopWhen: stepCountIs(8), // Opcional, default es 20\n});\n\nconst { text, steps } = await asistente.generate({\n prompt: 'Compré un taladro (venta #FER-2025-001) y no funciona. Quiero devolverlo.'\n});\n\nconsole.log(`Resuelto en ${steps.length} pasos`);\n```\n\nEl agente se detiene cuando:\n1. La tarea está completada\n2. Un tool requiere aprobación\n3. Se alcanza el límite de pasos\n\n## Callbacks y Monitoreo\n\n```typescript\nconst result = streamText({\n model: openai('gpt-4o-mini'),\n messages,\n tools: { consultarInventario, buscarProductos },\n stopWhen: stepCountIs(5),\n\n onStepFinish({ stepType, usage }) {\n console.log(`Paso: ${stepType}, Tokens: ${usage.totalTokens}`);\n },\n\n onFinish({ text, usage, steps }) {\n console.log(`Completado en ${steps.length} pasos`);\n console.log(`Tokens totales: ${usage.totalTokens}`);\n }\n});\n```\n\n## Resumen\n\n| Concepto | Qué aprendiste |\n|----------|----------------|\n| `tool()` | Función que define una herramienta ejecutable |\n| `inputSchema` | Parámetros tipados con Zod (antes `parameters`) |\n| `execute` | La función que corre cuando el modelo llama el tool |\n| `stopWhen` | **CRÍTICO** — sin esto, no hay respuesta después del tool |\n| `stepCountIs(n)` | Helper para limitar pasos (reemplaza `maxSteps`) |\n| `needsApproval` | Requiere confirmación humana antes de ejecutar |\n| `toModelOutput` | Reduce tokens enviados al modelo |\n| `part.state` | Estados: `input-streaming`, `output-available`, `approval-requested` |\n\n### Tools vs Structured Output\n\n| Usar Tools cuando... | Usar Structured Output cuando... |\n|---------------------|----------------------------------|\n| Necesitas ejecutar acciones | Solo necesitas datos tipados |\n| Consultas externas (DB, API) | Parsear o clasificar texto |\n| El modelo decide qué hacer | Tú sabes qué estructura quieres |\n| Flujo conversacional | Respuesta única estructurada |\n\n---\n\nEn el próximo capítulo veremos **Agentes**: cuando el modelo toma el control completo del loop, decide autónomamente qué herramientas usar, y resuelve tareas complejas sin intervención.\n","currentChapter",{"_9":10,"_11":12,"_13":14},"id","06","title","Tools — Dándole Manos al Modelo","slug","capitulo-06","prevChapter",{"_9":17,"_11":18,"_13":19},"05","Structured Output — Respuestas Tipadas","capitulo-05","nextChapter",{"_9":22,"_11":23,"_13":24},"07","Agentes — Encapsulando la Inteligencia","capitulo-07","chapters",[27,31,35,39,43,47,16,8,21,51,55,59,63,67],{"_9":28,"_11":29,"_13":30},"prólogo","Prólogo","prologo",{"_9":32,"_11":33,"_13":34},"intro","Introducción","introduccion",{"_9":36,"_11":37,"_13":38},"01","Tu Primera Inferencia con IA","capitulo-01",{"_9":40,"_11":41,"_13":42},"02","React y el Hook useChat","capitulo-02",{"_9":44,"_11":45,"_13":46},"03","Dentro del Streaming","capitulo-03",{"_9":48,"_11":49,"_13":50},"04","React Router v7 — Tu Chat Full-Stack","capitulo-04",{"_9":52,"_11":53,"_13":54},"08","generateImage — Creando Imágenes con Código","capitulo-08",{"_9":56,"_11":57,"_13":58},"09","Embeddings — Búsqueda Semántica","capitulo-09",{"_9":60,"_11":61,"_13":62},"10","RAG — Retrieval Augmented Generation","capitulo-10",{"_9":64,"_11":65,"_13":66},"11","Agentic RAG — Agentes con Conocimiento","capitulo-11",{"_9":68,"_11":69,"_13":70},"12","Audio y Speech — Voz e IA","capitulo-12","hasAccess",true,"accessLevel","public","isSubscribed",false,"isPurchased","hasFullAccess","showSubscriptionDrawer","showPurchaseDrawer","userEmail","chaptersAccessInfo",{"_30":84,"_34":86,"_38":87,"_42":88,"_46":89,"_50":90,"_19":92,"_14":93,"_24":94,"_54":95,"_58":97,"_62":98,"_66":99,"_70":100},{"_73":74,"_85":76},"isLocked",{"_73":74,"_85":76},{"_73":74,"_85":76},{"_73":74,"_85":76},{"_73":74,"_85":76},{"_73":91,"_85":72},"paid",{"_73":74,"_85":76},{"_73":74,"_85":76},{"_73":74,"_85":76},{"_73":96,"_85":72},"subscriber",{"_73":96,"_85":72},{"_73":96,"_85":72},{"_73":91,"_85":72},{"_73":91,"_85":72},"bookSlug","ai-sdk","bookConfig",{"_11":105,"_106":107,"_108":109,"_110":111,"_112":102,"_113":114,"_115":116,"_117":118,"_119":-5},"IA aplicada con React y TypeScript","priceUSD",1500,"priceMXN",24900,"chaptersCount",12,"contentPath","routePath","ai_sdk","epubS3Key","fixtergeek/books/ai-sdk.epub","epubFilename","ai-sdk-react-router.epub","epubPublicPath","searchParams",{"_122":76,"_123":76},"success","subscribed","root","actionData","errors"]

¿Ya compraste el libro?