Esta página foi traduzida pela API Cloud Translation.

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 de IA inteligente usando o Kit de Desenvolvimento de Agentes (ADK) 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ção 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 do 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.

Pré-requisitos

Noções básicas sobre os conceitos da 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
Uma mente curiosa e vontade de aprender

Resgatar uma conta de faturamento de teste

Para concluir este codelab, você também precisa de uma conta de faturamento ativa do Google Cloud. Se você ainda não tem uma, siga estas etapas para resgatar uma conta de faturamento de teste:

Abra uma janela anônima no navegador.
Acesse este portal de resgate.
Faça login usando sua conta pessoal do Gmail.
Siga as instruções detalhadas do portal.

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 nisso 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 Agent Development Kit (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

Comece criando um projeto do Google Cloud para que as atividades deste codelab fiquem isoladas apenas nesse novo projeto.

Acesse console.cloud.google.com/projectcreate.
Insira as informações necessárias:

Nome do projeto: você pode inserir qualquer nome que quiser (por exemplo, genai-workshop).
Local: deixe como Nenhuma organização.
Conta de faturamento: se essa opção aparecer, selecione Conta de faturamento de avaliação do Google Cloud Platform. Não se preocupe se essa opção não aparecer. Basta seguir para a próxima etapa.

Copie o ID do projeto gerado. Ele será necessário mais tarde.

Se tudo estiver certo, clique no botão Criar.

Configurar o Cloud Shell

Depois que o projeto for criado, siga estas etapas para configurar o Cloud Shell.

1. Iniciar o Cloud Shell

Acesse shell.cloud.google.com e, se aparecer um pop-up pedindo autorização, clique em Autorizar.

2. Definir ID do projeto

Execute o seguinte comando no terminal do Cloud Shell para definir o ID do projeto correto. Substitua <your-project-id> pelo ID do projeto copiado da etapa de criação acima.

gcloud config set project <your-project-id>

Agora você vai ver que o projeto correto está selecionado no terminal do Cloud Shell. O ID do projeto selecionado é destacado em amarelo.

3. Ativar APIs obrigatórias

Para usar os serviços do Google Cloud, primeiro é necessário ativar as APIs respectivas no seu projeto. Execute os comandos abaixo no terminal do Cloud Shell para ativar os serviços deste 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.

1. Crie um diretório de projeto e navegue até ele:

mkdir ai-agents-adk
cd ai-agents-adk

2. Crie e ative um ambiente virtual:

uv venv --python 3.12
source .venv/bin/activate

Você vai ver (ai-agents-adk) prefixando o prompt do terminal, indicando que o ambiente virtual está ativo.

3. Página de instalação do ADK

uv pip install google-adk

5. Criar um agente

Com o ambiente pronto, é hora de criar a base do seu agente de IA. O ADK exige alguns arquivos para definir a lógica e a configuração do seu agente:

agent.py: contém o código Python principal do seu agente, definindo o nome, o LLM usado e as instruções principais.
__init__.py: marca o diretório como um pacote Python, ajudando o ADK a descobrir e carregar a definição do seu agente.
.env: armazena informações sensíveis e variáveis de configuração, como chave de API, ID do projeto e local.

Esse comando cria um diretório chamado personal_assistant com os três arquivos essenciais.

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

Depois disso, verifique se o ID do projeto mostrado entre colchetes [...] está definido corretamente. Se for, pressione Enter. Caso contrário, digite o ID correto do projeto no seguinte comando:

Enter Google Cloud project ID [your-project-id]:

Por fim, pressione Enter na próxima pergunta para usar us-central1 como a região deste codelab.

Enter Google Cloud region [us-central1]:

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

6. Conhecer os códigos dos agentes

Para conferir os arquivos criados, abra a pasta ai-agents-adk no editor do Cloud Shell.

Clique em Arquivo > Abrir pasta... no menu superior.
Encontre e selecione a pasta ai-agents-adk.
Clique em OK.

Se a barra de menus na parte de cima não aparecer, clique no ícone de pastas e escolha Abrir pasta.

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).

O arquivo .env geralmente fica oculto por padrão. Para que ele fique visível no editor do Cloud Shell:

acesse a barra de menu na parte de cima;
clique em Ver e
selecione Alternar arquivos ocultos.

Confira 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="root_agent": 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 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.

7. Executar o agente no terminal

Com os três arquivos no lugar, você está pronto para executar o agente diretamente do terminal. Para isso, execute o seguinte comando adk run no terminal:

adk run personal_assistant

Se tudo estiver configurado corretamente, você verá uma saída semelhante no terminal. Não se preocupe com os avisos por enquanto. Se você vir [user]:, pode continuar.

...
Running agent personal_assistant, type exit to exit.
[user]: 
...

Converse com o agente! Digite algo como "olá. O que você pode fazer por mim?" e você vai receber uma resposta.

...
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:
...

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.

Solução de problemas

Este método de API exige que o faturamento esteja ativado

Se você receber uma mensagem dizendo {‘message': ‘This API method requires billing to be enabled'}, faça o seguinte:

Verifique se você está usando o ID do projeto correto no arquivo .env.
Acesse a página conta de faturamento vinculada e verifique se ela já está vinculada.
Caso contrário, escolha Conta de faturamento de avaliação do Google Cloud Platform na opção.

A API Vertex AI não foi usada no projeto

Se você receber uma mensagem de erro contendo {'message': 'Vertex AI API has not been used in project...'}, ative a API Vertex AI digitando o seguinte no terminal:

gcloud services enable aiplatform.googleapis.com

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

Outros erros

Se você receber outros erros não mencionados acima, tente recarregar a guia Cloud Shell no navegador e autorize novamente se solicitado.

8. Executar o agente na interface da Web de desenvolvimento

O Kit de Desenvolvimento de Agente 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 o terminal ainda estiver executando adk run, digite "exit" para fechar antes de digitar este comando:

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:

Abrir pelo Terminal

Ctrl + clique ou Cmd + clique no link (por exemplo, http://localhost:8000), conforme mostrado no terminal.

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ê!

9. Limpeza (opcional)

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 ou Cmd + C no terminal.

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.

10. Conclusão

Parabéns! Você criou um agente assistente pessoal simples usando o Kit de Desenvolvimento de Agente (ADK). Agora você tem uma base sólida e entende os componentes principais de um agente do ADK.

Como próximo passo, você pode expandir significativamente as capacidades do seu agente, fornecendo a ele ferramentas para acessar informações em tempo real e interagir com serviços externos. Se quiser continuar sua jornada, o próximo codelab desta série, Como criar agentes de IA com o ADK: capacitação com ferramentas, vai orientar você nesse processo.