Projetando ferramentas que a IA pode realmente usar

Aqui está uma definição de ferramenta que vejo o tempo todo:

@tool
def get_data(id: str):
    """Obtém dados."""
    ...

O modelo não tem como saber quando chamar isso. "Obtém dados" poderia corresponder a quase qualquer solicitação. E quando um agente está escolhendo entre trinta ferramentas, a descrição faz a maior parte do roteamento. Para o modelo, aquele docstring de duas palavras é a interface; o código abaixo mal entra na decisão.

A maioria dos bugs de agente que persigo acabam sendo bugs de seleção de ferramenta. O modelo escolhe a ferramenta errada ou não escolhe nada quando deveria ter agido. Às vezes, chama a ferramenta certa com os argumentos errados. A correção está quase sempre na descrição, não no código.

Descrições são prompts, não docstrings

Uma descrição precisa responder a duas perguntas para o modelo: quando devo chamar isso e o que eu recebo de volta. Aqui está a mesma ferramenta escrita para um leitor humano:

@tool
def search_entities(query: str):
    """Pesquisar entidades."""

E escrita para o modelo que precisa roteá-la:

@tool
def search_entities(
    query: Annotated[str, "Termo de pesquisa, corresponde ao nome e domínio. Use termos exatos, SEM curingas"],
):
    """Encontre entidades por nome ou domínio.

    Use isso quando o usuário se referir a uma entidade, mas você não'tem seu ID exato. Nomes parciais e aproximados funcionam.
    Retorna uma lista classificada de correspondências com IDs, nomes e tipos.

    Se você não conseguir encontrar uma entidade pelo nome, tente seu domínio
    (por exemplo, "example.com").

    Exemplos de perguntas:
        - "Encontre a entidade para a Acme Corp"
        - "Pesquise o fornecedor com domínio example.com"
    """

A segunda diz quando alcançá-la, o que vem de volta e o que fazer quando a abordagem óbvia falha. O bloco Exemplos de perguntas está puxando mais peso do que parece: ele ancla os tipos de solicitações do usuário que devem ser roteadas aqui, que é a decisão exata que o modelo está tomando.

Note o que está faltando. Meu primeiro rascunho dizia "encontrar entidades por nome usando correspondência difusa." O modelo não se importa que a correspondência seja difusa; isso é um detalhe de implementação. Ele se importa que pode digitar algo aproximado e obter resultados. Então, eu descrevo o comportamento que o modelo pode agir, e como a correspondência funciona por baixo nunca entra no texto.

Uma cautela sobre aquelas perguntas de exemplo: mantenha-as variadas. Se todas parecerem semelhantes, o modelo decide que a ferramenta é mais estreita do que realmente é e a ignora quando uma pergunta não corresponde à forma. Eu me apoio em exemplos principalmente para parâmetros com formatos não óbvios, e mantenho os que uso deliberadamente diferentes entre si.

Literal é a anotação de maior valor que você pode adicionar

Um parâmetro chamado country pode ser um nome de país, um código de duas letras, um código de três letras ou um código numérico da ONU. O modelo vai adivinhar, e ele vai adivinhar errado com frequência suficiente para importar.

from typing import Annotated, Literal
from pydantic import Field

Status = Literal["ativo", "inativo", "indeterminado"]

@tool
def search_records(
    # Descrição inline, boa para parâmetros simples
    query: Annotated[str, "Termo de pesquisa. Use nomes exatos, SEM curingas"],

    # Literal fixa o valor a um conjunto conhecido
    status: Annotated[list[Status] | None, "Filtrar por status"] = None,

    # Field adiciona exemplos e validação
    country_code: Annotated[
        str | None,
        Field(description="Código do país ISO 3166-1 alpha-2 de duas letras", examples=["DE", "US", "PL"]),
    ] = None,

    # ge=1 impede que o modelo envie página 0 ou um negativo
    page: Annotated[int, Field(description="Número da página, indexado a partir de 1", ge=1