Padrão de agente do ADK com memória e MCP

1. O que você vai aprender

Bem-vindo à aula avançada do ADK: sua jornada para 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. Vamos nos aprofundar no Agent Development Kit (ADK) para criar sistemas sofisticados e autônomos que podem raciocinar, planejar e usar ferramentas para realizar tarefas complexas.

Todo este codelab será uma jornada prática, este 1 repositório do GitHub que contém todo o código e exemplos para nossas sessões. repositório do GitHub

Ao final deste tutorial, você poderá:

• Criar seu primeiro agente de IA: passe de zero a um agente totalmente funcional que pode entender as necessidades de um usuário, usar ferramentas como a Pesquisa Google e gerar respostas detalhadas e úteis.
• 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 processar quase todas as solicitações.
• Dar memória aos seus agentes: entenda o papel fundamental da memória conversacional, permitindo que seus agentes processem perguntas de acompanhamento, aprendam com o feedback e gerenciem tarefas de várias etapas sem problemas.
• Conectar-se ao MCP: conecte-se à caixa de ferramentas do MCP.

Vamos começar! 🚀

2. Configuração: receber sua chave de API

Configuração da chave de API do Google AI Studio

Este codelab é executado inteiramente em uma chave de API sem custo financeiro do Google AI Studio. Não é necessário um projeto do Google Cloud, uma conta de faturamento ou créditos. Todas as sessões, incluindo memória (sessão 6) e MCP (sessão 7), são executadas localmente na sua chave. Cada aluno usa a própria chave, então a cota de API é por pessoa, não compartilhada.

O que você precisa:

• Python 3.9 ou mais recente (python3 --version para verificar)
• Uma Conta do Google (para criar a chave do AI Studio)
• Um terminal: sua máquina local ou o Cloud Shell funcionam
• Cerca de 10 minutos

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: receber sua chave da API Gemini do AI Studio (1 minuto)

1. Abra https://aistudio.google.com/app/apikey em uma nova guia do navegador.
2. Faça login usando sua Conta do Google.
3. Clique em "Criar chave de API" (canto superior direito).
4. Uma caixa de diálogo será aberta com um menu suspenso do projeto:

• Se você já tiver um projeto do Google criado antes: selecione-o e clique em "Criar chave de API no projeto atual"
• Se não estiver na lista: clique em "Criar projeto".

5. Copie a chave de API que será exibida. Ela começa com AIza... e tem cerca de 40 caracteres.

✏️ Cole em um local seguro , você vai precisar dela na etapa 4 abaixo.

Trate a chave de API como uma senha. Não a cole em chats públicos, capturas de tela ou faça commit dela em um repositório público do GitHub.

Etapa 2: clonar o repositório (1 minuto)

👉💻 Abra o terminal (ou o Cloud Shell) e clone o repositório do tutorial:

git clone https://github.com/cuppibla/adk_tutorial.git
cd ~/adk_tutorial

Etapa 3: criar o ambiente virtual e instalar dependências

👉💻 Crie e ative um ambiente virtual chamado .adk_env e instale as dependências:

python3 -m venv .adk_env
source .adk_env/bin/activate
pip install --upgrade pip
pip install -r requirements.txt

Você verá (.adk_env) no início do prompt do terminal.

Etapa 4: 🔥 IMPORTANTE: adicionar sua chave de API

⚠️ Não pule esta etapa! Crie um arquivo .env na raiz da pasta adk_tutorial. Esse arquivo alimenta todas as sessões neste codelab. As sessões da Web do ADK (1 a 5) e as sessões de memória e MCP de linha de comando (6 a 7) leem automaticamente.

👉💻 Crie o arquivo .env com sua chave (substitua your_actual_api_key_here pela chave da etapa 1):

cat > .env <<'EOF'
GOOGLE_GENAI_USE_VERTEXAI=FALSE
GOOGLE_API_KEY=your_actual_api_key_here
EOF

Seu ~/adk_tutorial/.env agora deve conter:

GOOGLE_GENAI_USE_VERTEXAI=FALSE
GOOGLE_API_KEY=your_actual_api_key_here

🚨 CRÍTICO: substitua your_actual_api_key_here pela chave de API da etapa 1 (ela começa com AIza...).

⚠️ Verifique se GOOGLE_GENAI_USE_VERTEXAI está definido como FALSE. Isso informa ao ADK para autenticar com a chave de API do Google AI Studio em vez do Vertex AI.

✅ Ponto de verificação:você tem um arquivo .env em ~/adk_tutorial/.env contendo sua chave AIza..., e o prompt do terminal mostra (.adk_env). Você está pronto para criar agentes!

3. Sessão 1: seu primeiro agente na Web do ADK

Abra a Web do ADK executando:

cd ~/adk_tutorial
source .adk_env/bin/activate
adk web

Depois de executar os comandos, você verá uma saída no terminal indicando que o servidor da Web do ADK foi iniciado, semelhante a esta:

+-----------------------------------------------------------------------------+
| ADK Web Server started                                                      |
|                                                                             |
| For local testing, access at http://localhost:8000.                         |
+-----------------------------------------------------------------------------+


INFO:     Application startup complete.
INFO:     Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)

👉 Em seguida, abra o navegador em http://localhost:8000 para acessar a interface de desenvolvimento do ADK.

Executando no Cloud Shell em vez de localmente? Clique no ícone Visualização da Web na barra de ferramentas do Cloud Shell (geralmente no canto superior direito), selecione Alterar porta, defina a porta como 8000 e clique em "Alterar e visualizar". O Cloud Shell vai abrir a interface de desenvolvimento do ADK em uma nova guia do navegador.

👉 Seu ritual de invocação está concluído e o agente está em execução. A interface de desenvolvimento do ADK no navegador é sua conexão direta com o Familiar.

Escolha seu primeiro agente No menu suspenso na parte de cima da interface, escolha a_single_agent.

Você pode selecionar a_single_agent aqui:

Você pode conferir o rastreamento aqui:

👉 Comando de teste:

Plan a trip from Sunnyvale to San Francisco this weekend, I love food and art.

4. Sessão 2: agente de fluxo de trabalho: agente sequencial, agente paralelo, agente de loop

Abra a interface da Web do ADK seguindo as etapas da sessão 1.

Agente paralelo

Escolha o agente de fluxo de trabalho paralelo No menu suspenso na parte de cima da interface, escolha b2_parallel_agent.

👉 Comando de teste:

Plan my trip to San Francisco, I want to find some good concert, restaurant and museum.

Você pode selecionar b2_parallel_agent aqui:

Você pode conferir o rastreamento aqui:

Agente sequencial

Escolha o agente de fluxo de trabalho sequencial No menu suspenso na parte de cima da interface, escolha b1_sequential_agent.

👉 Comando de teste:

Find a good sushi near Standford and tell me how to get there.

Você pode selecionar b1_sequential_agent aqui:

Você pode conferir o rastreamento aqui:

Agente de loop

Escolha o agente de fluxo de trabalho de loop No menu suspenso na parte de cima da interface, escolha b3_loop_agent.

👉 Comando de teste:

Plan a trip from Sunnyvale to San Francisco today.

Você pode selecionar b3_loop_agent aqui:

Você pode conferir o rastreamento aqui:

5. Sessão 3: agente personalizado

Abra a interface da Web do ADK seguindo as etapas da sessão 1.

Depois que a interface da Web do ADK for aberta, escolha c_custom_agent no menu suspenso.

👉 Comando de teste:

Plan a trip from Sunnyvale to San Francisco this weekend, I love food and art. Make sure within budget of 100 dollars.

Você pode selecionar c_custom_agent aqui:

Você pode conferir o rastreamento aqui:

6. Sessão 4: padrão de orquestrador: agente de roteamento

Abra a interface da Web do ADK seguindo as etapas da sessão 1.

Depois que a interface da Web do ADK for aberta, escolha d_routing_agent no menu suspenso.

👉 Comando de teste:

Plan a trip from Sunnyvale to San Francisco this weekend, I love concert, restaurant and museum.

Você pode selecionar d_routing_agent aqui:

Você pode conferir o rastreamento aqui:

7. Sessão 5: agente como ferramenta

Abra a interface da Web do ADK seguindo as etapas da sessão 1.

Depois que a interface da Web do ADK for aberta, escolha e_agent_as_tool no menu suspenso.

👉 Comando de teste:

Plan a trip from Sunnyvale to San Francisco this weekend, I love concert, restaurant and museum.

Você pode selecionar e_agent_as_tool aqui:

Você pode conferir o rastreamento aqui:

8. Sessão 6: agente com memória de longo prazo

Executa totalmente no local. Esta sessão armazena a memória de conversa em um banco de dados SQLite local (em ~/.adk/), para que suas preferências persistam em reinicializações sem a necessidade do Google Cloud, faturamento ou créditos. O agente lê a chave do AI Studio do ~/adk_tutorial/.env que você criou na configuração.

👉💻 Teste sua memória de longo prazo acessando a pasta e usando o executor para ativar o agente:

cd ~/adk_tutorial
source .adk_env/bin/activate
cd ~/adk_tutorial/f_agent_with_memory
python main.py

👉 Comando de teste:

I like Art and Italian food.

Em seguida, encerre a sessão pressionando Ctrl+C. Reinicie a sessão:

cd ~/adk_tutorial
source .adk_env/bin/activate
cd ~/adk_tutorial/f_agent_with_memory
python main.py

👉 Comando de teste:

Plan a trip to San Francisco based on my preference.

✅ O agente deve lembrar "Arte e comida italiana" da execução anterior. Essa é a memória de longo prazo funcionando em todas as sessões.

9. Sessão 7: capacitar seu agente com o MCP

Executa totalmente no local. Esta sessão inicia um servidor de caixa de ferramentas do MCP local que lê um banco de dados SQLite local (destinations.db). Não é necessário o Google Cloud, faturamento ou créditos. O único download externo é o binário da caixa de ferramentas do MCP de código aberto.

Etapa 1: preparar o banco de dados local

👉💻 Na raiz do repositório, crie o banco de dados de exemplo:

cd ~/adk_tutorial
source .adk_env/bin/activate
chmod +x setup_trip_database.py
./setup_trip_database.py

Isso cria destinations.db em ~/adk_tutorial/.

⚠️ O banco de dados de exemplo contém apenas quatro cidades: Paris, Roma, Nova York e Tóquio (tipos de atração: marco, museu, parque). Os comandos que fazem referência a outras cidades (por exemplo, São Francisco ou Sunnyvale) vão retornar nenhum resultado corretamente, porque essas linhas não existem. Use as quatro cidades acima ao testar esta sessão.

Etapa 2: instalar e executar o servidor da caixa de ferramentas do MCP

👉💻 Faça o download do binário da caixa de ferramentas do MCP para seu sistema operacional:

cd ~/adk_tutorial/mcp_tool_box
export VERSION=0.16.0

# Choose the line that matches your machine:
export OS=linux/amd64      # Cloud Shell or Linux (x86_64)
# export OS=darwin/arm64   # macOS Apple Silicon (M1/M2/M3)
# export OS=darwin/amd64   # macOS Intel

curl -O https://storage.googleapis.com/genai-toolbox/v$VERSION/$OS/toolbox

depois de concluir o download e executar

chmod +x toolbox

Não sabe qual Mac você tem? Execute uname -m — arm64 = Apple Silicon, x86_64 = Intel. No Windows, faça o download de .../windows/amd64/toolbox.exe e execute-o no PowerShell.

Etapa 3

Em um terminal Execute o seguinte comando (deixe-o em execução. O agente se conecta a ele em http://127.0.0.1:7001):

cd ~/adk_tutorial
source .adk_env/bin/activate
cd ~/adk_tutorial/mcp_tool_box
./toolbox --tools-file "trip_tools.yaml" --port 7001

Em outro terminal Execute o seguinte comando

cd ~/adk_tutorial
source .adk_env/bin/activate
cd ~/adk_tutorial/g_agents_mcp
python main.py

👉 Comandos de teste (use as cidades que existem no banco de dados de exemplo: Paris, Roma, Nova York ou Tóquio):

What are the top-rated things to do in Tokyo?

Show me the museums in Rome.

What can I do in New York for under 25 dollars?

Solução de problemas da sessão 7

• "Conexão recusada" / o agente não encontra ferramentas: o servidor da caixa de ferramentas no primeiro terminal não está em execução. Reinicie-o e confirme se ele está escutando na porta 7001.
• Cada consulta retorna resultados vazios:confirme se você executou a etapa 1 para que ~/adk_tutorial/destinations.db exista e se o comando usa uma das quatro cidades (Paris, Roma, Nova York, Tóquio).
• toolbox: cannot execute binary file no macOS:você fez o download da versão do Linux. Execute novamente a etapa 2 com OS=darwin/arm64 (Apple Silicon) ou OS=darwin/amd64 (Intel).