Cómo construir tu primer agente de IA: un modelo, algunas herramientas y un bucle

"Agente de IA" suena como si debiera requerir un framework, una base de datos vectorial y un fin de semana de configuración. No es así. La propia definición de Anthropic es refrescantemente pequeña: un agente es un LLM que usa herramientas de forma autónoma dentro de un bucle. Una vez que ves el patrón, puedes construir un primer agente útil en bastante menos de cien líneas de código y, igual de importante, saber cuándo no deberías hacerlo.

El bucle central

Todo agente, por sofisticado que sea, es el mismo ciclo de cuatro pasos:

1. Le das al modelo un objetivo y una lista de herramientas que tiene permitido llamar.
2. El modelo decide si responde directamente o llama a una herramienta.
3. Tu código ejecuta la herramienta y le devuelve el resultado al modelo.
4. Se repite hasta que el modelo indica que ha terminado.

El modelo nunca toca por sí mismo tu sistema de archivos ni tu red. Lo único que hace es pedir ejecutar una herramienta; tu código decide si la ejecuta realmente y cómo. Esa separación es donde reside toda tu seguridad.

Un ejemplo concreto

Aquí tienes un agente mínimo que puede responder preguntas usando una herramienta de calculadora. Lo que importa es la estructura: la misma forma se escala a la edición de archivos, la búsqueda web o las consultas a bases de datos.

import anthropic

client = anthropic.Anthropic()

tools = [{
    "name": "calculator",
    "description": "Evaluate a basic arithmetic expression and return the result.",
    "input_schema": {
        "type": "object",
        "properties": {"expression": {"type": "string"}},
        "required": ["expression"],
    },
}]

def run_tool(name, args):
    if name == "calculator":
        # In real code, use a safe parser, not eval()
        return str(eval(args["expression"], {"__builtins__": {}}))
    return "unknown tool"

messages = [{"role": "user", "content": "What is 1894 * 37 plus 12?"}]

while True:
    resp = client.messages.create(
        model="claude-sonnet-4-6",
        max_tokens=1024,
        tools=tools,
        messages=messages,
    )
    messages.append({"role": "assistant", "content": resp.content})

    if resp.stop_reason != "tool_use":
        print(resp.content[0].text)
        break

    tool_results = []
    for block in resp.content:
        if block.type == "tool_use":
            result = run_tool(block.name, block.input)
            tool_results.append({
                "type": "tool_result",
                "tool_use_id": block.id,
                "content": result,
            })
    messages.append({"role": "user", "content": tool_results})

Ese bucle while es el agente. El modelo ve la pregunta, pide llamar a calculator con "1894 * 37 + 12", tu código lo ejecuta, le devuelve 70090, y el modelo escribe la respuesta final. Cambia la calculadora por un par read_file/write_file y tendrás un agente de programación rudimentario.

Las herramientas son la parte que realmente importa

El modelo es tan capaz como las herramientas que le des, y el diseño de las herramientas es donde fracasan la mayoría de los primeros agentes. Las recomendaciones de Anthropic sobre escribir herramientas para agentes se reducen a unas pocas reglas:

• Nombra y describe las herramientas como si escribieras para un nuevo compañero de equipo. search_invoices(customer_id, date_range) supera a un vago query(sql): cuanto más claro sea el contrato, menos llamadas erróneas habrá.
• Devuelve resultados con alta señal, no volcados en bruto. Si una herramienta devuelve 5000 líneas de JSON, acabas de gastar el presupuesto de contexto del modelo en ruido. Recorta a lo que es útil.
• Haz que los errores sean instructivos. "Archivo no encontrado: ¿querías decir config.yaml?" le permite al modelo recuperarse; un simple stack trace normalmente no lo hace.

Mecanismos de protección antes de dejarlo correr

Como tu código ejecuta cada llamada a herramienta, la seguridad es responsabilidad tuya. Tres mecanismos de protección que añadir antes de que cualquier agente toque algo real:

• Limita el bucle. Añade un número máximo de iteraciones para que un agente confundido no pueda dar vueltas eternamente (y disparar una factura).
• Controla las acciones destructivas. Cualquier cosa que borre, envíe o pague debería requerir confirmación o ejecutarse primero contra un entorno aislado (sandbox).
• Valida las entradas de las herramientas. Nunca uses eval() con cadenas no confiables ni pases la salida del modelo directamente a una shell. Trata cada argumento de herramienta como entrada de usuario no confiable, porque en la práctica lo es.

Cuándo NO construir un agente

Lo más útil que se puede aprender pronto: muchos problemas no necesitan un agente en absoluto. Si los pasos se conocen de antemano — obtener datos, resumirlos, enviar el resumen por correo — un simple script con una o dos llamadas al modelo es más barato, más rápido y más fácil de depurar. Anthropic los llama flujos de trabajo (workflows), y los recomienda siempre que el camino sea predecible. Recurre a un verdadero agente solo cuando el modelo realmente necesite decidir qué hacer a continuación en función de lo que encuentre.

Empieza con el bucle de cuatro pasos de arriba, dale una o dos herramientas bien descritas, limita las iteraciones y añade una tarea real. Aprenderás más de un agente que funciona que de cualquier cantidad de documentación de frameworks.