English · Español

00 — Qué es un agente, y qué no lo es¶

🇪🇸 Un agente aquí significa una cosa precisa: un loop alrededor del modelo que mantiene estado, invoca herramientas y termina. Ni más ni menos. La palabra "agente" carga mucho hype del marketing; este capítulo recorta hasta el hueso.

Una definición operativa¶

Un agente es un loop que, en cada paso, decide si invocar una herramienta o producir una respuesta final, ejecuta esa decisión, actualiza su estado y se repite hasta terminar.

Eso es todo. Tres primitivas:

Una función de decisión (el planificador / planner).
Un mecanismo de efecto (tool calling — posiblemente produciendo observaciones).
Una condición de terminación (un paso de respuesta final, un presupuesto de pasos o un error).

Más estado: la conversación hasta ahora, resultados intermedios de herramientas, hechos persistentes. A eso lo llamaremos memoria — dividida en un scratchpad transitorio y un almacén persistente.

Esa definición encaja con los agentes de LangChain, AutoGen, el loop de function-calling de GPT-4 y el que estamos a punto de construir. Las diferencias están en la implementación, no en el concepto.

Qué no es un agente (en este proyecto)¶

Un razonador. El modelo sigue sin razonar en ningún sentido filosófico profundo — muestrea de una distribución. El envoltorio "agente" expone ese muestreo de forma estructurada (tool calling, observaciones) pero no confiere nuevas habilidades cognitivas.
Una entidad autónoma. Nuestro agente se ejecuta cuando se le invoca y termina. No tiene metas que se ponga a sí mismo, ni planificación de calendario, ni conciencia. Decir "el agente decidió llamar a la herramienta X" es una figura útil del habla, no una afirmación metafísica.
Un planificador multi-paso que compila antes de actuar. Parte de la literatura usa "agente" para sistemas que primero construyen un plan (un grafo de acciones previstas) y luego lo ejecutan. La Fase 32 usa ReAct (Yao et al. 2022): decide una acción, hazla, observa, decide la siguiente. Plan-and-execute se menciona en el lab 01 por contraste.
Un asistente general. El tutor de gramática hace una cosa: corrige conjugaciones verbales en inglés según §A13. Las peticiones fuera de alcance se rechazan, no se interpretan generosamente.

Por qué importa el loop¶

Una sola pasada hacia adelante por un transformer es una función sin estado: tokens entran, tokens salen. Las aplicaciones reales necesitan estado — "¿qué acabo de consultar?" "¿qué acaba de corregir el usuario?" "¿es este un error recurrente?". El loop es donde vive el estado:

state = init_state(user_input)
while not done:
    decision = planner(state)            # el modelo elige el siguiente movimiento
    if is_final_answer(decision):
        return decision.answer
    observation = call_tool(decision)    # el mundo produce un resultado
    state = update(state, decision, observation)

Seis líneas. Cualquier componente más allá de esto — memoria, sandboxing, restricciones del planificador, selección de herramientas — es una mejora de una de esas seis líneas.

Dos énfasis que dan forma al resto de la fase¶

Énfasis 1 — el planificador emite decisiones estructuradas, no texto libre¶

Un "agente" ingenuo le pregunta al modelo con "¿Debería llamar a una herramienta o dar una respuesta final?" y parsea la prosa resultante. Esto no es fiable para ningún modelo por debajo de 70B parámetros (y es discutible por encima). Usamos otro enfoque:

El planificador emite JSON que cumple un esquema estricto, impuesto por JSONSchemaMask (de la Fase 30). El modelo no puede producir salida inválida por construcción.

Mecanismo: en cada paso de generación de tokens calculamos qué tokens son continuaciones válidas bajo el esquema y anulamos (vía sesgo de logit \(-\infty\)) cualquier otro token. El resultado: la salida del planificador es siempre {"next": "tool_call", "tool": <enum>, "args": {...}} o {"next": "final_answer", "answer": ...}. Nunca otra cosa. Esto elimina una categoría entera de modos de fallo.

Cubrimos la técnica en la Fase 30. La Fase 32 la usa.

Énfasis 2 — el agente termina bajo recursos acotados¶

El agente tiene un presupuesto de pasos duro (típico: 8). Si lo agota sin producir una respuesta final, devuelve un resultado estructurado "no pude converger". Presupuesto de pasos + deduplicación de tool calls repetidos evitan bucles infinitos. Esta es la diferencia entre un sistema y un demo.

Mediremos los pasos medios por corrección sobre el conjunto canónico de prueba de 30 frases. Para las correcciones de verbos de §A13, \(\mu \approx 3\) pasos (parsear → buscar la forma → comprobar concordancia → responder). Si mides \(\mu > 5\) en el lab 01, tu planificador está iterando en bucle; depura.

El tutor de gramática §A13 — forma concreta¶

Entrada: una frase en inglés. Salida: un CorrectionResult (dataclass):

@dataclass
class CorrectionResult:
    original: str                         # input verbatim
    corrected: str | None                 # corrected sentence, or None if no correction
    rationale: list[str]                  # human-readable explanations (1-3 items)
    spanish_gloss: str | None             # Spanish translation, only if corrected ≠ original
    in_scope: bool                        # False if the sentence is outside §A13's verb set
    tool_trace: list[ToolCall]            # the path through tool space (for debugging)

Herramientas (de la Fase 31, servidas vía MCP; nombres canónicos según docs/phase-31-tools-mcp/lab/00-typed-tools.md):

conjugate(verb: str, tense: str, person: str) → str — devuelve la forma conjugada esperada.
lookup_irregular_verb(verb: str) → dict — partes principales más un flag is_irregular; se usa para construir el rationale.
check_subject_verb_agreement(subject: str, verb_form: str) → dict — ¿la forma concuerda con el sujeto? Devuelve {agrees, expected_form}.
lookup_spanish(english_form: str) → str — forma española emparejada para la forma inglesa conjugada.

El trabajo del agente: decidir cuál de ellas invocar, en qué orden, con qué argumentos, y cuándo parar. Eso es el bucle del agente.

Qué deberías ser capaz de hacer tras esta fase¶

Escribir el bucle del agente de memoria en 6–10 líneas.
Explicar cuándo ReAct supera a plan-and-execute y cuándo no. (Aproximadamente: ReAct para profundidades de interacción cortas y tool calling incierto; plan-and-execute cuando el plan puede calcularse barato por adelantado.)
Identificar tres modos de fallo de los bucles de agente y las mitigaciones: iteración en bucle (presupuesto de pasos + dedup), alucinación del planificador (máscara JSON schema), mal comportamiento de herramienta (sandbox).
Leer el código fuente de cualquier framework de agentes — LangChain, AutoGen, el cookbook de tool-use de Anthropic — y localizar las 6 líneas correspondientes.

Lo que este archivo NO cubre¶

Las matemáticas del decoding enmascarado del planificador. Fase 30.
El formato de cable de MCP. Fase 31.
El entrenamiento de un agente. El fine-tuning de la Fase 28 podría ajustarse sobre trazas de agente; la Fase 32 no lo hace. El entrenamiento real de agentes (p. ej., DPO sobre trayectorias de herramientas) es una de varias piezas que dejamos fuera.
Debate multi-agente, swarms, etc. Fuera de alcance.

Siguiente: 01-react-and-planning.md