Como criar agentes de IA com o ADK: capacitação com ferramentas

1. Antes de começar

Bem-vindo à segunda parte da série "Como criar agentes de IA com o ADK"! Neste codelab prático, você vai capacitar um agente de IA básico com várias ferramentas.

Para começar, este guia oferece dois caminhos: um para quem está continuando do codelab "Como criar agentes de IA com o ADK: os fundamentos" e outro para quem está começando do zero. Os dois caminhos garantem que você tenha o código do agente base necessário para começar.

Ao final deste codelab, você terá capacitado seu agente assistente pessoal com ferramentas para várias finalidades, um passo mais perto de ser expandido nas partes subsequentes desta série, à medida que o transformamos em um sofisticado sistema multiagente (MAS).

Você também pode acessar este codelab usando este URL encurtado: goo.gle/adk-using-tools.

Pré-requisitos

O que você vai aprender

  • Ofereça novas habilidades ao seu agente criando funções personalizadas do Python como ferramentas.
  • Conecte seu agente a informações em tempo real usando ferramentas integradas, como a Pesquisa Google.
  • Estruture um agente de várias ferramentas criando subagentes especializados para tarefas complexas.
  • Integre ferramentas de frameworks de IA conhecidos, como o LangChain, para expandir rapidamente os recursos.

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

2. Introdução

Um agente básico criado com o ADK tem um cérebro LLM poderoso, mas também tem limitações: ele não pode acessar informações criadas após a data de treinamento e não pode interagir com serviços externos. É como um assistente brilhante e inteligente preso em uma biblioteca sem telefone ou Internet. Para tornar um agente realmente útil, precisamos fornecer ferramentas a ele.

Pense nas ferramentas como dar ao assistente de IA acesso ao mundo externo: uma calculadora, um navegador da Web ou acesso a um banco de dados específico da empresa. No ADK, uma ferramenta é uma parte modular de código que permite que o agente execute ações específicas, como pesquisar dados em tempo real ou chamar uma API externa. O uso de ferramentas estende os recursos muito além da simples conversa.

O ADK oferece três categorias de ferramentas:

  1. Ferramentas de função:ferramentas personalizadas que você desenvolve para atender aos requisitos exclusivos do seu aplicativo, como funções e agentes predefinidos.
  2. Ferramentas integradas:ferramentas prontas para uso fornecidas pelo framework para operações comuns, como a Pesquisa Google e a execução de código.
  3. Ferramentas de terceiros:bibliotecas externas conhecidas, como Serper e ferramentas do LangChain e do CrewAI.

Para saber mais sobre como usar ferramentas com agentes do ADK, consulte a documentação oficial. Neste codelab, vamos adicionar ferramentas para transformar nosso agente simples em um assistente de viagens pessoal capaz. Vamos começar.

3. Introdução: seu agente base

Antes de capacitar um agente com ferramentas, você precisa de um agente básico para trabalhar. Escolha o caminho que melhor se adapta ao seu progresso.

Caminho A: continuar do codelab de fundamentos

Se você acabou de concluir o codelab " Como criar agentes de IA com o ADK: os fundamentos", está tudo pronto. Você pode continuar trabalhando no diretório do projeto ai-agents-adk.

Caminho B: começar do zero

Se você estiver começando este codelab diretamente, conclua estas quatro etapas para configurar seu ambiente e criar o agente inicial necessário.

  1. Configurar os serviços do Google Cloud
  2. Criar um ambiente virtual em Python
  3. Criar um agente
  4. Executar o agente na interface de desenvolvimento

Depois de concluir as etapas, você estará pronto para iniciar sua jornada de aprendizado.

4. Criar uma ferramenta personalizada para câmbio de moeda

Nesta fase, você já deve saber como criar um agente de IA simples usando o ADK e executá-lo na interface de desenvolvimento.

Imagine que você está se preparando para uma viagem ao Japão no mês que vem e precisa verificar a taxa de câmbio atual. Pergunte ao agente "Qual é a taxa de câmbio do dólar de Singapura para o iene japonês?"

7b3c502f88e8ab80.png

Você verá que o agente não pode recuperar taxas de câmbio em tempo real. Isso ocorre porque o agente não tem acesso à Internet e conectividade com sistemas externos. Mesmo que o agente responda com um valor, é difícil confiar nesse valor, porque provavelmente será uma alucinação.

Para resolver isso, vamos implementar uma função Python para recuperar taxas de câmbio usando uma API REST e integrá-la como uma ferramenta de função para o agente.

Encerre o processo do agente em execução usando o atalho de teclado Ctrl + C na janela do terminal.

Criar o arquivo custom_functions.py

Execute este comando no terminal para criar um arquivo Python chamado custom_functions.py na pasta personal_assistant e também abri-lo no editor de código.

cloudshell edit personal_assistant/custom_functions.py

Esta é a aparência da estrutura de pastas agora:

ai-agents-adk/
└── personal_assistant/
    ├── .env
    ├── __init__.py
    ├── agent.py
    └── custom_functions.py

Esse arquivo custom_functions.py vai conter a função Python responsável por recuperar dados de taxa de câmbio de uma API externa. Copie e cole o seguinte código no arquivo:

import requests

# define a function to get exchange rate
def get_fx_rate(base: str, target: str):
        """
        Fetches the current exchange rate between two currencies.

        Args:
                base: The base currency (e.g., "SGD").
                target: The target currency (e.g., "JPY").

        Returns:
                The exchange rate information as a json response,
                or None if the rate could not be fetched.
        """
        base_url = "https://hexarate.paikama.co/api/rates/latest"
        api_url = f"{base_url}/{base}?target={target}"

        response = requests.get(api_url)
        if response.status_code == 200:
                return response.json()

Agora, edite o arquivo agent.py: importe a função get_fx_rate e atribua-a como um FunctionTool.

Atualizar o arquivo agent.py

Copie este bloco de código e substitua o conteúdo atual do arquivo agent.py:

from google.adk.agents import Agent
from google.adk.tools import FunctionTool

from .custom_functions import get_fx_rate

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',
    tools=[FunctionTool(get_fx_rate)]
)

Depois das mudanças, inicie o agente novamente digitando:

adk web --allow_origins "regex:https://.*\.cloudshell\.dev"

Quando o agente estiver ativo, faça a mesma pergunta novamente: "Qual é a taxa de câmbio do dólar de Singapura para o iene japonês?"

Desta vez, você verá a taxa de câmbio real fornecida pela ferramenta get_fx_rate.

76b1647fbfc0687a.png

Faça quantas perguntas quiser relacionadas ao câmbio de moeda.

5. Integrar com a ferramenta de Pesquisa Google integrada

Com o agente agora capaz de fornecer taxas de câmbio, a próxima tarefa é receber a previsão do tempo para o mês que vem. Faça esta pergunta ao agente: "Qual é a previsão do tempo para Tóquio, Japão, no mês que vem?"

399f40c4ea3e0bb3.png

Como esperado, a previsão do tempo requer informações em tempo real que nosso agente não tem. Embora possamos codificar novas funções Python para cada caso de uso que requer dados em tempo real, adicionar cada vez mais ferramentas personalizadas torna o agente muito complicado e difícil de gerenciar.

Felizmente, o Kit de Desenvolvimento de Agentes (ADK) fornece um conjunto de ferramentas integradas, incluindo a Pesquisa Google, que estão prontas para uso, simplificando a maneira como nosso agente interage com o mundo externo.

Para equipar o agente com a ferramenta Pesquisa Google, é necessário implementar um padrão multiagente. Primeiro, crie um agente especializado cuja única função seja realizar pesquisas no Google. Em seguida, atribua esse novo Agente de Pesquisa Google ao nosso personal_assistant principal como uma ferramenta. Veja as etapas:

Criar o arquivo custom_agents.py

Execute este comando no terminal para criar um arquivo Python chamado custom_agents.py na pasta personal_assistant e abri-lo no editor de código:

cloudshell edit personal_assistant/custom_agents.py

Esta é a aparência da estrutura de pastas agora:

ai-agents-adk/
└── personal_assistant/
    ├── .env
    ├── __init__.py
    ├── agent.py
    ├── custom_functions.py
    └── custom_agents.py

Esse arquivo custom_agents.py vai conter o código do google_search_agent especializado. Copie o código a seguir para o arquivo custom_agents.py:

from google.adk.agents import Agent
from google.adk.tools import google_search


# Create an agent with google search tool as a search specialist
google_search_agent = Agent(
    model='gemini-2.5-flash',
    name='google_search_agent',
    description='A search agent that uses google search to get latest information about current events, weather, or business hours.',
    instruction='Use google search to answer user questions about real-time, logistical information.',
    tools=[google_search],
)

Depois que o arquivo for criado, atualize o arquivo agent.py conforme mostrado abaixo.

Atualizar o arquivo agent.py

Copie este bloco de código e substitua o conteúdo atual do arquivo agent.py:

from google.adk.agents import Agent
from google.adk.tools import FunctionTool
from google.adk.tools.agent_tool import AgentTool

from .custom_functions import get_fx_rate
from .custom_agents import google_search_agent


root_agent = Agent(
    model='gemini-2.5-flash',
    name='root_agent',
    description='A helpful assistant for user questions.',
    tools=[
        FunctionTool(get_fx_rate), 
        AgentTool(agent=google_search_agent),
    ]
)

Vamos analisar o novo padrão poderoso no código:

  • Um novo agente especialista: definimos um agente completamente novo, google_search_agent. Observe a descrição específica e que a única ferramenta dele é google_search. É um especialista em pesquisa.
  • agent_tool.AgentTool: esse é um wrapper especial do ADK. Ele usa um agente inteiro (nosso google_search_agent) e o empacota para parecer e agir como uma ferramenta padrão.
  • Um **root_agent mais inteligente**: nosso root_agent agora tem uma nova ferramenta: AgentTool(agent=google_search_agent). Ele não sabe como pesquisar na Web, mas sabe que tem uma ferramenta para delegar tarefas de pesquisa.

Observe que o campo de instrução desapareceu do root_agent. As instruções agora são definidas implicitamente pelas ferramentas disponíveis.

O root_agent se tornou um orquestrador ou um roteador, cuja principal função é entender a solicitação de um usuário e transmiti-la à ferramenta correta, seja a função get_fx_rate ou o google_search_agent. Esse design descentralizado é fundamental para criar sistemas de agentes complexos e fáceis de manter.

Agora, digite este comando no terminal para iniciar a instância:

adk web --allow_origins "regex:https://.*\.cloudshell\.dev"

Quando o agente estiver em execução, faça a mesma pergunta novamente: "Qual é a previsão do tempo para Tóquio, Japão, no mês que vem?"

8a2a6d9532b54301.png

O agente agora está usando google_search_agent para receber as informações mais recentes

Você também pode fazer uma pergunta sobre a taxa de câmbio atual. O agente agora poderá usar a ferramenta certa para a pergunta respectiva.

ff3739a0b5ede6c2.png

Faça outras perguntas que exigem informações em tempo real ao agente e observe como ele processa as consultas usando as ferramentas disponíveis.

6. Aproveitar a ferramenta Wikipedia do LangChain

Nosso agente está se tornando um ótimo assistente de viagens. Ele pode processar o câmbio de moeda com a ferramenta get_fx_rate e gerenciar a logística com a ferramenta google_search_agent. Mas uma ótima viagem não é apenas sobre logística. É preciso entender a cultura e a história do seu destino.

Embora o google_search_agent possa encontrar fatos culturais e históricos, as informações de uma fonte dedicada, como a Wikipédia, geralmente são mais estruturadas e confiáveis.

Felizmente, o ADK foi projetado para ser altamente extensível, permitindo que você integre ferramentas de outros frameworks de agentes de IA, como CrewAI e LangChain. Essa interoperabilidade é fundamental porque permite um tempo de desenvolvimento mais rápido e permite reutilizar ferramentas atuais. Para esse caso de uso, vamos aproveitar as ferramentas da Wikipédia do LangChain.

Primeiro, interrompa o processo do agente em execução (Ctrl + C) e instale bibliotecas adicionais no ambiente virtual Python atual digitando os comandos a seguir no Terminal.

uv pip install langchain-community wikipedia

Criar o arquivo third_party_tools.py

O comando a seguir cria um arquivo Python chamado third_party_tools.py na pasta personal_assistant e o abre no Cloud Editor:

cloudshell edit personal_assistant/third_party_tools.py

Esta é a aparência da estrutura de pastas agora:

ai-agents-adk/
└── personal_assistant/
    ├── .env
    ├── __init__.py
    ├── agent.py
    ├── custom_functions.py
    ├── custom_agents.py
    └── third_party_tools.py

Esse arquivo vai conter a implementação da ferramenta Wikipedia do LangChain. Copie o código a seguir para o arquivo third_party_tools.py**:**

from langchain_community.tools import WikipediaQueryRun
from langchain_community.utilities import WikipediaAPIWrapper

# Configure the Wikipedia LangChain tool to act as our cultural guide
langchain_wikipedia_tool = WikipediaQueryRun(
    api_wrapper=WikipediaAPIWrapper(top_k_results=1, doc_content_chars_max=3000)
)

# Give the tool a more specific description for our agent
langchain_wikipedia_tool.description = (
    "Provides deep historical and cultural information on landmarks, concepts, and places."
    "Use this for 'tell me about' or 'what is the history of' type questions."
)

Atualizar o arquivo agent.py

Agora, atualize o arquivo agent.py com o conteúdo abaixo:

from google.adk.agents import Agent
from google.adk.tools import FunctionTool
from google.adk.tools.agent_tool import AgentTool
from google.adk.tools.langchain_tool import LangchainTool

from .custom_functions import get_fx_rate
from .custom_agents import google_search_agent
from .third_party_tools import langchain_wikipedia_tool


root_agent = Agent(
    model='gemini-2.5-flash',
    name='root_agent',
    description='A helpful assistant for user questions.',
    tools=[
        FunctionTool(get_fx_rate), 
        AgentTool(agent=google_search_agent),
        LangchainTool(langchain_wikipedia_tool),
    ]
)

Agora, digite este comando no terminal para iniciar a instância:

adk web --allow_origins "regex:https://.*\.cloudshell\.dev"

Quando o agente estiver pronto, faça esta pergunta: "Conte-me sobre a história de Quioto".

9098274a483dee32.png

O agente identifica corretamente isso como uma consulta histórica e usa a nova ferramenta Wikipedia. Ao integrar uma ferramenta de terceiros e atribuir a ela um papel específico, você tornou seu agente significativamente mais inteligente e útil para a finalidade de planejamento de viagens.

Para saber exatamente como o agente fez essa escolha, use o inspetor de eventos na interface adk web. Clique na guia "Eventos" e, em seguida, no evento functionCall mais recente.

eb2cdb9806cd3734.png

O inspetor mostra uma lista de todas as ferramentas disponíveis e destaca o tool_code daquela que foi executada pelo agente.

119d55bfb0b36e17.png

7. 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 no terminal.

Excluir pastas e arquivos de projetos de agentes

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

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 desligar totalmente o projeto do Google Cloud, consulte o guia oficial para instruções detalhadas.

8. Conclusão

Parabéns! Você capacitou com sucesso o agente assistente pessoal com funções personalizadas e acesso à Pesquisa Google em tempo real. Leia esta documentação oficial sobre como usar ferramentas com o ADK do Google.

Mais importante ainda, você aprendeu o padrão arquitetônico fundamental para criar agentes capazes: usar agentes especializados como ferramentas. Ao criar um google_search_agent dedicado e fornecê-lo ao seu root_agent, você deu o primeiro passo para criar um único agente para orquestrar um sistema multiagente simples, mas poderoso.

Agora você está perfeitamente preparado para o próximo codelab (em breve) da série, em que vamos nos aprofundar na orquestração de vários agentes e fluxos de trabalho. Até lá!