Cómo construir tu propio agente de IA

Un agente de IA no es un “prompt más grande”. Es un bucle: el modelo recibe un objetivo, elige una herramienta, la ejecuta, lee el resultado y decide qué hacer a continuación, hasta que da la tarea por terminada. El resto de este artículo es una guía para construir ese bucle desde cero, con un ejemplo concreto: un agente que hace triage de issues en GitHub. Si estás construyendo tu primer agente, léelo en orden: cada sección es una decisión que vas a tener que tomar de todos modos.

Cómo elegir el modelo y el SDK

Primero, separa dos cosas: el modelo (razonamiento, function calling) y la orquestación (bucle, estado, reintentos). Los modelos son intercambiables, así que no te cases con uno demasiado pronto.

• Claude Agent SDK: si quieres un bucle listo, gestión de herramientas y MCP de serie. Es lo que menos boilerplate exige para empezar.
• OpenAI (Responses / Agents API): tooling maduro, buena opción para equipos que ya están metidos en ese ecosistema.
• LangGraph: cuando necesitas un grafo de estados explícito, ramificaciones y control total del flujo. Más potencia, más código.

Recomendación para un primer agente: empieza con el SDK del proveedor del modelo (Claude u OpenAI), no con un framework de grafos. Añade el grafo cuando de verdad aparezcan ramificaciones. Adoptar LangGraph antes de tiempo supone mucha abstracción que todavía no necesitas.

Las herramientas y su esquema para function calling

Una herramienta es una función más la descripción que lee el modelo. El modelo nunca ve tu código: solo ve el nombre, la descripción y el esquema de parámetros (JSON Schema). Esa es tu verdadera interfaz, y la escribes para el modelo, no para una persona.

Reglas de diseño de herramientas que te ahorrarán muchas iteraciones:

• Un nombre con verbo y sin ambigüedades: get_issue, add_label, post_comment. Nada de process ni handle.
• La descripción dice cuándo usar la herramienta y cuándo no. Una sola frase sobre “lo que no hace” elimina la mitad de las llamadas erróneas.
• Parámetros acotados y tipados. En lugar de un query libre, ofrece un enum con las etiquetas permitidas. El modelo alucina menos cuando el conjunto de opciones es finito.
• Cada descripción de campo del esquema es un mini prompt. Un label sin descripción obliga a adivinar; un label con “una de las etiquetas que ya existen en el repo” es un contrato.
• Pocas herramientas, cada una con una sola función. Cinco herramientas precisas ganan a quince difusas. A partir de veinte, al modelo le empieza a costar elegir.

El resultado de una herramienta también es un prompt. Devuelve texto conciso y estructurado, no un volcado de JSON en bruto de la API. Si la respuesta ocupa 8000 tokens, el agente los paga en cada turno posterior del bucle. Filtra a nivel de herramienta.

El bucle del agente

El núcleo es un bucle sencillo que vale la pena entender aunque el SDK lo oculte:

1. Envía los mensajes al modelo (system + historial + objetivo).
2. El modelo responde con texto o con una petición de tool call.
3. Si es una tool call: ejecuta la función y añade el resultado como mensaje de herramienta.
4. Vuelve al paso 1 con el resultado adjunto.
5. Detente cuando el modelo devuelva un texto final sin tool call.

Tres salvaguardas que lamentarás haberte saltado: un límite estricto de iteraciones (por ejemplo, 10), porque el modelo puede entrar en bucle; un timeout para toda la ejecución, porque una herramienta puede quedarse colgada; y tratar un error de herramienta como datos: no lances la excepción hacia arriba, devuélvele al modelo “la herramienta devolvió un 404” para que pueda reaccionar. Es una de las mayores diferencias entre una demo y un agente en producción.

System prompt y estrategia de contexto

El system prompt es la constitución del agente. Debe recoger el rol y el objetivo, las herramientas disponibles con sus reglas de uso, el formato de respuesta y límites explícitos (“nunca cierres un issue sin etiqueta”). Mantenlo estable y versiónalo como si fuera código: cambiar una sola frase puede alterar el comportamiento en toda la población de llamadas.

El contexto es un presupuesto, no un almacén. Que la ventana sea más grande no significa que debas llenarla.

• Instrucciones estáticas: en el system prompt, una sola vez, al principio.
• Datos de la tarea: los aportan las herramientas bajo demanda, no se inyectan por si acaso.
• Historiales largos: compáctalos. Tras unos cuantos turnos, resume los más antiguos en lugar de arrastrar toda la transcripción.
• Prompt caching: actívalo para la parte estable (system + definiciones de herramientas). Reduce de verdad el costo y la latencia cuando hay muchos turnos.

Memoria: estado y vectores

Separa tres niveles; confundirlos es un error clásico del primer agente:

• Estado de la tarea: lo que ocurre en el bucle actual. Vive en los mensajes y en una variable normal. No necesita base de datos.
• Memoria persistente: hechos que se conservan entre ejecuciones (preferencias, decisiones). Un almacén clave-valor o una simple tabla de Postgres. Lo simple gana.
• Conocimiento: un gran conjunto de documentos en el que buscar (vectores, RAG). Recurre a los vectores solo cuando los hechos ya no caben en el contexto.

No empieces con un vector store porque “un agente tiene que tener memoria”. La mayoría de los primeros agentes necesitan una tabla, no una infraestructura de embeddings. Añade vectores cuando la ventana de contexto se te quede pequeña de verdad.

Cómo añadir servidores MCP

MCP (Model Context Protocol) es un estándar para conectar a un agente conjuntos de herramientas ya hechos sin tener que escribirlos desde cero. En lugar de programar a mano una integración con GitHub, conectas un servidor MCP que expone herramientas como endpoints.

• Servidores listos para usar: GitHub, Slack, bases de datos, el navegador. Menos código de integración.
• Cada servidor MCP es una superficie de confianza. Trata su salida como datos no confiables: nunca ejecutes instrucciones incrustadas en el contenido que devuelve.
• Expón solo las herramientas que el agente necesita. Un servidor con 60 herramientas inunda la ventana de contexto con sus descripciones y empeora la precisión al elegir.

Ejemplo práctico: triage de issues en GitHub

Juntamos todas las piezas. El objetivo del agente: para cada issue nuevo, asignar etiquetas, evaluar la prioridad y dejar un comentario que ponga orden, sin cerrar nada.

1. Herramientas: get_issue (cuerpo + metadatos), list_labels (etiquetas permitidas del repo), add_label (enum a partir de esa lista), post_comment. No hay herramienta para cerrar: el agente no tiene forma de hacer lo que no le permites.
2. System prompt: “Te encargas del triage de issues. Asigna siempre exactamente una etiqueta de tipo (bug/feature/question) y, opcionalmente, un área. Nunca cierres un issue. Si falta información, pídela en un comentario.”
3. Bucle: el modelo llama a get_issue, después a list_labels, elige una etiqueta, llama a add_label, redacta un comentario, llama a post_comment y termina con un texto de resumen.
4. Guardrail: add_label valida que la etiqueta esté en la lista que devuelve el repo. Una etiqueta alucinada como “needs-triage-v2”, que no existe, se rechaza con un error claro y el modelo vuelve a intentarlo.
5. Aprobación humana: en los issues etiquetados como security, el agente no comenta en público: crea un borrador para que alguien lo apruebe manualmente.

El mismo esqueleto se adapta a otros dominios. Cambias las herramientas y el system prompt; el bucle, los guardrails y la memoria se quedan.

Evals, tracing y observabilidad

Sin evals no sabes si un cambio en el prompt ha ayudado o ha roto algo. Esa es la diferencia entre hacer ingeniería y hacer conjeturas.

• Reúne 20-50 casos reales con su resultado esperado (por ejemplo, issue → etiqueta correcta). Ese es tu conjunto de regresión.
• Mide cosas concretas: precisión de las etiquetas, turnos hasta completar la tarea y porcentaje de llamadas a herramientas que terminan en error.
• Traza cada turno: entrada, herramienta elegida, resultado, decisión. Sin trazas, depurar un agente es como consultar una bola de cristal.
• Cada cambio de prompt pasa por el conjunto de evals antes de publicarse. Es un filtro obligatorio, no una sugerencia.

Costo, latencia y guardrails

El costo de un agente crece con el número de turnos, porque cada turno arrastra el contexto acumulado. Las palancas de control:

• Un modelo más barato para los pasos sencillos y el más potente solo para la decisión difícil (enrutamiento de modelos).
• Prompt caching en la parte estable: una de las mejoras más baratas.
• Un límite de iteraciones y un presupuesto de tokens por ejecución, con un interruptor de emergencia.
• Resultados de herramientas concisos: no pagues 8000 tokens de JSON en cada turno.

Los guardrails no son un extra opcional; son la condición para llevar un agente más allá de la demo:

• Valida los argumentos de las herramientas (Zod / JSON Schema) antes de que se ejecute nada.
• Acciones destructivas (borrar, enviar, pagar) detrás de una aprobación humana o de un dry-run.
• Una lista de herramientas y dominios permitidos: el agente no va más allá de lo que se permite de forma explícita.
• Trata cada resultado de herramienta y cada respuesta de API como una entrada no confiable.

Desplegarlo como servicio

Un agente en producción es un servicio, no un script. Oculta el bucle detrás de un endpoint (HTTP o una cola), porque las ejecuciones pueden ser largas. Para tareas de más de unas decenas de segundos, usa una cola y un webhook: no mantengas abierta una conexión HTTP. Las claves y los secretos salen únicamente de variables de entorno. Registra cada turno (con los datos personales enmascarados), añade alertas sobre el costo por petición y la latencia p99, y prepara un interruptor de emergencia para toda la población. Versiona el prompt y las definiciones de herramientas junto con el código para que cada rollback sea determinista.

TL;DR

Un agente es un bucle: el modelo elige una herramienta, la ejecuta, lee el resultado y decide el siguiente paso. Empieza con el SDK del proveedor del modelo, no con un framework de grafos. Diseña pocas herramientas precisas, con buenas descripciones y un esquema acotado. Trata el contexto como un presupuesto, no como un almacén. Divide la memoria en estado, hechos y conocimiento; vectores solo cuando de verdad los necesites. Construye evals y tracing desde el primer día, y deja las acciones destructivas detrás de una aprobación humana. Despliégalo como servicio, con logs, límites de costo y un interruptor de emergencia.