Constructor de Agentes IA

Esta página es la guía canónica para construir agentes LLM con el AI Agent Builder de DevUtilities. Use el flujo guiado de arriba mientras lee, o salte a un tema abajo. Schemas, JSON MCP, prompts y conteos de tokens permanecen en su navegador — nada se sube para inferencia.

AI Agent Builder es un taller del lado del cliente para ensamblar configs de agentes listos para producción: herramientas JSON Schema para function calling de OpenAI, validación mcpServers para Cursor y Claude Desktop, system prompts, presupuestos de tokens combinados y artefactos exportables para traspaso al equipo.

Qué obtiene

• Cuatro modos de flujo: agente completo, solo function calling, configuración MCP, respuesta estructurada
• Plantillas de inicio: Filesystem MCP, OpenAI function calling, clasificador estructurado
• Inferencia ejemplo-JSON → JSON Schema con additionalProperties: false estricto opcional
• Lint MCP local con errores y advertencias por JSON-pointer
• Presupuesto de tokens combinado entre prompt, tools minificadas y JSON MCP
• Exportaciones: OpenAI tools JSON, response_format, config MCP, resumen markdown, bundle completo

Use este builder cuando

• Necesita OpenAI tools JSON y no quiere escribir JSON Schema a mano
• Está conectando servidores MCP de Cursor o Claude Desktop y quiere lint antes de pegar
• Debe demostrar que el prompt + tools del agente aún caben en una ventana de contexto
• Quiere una sesión persistida que encadene schema → MCP → prompt → export

Prefiera una herramienta independiente cuando

• Solo necesita comparación profunda de encoding o cálculo de costos → LLM Token Counter
• Solo necesita lint MCP puntual sin prompts → MCP Validator
• Solo necesita inferencia de schema desde una muestra → Structured Output Generator

Elija un modo antes de definir tools. Los modos ocultan pasos irrelevantes para que no luche con paneles vacíos.

Recorrido inicial para un agente completo. Los atajos de plantilla omiten varios de estos pasos.

1. Elija Agente completo (o cargue la plantilla OpenAI function calling).
2. En Definir tools, agregue cada tool con un nombre claro, descripción y JSON de argumentos de ejemplo representativo.
3. Revise el JSON Schema inferido — active el modo estricto para structured outputs / strict tool calling de OpenAI.
4. Pegue o edite el JSON mcpServers si el agente correrá dentro de Cursor o Claude Desktop; corrija cada error antes de continuar.
5. Escriba system instructions que indiquen al modelo cuándo llamar cada tool y qué nunca inventar.
6. Abra Presupuesto de tokens, elija cl100k_base u o200k_base, y confirme que el total combinado cabe en su modelo.
7. Exporte OpenAI tools JSON para la API, config MCP para el cliente de escritorio y un resumen markdown para el equipo.
8. Opcionalmente exporte el bundle JSON completo para que otro ingeniero pueda recargar el mismo estado de sesión después.

Problema: necesita un agente de soporte al cliente que consulte clima y pedidos vía OpenAI function calling, pero el JSON Schema escrito a mano sigue fallando la validación estricta.

Cómo lo resuelve esta herramienta

1. Seleccione el modo Function calling o cargue la plantilla OpenAI function calling (clima + consulta de pedidos).
2. Edite el JSON de ejemplo para que cada campo que necesite en producción aparezca al menos una vez — las claves faltantes no se convertirán en propiedades required.
3. Active el modo estricto para que cada objeto emita additionalProperties: false.
4. Ajuste el system prompt: confirme IDs de pedido, nunca invente resultados de tools, mantenga respuestas concisas.
5. Revise el presupuesto de tokens bajo o200k_base si despliega en GPT-4o.
6. Exporte OpenAI tools JSON y péguelo en su cliente de Chat Completions o Responses API.

Resultado: un array de tools estricto y listo para la API más un prompt que coincide con los schemas — sin un editor de schema separado.

Problema: Cursor o Claude Desktop rechazan su mcp.json, o el servidor filesystem arranca con el directorio incorrecto y puede ver demasiado del disco.

Cómo lo resuelve esta herramienta

1. Elija el modo Configuración MCP o cargue la plantilla Filesystem MCP.
2. Reemplace /path/to/allowed/dir con una ruta absoluta al único directorio que el agente puede tocar.
3. Ejecute la validación — corrija command/args faltantes, URLs inválidas y valores env que no sean string.
4. Use valores env de marcador de posición (no secretos de producción) mientras hace lint en el navegador.
5. Exporte el JSON mcpServers validado a su config de Cursor o Claude Desktop.
6. Agregue system instructions que exijan confirmación antes de operaciones destructivas de archivos.

Resultado: una config de cliente MCP con lint y un prompt alineado con las capacidades del servidor antes de reiniciar la app de escritorio.

Problema: necesita que el modelo devuelva sentimiento, confianza, temas y un resumen corto como JSON — las respuestas en prosa rompen su parser downstream.

Cómo lo resuelve esta herramienta

1. Elija el modo Respuesta estructurada o cargue la plantilla de clasificador estructurado.
2. Edite el JSON de ejemplo para que coincida con la forma exacta que espera su pipeline.
3. Active el modo estricto para que las claves no declaradas se rechacen en validación.
4. Escriba un system prompt que prohíba prosa fuera del objeto JSON.
5. Exporte response_format json_schema para structured outputs de OpenAI.
6. Verifique que el presupuesto de tokens aún deje espacio para el documento de entrada que clasificará.

Resultado: un schema de salida único que puede insertar en APIs de structured output con instrucciones coincidentes.

Problema: tras agregar tres tools y una config MCP larga, el prompt combinado del agente ya no cabe en el presupuesto práctico de GPT-4o una vez incluida el historial de chat.

Cómo lo resuelve esta herramienta

1. Abra el paso Presupuesto de tokens y anote el total combinado de prompt + tools minificadas + JSON MCP.
2. Acorte descripciones de tools y quite campos de ejemplo no usados que inflan schemas required.
3. Mueva texto de política verboso fuera del system prompt siempre activo hacia recuperación bajo demanda.
4. Si solo necesita matemática de encoding más profunda, copie el payload ensamblado a LLM Token Counter.
5. Reexporte solo cuando el presupuesto muestre margen cómodo para historial y completions.

Resultado: detecta el overflow en el builder — no después del primer error 400 en producción.

El JSON de ejemplo debe ser JSON estricto. Solo las claves presentes en el ejemplo se vuelven propiedades required. Objetos y arrays anidados infieren tipos desde los valores de muestra.

Reglas prácticas

• Incluya cada campo que el modelo deba poder enviar — omitir significa «no required», no «opcional con un default».
• Use enums realistas como muestras string, luego edite a mano el schema si necesita un array enum explícito.
• Active el modo estricto para emitir additionalProperties: false en cada objeto — recomendado para structured outputs y strict tool calling de OpenAI.
• Los arrays vacíos infieren tipos de ítem débiles — agregue al menos un elemento representativo.

Los servidores stdio necesitan command y normalmente args. Los remotos necesitan una url http o https válida. Los valores env deben ser strings. Los errores bloquean la confianza de exportación; las advertencias merecen un pase manual.

Envelopes de cliente habituales

• La clave de nivel superior debe ser "mcpServers" según las convenciones de Cursor y Claude Desktop
• Los servidores filesystem deben usar rutas absolutas en allow-list
• Prefiera marcadores de posición env al editar en el navegador; inyecte secretos reales solo en la máquina local

Los conteos de tokens combinan system prompt, schemas de tools minificadas y JSON MCP. Elija cl100k_base para aproximación GPT-4 / Claude u o200k_base para GPT-4o. Los conteos usan tablas tiktoken locales — sin llamadas a la API.

• Trate el número como un piso: el historial de chat y los resultados de tools añaden más en runtime
• Vuelva a comprobar tras cada edición de schema o prompt
• Use LLM Token Counter cuando necesite mapas de límites o tarjetas de costo mensual sobre un payload personalizado

Síntomas: OpenAI rechaza el payload de tools, o el modelo no puede pasar argumentos que su app realmente necesita.

Por qué ocurre

Los schemas estrictos rechazan claves no declaradas. Si el JSON de ejemplo omitió un campo, nunca se convirtió en propiedad. Si el modo estricto está desactivado, los límites de structured output de OpenAI aún pueden rechazar objetos abiertos.

Diagnosticar

Compare las properties del schema inferido con los argumentos que envía su aplicación. Compruebe que el modo estricto esté activado al apuntar a structured outputs de OpenAI.

Soluciones

1. Agregue las claves faltantes al JSON de ejemplo y regenere el schema.
2. Active el modo estricto para que additionalProperties: false sea consistente en objetos anidados.
3. Acorte constructos no soportados (oneOf muy anidados, tipos exóticos) según los límites de structured output de OpenAI.
4. Reexporte tools JSON y vuelva a probar con un payload de argumentos conocido y válido.

Síntomas: errores de validación en command/url, el cliente no puede arrancar el servidor, o el transporte remoto nunca conecta.

Por qué ocurre

Entradas stdio sin command, remotas sin URLs http(s), valores env numéricos o claves de nivel superior incorrectas rompen los parsers del cliente.

Diagnosticar

Lea el JSON pointer de cada error de lint. Confirme que el envelope usa mcpServers y que cada servidor es stdio (command) o remoto (url), no un híbrido roto.

Soluciones

1. Agregue command y args para servidores stdio; cite todos los valores env como strings.
2. Use URLs http:// o https:// para transportes MCP remotos.
3. Corrija el nombre de la clave de nivel superior a mcpServers.
4. Vuelva a validar hasta que no haya errores; priorice las advertencias antes de publicar.

Síntomas: las API keys aparecen en JSON exportado, diffs de git o capturas del builder.

Por qué ocurre

Los bloques env de MCP son JSON plano. Pegar secretos de producción en una herramienta del navegador — aunque sea local — aumenta el riesgo de fuga vía portapapeles, pantalla compartida y commits accidentales.

Diagnosticar

Busque en exportaciones y el panel MCP patrones sk-, Bearer o claves de proveedor. Compruebe que las configs versionadas solo contengan marcadores de posición.

Soluciones

1. Reemplace secretos con marcadores estilo ${ENV_VAR} en el builder.
2. Inyecte valores reales solo en el cliente de escritorio local o el almacén de secretos del despliegue.
3. Rote cualquier clave que se haya pegado en chat, tickets o pantallas compartidas.
4. Agregue un escaneo de secretos pre-commit para mcp.json y archivos de bundle del agente.

Este workspace no sube su config — pero el portapapeles y git sí pueden filtrarla.

• Nunca confirme API keys en bloques env MCP — use marcadores de variables de entorno
• Use rutas absolutas de mínimo privilegio para servidores MCP filesystem
• Revise el presupuesto de tokens antes de agregar ejemplos few-shot grandes a prompts de producción
• Prefiera schemas estrictos para que las tools no acepten claves inesperadas
• Trate los bundles exportados como sensibles si contienen nombres de tools internos o hosts de infra

• Empiece desde una plantilla y luego elimine tools que no necesite — schemas más pequeños son más baratos y seguros
• Nombre tools con verbos claros (lookup_order, get_weather) que coincidan con las instrucciones del system prompt
• Mantenga una sola fuente de verdad: exporte desde este builder en lugar de mantener copias de schema divergentes
• Revalide MCP tras cada cambio de ruta o command
• Documente el presupuesto de tokens en el export markdown para que los revisores vean el impacto de costo en los PRs
• Use LLM Token Counter para diffs profundos de encoding; use este builder para el agente ensamblado