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

1. Introdução

Começando pelo básico e progredindo para o desenvolvimento de agentes com 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 "mecanismo de raciocínio" para alcançar um objetivo realizando de forma autônoma uma sequência de tarefas.

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.

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 maneira inteligente qual ferramenta usar em cada etapa e pode transmitir a saída de uma ação como entrada para a próxima, a fim de atingir uma meta final.

O que você vai criar

Neste codelab, você vai criar um agente "Dicas saudáveis", um consultor nutricional inteligente que faz a transição de um raciocínio de texto simples para uma ferramenta multifuncional poderosa. Você vai começar criando um agente de conversa básico que entende conceitos de nutrição e, em seguida, vai equipá-lo progressivamente com uma ferramenta do SDK do Storage para arquivar imagens de ingredientes e uma ferramenta do Vision para "ler" e analisar essas imagens. Ao final deste laboratório, você terá um orquestrador totalmente funcional que pode pegar uma foto enviada de um rótulo de alimento, armazená-la em um bucket da nuvem para 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.
Verifique 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 seguinte comando 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 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 uma chave de API do Google usando o AI Studio:

Acesse https://aistudio.google.com/ e, no menu da parte de baixo à esquerda, clique em Get API Key.

Uma janela "Chaves de API" vai aparecer. Clique em "Criar chave de API":

Um pop-up vai aparecer para você criar uma chave. Nomeie a chave como: healthy-hints-key

Acesse o menu suspenso "Escolher um projeto importado".

Clique em Import Project. Uma janela lateral vai aparecer com 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ê vai 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 exemplo

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

adk create healthy_hints

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

Neste codelab, vamos usar a Google AI. Cole a chave de API criada na etapa anterior.

Vamos abrir a pasta que acabamos de criar. No menu à esquerda, clique no ícone e em "Arquivo" -> "Abrir pasta". Selecione a pasta healthy_hints que acabou de ser criada. Normalmente, ela fica na pasta /home/<username>.
A estrutura de pastas healthy_hints normalmente é assim:

Você vai encontrar um arquivo .env com 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 principal do agente. É aqui que um agente raiz de amostra é criado. Vamos analisar o conteúdo desse arquivo. Primeiro, importamos o llm_agent do ADK. Em seguida, usamos a 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 é o mais importante aqui. É nela que dizemos ao agente o que ele precisa fazer em linguagem natural.
Esse agente de amostra é bem genérico e responde a qualquer pergunta do usuário.
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 seguinte comando:

adk run .

Você vai ver uma saída semelhante:

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 seguinte comando no diretório principal de healthy_hints :

adk web

6. Agente multiferramenta

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

Tipos de ferramentas no ADK

Ferramentas de função:lógica personalizada escrita por você. Por exemplo, uma função que se conecta ao seu banco de dados específico ou um "Log Parser" 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 "Multi-tool" ou "Multi-agent", 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 gerente de pesquisa".

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

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}

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, as instruções e as ferramentas de acordo com isso. Agora, vamos executar esse agente atualizado. Desta vez, o agente também responderia 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 da vida real. Vamos criar um agente de dicas saudáveis. Nosso objetivo aqui é fazer upload de qualquer imagem que tenha uma lista de ingredientes para nosso agente, e ele vai nos dizer se cada ingrediente é saudável ou não.

Primeiro, vamos criar um bucket para fazer upload da imagem no Google Cloud Storage. Abra uma nova guia e acesse https://console.cloud.google.com/. Na barra de pesquisa, digite "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 de criação do bucket, insira o nome dele. O nome pode ser qualquer um, mas, para este codelab, vamos usar healthy-hints-bucket-kolkata . Deixe tudo no estado em que se encontra e clique no botão Create.

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

Primeiro, instale as dependências:

pip install -r requirements.txt

Talvez seja necessário ativar a API Storage primeiro. Para fazer isso, execute o seguinte comando no terminal:

gcloud services enable storage.googleapis.com

Agora vamos adicionar uma nova ferramenta para fazer 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 o 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

Talvez seja necessário ativar a API Vision primeiro. Para fazer isso, execute o seguinte comando no terminal:

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

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 Healthy Hints. Você transformou 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 arquivar. 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.

Daqui para frente, esses princípios vão servir como um modelo para qualquer sistema automatizado. Seja para gerenciar a infraestrutura em nuvem ou criar 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 aumentar o impacto do seu agente.