Adaptador 2 do Google ADK para o SDK do MongoDB Atlas Agent Engine.
O adaptador é durável somente no modo AER. Defina features.durable_workflow: true em agent.yaml. Omitido ou false não volta para uma sessão nativa do ADK; a primeira invocação falha. O Mecanismo de orquestração possui o estado de rotação cruzada e o fornece a cada tentativa; o adaptador não mantém um banco de dados de sessão ADK separado . Conceitos de plataforma, habilitação e a regra de identidade por trás dos limites de topologia abaixo: Fluxo de trabalho durável. O Atlas Agent Engine ctx.resume não é uma retomada do checkpoint do ADK. Rotas ADK paralelas podem ser suspensas juntas; o adaptador os coleta por meio da inatividade do executor e confirma uma fronte de espera OE atômica. Uma vez que essa limite seja atendida, sua etapa é confirmada e o ADK pode continuar em outra limite serial ou paralela.
Suspender e retomar
Os autores compõem esperas nativas do ADK no construtor de agente com os construtores oficiais `FunctionTool(..., require_confirmation=True) <https://adk.dev/graphs/Human-input/#tool-confirmation-approval-prompts-in-llm-agents>`__ e LongRunningFunctionTool. Passe as chamadas de app.tools(), não da função @app.tool bruta: @app.tool apenas registra a ferramenta; app.tools() é o que aplica o wrapper seguro do Atlas Agent Engine. O Atlas Agent Engine registra cada espera como uma atividade OE e finaliza a borda completa em um comando. As IDs de interrupção do Atlas Agent Engine são essas IDs de atividade, não as IDs de chamada de função do ADK. Continuar requer um resume_map completo; é uma nova tentativa que transmite a mensagem original do usuário novamente; OE retorna a resposta registrada; o adaptador alimenta o ADK com um lote de partes FunctionResponse codificadas pelas IDs de chamada de função desta execução. Não há o Mecanismo Atlas app.suspend(). Uma resposta de confirmação é o objeto{confirmed: true|false} do ADK. Uma resposta RequestInput é qualquer que seja o que o FunctionResponse.response dic do ADK aceite: um objeto JSON ou uma escalar/array não nula que o adaptador envolve como {result: ...}. JSON null não é uma resposta.
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
Local | Função |
|---|---|
|
|
| Corredor de ADK público estável e ponte |
| Vincule a tentativa de OE, reconstrua a mensagem original e identifique a limite de retomada atual |
| Percorrer |
| Continue através das bordas resolvidas até a próxima espera ou conclusão recente |
| Vincular caminhos de nó canônicos do ADK a caminhos de operação duráveis compartilhados |
| Reserve transferências de subagente configuradas em seus caminhos pai canônicos |
| Mapeie as esperas nativas para uma borda ordenada e crie o lote de resposta |
| Finalize todas as esperas atomicamente e corresponda os resultados da OE por posição durável |
|
|
| O prefixo LLM e as ferramentas são atividades do Atlas Agent Engine, portanto, continuar não executa novamente esses efeitos colaterais |
O adaptador aceita um ADK BaseAgent ou um ADK 2 Workflow. O ADK não define um ciclo de vida superstep no estilo LangGraph. Portanto, o Atlas Agent Engine introduz uma etapa somente em uma borda de coordenação inativa: todas as esperas nessa borda se juntam atomicamente, a borda resolvida confirma sua etapa e a próxima continuação Runner.run_async inicia a próxima etapa.
Fluxo de trabalho e caminhos do agente
O ADK expõe a composição Workflow e a colaboração de agente por meio de diferentes APIs de configuração, mas as execuções configuradas se encontram no mesmo primitivo de tempo de execução: os nós e os agentes de fluxo de trabalho são instâncias BaseNode e o ADK atribui a cada execução um Context.node_path canônico. O adaptador mapeia esse caminho para o caminho de operação OE; não reconstrói a ascendência do agente a partir de texto de modelo ou eventos de sessão.
O adaptador durável requer o fluxo de trabalho completo e a topologia do agente na construção do aplicação . Esta é a mesma restrição de topologia estática que o adaptador de gráfico durável LangGraph: o fluxo arbitrário de controle de tempo de execução não pode ser tratado como um limite de gráfico durável depois que seu trabalho externo já começou.
Funcionalidade ADK | Suporte durável |
|---|---|
Raiz de | Suportado |
Nós | Suportado |
Gráficos | Suportado |
| Suportado |
Nós do agente de fluxo de trabalho com transferências configuradas | Compatível quando o agente proprietário usa |
Filhos públicos | Rejeitado antes da execução; usar |
Modele, utilize ferramentas e a atividade de espera dentro de nós configurados | Suportado |
Nós criados pelo aplicativo passados para | Rejeitado antes da execução do secundário dinâmico |
| Rejeitado antes que seu filho seja executado |
As metas criadas pelo tempo de execução passadas para | Rejeitado antes da execução do secundário dinâmico |
Ferramentas comuns do | Suportado; resolvidos filhos |
Antes de executar um nó, o ADK atribui a ele um Context.node_path canônico. O ADK usa o mesmo valor para a contabilidade do Workflow e o registra em eventos emitidos como Event.node_info.path. O adaptador envolve o limite público BaseNode.run para que a entrada de atividade de modelo e ferramenta possa usar o caminho antes que um evento exista.
ADK node path: outer@1/inner@1/review@1 OE path: agent -> inner -> review
A raiz ADK configurada (outer@1) mapeia para a raiz agent existente da OE. Os segmentos restantes se tornam limites filhos e seus prefixos ADK completos permanecem as chaves de ocorrência:
inner occurrence: outer@1/inner@1 review occurrence: outer@1/inner@1/review@1
Para left e right paralelos, cada wrapper de nó vincula seu próprio caminho canônico em um contexto de solicitação local, portanto, a ordem de conclusão não pode trocar suas identidades OE. Uma ferramenta chamada por review herda o escopo review. Se review emitir uma wait, seu evento carregará o mesmo caminho e a suspensão registrará os mesmos limites após o término do escopo do nó ativo. Nomes de folha iguais sob diferentes ancestrais do Workflow permanecem distintos porque a identidade vem do caminho completo, não de uma pesquisa de nome global. Caminhos de nó malformados e eventos de espera sem um caminho de nó falham explicitamente.
Subagentes configurados
Uma transferência é uma seleção de tempo de execução de uma borda sub_agents já configurada. A resposta do modelo informa ao ADK qual filho deve ser executado, mas o adaptador aguarda que o ADK insira esse filho e usa o caminho canônico atribuído ao ADK para a execução. Por exemplo:
configured: router -> reviewer -> specialist ADK path: router@1/reviewer@1/specialist@1 OE path: agent -> reviewer -> specialist
Transferências repetidas recebem novos IDs de execução do ADK. O adaptador reserva o limite filho selecionado quando o ADK entra nele, portanto, duas visitas a specialist se tornam specialist ordinais 1 e 2, mesmo que o mesmo objeto de agente configurado execute as duas vezes.
Uma árvore de agente configurada é suportada como raiz do aplicação ou dentro de um nó de Fluxo de Trabalho. Um agente de fluxo de trabalho que possui sub_agents deve usar explicitamente mode="chat". Caso contrário, o ADK padroniza esse nó para single_turn, que executa uma transferência uma vez dentro do agente e novamente do fluxo de trabalho contêiner. O adaptador rejeita esse ciclo de vida durante a construção de uma sessão durável, em vez de permitir efeitos secundários duplicados. No desenvolvimento local, este erro aparece na primeira invocação do playground, antes do início da atividade do modelo ou da ferramenta.
No modo de chat, cada transferência configurada permanece no ciclo de vida de um nó público do ADK. O adaptador vincula o caminho canônico completo do nó, incluindo a ancestralidade do Workflow e a cadeia de agente ativos, antes do início da atividade do modelo, ferramenta ou suspensão. O ADK clona os nós de agente ao entrar no fluxo de trabalho, portanto, o roteamento é instalado no limite público BaseNode.run e selecionado por meio do estado do adaptador local de solicitação. Os modelos configurados carregam apenas a procedência opaca que o ADK copia para seus clones, permitindo que o adaptador rejeite um nó do mesmo nome e tipo criado dinamicamente no tempo de execução.
Na retomada, as transferências configuradas em cache permanecem dentro do loop de transferência do ADK e um destino de transferência em espera resolvido é executado até a conclusão. Isso preserva a resposta final do agente em vez de expor o valor bruto de retomada como saída do fluxo de trabalho.
Uma árvore de colaboração de agente pode começar em qualquer nó de agente configurado estaticamente em um gráfico de fluxo de trabalho aninhado, serial ou paralelo. Isso não aceita agentes ou outros nós criados dinamicamente por meio de Context.run_node(); aqueles permanecem rejeitados antes do início da execução.
agent root: router agent -> reviewer -> specialist composed: outer Workflow -> router agent -> reviewer -> specialist
As transferências permanecem dentro da árvore de agente configurada enraizada nesse nó do Fluxo de Trabalho, sujeitas às regras de transferência de agentes do ADK; um fluxo de trabalho não é um destino de transferência. Quando a árvore de agente é concluída, o controle retorna ao Agendador de Fluxo de Trabalho e continua ao longo do gráfico configurado.
AgentTool está intencionalmente fora desse recurso. O ADK executa seu filho por meio de um Corredor privado, para que o filho não herde o caminho do nó canônico do chamador ou a borda de espera externa. O suporte a esse ciclo de vida requer uma ponte durável separada; o adaptador atual falha antes da execução em vez de inferir um caminho.
Recuo no nível da curva
App.runner é o executor ADK público estável do Atlas Agent Engine. Seu método rewind_async() mantém os nomes de argumento documentados do Google e mapeia rewind_before_invocation_id diretamente para uma ramificação de sessão OE:
branch = await app.runner.rewind_async( user_id="user-1", session_id="session-1", rewind_before_invocation_id="execution-3", )
Uma invocação de ADK é uma execução de OE, portanto, o rewind tem como alvo apenas voltas inteiras. A chamada deve ser executada dentro de uma invocação ativa durável e session_id deve nomear a sessão dessa invocação. O SDK envia o ID de execução atual pela rota de chamada de resposta de execução existente da OE. O OE carrega essa execução para derivar sua organização, projeto, espaço de trabalho e sessão; o cliente não envia essas coordenadas nem tenta credenciais. O ID de execução tem a mesma função que para retornos de chamada de fluxo, resultado de ferramenta e executor: ele encaminha uma solicitação já dentro do limite de confiança de chamada de resposta de volume de trabalho para OE e não é uma credencial de gerenciamento público. Em uma transação, a OE verifica se a execução ainda tem um leasing durável ativo, resolve a primeira execução a ser excluída na mesma sessão e copia o estado terminal do retorno anterior para uma nova sessão inativa. Para retroceder uma reviravolta em uma sessão de ancestral, invoque essa sessão de ancestral e solicite sua bifurcação diretamente; a sessão filho não herda autoridade para modificar o histórico ancestral. A resposta contém o novo session_id e execution_id pendente; a próxima invocação comum nessa sessão afirma a execução pendente com a solicitação do usuário de substituição.
Isso estende intencionalmente o contrato de devolução do ADK. O ADK nativo muta a sessão especificada e retorna None; O Atlas Agent Engine mantém essa sessão imutável e retorna SessionForkResponse para que o chamador possa continuar usando os novos session_id e execution_id. O nome do método e os argumentos permanecem a interface documentada do ADK, mas app.runner é um tipo de propriedade do Atlas Agent Engine com a anotação de retorno correta. O Runner do Google continua sendo um detalhe de execução privado com escopo de tentativa. As voltas comuns ainda entram pela interface de invocação da plataforma; o executor público não cria um caminho de execução alternativo.
O adaptador não verifica eventos ADK, mantém um catálogo de execução, calcula um ordinal de etapa, envia bytes de snapshot ou escolhe uma chave de ramificação. Há falha ao retroceder antes do primeiro retorno, nomear um ID de evento ou direcionar um retorno de propriedade de outra sessão. Chamar rewind_async() fora de uma invocação ativa durável também falha; o retrocesso administrativo fora de hora não é suportado. Cada nova tentativa é uma nova solicitação de ramificação; não há chave de idempotência do cliente .
Início rápido
Instalação
pip install agent-engine-sdk-adk
Ou em um projeto uv:
uv add agent-engine-sdk-adk
Desenvolvimento
Requisitos
Python >= 3.11
Google ADK >= 2.4.0, < 3
Configuração do desenvolvedor
uv sync --extra dev
Teste
./scripts/test.sh agent-engine-sdk-adk
O conjunto de propriedade do repositório sincroniza o pacote do espaço de trabalho e executa Ruff, Pyright e pytest usando o mesmo caminho do CI.
direitos reservados 2026 MongoDB, Inc. licenciada sob a licença Apache, versão 2.0.