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 agentes do ADK com ferramentas

Objetivos

Neste laboratório, você vai:

• Definir vários agentes e relacioná-los entre si com hierarquia de agente pai para subagente.
• Criar conteúdo em várias interações de conversa e com múltiplos agentes, gravando tudo 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 que a conversa seja transmitida diretamente entre eles.

Configuração e requisitos

Antes de clicar no botão "Começar o Laboratório"

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

Este laboratório prático permite que você realize as atividades em um ambiente real de nuvem, e não em uma simulação ou demonstração. Você vai receber novas credenciais temporárias para fazer login e acessar o Google Cloud durante o laboratório.

Confira os requisitos para concluir o laboratório:

• Acesso a um navegador de Internet padrão (recomendamos o Chrome).

• Tempo para concluir o laboratório: não se esqueça que, depois de começar, não será possível pausar o 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 boas-vindas.

   {{{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, talvez 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 sem custo financeiro.

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, que podem gerar resultados não 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 diversas vantagens importantes, como:

• Mais fácil de projetar: você pode pensar em termos de agentes com habilidades e jobs específicos.
• 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 proporciona uma abordagem mais organizada e, portanto, mais fácil de pensar.
• Capacidade de 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 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

Neste ambiente de laboratório, a API Agent Platform já foi ativada para você. Se você fosse executar essas etapas no seu projeto, seria necessário acessar a Agent Platform e seguir o comando para ativar a API.

Preparar 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. Se preferir, 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. Clique no ícone de lápis Abrir editor () na parte de cima do painel para visualizar os arquivos.
6. Na parte de cima do menu de navegação à esquerda, clique no ícone do Explorer () para abrir o explorador de arquivos.
7. Clique no botão Abrir pasta.
8. Na caixa de diálogo "Abrir pasta" exibida, clique em OK para selecionar a pasta inicial da sua conta de estudante do Qwiklabs.
9. Feche todos os outros tutoriais ou painéis do Gemini que aparecem no lado direito da tela. Assim você terá mais espaço na janela do editor de código.
10. Durante o restante deste laboratório, você pode trabalhar nesta janela como seu ambiente de desenvolvimento integrado (IDE, na sigla em inglês) com o editor e o terminal do Cloud Shell.

Baixar e instalar o ADK e os exemplos de código para este laboratório

1. Cole os comandos abaixo 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/* .

2. Execute os comandos abaixo no terminal do Cloud Shell para atualizar a variável de ambiente PATH e instalar o ADK e outros requisitos do laboratório.

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

Tarefa 2: conhecer as transferências entre o agente pai, o agente par e o subagente

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

O comportamento padrão de um agente pai é 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 pai. Basta indicar os subagentes por nome (os valores do parâmetro name, não os nomes das variáveis). Teste um exemplo:

1. No terminal do Cloud Shell, execute o código abaixo 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=global MODEL={{{project_0.startup_script.gemini_flash_model_id | gemini_flash_model_id}}} EOF

   Essas variáveis têm as seguintes funções:

   • GOOGLE_GENAI_USE_VERTEXAI=TRUE indica que você usa a Agent Platform para autenticação em vez da autenticação por chave da API Gemini.
   • GOOGLE_CLOUD_PROJECT e GOOGLE_CLOUD_LOCATION indicam o projeto e o local para associar as chamadas de modelo.
   • MODEL fica armazenado aqui para que possa ser carregado como outra variável de ambiente.

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 "Buscador de arquivos" do editor do Cloud Shell, acesse o diretório adk_multiagent_systems/parent_and_subagents.

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

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

   • Um root_agent chamado steering (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. 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 legais para fazer depois de saber qual país ele gostaria de visitar.

6. Defina travel_brainstormer e attractions_planner como subagentes 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 pai, 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:

    hello

    Exemplo de resposta (pode variar):

    [user]: hello [steering]: Hello! Welcome to your travel adventure. Do you already know where you'd like to travel, or would you like some help deciding?

11. Diga ao agente:

    I could use some help deciding.

    Exemplo de resposta (pode variar):

    [user]: I could use some help deciding. [travel_brainstormer]: Hello! I'd love to help you decide on the perfect destination for your next trip. To start, here are a few highly popular countries that travelers love: * **Italy:** Famous for food, history, art, and beautiful landscapes. * **Japan:** A unique blend of ultra-modern cities, ancient temples, stunning nature, and incredible cuisine. * **Costa Rica:** A paradise for nature lovers, wildlife, and outdoor adventures. * **France:** Renowned for world-class art, fashion, gastronomy, and romantic cities. To help narrow things down to the perfect match for you, what are your primary goals for this trip? Are you looking for: 1. **Adventure** (hiking, wildlife, outdoor activities) 2. **Leisure** (relaxing on beaches, spas, slow-paced exploring) 3. **Learning** (history, museums, exploring different cultures) 4. **Shopping** (fashion, local markets, unique finds) 5. **Viewing Art** (galleries, architecture, world-famous masterpieces) Let me know what sounds most exciting to you, or if you have a mix of these in mind!

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 desse subagente.

13. No comando user:, digite exitpara encerrar a conversa.

14. Você também pode explicar melhor ao agente quando transferir para um subagente como parte das instructions. No arquivo agent.py, adicione as seguintes linhas à instruction do root_agent:

    If they need help deciding, send them to 'travel_brainstormer'. If they know what country they'd like to visit, send them to the '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:

    hello

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

    I would like to go to Japan.

    Exemplo de resposta (pode variar):

    [user]: I would like to go to Japan. [attractions_planner]: Japan is an incredible destination with a perfect blend of ancient traditions and futuristic cities! Here are some of the top attractions and regions to consider for your trip, categorized by the type of experience: ### 1. **The Modern & Futuristic (Tokyo)** * **Shibuya Crossing & Harajuku:** Experience the bustling energy of the world's busiest pedestrian crossing and the quirky fashion of Takeshita Street. * **teamLab Planets:** An immersive, digital-art museum where you walk through water and interact with stunning light projections. * **Senso-ji Temple:** Tokyo's oldest and most iconic Buddhist temple, located in the historic Asakusa district. ### 2. **History & Tradition (Kyoto & Nara)** * **Fushimi Inari Shrine (Kyoto):** Famous for its path of thousands of vibrant red torii gates winding up the mountain. * **Kinkaku-ji (The Golden Pavilion, Kyoto):** A breathtaking Zen temple covered in gold leaf, reflecting over a serene pond. * **Nara Park (Nara):** Home to hundreds of freely roaming, bowing deer and the massive Great Buddha statue at Todai-ji Temple. ### 3. **Nature & Scenic Views** * **Mount Fuji & Lake Kawaguchiko:** Enjoy stunning views of Japan's iconic volcano, especially beautiful during cherry blossom or autumn foliage seasons. * **Arashiyama Bamboo Grove (Kyoto):** Walk through a towering forest of green bamboo that feels like another world. ### 4. **Food & Entertainment (Osaka)** * **Dotonbori:** Osaka's neon-lit food street, famous for street foods like *takoyaki* (octopus balls) and *okonomiyaki* (savory pancakes). * **Osaka Castle:** A magnificent historic landmark surrounded by a massive park and moat. --- To help me tailor the perfect itinerary for you, **what kinds of things are you most interested in?** * Historic temples and shrines? * Modern city life and pop culture (anime, gaming, shopping)? * Nature, hiking, and scenic landscapes? * Incredible food and culinary experiences? Let me know, and we can start building your custom list of stops!

19. Note que houve uma transferência para outro subagente, o attractions_planner.

20. Responda com:

    Actually I don't know what country to visit.

    Exemplo de resposta (pode variar):

    user: actually I don't know what country to visit [travel_brainstormer]: Okay! I can help you brainstorm some countries for travel...

21. Observe que houve uma transferência para o agente travel_brainstormer, que é 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.

Clique em Verificar meu progresso para conferir o objetivo. Conhecer as transferências entre o agente pai, o agente par e o subagente

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.

Para 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]: """Saves the list of attractions to state["attractions"]. Args: attractions [str]: a list of strings to add to the list of attractions Returns: None """ # Load existing attractions from state. If none exist, start an empty list existing_attractions = tool_context.state.get("attractions", []) # Update the 'attractions' key with a combo of old and new lists. # When the tool is run, ADK will create an event and make # corresponding updates in the session's state. tool_context.state["attractions"] = existing_attractions + attractions # A best practice for tools is to return a status message in a return dict return {"status": "success"}

3. Nesse 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:

   - When they reply, use your tool to save their selected attraction and then provide more possible attractions. - If they ask to view the list, provide a bulleted list of { attractions? } and then suggest some more.

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. Use o comando abaixo para iniciar a interface da web do Kit de Desenvolvimento de Agente:

   adk web --allow_origins "regex:https://.*\.cloudshell\.dev"

   Resposta

   INFO: Started server process [2434] INFO: Waiting for application startup. +-------------------------------------------------------+ | ADK Web Server started | | | | For local testing, access at http://localhost:8000. | +-------------------------------------------------------+ INFO: Application startup complete. INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)

8. Para ver a interface da web em uma nova guia, clique no link http://127.0.0.1:8000 na resposta 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: olá

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

    I'd like to go to Egypt.

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

13. Escolha uma delas. Por exemplo:

    I'll go to the Sphinx

14. Você vai receber uma confirmação na resposta, como: Okay, I've saved The Sphinx to your list. Here are some other attractions...

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. 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:

    What is on my list?

20. Ele deve retorná-la formatada como uma lista com marcadores conforme 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

Agentes de fluxo de trabalho

As transferências de agente pai 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 cumprimentar o usuário e pedir um personagem histórico como tema de filme

• Um SequentialAgent chamado film_concept_team vai incluir:

  • Um researcher 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 screenwriter 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 pai, 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. Ela é 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 sempre que eles agirem.

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 em tempo real dos agentes com base nas mudanças feitas neles:

   cd ~/adk_multiagent_systems adk web --allow_origins "regex:https://.*\.cloudshell\.dev" --reload_agents Observação: se você não desligou 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 ver a interface da web em uma nova guia, clique no link http://127.0.0.1:8000 na resposta 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: olá. Pode levar alguns instantes para o agente responder, mas ele vai pedir a você que insira 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 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.

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 o 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 é útil 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 researcher será o mesmo de antes.
    • O researcher será semelhante ao anterior.
    • Um researcher 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 a importação de ferramenta abaixo para permitir que os agentes saiam da repetição quando quiserem:

   from google.adk.tools import exit_loop from google.adk.models import Gemini

2. Para determinar quando a repetição pode ser encerrada, adicione um agente crítico que decide quando o esboço do enredo está pronto. Cole o novo agente no arquivo agent.py no cabeçalho da seção # Agents (sem substituir os agentes atuais). Ele tem a ferramenta exit_loop, além de instruções sobre quando usá-la:

   critic = Agent( name="critic", model=Gemini(model=model_name, retry_options=RETRY_OPTIONS), description="Reviews the outline so that it can be improved.", instruction=""" INSTRUCTIONS: Consider these questions about the PLOT_OUTLINE: - Does it meet a satisfying three-act cinematic structure? - Do the characters' struggles seem engaging? - Does it feel grounded in a real time period in history? - Does it sufficiently incorporate historical details from the RESEARCH? If the PLOT_OUTLINE does a good job with these questions, exit the writing loop with your 'exit_loop' tool. If significant improvements can be made, use the 'append_to_state' tool to add your feedback to the field 'CRITICAL_FEEDBACK'. Explain your decision and briefly summarize the feedback you have provided. 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 a repetição iterativa 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="Iterates through research and writing to improve a movie plot outline.", sub_agents=[ researcher, screenwriter, critic ], max_iterations=5, )

4. 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, convém 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="Write a film plot outline and save it as a text file.", sub_agents=[ writers_room, file_writer ], )

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

7. Comece uma nova conversa com: olá

8. Quando for solicitado, escolha um tipo de personagem histórico que seja do seu 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, depois, dar um título ao filme e escrever o esboço em um arquivo.

10. Usando o Editor do Cloud Shell, confira 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 o 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 researcher
    • O agente screenwriter
    • O agente critic
  • Seu novo preproduction_team ParallelAgent vai agir, composto por:
    • Um agente box_office_researcher para usar dados históricos de bilheteria e 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 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=Gemini(model=model_name, retry_options=RETRY_OPTIONS), description="Considers the box office potential of this film", instruction=""" PLOT_OUTLINE: { PLOT_OUTLINE? } INSTRUCTIONS: Write a report on the box office potential of a movie like that described in PLOT_OUTLINE based on the reported box office performance of other recent films. """, output_key="box_office_report" ) casting_agent = Agent( name="casting_agent", model=Gemini(model=model_name, retry_options=RETRY_OPTIONS), description="Generates casting ideas for this film", instruction=""" PLOT_OUTLINE: { PLOT_OUTLINE? } INSTRUCTIONS: Generate ideas for casting for the characters described in PLOT_OUTLINE by suggesting actors who have received positive feedback from critics and/or fans when they have played similar roles. """, 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="Write a film plot outline and save it as a text file.", sub_agents=[ writers_room, preproduction_team, file_writer ], )

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

   INSTRUCTIONS: - Create a marketable, contemporary movie title suggestion for the movie described in the PLOT_OUTLINE. If a title has been suggested in PLOT_OUTLINE, you can use it, or replace it with a better one. - Use your 'write_file' tool to create a new txt file with the following arguments: - for a filename, use the movie title - Write to the 'movie_pitches' directory. - For the 'content' to write, include: - The PLOT_OUTLINE - The BOX_OFFICE_REPORT - The 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 olá para iniciar a conversa.

7. Quando solicitado, insira uma nova ideia de personagem que seja do seu interesse. Algumas ideias incluem:

   • aquela atriz que inventou a tecnologia do Wi-Fi
   • um chef incrível
   • os principais personagens do mundo das exposiçõ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 existe, caso você precise.

Parabéns!

Neste laboratório, você aprendeu a criar vários agentes e relacioná-los entre si com hierarquia de pai para subagente, adicionar dados ao estado da sessão e lê-los nas instruções do agente, além de usar agentes de fluxo de trabalho para encaminhar a conversa entre agentes de maneira direta.

Treinamento e certificação do Google Cloud

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

Manual atualizado em 26 de julho de 2026

Laboratório testado em 26 de julho de 2026

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