Como criar agentes de IA com o ADK: os fundamentos

1. Antes de começar

Esta é a primeira parte da série "Como criar agentes de IA com o ADK". Nesta série de codelabs práticos, você vai embarcar em uma jornada emocionante para criar seu próprio agente inteligente de IA usando o Kit de desenvolvimento de agentes (ADK, na sigla em inglês) do Google.

Vamos começar com o essencial, orientando você na configuração do ambiente de desenvolvimento e na criação de um agente de conversa básico. Ao final deste codelab, você terá criado sua primeira IA interativa, pronta para ser expandida nas próximas partes desta série à medida que a transformamos em um sofisticado sistema multiagente (MAS, na sigla em inglês).

É possível concluir este codelab no seu ambiente local ou no Google Cloud. Para uma experiência mais consistente, recomendamos usar o Cloud Shell no ambiente do Google Cloud. O Cloud Shell também oferece 5 GB de armazenamento permanente no diretório $HOME. Isso é útil para armazenar scripts, arquivos de configuração ou repositórios clonados.

Observação:se você optar por trabalhar localmente, talvez precise seguir outras etapas de configuração, instalação e autenticação, que não estão incluídas na seção de configuração do ambiente deste laboratório.

Pré-requisitos

• Entendimento dos conceitos de IA generativa
• Proficiência básica em programação em Python
• Familiaridade com a linha de comando / terminal

O que você vai aprender

• Como configurar um ambiente Python
• Como criar um agente de assistente pessoal simples usando o ADK
• Como executar, testar e depurar o agente

O que é necessário

• Um computador em funcionamento com uma rede Wi-Fi confiável
• Um navegador, como o Chrome, para acessar o Console do Google Cloud
• Ter um projeto do Google Cloud com o faturamento ativado
• Uma mente curiosa e vontade de aprender

2. Introdução

O mundo da IA generativa (GenAI) está evoluindo rapidamente, e os agentes de IA são um assunto em alta no momento. Um agente de IA é um programa de computador inteligente projetado para agir em seu nome, assim como um assistente pessoal. Ela pode perceber o ambiente digital, tomar decisões e realizar ações para alcançar metas específicas sem controle humano direto. Pense nele como uma entidade proativa e autônoma que pode aprender e se adaptar para realizar tarefas.

Basicamente, um agente de IA usa um modelo de linguagem grande (LLM) como "cérebro" para entender e raciocinar. Isso permite que ele processe informações de várias fontes, como texto, imagens e sons. Em seguida, o agente usa esse entendimento para criar um plano e executar uma série de tarefas para atingir um objetivo predefinido.

Agora é fácil criar seus próprios agentes de IA, mesmo sem conhecimento profundo, devido a frameworks prontos para uso, como o Kit de Desenvolvimento de Agente (ADK). Vamos começar essa jornada construindo um agente de assistente pessoal para ajudar você com suas tarefas. Vamos começar.

3. Configurar os serviços do Google Cloud

Criar um projeto do Google Cloud

Este codelab pressupõe que você já criou um projeto do Google Cloud com o faturamento ativado. Se você ainda não tiver um projeto, siga estas etapas para criar um:

Selecionar ou criar um projeto do Google Cloud

• Navegue até o Console do Google Cloud.
• Na parte de cima, clique no menu suspenso do seletor de projetos (ao lado do logotipo do Google Cloud).
• Escolha um projeto atual ou crie um novo.

Ativar faturamento

• Verifique se o faturamento está ativado para o projeto do Google Cloud selecionado.
• Para saber como verificar se o faturamento está ativado em um projeto, siga as instruções na documentação do Google Cloud Billing.

Observação:o faturamento precisa estar ativado mesmo para serviços do nível sem custo financeiro, já que é o mecanismo usado pelo Google Cloud para rastrear o uso de recursos. No entanto, você só vai receber cobranças se o uso exceder os limites do nível sem custo financeiro ou se você usar serviços pagos.

Configurar o Cloud Shell

Agora, vamos verificar se você está configurado corretamente no Cloud Shell, uma interface de linha de comando prática diretamente no Console do Google Cloud.

Iniciar o Cloud Shell

No canto superior direito do console do Google Cloud, clique no ícone que parece um terminal (>_) para ativar o Cloud Shell.

Autorizar acesso

Se for preciso, clique em Autorizar para conceder ao Cloud Shell as permissões necessárias para interagir com seu projeto do Google Cloud.

Verificar sua conta:

Depois que o Cloud Shell for carregado, confirme se você está usando a conta correta do Google Cloud. Execute este comando:

gcloud auth list

Você vai encontrar uma saída de comando semelhante no terminal:

Credentialed Accounts

ACTIVE: *
ACCOUNT: [e-mail]

To set the active account, run:
    $ gcloud config set account `ACCOUNT`

Mudar de conta (se necessário):

Se a conta ativa não for a que você pretende usar neste codelab, mude para a conta correta usando este comando, substituindo <[e-mail]> pelo e-mail que você vai usar neste laboratório:

gcloud config set account <[e-mail]

Confirmar seu projeto

Em seguida, vamos verificar se o Cloud Shell está configurado para usar o projeto correto do Google Cloud. Execute:

gcloud config list project

Uma lista de configurações vai aparecer. Procure a seção [core] e verifique se o valor do projeto corresponde ao ID do projeto do Google Cloud que você quer usar neste codelab:

[core]
project = <current-project-id>

Definir seu projeto (se necessário)

Se o valor de project ID estiver incorreto, defina o projeto desejado usando o seguinte comando:

gcloud config set project <your-desired-project-id>

Ativar as APIs necessárias

Para usar os serviços do Google Cloud, primeiro é necessário ativar as APIs respectivas no seu projeto. Executar os comandos abaixo no terminal do Cloud Shell ativa todos os serviços necessários para este codelab:

gcloud services enable aiplatform.googleapis.com

Se a operação for concluída, você verá Operation/... finished successfully impresso no terminal.

4. Crie um ambiente virtual em Python.

Antes de iniciar qualquer projeto em Python, é recomendável criar um ambiente virtual. Isso isola as dependências do projeto, evitando conflitos com outros projetos ou com os pacotes globais do Python no sistema. Como o Agent Development Kit (ADK) exige o Python 3.9 ou mais recente, vamos usar uma ferramenta como o uv para gerenciar o ambiente virtual e garantir que a versão correta do Python seja usada.

O uv é uma ferramenta moderna, rápida e eficiente para gerenciar projetos e ambientes Python, combinando funcionalidades encontradas tradicionalmente em ferramentas como pip, venv, pip-tools e pipx. Ele é escrito em Rust para ser rápido.

O Cloud Shell já tem o uv disponível, então podemos começar imediatamente.

Verifique se o uv está instalado corretamente

uv --version

Criar uma pasta de projeto para seu agente de IA

uv init ai-agents-adk
cd ai-agents-adk

Criar um ambiente virtual com o Python 3.12

uv venv --python 3.12

Instale a biblioteca do ADK do Google no ambiente virtual

uv add google-adk

Verifique se você instalou o pacote google-adk

uv pip list | grep google-adk

Se você vir uma linha de saída com google-adk e a versão dele, siga para a próxima etapa.

5. Criar um agente

Agora que seu ambiente de desenvolvimento está configurado e pronto, é hora de criar a base do seu agente de IA. O Kit de Desenvolvimento de Agentes (ADK, na sigla em inglês) simplifica esse processo, exigindo apenas alguns arquivos essenciais para definir a lógica e a configuração principais do seu agente.

Esses três arquivos trabalham juntos para tornar seu agente detectável, executável e configurável:

• agent.py: é o coração do seu agente. Ele contém o código Python principal que define o comportamento do agente, incluindo o nome, o modelo de linguagem grande (LLM) que ele usa como "cérebro" e as instruções principais que orientam as respostas.
• __init__.py: em Python, o arquivo __init__.py marca um diretório como um pacote Python. Para o ADK, isso é crucial porque ajuda o framework a descobrir e carregar a definição do agente em agent.py. Em projetos simples do ADK, ele geralmente contém uma única linha para importar o módulo agent, tornando seu agente acessível ao executor do ADK.
• .env: esse arquivo (abreviação de "ambiente") é usado para armazenar informações sensíveis e variáveis de configuração necessárias ao seu agente, como chaves de API, IDs de projetos e locais geográficos. Manter esses detalhes em um arquivo .env separado é uma prática recomendada para segurança e portabilidade, já que evita a codificação de dados sensíveis diretamente no código. Também é possível mudar as configurações com facilidade sem modificar a lógica principal do agente.

Use os comandos abaixo para criar esses arquivos em uma pasta dedicada ao seu agente assistente pessoal:

uv run adk create personal_assistant

Depois que o comando for executado, você precisará escolher algumas opções para configurar o agente. Na primeira etapa, escolha a opção 1 para usar o modelo gemini-2.5-flash, que é rápido e eficiente, perfeito para tarefas de conversa.

Choose a model for the root agent:
1. gemini-2.5-flash
2. Other models (fill later)
Choose model (1, 2): 1

Na segunda etapa, escolha Vertex AI (opção 2), a plataforma de IA gerenciada e avançada do Google Cloud, como provedor de serviços de back-end.

1. Google AI
2. Vertex AI
Choose a backend (1, 2): 2

Por fim, você vai precisar confirmar o ID do projeto e a região do Google Cloud. Se os valores preenchidos automaticamente (current-project-id e current-region) forem os que você pretende usar, basta pressionar Enter para cada pergunta.

Enter Google Cloud project ID [current-project-id]: 
Enter Google Cloud region [current-region]:

Você vai ver uma saída semelhante no terminal.

Agent created in /home/<your-username>/ai-agent-adk/personal_assistant:
- .env
- __init__.py
- agent.py

Agora, clique no botão Abrir editor na parte de cima da janela do Cloud Shell. Ao clicar nesse botão, você acessa a janela do Editor, que facilita a análise do conteúdo dos seus arquivos. A troca pode levar um tempo. Se você ficar preso em uma tela de carregamento por mais de alguns minutos, tente atualizar o navegador.

Observação:você pode usar um editor de linha de comando como o Vim, mas precisa saber os comandos para abrir e sair dele.

Quando a janela do editor estiver totalmente carregada, navegue até a pasta personal-assistant. Você vai encontrar os arquivos necessários, conforme mencionado acima (agent.py, __init__.py e .env). Vamos analisar o conteúdo.

Se o arquivo .env não aparecer na pasta, acesse a barra de menus na parte de cima, clique em "Visualizar" e selecione Alternar arquivos ocultos. Essa é uma configuração comum, já que os arquivos .env geralmente ficam ocultos por padrão para evitar exposição acidental.

Vamos analisar o conteúdo de cada arquivo.

agent.py

Esse arquivo instancia seu agente usando a classe Agent da biblioteca google.adk.agents.

from google.adk.agents import Agent

root_agent = Agent(
    model='gemini-2.5-flash',
    name='root_agent',
    description='A helpful assistant for user questions.',
    instruction='Answer user questions to the best of your knowledge',
)

• from google.adk.agents import Agent: essa linha importa a classe Agent necessária da biblioteca ADK.
• root_agent = Agent(...): aqui, você está criando uma instância do seu agente de IA.
• name="personal_assistant": um identificador exclusivo para seu agente. É assim que o ADK vai reconhecer e se referir ao seu agente.
• model="gemini-2.5-flash": esse parâmetro crucial especifica qual modelo de linguagem grande (LLM) seu agente vai usar como "cérebro" para entender, raciocinar e gerar respostas. O gemini-2.5-flash é um modelo rápido e eficiente adequado para tarefas de conversa.
• description="...": fornece um resumo conciso da finalidade ou das capacidades do agente. A descrição é mais para compreensão humana ou para que outros agentes em um sistema multiagente entendam o que esse agente específico faz. Geralmente é usado para geração de registros, depuração ou ao mostrar informações sobre o agente.
• instruction="...": é o comando do sistema que orienta o comportamento do agente e define a personalidade dele. Ela informa à LLM como agir e qual é o propósito principal. Nesse caso, ela estabelece o agente como um "assistente útil". Essa instrução é fundamental para moldar o estilo e as capacidades de conversa do agente.

init.py

Esse arquivo é necessário para que o Python reconheça personal-assistant como um pacote, permitindo que o ADK importe corretamente o arquivo agent.py.

from . import agent

• from . import agent: essa linha realiza uma importação relativa, informando ao Python para procurar um módulo chamado agent (que corresponde a agent.py) no pacote atual (personal-assistant). Essa linha simples garante que, quando o ADK tentar carregar o agente personal-assistant, ele possa encontrar e inicializar o root_agent definido em agent.py. Mesmo que esteja vazio, a presença de __init__.py é o que faz do diretório um pacote Python.

.env

Esse arquivo contém configurações específicas do ambiente e credenciais sensíveis.

GOOGLE_GENAI_USE_VERTEXAI=1
GOOGLE_CLOUD_PROJECT=YOUR_PROJECT_ID
GOOGLE_CLOUD_LOCATION=YOUR_PROJECT_LOCATION

• GOOGLE_GENAI_USE_VERTEXAI: informa ao ADK que você pretende usar o serviço da Vertex AI do Google para suas operações de IA generativa. Isso é importante para aproveitar os serviços gerenciados e os modelos avançados do Google Cloud.
• GOOGLE_CLOUD_PROJECT: essa variável vai conter o identificador exclusivo do seu projeto do Google Cloud. O ADK precisa disso para associar corretamente seu agente aos recursos da nuvem e ativar o faturamento.
• GOOGLE_CLOUD_LOCATION: especifica a região do Google Cloud em que seus recursos da Vertex AI estão localizados (por exemplo, us-central1). Usar o local correto garante que seu agente possa se comunicar de maneira eficaz com os serviços da Vertex AI nessa região.

6. Executar o agente no terminal

Com os três arquivos no lugar, você está pronto para executar o agente diretamente do terminal. Para fazer isso, abra a janela do Terminal. Clique em Terminal na barra de menu e escolha Novo terminal.

Quando o terminal estiver disponível, inicie o agente usando o comando adk run. Como esta é uma nova janela de terminal e estamos usando uv, primeiro navegue até a pasta ai-agent-adk e prefixe o comando adk run com uv run.

Digite estes comandos no terminal:

cd ai-agents-adk
uv run adk run personal_assistant

Se tudo estiver configurado corretamente, você verá uma saída semelhante no terminal.

...
Running agent personal_assistant, type exit to exit.
[user]: hello. What can you do for me?
[personal_assistant]: Hello! I am a large language model, trained by Google. I can do many things to help you, such as:
...

Converse com o agente! Você vai notar que a saída às vezes é formatada com Markdown, o que pode ser difícil de ler no terminal. Na próxima etapa, vamos usar a interface de desenvolvimento para uma experiência muito mais rica, semelhante a um aplicativo de chat.

7. Executar o agente na interface de desenvolvimento

O Agent Development Kit também oferece uma maneira conveniente de iniciar seu agente como um aplicativo de chat usando a interface de desenvolvimento. Basta usar o comando adk web em vez de adk run..

Se você ainda estiver na sessão anterior, basta digitar exit no terminal para fechá-la. Depois que a sessão anterior for fechada, digite o seguinte comando no terminal:

uv run adk web

Você vai ver uma saída semelhante no terminal:

...
INFO:     Started server process [4978]
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)

Você tem duas opções para acessar a interface de desenvolvimento:

1. Abrir pelo Terminal

• Ctrl + clique ou Cmd + clique nos URLs (por exemplo, http://localhost:8000) no terminal.

2. Abrir na Visualização na Web

• Clique no botão Visualização da Web.
• Selecione Alterar porta.
• Digite o número da porta (por exemplo, 8000)
• Clique em Alterar e visualizar.

Em seguida, a interface do usuário semelhante a um aplicativo de chat vai aparecer no navegador. Converse com seu assistente pessoal por essa interface. Você vai notar que a formatação Markdown agora é exibida corretamente, e essa interface também permite depurar e investigar cada evento de mensagens, o estado do agente, as solicitações do usuário e muito mais. Boas conversas para você!

8. Limpeza

Como este codelab não envolve produtos de longa duração, basta interromper as sessões de agente ativas (por exemplo, a instância adk web no terminal) pressionando Ctrl + C no terminal.

Atenção: NÃO siga estas etapas se você planeja continuar a série de codelabs, porque elas vão fazer você repetir algumas ações no próximo codelab.

Excluir pastas e arquivos do projeto do agente

Se você quiser remover apenas o código do ambiente do Cloud Shell, use os seguintes comandos:

cd ~
rm -rf ai-agents-adk

Desativar a API Vertex AI

Para desativar a API Vertex AI que foi ativada anteriormente, execute este comando:

gcloud services disable aiplatform.googleapis.com

Encerrar todo o projeto do Google Cloud

Se você quiser encerrar totalmente seu projeto do Google Cloud, consulte o guia oficial para instruções detalhadas.

9. Conclusão

Parabéns! Você criou um agente assistente pessoal simples usando o Agent Development Kit (ADK).

Como você deve ter percebido, esse agente de assistente pessoal ainda não é muito capaz. Por exemplo, ele não consegue acessar a Internet para obter as informações mais recentes. No próximo codelab desta série "Como criar agentes de IA com o ADK", você vai aprender a capacitar seu agente assistente pessoal com funções e ferramentas. Até lá!