DEV Community: Xavier Gutiérrez

Agentes 101 - 02: El ciclo del agente como State Machine (y Hierarchical State Machines)

Xavier Gutiérrez — Sun, 26 Jul 2026 15:09:16 +0000

En el artículo anterior definimos un agente de forma práctica:

Un agente LLM es un modelo dentro de un ciclo donde puede razonar, actuar, observar el resultado y decidir qué hacer después.

Esa definición es correcta. Pero todavía es demasiado abstracta.

Hoy mucha gente está construyendo agentes con vibe coding. Le pide al modelo que le arme un agente, copia el código y sigue. Los modelos actuales son realmente buenos escribiendo código, y eso hace que el proceso se sienta mágico.

El problema es que muchas veces se termina implementando algo sin entender los conceptos base.

Y cuando no se entienden los conceptos, el modelo puede proponer soluciones más complejas de lo necesario. Por ejemplo, sugerirte una Hierarchical State Machine cuando una Finite State Machine simple habría sido más que suficiente (y capaz ni siquiera te das cuenta de que es una FSM o HSM)..

Por eso este artículo.

No para complicar las cosas, sino para tener claridad sobre qué estamos construyendo realmente.

La pregunta central es:

¿Cómo modelamos el ciclo de un agente de forma explícita, controlable y escalable?

La respuesta es: tratarlo como una máquina de estados.

El ciclo Think Act Observe como máquina de estados

Imaginemos el flujo más simple de un agente:

Recibe una tarea
Razona sobre qué hacer
Decide si necesita usar una herramienta
Ejecuta la herramienta
Observa el resultado
Decide si terminó o si debe seguir

Ese flujo se puede modelar perfectamente como una Finite State Machine (FSM):

Estado	Descripción
`'thinking'`	El modelo está razonando
`'acting'`	Está ejecutando una herramienta
`'observing'`	Está procesando el resultado
`'done'`	Terminó la tarea
`'error'`	Algo falló

Las transiciones dependen del resultado de cada paso.

Eso es exactamente lo que hace un agente.

Una State Machine simple

Aquí un ejemplo conceptual (pseudo-código):

state = {
    "task": "Implementar CORS en API Gateway con CDK",
    "code": "",
    "last_observation": None,
    "status": "thinking"
}

while state["status"] not in ["done", "error"]:
    if state["status"] == "thinking":
        decision = llm.think(state)
        if decision.needs_tool:
            state["status"] = "acting"
            state["next_tool"] = decision.tool
        else:
            state["status"] = "done"
            state["final_answer"] = decision.answer

    elif state["status"] == "acting":
        result = run_tool(state["next_tool"], state)
        state["last_observation"] = result
        state["status"] = "observing"

    elif state["status"] == "observing":
        # El modelo decide qué hacer con la observación
        next_action = llm.observe(state)
        state["status"] = next_action  # puede ser "thinking", "done", "error"...

Este patrón es el corazón de casi todos los frameworks de agentes.

La diferencia está en qué tan explícito se hace el control del estado.

Tools = acciones que cambian el estado

Las herramientas no son un "extra".

Son acciones que producen una observación y, por lo tanto, cambian el estado de la máquina.

Cuando el agente llama a search_docs o run_tests, lo que realmente está haciendo es:

Salir del estado thinking
Entrar al estado acting
Ejecutar una acción
Recibir una observación
Actualizar el estado
Decidir la siguiente transición

Si pensamos las tools de esta forma, el diseño se vuelve mucho más claro:

Una tool bien diseñada tiene un contrato claro de entrada/salida. El resultado de la tool debe poder interpretarse para decidir la siguiente transición.
El manejo de errores de tools se convierte en transiciones hacia el estado error o hacia un estado de recuperación.

Cuando la máquina se complica: Hierarchical State Machines

Una FSM plana funciona bien para agentes simples.

Pero cuando el agente crece, empiezan a aparecer problemas:

Demasiados estados
Transiciones difíciles de seguir
Lógica de "modo investigación" mezclada con "modo implementación"
Dificultad para reutilizar partes del flujo

Aquí es donde aparecen las Hierarchical State Machines (HSM).

La idea es simple: un estado puede contener otra máquina de estados completa.

Ejemplo:

resolver_tarea (estado de alto nivel)
├── investigar
│   ├── buscar_documentación
│   ├── analizar_código_existente
│   └── sintetizar_hallazgos
├── implementar
│   ├── escribir_código
│   └── correr_tests
│   └── corregir_errores
└── validar
    ├── revisar_calidad
    └── generar_respuesta_final

Cada sub-máquina tiene su propio estado interno, pero el padre solo ve el resultado agregado.

Esto es exactamente cómo trabaja un desarrollador humano experimentado: no piensa en cada detalle al mismo tiempo. Entra en "modo investigación", luego en "modo implementación", etc.

Cómo lo implementa LangGraph

LangGraph es, en la práctica, una de las implementaciones más limpias de este enfoque.

1. StateGraph = la máquina de estados

from typing import TypedDict
from langgraph.graph import StateGraph, START, END

class AgentState(TypedDict):
    task: str
    messages: list
    code: str
    status: str

builder = StateGraph(AgentState)

El State es el estado compartido.
Los nodes son las funciones que actualizan el estado.
Las edges (especialmente las condicionales) definen las transiciones.

2. Subgraphs = Hierarchical State Machines

LangGraph permite meter un grafo completo como nodo de otro grafo.

Eso es literalmente una Hierarchical State Machine.

Hay dos patrones principales:

Patrón A - Shared State

El subgraph y el parent comparten claves del estado.

# El subgraph se agrega directamente como nodo
builder.add_node("investigar", investigar_subgraph)

Patrón B - Isolated State

Cada subgraph tiene su propio schema y se hace una transformación explícita.

def call_investigar(state: AgentState):
    subgraph_input = {"query": state["task"]}
    result = investigar_subgraph.invoke(subgraph_input)
    return {"code": result["findings"]}

Además, LangGraph gestiona checkpoint namespaces por subgraph, lo que permite:

Aislar el estado de cada sub-máquina
Recuperar el estado después de fallos
Hacer human-in-the-loop a nivel de sub-proceso

Esto es extremadamente poderoso cuando pasamos de demos a sistemas reales.

¿Cuándo vale la pena formalizarlo?

Situación	Recomendación
Prototipo/demo rápida	Loop simple suele alcanzar
Agente con pocas tools	FSM plana
Agente con modos claros	HSM (subgraphs)
Multi-agente / equipos	HSM + supervisor
Producción con observabilidad	State machine explícita

No hay que formalizar todo desde el día uno.

Pero cuando el flujo empieza a volverse difícil de seguir, convertir el ciclo en una máquina de estados (y eventualmente jerárquica) suele ser el siguiente paso natural.

Y aquí vuelve el punto del principio: si no tenés claros estos conceptos, es fácil que el modelo te proponga una HSM cuando en realidad necesitabas una FSM simple. O al revés.

Conclusión

El ciclo Think Act Observe no es solo una metáfora.

Es una máquina de estados.

Las Hierarchical State Machines nos permiten escalar esa idea sin que el sistema se convierta en un laberinto de ifs y prompts.

Y frameworks como LangGraph nos dan las primitivas exactas para implementarlo de forma limpia: StateGraph + Subgraphs.

Resumen:

Un agente no es solo un modelo con tools.

Es un modelo operando dentro de una máquina de estados (que puede ser jerárquica).

Entender esto cambia bastante la forma en que diseñamos, debuggeamos y operamos agentes.

Agentes 101 - 01

Xavier Gutiérrez — Sat, 25 Apr 2026 19:32:24 +0000

¿Qué es realmente un agente LLM?

Llevo tiempo queriendo escribir sobre agentes. No porque el tema sea nuevo, sino porque cada vez que parece que empezamos a entenderlo, cambia el nivel de abstracción con el que se habla de él.

Y ahí empieza buena parte del problema.

Hoy una persona dice “agente” y se refiere a un sistema con tools, memoria, planificación y control de estado. Otra usa la misma palabra para hablar de un prompt bien diseñado dentro de un archivo .md. Y otra simplemente la usa para describir cualquier flujo donde un modelo hace más de un paso.

Mientras tanto, la adopción en empresas tampoco ocurre al mismo ritmo. Algunas organizaciones todavía están evaluando asistentes de código en grupos pequeños. Otras ya probaron varias herramientas, cambiaron de enfoque más de una vez y ahora están intentando separar qué fue entusiasmo, qué fue utilidad real y qué sí puede sostenerse en producción.

Por eso, cuando en una conversación aparece la pregunta:

¿Qué es un agente?

casi nunca hay una sola respuesta.

Y el problema no es que falten definiciones. El problema es que muchas definiciones son correctas, pero se quedan demasiado arriba y no siempre ayudan a entender qué está pasando en la práctica.

La respuesta corta

Una definición razonable sería esta:

Un LLM común genera texto a partir de su entrenamiento.

Un agente LLM es ese mismo modelo dentro de un ciclo donde puede razonar, usar herramientas, recibir feedback y ajustar su siguiente acción.

Dicho de otra forma:

LLM + tools + memory + planning = agente

No está mal. De hecho, es una buena síntesis.

Pero también es el tipo de respuesta que muchas personas escuchan, entienden de forma parcial y luego repiten sin terminar de visualizar qué significa realmente.

Así que conviene detenerse un poco más.

Una definición más útil

La forma que más me convence de explicarlo es esta:

Un agente LLM es un LLM dentro de un workflow iterativo donde puede razonar, actuar y usar el resultado de sus acciones para decidir qué hacer después.

Ese matiz importa.

Porque el centro de la idea no está solo en el modelo, sino en el ciclo en el que ese modelo opera.

No es magia.

No es una categoría mística de software.

Es un sistema con estructura.

Visual general

La analogía más simple: un desarrollador humano

Una buena forma de aterrizarlo es compararlo con el trabajo cotidiano de un desarrollador.

Fase humana	Equivalente del agente
Recibe un requerimiento	Recibe un prompt o una task
Piensa cómo abordarlo	Razona sobre el problema
Busca documentación, prueba opciones, escribe código	Usa tools
Ejecuta, valida y corrige	Actúa sobre el entorno
Ve errores, resultados o confirmaciones	Recibe feedback
Ajusta el enfoque	Decide el siguiente paso

Eso es lo que hace que la idea deje de sonar abstracta.

Un agente no es más que un modelo participando en algo que se parece bastante a un ciclo real de trabajo:

analizar
actuar
observar
corregir

La diferencia es que, en lugar de hacerlo con navegador, terminal, editor y pruebas como lo haría una persona, lo hace a través de herramientas conectadas al sistema.

Entonces, ¿de dónde sale tanta confusión?

De que hoy la palabra agente se usa para hablar de cosas bastante distintas.

Hay personas que dicen “creé un agente” y, cuando miras más de cerca, en realidad lo que construyeron fue un archivo .md con instrucciones muy claras para que Claude Code, Cursor u otra herramienta se comporte de cierta manera.

Y eso no está mal.

De hecho, muchas veces ese archivo contiene una parte valiosa del diseño:

el rol
las reglas
las restricciones
el criterio de calidad
la forma de decidir entre opciones

El problema aparece cuando esa pieza se confunde con el sistema completo.

Un .md puede definir comportamiento. Puede incluso capturar muy bien la intención del flujo. Pero, por sí solo, normalmente no resuelve aspectos fundamentales como:

ejecución de herramientas
control de estado
manejo de errores
límites operativos
observabilidad
validación
integración con otros sistemas

Por eso, más que decir “eso sí es un agente” o “eso no es un agente”, creo que la distinción más útil es esta:

Un archivo de instrucciones puede ser una parte importante del agente, pero no suele ser suficiente para representar todo el sistema.

Esa diferencia parece pequeña, pero cambia mucho la conversación.

Veamos un ejemplo en código

Para hacerlo más tangible, le pedí a ChatGPT que generara un ejemplo sencillo usando strands-agents, el framework de AWS:

from strands import Agent, Tool

# --- Tools (simuladas) ---
def search_docs(query: str) -> str:
    if "CORS" in query:
        return "Use API Gateway integrationResponses to handle CORS in AWS CDK."
    return "No results found."

def run_tests(code: str) -> str:
    if "cors" in code.lower():
        return "Tests passed ✅"
    return "Tests failed ❌: missing CORS config"

# Registrar tools
tools = [
    Tool(name="search_docs", func=search_docs, description="Search technical documentation"),
    Tool(name="run_tests", func=run_tests, description="Run code tests")
]

# --- Agente ---
agent = Agent(
    tools=tools,
    system_prompt="""
You are an autonomous software engineer.
You follow a loop:
1. Think about the problem
2. Decide if you need a tool
3. Act using tools
4. Observe results
5. Iterate until the task is complete
"""
)

# --- Task ---
task = "Implement CORS in AWS API Gateway using CDK and verify it works"

# --- Loop ---
state = {"task": task, "code": ""}

for step in range(5):
    print(f"\n--- Step {step + 1} ---")

    response = agent.step(state)

    print("Thought:", response.thought)

    if response.action:
        print("Action:", response.action.name)

        result = response.action.run()
        print("Observation:", result)

        state["last_observation"] = result

        # Simulación: el agente escribe código
        if "CORS" in result:
            state["code"] = "const cors = true;"

    else:
        print("Final Answer:", response.output)
        break

Es un ejemplo simple, pero alcanza para mostrar el patrón.

Lo importante no es el framework

Más allá del framework, lo importante es el ciclo:

Think → Act → Observe → Iterate

Eso es lo que le da forma al comportamiento del agente.

No importa demasiado si usas strands-agents, LangGraph, AutoGen, OpenAI Agents SDK o una implementación propia. En casi todos los casos, la lógica de fondo se parece bastante:

el modelo analiza el problema
decide si necesita una herramienta
ejecuta una acción
observa el resultado
ajusta el siguiente paso

Cuando lo miras así, el concepto deja de parecer misterioso.

No estamos hablando de una inteligencia separada del resto del sistema. Estamos hablando de un modelo que participa en un flujo iterativo con capacidad de actuar sobre un entorno.

¿Por qué extender LLMs con tools?

Porque un LLM sin tools tiene límites muy claros.

Una analogía útil es imaginar a un desarrollador trabajando en un archivo .txt, sin internet, sin compilador y sin un entorno donde validar nada.

Puede razonar, sí.

Pero no puede:

buscar información nueva
verificar si lo que hizo funciona
ejecutar código
consultar el estado real del mundo

Ese es el punto clave.

Un modelo sin herramientas puede producir texto muy convincente, pero no tiene cómo contrastarlo con la realidad.

Visual: LLM sin tools vs con tools

Qué cambia cuando agregas tools

Cuando conectas tools, el modelo puede dejar de operar únicamente sobre lo que recuerda y empezar a interactuar con información y sistemas externos.

Por ejemplo, puede:

buscar documentación
consultar una base de conocimiento
ejecutar código
correr pruebas
leer archivos
consultar APIs
validar una respuesta con datos reales

Ese cambio es mucho más importante de lo que parece.

Porque el valor ya no está solo en que el modelo “sepa” algo, sino en que puede hacer algo, observar lo que ocurrió y usar ese resultado para continuar.

Ahí es donde aparece la parte realmente interesante del comportamiento agéntico.

La idea clave

Un agente no es solamente un modelo.

Es un modelo dentro de un ciclo, conectado a herramientas y expuesto a feedback del entorno.

Esa definición, para mí, es mucho más útil que cualquier explicación grandilocuente.

Porque además ayuda a desmontar una confusión bastante común: pensar que el salto de “LLM” a “agente” es una cuestión de branding o de complejidad artificial.

No lo es.

Lo que cambia no es solo el nombre.

Lo que cambia es la arquitectura del problema.

Entonces, ¿un archivo `.md` es un agente?

Por sí solo, normalmente no.

Puede ser una pieza excelente de diseño. Puede capturar reglas, intención, tono, restricciones, prioridades e incluso estrategias de decisión. Y en algunos casos, eso ya aporta muchísimo valor.

Pero cuando hablamos de un agente funcionando como sistema, suele hacer falta bastante más:

un runtime que ejecute acciones
herramientas reales
estado
validación
manejo de errores
observabilidad
integración con otros componentes

Por eso, más que oponer “prompt” contra “agente”, creo que conviene pensar en capas.

Un .md puede ser la capa de comportamiento.

El agente completo incluye además la capa de ejecución, control y operación.

Llevar esto a producción cambia por completo la conversación

Aquí es donde muchas demos dejan de ser suficientes.

En una prueba local, casi todo puede verse ordenado:

el modelo recibe una instrucción
llama una tool
obtiene algo útil
devuelve una respuesta razonable

Pero producción introduce otro tipo de preguntas.

No preguntas sobre la idea.

Preguntas sobre el sistema.

Por ejemplo:

¿qué ocurre si una tool falla?
¿cómo evitas loops innecesarios?
¿cómo limitas costo y latencia?
¿cómo registras las decisiones que tomó el agente?
¿cómo auditas lo que hizo?
¿cómo validas que una acción sea segura antes de ejecutarla?
¿cómo recuperas el estado si el flujo se interrumpe?
¿cómo haces retries sin duplicar efectos?
¿dónde incorporas aprobación humana?
¿cómo pruebas algo cuyo comportamiento depende de contexto, tools y feedback?

Y ahí se vuelve evidente algo importante:

construir una demo con sabor a agente es relativamente fácil; construir un sistema confiable es otra cosa.

Por eso, cuando alguien pregunta si un agente es “solo un prompt con tools”, mi respuesta tiende a ser: a veces eso alcanza para una demo útil, pero no para describir todo lo que implica operarlo bien.

Conclusión

Más que decir que estamos en un momento extraño, diría que estamos en una etapa de ajuste.

Todavía hay equipos que apenas están empezando a explorar asistentes de código. Otros ya pasaron por varias herramientas, frameworks y experimentos con agentes. Y muchos están descubriendo, quizá por primera vez, que bajo una misma palabra se mezclan ideas que conviene separar.

Por eso la pregunta sigue apareciendo:

¿Qué es realmente un agente?

Mi respuesta, hoy, sería esta:

Un agente no es magia.

No es solamente un prompt.

No es simplemente un .md.

Y tampoco es cualquier flujo con varias llamadas a un modelo.

Un agente es un sistema donde un modelo puede:

razonar
actuar
observar resultados
y decidir qué hacer después en función de ese feedback

Entender eso no resuelve todo, pero sí limpia bastante el terreno.

Y en un momento donde casi todo el mundo usa la palabra “agente” para algo distinto, tener una definición más concreta ya es un muy buen comienzo.

DEV Community: Xavier Gutiérrez

Agentes 101 - 02: El ciclo del agente como State Machine (y Hierarchical State Machines)

El ciclo Think Act Observe como máquina de estados

Una State Machine simple

Tools = acciones que cambian el estado

Cuando la máquina se complica: Hierarchical State Machines

Cómo lo implementa LangGraph

1. StateGraph = la máquina de estados

2. Subgraphs = Hierarchical State Machines

Patrón A - Shared State

Patrón B - Isolated State

¿Cuándo vale la pena formalizarlo?

Conclusión

Agentes 101 - 01

¿Qué es realmente un agente LLM?

La respuesta corta

Una definición más útil

Visual general

La analogía más simple: un desarrollador humano

Entonces, ¿de dónde sale tanta confusión?

Veamos un ejemplo en código

Lo importante no es el framework

¿Por qué extender LLMs con tools?

Visual: LLM sin tools vs con tools

Qué cambia cuando agregas tools

La idea clave

Entonces, ¿un archivo .md es un agente?

Llevar esto a producción cambia por completo la conversación

Conclusión

Entonces, ¿un archivo `.md` es un agente?