1. O que você vai aprender
Bem-vindo à Master Class do ADK: sua jornada nos sistemas multiagentes
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 no 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: aprenda a criar um agente totalmente funcional que entende as necessidades do usuário, usa ferramentas como a Pesquisa Google e gera 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 multiagentes: 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 com várias etapas sem problemas.
Vamos começar! 🚀
2. Configuração: receber sua chave de API
Configuração da chave de API do Google AI Studio
Para ativar nossos agentes de IA, precisamos de uma chave da API Gemini do Google AI Studio. Essa é a maneira mais rápida de começar.
Etapa 1: receba sua chave da API Gemini no AI Studio (1 minuto)
- Abra https://aistudio.google.com/app/apikey em uma nova guia do navegador.
- Faça login usando sua Conta do Google.
- Clique em Criar chave de API (canto superior direito).
- Uma caixa de diálogo é aberta com um menu suspenso de projetos:
- Se você já tiver um projeto do Google criado: selecione-o e clique em Criar chave de API em um projeto atual.
- Se NÃO estiver na lista:clique em Criar projeto.
- Copie a chave de API que aparece. Ele começa com
AIza...e tem cerca de 40 caracteres.
✏️ Cole em um lugar seguro: você vai precisar dele para os notebooks do Colab e a configuração da Web do ADK (no Apêndice).
Etapa 2: adicionar sua chave de API ao Colab (1 minuto)
Cada notebook tem uma célula de configuração que carrega sua chave de API. Você tem duas opções. Escolha a que preferir:
Opção A: Colab Secrets (recomendada: a chave fica oculta)
- No notebook do Colab, clique no ícone de chave 🔑 na barra lateral esquerda.
- Clique em Adicionar novo secret.
- Defina o Nome como
GOOGLE_API_KEY. - Cole sua chave de API (da etapa 1) no campo Valor.
- Mude a opção Acesso ao notebook para ATIVADO.
Quando você executa a célula de configuração, ela seleciona automaticamente a chave:
✅ API key loaded from Colab Secrets.
Opção B: colar quando solicitado (rápido e fácil)
Se você pular o Colab Secrets e executar diretamente codelab1 e codelab2, o notebook vai mostrar um campo de senha:
🔑 Enter your Google AI Studio API key: ••••••••
Cole a chave de API e pressione "Enter". A chave não vai aparecer na tela.
✅ API key entered manually.
Depois que a célula da chave de API for executada, a próxima célula vai configurar o ambiente:
✅ API key configured (starts with 'AIzaSy...')
✅ Using Google AI Studio (not Vertex AI).
✅ Checkpoint:você vê as duas mensagens ✅ acima no notebook. Sua chave de API está configurada e você já pode criar agentes.
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 na solicitação de um 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 usado (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.
- Executor: o mecanismo que executa a tarefa. Ele usa o agente e a sessão, processa a nova consulta do usuário e orquestra 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 da 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 API Weather. 🌟
- Definição da 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 agente para usar a ferramenta
get_live_weather_forecastporque 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 simpático. A função do orquestrador é entender a solicitação do usuário e encaminhá-la para o 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 com várias camadas:
- 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. É importante ressaltar 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 nas proximidades.
- 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. Ele precisa lembrar da conversa, entender o contexto e se adaptar ao feedback. Isso é feito com o gerenciamento adequado de sessões. Um "agente de loop" é 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 lide com 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 de forma progressiva. As instruções enfatizam a importância de 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.
Cenário 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 turno.
- 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_two. Como essa nova sessão não tem histórico, o agente fica confuso. Ele está com amnésia! Ele 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(). Esse é 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 funciona como um agente "mestre" ou um despachante. O único objetivo dele é analisar uma consulta do usuário e decidir qual agente especialista (ou fluxo de trabalho de agentes) é o mais adequado para a tarefa. 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 recebe a instrução explícita de 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 especializado 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. Esse é 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 de posição.
- 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/elifdesapareceu! 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 do Núcleo: 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. - A 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, executar essas pesquisas uma por uma será lento.
A 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 usando 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. Quando os três terminam, os resultados individuais (salvos no estado compartilhado) sã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 é 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 claro.
11. Apêndice: ADK Web – 🍎 Para Mac/Linux
Este guia mostra como configurar e executar o 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 (da etapa de configuração acima)
- Conexão de 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 na etapa Configuração: gerar sua chave de API.
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 mostra como configurar e executar o 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 (da etapa de configuração acima)
- Conexão de 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 na etapa Configuração: gerar sua chave de API.
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.