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

Combinar ferramentas numa única chamada

Aula 19 de 20 Atualizada a 2 de novembro de 2026 Programador
Nesta página
  1. Combinar ferramentas numa única chamada
  2. Princípio de combinação
  3. Exemplo completo: assistente analítico
  4. Gerir o ciclo multi-ferramentas
  5. Estratégias de orquestração
  6. Padrão: agente multi-competências
  7. Pontos-chave

Atualizado em 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 entrada de texto utilizam o tipo 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 através das funções fichiers_generes e telecharger da Lição 10. Os ficheiros anexados a uma mensagem são carregados com o propósito user_data, que a OpenAI recomenda para entradas do modelo (File inputs). Fontes: Code Interpreter · Web search.

Combinar ferramentas numa única chamada

Até agora, analisámos cada ferramenta isoladamente. Em produção, as perguntas interessantes raramente assumem essa forma. Perguntar «como se comparam as nossas vendas com o mercado?» exige obter um valor interno, um valor externo e, em seguida, compará-los. Três ferramentas, três fontes, uma chamada.

O que muda é quem decide a ordem. Não programa a sequência: declara as ferramentas disponíveis e descreve o resultado esperado, e o modelo estabelece o seu próprio plano. Isto é conveniente, mas é também o ponto a vigiar — um plano implícito é um plano que não pode rever. A última parte desta lição mostra como retomar o controlo quando a ordem é verdadeiramente importante.

Princípio de combinação

Todas as ferramentas são declaradas no mesmo array tools, e esse é todo o mecanismo: não existe uma API de composição, apenas uma lista de capacidades disponíveis. O modelo lê o seu pedido, infere os passos necessários e chama o que precisa, pela ordem que considerar útil. Uma ferramenta declarada mas desnecessária para a tarefa simplesmente não será chamada — não custa nada além de alguns tokens na sua descrição.

from openai import OpenAI

client = OpenAI()

response = client.responses.create(
    model="gpt-5.6-terra",
    input="Compare as nossas previsões de vendas com as tendências de mercado, "
          "depois crie um gráfico de comparação.",
    tools=[
        {"type": "file_search", "vector_store_ids": ["vs_previsions"]},
        {"type": "web_search"},
        {"type": "code_interpreter", "container": {"type": "auto"}}
    ]
)

O modelo irá:

  1. Obter previsões internas via File Search
  2. Obter tendências de mercado via Web Search
  3. Gerar um gráfico de comparação via Code Interpreter

Exemplo completo: assistente analítico

with open("donnees_ventes.csv", "rb") as f:
    fichier = client.files.create(file=f, purpose="user_data")

tools = [
    # Pesquisar documentos internos
    {
        "type": "file_search",
        "vector_store_ids": ["vs_rapports", "vs_objectifs"],
        "max_num_results": 10
    },
    # Pesquisa na web para contexto de mercado
    {
        "type": "web_search",
        "search_context_size": "medium"
    },
    # Execução de código para análise
    {"type": "code_interpreter", "container": {"type": "auto"}},
    # Função para guardar o relatório
    {
        "type": "function",
        "name": "sauvegarder_rapport",
        "description": "Guardar um relatório de análise no sistema de documentos",
        "parameters": {
            "type": "object",
            "properties": {
                "titre": {"type": "string"},
                "contenu": {"type": "string"},
                "categorie": {
                    "type": "string",
                    "enum": ["analyse", "prevision", "audit", "comparaison"]
                },
                "tags": {
                    "type": "array",
                    "items": {"type": "string"}
                }
            },
            "required": ["titre", "contenu", "categorie", "tags"],
            "additionalProperties": False
        },
        "strict": True
    }
]

response = client.responses.create(
    model="gpt-5.6-terra",
    input=[{
        "role": "user",
        "content": [
            {"type": "input_text", "text": (
                "Com base neste ficheiro de vendas: "
                "1. Analisar tendências dos últimos 12 meses "
                "2. Comparar com os nossos objetivos anuais (pesquisar nos docs) "
                "3. Pesquisar na web tendências de mercado "
                "4. Gerar um gráfico de comparação "
                "5. Escrever um relatório resumo "
                "6. Guardar o relatório"
            )},
            {"type": "input_file", "file_id": fichier.id}
        ]
    }],
    tools=tools,
    instructions=(
        "É um analista de negócios sénior. "
        "Utilize todas as ferramentas ao seu dispor para produzir "
        "uma análise completa e fundamentada."
    )
)

Gerir o ciclo multi-ferramentas

Existe aqui uma assimetria que deve ter em mente, pois determina a estrutura do seu código. As ferramentas integradas — Web Search, File Search, Code Interpreter — são executadas na OpenAI: o modelo chama-as, obtém o resultado e continua, tudo numa única ida e volta. As suas funções personalizadas, no entanto, são executadas do seu lado: o modelo só pode solicitar a sua execução, depois cede o controlo e aguarda.

Daí o ciclo abaixo. Enquanto a resposta contiver chamadas de função, executa-as, devolve os resultados e reinicia. Defina um número máximo de iterações: um modelo que recorde indefinidamente a mesma ferramenta porque o resultado não o satisfaz é um caso raro mas real, e sem uma salvaguarda consumirá o seu orçamento até à exaustão.

import json

def boucle_multi_outils(prompt, tools, fichiers=None, max_tours=15):
    """Ciclo de chamada de funções com suporte multi-ferramentas."""
    content = [{"type": "input_text", "text": prompt}]
    if fichiers:
        for fid in fichiers:
            content.append({"type": "input_file", "file_id": fid})

    messages = [{"role": "user", "content": content}]

    for tour in range(max_tours):
        response = client.responses.create(
            model="gpt-5.6-terra",
            input=messages,
            tools=tools,
            instructions="Utilize as ferramentas necessárias para responder completamente."
        )

        # As ferramentas integradas (web_search, file_search, code_interpreter)
        # são executadas automaticamente no lado do servidor.
        # Apenas tratamos os itens function_call personalizados.
        appels_custom = [
            item for item in response.output
            if item.type == "function_call"
        ]

        if not appels_custom:
            # Nenhuma chamada personalizada: o modelo terminou
            return {
                "reponse": response.output_text,
                "tours": tour + 1,
                "tokens": response.usage.total_tokens
            }

        # Executar funções personalizadas
        resultats = []
        for appel in appels_custom:
            resultat = dispatcher_fonctions(appel.name, appel.arguments)
            resultats.append({
                "type": "function_call_output",
                "call_id": appel.call_id,
                "output": json.dumps(resultat)
            })

        # Preparar a próxima volta
        messages = response.output + resultats

    return {"reponse": "Limite de voltas atingido", "tours": max_tours}

Estratégias de orquestração

Orientar a ordem das ferramentas

A orquestração automática funciona bem enquanto a ordem não importar. Deixa de funcionar quando um passo deve informar o seguinte: pesquisar nos seus documentos antes da web, por exemplo, porque o vocabulário interno condiciona a relevância da consulta externa. O prompt do sistema é a alavanca — não como uma restrição técnica, mas como uma instrução metodológica que o modelo segue tanto melhor quanto for justificada.

# Estratégia 1: pesquisar primeiro, agir depois
instructions_recherche_dabord = (
    "Antes de qualquer ação, pesquise primeiro a informação necessária "
    "nos documentos internos e na web. "
    "Não proponha ações até ter reunido todos os dados."
)

# Estratégia 2: análise de dados depois enriquecimento
instructions_analyse_dabord = (
    "Comece por analisar os dados com o Code Interpreter. "
    "Depois enriqueça as suas conclusões com pesquisas na web. "
    "Finalmente, compare com documentos internos."
)

# Estratégia 3: verificação cruzada
instructions_verification = (
    "Para cada informação importante, verifique-a em pelo menos duas fontes: "
    "documentos internos E pesquisa na web. Relate quaisquer contradições."
)

Limitar ferramentas por etapa

A abordagem oposta é remover a escolha. Em vez de uma única chamada com o conjunto completo de ferramentas, divide o fluxo de trabalho em várias chamadas, cada uma declarando apenas a ferramenta para a sua etapa específica. Perde a orquestração automática, mas ganha três coisas importantes em produção: ordem garantida, custo previsível e erros isoláveis. Para um fluxo crítico, esta é quase sempre a troca certa.

# Etapa 1: recolha de dados (sem código)
response_collecte = client.responses.create(
    model="gpt-5.6-terra",
    input="Recolher informações sobre o Projeto Alpha",
    tools=[
        {"type": "file_search", "vector_store_ids": ["vs_projets"]},
        {"type": "web_search"}
    ]
)

# Etapa 2: análise com dados recolhidos
response_analyse = client.responses.create(
    model="gpt-5.6-terra",
    input=f"Analisar esta informação e gerar gráficos:\n"
          f"{response_collecte.output_text}",
    tools=[{"type": "code_interpreter", "container": {"type": "auto"}}]
)

Padrão: agente multi-competências

Este último exemplo combina ambas as abordagens: um router seleciona a configuração da ferramenta com base na natureza do pedido, depois deixa o modelo orquestrar dentro desse âmbito restrito. É o compromisso que se mantém em uso — liberdade suficiente para absorver a variedade de pedidos, estrutura suficiente para manter custos e comportamento previsíveis.

class AgentMultiCompetences:
    def __init__(self, vector_stores: list[str], fonctions: list[dict]):
        self.client = OpenAI()
        self.tools = [
            {"type": "file_search", "vector_store_ids": vector_stores},
            {"type": "web_search", "search_context_size": "medium"},
            {"type": "code_interpreter", "container": {"type": "auto"}},
        ] + fonctions

    def traiter(self, requete: str, fichiers: list[str] = None) -> dict:
        return boucle_multi_outils(requete, self.tools, fichiers)

# Instanciar o agente
agent = AgentMultiCompetences(
    vector_stores=["vs_docs", "vs_contrats"],
    fonctions=[
        {
            "type": "function",
            "name": "envoyer_email",
            "description": "Enviar um e-mail de notificação",
            "parameters": {
                "type": "object",
                "properties": {
                    "destinataire": {"type": "string"},
                    "sujet": {"type": "string"},
                    "corps": {"type": "string"}
                },
                "required": ["destinataire", "sujet", "corps"],
                "additionalProperties": False
            },
            "strict": True
        },
        {
            "type": "function",
            "name": "creer_tache",
            "description": "Criar uma tarefa no gestor de projetos",
            "parameters": {
                "type": "object",
                "properties": {
                    "titre": {"type": "string"},
                    "assignee": {"type": "string"},
                    "priorite": {"type": "string", "enum": ["basse", "moyenne", "haute"]},
                    "echeance": {"type": "string"}
                },
                "required": ["titre", "assignee", "priorite"],
                "additionalProperties": False
            },
            "strict": True
        }
    ]
)

# O agente pode agora:
# - Pesquisar documentos
# - Pesquisar na web
# - Analisar dados
# - Enviar e-mails
# - Criar tarefas
resultat = agent.traiter(
    "Analisar vendas do 1.º trimestre, comparar com objetivos, "
    "e criar uma tarefa para o diretor de vendas se estivermos atrasados."
)

Pontos-chave

  • Todas as ferramentas coexistem no mesmo array tools
  • As ferramentas integradas são executadas no servidor, as funções personalizadas no cliente
  • O modelo orquestra automaticamente a ordem das chamadas
  • Oriente a estratégia de orquestração através do prompt do sistema
  • Implemente um ciclo para tratar chamadas de funções personalizadas