Crear el primer agente: la configuración mínima y el bucle

💡 Lo único que lo diferencia de «una sola llamada a la API» es el bucle. Si solo preguntas una vez al LLM y recibes su respuesta, eso es simple uso de una API. En el momento en que le añades esa repetición —«ejecutar la herramienta, devolver el resultado y hacerle pensar otra vez»—, se convierte en un agente. En esencia, lo único que crece es ese bucle. Por eso, entenderlo por completo primero es el camino más corto.

# Bucle mínimo del agente (pseudocódigo)
messages = [ user("Investiga la temperatura media del mes pasado y resúmela") ]

while True:
    reply = llm.think(messages, tools=[search_tool])   # PASO1 pensar

    if reply.wants_tool:                              # ¿pide herramienta?
        result = run_tool(reply.tool_name, reply.args) # PASO2 invocar
        messages.append(assistant(reply))
        messages.append(tool_result(result))           # PASO3 devolver
    else:
        return reply.text                             # PASO4 detenerse al completar

⚠️ Pon siempre un número máximo de vueltas. El pseudocódigo de arriba usa while True solo para explicar, pero en un caso real siempre metemos un freno de «hasta un máximo de N vueltas». El bucle infinito en el que el LLM sigue invocando herramientas sin parar es un accidente que, de hecho, ocurre a menudo. Lo tratamos en detalle en Puntos donde se atasca.

# ① y ② … definición de herramienta que pasas al LLM
search_tool = {
    "name": "search_weather",
    "description": "devuelve la temperatura media (°C) si le pasas una ciudad y un mes",
    "input_schema": {
        "city":  "string",
        "month": "number",
    },
}

# ③ … la función real que te quedas. Solo una función
def run_tool(name, args):
    if name == "search_weather":
        return weather_db.lookup(args["city"], args["month"])
    return "unknown tool"

📊 La descripción es parte del prompt. La description de la herramienta es la única pista que tiene el LLM para decidir «cuándo usarla». Si es ambigua, no la usará o la usará en momentos raros. El truco es escribirla como si le explicaras a una persona «qué devuelve y cuándo debe usarse». El diseño de herramientas lo profundizamos aún más en el siguiente capítulo, con MCP.

# A. Bucle a mano (pseudocódigo / estilo de mensajes de Claude)
messages = [ user(goal) ]

for step in range(MAX_STEPS):          # ← freno con el límite
    reply = client.messages.create(
        model="claude-…",
        messages=messages,
        tools=[search_tool],
    )
    log(step, reply)                       # ← registra siempre, para observar

    if reply.stop_reason == "tool_use":
        out = run_tool(reply.tool_name, reply.tool_args)
        messages += [ assistant(reply), tool_result(out) ]
    else:
        break                              # salió la respuesta final → fin

# B. Delegar en el tool runner del SDK (pseudocódigo)
runner = ToolRunner(
    model="claude-…",
    tools=[search_tool],       # definición
    handlers={"search_weather": run_tool},  # función real
)
answer = runner.run(goal)      # el bucle gira por dentro

💡 Los nombres exactos de los métodos, en la documentación oficial. Aquí, client.messages.create y ToolRunner son pseudocódigo para transmitir la idea. Los nombres reales de los argumentos, la forma de los valores de retorno y los ID de modelo difieren en cada SDK y se actualizan con frecuencia, así que consulta siempre la versión más reciente en la documentación oficial. Primero captar el concepto y luego rellenar los detalles con la documentación: esa es la forma de no dar rodeos. Como introducción paso a paso, consulta también Cómo crear un agente de IA (introducción).

✅ Los registros no son una «función de lujo», sino imprescindibles desde el principio. Como el interior de un agente es difícil de ver, sin registros no entiendes en absoluto «por qué actuó así». De momento basta con una línea de print. La evaluación y la observabilidad, que sistematizan esta observación, las tratamos en serio en el capítulo 5. Por ahora, adquiere aquí el «hábito de mirar».

📊 Los tres son problemas de «diseño del contexto». El bucle infinito, el inflado del valor de retorno y el inflado del contexto: la raíz de todos llega al diseño del contexto, es decir, «qué y cuánto le pasas al LLM». Este enfoque está sistematizado como ingeniería de contexto y es la columna vertebral del desarrollo de agentes. Para empezar, ten como lema «no pasar de más ni acumular de más».

• El agente mínimo = los 4 elementos montados en su forma más pequeña. Lo único que lo diferencia de un uso único de la API es el bucle.
• El bucle repite una vuelta de «pensar → invocar la herramienta → devolver el resultado → volver a pensar → detenerse al completar». El freno del número máximo de vueltas es imprescindible.
• De la herramienta, pasas la definición (nombre, descripción, argumentos) al LLM, y la función real la ejecutas en tu lado. El LLM solo la pide.
• La implementación tiene 2 formas: bucle a mano (para aprender) y tool runner del SDK (para la práctica). Por dentro son lo mismo.
• Desde el principio, observa con registros y detecta los atascos clásicos: bucle infinito, inflado del valor de retorno e inflado del contexto.