Notas prácticas: ¿Por qué nadie habla de LangChain, LangGraph o AutoAgent?
Guía práctica paso a paso: Por qué nadie habla de LangChain, LangGraph o AutoAgent: contratos, verificaciones y espacios para código listo para usar para los equipos que implementan este patrón.
Fuentes: Why No One Talks About LangChain, LangGraph Or AutoAgent
Esta guía reconstruye el proceso desde las materias primas hasta un sistema funcional para: ¿Por qué nadie habla de LangChain, LangGraph o AutoAgent? El enfoque está en pasos operativos, verificaciones explícitas y código que se puede incorporar directamente a un repositorio sin tener que adivinar la intención. Para obtener una visión general, defina las entradas, el responsable del paso y los criterios de finalización antes de modificar el código. Los operadores deben poder volver a ejecutar el paso a partir de un punto de control conocido sin tener que adivinar el estado oculto. Documente tanto el camino óptimo como el camino de recuperación. Las reintentos, los controles humanos y el manejo de mensajes no entregados forman parte del producto, no son mejoras posteriores.
┌────────────────────────────────────────┐
│ POST-FRAMEWORK PARADIGM │
└──────────────────┬─────────────────────┘
│
┌─────────────┴─────────────┐
▼ ▼
┌──────────────┐ ┌──────────────┐
│ PIPELINE │ │ HARNESS │
│ MODE │ │ MODE │
├──────────────┤ ├──────────────┤
│ • Bounded │ │ • Unbounded │
│ • Code-Run │ │ • Model-Run │
│ • Compute │ │ • Context │
│ Bound │ │ Bound │
└──────────────┘ └──────────────┘
Índice
Al trabajar con la tabla de contenidos, anote primero el contrato: los datos requeridos, la señal de éxito y qué ocurre en caso de fallo parcial. Esa lista de verificación mantiene honestas las futuras modificaciones del código. Prefiera unidades pequeñas y verificables en lugar de scripts extensos. Cuando un paso falla, el fallo debe apuntar a una única responsabilidad y no a un proceso complicado. Haga una verificación después de los pasos costosos. El sistema de reanudación no debe volver a facturar la misma llamada al LLM cuando un operador intenta nuevamente un nodo posterior.
1. La clasificación del trabajo que nadie hace
Al trabajar en “1. La clasificación de tareas que nadie realiza”, anote primero el contrato: los datos necesarios, la señal de éxito y qué ocurre en caso de fallo parcial. Esa lista de verificación mantiene honestas las futuras modificaciones del código. Considere esta etapa como un contrato entre los datos de entrada y los resultados validados. Asigne nombres a los artefactos, defina las comprobaciones de éxito y evite completaciones parciales silenciosas. Haga una verificación después de los pasos costosos. El sistema de reanudación no debe volver a facturar la misma llamada al LLM cuando un operador intente nuevamente un nodo posterior.
Is the work decomposable into a finite set of
named states with deterministic transitions?
[ YES ] ──► PIPELINE MODE
• Invoice Extraction
• Document Classification
• Approval Routing
• KYC Verification
• Data Enrichment
[ NO ] ──► HARNESS MODE
• Coding Agents
• Research Agents
• Ephemeral Tool/Shell Use
• Legacy Code Migrations
• Open-Ended Investigation
2. Modo de pipeline: cuando el trabajo es descomponible
Al trabajar en el punto 2: Modo de pipeline, cuando el trabajo es descomponible, primero debe escribirse el contrato: entradas requeridas, señal de éxito y qué ocurre en caso de fallo parcial. Esa lista de verificación garantiza que los cambios posteriores en el código sean transparentes. Registre los tiempos de ejecución y el costo de tokens o consultas junto con los resultados funcionales. Tener visibilidad del costo desde el principio evita facturas inesperadas cuando el proceso pasa de la fase de demostración a entornos compartidos. Haga un punto de control después de los pasos costosos. La reanudación del proceso no debe volver a facturar la misma llamada al LLM cuando un operador intenta nuevamente un nodo posterior. Al trabajar en el punto 2: Modo de pipeline, cuando el trabajo es descomponible, primero debe escribirse el contrato: entradas requeridas, señal de éxito y qué ocurre en caso de fallo parcial. Esa lista de verificación garantiza que los cambios posteriores en el código sean transparentes. Documente tanto la ruta óptima como la ruta de recuperación. Las reintentos, los controles humanos y el manejo de mensajes no entregados forman parte del producto, no son mejoras adicionales realizadas posteriormente.
[Input Data payload]
│
▼
┌──────────────┐
│ State 1 │ ──► [Structured LLM Call]
└──────┬───────┘ │
│ ▼
│ ┌──────────────┐
│ │ Validation │ ──► [Fail] ──► [Error State]
│ └──────┬───────┘
│ │ [Pass]
▼ ▼
┌──────────────┐
│ State 2 │ ──► [Structured LLM Call]
└──────┬───────┘ │
│ ▼
│ ┌──────────────┐
│ │ Validation │ ──► [Fail] ──► [Error State]
│ └──────┬───────┘
│ │ [Pass]
▼ ▼
[Final Success Output]
3. Modo Harness: Cuando el trabajo no es descomponible
- El Modo Harness: Cuando el trabajo no es descomponible funciona mejor si se trata como una superficie medible. Capture una transcripción ejemplar, un caso de fallo y la nota de reversión antes de ampliar el alcance. Prefiera unidades pequeñas y verificables en lugar de scripts extensos. Cuando un paso falla, el fallo debe apuntar a una única responsabilidad y no a un proceso complicado. Ofrezca herramientas con esquemas limitados y etiquetas explícitas sobre efectos secundarios. Los administradores necesitan saber qué llamadas modifican el estado antes de aprobarlas automáticamente.
┌──────────────────────────────────────────────┐
│ HARNESS LAYER │
│ Executes container limits & system safety │
├──────────────────────────────────────────────┤
│ [Safety Hooks] [Budgets] [Time Constraints] │
├──────────────────────────────────────────────┤
│ ┌────────────────────────────────────────┐ │
│ │ MODEL OWNS LOOP │ │
│ │ Plan ──► Execute ──► Observe ──► Plan │ │
│ │ │ │
│ │ Native capabilities: │ │
│ │ • File / Sandboxed Shell access │ │
│ │ • Context-isolated subagent spawning │ │
│ │ • Skill discovery & loading │ │
│ └────────────────────────────────────────┘ │
└──────────────────────┬───────────────────────┘
▼
Result, Partial State, or Escalation
Los modos de fallo del Modo Harness
Los modos de fallo del modo Harness funcionan mejor cuando se tratan como una superficie medible. Capture una transcripción clave, un caso de fallo y la nota de reversión antes de ampliar el alcance. Considere esta etapa como un contrato entre las entradas y las salidas validadas. Asigne nombres a los artefactos, defina verificaciones de éxito y rechace las completaciones parciales silenciosas. Exponga herramientas con esquemas limitados y etiquetas explícitas de efectos secundarios. Los hosts necesitan saber qué llamadas modifican el estado antes de aprobarlas automáticamente.
4. La realidad matemática de ambos modos
- La Realidad Matemática de Ambos Modos funciona mejor cuando se trata como una superficie medible. Capture un registro ideal, un caso de fallo y la nota de reversión antes de ampliar el alcance. Registre los tiempos y el costo de tokens o consultas junto con los resultados funcionales. Tener visibilidad del costo desde el principio evita facturas inesperadas cuando el proceso pasa de la versión de demostración a entornos compartidos. Mantenga el estado del gráfico en formato plano y tipado de forma consistente. Los bloques anidados ocultan qué nodo escribió qué campo y causan interrupciones en la continuación del proceso.
- La Realidad Matemática de Ambos Modos funciona mejor cuando se trata como una superficie medible. Capture un registro ideal, un caso de fallo y la nota de reversión antes de ampliar el alcance. Documente tanto el camino óptimo como el camino de recuperación. Las reintentos, los controles humanos y el manejo de mensajes no entregados forman parte del producto, no son ajustes realizados posteriormente.
Modo de Pipeline: La Ley de Escalado en Tiempo de Inferencia
Para el modo Pipeline: La ley de escalamiento del tiempo de inferencia exige definir las entradas, el responsable de cada paso y los criterios de finalización antes de modificar el código. Los operadores deben poder volver a ejecutar el paso a partir de un punto de control conocido, sin tener que adivinar el estado oculto. Es preferible utilizar unidades pequeñas y verificables en lugar de scripts extensos. Cuando un paso falla, el error debe indicar una única responsabilidad y no un proceso complejo e entrelazado. Se debe incluir la aprobación humana en aquellos casos en que se gastan fondos o se modifican datos de producción. La conexión de componentes en tiempo de compilación no equivale a la completitud del proceso empresarial.
Modo Harness: La curva de degradación del contexto
Para el modo Harness: La curva de degradación del contexto exige definir las entradas, el responsable de cada paso y los criterios de finalización antes de modificar el código. Los operadores deben poder volver a ejecutar el paso a partir de un punto de control conocido, sin tener que adivinar el estado oculto. Considere esta etapa como un contrato entre las entradas y los resultados validados. Asigne nombres a los artefactos, defina verificaciones de éxito y rechace cualquier completación parcial silenciosa. Autentíquese en la pasarela y vuelva a autorizarse en el plano de datos. Un token portador por sí solo no constituye un límite entre tenencias.
P(Success)
▲
1.0├───────────┐
│ │
│ └───┐
0.5│ │
│ └─────────────► Context Size (Tokens)
0└───────────┬───┬─────────────
50k 100k
5. La forma de Harness en 2026 (Plan de implementación)
Para 5. La estructura de un Harness 2026 (plan de implementación), defina las entradas, el responsable del paso y los criterios de finalización antes de modificar el código. Los operadores deben poder volver a ejecutar el paso a partir de un punto de control conocido sin tener que adivinar el estado oculto. Registre los tiempos y el costo de tokens o consultas junto con los resultados funcionales. La visibilidad temprana del costo evita facturas inesperadas cuando el proceso pasa de entornos de demostración a entornos compartidos. Autentique en la pasarela y vuelva a autorizarlo en el plano de datos. Un token portador por sí solo no constituye un límite entre tenencias. Para 5. La estructura de un Harness 2026 (plan de implementación), defina las entradas, el responsable del paso y los criterios de finalización antes de modificar el código. Los operadores deben poder volver a ejecutar el paso a partir de un punto de control conocido sin tener que adivinar el estado oculto. Documente tanto la ruta óptima como la ruta de recuperación. Las reintentos, los controles humanos y el manejo de mensajes no entregados forman parte de la solución profesional.
conducto, no pulirlo más tarde.import logging
import os
from typing import Dict, Any, List
from pydantic import BaseModel, Field
# 2026 SDK abstractions (analogous across major provider frameworks)
from modern_agent_sdk import Agent, Skill, SubAgent
from modern_agent_sdk.hooks import PreToolUse, PostToolUse
from modern_agent_sdk.budgets import TokenBudget, StepBudget, WallTimeBudgetlogger = logging.getLogger("EnterpriseHarness")# 1. Skills are dynamically loaded from disk, not declared inline.
# Each skill is an isolated directory containing metadata (SKILL.md),
# runtime scripts, and specialized sandbox requirements.
SKILLS_DIR = "./skills"
all_skills = Skill.load_directory(SKILLS_DIR)# 2. Safety Hooks: Gateway controls running in the host environment.
# These run on the host *before* any action is committed inside the sandbox.
def pre_tool_execution_hook(context: Dict[str, Any], tool_call: BaseModel) -> PreToolUse:
"""
Validates security boundaries and consumption limits before the model executes a tool.
"""
# Hard safety boundary: Prevent destructive shell operations
if tool_call.name == "execute_shell":
command = tool_call.args.get("command", "")
if any(bad_cmd in command for bad_cmd in ["rm -rf", "chmod", "wget"]):
logger.error(f"Execution blocked: Blocked command detected: '{command}'")
return PreToolUse.deny("Destructive shell operations are prohibited in this sandbox.")
# Budget check: Halt network tools if API budget is running low
if tool_call.name == "network_request":
if context["budget"].remaining_tokens < 15_000:
return PreToolUse.deny("Insufficient remaining token budget to execute external network calls.")
logger.info(f"Approved tool call: {tool_call.name}")
return PreToolUse.allow()def post_tool_execution_hook(context: Dict[str, Any], tool_call: BaseModel, result: Any) -> PostToolUse:
"""
Evaluates tool execution outcomes to detect systemic failure loops.
"""
# Detect repeating error patterns to prevent infinite execution loops
if result.is_error and context["consecutive_failures"] >= 3:
logger.warning("System detected a repeating error loop. Forcing escalation.")
return PostToolUse.escalate("Agent is stuck in an execution failure loop.")
return PostToolUse.continue_loop()# 3. Context Isolation via Subagents
# To prevent context poisoning, the parent agent never sees the child's
# scratchpad or intermediate execution steps—only the final verified output.
def spawn_research_subagent(target_query: str) -> str:
"""
Spawns a specialized subagent in a separate context window to perform a task,
keeping the parent's working context completely clean.
"""
logger.info(f"Spawning isolated subagent for query: '{target_query}'")
subagent = SubAgent(
model="claude-sonnet-4-5",
skills=all_skills.filter_by_tag("research"),
budgets=[
TokenBudget(max_input_tokens=40_000, max_output_tokens=8_000),
StepBudget(max_steps=12)
]
)
# Run task and return only the clean, compiled summary
output = subagent.execute(task=target_query)
return output.summary# 4. Assembling the Harness Container
# The harness manages the execution sandbox, enforces constraints, and handles state.
agent_harness = Agent(
model="claude-opus-4-7",
skills=all_skills,
subagent_factories={
"researcher": spawn_research_subagent
},
hooks={
"pre_tool_use": pre_tool_execution_hook,
"post_tool_use": post_tool_execution_hook
},
budgets=[
TokenBudget(max_total_tokens=600_000),
StepBudget(max_steps=100),
WallTimeBudget(max_seconds=1800) # 30-minute hard cap
],
persistence_store="./.agent_state_db", # State is persisted per step to survive restarts
escalation_handler=lambda issue: open_human_review_ticket(issue)
)# 5. Execution
if __name__ == "__main__":
task_input = "Migrate this legacy Django 4.2 codebase to FastAPI with 100% endpoint parity."
try:
# The agent loop is entirely internal to the model.
# There is no manual 'while True' in our orchestration code.
result = agent_harness.run(task=task_input)
logger.info(f"Task completed. Result: {result.status}")
except Exception as e:
logger.critical(f"Harness terminated execution: {e}")
Diferencias clave con los frameworks heredados de 2024:
Al trabajar en las Diferencias clave con los frameworks heredados de 2024:, anote primero el contrato: entradas requeridas, señal de éxito y qué ocurre en caso de fallo parcial. Esa lista de verificación mantiene honestas las futuras modificaciones del código. Prefiera unidades pequeñas y verificables en lugar de scripts extensos. Cuando un paso falla, el fallo debe apuntar a una única responsabilidad y no a un proceso complicado. Haga una verificación después de los pasos costosos. La función de reanudación no debe volver a facturar la misma llamada al LLM cuando un operador intenta nuevamente un nodo posterior.
6. Colisiones arquitectónicas: Aplicar la solución incorrecta al problema equivocado
Al trabajar en la sección 6, “Colisiones arquitectónicas: Aplicar la forma incorrecta al problema equivocado”, anote primero el contrato: los datos de entrada requeridos, la señal de éxito y qué ocurre en caso de fallo parcial. Esa lista de verificación mantiene honestas las futuras modificaciones del código. Considere esta etapa como un contrato entre los datos de entrada y las salidas validadas. Asigne nombres a los artefactos, defina comprobaciones de éxito y evite completaciones parciales silenciosas. Haga una verificación después de los pasos costosos. El sistema de reanudación no debe volver a facturar la misma llamada al LLM cuando un operador intente nuevamente un nodo posterior.
┌─────────────────────────────────────────────────────┐
│ ARCHITECTURAL MATCH │
├──────────────────────────┬──────────────────────────┤
│ PIPELINE WORKLOAD │ HARNESS WORKLOAD │
├──────────────────────────┼──────────────────────────┤
│ • Goal: Exact Extraction │ • Goal: Code Refactoring,│
│ & Routing │ Agent Tasks, Migration │
│ │ │
│ • WRONG: Harness │ • WRONG: Pipeline │
│ (High latency, costly, │ (FSM State explosion, │
│ non-deterministic) │ inflexible schema) │
│ │ │
│ • RIGHT: Pipeline FSM │ • RIGHT: Sandbox Harness │
│ (Predictable transitions)│ (Dynamic loop execution)│
└──────────────────────────┴──────────────────────────┘
Caso 1: El error de Harness-on-Pipeline (Soboingeniería)
Al trabajar en el Caso 1: El error de Harness-on-Pipeline (Sob ingeniería), anote primero el contrato: entradas requeridas, señal de éxito y qué ocurre en caso de fallo parcial. Esa lista de verificación mantiene honestas las futuras modificaciones del código. Registre los tiempos y el costo de tokens o consultas junto con los resultados funcionales. Tener visibilidad del costo desde el principio evita facturas inesperadas cuando el proceso pasa de la fase de demostración a entornos compartidos. Registre el nombre de la herramienta, el hash de los argumentos, la latencia y el resultado de cada llamada. Depurar bucles sin ese historial desperdicia horas. Al trabajar en el Caso 1: El error de Harness-on-Pipeline (Sob ingeniería), anote primero el contrato: entradas requeridas, señal de éxito y qué ocurre en caso de fallo parcial. Esa lista de verificación mantiene honestas las futuras modificaciones del código. Documente tanto el camino óptimo como el camino de recuperación. Las reintentos, los controles humanos y el manejo de mensajes no entregados forman parte del producto, no son mejoras posteriores.
Caso 2: El error de Pipeline-on-Harness (diseño insuficiente)
Caso 2: El error de Pipeline-on-Harness (diseño insuficiente) funciona mejor cuando se trata como una superficie medible. Capture una transcripción ejemplar, un caso de fallo y la nota de reversión antes de ampliar el alcance. Prefiera unidades pequeñas y verificables en lugar de scripts extensos. Cuando falla un paso, el fallo debe apuntar a una única responsabilidad y no a un proceso complejo. Exponga herramientas con esquemas limitados y etiquetas explícitas de efectos secundarios. Los administradores necesitan saber qué llamadas modifican el estado antes de aprobarlas automáticamente.
Cómo seleccionar la arquitectura correcta
Cómo seleccionar la arquitectura correcta funciona mejor cuando se trata como una superficie medible. Capture un registro ejemplar, un caso de fallo y la nota de reversión antes de ampliar el alcance. Considere esta etapa como un contrato entre las entradas y los resultados validados. Asigne nombres a los artefactos, defina verificaciones de éxito y rechace las completaciones parciales silenciosas. Mantenga el estado del grafo plano y tipado; los bloques anidados ocultan qué nodo escribió qué campo y provocan interrupciones en la continuación del proceso.
7. La capa de habilidades: el estándar abierto de 2026
- La capa de habilidades: El estándar abierto de 2026 funciona mejor cuando se trata como una superficie medible. Capture un registro ideal, un caso de fallo y la nota de reversión antes de ampliar el alcance. Registre los tiempos y el costo en tokens o consultas junto con los resultados funcionales. Tener visibilidad del costo desde el principio evita facturas inesperadas cuando el proceso pasa de la demostración a entornos compartidos. Mantenga el estado del gráfico simple y tipado. Los bloques anidados ocultan qué nodo escribió qué campo y causan interrupciones en la continuación del proceso.
- La capa de habilidades: El estándar abierto de 2026 funciona mejor cuando se trata como una superficie medible. Capture un registro ideal, un caso de fallo y la nota de reversión antes de ampliar el alcance. Documente tanto el camino óptimo como el camino de recuperación. Las reintentos, los controles humanos y el manejo de mensajes no entregados forman parte del producto, no son mejoras posteriores.
skills/
├── document_parser/
│ ├── SKILL.md <-- Human/Model readable metadata & capabilities
│ ├── run.py <-- The execution logic running inside the sandbox
│ └── reference_rules.pdf <-- Domain-specific constraints and edge-cases
8. Conclusión: El nuevo trabajo en ingeniería
8. Conclusión: El nuevo trabajo de ingeniería exige definir las entradas, el responsable de cada paso y los criterios de finalización antes de modificar el código. Los operadores deben poder volver a ejecutar un paso a partir de un punto de control conocido, sin tener que adivinar el estado oculto. Es preferible utilizar unidades pequeñas y verificables en lugar de scripts extensos. Cuando un paso falla, el error debe indicar una única responsabilidad y no un proceso complicado. Se debe incluir la aprobación humana en aquellas tareas que implican gastos o modificaciones en los datos de producción. La configuración en tiempo de compilación no equivale a la completitud del proceso empresarial.
Lista de verificación operativa
La lista de verificación operativa funciona mejor cuando se trata como una superficie medible. Capture una transcripción de referencia, un caso de fallo y la nota de reversión antes de ampliar el alcance.
Mantenga la configuración fuera del código de la aplicación. Los archivos de entorno, los almacenes de datos secretos y las banderas de funcionalidad deben estar en un único lugar que los operadores puedan auditar sin tener que leer todo el grafo.
Mantenga el estado del grafo plano y tipado. Los bloques anidados ocultan qué nodo escribió qué campo y dificultan la reanudación después de interrupciones.
Agregue una prueba de funcionamiento básica que ejecute la ruta crítica en los procesos CI utilizando fixtures, y no APIs pagadas en tiempo real, siempre que lo permitan los presupuestos.
Documente tanto la ruta óptima como la ruta de recuperación. Las reintentos, los controles humanos y el manejo de mensajes no entregados forman parte del producto, no son algo que se añada posteriormente.
Mantenga el estado del grafo plano y tipado. Los bloques anidados ocultan qué nodo escribió qué campo y dificultan la reanudación después de interrupciones.
Antes de promocionar el conjunto de herramientas, congele las versiones, capture una transcripción de referencia para la ruta crítica y confirme los pasos para revertir cambios. Los entornos compartidos requieren límites de velocidad, verificaciones de tenencia y un responsable claro para la rotación de credenciales secretas. Prefiera una fiabilidad sencilla a demostraciones ingeniosas pero puntuales.
Nota para el lote 9f921d978495: mantenga las claves del proveedor fuera del repositorio, establezca un límite para tokens por sesión y almacene las transcripciones junto a los archivos de prueba para que los cambios en los modelos posteriores sigan siendo comparables.
Lecturas relacionadas
- Notas prácticas: IA agente con LangChain — Parte 4: Patrón ReAct en LangGraph — Guía detallada de las Notas prácticas: IA agente con LangChain — Parte 4: Patrón ReAct en LangGraph, incluyendo contratos, verificaciones y espacios de código listos para usar por parte de los equipos que implementan este patrón.