Adaptador Google ADK 2 para el SDK de MongoDB Atlas Agent Engine.
El adaptador es duradero solo en modo AER. Establezca features.durable_workflow: true en agent.yaml. Omitido o false no vuelve a una sesión ADK nativa; la primera invocación falla. El motor de orquestación posee el estado de giro cruzado y lo proporciona a cada intento; el adaptador no mantiene una base de datos de sesión ADK separada. Conceptos de plataforma, habilitación y la regla de identidad detrás de los límites de topología a continuación: Flujo de trabajo duradero. Atlas Agent Engine ctx.resume no es una reanudación de punto de control ADK. Las rutas ADK paralelas pueden suspenderse juntas; el adaptador las recopila a través de la quiescencia del ejecutor y confirma una frontera de espera OE atómica. Una vez que esa frontera es respondida, su paso se confirma y ADK puede continuar en otra frontera serial o paralela.
Suspender y reanudar
Los autores componen esperas nativas de ADK en el constructor de agentes con los constructores oficiales `FunctionTool(..., require_confirmation=True)LongRunningFunctionTool. Pase las funciones invocables de app.tools(), no la función @app.tool sin procesar: @app.tool solo registra la herramienta; app.tools() es lo que aplica el envoltorio seguro de Atlas Agent Engine. Atlas Agent Engine registra cada espera como una actividad de OE y finaliza la frontera completa en un comando. Los identificadores de interrupción de Atlas Agent Engine son esos identificadores de actividad, no los identificadores de llamada a función de ADK. Continue requiere un resume_map completo; es un nuevo intento que recorre el mensaje de usuario original nuevamente; OE devuelve la respuesta registrada; el adaptador alimenta a ADK un lote de FunctionResponse partes indexadas por los identificadores de llamada a función de esta ejecución. No hay Atlas Agent Engine app.suspend(). Una respuesta de confirmación es el objeto {confirmed: true|false} de ADK. Una respuesta de RequestInput es lo que acepte el diccionario FunctionResponse.response de ADK: un objeto JSON o un escalar/matriz no nulo que el adaptador encapsula como {result: ...}. JSON null no es una respuesta.
attempt 1: original message → ADK runs to quiescence → OE frontier 1 SUSPENDED attempt 2: replay frontier 1 → COMPLETED → commit step 1 → continue ADK → frontier 2 SUSPENDED attempt 3: replay step 1 → replay frontier 2 → COMPLETED → commit step 2 → continue
sitio | rol |
|---|---|
|
|
| Corredor ADK público estable y puente |
| Vincula el intento de OE, reconstruye el mensaje original e identifica la frontera de reanudación actual. |
| Camina |
| Continúe a través de las fronteras resueltas hasta la siguiente nueva espera o finalización. |
| Vincular las rutas de nodos ADK canónicas a rutas de operaciones duraderas compartidas. |
| Reservar las transferencias de subagentes configuradas bajo sus rutas principales canónicas. |
| Mapea las esperas nativas a una frontera ordenada y construye el lote de respuesta. |
| Finalizar todas las esperas atómicamente y hacer coincidir los resultados de OE por posición duradera. |
|
|
| Prefijo LLM y herramientas son actividades de Atlas Agent Engine, por lo que continuar no vuelve a ejecutar esos efectos secundarios. |
El adaptador acepta un ADK BaseAgent o un ADK 2 Workflow. ADK no define un ciclo de vida de superpaso al estilo LangGraph. Por lo tanto, Atlas Agent Engine introduce un paso solo en una frontera de coordinación quiescente: todas las esperas en esa frontera se unen atómicamente, la frontera resuelta confirma su paso y la siguiente continuación Runner.run_async inicia el siguiente paso.
Flujo de trabajo y rutas de los agentes
ADK expone la composición Workflow y la colaboración de agentes a través de diferentes API de configuración, pero las ejecuciones configuradas coinciden en la misma primitiva de tiempo de ejecución: tanto los nodos de flujo de trabajo como los agentes son instancias BaseNode, y ADK asigna a cada ejecución una instancia canónica Context.node_path. El adaptador asigna esa ruta a la ruta de operación de OE; no reconstruye la ascendencia del agente a partir del texto del modelo o los eventos de la sesión.
El adaptador duradero requiere la topología completa del flujo de trabajo y del agente durante la construcción de la aplicación. Esta es la misma restricción de topología estática que el adaptador de grafos LangGraph duradero: un flujo de control arbitrario en tiempo de ejecución no puede tratarse como un límite de grafo duradero una vez que su trabajo externo ya ha comenzado.
Característica ADK | Soporte duradero |
|---|---|
Raíz simple | Admitido |
Nodos | Admitido |
Gráficos | Admitido |
Configurado | Admitido |
Nodos de agente de flujo de trabajo con transferencias configuradas | Compatible cuando el agente propietario utiliza |
Niños públicos | Rechazado antes de la ejecución; utilice |
Modelo, herramienta y actividad de espera dentro de los nodos configurados. | Admitido |
Nodos creados por la aplicación que se pasan a | Rechazado antes de que se ejecute el proceso dinámico infantil. |
| Rechazado antes de que su hijo corra |
Objetivos creados en tiempo de ejecución pasados a | Rechazado antes de que se ejecute el proceso dinámico infantil. |
Herramientas ordinarias | Compatible; los hijos |
Antes de ejecutar un nodo, ADK le asigna un valor canónico Context.node_path. ADK utiliza ese mismo valor para la contabilidad del flujo de trabajo y lo registra en los eventos emitidos como Event.node_info.path. El adaptador envuelve el límite público BaseNode.run para que la admisión de actividad del modelo y de la herramienta pueda usar la ruta antes de que exista un evento.
ADK node path: outer@1/inner@1/review@1 OE path: agent -> inner -> review
La raíz ADK configurada (outer@1) se asigna a la raíz agent existente de OE. Los segmentos restantes se convierten en límites secundarios, y sus prefijos ADK completos siguen siendo las claves de ocurrencia:
inner occurrence: outer@1/inner@1 review occurrence: outer@1/inner@1/review@1
Para un left y un right paralelos, cada envoltorio de nodo vincula su propia ruta canónica en un contexto local de solicitud, por lo que el orden de finalización no puede intercambiar sus identidades OE. Una herramienta llamada por review hereda el ámbito review. Si review emite una espera, su evento lleva la misma ruta y la suspensión registra los mismos límites después de que finaliza el ámbito del nodo activo. Los nombres de hoja iguales bajo diferentes ancestros de flujo de trabajo permanecen distintos porque la identidad proviene de la ruta completa, no de una búsqueda de nombre global. Las rutas de nodo mal formadas y los eventos de espera sin una ruta de nodo fallan explícitamente.
Subagentes configurados
Una transferencia es una selección en tiempo de ejecución de un borde sub_agents ya configurado. La respuesta del modelo le indica a ADK qué proceso hijo ejecutar, pero el adaptador espera a que ADK acceda a ese proceso hijo y utiliza la ruta canónica que ADK asignó a la ejecución. Por ejemplo:
configured: router -> reviewer -> specialist ADK path: router@1/reviewer@1/specialist@1 OE path: agent -> reviewer -> specialist
Las transferencias repetidas reciben nuevos ID de ejecución de ADK. El adaptador reserva el límite secundario seleccionado cuando ADK entra en él, por lo que dos visitas a specialist se convierten en los ordinales 1 y 2 de specialist, incluso si el mismo objeto de agente configurado se ejecuta en ambas ocasiones.
Se admite un árbol de agentes configurado como raíz de la aplicación o dentro de un nodo de flujo de trabajo. Un agente de flujo de trabajo que posee sub_agents debe usar explícitamente mode="chat". De lo contrario, ADK asigna por defecto ese nodo a single_turn, que ejecuta una transferencia una vez dentro del agente y otra vez desde el flujo de trabajo contenedor. El adaptador rechaza ese ciclo de vida durante la construcción de la sesión duradera en lugar de permitir efectos secundarios duplicados. En el desarrollo local, este error aparece en la primera invocación del entorno de pruebas, antes de que comience la actividad del modelo o la herramienta.
En el modo de chat, cada transferencia configurada permanece en el ciclo de vida del nodo público único de ADK. El adaptador vincula la ruta de nodo canónica completa, incluyendo la ascendencia del flujo de trabajo y la cadena de agentes activos, antes de que comience la actividad del modelo, la herramienta o la suspensión. ADK clona los nodos de agente al entrar en el flujo de trabajo, por lo que el enrutamiento se instala en el límite público BaseNode.run y se selecciona a través del estado del adaptador local de la solicitud. Las plantillas configuradas solo contienen una procedencia opaca que ADK copia en sus clones, lo que permite al adaptador rechazar un nodo del mismo nombre y tipo creado dinámicamente en tiempo de ejecución.
Al reanudarse, las transferencias configuradas en caché permanecen dentro del bucle de transferencias de ADK, y un destino de transferencia en espera resuelto se ejecuta hasta su finalización. Esto preserva la respuesta final del agente en lugar de exponer el valor de reanudación sin procesar como salida del flujo de trabajo.
Un árbol de colaboración de agentes puede comenzar en cualquier nodo de agente configurado estáticamente en un grafo de flujo de trabajo anidado, serial o paralelo. Esto no admite agentes ni otros nodos creados dinámicamente a través de Context.run_node(); estos permanecen rechazados antes de que comience su ejecución.
agent root: router agent -> reviewer -> specialist composed: outer Workflow -> router agent -> reviewer -> specialist
Las transferencias permanecen dentro del árbol de agentes configurado, con raíz en ese nodo de flujo de trabajo, sujetas a las reglas de transferencia de agentes de ADK; un flujo de trabajo no es un destino de transferencia. Cuando el árbol de agentes finaliza, el control regresa al planificador de flujo de trabajo y continúa a lo largo del gráfico configurado.
AgentTool Está intencionalmente fuera de esta característica. ADK ejecuta su proceso hijo a través de un Runner privado, por lo que el proceso hijo no hereda la ruta de nodo canónica ni el límite de espera externo del proceso que lo llama. Para admitir ese ciclo de vida se requiere un puente duradero independiente; el adaptador actual falla antes de la ejecución en lugar de inferir una ruta.
Retroceso de nivel de giro
App.runner es el ejecutor ADK público y estable de Atlas Agent Engine. Su método rewind_async() mantiene los nombres de argumentos documentados por Google y asigna rewind_before_invocation_id directamente a una rama de sesión de OE:
branch = await app.runner.rewind_async( user_id="user-1", session_id="session-1", rewind_before_invocation_id="execution-3", )
Una invocación de ADK es una ejecución de OE, por lo que rewind apunta solo a turnos completos. La llamada debe ejecutarse dentro de una invocación duradera activa, y session_id debe nombrar la sesión de esa invocación. El SDK envía el ID de ejecución actual a través de la ruta de devolución de llamada de ejecución existente de OE. OE carga esa ejecución para derivar su organización, proyecto, espacio de trabajo y sesión; el cliente no envía esas coordenadas ni intenta credenciales. El ID de ejecución tiene el mismo rol que tiene para las devoluciones de llamada de flujo, resultado de herramienta y ejecutor: enruta una solicitud que ya está dentro del límite de confianza de devolución de llamada de carga de trabajo a OE y no es una credencial de administración pública. En una transacción, OE verifica que la ejecución todavía tiene una concesión duradera activa, resuelve la primera ejecución a excluir en la misma sesión y copia el estado terminal del turno anterior en una nueva sesión inactiva. Para rebobinar un turno en una sesión ancestro, invoque esa sesión ancestro y solicite su bifurcación directamente; la sesión hija no hereda autoridad para modificar el historial ancestro. La respuesta contiene el nuevo session_id y el pendiente execution_id; la siguiente invocación ordinaria en esa sesión reclama la ejecución pendiente con la solicitud de usuario de reemplazo.
Esto extiende intencionalmente el contrato de retorno de ADK. ADK nativo modifica la sesión especificada y devuelve None; Atlas Agent Engine mantiene esa sesión inmutable y devuelve SessionForkResponse para que quien la llama pueda seguir usando los nuevos session_id y execution_id. El nombre del método y los argumentos siguen siendo la interfaz documentada de ADK, pero app.runner es un tipo propiedad de Atlas Agent Engine con la anotación de retorno correcta. El Runner de Google sigue siendo un detalle de ejecución privado, con ámbito de intento. Los turnos ordinarios siguen entrando a través de la interfaz de invocación de la plataforma; el runner público no crea una ruta de ejecución alternativa.
El adaptador no analiza los eventos de ADK, no mantiene un catálogo de ejecución, no calcula un ordinal de paso, no envía bytes de instantánea ni elige una clave de rama. Retroceder antes del primer turno, nombrar un ID de evento o apuntar a un turno propiedad de otra sesión falla. Llamar a rewind_async() fuera de una invocación duradera activa también falla; no se admite el retroceso administrativo fuera de turno. Cada reintento es una nueva solicitud de rama; no hay clave de idempotencia del cliente.
Inicio rápido
Instalación
pip install agent-engine-sdk-adk
O en un proyecto UV:
uv add agent-engine-sdk-adk
Desarrollo
Requisitos
Python >= 3.11
Google ADK >= 2.4.0, < 3
Configuración del desarrollador
uv sync --extra dev
Pruebas
./scripts/test.sh agent-engine-sdk-adk
El conjunto de herramientas propiedad del repositorio sincroniza el paquete del espacio de trabajo y ejecuta Ruff, Pyright y pytest utilizando la misma ruta que la integración continua (CI).
Copyright 2026 MongoDB, Inc. Licenciado bajo la Licencia Apache, Versión 2.0.