Guia Completo: Como Configurar Ambiente para Google ADK Facilmente

Domine a instalação do Google ADK, desde ambiente virtual até integração com API Key, para desenvolvimento rápido e seguro de agentes inteligentes.

Insights

O Google ADK impõe uma estrutura de pastas específica que deve ser respeitada rigorosamente, não é sugestão
A API Key do Google AI Studio é gratuita e suficiente para desenvolvimento e aprendizado, sem necessidade de Google Cloud
O comando adk web fornece interface de desenvolvimento interativa que acelera drasticamente o ciclo de experimentação
O arquivo .env na pasta do agente é o local correto para a API Key, não na raiz do projeto
Python 3.10 é o mínimo suportado, versões anteriores simplesmente não funcionam com o ADK

Configurar o ambiente para o Google ADK é surpreendentemente direto quando você entende os requisitos. Diferente de outros frameworks que oferecem flexibilidade excessiva, o ADK impõe convenções claras que eliminam decisões desnecessárias. A estrutura de pastas é obrigatória, o arquivo de agente deve seguir convenções de nomenclatura, e a API Key deve estar no local correto. Essa rigidez intencional significa que, uma vez configurado corretamente, o framework simplesmente funciona.

Pré-Requisitos de Sistema são mínimos

O Google ADK foi projetado para ser acessível. Os pré-requisitos de sistema são intencionalmente modestos, permitindo que qualquer desenvolvedor Python comece rapidamente.

Python 3.10 ou Posterior

O ADK utiliza recursos de linguagem introduzidos no Python 3.10. Versões anteriores não são suportadas e produzirão erros de sintaxe ou importação.

Verifique sua versão:

python --version

1	python --version

Se o output mostrar versão inferior a 3.10, você tem algumas opções:

Instalação direta: Baixe do python.org a versão mais recente e instale.

pyenv (recomendado para gerenciar múltiplas versões):

# Instalar pyenv (macOS/Linux)
curl https://pyenv.run | bash

# Instalar Python 3.12
pyenv install 3.12.0
pyenv global 3.12.0

# Instalar pyenv (macOS/Linux)

curl https://pyenv.run | bash

# Instalar Python 3.12

pyenv install 3.12.0

pyenv global 3.12.0

Windows via Microsoft Store: Busque “Python” na Microsoft Store e instale a versão mais recente.

Após instalação, reinicie o terminal e verifique novamente.

IDE ou Editor de código

Qualquer editor funciona, mas recomendamos:

Visual Studio Code: Com extensão Python, oferece IntelliSense, debugging e integração com terminal
PyCharm: IDE completa com excelente suporte a Python e ambientes virtuais
Cursor: Fork do VS Code com IA integrada, útil para desenvolvimento com agentes

Conexão com Internet

Necessária para chamadas à API do Gemini. O ADK faz requests HTTP para endpoints do Google AI.

API Key do Google AI Studio é gratuita e suficiente

A forma mais simples de começar é com uma API Key do Google AI Studio. Não requer cartão de crédito, não requer projeto Google Cloud, e oferece generosa camada gratuita para desenvolvimento.

Obtendo a API Key

Acesse aistudio.google.com
Faça login com sua conta Google
Clique em “Get API key” no menu lateral
Clique em “Create API key”
Copie a chave gerada

A chave tem formato similar a: AIzaSyD... com aproximadamente 40 caracteres.

Limites da camada gratuita

O Google AI Studio oferece limites generosos para desenvolvimento:

Gemini 2.0 Flash: 15 RPM (requests por minuto), 1 milhão de tokens/minuto
Gemini 1.5 Pro: 2 RPM, 32.000 tokens/minuto

Esses limites são suficientes para aprendizado, desenvolvimento e testes. Para produção com volume alto, considere Vertex AI.

Segurança da API Key

A API Key é um segredo que não deve ser exposta:

Nunca commite a key em repositórios git
Adicione .env ao .gitignore
Use variáveis de ambiente em produção
Regenere a key se suspeitar de exposição

Instalação do Google ADK

Com Python configurado e API Key em mãos, podemos instalar o framework.

Criando ambiente virtual

Isole as dependências do projeto em um ambiente virtual dedicado:

<em># Criar ambiente virtual</em>
python -m venv adk-env

<em># Ativar no Windows</em>
adk-env\Scripts\activate

<em># Ativar no macOS/Linux</em>
source adk-env/bin/activate

# Criar ambiente virtual

python -m venv adk-env

# Ativar no Windows

adk-env\Scripts\activate

# Ativar no macOS/Linux

source adk-env/bin/activate

O prompt do terminal deve mudar para indicar ambiente ativo. Algo como (adk-env) antes do cursor.

Instalando o pacote

Com ambiente ativo, instale o ADK:

pip install google-adk

1	pip install google-adk

A instalação baixa o pacote principal e todas as dependências necessárias.

Verificando a instalação

Confirme que a instalação foi bem-sucedida:

pip show google-adk

1	pip show google-adk

O output deve mostrar informações do pacote, incluindo versão e localização.

Verifique também se o comando adk está disponível:

adk --help

1	adk --help

Deve exibir lista de comandos disponíveis: web, run, deploy, eval, etc.

O Google ADK impõe uma estrutura de pastas específica. Isso não é sugestão ou recomendação. É requisito. O framework procura arquivos em locais específicos e falha se não encontrar.

Estrutura mínima

Para um único agente, a estrutura é:

meu_projeto/
└── meu_agente/
    ├── __init__.py
    ├── .env
    └── agent.py

meu_projeto/

└── meu_agente/

├── __init__.py

├── .env

└── agent.py

Cada elemento tem propósito específico:

meu_projeto/: Diretório raiz do projeto. Pode ter qualquer nome.

meu_agente/: Diretório do agente. O nome deve corresponder ao nome usado no código do agente.

init.py: Arquivo vazio que transforma o diretório em pacote Python. Deve existir.

.env: Arquivo de configuração com variáveis de ambiente, incluindo a API Key.

agent.py: Arquivo principal com a definição do agente. Por convenção, deve conter uma variável com mesmo nome da pasta.

Criando a estrutura

Linux/macOS:

mkdir -p meu_projeto/greeting_agent
touch meu_projeto/greeting_agent/__init__.py
touch meu_projeto/greeting_agent/agent.py
touch meu_projeto/greeting_agent/.env

mkdir -p meu_projeto/greeting_agent

touch meu_projeto/greeting_agent/__init__.py

touch meu_projeto/greeting_agent/agent.py

touch meu_projeto/greeting_agent/.env

Windows (PowerShell):

mkdir meu_projeto\greeting_agent
New-Item meu_projeto\greeting_agent\__init__.py -ItemType File
New-Item meu_projeto\greeting_agent\agent.py -ItemType File
New-Item meu_projeto\greeting_agent\.env -ItemType File

mkdir meu_projeto\greeting_agent

New-Item meu_projeto\greeting_agent\__init__.py -ItemType File

New-Item meu_projeto\greeting_agent\agent.py -ItemType File

New-Item meu_projeto\greeting_agent\.env -ItemType File

Windows (CMD):

mkdir meu_projeto\greeting_agent
echo. > meu_projeto\greeting_agent\__init__.py
echo. > meu_projeto\greeting_agent\agent.py
echo. > meu_projeto\greeting_agent\.env

mkdir meu_projeto\greeting_agent

echo. > meu_projeto\greeting_agent\__init__.py

echo. > meu_projeto\greeting_agent\agent.py

echo. > meu_projeto\greeting_agent\.env

Configurando o arquivo .env

Edite o arquivo .env dentro da pasta do agente:

GOOGLE_API_KEY=sua_api_key_aqui

1	GOOGLE_API_KEY=sua_api_key_aqui

Substitua sua_api_key_aqui pela chave obtida no Google AI Studio.

Importante: O arquivo .env deve estar dentro da pasta do agente, não na raiz do projeto.

Estrutura para múltiplos agentes

Quando você tem múltiplos agentes no mesmo projeto:

meu_projeto/
├── agente_suporte/
│   ├── __init__.py
│   ├── .env
│   └── agent.py
├── agente_vendas/
│   ├── __init__.py
│   ├── .env
│   └── agent.py
└── agente_tecnico/
    ├── __init__.py
    ├── .env
    └── agent.py

meu_projeto/

├── agente_suporte/

│ ├── __init__.py

│ ├── .env

│ └── agent.py

├── agente_vendas/

│ ├── __init__.py

│ ├── .env

│ └── agent.py

└── agente_tecnico/

├── __init__.py

├── .env

└── agent.py

Cada agente tem seu próprio diretório com estrutura completa. Você pode compartilhar a mesma API Key criando um arquivo .env em cada pasta ou configurando variável de ambiente global.

A Interface web acelera o desenvolvimento

Uma das melhores funcionalidades do ADK é a interface web integrada para desenvolvimento. Ela oferece ambiente interativo para testar agentes sem escrever código de cliente.

Iniciando a interface web

Navegue até a pasta do projeto e execute:

cd meu_projeto
adk web

1 2	cd meu_projeto adk web

O terminal mostrará:

Starting ADK Web Server...
Open http://localhost:8000 in your browser

1 2	Starting ADK Web Server... Open http://localhost:8000 in your browser

Abra o navegador e acesse http://localhost:8000.

O que a interface oferece

Seleção de Agente: Lista todos os agentes encontrados no diretório. Selecione qual agente testar.

Chat Interativo: Interface de conversa para enviar mensagens e ver respostas. Similar a usar ChatGPT ou Gemini diretamente.

Eventos em Tempo Real: Visualização de todos os eventos do agente: chamadas de modelo, invocações de ferramentas, mudanças de estado.

Inspeção de Estado: Visualize o estado atual da sessão e como ele muda durante a conversa.

Testando um agente mínimo

Antes de testar, precisamos de um agente. Edite greeting_agent/agent.py:

from google.adk.agents import Agent

greeting_agent = Agent(
    name="greeting_agent",
    model="gemini-2.0-flash",
    description="Um agente amigável que cumprimenta usuários",
    instructions="Você é um assistente amigável. Cumprimente o usuário de forma calorosa."
)

from google.adk.agents import Agent

greeting_agent = Agent(

name="greeting_agent",

model="gemini-2.0-flash",

description="Um agente amigável que cumprimenta usuários",

instructions="Você é um assistente amigável. Cumprimente o usuário de forma calorosa."

)

Note que o nome da variável (greeting_agent) corresponde ao nome da pasta.

Agora execute adk web e teste:

Selecione “greeting_agent” na lista
Digite “Olá!” no chat
Observe a resposta do agente

Se tudo estiver configurado corretamente, você verá uma saudação amigável.

Executando agentes programaticamente

A interface web é excelente para desenvolvimento, mas eventualmente você precisará executar agentes em código.

Script básico de execução

Crie um arquivo main.py na raiz do projeto:

import asyncio
from google.adk.runners import Runner
from google.adk.sessions import InMemorySessionService
from google.genai import types

<em># Importar o agente</em>
from greeting_agent.agent import greeting_agent

async def main():
    <em># Configurar serviço de sessão</em>
    session_service = InMemorySessionService()

    <em># Criar sessão</em>
    session = await session_service.create_session(
        app_name="meu_app",
        user_id="usuario_teste"
    )

    <em># Criar runner</em>
    runner = Runner(
        agent=greeting_agent,
        app_name="meu_app",
        session_service=session_service
    )

    <em># Preparar mensagem</em>
    content = types.Content(
        role="user",
        parts=[types.Part.from_text("Olá! Como você está?")]
    )

    <em># Executar e coletar resposta</em>
    print("Agente: ", end="", flush=True)
    async for event in runner.run_async(
        user_id="usuario_teste",
        session_id=session.id,
        new_message=content
    ):
        if hasattr(event, 'content') and event.content:
            for part in event.content.parts:
                if hasattr(part, 'text'):
                    print(part.text, end="", flush=True)
    print()

if __name__ == "__main__":
    asyncio.run(main())

import asyncio

from google.adk.runners import Runner

from google.adk.sessions import InMemorySessionService

from google.genai import types

# Importar o agente

from greeting_agent.agent import greeting_agent

async def main():

# Configurar serviço de sessão

session_service = InMemorySessionService()

# Criar sessão

session = await session_service.create_session(

app_name="meu_app",

user_id="usuario_teste"

)

# Criar runner

runner = Runner(

agent=greeting_agent,

app_name="meu_app",

session_service=session_service

)

# Preparar mensagem

content = types.Content(

role="user",

parts=[types.Part.from_text("Olá! Como você está?")]

)

# Executar e coletar resposta

print("Agente: ", end="", flush=True)

async for event in runner.run_async(

user_id="usuario_teste",

session_id=session.id,

new_message=content

if hasattr(event, 'content') and event.content:

for part in event.content.parts:

if hasattr(part, 'text'):

print(part.text, end="", flush=True)

print()

if __name__ == "__main__":

asyncio.run(main())

Execute:

python main.py

1	python main.py

Session service gerencia a memória do agente

session_service = InMemorySessionService()

1	session_service = InMemorySessionService()

O SessionService é o componente responsável por gerenciar o estado das conversas. Sem ele, cada mensagem seria tratada como se fosse a primeira interação. O agente não lembraria o que você disse há dois segundos.

O InMemorySessionService armazena tudo na memória RAM. Quando o programa termina, os dados são perdidos. Isso é intencional para desenvolvimento e testes. Em produção, você utilizaria DatabaseSessionService com SQLite, PostgreSQL ou outro banco para persistência real.

Session representa uma conversa individual

session = await session_service.create_session(
    app_name="meu_app",
    user_id="usuario_teste"
)

session = await session_service.create_session(

app_name="meu_app",

user_id="usuario_teste"

)

Uma sessão é uma conversa individual. O método create_session cria nova instância e retorna um objeto Session contendo ID único gerado automaticamente, dicionário de estado para dados customizados e histórico de mensagens.

O parâmetro app_name identifica sua aplicação. O mesmo serviço pode gerenciar múltiplas aplicações diferentes. O parâmetro user_id identifica o usuário. Um usuário pode ter múltiplas sessões simultâneas, como abas diferentes de chat.

Runner orquestra todo o fluxo de wxecução

runner = Runner(
    agent=greeting_agent,
    app_name="meu_app",
    session_service=session_service
)

runner = Runner(

agent=greeting_agent,

app_name="meu_app",

session_service=session_service

)

O Runner é o motor de execução do ADK. Ele conecta agente, sessão e modelo de linguagem em um fluxo coerente.

Quando você executa o runner, ele carrega o contexto da sessão, adiciona a nova mensagem ao histórico, monta o prompt completo com instruções do agente, envia para o modelo Gemini, processa a resposta incluindo possíveis chamadas de ferramentas, salva o novo estado na sessão e emite eventos para você consumir.

O parâmetro agent é o agente que será executado. O app_name deve corresponder ao usado na criação da sessão. O session_service é a referência ao serviço que gerencia as sessões.

Content Estrutura Mensagens no Formato do Gemini

content = types.Content(
    role="user",
    parts=[types.Part.from_text("Olá! Como você está?")]
)

content = types.Content(

role="user",

parts=[types.Part.from_text("Olá! Como você está?")]

)

O ADK utiliza o formato de mensagem do Gemini. O objeto Content representa uma mensagem completa. O parâmetro role indica quem está falando, podendo ser "user" para o usuário ou "model" para o agente.

O parâmetro parts é uma lista que contém os pedaços do conteúdo. Uma mensagem pode ter múltiplas partes porque o Gemini é multimodal. Você pode enviar texto e imagem na mesma mensagem, texto e áudio, ou qualquer combinação suportada. O método Part.from_text() cria uma parte de texto simples.

O Loop de Eventos Processa a Resposta em Streaming

async for event in runner.run_async(
    user_id="usuario_teste",
    session_id=session.id,
    new_message=content
):
    if hasattr(event, 'content') and event.content:
        for part in event.content.parts:
            if hasattr(part, 'text'):
                print(part.text, end="", flush=True)

async for event in runner.run_async(

user_id="usuario_teste",

session_id=session.id,

new_message=content

if hasattr(event, 'content') and event.content:

for part in event.content.parts:

if hasattr(part, 'text'):

print(part.text, end="", flush=True)

O método run_async retorna um gerador assíncrono de eventos. A resposta não vem de uma vez. Ela chega em pedaços conforme o modelo gera texto. Isso permite exibir a resposta em tempo real, sem esperar o modelo terminar de pensar.

Os parâmetros user_id e session_id identificam a sessão existente. O new_message é a mensagem do usuário a ser processada.

O loop async for itera sobre cada evento emitido. Nem todo evento contém conteúdo de texto. Alguns eventos representam chamadas de ferramentas, resultados de ferramentas ou mudanças de estado. Por isso a verificação hasattr(event, 'content') é necessária.

Dentro do evento, content.parts pode conter múltiplas partes. Cada parte é verificada individualmente. Se a parte tem atributo text, é texto gerado pelo modelo.

O print com end="" não adiciona quebra de linha, permitindo que os pedaços de texto apareçam continuamente na mesma linha. O flush=True força exibição imediata, sem esperar o buffer do terminal encher.

Estrutura de projeto avançada

À medida que o projeto cresce, você precisará de estrutura mais elaborada.

Estrutura recomendada para projetos maiores

meu_projeto/
├── pyproject.toml              # Configuração do projeto
├── requirements.txt            # Dependências
├── .gitignore                  # Arquivos ignorados pelo git
├── README.md                   # Documentação
├── .env.example                # Template de variáveis (sem valores reais)
├── agents/
│   ├── support_agent/
│   │   ├── __init__.py
│   │   ├── .env
│   │   └── agent.py
│   ├── sales_agent/
│   │   ├── __init__.py
│   │   ├── .env
│   │   └── agent.py
│   └── coordinator/
│       ├── __init__.py
│       ├── .env
│       └── agent.py
├── tools/
│   ├── __init__.py
│   ├── crm_tools.py            # Ferramentas de CRM
│   └── analytics_tools.py      # Ferramentas de analytics
├── tests/
│   ├── __init__.py
│   ├── test_support_agent.py
│   └── test_sales_agent.py
└── scripts/
    ├── run_support.py
    └── run_coordinator.py

meu_projeto/

├── pyproject.toml # Configuração do projeto

├── requirements.txt # Dependências

├── .gitignore # Arquivos ignorados pelo git

├── README.md # Documentação

├── .env.example # Template de variáveis (sem valores reais)

├── agents/

│ ├── support_agent/

│ │ ├── __init__.py

│ │ ├── .env

│ │ └── agent.py

│ ├── sales_agent/

│ │ ├── __init__.py

│ │ ├── .env

│ │ └── agent.py

│ └── coordinator/

│ ├── __init__.py

│ ├── .env

│ └── agent.py

├── tools/

│ ├── __init__.py

│ ├── crm_tools.py # Ferramentas de CRM

│ └── analytics_tools.py # Ferramentas de analytics

├── tests/

│ ├── __init__.py

│ ├── test_support_agent.py

│ └── test_sales_agent.py

└── scripts/

├── run_support.py

└── run_coordinator.py

Arquivo .gitignore

Crie um .gitignore para evitar commits acidentais de arquivos sensíveis:

# Ambientes virtuais
venv/
adk-env/
.venv/

# Variáveis de ambiente
.env

# Cache Python
__pycache__/
*.pyc
*.pyo

# IDEs
.vscode/
.idea/

# Bancos de dados locais
*.db
*.sqlite

# Logs
*.log

# Distribuição
dist/
build/
*.egg-info/

# Ambientes virtuais

venv/

adk-env/

.venv/

# Variáveis de ambiente

.env

# Cache Python

__pycache__/

*.pyc

*.pyo

# IDEs

.vscode/

.idea/

# Bancos de dados locais

*.db

*.sqlite

# Logs

*.log

# Distribuição

dist/

build/

*.egg-info/

Arquivo .env.example

Documente as variáveis necessárias sem expor valores reais:

# Google AI API Key (obtenha em aistudio.google.com)
GOOGLE_API_KEY=your_api_key_here

1 2	# Google AI API Key (obtenha em aistudio.google.com) GOOGLE_API_KEY=your_api_key_here

Troubleshooting comum

Erro: “No agents found”

Causa: O ADK não encontrou pastas com estrutura válida de agente.

Solução: Verifique que existe:

Pasta do agente com agent.py
Arquivo __init__.py na pasta
Você está executando adk web da pasta correta (pai das pastas de agentes)

Erro: “GOOGLE_API_KEY not set”

Causa: Variável de ambiente não configurada.

Solução: Crie arquivo .env dentro da pasta do agente com:

GOOGLE_API_KEY=sua_chave_aqui

1	GOOGLE_API_KEY=sua_chave_aqui

Erro: “Agent name doesn’t match folder name”

Causa: O parâmetro name no Agent não corresponde ao nome da pasta.

Solução: Se a pasta é greeting_agent, o código deve ter:

greeting_agent = Agent(name="greeting_agent", ...)

1	greeting_agent = Agent(name="greeting_agent", ...)

Erro: “ModuleNotFoundError: No module named ‘google.adk'”

Causa: ADK não instalado ou ambiente virtual não ativado.

Solução:

<em># Ativar ambiente virtual</em>
source adk-env/bin/activate  <em># Linux/macOS</em>
adk-env\Scripts\activate     <em># Windows</em>

<em># Reinstalar se necessário</em>
pip install google-adk

# Ativar ambiente virtual

source adk-env/bin/activate # Linux/macOS

adk-env\Scripts\activate # Windows

# Reinstalar se necessário

pip install google-adk

Erro: “API key not valid”

Causa: API Key incorreta ou expirada.

Solução: Gere nova chave em aistudio.google.com e atualize o arquivo .env.

FAQ: Perguntas Frequentes

1. Posso usar o Google ADK sem API Key?

Não para os modelos Gemini da Google. A API Key é obrigatória para autenticação. Você pode usar modelos locais via Ollama ou outros provedores via LiteLLM, mas isso adiciona complexidade à configuração inicial.

2. A API Key do Google AI Studio tem custo?

A camada gratuita é generosa o suficiente para desenvolvimento e aprendizado. Para produção com alto volume, considere Vertex AI que oferece mais controle e SLAs.

3. Posso ter múltiplas API Keys para diferentes agentes?

Sim. Cada pasta de agente tem seu próprio arquivo .env. Você pode configurar chaves diferentes para cada agente se necessário (por exemplo, diferentes projetos de billing).

4. O adk web funciona em produção?

Não. O adk web é ferramenta de desenvolvimento. Para produção, use os métodos de deploy: Vertex AI Agent Engine, Cloud Run, GKE ou containers customizados.

5. Preciso de conta Google Cloud para usar o ADK?

Não para desenvolvimento básico. A API Key do Google AI Studio é suficiente. Google Cloud é necessário apenas para deploy em produção usando serviços como Vertex AI Agent Engine.

Compartilhe:

Tiago Tartari

Eu ajudo e capacito pessoas e organizações a transformar problemas complexos em soluções práticas usando a tecnologia para atingir resultados extraordinários.

Qual é o desafio
que você tem hoje?

Agentes de IA: Como Configurar Ambiente para Google ADK Facilmente

Conteúdo

Insights

Pré-Requisitos de Sistema são mínimos

Python 3.10 ou Posterior

IDE ou Editor de código

Conexão com Internet

API Key do Google AI Studio é gratuita e suficiente

Obtendo a API Key

Limites da camada gratuita

Segurança da API Key

Instalação do Google ADK

Criando ambiente virtual

Instalando o pacote

Verificando a instalação

Estrutura mínima

Criando a estrutura

Configurando o arquivo .env

Estrutura para múltiplos agentes

A Interface web acelera o desenvolvimento

Iniciando a interface web

O que a interface oferece

Testando um agente mínimo

Executando agentes programaticamente

Script básico de execução

Session service gerencia a memória do agente

Session representa uma conversa individual

Runner orquestra todo o fluxo de wxecução

Content Estrutura Mensagens no Formato do Gemini

O Loop de Eventos Processa a Resposta em Streaming

Estrutura de projeto avançada

Estrutura recomendada para projetos maiores

Arquivo .gitignore

Arquivo .env.example

Troubleshooting comum

Erro: “No agents found”

Erro: “GOOGLE_API_KEY not set”

Erro: “Agent name doesn’t match folder name”

Erro: “ModuleNotFoundError: No module named ‘google.adk'”

Erro: “API key not valid”

FAQ: Perguntas Frequentes

1. Posso usar o Google ADK sem API Key?

2. A API Key do Google AI Studio tem custo?

3. Posso ter múltiplas API Keys para diferentes agentes?

4. O adk web funciona em produção?

5. Preciso de conta Google Cloud para usar o ADK?