ADK: das noções básicas aos agentes com várias ferramentas

1. Introdução

Começando com o básico e progredindo para o desenvolvimento de agentes de várias ferramentas, este codelab oferece uma introdução abrangente à criação de agentes com o ADK.

Em sua forma mais simples, um agente de IA é um sistema de software que usa um modelo de linguagem grande (LLM) como seu "mecanismo de raciocínio" para atingir um objetivo, realizando uma sequência de tarefas de forma autônoma.

Se um LLM é um consultor altamente capaz que pode dar conselhos, um agente de IA é um engenheiro proativo que pode usar ferramentas para executar esses conselhos.

LLM x agentes

O cérebro (LLM) : fornece raciocínio, planejamento e compreensão de linguagem natural. Ele decide o que precisa ser feito.

As mãos (ferramentas) : são as APIs, os SDKs e as funções personalizadas que permitem que o agente interaja com o mundo real. Ele executa o plano.

O Kit de Desenvolvimento de Agente (ADK)

O Kit de Desenvolvimento de Agente (ADK) é um framework especializado projetado para simplificar a criação, a implantação e a orquestração de agentes de IA. Ele fornece os blocos de construção padronizados necessários para transformar um modelo de linguagem grande estático em um agente dinâmico capaz de executar código, chamar APIs e gerenciar fluxos de trabalho de várias etapas.

Um agente de várias ferramentas é um orquestrador que pode selecionar e sequenciar diferentes funções especializadas, como um mecanismo de pesquisa, um banco de dados e uma calculadora, para resolver problemas complexos. Ele determina de forma inteligente qual ferramenta usar para cada etapa e pode transmitir a saída de uma ação como entrada para a próxima para atingir uma meta final.

O que você vai criar

Neste codelab, você vai criar um agente de "Dicas saudáveis", um consultor nutricional inteligente que faz a transição do raciocínio de texto simples para uma potência de várias ferramentas. Você vai começar criando um agente de conversação básico que entende conceitos de nutrição e, em seguida, equipá-lo progressivamente com uma ferramenta do SDK do Storage para arquivar imagens de ingredientes e uma ferramenta Vision para "ler" e analisar essas imagens. Ao final deste laboratório, você terá um orquestrador totalmente funcional que pode receber uma foto enviada de um rótulo de alimento, armazená-la em um bucket do Cloud para fins de manutenção de registros e fornecer imediatamente "Dicas saudáveis" para cada ingrediente.

2. Pré-requisitos

Um projeto do Google Cloud com o faturamento ativado
Um navegador da Web

Criar seu projeto

No console do Google Cloud, na página de seletor de projetos, selecione ou crie um projeto do Google Cloud.
Confira se o faturamento está ativado no seu projeto na nuvem. Saiba como verificar se o faturamento está ativado em um projeto.

Ativar o Cloud Shell

Você vai usar o Cloud Shell, um ambiente de linha de comando executado no console do Google Cloud que vem pré-carregado com os idiomas necessários instalados. No console do Cloud, clique em Ativar o Cloud Shell no canto superior direito:

Depois de se conectar ao Cloud Shell, você vai ver que sua conta já está autenticada e que o projeto está configurado com o ID do seu projeto. Execute o comando a seguir no Cloud Shell para confirmar se a conta está autenticada:

gcloud auth list

Execute o comando a seguir no Cloud Shell para confirmar se o comando gcloud sabe sobre seu projeto:

gcloud config list project

Se o projeto não estiver definido, use este comando:

gcloud config set project <YOUR_PROJECT_ID>

Consulte a documentação para ver o uso e os comandos gcloud.

Abrir editor

Neste codelab, vamos usar o editor do Cloud integrado. Na janela do Cloud Shell, clique no botão "Abrir editor" no canto superior direito. Isso vai abrir um editor do VSCode.

3. Configuração do ADK

Vamos passar para o terminal do Cloud Shell que ativamos na seção anterior:

Criar e ativar o ambiente virtual (recomendado)

No terminal do Cloud Shell, crie um ambiente virtual:

python -m venv .venv

Ative o ambiente virtual:

source .venv/bin/activate

Instale o ADK

pip install google-adk

4. Chave de API do Google

Crie a chave de API do Google usando o AI Studio:

Acesse https://aistudio.google.com/ e, no menu inferior esquerdo, clique em Get API Key.

Você verá uma janela "Chaves de API". Clique em "Criar chave de API" nessa janela:

Você verá um pop-up para criar uma nova chave. Nomeie a chave como: healthy-hints-key

Acesse o menu suspenso "Escolher um projeto importado".

Clique em Import Project. Uma janela lateral vai mostrar todos os seus projetos do Google Cloud. Selecione aquele com que você quer trabalhar.

Clique em "Importar".

O menu suspenso será atualizado com o projeto que você acabou de importar. Selecione o projeto no menu suspenso. Clique em "Criar chave agora". Agora você verá a lista de chaves de API criadas. Clique no ícone de cópia da chave de API que você acabou de criar.

5. Agente de amostra

No terminal do Cloud Shell, crie um diretório raiz para seu agente no local do projeto desejado:

adk create healthy_hints

Você pode escolher qualquer modelo, mas, para este codelab, vamos usar o gemini-2.5-flash.

Para este codelab, vamos usar o Google AI. Cole a chave de API que você criou na etapa anterior.

Vamos abrir a pasta que acabamos de criar. No menu mais à esquerda, clique no ícone e em "Arquivo" > "Abrir pasta". Selecione a pasta healthy_hints que acabou de ser criada. Ela normalmente reside na pasta /home/<username>.
A estrutura de pastas healthy_hints normalmente tem esta aparência:

Você verá um arquivo .env que tem sua chave de API do Google. É possível usar esse arquivo para definir qualquer variável de ambiente.
Outro arquivo chamado agent.py também é criado, e esse é nosso arquivo de agente principal. É aqui que um agente raiz de amostra é criado. Vamos analisar de perto o conteúdo desse arquivo. Primeiro, importamos o llm_agent do ADK. Em seguida, usamos o DSL do ADK para criar o agente raiz. Especificamos o nome do modelo como Gemini-2.5-flash, nomeamos o agente e fornecemos uma boa descrição dele. A instrução é a coisa mais importante aqui. É nela que informamos ao agente o que ele precisa fazer em linguagem natural.
Esse agente de amostra é bastante genérico. Ele apenas responde a qualquer pergunta que um usuário tenha.
Agora vamos executar esse agente localmente. Há duas maneiras de interagir com esse agente : CLI e Web.
CLI: execute o comando a seguir fora do diretório healthy_hints.

adk run healthy_hints

Ou, se você estiver no diretório healthy_hints, execute o comando a seguir:

adk run .

Você verá uma saída semelhante a esta:

Escreva "oi" ou qualquer pergunta que você tenha. A resposta pode ser diferente para cada pessoa. Essa é a natureza da IA generativa.

Web: execute o comando a seguir no diretório pai de healthy_hints :

adk web

6. Agente de várias ferramentas

Uma ferramenta é uma parte modular do código, normalmente uma função ou uma API, que permite que um agente interaja com o mundo além do conhecimento interno.

Tipos de ferramentas no ADK

Ferramentas de função:lógica personalizada que você mesmo escreve. Por exemplo, uma função que se conecta ao seu banco de dados específico ou um "analisador de registros" personalizado para o formato exclusivo da sua empresa.
Ferramentas integradas: recursos prontos para uso fornecidos pelo Google ou pelo ADK, como a Pesquisa Google, o Interpretador de código ou o Mecanismo RAG do Google.
Agents-as-Tools::em sistemas avançados de "várias ferramentas" ou "vários agentes", um agente especializado pode atuar como uma ferramenta para outro. Por exemplo, um "agente de pesquisa" pode ser uma ferramenta usada por um "agente de gerenciamento de pesquisa".

Neste codelab, vamos abordar as ferramentas de função. Agora, vamos avançar nosso agente e torná-lo de várias ferramentas.

Vamos adicionar um novo método get_weather em agent.py

def get_weather(city: str) -> dict:
  """Retrieves the current weather report for a specified city.

  Args:
    city (str): The name of the city for which to retrieve the weather report.

  Returns:
    dict: status and result or error msg.
  """
  if city.lower() == "new york":
    return {
      "status": "success",
      "report": (
          "The weather in New York is sunny with a temperature of 25 degrees"
          " Celsius (77 degrees Fahrenheit)."
      ),
    }
  else:
    return {
      "status": "error",
      "error_message": f"Weather information for '{city}' is not available.",
    }

Vamos modificar o agent.py e mudar o nome, a descrição e a instrução do agente:

root_agent = Agent(
    model='gemini-2.5-flash',
    name='healthy_hints_agent',
    description='Agent to answer questions about the weather in a city.',
    instruction='You are a helpful agent who can answer user questions about the weather in a city.',
    tools=[get_weather],
)

Até agora, criamos apenas uma ferramenta. Agora vamos criar várias ferramentas:

Vamos criar outro método chamado get_current_time :

def get_current_time(city: str) -> dict:
  """Returns the current time in a specified city.

  Args:
    city (str): The name of the city for which to retrieve the current time.

  Returns:
    dict: status and result or error msg.
  """

  if city.lower() == "new york":
    tz_identifier = "America/New_York"
  else:
    return {
      "status": "error",
      "error_message": (
        f"Sorry, I don't have timezone information for {city}."
      ),
    }

  tz = ZoneInfo(tz_identifier)
  now = datetime.datetime.now(tz)
  report = (
    f'The current time in {city} is {now.strftime("%Y-%m-%d %H:%M:%S %Z%z")}'
  )
  return {"status": "success", "report": report}

E vamos modificar nosso agente para invocar essa ferramenta também:

root_agent = Agent(
  model='gemini-2.5-flash',
  name='healthy_hints_agent',
  description='Agent to answer questions about the time and weather in a city.',
  instruction='You are a helpful agent who can answer user questions about the time and weather in a city.',
  tools=[get_weather, get_current_time],
)

Modificamos a descrição, a instrução e as ferramentas de acordo. Agora, vamos executar esse agente atualizado. Desta vez, o agente também responderá com a hora e o clima atuais.

7. Integração do SDK

Agora que sabemos como usar várias ferramentas. Vamos trabalhar com alguns exemplos reais. Vamos criar um agente de dicas saudáveis. Nossa agenda aqui é fazer o upload de qualquer imagem que tenha uma lista de ingredientes para nosso agente, e o agente vai nos informar sobre cada ingrediente que é saudável ou não.

Vamos criar um bucket primeiro para fazer o upload da imagem no Google Cloud Storage. Vamos abrir uma nova guia e acessar https://console.cloud.google.com/ e, na barra de pesquisa, digitar "cloud storage". Agora, selecione "Cloud Storage" em "Produtos e páginas":

Isso vai levar você à página de visão geral do Google Cloud Storage. Clique no botão Create bucket. Na página "Criar bucket", insira o nome do bucket. O nome pode ser qualquer coisa, mas, para este codelab, vamos colocar healthy-hints-bucket-kolkata . Deixe tudo no estado em que se encontra e clique no botão Create.

Vamos criar um novo arquivo chamado requirements.txt e adicionar google-cloud-storage nele. Vamos usar o SDK do Storage do Python para fazer o upload da imagem no Storage.

Primeiro, vamos instalar as dependências:

pip install -r requirements.txt

Talvez seja necessário ativar a API Storage primeiro. Execute o comando a seguir no terminal para fazer isso:

gcloud services enable storage.googleapis.com

Agora vamos adicionar uma nova ferramenta para fazer o upload da imagem.

def upload_image() -> str:
  storage_client = storage.Client()
  bucket_name = "healthy-hints-bucket-kolkata"
  bucket = storage_client.bucket(bucket_name)
  blob = bucket.blob("ingredirents")
  blob.upload_from_filename(<image-file-path>)

Agora, vamos atualizar nosso agente para que ele use a nova ferramenta:

root_agent = Agent(
  model='gemini-2.5-flash',
  name='healthy_hints_agent',
  description='Agent to upload image to Google Cloud Storage',
  instruction='You are a helpful agent who will upload the image to Google Cloud Storage using `upload_image` tool.',
  tools=[upload_image],
)

Agora vamos adicionar outra ferramenta para ler os ingredientes da imagem. Vamos adicionar google-cloud-vision em requirements.txt e instalar a nova dependência.

pip install -r requirements.txt

Novamente, talvez seja necessário ativar a API Vision primeiro. Execute o comando a seguir no terminal para fazer isso:

gcloud services enable vision.googleapis.com

Agora vamos adicionar uma nova ferramenta read_ingredients :

def read_ingredients() -> str:
  vision_client = vision.ImageAnnotatorClient()

  with io.open("/home/bajajnehaa/healthy_hints/images/Ingredients-list.jpg", 'rb') as image_file:
    content = image_file.read()

  image = vision.Image(content=content)
  response = vision_client.text_detection(image=image)
  texts = response.text_annotations
  return texts[0].description

E agora vamos atualizar nosso agente para usar essa ferramenta.

root_agent = Agent(
  model='gemini-2.5-flash',
  name='healthy_hints_agent',
  description='Agent to upload image to Google Cloud Storage, read the list of ingredients from the image and explain if the ingredient is healthy or not',
  instruction='You are a helpful agent who will upload the image to Google Cloud Storage using `upload_image` tool, read the ingredients of the image using `read_ingredients` tool and explain if the ingredient is healthy or not in one line.',
  tools=[upload_image, read_ingredients],
)

8. Conclusão

Parabéns por concluir o codelab de dicas saudáveis. Você transformou com sucesso uma IA padrão de um gerador de texto em um agente proativo de várias ferramentas. Ao usar o ADK para integrar a API Vision e o SDK do Cloud Storage, você deu ao seu agente os "olhos" para ler rótulos e a "memória" para arquivá-los. Você viu como o agente decide de forma autônoma quando salvar um arquivo e como interpretar dados brutos para fornecer conselhos de saúde do mundo real.

No futuro, esses princípios servirão como um modelo para qualquer sistema automatizado. Se você estiver gerenciando a infraestrutura em nuvem ou criando assistentes pessoais, o núcleo permanece o mesmo: defina ferramentas especializadas e deixe o agente orquestrar a lógica. Como próxima etapa, tente adicionar mais ferramentas, como um "banco de dados nutricional" ou uma "ferramenta de e-mail", para expandir o impacto do seu agente.

ADK: das noções básicas aos agentes com várias ferramentas Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.