1. O que você vai aprender
Boas-vindas à Master Class do ADK: sua jornada nos sistemas multiagente
Você está prestes a entrar no incrível mundo dos agentes de IA. Esqueça os chatbots simples que apenas respondem a perguntas. Estamos nos aprofundando na Agent Development Kit (ADK) para criar sistemas autônomos sofisticados que podem raciocinar, planejar e usar ferramentas para realizar tarefas complexas.
Ao final deste tutorial, você vai saber como:
- Crie seu primeiro agente de IA: crie um agente totalmente funcional que entenda as necessidades de um usuário, use ferramentas como a Pesquisa Google e gere respostas detalhadas e úteis.
- Domine as ferramentas personalizadas: conecte os agentes às suas próprias funções e APIs personalizadas para aproveitar todo o potencial deles. Você vai ensinar o agente a buscar dados em tempo real, como previsões do tempo.
- Construir sistemas multiagente: aprenda o padrão "Agente como ferramenta", um conceito revolucionário em que os agentes delegam tarefas a outros agentes especializados, criando uma equipe de especialistas em IA que trabalham juntos.
- Orquestrar fluxos de trabalho complexos: vá além da delegação simples e domine padrões avançados, como roteadores, cadeias sequenciais, loops e execução paralela, para criar aplicativos robustos, eficientes e inteligentes que podem lidar com quase qualquer solicitação.
- Dê memória aos seus agentes: entenda o papel fundamental da memória de conversa, permitindo que seus agentes respondam a perguntas complementares, aprendam com o feedback e gerenciem tarefas de várias etapas sem problemas.
Vamos começar! 🚀
2. Configurar o GCP e a chave da API Gemini
Configurar seu projeto do GCP e a chave da API Gemini
Para alimentar nossos agentes de IA, precisamos de duas coisas: um projeto do Google Cloud para fornecer a base e uma chave de API do Gemini para acessar os modelos avançados do Google.
Etapa 1: ativar a conta de faturamento
- Reivindique sua conta de faturamento com um crédito de US$ 5, que será necessário para a implantação. Verifique se é sua conta do Gmail.
Etapa 2: criar um projeto do GCP
- Acesse o Console do Google Cloud e crie um projeto.
- Acesse o Console do Google Cloud e crie um projeto.
- Abra o painel à esquerda, clique em
Billinge verifique se a conta de faturamento está vinculada a essa conta do GCP.
Se você vir esta página, verifique o manage billing account, escolha o teste sem custo financeiro do Google Cloud e vincule a ele.
Etapa 3: gerar sua chave da API Gemini
Antes de proteger a chave, você precisa ter uma.
- Acesse o Google AI Studio : https://aistudio.google.com/
- Faça login com sua conta do Gmail.
- Clique no botão Receber chave de API, geralmente encontrado no painel de navegação à esquerda ou no canto superior direito.
- Na caixa de diálogo Chaves de API, clique em "Criar chave de API em um novo projeto".
- Escolha o novo projeto que você criou e que tem uma conta de faturamento configurada.
- Uma nova chave de API será gerada para você. Copie essa chave imediatamente e armazene-a em um lugar seguro temporariamente, como um gerenciador de senhas ou uma nota segura. Esse é o valor que você vai usar nas próximas etapas.
3. Sessão 1: seu primeiro agente com o Runner
Vamos começar com o básico. Aqui, criamos nosso primeiro agente simples, o day_trip_agent. O objetivo desse agente é gerar um itinerário de viagem de um dia inteiro com base em uma solicitação do usuário, incluindo considerações de orçamento. Este exemplo apresenta os três componentes principais de qualquer interação do agente no ADK:
- Agente: o cérebro principal da operação. Ele é definido pelas instruções (personalidade e missão), pelo modelo de IA que usa (como o Gemini) e pelas ferramentas a que tem acesso.
- Sessão: a memória da conversa. Ele armazena o histórico de interações (mensagens do usuário e respostas do agente), permitindo um diálogo contínuo.
- Runner: o mecanismo que executa a tarefa. Ele usa o agente e a sessão, processa a nova consulta do usuário e organiza as etapas para gerar uma resposta.
➡️ Onde encontrar no notebook
👉 Isso corresponde às células em Parte 1: seu primeiro agente: o Genie de viagem de um dia 🧞.🌟
- Definição do agente: procure a função
create_day_trip_agent(). É aqui que o agente é definido. Observe a string de instrução detalhada. Esse é o comando que informa ao agente como se comportar. Também oferecemos a primeira ferramenta: a Pesquisa Google. - Função auxiliar: a função auxiliar
run_agent_query()é definida aqui. Vamos usar essa utilidade em todo o notebook para simplificar a execução de consultas. - Teste: a função
run_day_trip_genie()simula um usuário pedindo uma viagem de um dia "econômica" e "relaxante". O agente usa as instruções e a ferramenta de Pesquisa Google para encontrar locais adequados e criar um itinerário formatado em Markdown.
➡️ Ação: examine o comando de instrução para o day_trip_agent. Veja como o pedido de uma viagem "acessível" na consulta de teste se relaciona diretamente à diretriz do agente de ser "consciente do orçamento".
4. Sessão 2: ferramentas personalizadas 🛠️
Embora a Pesquisa Google seja poderosa, o verdadeiro potencial dos agentes de IA é revelado quando você os conecta às suas próprias fontes de dados, APIs ou lógica personalizada. Nesta seção, vamos criar uma ferramenta personalizada com uma função simples do Python.
A parte mais importante de uma ferramenta de função é a docstring. O ADK analisa automaticamente a docstring para entender o que a ferramenta faz, quais parâmetros ela aceita (Args) e o que ela retorna (Returns). O modelo de linguagem grande (LLM) lê essa descrição para decidir quando e como usar a ferramenta.
➡️ Onde encontrar no notebook
👉 Isso corresponde às células em 2.1 A Simple FunctionTool: Calling a Real-Time Weather API. 🌟
- Definição de ferramenta: a função
get_live_weather_forecast(location: str)é o núcleo da nossa ferramenta personalizada. Ele usa o nome de uma cidade, chama a API pública do National Weather Service e retorna um dicionário com a temperatura e a previsão. - Definição do agente: o weather_agent é criado e equipado com nossa nova ferramenta transmitindo
tools=[get_live_weather_forecast]durante a inicialização. As instruções do agente dizem explicitamente para usar essa ferramenta antes de sugerir atividades ao ar livre. - Teste: a consulta "Quero fazer uma trilha perto do Lago Tahoe. Como está o clima?" aciona diretamente o uso da ferramenta
get_live_weather_forecastpelo agente porque as instruções exigem isso.
➡️ Ação: leia a docstring da função get_live_weather_forecast e a instrução para weather_agent. Observe a relação direta entre eles.
5. Sessão 3: Agente como ferramenta 🧑🍳
Por que criar um único agente monolítico quando você pode criar uma equipe de especialistas? O padrão Agent-as-a-Tool é uma maneira eficiente de criar sistemas complexos em que um agente principal, geralmente chamado de orquestrador ou roteador, delega tarefas a outros agentes mais focados.
Esse padrão permite criar agentes modulares e reutilizáveis. Por exemplo, você pode ter um agente especialista em consultas de banco de dados, outro em escrita criativa e um terceiro que atua como um concierge amigável. O trabalho do organizador é entender a solicitação do usuário e encaminhá-la ao especialista correto.
➡️ Onde encontrar no notebook
👉 Isso corresponde às células em 2.2 O agente como uma ferramenta: consultar um especialista 🧑🍳.🌟
Este exemplo cria um sistema de agente sofisticado e multicamadas:
- Os especialistas:
- food_critic_agent: um agente altamente especializado que só oferece sugestões de restaurantes.
- db_agent: um agente simulado que finge consultar um banco de dados para informações de hotéis.
- concierge_agent: um agente de nível médio que atua como um concierge educado. O mais importante é que ele tem o
food_critic_agentcomo ferramenta própria.
- O orquestrador (
trip_data_concierge_agent): é o agente de nível superior com que o usuário interage. As instruções o transformam em um "planejador de viagens mestre", e ele recebe duas ferramentas que chamam os outros agentes:- call_db_agent: uma função que chama o
db_agent. - call_concierge_agent: uma função que chama o
concierge_agent.
- call_db_agent: uma função que chama o
- O fluxo: a execução do teste em
run_trip_data_concierge()demonstra a cadeia de delegação completa.- Um usuário pede ao orquestrador um hotel e um restaurante próximo.
- As instruções do orquestrador dizem para primeiro usar a ferramenta
call_db_agentpara receber dados de hotéis. - Em seguida, o orquestrador usa a ferramenta
call_concierge_agentpara receber uma recomendação. - O
concierge_agent, ao receber a solicitação, usa a própria ferramenta, ofood_critic_agent, para receber uma sugestão de restaurante.
A resposta do crítico de gastronomia é transmitida de volta ao concierge, que a formata de maneira educada e a envia de volta ao orquestrador, que finalmente a apresenta ao usuário.
➡️ Ação: rastreie o fluxo de execução na execução do teste em run_trip_data_concierge(). Observe como as impressões TOOL CALLED mostram a cadeia de delegação do orquestrador até os especialistas. Essa é uma cadeia de comando sequencial.
6. Sessão 4: memória do agente 🧠
Um agente verdadeiramente inteligente precisa fazer mais do que apenas responder a consultas únicas. Ela precisa lembrar da conversa, entender o contexto e se adaptar ao feedback. Isso é feito com o gerenciamento adequado de sessões. Pense em um "agente de loop" como um agente envolvido em um loop de conversa contínuo, alimentado pela memória dele.
Quando você usa o mesmo objeto de sessão para várias consultas sequenciais, o agente pode "ver" todo o histórico da conversa. Isso permite que ele responda a perguntas de acompanhamento, se corrija com base no feedback e planeje tarefas de várias etapas.
➡️ Onde encontrar no notebook
👉 Isso corresponde às células em Parte 3: agente com memória: o planejador adaptativo 🗺️. 🌟
- Definição do agente: a função
create_multi_day_trip_agent()define um agente projetado para planejar uma viagem progressivamente. As instruções enfatizam lembrar o contexto, lidar com feedback e planejar um dia de cada vez.
Cenário 3a: agente COM memória (✅)
Esse teste é executado na função run_adaptive_memory_demonstration().
- Um único
trip_sessioné criado e reutilizado por três turnos consecutivos. - Turno 1: o usuário inicia um plano de viagem de dois dias.
- Turno 2: o usuário dá feedback ("Não sou muito fã de castelos"). Como o agente tem a memória da rodada 1, ele entende qual parte do plano precisa ser mudada e oferece uma alternativa.
- Turno 3: o usuário confirma a mudança e pede a próxima etapa. O agente se lembra de tudo e começa a planejar o dia 2.
Situação 3b: agente SEM memória (❌)
Esse teste é executado na função run_memory_failure_demonstration().
Isso demonstra a importância crítica do gerenciamento de sessões ao cometer um erro de propósito. Uma nova sessão é criada para cada vez.
- Turno 1: o usuário inicia a viagem em session_one. O agente responde corretamente.
- Turno 2: o usuário pede para planejar o dia 2, mas a consulta é enviada em uma nova sessão_dois. Como essa nova sessão não tem histórico, o agente fica confuso. Ele está com amnésia! Ela não sabe qual viagem está sendo planejada.
Ação: compare as respostas do agente em run_adaptive_memory_demonstration() e run_memory_failure_demonstration(). Este é o conceito mais importante do notebook: uma conversa contínua exige uma sessão contínua.
7. Sessão 5: o agente de roteamento 🚏
Um único agente tem limitações. Para lidar com solicitações de usuários realmente complexas, precisamos de uma equipe de agentes especializados. Mas como saber qual agente usar para uma determinada consulta? É aí que entra o agente de roteamento.
O agente de roteador atua como um agente "mestre" ou um dispatcher. O único objetivo dela é analisar uma consulta do usuário e decidir qual agente especialista (ou fluxo de trabalho de agentes) é o mais adequado para o trabalho. Ele não responde à consulta em si, apenas a encaminha para o agente downstream correto.
Por exemplo, uma consulta sobre "o melhor sushi" deve ser direcionada a um foodie_agent, enquanto uma pergunta sobre "shows neste fim de semana" deve ser tratada por um weekend_guide_agent.
➡️ Onde encontrar isso no notebook:
👉 Esse conceito é fundamental para todo o notebook, mas é apresentado pela primeira vez na Parte 1: Multi-Agent Mayhem - Fluxos de trabalho sequenciais 🧠→🤖→🤖 🌟
- Definições de agente: a célula de código define vários agentes especializados (day_trip_agent, foodie_agent, transportation_agent) e, mais importante, o router_agent. Preste atenção ao comando de instrução do router_agent. Ele é explicitamente instruído a retornar apenas o nome do melhor agente para o trabalho.
- Lógica de execução: a função run_sequential_app demonstra como primeiro chamar o router_agent para receber uma decisão (chosen_route) e depois usar essa decisão em um bloco
if/elifpara executar o agente especialista apropriado.
8. Sessão 6: SequentialAgent ⛓️
Algumas tarefas exigem várias etapas em uma ordem específica. Por exemplo, "Encontre o melhor sushi em Palo Alto e me diga como chegar lá". Esse processo é realizado em duas etapas: primeiro, encontre o restaurante e, segundo, confira o trajeto.
O ADK oferece uma maneira limpa e eficiente de gerenciar isso com o SequentialAgent. É um agente de fluxo de trabalho especial que executa uma lista de subagentes em uma ordem predefinida.
O segredo está no estado compartilhado. A saída de um agente na sequência pode ser salva automaticamente em um dicionário de estado compartilhado e usada como entrada para o próximo agente, eliminando a necessidade de um código manual complexo para transmitir informações entre as etapas.
➡️ Onde encontrar isso no notebook:
👉 Isso é abordado na Parte 2 (A maneira do ADK): caos multiagente com SequentialAgent 🧠→⛓️→🤖. 🌟
- Refatoração do agente:na primeira célula de código desta seção, observe as principais mudanças no
foodie_agente notransportation_agent:foodie_agentagora tem umoutput_key="destination". Isso informa ao ADK para salvar a resposta final em uma variável chamadadestinationno estado compartilhado.- O
transportation_agentagora tem o marcador de posição{destination}no comando de instrução. O ADK injeta automaticamente o valor do estado compartilhado nesse marcador.
- Definindo o fluxo de trabalho: o
find_and_navigate_agenté definido como um SequentialAgent, com os subagentes definidos como [foodie_agent,transportation_agent], garantindo que eles sejam executados nessa ordem exata. - Execução simplificada: confira a função
run_sequential_appnesta seção. A lógica complexaif/elifsumiu! Ofind_and_navigate_agentagora é tratado como uma única unidade chamável, e o ADK processa as etapas sequenciais internas automaticamente.
9. Sessão 7: LoopAgent 🔁
Nem todos os problemas têm uma solução simples e única. Às vezes, precisamos propor uma solução, criticá-la e refiná-la até que ela atenda a uma restrição específica.
Para isso, o ADK oferece o LoopAgent. Esse agente de fluxo de trabalho executa repetidamente uma sequência de subagentes até que uma condição específica seja atendida. Isso é perfeito para criar agentes "perfeccionistas" que podem planejar, criticar e melhorar o próprio trabalho.
O diagrama mostra o Planner Agent criando um plano primeiro. Em seguida, inserimos o LoopAgent. O Critic Agent verifica o plano. Se estiver com falhas, o Refiner Agent vai criar uma nova versão, e o loop vai se repetir. Se o plano for bom, o Refiner Agent vai chamar a ferramenta exit_loop, e o plano final validado será retornado.
➡️ Onde encontrar isso no notebook:
👉 Isso é explicado em Ideias iterativas com o LoopAgent 🧠→🔁→🤖. 🌟
- Os agentes principais: o fluxo de trabalho usa um
planner_agent,critic_agenterefiner_agent. - Definição do loop: o
refinement_loopé definido como um LoopAgent que orquestra ocritic_agent, orefiner_agente osets max_iterations=3. - Condição de saída: o loop termina quando o
critic_agentaprova o plano, fazendo com que orefiner_agentchame a ferramenta personalizadaexit_loop.
10. Sessão 8: ParallelAgent ⚡️
A eficiência é fundamental. Se um usuário pedir várias informações não relacionadas de uma vez, fazer essas pesquisas uma por uma seria lento.
O ParallelAgent é a solução. Esse agente de fluxo de trabalho executa uma lista de subagentes simultaneamente. Depois que todas as tarefas paralelas forem concluídas, os resultados poderão ser reunidos e sintetizados em uma única resposta abrangente.
Este diagrama mostra o ParallelAgent pegando uma única consulta e dividindo o trabalho em três faixas simultâneas. Os comandos museum_finder, concert_finder e restaurant_finder são executados ao mesmo tempo. Depois que os três terminarem, os resultados individuais (salvos no estado compartilhado) serão unidos e transmitidos ao agente de síntese final, que os combina em uma resposta.
➡️ Onde encontrar isso no notebook:
👉 Esse fluxo de trabalho está detalhado na seção Parallel Power com ParallelAgent 🧠→⚡️→🤖🤖🤖. 🌟
- Agentes especializados: três agentes especializados são definidos, cada um com uma output_key exclusiva (por exemplo, museum_result).
- O fluxo de trabalho paralelo: o parallel_research_agent é definido como um ParallelAgent, com os três agentes de pesquisa listados como subagentes.
- A etapa de síntese: após a etapa paralela, um synthesis_agent final coleta todas as descobertas do estado compartilhado usando marcadores de posição (
{museum_result},{concert_result}etc.) para formatar um resumo organizado.
11. Apêndice: ADK Web - 🍎 Para Mac/Linux
Este guia vai orientar você na configuração e execução do agente de planejamento de passeios de um dia do ADK na sua máquina local.
Pré-requisitos
- Python 3.8 ou mais recente
- Python 3.9 ou mais recente: instala google-adk==1.5.0 (versão mais recente com recursos completos)
- Python 3.8: instala google-adk==0.3.0 (versão compatível)
- Chave de API do Google AI Studio
- Conexão com a Internet
Etapa 1: clonar o repositório
Abra o Terminal e execute:
git clone https://github.com/cuppibla/ADK_Basic.git
cd ADK_Basic
Etapa 2: configurar o ambiente virtual e instalar dependências
Opção A: configuração automática (recomendada)
# Run the setup script
chmod +x setup_venv.sh
./setup_venv.sh
Opção B: configuração manual
# Create virtual environment
python3 -m venv .adk_env
# Activate virtual environment
source .adk_env/bin/activate
# Install dependencies
pip install --upgrade pip
pip install -r requirements.txt
Etapa 3: 🔥 IMPORTANTE - Criar variáveis de ambiente
⚠️ Não pule esta etapa! Crie um arquivo .env no diretório agent/:
# Create the .env file
touch agent/.env
# Open it in your default text editor
open agent/.env
Adicione estas linhas ao arquivo:
GOOGLE_GENAI_USE_VERTEXAI=FALSE
GOOGLE_API_KEY=your_actual_api_key_here
🚨 CRÍTICO: substitua your_actual_api_key_here pela sua chave de API real.
Etapa 4: ativar o ambiente virtual (se ainda não estiver ativo)
source .adk_env/bin/activate
Você vai ver (.adk_env) no início do prompt do terminal.
Etapa 5: executar a interface da Web do ADK
adk web
Etapa 6: abra o navegador
- Abra o navegador e acesse o URL mostrado no terminal (geralmente
http://localhost:8000). - No menu suspenso no canto superior esquerdo, selecione
agent - Comece a conversar com seu agente de planejamento de viagens de um dia!
Você vai ver uma conversa como: 
Como desativar o ambiente
Quando terminar de trabalhar com o projeto:
deactivate
Esse comando funciona da mesma forma no Mac/Linux e no Windows. O prefixo (.adk_env) vai desaparecer do seu terminal.
Solução de problemas do Mac
- Python não encontrado: use
python3em vez depython - Permissão negada: execute
chmod +x setup_venv.shantes de executar o script
12. Apêndice: ADK Web - 🪟 para usuários do Windows
Este guia vai orientar você na configuração e execução do agente de planejamento de passeios de um dia do ADK na sua máquina local.
Pré-requisitos
- Python 3.8 ou mais recente
- Python 3.9 ou mais recente: instala google-adk==1.5.0 (versão mais recente com recursos completos)
- Python 3.8: instala google-adk==0.3.0 (versão compatível)
- Chave de API do Google AI Studio
- Conexão com a Internet
Etapa 1: clonar o repositório
Abra o prompt de comando ou o PowerShell e execute:
git clone https://github.com/cuppibla/ADK_Basic.git
cd ADK_Basic
Etapa 2: configurar o ambiente virtual e instalar dependências
Opção A: configuração automática (recomendada)
# Run the setup script in Command Prompt
setup_venv.bat
Opção B: configuração manual
Para o prompt de comando:
# Create virtual environment
python -m venv .adk_env
# Activate virtual environment
.adk_env\Scripts\activate
# Install dependencies
pip install --upgrade pip
pip install -r requirements.txt
Para PowerShell:
# Create virtual environment
python -m venv .adk_env
# Activate virtual environment
.adk_env\Scripts\Activate.ps1
# Install dependencies
pip install --upgrade pip
pip install -r requirements.txt
Etapa 3: 🔥 IMPORTANTE - Criar variáveis de ambiente
⚠️ Não pule esta etapa! Crie um arquivo .env no diretório agent/:
# Create the .env file
type nul > agent\.env
# Open it in Notepad
notepad agent\.env
Adicione estas linhas ao arquivo:
GOOGLE_GENAI_USE_VERTEXAI=FALSE
GOOGLE_API_KEY=your_actual_api_key_here
🚨 CRÍTICO: substitua your_actual_api_key_here pela sua chave de API real.
Etapa 4: ativar o ambiente virtual (se ainda não estiver ativo)
Prompt de comando:
.adk_env\Scripts\activate
PowerShell:
.adk_env\Scripts\Activate.ps1
Você vai ver (.adk_env) no início do comando.
Etapa 5: executar a interface da Web do ADK
adk web
Etapa 6: abra o navegador
- Abra o navegador e acesse o URL mostrado no terminal (geralmente
http://localhost:8000). - No menu suspenso no canto superior esquerdo, selecione
agent - Comece a conversar com seu agente de planejamento de viagens de um dia!
Solução de problemas do Windows
- Erro na política de execução do PowerShell: execute
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
Você vai ver uma conversa como:
Como desativar o ambiente
Quando terminar de trabalhar com o projeto:
deactivate
Esse comando funciona da mesma forma no Mac/Linux e no Windows. O prefixo (.adk_env) vai desaparecer do seu terminal.