Subgrafos compilados duraderos

Flujo de extremo a extremo

sequenceDiagram
    participant App as App.get_agent
    participant Resolver as DurableSubgraphResolver
    participant Session as DurableSession
    participant LangGraph as LangGraph runtime
    participant Wrapper as Secure LLM or Tool wrapper
    participant Paths as Runner-shared path allocator
    participant OE as Orchestration Engine
    Note over App,Session: Materialize and validate once
    App->>Resolver: Discover compiled-child topology
    App->>Session: Attach resolver to the agent session
    Session->>Resolver: Validate supported topology
    Note over Session,LangGraph: Bind for each invoke or stream iteration
    Session->>LangGraph: Enter durable identity scope
    LangGraph->>LangGraph: Enter compiled child graph
    LangGraph->>LangGraph: Expose active checkpoint_ns
    Note over Wrapper,OE: Resolve only when a secure effect is admitted
    LangGraph->>Wrapper: Invoke secure LLM or Tool
    Wrapper->>Paths: Build durable activity command
    Paths->>Resolver: Resolve current operation path
    Resolver->>LangGraph: Read checkpoint_ns from runtime config
    LangGraph-->>Resolver: Compiled-child occurrence namespace
    Resolver-->>Paths: Ordered child boundaries
    Paths->>Paths: Assign stable child ordinals
    Paths->>OE: Start activity at resolved position
    OE-->>Wrapper: Recorded outcome or newly executed result

Ejemplo concreto

Considere este gráfico compilado:

root graph
  -> case_investigation (compiled child graph)
       -> policy_analysis (compiled child graph)
            -> review_policy (ordinary node)
                 -> secure Tool lookup_policy

Mientras review_policy se ejecuta, LangGraph expone un espacio de nombres con un segmento por tarea de gráfico activa, similar a:

case_investigation:task-a|policy_analysis:task-b|review_policy:task-c

`DurableSubgraphResolver.resolve_namespace <../src/agent_engine_sdk_langgraph/durable_subgraphs.py>`__ recorre la topología y el espacio de nombres juntos:

1. case_investigation es un hijo compilado, por lo que contribuye con ChildOperationBoundary("case_investigation", "task-a").

2. policy_analysis es un hijo compilado dentro de él, por lo que contribuye con ChildOperationBoundary("policy_analysis", "task-b").

3. review_policy es un nodo ordinario. Se valida como el segmento de espacio de nombres más a la derecha y no aporta un límite hijo.

Runner-shared utiliza cada clave de ocurrencia para asignar un ordinal bajo su padre:

agent/1 / case_investigation/1 / policy_analysis/1

Las cadenas task-a y task-b provienen directamente del texto que sigue a : en el espacio de nombres de LangGraph. Atlas Agent Engine las trata como claves de asignador opacas. La ruta de operación final contiene ordinales estables en lugar de los identificadores de tarea sin procesar de LangGraph.

El LLM seguro y todas las herramientas seguras a las que se accede desde review_policy resuelven el mismo prefijo de elemento secundario compilado. Su tipo de actividad, paso del flujo de trabajo y ordinal de actividad distinguen los efectos individuales que se encuentran debajo de ese prefijo.

Descubra la topología estática

`App.get_agent <../src/agent_engine_sdk_langgraph/runtime.py>`__ crea un DurableSubgraphResolver cuando el grafo materializado utiliza el puntero de control de la plataforma. El resolvedor inspecciona recursivamente los nodos CompiledStateGraph y almacena solo:

• cada nombre de nodo en cada nivel del gráfico, para la validación del espacio de nombres; y

• cada gráfico hijo compilado directamente, para los límites de operación.

`DurableSession `__valida la topología guardada antes de que comience la ejecución duradera. La topología compilada cíclica y un hijo compilado con su propio puntero de control fallan explícitamente. Un hijo compatible usa checkpointer=None y hereda el puntero de control de la plataforma raíz.

Discovery no asigna identidades de actividad ni conserva los ID de las tareas en tiempo de ejecución. Registra el mapa estructural necesario para interpretar posteriormente el espacio de nombres activo de LangGraph.

Vincular el resolvedor a la ejecución

Invoke y stream execution vinculan el mismo resolvedor a través de `operation_path_resolver_scope de agent-engine-runner-shared <../../agent-engine-runner-shared/src/agent_engine_runner_shared/workflow/context.py>`__:

• `ExecutionSession.invoke_scopes <../src/agent_engine_sdk_langgraph/execution_session.py>`__ cubre una llamada completa a invoke.

• `scoped_anext <../src/agent_engine_sdk_langgraph/stream_scope.py>`__ vuelve a enlazar el ámbito para cada iteración del flujo porque un generador asíncrono puede reanudarse en una tarea asyncio diferente.

El ámbito instala el resolvedor a través de `operation_path_resolver_scope de agent-engine-runner-shared <../../agent-engine-runner-shared/src/agent_engine_runner_shared/workflow/context.py>`__. Este es el límite del adaptador: agent-engine-runner-shared solo sabe que una devolución de llamada puede devolver límites secundarios ordenados; no conoce los espacios de nombres de LangGraph ni los tipos de grafos.

Resolver en el límite del efecto seguro

Los envoltorios seguros de LLM y Tool finalmente llaman a `run_serial_activity <../../agent-engine-runner-shared/src/agent_engine_runner_shared/workflow/activity.py>`__ para construir una actividad OE. Durante la construcción del comando, `current_operation_path <../../agent-engine-runner-shared/src/agent_engine_runner_shared/workflow/context.py>`__ invoca el ámbito DurableSubgraphResolver.

El solucionador entonces:

1. Llama al método público get_config() de LangGraph mientras el nodo está activo.

2. Lee configurable.checkpoint_ns.

3. Analiza cada segmento name:occurrence-key de izquierda a derecha.

4. Requiere que cada segmento coincida con la topología descubierta durante la construcción.

5. Devuelve un límite para cada nodo hijo compilado y omite el último nodo ordinario.

Un nodo ordinario puede aparecer únicamente como el segmento más a la derecha. Un espacio de nombres que continúa por debajo de un nodo ordinario no se explica por la topología compilada y se rechaza. Esto evita que una ruta de marco desconocida colapse silenciosamente sobre una identidad duradera válida.

Runner-shared combina los límites devueltos con la raíz fija agent/1, el paso actual del flujo de trabajo y el ordinal de la actividad del efecto. Esa posición completa es la que OE utiliza para grabar o reproducir.

Replay

Al reemplazarlo, LangGraph accede a la misma instancia compilada del elemento hijo y expone el espacio de nombres correspondiente. El adaptador reconstruye los mismos límites de elementos hijos ordenados, agent-engine-runner-shared asigna los mismos ordinales y el efecto seguro solicita a OE la misma posición de actividad. OE devuelve el resultado registrado en lugar de ejecutar el efecto externo nuevamente.

Solo los contenedores seguros de LLM y Tool activan esta resolución. El trabajo con gráficos ordinarios puede avanzar a través de elementos secundarios compilados sin crear actividades OE.

Límite soportado

La identidad de subgrafo compilado duradero admite grafos secundarios materializados estáticamente que heredan el puntero de control de la plataforma raíz. No admite la ramificación LangGraph Send creada por la aplicación. Los bordes fijos y los grafos secundarios compilados son las formas admitidas para que los grafos de la aplicación expresen trabajo duradero anidado.

Mapa del lugar de la llamada

Verificación y mantenimiento

Al actualizar LangGraph:

1. Revitalice los contratos públicos checkpoint_ns y get_config() enlazados anteriormente.

2. Ejecuta escenarios de topología, análisis de espacio de nombres, forma inválida y ámbito de invocación en `test_durable_subgraphs.py <../tests/test_durable_subgraphs.py>`__.

3. Ejecuta escenarios de reproducción de hijos compilados e identidad de hermanos en `test_durable_subgraphs_integration.py <../tests/test_durable_subgraphs_integration.py>`__.

4. Ejecuta la invocación y la cobertura de transmisión en `test_agent.py <../tests/test_agent.py>`__.