Nº 5 · Manos a la obra
Un agente desde cero, en 60 líneas de Python
Sin frameworks: un modelo, dos herramientas y un bucle. Construimos un agente que lee tus notas de reuniones para entender qué es, por dentro, eso que llamamos agente.
Por Data Sirens Lectura de 5 minutos
Se habla de agentes como si fueran una tecnología nueva y misteriosa. Por dentro son sorprendentemente simples: un modelo de lenguaje, unas cuantas funciones que puede pedir que ejecutes y un bucle que repite «pregunta al modelo, ejecuta lo que pide, devuélvele el resultado» hasta que el modelo da la tarea por terminada.
En este artículo escribimos ese bucle a mano, sin ningún framework, para que no quede nada escondido. El agente responde preguntas sobre una carpeta de notas de reuniones: «¿qué quedó pendiente esta semana?», «¿quién se comprometió a enviar el presupuesto?».
Lo que necesitas: Python 3.10 o posterior, una clave de la API de Anthropic y la biblioteca oficial:
pip install anthropic
export ANTHROPIC_API_KEY="tu-clave"
mkdir notas # y deja dentro unos cuantos .md con notas de reuniones
Las herramientas: lo que el agente puede hacer
Un modelo de lenguaje solo produce texto. Para que actúe, le describimos funciones que puede pedirnos que ejecutemos. La descripción tiene tres partes: un nombre, una explicación en lenguaje natural y un esquema JSON con los parámetros.
import json
from pathlib import Path
import anthropic
client = anthropic.Anthropic() # usa la clave de ANTHROPIC_API_KEY
NOTAS = Path("notas").resolve()
herramientas = [
{
"name": "listar_notas",
"description": "Lista los archivos de la carpeta de notas.",
"input_schema": {"type": "object", "properties": {}},
},
{
"name": "leer_nota",
"description": "Devuelve el texto completo de una nota.",
"input_schema": {
"type": "object",
"properties": {
"nombre": {"type": "string", "description": "Por ejemplo, 'lunes.md'"}
},
"required": ["nombre"],
},
},
]
La parte más importante del listado 2 no es el código, son las descripciones. El modelo no ve nuestras funciones: solo ve estos textos y decide a partir de ellos cuándo usar cada herramienta y con qué argumentos. Una descripción ambigua produce un agente torpe, igual que unas instrucciones ambiguas producen un empleado torpe.
Ejecutar lo que pide
Cuando el modelo quiere usar una herramienta, no la ejecuta él: nos devuelve el nombre y los argumentos, y somos nosotras quienes la ejecutamos. Esto es lo que lo hace controlable.
def ejecutar(nombre, entrada):
if nombre == "listar_notas":
return "\n".join(p.name for p in NOTAS.glob("*.md")) or "(no hay notas)"
if nombre == "leer_nota":
ruta = (NOTAS / entrada["nombre"]).resolve()
if ruta.parent != NOTAS:
raise ValueError("solo puedo leer archivos de la carpeta de notas")
return ruta.read_text()
raise ValueError(f"herramienta desconocida: {nombre}")
Fíjate en la comprobación de la ruta. Sin ella, el modelo podría pedir ../../.ssh/id_rsa y nuestra función lo leería obedientemente. Puede que el modelo nunca lo pida por sí mismo, pero si alguna de las notas contiene texto escrito por otra persona, ese texto puede pedírselo: es la inyección de instrucciones que explicamos en la trifecta letal. Los límites de un agente se ponen en el código de sus herramientas, no en el prompt.
El bucle
Y esto es el agente:
def agente(pregunta):
mensajes = [{"role": "user", "content": pregunta}]
while True:
respuesta = client.messages.create(
model="claude-opus-5-5",
max_tokens=16000,
tools=herramientas,
messages=mensajes,
)
mensajes.append({"role": "assistant", "content": respuesta.content})
if respuesta.stop_reason != "tool_use":
return "".join(b.text for b in respuesta.content if b.type == "text")
resultados = []
for bloque in respuesta.content:
if bloque.type != "tool_use":
continue
print(f"→ {bloque.name} {json.dumps(bloque.input, ensure_ascii=False)}")
try:
salida, error = ejecutar(bloque.name, bloque.input), False
except Exception as e:
salida, error = f"Error: {e}", True
resultados.append({
"type": "tool_result",
"tool_use_id": bloque.id,
"content": salida,
"is_error": error,
})
mensajes.append({"role": "user", "content": resultados})
if __name__ == "__main__":
print(agente("¿Qué quedó pendiente en las reuniones de esta semana?"))
Merece la pena leer el listado 4 despacio, porque contiene casi todo lo que hay que saber sobre agentes:
- El modelo no tiene memoria. En cada vuelta le enviamos la conversación entera: la pregunta, lo que respondió, los resultados de las herramientas. Lo que el agente «recuerda» es lo que hay en
mensajes. - El modelo decide cuándo parar. Si su respuesta termina con
stop_reasonigual a"tool_use", quiere que ejecutemos algo; si no, ha terminado. El bucle no tiene un número fijo de pasos. - Puede pedir varias herramientas a la vez. Una respuesta puede traer varios bloques
tool_use, y devolvemos todos los resultados juntos, cada uno con eltool_use_iddel bloque al que responde. - Los errores también son información. Si una herramienta falla, no rompemos el bucle: le devolvemos el error con
is_errory el modelo suele corregirse solo, por ejemplo pidiendo primero la lista de notas para ver qué nombres existen.
Al ejecutarlo verás algo así:
→ listar_notas {}
→ leer_nota {"nombre": "lunes.md"}
→ leer_nota {"nombre": "miercoles.md"}
Esta semana quedaron dos tareas pendientes: Ana tiene que enviar el
presupuesto revisado (reunión del lunes) y falta fijar la fecha de la
demo con el cliente (reunión del miércoles).
Nadie le dijo que listara primero y leyera después, ni cuántas notas leer. Lo decidió el modelo a partir de la pregunta y de las descripciones de las herramientas. Esa es toda la diferencia entre un programa y un agente.
Lo que falta para producción
Estas 60 líneas son un agente de verdad, pero no uno que pondríamos delante de usuarios sin más. Lo que le falta dice mucho sobre dónde está el trabajo real:
| Falta | Por qué importa |
|---|---|
| Límite de vueltas | Un agente confundido puede entrar en bucle y gastar sin fin |
| Registro de cada paso | Sin él, no sabrás por qué respondió lo que respondió |
| Conjunto de preguntas de prueba | Para saber si un cambio en las descripciones lo mejora o lo empeora |
| Gestión del contexto | Con muchas notas, la conversación crece hasta no caber |
| Confirmación humana | Imprescindible en cuanto alguna herramienta escriba o envíe |
La biblioteca de Anthropic incluye un tool runner que implementa este mismo bucle por ti, y existen frameworks que añaden mucho más. Úsalos. Pero conviene haber escrito el bucle a mano una vez: cuando un agente haga algo raro, sabrás exactamente dónde mirar.