El secretario del martes

Imagínese que el martes llega un secretario a la ferretería. Es rápido, no se cansa y no cobra por hora. Doña Marta le dice: «Mijo, revise los correos, y cada vez que llegue una factura de un proveedor, sáquele los datos y me la deja anotada. Si algo le parece raro, no invente: me pregunta».

Fíjese en todo lo que doña Marta le dio sin darse cuenta:

• Una meta («que las facturas queden anotadas»), no una orden suelta.
• Unas herramientas: el correo, el cuaderno donde anota, y usted para preguntarle.
• Un límite: si algo es raro, no decida solo.

Eso es un agente. Y la palabra que mejor lo describe es la que ya usa todo el mundo: un secretario. Un consultor responde una pregunta y se calla. Un secretario recibe un encargo, sale, hace diligencias y vuelve con el resultado. Y todo lo que vamos a construir en esta lección es exactamente ese secretario, pero con reloj —porque un secretario sin reloj puede pasarse el día releyendo el mismo correo.

Los cuatro objetos sobre la mesa

Antes de escribir nada, hay que tener claras cuatro cosas. Se escriben en media hoja, a mano.

El encargo. Una frase. «De cada factura de proveedor que llegue por correo, sacar número, fecha, proveedor, NIT y total, y dejarlos anotados. Lo dudoso, a Marta.» Si no cabe en una frase, son dos encargos.

Las herramientas. Tres o cuatro, no diez. Cada una con una etiqueta que diga exactamente qué hace y cuándo no usarla. «Buscar factura por número exacto — no sirve para buscar por fechas, para eso use la otra». La caja de herramientas del secretario: cada una etiquetada. Con veinte se confunde igual que uno humano.

La carta. Las casillas que la respuesta debe llenar. Cinco: número, fecha, proveedor, NIT, total. Ni una más. Y una casilla extra que casi nadie pone y lo cambia todo: qué tan seguro está de cada dato. Porque el secretario que dice «el total es 1.850.000, y de eso estoy seguro» y el que dice «creo que es 1.850.000, la tinta estaba corrida» merecen trato distinto.

El reloj. Cuántos pasos puede dar antes de rendirse y avisar. Ocho está bien. Sin esto, un agente se puede quedar dando vueltas toda la noche.

Los prompts los escribe la IA

Aquí viene lo que a todo el mundo le da pereza y no debería: usted no escribe los prompts a mano. Se los pide a un modelo, con una plantilla de tres líneas. Es más rápido y salen mejores que los suyos y los míos.

La plantilla es siempre la misma:

Qué hace: … Qué recibe: … Qué devuelve: …

Y el encargo que se le pasa al modelo es este —cópielo tal cual y cámbiele lo suyo:

Escríbame las instrucciones (system prompt) para un asistente que hace UNA sola tarea.

Qué hace: extraer los datos de una factura de proveedor colombiana.
Qué recibe: el texto de la factura, que puede venir de un escaneo y traer errores.
Qué devuelve: solo un JSON con estas casillas: numero, fecha, proveedor, nit, total,
 y confianza (0 a 1) por cada casilla.

Reglas que quiero que queden escritas en las instrucciones:
- Si un dato no está o no se lee, la confianza de ese dato es 0. NO lo invente.
- Los montos van en pesos, como número entero, sin puntos ni comas.
- No agregue casillas que no le pedí.
- No explique nada: solo el JSON.

Escríbalo en español, en segunda persona, en menos de 150 palabras.

Lo que devuelve, se pega y se prueba. Si falla, no se reescribe a mano: se le dice al modelo «falló en esto, corrija», y se vuelve a pegar. Ese ciclo dura minutos.

Paso a paso: el agente de doña Marta

1. Escriba el encargo en media hoja. Los cuatro objetos de arriba. No siga sin esto.

2. Pida los prompts. Uno por cada cosa que el agente tiene que decidir. En este caso dos: el que clasifica («¿esto es factura, remisión o basura?») y el que extrae. Use la plantilla.

3. Escriba la carta en JSON. Es el archivo más importante del agente. La palabra clave es additionalProperties: false, que en cristiano significa «no puede inventarse casillas».

{
 "type": "object",
 "additionalProperties": false,
 "required": ["numero","fecha","proveedor","nit","total","confianza"],
 "properties": {
 "numero": {"type": "string"},
 "fecha": {"type": "string", "format": "date"},
 "proveedor": {"type": "string", "minLength": 3},
 "nit": {"type": "string"},
 "total": {"type": "integer", "minimum": 0},
 "confianza": {"type": "object"}
 }
}

4. Escriba las herramientas. Cada una es una función normal de Python: buscar el correo, guardar en la base, avisar a Marta. Nada de IA aquí. Esto es plomería.

5. Arme el bucle, con reloj. Diez líneas. El agente ve el estado, decide, la herramienta corre, el resultado vuelve, y se repite. Si se acaba el reloj, se detiene y avisa.

6. Póngale el freno de mano. Todo lo que no se pueda deshacer —registrar un pago, mandarle un correo al proveedor— no lo hace el agente. Lo deja en una lista para que Marta apruebe. Lo reversible sí lo hace solo. Esta regla es la que permite dormir tranquilo.

7. Pruébelo con veinte casos de los que usted ya sabe la respuesta. Si acierta diecinueve, va. Si acierta doce, el problema casi nunca es el modelo: es la carta o el prompt. Vuelva al paso 2.

8. Déjelo trabajando y mírele el cuaderno. Cada cosa que hizo queda anotada: qué hizo, con qué documento, cuánto tardó, qué le costó. Ese cuaderno es lo que usted le muestra al cliente.

Lo que sale mal siempre

El agente que hace de todo. «Que también me conteste los correos y me arme el inventario». No. Un agente, un encargo. Dos encargos, dos agentes.

El agente sin reloj. Se lo van a encontrar a las seis de la mañana en el paso doscientos.

El agente con permiso de firmar. Nada irreversible sin una persona. Nunca.

El agente al que se le pide texto libre. «Dígame qué encontró» produce párrafos distintos cada vez y un programa que se cae. Casillas, siempre.

La trastienda

El bucle mínimo, con presupuesto duro:

def agente(modelo, herramientas, meta, max_pasos=8):
 ctx = [{"rol":"sistema","texto":INSTRUCCIONES}, {"rol":"usuario","texto":meta}]
 for _ in range(max_pasos):
 d = modelo(ctx, herramientas) # → {"tipo":"texto"|"tool", ...}
 if d["tipo"] == "texto":
 return d["texto"]
 ctx.append({"rol":"tool","texto":str(ejecutar(d["tool"], d["args"]))})
 return "PRESUPUESTO AGOTADO — requiere revisión humana"

Presupuestos que se ponen en producción: pasos_max 6–10 · tokens_max ~20 000 por tarea · segundos_max 120. Al superarlos: estado fallida con motivo, nunca «un paso más».

Contrato entre roles: JSON con tarea_id, identificadores (no contenidos), campos, confianza y origen{rol, modelo, version}. Umbral de confianza inicial 0,8 → por debajo, cola humana.

Ver módulos 5.2 (esquemas), 10.3 (máquina de estados), 10.4 (contratos y aprobación), 12 (evals).