Módulo 1: Por qué operar es distinto de construir

El encargo: opera el agente de Reservo para usuarios reales

Siguiente →

Descripción

Las lecciones 01 a 06 de este módulo hicieron tres cosas: mostraron el problema (un run sin instrumentar es una caja negra), nombraron las señales que importan (error, fallo por herramienta, costo, latencia), y trazaron con precisión dónde termina lo que ya está construido y dónde empieza lo que esta guía opera. Esta lección junta las tres en un solo lugar, con la forma en que este tipo de trabajo llega en la vida real: no como una lista de conceptos, sino como un encargo, con preguntas de negocio concretas que alguien —un product owner, un gerente, el dueño de Reservo— necesita que respondas antes de dejar que usuarios reales usen el agente.

Conexión con el módulo

Este es el puente directo hacia los Módulos 2 a 8. Cada una de las cuatro preguntas del encargo de esta lección tiene un módulo específico que la responde — y verlas planteadas como preguntas de negocio, no como nombres de módulo, es lo que le da sentido a por qué esta guía está organizada en ese orden.

El encargo

Imagina que Reservo, el sistema de reservas de salas de coworking, decide abrir su agente conversacional a usuarios reales — no ya el equipo de desarrollo probando guiones, sino cualquier persona con una cuenta, escribiendo lo que se le ocurra, a cualquier hora. Antes de aprobar eso, quien dirige el producto te hace cuatro preguntas. Ninguna es un capricho técnico — cada una es exactamente el tipo de pregunta que un negocio real hace antes de confiarle tráfico real a un sistema automatizado:

Pregunta 1: "¿Cuánto nos va a costar operar esto por mes?"

Hoy no lo sabes. Como confirmó la lección 05, calcular el costo de un run ya es posible —la fórmula fija de claude-sonnet-5 más la estimación de tokens—, pero un número mensual de negocio necesita sumar el costo de todos los runs de un período, con desglose por volumen y por tipo de tarea. Eso es el Módulo 3.

Pregunta 2: "¿Va a responder rápido, o se va a sentir lento para el cliente?"

Tampoco lo sabes todavía, más allá del run individual que mediste en la lección 05. Una respuesta de negocio necesita saber qué percentil de latencia experimenta un cliente típico (no solo el promedio, que puede esconder a los clientes con la peor experiencia) y qué herramienta específica es la que más contribuye cuando algo se siente lento. Eso es el Módulo 4.

Pregunta 3: "¿Cómo sabemos si algo se rompió, sin que un cliente se queje primero?"

Esta es, en el fondo, la pregunta que motivó todo este módulo: hoy, la única forma de enterarte de que algo falló es que alguien mire history a mano, en el momento exacto en que ocurre — y ya viste, en la lección 03, que ni siquiera eso funciona cuando el run revienta por completo. Responder esta pregunta con seriedad necesita dos cosas: un registro de cada run que sobreviva más allá de la llamada individual (Módulo 2, logging estructurado y trace_id), y un gate que confirme, de forma automática, que el comportamiento del agente sigue siendo el esperado antes de que un cambio llegue a producción (Módulo 5).

Pregunta 4: "¿Qué pasa si cambiamos el prompt o agregamos una tool nueva, sin romper lo que ya funciona?"

Cambiar el sistema —un prompt nuevo, una tool nueva, un modelo distinto— es inevitable en cualquier producto que evoluciona. La pregunta de negocio no es "¿podemos cambiarlo?" —claro que sí— sino "¿cómo sabemos, con evidencia, que el cambio no rompió algo que antes funcionaba?". Eso combina tres piezas: el mismo gate de regresión de la Pregunta 3 (Módulo 5), un mecanismo que deje de insistir con una tool que empezó a fallar de forma consistente (Módulo 6), y un registro versionado que permita comparar la versión vieja contra la nueva antes de decidir si el cambio se queda (Módulo 7).

El mapa completo del encargo

PREGUNTA DE NEGOCIO                                MÓDULO QUE LA RESPONDE
────────────────────────────────────────────────────────────────────────
"¿Cuánto va a costar por mes?"                  ->  M3 -- costo por run, agregado
"¿Va a responder rápido?"                        ->  M4 -- latencia, p50/p95
"¿Cómo sabemos si algo se rompió?"               ->  M2 (observar) + M5 (gatear)
"¿Podemos cambiar algo sin romper lo que anda?"  ->  M5 + M6 (endurecer) + M7 (versionar)

TODO JUNTO, SOBRE EL AGENTE DE RESERVO COMPLETO  ->  M8 -- el capstone

Ninguna de las cuatro preguntas se puede responder con una sola señal aislada — cada una necesita, como mínimo, la disciplina completa de un módulo. Y las cuatro juntas son, literalmente, el contenido del Módulo 8: operar el mismo agente de Reservo con las cuatro capas encima, y entregar evidencia real —cuatro archivos— de que cada pregunta tiene respuesta.

Ejemplo trabajado: una mañana de tráfico real, sin guion previo

Para sentir la diferencia entre "un guion que yo escribí para probar algo" y "lo que un negocio real recibe", corre dos tareas que no aparecieron en ninguna lección anterior de esta guía — una consulta que nunca reserva nada, y una reserva de una persona y una sala nuevas:

import reservo_agent as ra

# Un cliente que solo quiere saber el precio, sin reservar nada todavía.
script_quote_only = [
    {"stop_reason": "tool_use", "content": [
        {"type": "tool_use", "id": "toolu_01", "name": "get_quote",
         "input": {"room": "Boardroom", "tier": "basic", "hours": 2}}]},
    {"stop_reason": "end_turn", "content": [
        {"type": "text", "text": "Boardroom basic 2h cuesta $160.00."}]},
]

# Un cliente nuevo, con un nombre que no apareció en ninguna lección anterior.
script_marta = [
    {"stop_reason": "tool_use", "content": [
        {"type": "tool_use", "id": "toolu_01", "name": "get_quote",
         "input": {"room": "Focus", "tier": "basic", "hours": 2}}]},
    {"stop_reason": "tool_use", "content": [
        {"type": "tool_use", "id": "toolu_02", "name": "book_room",
         "input": {"room": "Focus", "tier": "basic", "hours": 2, "member": "Marta"}}]},
    {"stop_reason": "end_turn", "content": [
        {"type": "text", "text": "Reservé Focus basic por 2 horas para Marta. Total $50.00. Confirmación #1."}]},
]

final_1, _ = ra.run_reservo_agent("¿Cuánto cuesta Boardroom basic 2h?", script_quote_only)
print("Consulta  ->", final_1["content"][0]["text"])

final_2, _ = ra.run_reservo_agent("Reserva Focus basic 2h para Marta", script_marta)
print("Reserva   ->", final_2["content"][0]["text"])

Qué esperar:

Consulta  -> Boardroom basic 2h cuesta $160.00.
Reserva   -> Reservé Focus basic por 2 horas para Marta. Total $50.00. Confirmación #1.

Boardroom basic 2h: 8000 * 2 = 16000 centavos, $160.00 — confirmado. Focus basic 2h: 2500 * 2 = 5000 centavos, $50.00 — confirmado. Dos tareas resueltas correctamente, ninguna reutilizada de una lección anterior. Este es, precisamente, el tipo de variedad que las cuatro preguntas del encargo asumen como punto de partida: nadie en Reservo va a escribir un guion de turnos a mano por cada cliente real — el guion (concepto, claude-sonnet-5) lo produce el modelo, sobre preguntas que nadie en tu equipo vio venir.

Por qué el encargo no se puede aceptar todavía

Con lo que existe hoy —el agente de agent-fundamentals, sin ninguna capa de operación encima— la respuesta honesta a las cuatro preguntas del encargo es "no lo sé, y no tengo forma de averiguarlo sin mirar cada run a mano, uno por uno". Eso no es una falla del agente — es exactamente el estado en el que cualquier sistema que resuelve tareas de varios pasos se encuentra el día antes de instrumentarlo. La diferencia entre un equipo que puede aceptar este encargo con confianza y uno que no, no está en tener un agente mejor construido — está en tener las cuatro disciplinas de esta guía encima del mismo agente. Eso es exactamente lo que los Módulos 2 a 8 construyen, uno a la vez.

Errores comunes

  1. Tratar las cuatro preguntas del encargo como si fueran una sola. Cada una necesita una disciplina distinta —costo, latencia, observabilidad+gate, versionado+endurecimiento— y confundirlas lleva a construir la capa equivocada primero. Por ejemplo, no tiene sentido intentar responder "¿qué pasa si cambiamos el prompt?" (Pregunta 4) antes de tener un gate de regresión (Pregunta 3, Módulo 5) contra el cual comparar.

  2. Pensar que basta con responder una de las cuatro para "estar listos". Un negocio real necesita las cuatro — saber el costo mensual sin saber si el sistema sigue funcionando después de un cambio es una respuesta parcial e insuficiente.

  3. Intentar responder el encargo completo en este módulo. Este módulo no responde ninguna de las cuatro preguntas a fondo — las plantea con precisión y arma el vocabulario (las señales de la lección 04) con el que los módulos siguientes sí las responden. Ese es, precisamente, el trabajo de un Módulo 1: encuadrar el problema, no resolverlo.

  4. Escribir el guion de un "cliente real" y pensar que eso ya resuelve la variedad de producción. El ejemplo trabajado de esta lección usó dos tareas nuevas, pero siguen siendo guiones escritos a mano por ti — la variedad genuina de producción viene de miles de preguntas que ningún ser humano en tu equipo escribió de antemano. Esta lección demuestra el tipo de variedad, no la reemplaza.

  5. Adelantarse a construir el circuit breaker o el versionado antes de tener observabilidad. El orden del encargo no es arbitrario: no puedes decidir con evidencia si un cambio rompió algo (Pregunta 4) sin poder medir primero (Preguntas 1 y 2) ni observar primero (parte de la Pregunta 3). Ese orden de dependencia es, literalmente, el orden de los Módulos 2 a 7.

Ejercicios

Ejercicio 1: Asigna cada pregunta a su módulo, sin mirar el mapa (Fácil)

Sin volver a mirar la sección "El mapa completo del encargo", escribe de memoria a qué módulo (2 a 7) corresponde cada una de las cuatro preguntas del encargo. Después, compara con el mapa y corrige lo que hiciera falta.

Ver solución
  1. "¿Cuánto va a costar por mes?" → Módulo 3 (costo por run, agregado sobre un lote).
  2. "¿Va a responder rápido?" → Módulo 4 (latencia, percentiles).
  3. "¿Cómo sabemos si algo se rompió?" → Módulo 2 (observar, logging + trace_id) y Módulo 5 (gatear, regresión).
  4. "¿Podemos cambiar algo sin romper lo que anda?" → Módulo 5 (el mismo gate), Módulo 6 (endurecer, circuit breaker) y Módulo 7 (versionar, comparar GO/NO-GO).

Explicación: si tu respuesta puso la Pregunta 3 solo en el Módulo 5, o solo en el Módulo 2, revisa por qué hacen falta ambos: sin el Módulo 2, no hay ningún registro de qué pasó en cada run contra el cual correr el gate del Módulo 5; sin el Módulo 5, el registro del Módulo 2 solo te dice qué pasó, nunca si eso que pasó era lo esperado.

Ejercicio 2: Escribe la quinta pregunta que Reservo debería hacer (Medio)

Las cuatro preguntas del encargo cubren costo, latencia, observabilidad+gate, y versionado+endurecimiento. Basándote en lo que aprendiste en la lección 06 sobre la frontera hacia sre-and-incident-response-guide, escribe una quinta pregunta de negocio, razonable, que Reservo debería hacer — pero que ninguna de las ocho lecciones de esta guía responde, porque pertenece a esa guía vecina.

Ver solución

Una respuesta razonable: "¿qué pasa si el servicio que expone el agente se cae por completo — si el balanceador de carga no puede repartir tráfico, o la base de datos detrás de book_room deja de responder?" Esta pregunta no la resuelve ninguna lección de esta guía porque no es una pregunta sobre el comportamiento del agente —costo, latencia de sus pasos, tasa de fallo de sus tool calls—; es una pregunta sobre la disponibilidad de la infraestructura que lo expone: SLI/SLO de un servicio, el ciclo de vida de un incidente con roles y severidades, postmortems. Esa es, con precisión, la frontera de la lección 06: sre-and-incident-response-guide.

Otras respuestas válidas: "¿cuánto tarda el servicio en recuperarse después de un despliegue fallido?", "¿tenemos alertas si la tasa de errores 5xx del servicio sube de golpe?" — todas preguntas legítimas de negocio, todas fuera del alcance de esta guía por la misma razón.

Ejercicio 3: Ordena las cuatro preguntas por dependencia, y justifica el orden (Difícil)

Las cuatro preguntas del encargo no tienen el mismo orden de urgencia que de dependencia técnica. Ordénalas según qué necesita resolverse primero para que la siguiente tenga sentido, y justifica cada paso del orden con una frase.

Ver solución

Un orden razonable, de la dependencia más temprana a la más tardía:

  1. Observabilidad (parte de la Pregunta 3, Módulo 2). Sin un registro de qué pasó en cada run, ninguna de las otras tres preguntas tiene datos sobre los cuales trabajar — no hay costo que sumar, no hay latencia que promediar, no hay comportamiento que comparar contra un gate.

  2. Costo y latencia (Preguntas 1 y 2, Módulos 3 y 4). Ambas dependen directamente de la observabilidad del paso anterior —necesitan el registro de cada run para calcular sus señales—, pero son independientes entre sí: se pueden construir en cualquier orden relativo, una respecto de la otra.

  3. El gate de regresión (el resto de la Pregunta 3, Módulo 5). Necesita que existan señales que comparar —costo, latencia, tasa de fallo— para poder fijar un umbral y decidir pass/fail; por eso depende de los pasos 1 y 2, no al revés.

  4. Endurecimiento y versionado (Pregunta 4, Módulos 6 y 7). Decidir si un cambio de prompt o una tool nueva "rompió algo" necesita, como requisito, tener ya un gate contra el cual comparar (paso 3) — no se puede decidir GO/NO-GO sin un criterio objetivo que ya exista.

Por qué ese orden: cada capa consume la salida de la anterior como su materia prima — el gate de regresión no puede evaluar nada sin señales que medir, y las señales no existen sin un registro de lo que pasó. Es exactamente el mismo principio de dependencia que la lección 01 mostró con las cuatro disciplinas (observar → medir → gatear → endurecer+versionar), ahora aplicado a las cuatro preguntas concretas del negocio.

Resumen y siguiente paso

  • Planteamos el caso completo de esta guía como un encargo de negocio: cuatro preguntas concretas —costo mensual, velocidad de respuesta, cómo detectar una rotura, cómo cambiar algo sin romper lo que funciona— que hoy no se pueden responder con el agente tal como está.
  • Ejecutamos dos tareas nuevas, no guionadas en ninguna lección anterior, para sentir el tipo de variedad que un negocio real trae — y confirmamos que el agente las resuelve correctamente, sin ningún cambio de código.
  • Mapeamos cada una de las cuatro preguntas a los módulos que la responden (M2-M7), y confirmamos, con un ejercicio de dependencia, por qué ese orden no es arbitrario: cada capa necesita la anterior como materia prima.

Siguiente lección: 08 — Mini-proyecto: envuelve un run y mira adentro. Construyes tu primera envoltura de instrumentación —costo, latencia y las cuatro señales, todas juntas— alrededor de run_reservo_agent, sobre un lote real de runs. Es la primera respuesta, todavía mínima, al encargo de esta lección.

Recursos adicionales

  1. Anthropic — Building effective agents — Sobre la brecha entre un prototipo que funciona y un sistema al que un negocio puede confiarle tráfico real.
  2. Anthropic — Tool use (function calling) overview — El protocolo sobre el que corren, sin ningún cambio, las dos tareas nuevas de esta lección.
  3. Anthropic — Pricing — La referencia de precio que va a sostener la respuesta real a la Pregunta 1 del encargo, desde el Módulo 3.
  4. Python 3.14 — What's New — La versión con la que se ejecutaron las dos tareas nuevas de esta lección.
← AnteriorOperar vs. construir: la fronteraSiguiente →Mini-proyecto: envuelve un run y mira adentro