Combinar ferramentas numa única chamada
Nesta página
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 tipoinput_texte a pesquisa na web utiliza a ferramentaweb_search(web_search_previewé agora uma ferramenta legada sem filtros de domínio). Os ficheiros gerados são recuperados através das funçõesfichiers_generesetelechargerda Lição 10. Os ficheiros anexados a uma mensagem são carregados com o propósitouser_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á:
- Obter previsões internas via File Search
- Obter tendências de mercado via Web Search
- 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