Crie um agente com o Google ADK

Neste guia, você pode aprender como criar e executar um agente com o Google Agent Development Kit (ADK). O pacote agent-engine-sdk-adk é um adaptador entre o ADK e o mecanismo de agente do MongoDB Atlas. O adaptador traduz agentes ADK, nós de fluxo de trabalho e chamadas de ferramenta em operações que o Mecanismo de Orquestração da plataforma executa e registra.

O adaptador é durável, portanto, os agentes ADK executam no modo de fluxo de trabalho durável. O Orchestration Mecanismo, não o ADK, armazena o estado de cada sessão. A plataforma também armazena os resultados de cada chamada de modelo e chamada de FERRAMENTAS. Uma execução retomada reproduz os resultados registrados em vez de repetir as ações de execução.

Considerações sobre o Google ADK

Ao criar um agente ADK no Atlas Agent mecanismo, considere os seguintes pontos principais:

O Google ADK SDK está disponível apenas para Python. Para criar um agente em Typescript, consulte o guia do SDK Typescript.
Seu agente deve definir o valor features.durable_workflow como true no arquivo agent.yaml. Se você omitir esse campo ou defini-lo como false, a primeira invocação falhará. Para saber mais sobre os campo disponíveis no arquivo agent.yaml, consulte o esquema agent.yaml.
O pacote agent-engine-sdk-adk aceita um BaseAgent do ADK ou um 2 Workflow do ADK como a raiz do seu agente.

Pré-requisitos

Certifique-se de ter os seguintes pré-requisitos antes de começar:

Python 3.11 ou posterior.
uv gerenciador de pacotes.
CLI agentengine instalada e autenticada. Para aprender como, consulte Criar um projeto.
Google ADK versão 2.9.0 ou posterior. Para aprender como instalar o ADK, consulte a documentação de instalação do ADK.
Chave de API para o seu provedor de LLM. O comando agentengine create solicita a chave e a salva no seu arquivo .env como LLM_API_KEY.

Passos

Crie um projeto a partir de um modelo inicial do ADK.

Execute o comando agentengine create com um dos modelos ADK:

agentengine create --template hello-world-agent-adk

O modelo hello-world-agent-adk cria um agente mínimo. O modelo insurance-agent-adk cria um agente de domínio de seguros. Para aprender sobre todos os modelos disponíveis e opções de comando agentengine create, consulte Modelos Suportados.

Revise o código do modelo.

Abra o módulo de ponto de entrada no seu projeto. O modelo já registra uma ferramenta e criar o agente. O módulo usa os seguintes recursos do SDK:

@app.tool(): Registra uma função como uma ferramenta na plataforma. O decorador não expõe automaticamente a ferramenta ao seu agente.
@app.entrypoint: Marca a função que retorna seu agente ADK.
app.llm(): Envolve uma instância BaseLlm do ADK para que a plataforma audite cada chamada de modelo.
app.tools(): Retorna suas FERRAMENTAS registradas com o wrapper seguro da plataforma aplicado.

Importante

Passe as FERRAMENTAS que a função app.tools() retorna para o seu agente, não as funções que você decora com @app.tool().

Execute o agente localmente.

No diretório do seu agente, execute o seguinte comando para iniciar o ambiente de desenvolvimento local:

agentengine dev up

Para aprender sobre os modos hot-reload e isolado, consulte Executar e testar seu agente localmente.

Implantar o agente.

Execute o seguinte comando para criar e implantar seu agente em uma única etapa:

agentengine deploy --auto

O agente implantado também requer sua chave de API de LLM. Para aprender como fornecer segredos a um agente implantado, consulte Provisionamento de segredos na nuvem.

Para aprender como criar e implantar como etapas separadas, consulte Criar a imagem do agente e Implantar sua compilação.

Adicionar revisar humano a uma ferramenta

Para pausar uma execução até que um humano aprove um chamar de ferramenta, envolva uma função de ferramenta chamável na classe ADK FunctionTool e passe a opção require_confirmation=True para o construtor. Para pausar uma execução e coletar uma entrada diferente de uma aprovação, use a classe ADK LongRunningFunctionTool. Envolva as funções de ferramenta chamáveis que app.tools() retorna, não as funções brutas que você decora com @app.tool().

O exemplo a seguir envolve cada ferramenta chamável que app.tools() retorna na classe FunctionTool, para que cada chamar de ferramenta aguarde a aprovação humana antes de ser executada:

import os
from google.adk.agents import LlmAgentfrom google.adk.models.lite_llm import LiteLlmfrom google.adk.tools.function_tool import FunctionTool
@app.entrypointdef build_agent():    return LlmAgent(        name="daily",        instruction="You are a helpful assistant.",        model=app.llm(            LiteLlm(                model="<model-name>",                api_key=os.environ["LLM_API_KEY"],            )        ),        tools=[            FunctionTool(tool, require_confirmation=True)            for tool in app.tools()        ],    )

Observação

As FERRAMENTAS MCP remotas que app.tools() retorna são objetos ADK BaseTool, não chamáveis simples, portanto, você não pode envolvê-los com a classe FunctionTool. A plataforma rege as chamadas de FERRAMENTAS MCP por meio da política e das proteções do mecanismo de orquestração.

Responder a solicitações de ferramentas

Uma resposta de confirmação tem a sintaxe de objeto ADK {confirmed: true|false}. A plataforma registro cada pausa como uma atividade do mecanismo de orquestração e usa o ID da atividade como o ID de interrupção.

Para retomar uma execução pausada, envie uma solicitação ao ponto de extremidade de invocação na mesma sessão. Na solicitação, inclua um objeto resume_map que mapeia o ID de cada pausa pendente para sua resposta. Você deve dar uma resposta a todas as pausas pendentes na mesma solicitação. Para encontrar os IDs, leia a lista suspend_context.interrupts da execução pausada. Para saber mais, consulte Invocation API.

O seguinte exemplo de corpo de solicitação resposta a duas pausas pendentes. A primeira resposta aprova uma chamar de ferramenta que requer confirmação. A segunda resposta retorna a entrada que uma ferramenta pausada diferente solicitou.

{  "resume_map": {    "<activity-id-1>": { "confirmed": true },    "<activity-id-2>": "us-east-1"  }}

Para retomar a partir da CLI, use as opções --session e --resume do comando agentengine invoke. Para aprender mais, consulte Invocar um agente a partir da CLI.

Observação

Os agente ADK são executados no modo de fluxo de trabalho durável, portanto, você os retoma com uma solicitação resume_map e não com o corpo da solicitação decision descrito no guia Human-in-the-Loop.

Estruturas de agente suportadas

O pacote agent-engine-sdk-adk requer a estrutura completa de Workflow e agente quando seu agente é iniciado. A plataforma faz o registro de cada etapa por seu caminho nessa estrutura. A tabela a seguir lista os recurso do ADK que o pacote agent-engine-sdk-adk suporta:

Recurso ADK	Suporte
Raiz `BaseAgent` simples	Suportado
Nós de `Workflow` configurados estaticamente, incluindo grafos seriais e paralelos aninhados	Suportado
Parâmetro `sub_agents` configurado, onde o modelo seleciona o agente filho para executar chamando a função `transfer_to_agent`	Suportado
Nós de agente de fluxo de trabalho com transferências configuradas	Suportado quando o agente usa `mode="chat"`
Agentes envolvidos com a classe `AgentTool`	Rejeitado antes da execução. Use `sub_agents` configurado em vez disso.
`NodeTool` e nós passados para `run_node()` em tempo de execução	Rejeitado com um erro antes que o agente ou nó aninhado seja iniciado.

Adicionar outros recursos da plataforma

Os seguintes recursos da plataforma funcionam com agentes ADK:

Servidores MCP remotos que você declara no campo mcp do arquivo agent.yaml. A plataforma descobre as FERRAMENTAS na inicialização e as retorna de app.tools(). Para aprender mais, consulte Usar servidores MCP remotos.
Revisar de saída do guardrail. Um guardrail llm_output com a ação require_review pausa o chamar do modelo até que um revisor aprove ou negue a saída. Revise a saída por meio da solicitação resume_map.

Saiba mais

Voltar

Criar um Deep Agente