O Google usa tecnologia de IA na tradução de conteúdos para seu idioma de preferência. As traduções com IA podem ter erros.

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

1. Antes de começar

Esta é a segunda parte da série "Criação de 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 base do agente 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 o URL abreviado: goo.gle/adk-using-tools.

Pré-requisitos

Entendimento dos conceitos de IA generativa
Proficiência básica em programação Python
Familiaridade com a CLI gcloud e a ferramenta Python uv
Ter concluído o codelab Como criar agentes de IA com o ADK: os fundamentos ou similar

O que você vai aprender

Dê novas habilidades ao seu agente criando funções Python personalizadas como ferramentas.
Conecte seu agente a informações em tempo real usando ferramentas integradas, como a Pesquisa Google.
Estruture um agente multi-ferramenta 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 LLM poderoso, mas também tem limitações: ele não pode acessar informações criadas após a data de treinamento nem interagir com serviços externos. É como um assistente brilhante e inteligente preso em uma biblioteca sem telefone ou Internet. Para que um agente seja realmente útil, precisamos fornecer ferramentas a ele.

Pense nas ferramentas como se elas dessem ao assistente de IA acesso ao mundo exterior: uma calculadora, um navegador da Web ou acesso a um banco de dados específico de uma empresa. No ADK, uma ferramenta é uma parte modular de código que permite ao agente realizar ações específicas, como pesquisar dados em tempo real ou chamar uma API externa. O uso de ferramentas amplia muito mais as capacidades dele do que uma simples conversa.

O ADK oferece três categorias de ferramentas:

Ferramentas de função:ferramentas personalizadas que você desenvolve para atender aos requisitos exclusivos do seu aplicativo, como funções e agentes predefinidos.
Ferramentas integradas:ferramentas prontas para uso fornecidas pelo framework para operações comuns, como a Pesquisa Google e a execução de código.
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 viagem pessoal eficiente. Vamos começar.

3. Introdução: seu agente básico

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

Se você não vir (ai-agents-adk) no prompt do Cloud Shell, execute estes comandos para ativar o ambiente virtual do Python:

cd ~/ai-agents-adk
source .venv/bin/activate

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.

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

4. Criar uma ferramenta personalizada para câmbio

Nesta etapa, 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 entre dólares de Singapura e ienes japoneses?"

Você vai notar que o agente não consegue recuperar as taxas de câmbio em tempo real. Isso ocorre porque o agente não tem acesso à Internet nem conectividade com sistemas externos. Mesmo que o agente responda com um valor, é difícil confiar nele, já que 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 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 abrir 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 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-3.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 disponível, faça a mesma pergunta novamente: "Qual é a taxa de câmbio de dólares de Singapura para ienes japoneses?"

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

Fique à vontade para fazer perguntas relacionadas a câmbio.

5. Integrar com a ferramenta de Pesquisa Google integrada

Agora que o agente pode fornecer taxas de câmbio, a próxima tarefa é obter a previsão do tempo para o próximo mês. Pergunte ao agente: "Qual é a previsão do tempo para Tóquio, Japão, no próximo mês?"

Como esperado, a previsão do tempo exige informações em tempo real, que nosso agente não tem. Embora seja possível programar novas funções Python para cada caso de uso que exija 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 Agente (ADK) oferece um conjunto de ferramentas integradas, incluindo a Pesquisa Google, que estão prontas para uso, simplificando a interação do agente com o mundo externo.

Para equipar o agente com a ferramenta da Pesquisa Google, é necessário implementar um padrão multiagente. Primeiro, você cria um agente especializado cuja única função é fazer pesquisas no Google. Em seguida, atribua esse novo agente da Pesquisa Google ao personal_assistant principal como uma ferramenta. Siga estas etapas:

Criar arquivo `custom_agents.py`

Execute este comando no terminal para criar um arquivo Python chamado custom_agents.py na pasta personal_assistant e abrir 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 no 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-3.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-3.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 avançado no código:

Um novo agente especialista: definimos um agente totalmente novo, o google_search_agent. Observe a descrição específica e que a única ferramenta é google_search. É um especialista em pesquisa.
agent_tool.AgentTool: um wrapper especial do ADK. Ele pega 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 a que pode delegar tarefas de pesquisa.

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

O root_agent se tornou um organizador ou roteador, cuja principal função é entender a solicitação de um usuário e encaminhá-la para a 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 de novo: "Qual é a previsão do tempo para Tóquio, Japão, no próximo mês?"

O agente agora usa o google_search_agent para receber as informações mais recentes

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

Faça outras perguntas que exijam informações em tempo real para o agente e observe como ele lida com as consultas usando as ferramentas disponíveis.

6. Usar a ferramenta Wikipedia do LangChain

Nosso agente está se tornando um ótimo assistente de viagens. Ele pode lidar com câmbio usando 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, é sobre 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, sem problemas. Essa interoperabilidade é crucial porque permite um tempo de desenvolvimento mais rápido e a reutilização de ferramentas atuais. Para este 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 do Python atual digitando os seguintes comandos no Terminal.

uv pip install langchain-community wikipedia

Criar 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 no 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-3.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 a seguinte pergunta: Conte-me sobre a história de Kyoto.

O agente identifica corretamente essa consulta como histórica e usa a nova ferramenta Wikipedia. Ao integrar uma ferramenta de terceiros e atribuir uma função específica a ela, você tornou seu agente muito mais inteligente e útil para o planejamento de viagens.

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

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

7. Limpar o ambiente

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 seu ambiente do Cloud Shell, use os seguintes comandos:

cd ~
rm -rf ai-agents-adk

Desativar a API Gemini Enterprise Agent Platform

Para desativar a API que foi ativada antes, execute este comando:

gcloud services disable aiplatform.googleapis.com

Desativar todo o projeto do Google Cloud

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

8. Conclusão

Parabéns! Você capacitou o agente assistente pessoal com funções personalizadas e acesso em tempo real à Pesquisa Google. Leia a 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 eficientes: usar agentes especializados como ferramentas. Ao criar um google_search_agent dedicado e atribuí-lo ao seu root_agent, você deu o primeiro passo para criar um sistema multiagente simples, mas eficiente, em vez de um único agente.

Agora você está totalmente 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á!

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

1. Antes de começar

Pré-requisitos

O que você vai aprender

O que é necessário

2. Introdução

3. Introdução: seu agente básico

4. Criar uma ferramenta personalizada para câmbio

Criar arquivo custom_functions.py

Atualizar o arquivo agent.py

5. Integrar com a ferramenta de Pesquisa Google integrada

Criar arquivo custom_agents.py

Atualizar o arquivo agent.py

6. Usar a ferramenta Wikipedia do LangChain

Criar arquivo third_party_tools.py

Atualizar o arquivo agent.py

7. Limpar o ambiente

Excluir pastas e arquivos do projeto do agente

Desativar a API Gemini Enterprise Agent Platform

Desativar todo o projeto do Google Cloud

8. Conclusão

Criar arquivo `custom_functions.py`

Atualizar o arquivo `agent.py`

Criar arquivo `custom_agents.py`

Atualizar o arquivo `agent.py`

Criar arquivo `third_party_tools.py`

Atualizar o arquivo `agent.py`