AI Engineering Academy · Aula

Definindo ferramentas para seu Agent

Crie ferramentas personalizadas com o decorador @tool, escreva descrições claras que o LLM use para decidir quando chamar cada ferramenta e adicione validação de entrada com Pydantic.

Aula 2 de 413 etapas

Definindo ferramentas para seu Agent é uma aula grátis de AI Engineering Academy no CoddyKit. Esta é a aula 2 de 4. Você pode ler a aula completa abaixo gratuitamente — depois pratica ao vivo no navegador com um editor de código integrado e um tutor de IA 24/7. Faz parte do caminho de aprendizado de AI Engineering Academy, e seu progresso é sincronizado entre a web e o app CoddyKit. O curso de AI Engineering Academy inclui 4 aulas no total.

As ferramentas dão superpoderes aos agentes

Um agente sem ferramentas só consegue raciocinar sobre o que já sabe: ele não pode pesquisar na web, consultar um banco de dados ou enviar um e-mail. Ferramentas são funções Python que ampliam as capacidades do agente, permitindo que ele execute ações no mundo real e obtenha informações atualizadas. Definir ferramentas com clareza é uma das etapas mais importantes para criar um agente confiável.

O decorador @tool no LangChain

O decorador @tool do LangChain transforma qualquer função Python em uma ferramenta que o agente pode chamar. A documentação da função se torna a descrição da ferramenta usada pelo LLM para decidir quando chamá-la. Uma descrição clara e específica melhora significativamente a precisão da seleção de ferramentas pelo agente.

from langchain_core.tools import tool

@tool
def get_weather(city: str) -> str:
    '''Get the current weather conditions for a given city.
    Use this tool when the user asks about weather in a specific location.
    Input should be just the city name, e.g. 'London' or 'New York'.
    '''
    # Real implementation would call a weather API
    return f'The weather in {city} is 18 degrees Celsius and partly cloudy.'

print(get_weather.name)         # 'get_weather'
print(get_weather.description)  # The docstring above

Anotações de tipo e geração de esquema

O LangChain gera automaticamente um esquema JSON para cada ferramenta a partir das anotações de tipo do Python. O agente recebe esse esquema no prompt do sistema, para saber quais argumentos são obrigatórios, quais são seus tipos e quais restrições se aplicam. Sempre anote suas funções de ferramenta com tipos precisos.

from langchain_core.tools import tool

@tool
def calculate_compound_interest(
    principal: float,
    annual_rate: float,
    years: int
) -> float:
    '''Calculate compound interest earned over a number of years.
    Args:
        principal: Initial investment amount in dollars.
        annual_rate: Annual interest rate as a decimal (e.g. 0.05 for 5%).
        years: Number of years to compound.
    Returns:
        Final amount after compounding.
    '''
    return principal * (1 + annual_rate) ** years

# Inspect the auto-generated schema
print(calculate_compound_interest.args_schema.schema())

Validação de entradas com Pydantic

Para ferramentas com entradas complexas, defina um modelo Pydantic como args_schema. Isso fornece validação automática, conversão de tipos e documentação descritiva no nível dos campos, que o LLM consulta ao decidir como chamar a ferramenta.

from langchain_core.tools import tool
from pydantic import BaseModel, Field

class SearchInput(BaseModel):
    query: str = Field(description='The search query to look up.')
    num_results: int = Field(default=5, ge=1, le=20, description='Number of results to return (1-20).')

@tool(args_schema=SearchInput)
def web_search(query: str, num_results: int = 5) -> str:
    '''Search the web for current information on any topic.
    Use this for facts that may have changed after the model training cutoff.
    '''
    return f'Searching for "{query}", returning {num_results} results...'

Escrevendo descrições eficazes para ferramentas

A descrição da ferramenta é a parte mais importante da definição dela: o LLM a lê para decidir quando e como chamar a ferramenta. Uma boa descrição responde às perguntas: O que essa ferramenta faz? Quando ela deve ser usada? Como deve ser a entrada? Qual será a saída?

Ruim: “Ferramenta de pesquisa.”
Boa: “Pesquise na web notícias, fatos ou dados atuais. Use quando o usuário perguntar sobre eventos recentes ou fatos que não estejam nos dados de treinamento. Entrada: uma consulta de pesquisa concisa.”

Tipos de retorno das ferramentas

As ferramentas podem retornar textos, dicionários ou objetos Pydantic estruturados. No entanto, o agente precisa, em última instância, do resultado como texto para incluí-lo na conversa. Se você retornar um dicionário, o LangChain o serializará como texto. Para dados aninhados complexos, formate-os como um resumo legível em vez de JSON bruto, para ajudar o modelo a raciocinar sobre eles.

from langchain_core.tools import tool
import json

@tool
def get_stock_price(ticker: str) -> str:
    '''Look up the current stock price for a given ticker symbol.
    Input should be the stock ticker symbol in uppercase, e.g. AAPL or MSFT.
    '''
    # Stub — real implementation calls a financial API
    data = {'ticker': ticker, 'price': 182.50, 'currency': 'USD', 'change': '+1.2%'}
    return f'{ticker}: ${data["price"]} ({data["change"]})'

Tratando erros de ferramentas de forma adequada

As ferramentas falham. APIs ficam indisponíveis, ocorrem tempos limite de rede e os usuários fornecem entradas inválidas. Em vez de permitir que exceções interrompam o ciclo do agente, envolva a lógica da ferramenta em try/except e retorne uma mensagem de erro descritiva. Assim, o agente poderá raciocinar sobre a falha e decidir se deve tentar novamente ou usar uma abordagem diferente.

from langchain_core.tools import tool
import requests

@tool
def fetch_url(url: str) -> str:
    '''Fetch the text content of a web page given its URL.
    Use for accessing specific documents or web pages the user references.
    '''
    try:
        resp = requests.get(url, timeout=10)
        resp.raise_for_status()
        return resp.text[:2000]  # Return first 2000 chars
    except requests.Timeout:
        return 'Error: Request timed out after 10 seconds.'
    except requests.HTTPError as e:
        return f'Error: HTTP {e.response.status_code}'
    except Exception as e:
        return f'Error fetching URL: {str(e)}'

Ferramentas assíncronas

Quando seu agente executa muitas chamadas de ferramentas ou quando suas ferramentas fazem solicitações de rede limitadas por entrada e saída, defina funções de ferramentas assíncronas para evitar o bloqueio do ciclo de eventos. O executor de agentes do LangChain oferece suporte nativo a ferramentas assíncronas: basta usar async def na função da ferramenta.

from langchain_core.tools import tool
import httpx

@tool
async def async_fetch(url: str) -> str:
    '''Asynchronously fetch content from a URL.
    Preferred over fetch_url when making multiple concurrent requests.
    '''
    async with httpx.AsyncClient(timeout=10) as client:
        try:
            resp = await client.get(url)
            resp.raise_for_status()
            return resp.text[:2000]
        except Exception as e:
            return f'Error: {str(e)}'

Organizando ferramentas em um conjunto

Quando você tem muitas ferramentas relacionadas, agrupe-as em um conjunto de ferramentas: uma classe que retorna uma lista de ferramentas. Os conjuntos de ferramentas do LangChain seguem um padrão comum: aceitam configurações, como chaves de API, no construtor e disponibilizam um método get_tools(). Isso torna o gerenciamento de ferramentas organizado e reutilizável em diferentes agentes.

from langchain_core.tools import BaseTool
from typing import List

class WeatherToolkit:
    def __init__(self, api_key: str):
        self.api_key = api_key

    def get_tools(self) -> List[BaseTool]:
        return [
            get_weather,          # defined earlier with @tool
            get_weather_forecast,  # another tool
            get_weather_alert      # another tool
        ]

# Usage
toolkit = WeatherToolkit(api_key='your_weather_api_key')
tools = toolkit.get_tools()
print(f'Loaded {len(tools)} weather tools')

Limitando o acesso às ferramentas por função do usuário

Nem todo usuário deve ter acesso a todas as ferramentas. Um usuário com acesso somente de leitura não deve acionar uma ferramenta send_email ou delete_record. Implemente o acesso às ferramentas com base em funções, selecionando quais ferramentas passar ao agente de acordo com as permissões do usuário autenticado.

def get_tools_for_user(user_role: str) -> list:
    read_tools = [web_search, get_weather, calculate_compound_interest]
    write_tools = [send_email, create_calendar_event, update_record]

    if user_role == 'admin':
        return read_tools + write_tools
    elif user_role == 'member':
        return read_tools
    else:
        return [web_search]  # Guest: only public search

Boas práticas de documentação de ferramentas

Ferramentas bem documentadas reduzem drasticamente os erros do agente. Siga estas boas práticas: use um nome claro iniciado por verbo (search_web, e não websearch), descreva explicitamente o formato de entrada esperado, mencione quando NÃO usar a ferramenta para evitar falsos positivos e descreva como é a saída para que o modelo possa analisá-la corretamente.

Verificação rápida

Teste sua compreensão sobre a definição de ferramentas para agentes do LangChain.

Responda na aula interativa

Recapitulação da lição

Nesta lição, você aprendeu que: o decorador @tool transforma funções Python em ferramentas que o agente pode chamar, usando suas docstrings como descrições, os esquemas do Pydantic adicionam entradas tipadas e validadas e as ferramentas devem tratar os erros de maneira adequada, retornando textos de erro descritivos. Em seguida, montaremos um agente ReAct completo com LangChain e rastrearemos suas etapas de raciocínio.

Grátis para começar

Aprenda Python com um tutor de IA — grátis

Escreva e execute código real no seu navegador, obtenha ajuda instantânea de um tutor de IA 24/7 e continue de onde parou na web ou no app.

Cursos: 30
Aulas: 120

Começar a aprender grátis Ver o curso completo

Perguntas Frequentes

A aula “Definindo ferramentas para seu Agent” é grátis?

Sim — o texto completo de “Definindo ferramentas para seu Agent” é grátis para ler aqui na web. Para praticá-la interativamente (um editor de código integrado e um tutor de IA 24/7) e desbloquear o restante do curso de AI Engineering Academy, atualize para CoddyKit PRO. O curso de AI Engineering Academy inclui 4 aulas no total.

O que vou aprender em “Definindo ferramentas para seu Agent”?

Crie ferramentas personalizadas com o decorador @tool, escreva descrições claras que o LLM use para decidir quando chamar cada ferramenta e adicione validação de entrada com Pydantic. Você pratica AI Engineering Academy com código prático que executa diretamente no navegador, e um tutor de IA 24/7 responde suas dúvidas enquanto trabalha na aula.

Preciso ter experiência prévia para começar AI Engineering Academy?

Nenhuma experiência prévia é necessária. AI Engineering Academy no CoddyKit é estruturado para alunos iniciantes até avançados, então você pode começar aqui ou desde o início e aprender no seu ritmo. Esta é a aula 2 de 4.

Quanto tempo leva a aula “Definindo ferramentas para seu Agent”?

A maioria das aulas CoddyKit leva cerca de 5–10 minutos. Cada uma é compacta e interativa, então você faz progresso constante e retoma exatamente de onde parou entre web e app.

Posso escrever e executar código nesta aula de AI Engineering Academy?

Sim. Cada aula de AI Engineering Academy inclui um editor de código integrado, então você escreve e executa código real direto no navegador e recebe feedback de IA instantaneamente — nenhuma configuração local necessária.

Todas as aulas deste curso

A estrutura ReAct: pensar, agir, observar
Definindo ferramentas para seu Agent
Criando um Agent ReAct com LangChain
Como lidar com falhas e loops de agentes

← Voltar para AI Engineering Academy