GENAI106

Visão geral

Este laboratório vai abordar a orquestração de sistemas multiagentes usando o Kit de Desenvolvimento de Agente (ADK) do Google.

Neste laboratório, vamos supor que você já conhece os conceitos básicos do ADK e o uso de ferramentas, conforme abordado nos laboratórios:

• Introdução ao Kit de Desenvolvimento de Agente (ADK) do Google
• Capacitar os agentes do ADK com ferramentas

Objetivo

Neste laboratório, você vai aprender sobre sistemas multiagentes usando o Kit de Desenvolvimento de Agentes.

Após este laboratório, você poderá:

• Definir vários agentes e relacioná-los entre si com hierarquia de agente principal para subagente
• Criar conteúdo em várias interações de conversa e vários agentes gravando no dicionário de estado de uma sessão
• Instruir os agentes a ler valores do estado da sessão para usar como contexto nas respostas
• Usar agentes de fluxo de trabalho para transmitir a conversa entre agentes diretamente

Configuração e requisitos

Antes de clicar no botão Start Lab

Leia estas instruções. Os laboratórios são cronometrados e não podem ser pausados. O timer, que é iniciado quando você clica em Start Lab, mostra por quanto tempo os recursos do Cloud ficarão disponíveis.

Este laboratório prático do Qwiklabs permite que você realize as atividades em um ambiente real de nuvem, não em um ambiente simulado ou de demonstração. Isso é possível porque você recebe credenciais novas e temporárias para fazer login e acessar o Google Cloud Platform durante o laboratório.

O que é necessário

Para fazer este laboratório, você precisa ter:

• acesso a um navegador de Internet padrão (recomendamos o Chrome);
• tempo para concluir todas as atividades.

Observação: não use um projeto seu nem uma conta pessoal do GCP neste laboratório.

Como iniciar seu laboratório e fazer login no console do Google Cloud

1. Clique no botão Começar o laboratório. Se for preciso pagar por ele, uma caixa de diálogo vai aparecer para você selecionar a forma de pagamento. No painel Detalhes do Laboratório, à esquerda, você vai encontrar o seguinte:

   • O botão Abrir Console do Google Cloud
   • O tempo restante
   • As credenciais temporárias que você vai usar neste laboratório
   • Outras informações, se forem necessárias

2. Se você estiver usando o navegador Chrome, clique em Abrir console do Google Cloud ou clique com o botão direito do mouse e selecione Abrir link em uma janela anônima.

   O laboratório ativa os recursos e depois abre a página Fazer Login em outra guia.

   Dica: coloque as guias em janelas separadas lado a lado.

   Observação: se aparecer a caixa de diálogo Escolher uma conta, clique em Usar outra conta.

3. Se necessário, copie o Nome de usuário abaixo e cole na caixa de diálogo Fazer login.

   {{{user_0.username | "Username"}}}

   Você também encontra o nome de usuário no painel Detalhes do Laboratório.

4. Clique em Próxima.

5. Copie a Senha abaixo e cole na caixa de diálogo de Olá.

   {{{user_0.password | "Password"}}}

   Você também encontra a senha no painel Detalhes do Laboratório.

6. Clique em Próxima.

   Importante: você precisa usar as credenciais fornecidas no laboratório, e não as da sua conta do Google Cloud. Observação: se você usar sua própria conta do Google Cloud neste laboratório, é possível que receba cobranças adicionais.

7. Acesse as próximas páginas:

   • Aceite os Termos e Condições.
   • Não adicione opções de recuperação nem autenticação de dois fatores (porque essa é uma conta temporária).
   • Não se inscreva em testes gratuitos.

Depois de alguns instantes, o console do Google Cloud será aberto nesta guia.

Observação: para acessar os produtos e serviços do Google Cloud, clique no Menu de navegação ou digite o nome do serviço ou produto no campo Pesquisar.

Sistemas multiagentes

Com o Kit de Desenvolvimento de Agente, os desenvolvedores alcançam comportamentos mais confiáveis, sofisticados e multietapas dos modelos generativos. em vez de escrever comandos longos e complexos, em que os resultados podem não ser confiáveis, é possível criar um fluxo com agentes simples, que podem colaborar com problemas complexos, dividindo as tarefas e as responsabilidades.

Essa abordagem arquitetônica oferece várias vantagens importantes, como:

• Mais fácil de projetar: você pode pensar em termos de agentes com trabalhos e habilidades específicas.
• Funções especializadas com desempenho mais confiável: os agentes especializados podem aprender com exemplos claros para se tornarem mais confiáveis em suas tarefas específicas.
• Organização: dividir o fluxo de trabalho em agentes distintos permite uma abordagem mais organizada e, portanto, mais fácil de pensar.
• Melhoria e manutenção: é mais fácil melhorar ou corrigir um componente especializado do que fazer mudanças em um agente complexo que pode corrigir um comportamento, mas afetar outros.
• Modularidade: agentes distintos de um fluxo de trabalho podem ser facilmente copiados e incluídos em outros fluxos de trabalho semelhantes.

A árvore hierárquica de agentes

No Kit de Desenvolvimento de Agente, você organiza seus agentes em uma estrutura em árvore. Isso ajuda a limitar as opções de transferência para cada agente na árvore, facilitando o controle e a previsão das possíveis rotas que a conversa pode seguir na árvore. Os benefícios da estrutura hierárquica incluem:

• Ela se inspira em equipes colaborativas do mundo real, facilitando o design e o raciocínio sobre o comportamento do sistema multiagente.
• Ela é intuitiva para desenvolvedores, porque espelha padrões comuns de desenvolvimento de software.
• Oferece mais controle sobre o fluxo de informações e a delegação de tarefas no sistema, facilitando a compreensão dos possíveis caminhos e a depuração do sistema. Por exemplo, se um sistema tiver dois agentes de geração de relatórios em diferentes partes do fluxo com descrições semelhantes, a estrutura em árvore facilita a invocação do agente correto.

A estrutura sempre começa com o agente definido na variável root_agent (embora ele possa ter um nome de voltado ao usuário diferente para se identificar). O root_agent pode atuar como pai de um ou mais subagentes. Cada subagente pode ter os próprios subagentes.

Tarefa 1: instalar o ADK e configurar o ambiente

Observação: o recomendado é usar uma janela de navegação anônima na maioria dos laboratórios do Qwiklabs para evitar confusão entre sua conta de estudante do Qwiklabs e outras contas conectadas ao Google Cloud. Se você estiver usando o Chrome, a maneira mais fácil de fazer isso é fechar todas as janelas anônimas, clicar com o botão direito do mouse no botão **Abrir console do Google Cloud** na parte de cima do laboratório e selecionar **Abrir link em uma janela anônima**.

Ative as APIs recomendadas da Vertex AI

1. Neste ambiente de laboratório, a API Vertex AI já foi ativada para você. Se você seguisse essas etapas no seu próprio projeto, poderia ativar o recurso navegando até a Vertex AI e seguindo o comando para ativá-lo.

Prepare uma guia do editor do Cloud Shell

1. Com a janela do console do Google Cloud selecionada, abra o Cloud Shell pressionando as teclas G e S no teclado. Como alternativa, clique no botão "Ativar o Cloud Shell" () no canto superior direito do console do Cloud.

2. Clique em Continuar.

3. Se for preciso autorizar o Cloud Shell, clique em Autorizar.

4. No canto superior direito do painel do terminal do Cloud Shell, clique no botão Abrir em uma nova janela .

5. No terminal do Cloud Shell, insira o seguinte código para abrir o Editor no seu diretório principal:

   cloudshell workspace ~

6. Feche qualquer outro tutorial ou painel do Gemini que apareça no lado direito da tela. Assim você terá mais espaço na janela do editor de código.
7. Durante o restante deste laboratório, você pode trabalhar nesta janela como seu ambiente de desenvolvimento integrado com o editor do Cloud Shell e o terminal do Cloud Shell.

Baixe e instale o ADK e os exemplos de código para este laboratório

1. Cole os comandos a seguir no terminal do Cloud Shell para copiar arquivos de código de um bucket do Cloud Storage para este laboratório:

   gcloud storage cp -r gs://{{{project_0.project_id| YOUR_GCP_PROJECT_ID}}}-bucket/adk_multiagent_systems .

2. Atualize a variável de ambiente PATH, instale o ADK e instale outros requisitos do laboratório executando os comandos a seguir no terminal do Cloud Shell.

   export PATH=$PATH:"/home/${USER}/.local/bin" python3 -m pip install google-adk -r adk_multiagent_systems/requirements.txt

Tarefa 2: criar transferências entre os agentes principais, secundários e pares

A conversa sempre começa com o agente definido como a variável root_agent.

O comportamento padrão de um agente principal é entender a descrição de cada subagente e determinar se o controle da conversa deve ser transferido para um deles em algum momento.

Você pode orientar essas transferências no código de instruction do agente principal. Basta indicar os subagentes por nome (os valores do parâmetro name, não os nomes das variáveis). Testar um exemplo:

1. No terminal do Cloud Shell, execute o código a seguir para criar um arquivo .env e autenticar o agente no diretório parent_and_subagents.

   cd ~/adk_multiagent_systems cat << EOF > parent_and_subagents/.env GOOGLE_GENAI_USE_VERTEXAI=TRUE GOOGLE_CLOUD_PROJECT={{{project_0.project_id| YOUR_GCP_PROJECT_ID}}} GOOGLE_CLOUD_LOCATION={{{project_0.default_region| GCP_LOCATION}}} MODEL=gemini-2.5-flash EOF

2. Execute o comando a seguir para copiar o arquivo .env para o diretório workflow_agents, que você vai usar mais tarde no laboratório:

   cp parent_and_subagents/.env workflow_agents/.env

3. No painel de análises do Editor do Cloud Shell, acesse o diretório adk_multiagent_systems/parent_and_subagents.

4. Clique no arquivo agent.py para abri-lo.

Dica: o código Python exige que os subagentes sejam definidos antes de serem adicionados a um agente principal, para ler um arquivo agent.py na ordem do fluxo da conversa. Por isso, comece com a leitura do agente inferior e prossiga em direção ao superior.

5. Você vai notar que há três agentes aqui:

   • Um root_agent chamado greeting (o nome é usado para identificá-lo na interface de desenvolvimento e nas interfaces de linha de comando do ADK). Ele faz uma pergunta ao usuário (se ele sabe para onde quer viajar ou se precisa de ajuda para decidir). Com essa resposta do usuário, o agente de direcionamento sabe para qual dos dois subagentes direcionar a conversa. Observe que ele tem apenas uma instruction simples que não menciona os subagentes, mas está ciente das descrições deles.
   • Um travel_brainstormer que ajuda o usuário a pensar em destinos se ele não souber para onde quer ir.
   • Um attractions_planner que ajuda o usuário a criar uma lista de coisas para fazer depois de saber qual país ele gostaria de visitar.

6. Deixe os subagentes travel_brainstormer e attractions_planner abaixo do root_agent. Para isso, adicione a seguinte linha à criação do root_agent:

   sub_agents=[travel_brainstormer, attractions_planner]

7. Salve o arquivo.

8. Não é preciso adicionar um parâmetro parent aos subagentes. Quando você cria os agentes principais, a árvore hierárquica é definida apenas especificando sub_agents.

9. No terminal do Cloud Shell, execute o seguinte código para usar a interface de linha de comando do ADK para conversar com seu agente:

   cd ~/adk_multiagent_systems adk run parent_and_subagents

10. Quando o comando [user]: aparecer, cumprimente o agente com:

    Olá!

    Exemplo de resposta (pode ser um pouco diferente):

    usuário: Olá [steering]: Olá, tudo bem? Você já tem um país em mente para sua viagem ou gostaria de ajuda para decidir para onde ir?

11. Diga ao agente:

    Preciso de ajuda para decidir.

    Exemplo de resposta (pode ser um pouco diferente):

    usuário: preciso de ajuda para decidir. [travel_brainstormer]: Ok! Para dar as melhores recomendações, preciso entender o que você procura em uma viagem. ...

12. Você vai perceber pelo nome [travel_brainstormer], entre colchetes na resposta, que o root_agent (chamado [steering]) transferiu a conversa para o subagente apropriado, com base apenas na description deste subagente.

13. No comando user:, digite exit para encerrar a conversa.

14. Você também pode fornecer ao agente instruções mais detalhadas sobre quando transferir para um subagente como parte das instructions. No arquivo agent.py, adicione as seguintes linhas à instruction do root_agent:

    Se precisar de ajuda para decidir, envie a pessoa para "travel_brainstormer". Se eles souberem qual país querem visitar, envie-os para o "attractions_planner".

15. Salve o arquivo.

16. No terminal do Cloud Shell, execute o seguinte comando para iniciar a interface de linha de comando novamente:

    adk run parent_and_subagents

17. Cumprimente o agente com:

    Olá!

18. Responda à saudação do agente com:

    Eu gostaria de ir ao Japão.

    Exemplo de resposta (pode ser um pouco diferente):

    usuário: Quero ir para o Japão. [attractions_planner]: Ok, posso ajudar você com isso. Confira algumas atrações populares no Japão: * **Tóquio:** * Templo Senso-ji * Cruzamento de Shibuya * Tokyo Skytree * **Quioto:** ...

19. Observe que você foi transferido para o outro subagente, attractions_planner.

20. Responder com…

    Na verdade, não sei qual país visitar.

    Exemplo de resposta (pode ser um pouco diferente):

    usuário: na verdade, não sei qual país visitar [travel_brainstormer]: Ok! Posso ajudar você a pensar em alguns países para viajar…

21. Observe que você foi transferido para o agente travel_brainstormer, que é um agente par do attractions_planner. Isso é permitido por padrão. Se você quisesse impedir transferências para outros usuários, poderia ter definido o parâmetro disallow_transfer_to_peers como True no agente attractions_planner.

22. Para encerrar a sessão, basta digitar exit no prompt do usuário.

Padrão detalhado

Se você quiser um agente que guie o usuário por um processo detalhado, um padrão útil é fazer da primeira etapa o root_agent, com o agente da segunda etapa como o único subagente dele, e continuar com cada etapa adicional sendo o único subagente do agente da etapa anterior.

Clique em Verificar meu progresso para conferir o objetivo. Criar transferências entre os agentes principais, agentes secundários e agentes pares

Tarefa 3: usar o estado da sessão para armazenar e recuperar informações específicas

Cada conversa no ADK está contida em uma Session que todos os agentes envolvidos na conversa podem acessar. Uma sessão inclui o histórico da conversa, que os agentes leem como parte do contexto usado para gerar uma resposta. A sessão também inclui um dicionário de estado da sessão que você pode usar para ter mais controle sobre as informações mais importantes que você quer destacar e como elas são acessadas.

Isso pode ser útil para transmitir informações entre agentes ou manter uma estrutura de dados simples, como uma lista de tarefas, ao longo de uma conversa com um usuário.

Aprender a adicionar e ler o estado:

1. Volte ao arquivo adk_multiagent_systems/parent_and_subagents/agent.py

2. Cole a seguinte definição de função após o cabeçalho # Tools:

   def save_attractions_to_state( tool_context: ToolContext, attractions: List[str] ) -> dict[str, str]: """Salva a lista de atrações para o estado["attractions"]. Args: attractions [str]: uma lista de strings para adicionar à lista de atrações Returns: Nenhuma """ # Carregar atrações existentes do estado. Se não houver nenhuma, comece uma lista vazia existing_attractions = tool_context.state.get("attractions", []) # Atualizar a chave "attractions" com uma combinação de listas antigas e novas. # Quando a ferramenta é executada, o ADK cria um evento e faz # as atualizações correspondentes no estado da sessão. tool_context.state["attractions"] = existing_attractions + attractions # Uma prática recomendada para ferramentas é retornar uma mensagem de status em um dicionário de retorno return {"status": "success"}

3. Neste código, observe:

   • A sessão é transmitida para a função da ferramenta como ToolContext. Basta atribuir um parâmetro para recebê-lo, como você vê aqui com o parâmetro chamado tool_context. Em seguida, use tool_context para acessar informações da sessão, como o histórico de conversas (com tool_context.events) e o dicionário de estado da sessão (com tool_context.state). Quando o dicionário tool_context.state é modificado pela função da ferramenta, essas mudanças são refletidas no estado da sessão após a conclusão da execução da ferramenta.
   • A docstring fornece uma descrição clara e seções para argumentos e valores de retorno.
   • O código da função comentado demonstra como é fácil fazer atualizações no dicionário de estado.

4. Adicione a ferramenta ao agente attractions_planner adicionando o parâmetro tools quando o agente for criado:

   tools=[save_attractions_to_state]

5. Adicione os seguintes marcadores à instruction atual do agente attractions_planner:

   - Quando eles responderem, use sua ferramenta para salvar a atração selecionada e depois ofereça mais opções de atrações. - Se pedirem para ver a lista, forneça uma lista com marcadores de { atractions? } e depois sugira mais algumas.

6. Observe a seção entre chaves: { attractions? }. Esse recurso do ADK, o modelo de chave, carrega o valor da chave attractions do dicionário de estado. O ponto de interrogação após a chave attractions impede que isso gere um erro se o campo ainda não estiver presente.

7. Agora você vai executar o agente na interface da Web, que tem uma guia para mostrar as mudanças feitas no estado da sessão. Inicie a interface da Web do Kit de Desenvolvimento de Agente com o seguinte comando:

   adk web

   Saída

   INFO: Processo do servidor iniciado [2434] INFO: Aguardando a inicialização do aplicativo. +-------------------------------------------------------+ | Servidor da Web do ADK iniciado | | | | Para testes locais, acesse http://localhost:8000. | +-------------------------------------------------------+ INFO: A inicialização do aplicativo foi concluída. INFO: Uvicorn em execução em http://127.0.0.1:8000 (Pressione CTRL+C para sair)

8. Para visualizar a interface da Web em uma nova guia, clique no link http://127.0.0.1:8000 na saída do terminal.

9. Uma nova guia do navegador será aberta com a interface de desenvolvimento do ADK.

10. No menu suspenso Selecionar um agente à esquerda, selecione o agente parent_and_subagents.

11. Comece a conversa com: hello

12. Depois que o agente cumprimentar você, responda com:

    Eu gostaria de ir ao Egito.

    Você será transferido para o attractions_planner e receberá uma lista de atrações.

13. Escolha uma atração, por exemplo:

    Vou até a Esfinge

14. Você vai receber uma confirmação na resposta, como: Ok, salvei "A Esfinge" na sua lista. Confira outras atrações...

15. Clique na caixa de ferramentas de resposta (selecionada com uma marca de seleção) para visualizar o evento criado usando a resposta da ferramenta. Observe que ele inclui um campo actions que inclui state_delta descrevendo as mudanças no estado.

16. O agente vai pedir para você selecionar mais atrações. Responda ao agente nomeando uma das opções apresentadas.

17. No menu de navegação à esquerda, clique no "X" para sair do foco no evento que você inspecionou anteriormente.

18. Agora, na barra lateral, você vai ver a lista de eventos e algumas opções de guia. Selecione a guia Estado. Aqui você pode conferir o estado atual, incluindo a matriz attractions com os dois valores solicitados.

    

19. Envie esta mensagem ao agente:

    O que tem na minha lista?

20. Ele deve retornar sua lista formatada como uma lista com marcadores de acordo com a instruction.

21. Quando terminar de testar o agente, feche a guia do navegador da Web e pressione CTRL + C no terminal do Cloud Shell para interromper o servidor.

    Mais adiante neste laboratório, você vai demonstrar como usar o estado para se comunicar entre agentes.

Clique em Verificar meu progresso para conferir o objetivo. Usar o estado da sessão para armazenar e recuperar informações específicas

Em vez de salvar pequenas informações, se você quiser armazenar toda a resposta de texto do seu agente no dicionário de estado, defina um parâmetro output_key ao definir o agente. Toda a saída dele será armazenada no dicionário de estado com esse nome de campo.

Agentes de fluxo de trabalho

As transferências de agente principal para subagente são ideais quando você tem vários subagentes especialistas e quer que o usuário interaja com cada um deles.

No entanto, se você quiser que os agentes atuem um após o outro sem esperar a vez do usuário, use os agentes de fluxo de trabalho. Alguns exemplos de cenários em que você pode usar agentes de fluxo de trabalho incluem quando você quer que seus agentes:

• Planejem e executem: quando você quer que um agente prepare uma lista de itens e outros agentes usem essa lista para realizar tarefas de acompanhamento, como escrever seções de um documento.
• Pesquisem e escrevam: quando você quer que um agente chame funções para coletar informações contextuais da Pesquisa Google ou de outras fontes de dados e que outro agente use essas informações para produzir alguma saída.
• Elaborem e revisem: quando você quer que um agente prepare um rascunho de um documento e outros agentes verifiquem o trabalho e façam iterações nele.

Para realizar esse tipo de tarefa, os agentes de fluxo de trabalho têm subagentes e garantem que cada um deles atue. O Kit de Desenvolvimento de Agente oferece três agentes de fluxo de trabalho integrados e a oportunidade de definir os seus próprios:

• SequentialAgent
• LoopAgent
• ParallelAgent

No restante deste laboratório, você vai criar um sistema multiagente que usa vários agentes de LLM, agentes de fluxo de trabalho e ferramentas para ajudar a controlar o fluxo do agente.

Especificamente, você vai criar um agente que vai desenvolver um documento de apresentação para um novo filme de sucesso: um filme biográfico baseado na vida de um personagem histórico. Seus subagentes vão cuidar da pesquisa, de um ciclo iterativo de escrita com um roteirista e um crítico e, por fim, alguns subagentes vão ajudar a fazer um brainstorming de ideias de elenco e usar dados históricos de bilheteria para fazer algumas previsões sobre os resultados de bilheteria.

No final, seu sistema multiagente vai ficar assim (clique na imagem para ampliar):

Mas você vai começar com uma versão mais simples.

Tarefa 4: começar a criar um sistema multiagente com um SequentialAgent

O SequentialAgent executa os subagentes em uma sequência linear. Cada subagente na lista sub_agents é executado, um após o outro, na ordem em que são definidos.

Isso é ideal para fluxos de trabalho em que as tarefas precisam ser realizadas em uma ordem específica e a saída de uma tarefa serve como entrada para a próxima.

Nesta tarefa, você vai executar um SequentialAgent para criar uma primeira versão do seu sistema multiagente de desenvolvimento de apresentação de filme. O primeiro rascunho do seu agente será estruturado assim:

• Um root_agent chamado greeter para recepcionar o usuário e pedir um personagem histórico como tema de filme

• Um SequentialAgent chamado film_concept_team vai incluir:

  • Um pesquisador para saber mais sobre a figura histórica solicitada na Wikipédia, usando uma ferramenta do LangChain abordada no laboratório Capacitar agentes do ADK com ferramentas. Um agente pode escolher chamar as ferramentas várias vezes em sequência, para que o pesquisador possa fazer várias rodadas seguidas se determinar que precisa fazer mais pesquisas.
  • Um roteirista para transformar a pesquisa em um esboço de enredo.
  • Um file_writer para dar um título ao filme resultante e gravar os resultados da sequência em um arquivo.

1. No Editor do Cloud Shell, acesse o diretório adk_multiagent_systems/workflow_agents.

2. Clique no arquivo agent.py no diretório workflow_agents.

3. Leia este arquivo de definição de agente. Como os subagentes precisam ser definidos antes de serem atribuídos a um agente principal, para ler o arquivo na ordem do fluxo da conversa, você pode ler os agentes de baixo para cima.

4. Você também tem uma ferramenta de função append_to_state. Essa função permite que os agentes com a ferramenta adicionem conteúdo a um valor de dicionário no estado. Ele é especialmente útil para agentes que podem chamar uma ferramenta várias vezes ou agir em várias passagens de um LoopAgent, para que a saída seja armazenada a cada vez que eles agem.

5. Teste a versão atual do agente abrindo a interface da Web no terminal do Cloud Shell. Você vai usar o argumento --reload_agents para ativar a recarga dinâmica de agentes com base nas mudanças feitas neles:

   cd ~/adk_multiagent_systems adk web --reload_agents Observação: se você não encerrou a sessão anterior de adk web, a porta padrão 8000 será bloqueada, mas você poderá iniciar a interface de desenvolvimento com uma nova porta usando adk web --port 8001, por exemplo.

6. Para visualizar a interface da Web em uma nova guia, clique no link http://127.0.0.1:8000 na saída do terminal.

7. Uma nova guia do navegador será aberta com a interface de desenvolvimento do ADK.

8. No menu suspenso Selecionar um agente à esquerda, selecione workflow_agents.

9. Comece a conversa com: hello. Pode levar alguns instantes para o agente responder, mas ele vai pedir para você inserir uma figura histórica para começar a gerar o enredo do filme.

10. Quando for solicitado que você insira uma figura histórica, escolha uma ou use um destes exemplos:

    • Zhang Zhongjing: médico chinês renomado do século II d.C.
    • Ada Lovelace: matemática e escritora inglesa conhecida por seu trabalho com os primeiros computadores.
    • Marco Aurélio: imperador romano conhecido por seus escritos filosóficos.

11. O agente agora deve chamar os outros agentes um após o outro ao executar o fluxo de trabalho e gravar o arquivo de esboço do enredo no diretório ~/adk_multiagent_systems/movie_pitches. Ele deve informar quando o arquivo foi gravado no disco.

    Se o agente não informar que gerou um arquivo para você ou se você quiser tentar outro personagem, clique em + Nova sessão no canto superior direito e tente de novo.

12. Veja a saída do agente no editor do Cloud Shell. Talvez seja necessário usar o menu do editor do Cloud Shell para ativar Ver > Quebra de linha para ver o texto completo sem muita rolagem horizontal.

13. Na interface de desenvolvimento do ADK, clique em um dos ícones de agente () que representam um turno de conversa para abrir a visualização de eventos.

14. A visualização de eventos fornece uma representação visual da árvore de agentes e ferramentas usadas nesta sessão. Talvez seja necessário rolar o painel de eventos para ver o gráfico completo.

15. Além da visualização de gráfico, você pode clicar na guia Solicitação do evento para conferir as informações que o agente recebeu como parte da solicitação, incluindo o histórico da conversa.
16. Você também pode clicar na guia Resposta do evento para ver o que o agente retornou.

Observação: embora esse sistema possa produzir resultados interessantes, ele não pretende sugerir que as instruções podem ser tão breves ou que os exemplos podem ser ignorados. A confiabilidade do sistema se beneficiaria muito da camada adicional de instruções e exemplos mais rigorosos para cada agente.

Clique em Verificar meu progresso para conferir o objetivo. Começar a criar um sistema multiagente com um SequentialAgent

Tarefa 5: adicionar um LoopAgent para trabalho iterativo

O LoopAgent executa os subagentes em uma sequência definida e depois começa novamente no início da sequência sem interromper uma entrada do usuário. Ele repete o loop até que um número de iterações seja alcançado ou uma chamada para sair do loop seja feita por um dos subagentes (geralmente chamando uma ferramenta exit_loop integrada).

Isso é benéfico para tarefas que exigem refinamento contínuo, monitoramento ou fluxos de trabalho cíclicos. Por exemplo:

• Refinamento iterativo: melhore continuamente um documento ou plano com ciclos repetidos do agente.
• Monitoramento contínuo: verifique periodicamente as fontes de dados ou condições usando uma sequência de agentes.
• Debate ou negociação: simule discussões iterativas entre agentes para chegar a um resultado melhor.

Você vai adicionar um LoopAgent ao agente de apresentação do filme para permitir várias rodadas de pesquisa e iteração durante a criação da história. Além de refinar o script, isso permite que o usuário comece com uma entrada menos específica: em vez de sugerir uma figura histórica específica, ele pode apenas saber que quer uma história sobre um médico antigo, e um loop de iteração de pesquisa e escrita permitirá que os agentes encontrem um bom candidato e trabalhem na história.

Seu agente revisado vai funcionar assim:

• O root_agent greeter vai continuar o mesmo.
• O film_concept_team SequentialAgent agora vai consistir em:
  • Um writers_room LoopAgent que vai iniciar a sequência. Ele vai consistir em:
    • O pesquisador será o mesmo de antes.
    • O roteirista será semelhante ao anterior.
    • Um crítico que vai oferecer feedback crítico sobre o rascunho atual para motivar a próxima rodada de pesquisa e melhoria no loop.
  • Quando o loop terminar, ele vai transferir o controle da conversa de volta para o film_concept_team SequentialAgent, que vai passar o controle para o próximo agente na sequência: o file_writer, que vai continuar como antes para dar um título ao filme e gravar os resultados da sequência em um arquivo.

Para fazer essas mudanças:

1. No arquivo adk_multiagent_systems/workflow_agents/agent.py, adicione esta importação de ferramenta para que você possa dar a um agente a capacidade de sair do loop quando quiser:

   from google.adk.tools import exit_loop

2. Para determinar quando sair do loop, adicione este agente crítico para decidir quando o esboço da trama estiver pronto. Cole o novo agente no arquivo agent.py na seção # Agents (sem substituir os agentes atuais). Ele tem a ferramenta exit_loop como uma das ferramentas e instruções sobre quando usá-la:

   critic = Agent( name="critic", model=model_name, description="Revisa o roteiro para que ele possa ser melhorado.", instruction=""" INSTRUÇÕES: Considere essas perguntas sobre o PLOT_OUTLINE: - Ele atende uma estrutura cinematográfica satisfatória de três atos? - As dificuldades dos personagens parecem envolventes? - O jogo se passa em um período histórico real? - Ele incorpora detalhes históricos da PESQUISA de forma suficiente? Se o PLOT_OUTLINE fizer um bom trabalho com essas perguntas, saia do loop de escrita com sua ferramenta "exit_loop". Se melhorias significativas puderem ser feitas, use a ferramenta "append_to_state" para adicionar seu feedback ao campo "CRITICAL_FEEDBACK". Explique sua decisão e resuma brevemente o feedback que você forneceu. PLOT_OUTLINE: { PLOT_OUTLINE? } RESEARCH: { research? } """, before_model_callback=log_query_to_model, after_model_callback=log_model_response, tools=[append_to_state, exit_loop] )

3. Crie um novo LoopAgent chamado writers_room que cria o loop iterativo do pesquisador, roteirista e crítico. Cada passagem pelo loop termina com uma análise crítica do trabalho até o momento, o que gera melhorias para a próxima rodada. Cole o seguinte acima do film_concept_team SequentialAgent atual.

   writers_room = LoopAgent( name="writers_room", description="Itera usando a pesquisa e a escrita para melhorar um esboço de plot de filme.", sub_agents=[ researcher, screenwriter, critic ], max_iterations=5, )

4. Observe que a criação do LoopAgent inclui um parâmetro para max_iterations. Isso define quantas vezes o loop será executado antes de terminar. Mesmo que você planeje interromper o loop por outro método, é uma boa ideia incluir um limite no número total de iterações.

5. Atualize o film_concept_team SequentialAgent para substituir o pesquisador e roteirista pelo writers_room LoopAgent que você acabou de criar. O agente file_writer deve permanecer no final da sequência. O film_concept_team agora vai ficar assim:

   film_concept_team = SequentialAgent( name="film_concept_team", description="Escreva um esboço de plot de filme e salve-o como um arquivo de texto.", sub_agents=[ writers_room, file_writer ], )

6. Volte para a guia da interface do desenvolvedor do ADK e clique no botão + Nova sessão no canto superior direito para iniciar uma nova sessão.

7. Comece uma nova conversa com: hello

8. Quando for solicitado a escolher um tipo de personagem histórico, escolha um que lhe interesse. Algumas ideias incluem:

   • um designer industrial que criou produtos para as massas
   • um cartógrafo (uma pessoa que faz mapas)
   • aquele cara que fez as plantações produzirem mais alimentos

9. Depois de escolher um tipo de personagem, o agente deve passar por iterações do loop e, por fim, dar um título ao filme e escrever o esboço em um arquivo.

10. Usando o Editor do Cloud Shell, revise o arquivo gerado, que deve ser salvo no diretório adk_multiagent_systems/movie_pitches. (Talvez seja necessário usar o menu do editor para ativar Ver > Quebra de linha para ver o texto completo sem muita rolagem horizontal.)

Clique em Verificar meu progresso para conferir o objetivo. Adicionar um LoopAgent para trabalho iterativo

Tarefa 6: usar um padrão de "distribuição e coleta" para geração de relatórios com um ParallelAgent

O ParallelAgent permite a execução simultânea dos subagentes. Cada subagente opera em sua própria ramificação e, por padrão, não compartilha o histórico de conversas ou o estado diretamente entre si durante a execução paralela.

Isso é útil para tarefas que podem ser divididas em subtarefas independentes que podem ser processadas simultaneamente. Usar um ParallelAgent pode reduzir significativamente o tempo total de execução dessas tarefas.

Neste laboratório, você vai adicionar alguns relatórios complementares (pesquisas sobre o possível desempenho de bilheteria e algumas ideias iniciais sobre o elenco) para melhorar a apresentação do seu novo filme.

Seu agente revisado vai funcionar assim:

• O greeter será o mesmo.
• O film_concept_team SequentialAgent agora vai consistir em:
  • O writers_room LoopAgent, que vai permanecer o mesmo, incluindo:
    • O agente pesquisador
    • O agente roteirista
    • O agente crítico
  • Seu novo preproduction_team ParallelAgent vai agir, composto por:
    • Um agente box_office_researcher para usar dados históricos de bilheteria para gerar um relatório sobre o desempenho da bilheteria do filme.
    • Um agente casting_agent para gerar algumas ideias iniciais sobre o elenco com base em atores que estrelaram em filmes semelhantes.
  • O file_writer que vai continuar como antes para gravar os resultados da sequência em um arquivo.

Embora grande parte deste exemplo demonstre um trabalho criativo que seria feito por equipes humanas, esse fluxo de trabalho representa como uma cadeia complexa de tarefas pode ser dividida em vários subagentes para produzir rascunhos de documentos complexos que os membros da equipe humana podem editar e melhorar.

1. Cole os novos agentes e o ParallelAgent no arquivo workflow_agents/agent.py abaixo do cabeçalho # Agents:

   box_office_researcher = Agent( name="box_office_researcher", model=model_name, description="Considera o potencial da bilheteria deste filme", instruction=""" PLOT_OUTLINE: { PLOT_OUTLINE? } INSTRUÇÕES: Escreva um relatório sobre o potencial de bilheteria de um filme como o descrito em PLOT_OUTLINE com base no desempenho de bilheteria relatado de outros filmes recentes. """, output_key="box_office_report" ) casting_agent = Agent( name="casting_agent", model=model_name, description="Gera ideias sobre o elenco deste filme", instruction=""" PLOT_OUTLINE: { PLOT_OUTLINE? } INSTRUÇÕES: Gere ideias para o elenco dos personagens descritos em PLOT_OUTLINE sugerindo atores que receberam feedback positivo de críticos e/ou fãs quando desempenharam papéis semelhantes. """, output_key="casting_report" ) preproduction_team = ParallelAgent( name="preproduction_team", sub_agents=[ box_office_researcher, casting_agent ] )

2. Atualize a lista sub_agents do agente film_concept_team para incluir o preproduction_team entre o writers_room e o file_writer:

   film_concept_team = SequentialAgent( name="film_concept_team", description="Escreva um esboço de plot de filme e salve-o como um arquivo de texto.", sub_agents=[ writers_room, preproduction_team, file_writer ], )

3. Atualize a instrução do file_writer para:

   INSTRUÇÕES: - Crie uma sugestão de título de filme contemporâneo e comercializável para o filme descrito em PLOT_OUTLINE. Se um título foi sugerido em PLOT_OUTLINE, você pode usá-lo ou substituí-lo por um melhor. - Use a ferramenta "write_file" para criar um novo arquivo txt com os seguintes argumentos: - Para o nome do arquivo, use o título do filme - Grave no diretório "movie_pitches". - Para o "conteúdo" a ser escrito, inclua: - O PLOT_OUTLINE - O BOX_OFFICE_REPORT - O CASTING_REPORT PLOT_OUTLINE: { PLOT_OUTLINE? } BOX_OFFICE_REPORT: { box_office_report? } CASTING_REPORT: { casting_report? }

4. Salve o arquivo.

5. Na interface de desenvolvimento do ADK, clique em + Nova sessão no canto superior direito.

6. Digite hello para iniciar a conversa.

7. Quando solicitado, insira uma nova ideia de personagem que você tenha interesse. Algumas ideias incluem:

   • aquela atriz que inventou a tecnologia do Wi-Fi
   • um chef incrível
   • melhores atores no mundo de feira de exibições

8. Quando o agente terminar de escrever e gerar o relatório, inspecione o arquivo produzido no diretório adk_multiagent_systems/movie_pitches. Se alguma parte do processo falhar, clique em + Nova sessão no canto superior direito e tente de novo.

Agentes de fluxo de trabalho personalizados

Quando os agentes de fluxo de trabalho predefinidos do SequentialAgent, LoopAgent e ParallelAgent não são suficientes para suas necessidades, o CustomAgent oferece a flexibilidade de implementar uma nova lógica de fluxo de trabalho. É possível definir padrões para controle de fluxo, execução condicional ou gerenciamento de estado entre subagentes. Isso é útil para fluxos de trabalho complexos, orquestrações com estado ou integração de lógica de negócios personalizada na camada de orquestração do framework.

A criação de um CustomAgent está fora do escopo deste laboratório, mas é bom saber que ele existe caso você precise dele.

Parabéns!

Neste laboratório, você aprendeu a:

• Definir vários agentes e relacioná-los entre si com hierarquia de agente principal para subagente
• Adicionar ao estado da sessão e ler nas instruções do agente
• Usar agentes de fluxo de trabalho para transmitir a conversa entre agentes diretamente

Próximas etapas

Aprenda a implantar agentes no Agent Engine no laboratório Implantar agentes do ADK no Agent Engine.

Treinamento e certificação do Google Cloud

Esses treinamentos ajudam você a aproveitar as tecnologias do Google Cloud ao máximo. Nossas aulas incluem habilidades técnicas e práticas recomendadas para ajudar você a alcançar rapidamente o nível esperado e continuar sua jornada de aprendizado. Oferecemos treinamentos que vão do nível básico ao avançado, com opções de aulas virtuais, sob demanda e por meio de transmissões ao vivo para que você possa encaixá-las na correria do seu dia a dia. As certificações validam sua experiência e comprovam suas habilidades com as tecnologias do Google Cloud.

Manual atualizado em 22 de maio de 2025

Laboratório testado em 22 de maio de 2025

Copyright 2020 Google LLC. Todos os direitos reservados. Google e o logotipo do Google são marcas registradas da Google LLC. Todos os outros nomes de produtos e empresas podem ser marcas registradas das respectivas empresas a que estão associados.