[{"_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 7: Agentes — Encapsulando la Inteligencia\n\nEn el capítulo anterior construiste un chat con tools. El modelo llama herramientas, el SDK las ejecuta automáticamente, el modelo genera respuesta. Todo funciona.\n\nPero hay un problema práctico: cada vez que quieres usar esa configuración, tienes que repetir todo:\n\n```typescript\n// Cada llamada requiere toda la configuración\nconst result = streamText({\n model: openai('gpt-4o-mini'),\n system: `Eres el asistente de Distribuidora Industrial del Bajío...`,\n messages,\n tools: {\n consultarInventario,\n buscarProductos,\n verificarPedido,\n generarCotizacion,\n },\n stopWhen: stepCountIs(5),\n});\n```\n\nSi tienes múltiples endpoints que usan el mismo \"asistente\", estás duplicando código. Si cambias el system prompt, tienes que actualizarlo en varios lugares.\n\n**ToolLoopAgent** resuelve esto: encapsula modelo, instrucciones y herramientas en un objeto reutilizable.\n\n## Código Primero\n\n```typescript\nimport { ToolLoopAgent, stepCountIs, tool } from 'ai';\nimport { openai } from '@ai-sdk/openai';\nimport { z } from 'zod';\n\n// Tools\nconst consultarInventario = tool({\n description: 'Consulta stock y precio de un producto',\n inputSchema: z.object({\n codigo: z.string().describe('Código SKU del producto')\n }),\n execute: async ({ codigo }) => {\n return { codigo, nombre: 'Válvula Industrial 2\"', stock: 45, precio: 1850 };\n }\n});\n\nconst buscarProductos = tool({\n description: 'Busca productos por término',\n inputSchema: z.object({\n termino: z.string()\n }),\n execute: async ({ termino }) => {\n return [\n { codigo: 'VAL-001', nombre: 'Válvula Industrial 2\"', precio: 1850 },\n { codigo: 'VAL-002', nombre: 'Válvula de Control 3\"', precio: 3200 },\n ];\n }\n});\n\n// El agente encapsula todo\nconst asistenteDistribuidora = new ToolLoopAgent({\n model: openai('gpt-4o-mini'),\n instructions: `Eres el asistente de Distribuidora Industrial del Bajío.\n Ayudas a clientes a encontrar productos y verificar disponibilidad.\n Precios siempre en pesos mexicanos.\n Sé profesional y directo.`,\n tools: {\n consultarInventario,\n buscarProductos,\n },\n});\n\n// Ahora usar es simple\nconst { text, steps } = await asistenteDistribuidora.generate({\n prompt: '¿Tienen válvulas industriales de 2 pulgadas?'\n});\n\nconsole.log(text);\n// \"Sí, contamos con la Válvula Industrial 2\" (SKU: VAL-001) a $1,850 MXN. Hay 45 unidades en stock.\"\nconsole.log(`Completado en ${steps.length} pasos`);\n```\n\nDefine una vez, usa en cualquier parte.\n\n## ¿Qué es un Agente?\n\nUn agente tiene tres componentes:\n\n1. **LLM** — Procesa entrada y decide qué hacer\n2. **Herramientas** — Extienden capacidades más allá del texto\n3. **Loop** — Ejecuta herramientas hasta completar la tarea\n\n`ToolLoopAgent` maneja los tres automáticamente. El loop continúa hasta que:\n- El modelo genera texto sin llamar tools (tarea completa)\n- Un tool requiere aprobación (`needsApproval`)\n- Se alcanza el límite de pasos (default: 20)\n- Un tool no tiene función `execute`\n\n## Parámetros del Constructor\n\n```typescript\nconst agente = new ToolLoopAgent({\n // === REQUERIDOS ===\n model: openai('gpt-4o-mini'), // Provider object, no string\n\n // === CONFIGURACIÓN ===\n instructions: 'Tu prompt de sistema', // Antes era 'system'\n tools: { tool1, tool2 },\n\n // === CONTROL DE LOOP ===\n stopWhen: stepCountIs(10), // Default: stepCountIs(20)\n\n // === SELECCIÓN DE TOOLS ===\n toolChoice: 'auto', // 'auto' | 'required' | 'none' | { type: 'tool', toolName: 'x' }\n activeTools: ['tool1'], // Limita cuáles están disponibles\n\n // === CALLBACKS ===\n onStepFinish: ({ stepType, usage }) => {\n console.log(`Paso: ${stepType}, Tokens: ${usage.totalTokens}`);\n },\n onFinish: ({ steps, result }) => {\n console.log(`Completado en ${steps.length} pasos`);\n },\n\n // === PARÁMETROS DEL MODELO ===\n temperature: 0.7,\n maxOutputTokens: 1000,\n});\n```\n\n### El cambio de system a instructions\n\nEn AI SDK v6, el parámetro se renombró:\n\n| v5 | v6 |\n|----|-----|\n| `system: '...'` | `instructions: '...'` |\n\nEsto refleja mejor el propósito: son instrucciones para el agente, no configuración del sistema.\n\n## Métodos: generate y stream\n\n### generate() — Ejecución Completa\n\n```typescript\nconst { text, steps, finishReason } = await agente.generate({\n prompt: '¿Cuál es el precio del motor trifásico de 5HP?'\n});\n\n// O con historial de mensajes\nconst result = await agente.generate({\n messages: [\n { role: 'user', content: 'Buenos días' },\n { role: 'assistant', content: 'Buenos días, ¿en qué puedo ayudarle?' },\n { role: 'user', content: 'Necesito cotización de bombas sumergibles' }\n ]\n});\n```\n\nEl objeto de retorno incluye:\n- `text` — Respuesta final del agente\n- `steps` — Array con cada paso ejecutado\n- `finishReason` — Por qué terminó ('stop', 'tool-calls', etc.)\n\n### stream() — Respuesta en Tiempo Real\n\n```typescript\nconst result = agente.stream({\n prompt: 'Dame un resumen de los productos más vendidos'\n});\n\n// Stream de texto\nfor await (const chunk of result.textStream) {\n process.stdout.write(chunk);\n}\n```\n\nPara APIs web:\n\n```typescript\n// app/routes/api.chat.ts\nimport { asistenteDistribuidora } from '~/agents/distribuidora';\n\nexport async function action({ request }: Route.ActionArgs) {\n const { messages } = await request.json();\n\n const result = asistenteDistribuidora.stream({ messages });\n\n return result.toUIMessageStreamResponse();\n}\n```\n\n## Control de Loop: stopWhen\n\nPor defecto, el agente ejecuta hasta 20 pasos. Personaliza con `stopWhen`:\n\n### Límite de pasos\n\n```typescript\nimport { stepCountIs } from 'ai';\n\nconst agente = new ToolLoopAgent({\n model: openai('gpt-4o-mini'),\n tools: { ... },\n stopWhen: stepCountIs(5), // Máximo 5 pasos\n});\n```\n\n### Parar en tool específico\n\n```typescript\nimport { hasToolCall } from 'ai';\n\nconst agente = new ToolLoopAgent({\n model: openai('gpt-4o-mini'),\n tools: { buscar, confirmarCompra },\n stopWhen: hasToolCall('confirmarCompra'), // Para cuando llama confirmarCompra\n});\n```\n\n### Múltiples condiciones\n\n```typescript\nstopWhen: [\n stepCountIs(10),\n hasToolCall('escalarAHumano')\n]\n// Para cuando CUALQUIERA se cumple\n```\n\n### Condición personalizada\n\n```typescript\n// Parar si encuentra la respuesta\nconst encontroRespuesta = ({ steps }) => {\n return steps.some(step =>\n step.text?.includes('PRECIO FINAL:')\n ) ?? false;\n};\n\nconst agente = new ToolLoopAgent({\n model: openai('gpt-4o-mini'),\n tools: { ... },\n stopWhen: encontroRespuesta\n});\n```\n\n### Control de presupuesto\n\n```typescript\n// Parar si excede presupuesto de tokens\nconst presupuestoExcedido = ({ steps }) => {\n const totalTokens = steps.reduce(\n (acc, step) => acc + (step.usage?.totalTokens ?? 0),\n 0\n );\n // Límite: 10,000 tokens\n return totalTokens > 10000;\n};\n```\n\n## prepareStep: Modificación Dinámica\n\n`prepareStep` se ejecuta **antes de cada paso**. Permite modificar configuración sobre la marcha.\n\n### Cambiar modelo según complejidad\n\n```typescript\nconst agente = new ToolLoopAgent({\n model: openai('gpt-4o-mini'),\n tools: { ... },\n\n prepareStep: async ({ stepNumber, messages }) => {\n // Si llevamos muchos pasos, usar modelo más potente\n if (stepNumber > 3) {\n return { model: openai('gpt-4o') };\n }\n return {};\n }\n});\n```\n\n### Limitar herramientas por fase\n\n```typescript\nprepareStep: async ({ stepNumber }) => {\n if (stepNumber <= 2) {\n // Fase 1: Solo buscar\n return { activeTools: ['buscar'], toolChoice: 'required' };\n }\n if (stepNumber <= 4) {\n // Fase 2: Analizar\n return { activeTools: ['analizar'] };\n }\n // Fase 3: Concluir\n return { activeTools: ['resumir'], toolChoice: 'required' };\n}\n```\n\n### Gestión de contexto largo\n\n```typescript\nprepareStep: async ({ messages }) => {\n if (messages.length > 20) {\n // Mantener solo el primer mensaje (sistema) y los últimos 10\n return {\n messages: [messages[0], ...messages.slice(-10)]\n };\n }\n return {};\n}\n```\n\n## Inspeccionando los Pasos\n\nDespués de `generate()`, puedes ver exactamente qué hizo el agente:\n\n```typescript\nconst { text, steps } = await agente.generate({\n prompt: 'Busca motores trifásicos y dame el más económico'\n});\n\nfor (const step of steps) {\n console.log('---');\n console.log('Número:', step.stepNumber);\n console.log('Tipo:', step.stepType);\n\n if (step.toolCalls) {\n for (const call of step.toolCalls) {\n console.log('Tool:', call.toolName);\n console.log('Input:', JSON.stringify(call.args));\n console.log('Output:', JSON.stringify(call.result));\n }\n }\n\n if (step.text) {\n console.log('Texto:', step.text);\n }\n\n console.log('Tokens:', step.usage?.totalTokens);\n}\n```\n\nOutput típico:\n\n```\n---\nNúmero: 1\nTipo: tool_call\nTool: buscarProductos\nInput: {\"termino\":\"motores trifásicos\"}\nOutput: [{\"codigo\":\"MOT-001\",\"nombre\":\"Motor 3HP\",\"precio\":8500},{\"codigo\":\"MOT-002\",\"nombre\":\"Motor 5HP\",\"precio\":12800}]\nTokens: 156\n\n---\nNúmero: 2\nTipo: text_generation\nTexto: El motor más económico es el Motor 3HP (MOT-001) a $8,500 MXN.\nTokens: 89\n```\n\n## Tipado con InferAgentUIMessage\n\nPara type-safety completo en el frontend:\n\n```typescript\n// agents/distribuidora.ts\nimport { ToolLoopAgent, InferAgentUIMessage } from 'ai';\n\nexport const asistenteDistribuidora = new ToolLoopAgent({\n model: openai('gpt-4o-mini'),\n instructions: '...',\n tools: { consultarInventario, buscarProductos },\n});\n\n// Exportar el tipo inferido\nexport type DistribuidoraMessage = InferAgentUIMessage;\n```\n\n```typescript\n// components/Chat.tsx\n'use client';\n\nimport { useChat } from '@ai-sdk/react';\nimport type { DistribuidoraMessage } from '~/agents/distribuidora';\n\nexport function Chat() {\n const { messages } = useChat();\n\n // TypeScript sabe exactamente qué tools existen y sus tipos\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 // TypeScript conoce los tools disponibles\n if (part.type === 'tool-consultarInventario') {\n return ;\n }\n return null;\n })}\n

\n ))}\n

\n );\n}\n```\n\n## Caso Práctico: Agente de Cobranza\n\n```typescript\n// agents/cobranza.ts\nimport { ToolLoopAgent, stepCountIs, tool } from 'ai';\nimport { openai } from '@ai-sdk/openai';\nimport { z } from 'zod';\nimport { db } from '~/lib/db';\n\nconst buscarCliente = tool({\n description: 'Busca cliente por nombre o RFC',\n inputSchema: z.object({\n termino: z.string()\n }),\n execute: async ({ termino }) => {\n const cliente = await db.cliente.findFirst({\n where: {\n OR: [\n { nombre: { contains: termino, mode: 'insensitive' } },\n { rfc: { contains: termino, mode: 'insensitive' } }\n ]\n }\n });\n if (!cliente) return { encontrado: false };\n return {\n encontrado: true,\n id: cliente.id,\n nombre: cliente.nombre,\n rfc: cliente.rfc,\n saldoPendiente: cliente.saldoPendiente\n };\n }\n});\n\nconst obtenerFacturas = tool({\n description: 'Obtiene facturas pendientes de un cliente',\n inputSchema: z.object({\n clienteId: z.string()\n }),\n execute: async ({ clienteId }) => {\n const facturas = await db.factura.findMany({\n where: { clienteId, estatus: 'PENDIENTE' },\n select: { folio: true, monto: true, vencimiento: true }\n });\n return facturas.map(f => ({\n folio: f.folio,\n monto: `$${f.monto.toLocaleString()} MXN`,\n vencimiento: f.vencimiento.toLocaleDateString('es-MX'),\n diasVencido: Math.floor((Date.now() - f.vencimiento.getTime()) / 86400000)\n }));\n }\n});\n\nconst enviarRecordatorio = tool({\n description: 'Envía recordatorio de pago por correo',\n inputSchema: z.object({\n clienteId: z.string(),\n facturas: z.array(z.string()).describe('Folios de facturas'),\n tono: z.enum(['amable', 'formal', 'urgente'])\n }),\n execute: async ({ clienteId, facturas, tono }) => {\n // Aquí enviarías el correo real\n console.log(`Enviando recordatorio ${tono} a ${clienteId}`);\n return { enviado: true, timestamp: new Date().toISOString() };\n }\n});\n\nexport const agenteCobranza = new ToolLoopAgent({\n model: openai('gpt-4o-mini'),\n\n instructions: `Eres el asistente de cobranza de una distribuidora.\n\nTu trabajo:\n- Buscar información de clientes\n- Identificar facturas vencidas\n- Enviar recordatorios de pago\n\nReglas:\n- Siempre busca el cliente primero\n- Usa tono amable para facturas recién vencidas (< 15 días)\n- Usa tono formal para 15-30 días vencidas\n- Usa tono urgente para > 30 días vencidas\n- Reporta montos en pesos mexicanos`,\n\n tools: {\n buscarCliente,\n obtenerFacturas,\n enviarRecordatorio,\n },\n\n stopWhen: stepCountIs(8),\n\n onStepFinish({ stepType, toolCalls }) {\n if (toolCalls?.length) {\n console.log(`[Cobranza] ${toolCalls[0].toolName}`);\n }\n },\n\n onFinish({ steps }) {\n console.log(`[Cobranza] Completado en ${steps.length} pasos`);\n }\n});\n```\n\nUso:\n\n```typescript\n// Una sola línea para ejecutar tarea compleja\nconst { text } = await agenteCobranza.generate({\n prompt: 'Manda recordatorio a Constructora Hernández por sus facturas vencidas'\n});\n\n// El agente automáticamente:\n// 1. Busca al cliente\n// 2. Obtiene sus facturas pendientes\n// 3. Determina el tono según días vencidos\n// 4. Envía el recordatorio\n// 5. Genera respuesta confirmando\n```\n\n## Resumen\n\n| Concepto | Qué aprendiste |\n|----------|----------------|\n| `ToolLoopAgent` | Encapsula modelo, instrucciones y tools en objeto reutilizable |\n| `instructions` | Prompt de sistema (antes `system`) |\n| `generate()` | Ejecuta y retorna resultado completo |\n| `stream()` | Ejecuta con respuesta en tiempo real |\n| `stopWhen` | Condiciones de parada (default: 20 pasos) |\n| `stepCountIs(n)` | Para después de n pasos |\n| `hasToolCall(name)` | Para cuando se llama un tool específico |\n| `prepareStep` | Modifica configuración antes de cada paso |\n| `onStepFinish` | Callback después de cada paso |\n| `onFinish` | Callback al completar |\n| `InferAgentUIMessage` | Infiere tipos para frontend |\n\n### ¿Cuándo usar ToolLoopAgent?\n\n| Usa funciones core (streamText) | Usa ToolLoopAgent |\n|--------------------------------|-------------------|\n| Configuración única | Configuración reutilizada |\n| Control muy específico | Comportamiento estándar |\n| Integración con código existente | Nuevo desarrollo |\n\nEl agente es una abstracción de conveniencia. Por debajo usa las mismas funciones core. Si necesitas control total, siempre puedes usar `generateText` o `streamText` directamente.\n\n---\n\nEn el próximo capítulo exploraremos **Embeddings y RAG**: cómo darle a tu agente acceso a documentos y bases de conocimiento para respuestas más precisas y contextuales.\n","currentChapter",{"_9":10,"_11":12,"_13":14},"id","07","title","Agentes — Encapsulando la Inteligencia","slug","capitulo-07","prevChapter",{"_9":17,"_11":18,"_13":19},"06","Tools — Dándole Manos al Modelo","capitulo-06","nextChapter",{"_9":22,"_11":23,"_13":24},"08","generateImage — Creando Imágenes con Código","capitulo-08","chapters",[27,31,35,39,43,47,51,16,8,21,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},"05","Structured Output — Respuestas Tipadas","capitulo-05",{"_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,"_54":92,"_19":93,"_14":94,"_24":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?