Esta página foi traduzida pela API Cloud Translation.

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

1. Antes de começar

Esta é a 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 de 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, na sigla em inglês).

Pré-requisitos

Entendimento dos conceitos de IA generativa
Proficiência básica em programação em Python
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 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 estruturas de IA conhecidas, como o LangChain, para expandir rapidamente as funcionalidades.

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
Ter um projeto do Google Cloud com o faturamento ativado
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 nem Internet. Para que um agente seja realmente útil, precisamos dar a ele ferramentas.

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 é um trecho de código modular 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 as capacidades dele muito além de 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 pessoal de viagens eficiente. Vamos começar.

3. Como começar: 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: a base, 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.

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 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 do dólar de Singapura para o iene japonês?"

O agente não consegue recuperar as taxas de câmbio em tempo real. Isso acontece 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 do 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 (para Windows/Linux) ou Cmd + C (para macOS) na janela do terminal.

Crie o arquivo `custom_functions.py`:

Crie um arquivo Python chamado custom_functions.py na pasta personal_assistant digitando este comando no terminal.

touch personal_assistant/custom_functions.py

Esta é a aparência da estrutura de pastas:

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

Abra o custom_functions.py no editor de código. Esse arquivo vai conter a função Python responsável por extrair dados de taxa de câmbio de uma API externa.

Copie e cole o seguinte código em:

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.

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

uv run adk web

Quando o agente estiver disponível, 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ê vai ver a taxa de câmbio real fornecida pela ferramenta get_fx_rate.

Fique à vontade para fazer perguntas relacionadas ao 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 você pode imaginar, 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 em Python para cada parte dos dados necessários 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 nosso agente com o mundo externo. Vamos adicionar uma ferramenta da Pesquisa Google ao nosso agente.

Para isso, edite o arquivo agent.py da seguinte forma:

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

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), 
        google_search,
    ]
)

Depois de editar o arquivo, reinicie a instância adk web. Caso você se esqueça,

Clique no terminal e pressione Ctrl + C ou Cmd + C para interromper a instância.
uv run adk web para iniciar a instância
Tente fazer a mesma pergunta: "Qual é a previsão do tempo para Tóquio, Japão, no próximo mês?"

A abordagem recomendada é adotar um padrão multiagente: crie um agente especializado cujo único trabalho seja realizar pesquisas no Google. Em seguida, atribuímos esse novo agente da Pesquisa Google ao nosso personal_assistant principal como uma ferramenta.

Criar arquivo `custom_agents.py`

Agora, crie um arquivo Python chamado custom_agents.py na pasta personal_assistant.

touch 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 vai conter o código do google_search_agent especializado. Copie o código a seguir para o arquivo custom_agents.py usando o Code Editor.

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 import agent_tool

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), 
        agent_tool.AgentTool(agent=google_search_agent),
    ]
)

Vamos analisar o novo padrão avançado no código:

Um novo agente especializado: definimos um agente completamente 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: este é 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 Smarter **root_agent**: nosso root_agent agora tem uma nova ferramenta: agent_tool.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 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, reinicie o

adk web

instância e faça a mesma pergunta ao agente de novo: "Qual é a previsão do tempo para Tóquio, Japão, no próximo mês?"

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

Você também pode fazer uma pergunta sobre 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 da Wikipédia 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 costumam ser 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 é 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 ou Cmd + C) e instale outras bibliotecas no ambiente virtual Python atual digitando os seguintes comandos no Terminal.

uv add langchain-community
uv add wikipedia

Criar arquivo `third_party_tools.py`

Agora, crie um arquivo Python chamado third_party_tools.py na pasta personal_assistant.

touch 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 da Wikipédia do LangChain. Copie o código a seguir no third_party_tools.py usando o Cloud Editor:

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 import agent_tool
from google.adk.tools import langchain_tool

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), 
        agent_tool.AgentTool(agent=google_search_agent),
        langchain_tool.LangchainTool(langchain_wikipedia_tool),
    ]
)

Agora, reinicie a instância adk web e faça esta pergunta ao agente: "Quero aprender 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 adk web interface. Clique na guia "Eventos" e 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. 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 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

Desativar todo o projeto do Google Cloud

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

8. Conclusão

Parabéns! Você capacitou o agente de 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.

E, mais importante, 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 entregá-lo ao seu root_agent, você deu o primeiro passo para passar da criação de um único agente à organização de um sistema multiagente simples, mas poderoso.

Agora você está totalmente preparado para o próximo codelab 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. Como começar: seu agente básico

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

Crie o arquivo custom_functions.py:

Atualize 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 da Wikipédia do LangChain

Criar arquivo third_party_tools.py

Atualizar o arquivo agent.py

7. Limpeza (opcional)

Excluir pastas e arquivos do projeto do agente

Desativar a API Vertex AI

Desativar todo o projeto do Google Cloud

8. Conclusão

Crie o arquivo `custom_functions.py`:

Atualize 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`