Ir para o conteúdo principal
Português— Escolher um idioma
Menu

Pesquisa de Ferramentas: Ferramentas Dinâmicas

Aula 15 de 20 Atualizada a 2 de novembro de 2026 Programador
Nesta página
  1. Pesquisa de Ferramentas: Ferramentas Dinâmicas
  2. O Problema dos Catálogos de Ferramentas Grandes
  3. Ativar a Pesquisa de Ferramentas
  4. Organizar o Catálogo de Funções
  5. Boas Práticas para Descrições
  6. Combinar Pesquisa de Ferramentas com Ferramentas Fixas
  7. Padrão: Sistema Multidomínio
  8. Pontos-chave

Lição atualizada a 2 de novembro de 2026 com base na documentação da OpenAI: a ferramenta Code Interpreter requer agora um parâmetro container (adicionado a todos os exemplos), as partes de texto de entrada são tipadas como input_text e a pesquisa na web utiliza a ferramenta web_search (web_search_preview é agora uma ferramenta legada sem filtros de domínio). Os ficheiros gerados são recuperados utilizando as funções fichiers_generes e telecharger da Lição 10. Fontes: Code Interpreter · Pesquisa na web.

Pesquisa de Ferramentas: Ferramentas Dinâmicas

Quando dispõe de dezenas ou centenas de funções, declará-las todas em cada chamada torna-se contraproducente: o modelo perde precisão e os custos disparam. A Pesquisa de Ferramentas resolve este problema ao permitir que o modelo procure a ferramenta correta num catálogo indexado.

O Problema dos Catálogos de Ferramentas Grandes

O custo de um catálogo de ferramentas extenso é invisível de duas formas. Primeiro, financeiramente: cada definição de função é enviada com cada pedido, incluindo as noventa e oito que não serão utilizadas. À escala, isto acaba por exceder o custo das próprias respostas. Segundo, e mais gravemente, qualitativamente: além de algumas dezenas de ferramentas com âmbitos sobrepostos, o modelo faz escolhas piores. Demasiadas opções degradam a tomada de decisão, aqui como em qualquer outro lugar.

# 5 funções = ~500 tokens de contexto
# 50 funções = ~5000 tokens de contexto
# 200 funções = impossível de gerir eficientemente

# O modelo perde precisão quando há demasiadas funções
# Por vezes escolhe a função errada ou alucina parâmetros

Ativar a Pesquisa de Ferramentas

A Pesquisa de Ferramentas inverte a lógica: em vez de apresentar tudo ao modelo, indexa o catálogo e mostra apenas o que corresponde ao pedido atual. O mecanismo baseia-se na pesquisa semântica sobre descrições — razão pela qual a próxima secção não é apenas um conselho de estilo; é um requisito para o sistema funcionar.

from openai import OpenAI

client = OpenAI()

# Declarar um grande número de funções
all_functions = [
    {
        "type": "function",
        "name": "create_invoice",
        "description": "Create a new invoice for a customer",
        "parameters": {"type": "object", "properties": {"client_id": {"type": "string"}}, "required": ["client_id"]}
    },
    {
        "type": "function",
        "name": "cancel_invoice",
        "description": "Cancel an existing invoice",
        "parameters": {"type": "object", "properties": {"invoice_id": {"type": "string"}}, "required": ["invoice_id"]}
    },
    # ... dezenas de outras funções
]

# Utilizar a Pesquisa de Ferramentas para deixar o modelo encontrar a função correta
response = client.responses.create(
    model="gpt-5.6-terra",
    input="Cancel invoice FAC-2026-0042",
    tools=[{
        "type": "tool_search",
        "tool_search": {
            "tools": all_functions
        }
    }]
)

O modelo recebe apenas as funções relevantes para o pedido no seu contexto, e não o catálogo inteiro.

Organizar o Catálogo de Funções

Dois princípios bastam para estruturar um catálogo que permaneça navegável. Prefixe os nomes por domínio (crm_, billing_, inventory_): a leitura do rasto de execução torna-se imediata e os conflitos de nomes desaparecem. E atribua a cada função um âmbito claro — duas funções cujas descrições se sobreponham produzirão escolhas instáveis, quer seja um humano ou um motor vetorial a fazer a chamada.

crm_catalog = [
    {
        "type": "function",
        "name": "crm_search_customer",
        "description": "Search for a customer in the CRM by name, email, or ID. "
                       "Use to find information about an existing customer.",
        "parameters": {
            "type": "object",
            "properties": {
                "term": {"type": "string", "description": "Search term"},
                "field": {"type": "string", "enum": ["name", "email", "id"]}
            },
            "required": ["term"],
            "additionalProperties": False
        },
        "strict": True
    },
    {
        "type": "function",
        "name": "crm_create_customer",
        "description": "Create a new customer in the CRM. "
                       "Use when a customer does not yet exist.",
        "parameters": {
            "type": "object",
            "properties": {
                "name": {"type": "string"},
                "email": {"type": "string"},
                "company": {"type": "string"}
            },
            "required": ["name", "email", "company"],
            "additionalProperties": False
        },
        "strict": True
    }
]

billing_catalog = [
    {
        "type": "function",
        "name": "bill_create_invoice",
        "description": "Create an invoice. Requires an existing customer.",
        "parameters": {
            "type": "object",
            "properties": {
                "client_id": {"type": "string"},
                "lines": {"type": "array", "items": {"type": "object", "properties": {
                    "description": {"type": "string"},
                    "amount": {"type": "number"}
                }}}
            },
            "required": ["client_id", "lines"],
            "additionalProperties": False
        },
        "strict": True
    }
]

# Fundir todos os catálogos
full_catalog = crm_catalog + billing_catalog

Boas Práticas para Descrições

Escreva descrições para pesquisa, não para documentação. «Recuperar dados do cliente» nunca será encontrado por uma consulta sobre «histórico de encomendas» ou «detalhes de contacto de faturação»: as palavras que os seus utilizadores realmente escrevem devem aparecer no texto indexado. Uma descrição útil nomeia casos de uso e vocabulário empresarial, não detalhes de implementação.

# Mau: demasiado genérico
{"name": "get_data", "description": "Retrieve data"}

# Bom: específico com contexto de utilização
{
    "name": "hr_check_leave_balance",
    "description": "Check an employee's leave balance (vacation, personal time, sick leave). "
                   "Returns remaining days by leave type. "
                   "Use when an employee asks how many days they have left."
}

# Bom: com sinónimos para melhorar a pesquisa
{
    "name": "acct_reconcile_bank",
    "description": "Bank reconciliation: compare accounting entries "
                   "with bank transactions. Account reconciliation. "
                   "Use to verify consistency between accounting records "
                   "and bank statements."
}

Combinar Pesquisa de Ferramentas com Ferramentas Fixas

A mistura é o modo de operação padrão em produção. Algumas ferramentas transversais — hora, utilizador atual, pesquisa de documentos — permanecem declaradas permanentemente porque servem quase todos os pedidos, enquanto o catálogo de negócios permanece dinâmico. Isto mantém o contexto leve sem obrigar o modelo a procurar o que precisa de cada vez.

response = client.responses.create(
    model="gpt-5.6-terra",
    input="Search the web for this month's sales and create the corresponding invoice",
    tools=[
        # Ferramentas sempre disponíveis
        {"type": "web_search"},
        {"type": "code_interpreter", "container": {"type": "auto"}},
        # Catálogo dinâmico
        {
            "type": "tool_search",
            "tool_search": {
                "tools": full_catalog  # 200+ funções
            }
        }
    ]
)

Padrão: Sistema Multidomínio

class MultiDomainSystem:
    def __init__(self):
        self.client = OpenAI()
        self.catalogs = {}

    def register_domain(self, name: str, functions: list[dict]):
        """Registar um catálogo de funções para um domínio."""
        self.catalogs[name] = functions

    def full_catalog(self) -> list[dict]:
        """Fundir todos os catálogos."""
        result = []
        for functions in self.catalogs.values():
            result.extend(functions)
        return result

    def execute(self, query: str) -> str:
        """Executar uma consulta com Pesquisa de Ferramentas em todos os domínios."""
        response = self.client.responses.create(
            model="gpt-5.6-terra",
            input=query,
            tools=[{
                "type": "tool_search",
                "tool_search": {
                    "tools": self.full_catalog()
                }
            }]
        )

        # Processar chamadas de função
        for item in response.output:
            if item.type == "function_call":
                result = self.dispatcher(item.name, item.arguments)
                # ... ciclo de chamada de função

        return response.output_text

    def dispatcher(self, name: str, arguments: str):
        """Encaminhar a chamada para o serviço correto."""
        # A sua lógica de encaminhamento
        pass

# Utilização
system = MultiDomainSystem()
system.register_domain("crm", crm_catalog)
system.register_domain("billing", billing_catalog)
system.register_domain("hr", hr_catalog)
system.register_domain("support", support_catalog)

# O modelo encontra automaticamente a função correta
# entre centenas de possibilidades
result = system.execute("How many vacation days does Marie Dupont have left?")

Pontos-chave

  • A Pesquisa de Ferramentas resolve o problema dos catálogos de funções grandes
  • O modelo recebe apenas as funções relevantes no seu contexto
  • Descrições ricas e específicas são essenciais para a precisão
  • Prefixe os nomes das funções por domínio para legibilidade
  • Combine a Pesquisa de Ferramentas com ferramentas integradas sempre disponíveis