Arquiteturas multi-ferramentas em produção
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 são tipadas comoinput_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 utilizando as funçõesfichiers_generesetelechargerda Lição 10. Fontes: Code Interpreter · Web search.
Arquiteturas multi-ferramentas em produção
Um protótipo multi-ferramentas funciona porque uma única pessoa o utiliza, conhece os seus limites e reinicia-o quando falha. A produção remove simultaneamente estas três condições. O que se torna crítico não é a qualidade da resposta — isso já existia — mas sim três propriedades que o protótipo não possuía: saber o que aconteceu quando uma chamada falha, impedir que um ciclo infinito esgote o seu orçamento e conseguir modificar o comportamento sem necessidade de redeploy.
Os padrões abaixo abordam cada um destes requisitos. Não os adote todos de uma vez: comece pela observabilidade, pois sem ela nem sequer saberá qual dos outros lhe falta.
Arquitetura em camadas
Separar responsabilidades em camadas não é elegância arquitetural: torna cada parte substituível. O benefício concreto é poder alterar a orquestração sem tocar na interface, ou adicionar uma ferramenta sem reescrever a lógica de negócio. As quatro camadas abaixo representam a decomposição mínima que se mantém na prática.
# Camada 1: Interface - receção de pedidos
# Camada 2: Orquestração - gestão de ciclos e encaminhamento
# Camada 3: Execução - chamadas de ferramentas e funções
# Camada 4: Observabilidade - logs, métricas, traços
from openai import OpenAI
from dataclasses import dataclass, field
from datetime import datetime
import json
import time
import logging
logger = logging.getLogger("multi-ferramentas")
@dataclass
class TraceExecucao:
"""Rasto de execução para monitorização."""
pedido_id: str
inicio: float = field(default_factory=time.time)
ciclos: list = field(default_factory=list)
ferramentas_usadas: list = field(default_factory=list)
tokens_total: int = 0
erros: list = field(default_factory=list)
duracao_total: float = 0.0
Orquestrador de produção
class OrquestradorProducao:
def __init__(self, config: dict):
self.cliente = OpenAI()
self.config = config
self.ferramentas = self._construir_ferramentas(config)
self.dispatcher = self._construir_dispatcher(config)
def _construir_ferramentas(self, config: dict) -> list:
"""Constrói o array de ferramentas a partir da configuração."""
ferramentas = []
if config.get("file_search"):
ferramentas.append({
"type": "file_search",
"vector_store_ids": config["file_search"]["vector_stores"],
"max_num_results": config["file_search"].get("max_results", 10)
})
if config.get("web_search"):
ferramentas.append({
"type": "web_search",
"search_context_size": config["web_search"].get("context_size", "medium")
})
if config.get("code_interpreter"):
ferramentas.append({"type": "code_interpreter", "container": {"type": "auto"}})
for func in config.get("funcoes", []):
ferramentas.append(func)
return ferramentas
def _construir_dispatcher(self, config: dict) -> dict:
"""Mapeia nomes de funções para as suas implementações."""
return config.get("implementacoes", {})
def executar(self, pedido: str, ficheiros: list = None,
max_ciclos: int = 10) -> dict:
"""Executa um pedido com rastreio completo."""
rasto = TraceExecucao(
pedido_id=f"req_{int(time.time()*1000)}"
)
conteudo = [{"type": "input_text", "text": pedido}]
if ficheiros:
for fid in ficheiros:
conteudo.append({"type": "input_file", "file_id": fid})
mensagens = [{"role": "user", "content": conteudo}]
try:
for ciclo in range(max_ciclos):
inicio_ciclo = time.time()
resposta = self.cliente.responses.create(
model=self.config.get("model", "gpt-5.6-terra"),
input=mensagens,
tools=self.ferramentas,
instructions=self.config.get("instructions", "")
)
rasto.tokens_total += resposta.usage.total_tokens
# Identificar chamadas de função
chamadas = [
item for item in resposta.output
if item.type == "function_call"
]
# Registar ferramentas utilizadas
for item in resposta.output:
if hasattr(item, "type"):
rasto.ferramentas_usadas.append(item.type)
rasto.ciclos.append({
"numero": ciclo + 1,
"chamadas_funcao": len(chamadas),
"duracao": time.time() - inicio_ciclo
})
if not chamadas:
rasto.duracao_total = time.time() - rasto.inicio
return {
"resposta": resposta.output_text,
"rasto": rasto
}
# Executar funções personalizadas
resultados = self._executar_funcoes(chamadas, rasto)
mensagens = resposta.output + resultados
except Exception as e:
rasto.erros.append(str(e))
rasto.duracao_total = time.time() - rasto.inicio
logger.error(f"Erro no pedido {rasto.pedido_id}: {e}")
return {"resposta": None, "erro": str(e), "rasto": rasto}
rasto.duracao_total = time.time() - rasto.inicio
return {"resposta": "Limite de ciclos atingido", "rasto": rasto}
def _executar_funcoes(self, chamadas: list, rasto: TraceExecucao) -> list:
"""Executa funções com tratamento de erros."""
resultados = []
for chamada in chamadas:
try:
func = self.dispatcher.get(chamada.name)
if not func:
raise ValueError(f"Função desconhecida: {chamada.name}")
args = json.loads(chamada.arguments)
resultado = func(**args)
resultados.append({
"type": "function_call_output",
"call_id": chamada.call_id,
"output": json.dumps(resultado)
})
except Exception as e:
rasto.erros.append(f"{chamada.name}: {str(e)}")
resultados.append({
"type": "function_call_output",
"call_id": chamada.call_id,
"output": json.dumps({"error": str(e)})
})
return resultados
Configuração declarativa
Mover as definições do sistema do código para a configuração altera quem pode intervir. Ajustar um prompt de sistema, remover uma ferramenta ou modificar um teto de custos torna-se uma alteração de ficheiro — revisável e reversível — em vez de um deploy. Num sistema que evolui semanalmente, essa é a diferença entre iterar e reagir.
config_assistente_comercial = {
"model": "gpt-5.6-terra",
"instructions": (
"És um assistente de vendas. Tens acesso a dados de CRM, "
"documentação de produtos, à web e à análise de dados. "
"Prioriza dados internos, enriquece com dados da web."
),
"file_search": {
"vector_stores": ["vs_fichas_produto", "vs_propostas"],
"max_results": 10
},
"web_search": {
"context_size": "medium"
},
"code_interpreter": True,
"funcoes": [
{
"type": "function",
"name": "criar_oportunidade",
"description": "Criar uma oportunidade no CRM",
"parameters": {
"type": "object",
"properties": {
"cliente": {"type": "string"},
"montante": {"type": "number"},
"probabilidade": {"type": "integer"}
},
"required": ["cliente", "montante", "probabilidade"],
"additionalProperties": False
},
"strict": True
}
],
"implementacoes": {
"criar_oportunidade": lambda cliente, montante, probabilidade:
crm_service.criar_oportunidade(cliente, montante, probabilidade)
}
}
orquestrador = OrquestradorProducao(config_assistente_comercial)
resultado = orquestrador.executar("Prepara uma proposta para a Acme Corp")
Observabilidade e monitorização
Painel de métricas
Três métricas são suficientes para começar, e cada uma responde a uma pergunta diferente: a latência por ferramenta indica qual está a desacelerar o sistema, a taxa de falha por ferramenta indica qual é frágil, e o custo por pedido indica qual está a disparar. Uma média global entre as três não responde a nenhuma destas questões.
class MetricasMultiFerramentas:
def __init__(self):
self.pedidos = []
def registar(self, rasto: TraceExecucao):
self.pedidos.append({
"id": rasto.pedido_id,
"timestamp": datetime.now().isoformat(),
"duracao": rasto.duracao_total,
"ciclos": len(rasto.ciclos),
"tokens": rasto.tokens_total,
"ferramentas": list(set(rasto.ferramentas_usadas)),
"erros": len(rasto.erros),
"custo_estimado": self._estimar_custo(rasto)
})
def _estimar_custo(self, rasto: TraceExecucao) -> float:
"""Estima o custo em dólares da execução."""
# Taxas aproximadas para gpt-5.6-terra: $2 / $12 por milhão
custo_input = rasto.tokens_total * 0.6 * 0.000002
custo_output = rasto.tokens_total * 0.4 * 0.000012
return round(custo_input + custo_output, 4)
def relatorio(self) -> dict:
if not self.pedidos:
return {}
duracoes = [r["duracao"] for r in self.pedidos]
tokens = [r["tokens"] for r in self.pedidos]
custos = [r["custo_estimado"] for r in self.pedidos]
return {
"total_pedidos": len(self.pedidos),
"duracao_media": sum(duracoes) / len(duracoes),
"tokens_medio": sum(tokens) / len(tokens),
"custo_total": sum(custos),
"taxa_erro": sum(1 for r in self.pedidos if r["erros"] > 0) / len(self.pedidos),
"ferramentas_mais_usadas": self._ferramentas_frequentes()
}
def _ferramentas_frequentes(self) -> dict:
contador = {}
for r in self.pedidos:
for ferramenta in r["ferramentas"]:
contador[ferramenta] = contador.get(ferramenta, 0) + 1
return dict(sorted(contador.items(), key=lambda x: -x[1]))
Gestão de custos
class GestorCustos:
def __init__(self, orcamento_diario: float = 50.0):
self.orcamento = orcamento_diario
self.gastos_dia = 0.0
self.data_reset = datetime.now().date()
def pode_executar(self, custo_estimado: float) -> bool:
"""Verifica se o orçamento permite a execução."""
hoje = datetime.now().date()
if hoje > self.data_reset:
self.gastos_dia = 0.0
self.data_reset = hoje
return (self.gastos_dia + custo_estimado) <= self.orcamento
def registar_gasto(self, custo: float):
self.gastos_dia += custo
def orcamento_restante(self) -> float:
return self.orcamento - self.gastos_dia
# Integração no orquestrador
gestor_custos = GestorCustos(orcamento_diario=100.0)
def executar_com_orcamento(orquestrador, pedido, **kwargs):
custo_estimado = 0.05 # Estimativa conservadora
if not gestor_custos.pode_executar(custo_estimado):
return {"erro": "Orçamento diário atingido", "restante": 0}
resultado = orquestrador.executar(pedido, **kwargs)
custo_real = resultado["rasto"].tokens_total * 0.000002
gestor_custos.registar_gasto(custo_real)
return resultado
Padrão: router inteligente
À medida que os casos de uso se multiplicam, a tentação é entregar tudo a um único sistema equipado com todas as ferramentas. Essa é a escolha mais dispendiosa: cada pedido, mesmo os triviais, carrega o conjunto completo de definições de ferramentas. Um router que classifica primeiro o pedido e depois chama um orquestrador especializado mantém os contextos curtos e torna cada fluxo mensurável separadamente.
class RouterInteligente:
def __init__(self):
self.cliente = OpenAI()
self.orquestradores = {}
def registar(self, dominio: str, orquestrador: OrquestradorProducao):
self.orquestradores[dominio] = orquestrador
def rotear(self, pedido: str) -> dict:
"""Determina o domínio e encaminha para o orquestrador correto."""
# Classificação rápida com um modelo leve
resposta = self.cliente.responses.create(
model="gpt-5.6-terra",
input=f"Classifica este pedido num domínio: {pedido}\n"
f"Domínios disponíveis: {list(self.orquestradores.keys())}\n"
f"Responde apenas com o nome do domínio.",
)
dominio = resposta.output_text.strip().lower()
if dominio not in self.orquestradores:
dominio = "geral" # Fallback
logger.info(f"Pedido roteado para: {dominio}")
return self.orquestradores[dominio].executar(pedido)
# Configuração
router = RouterInteligente()
router.registar("comercial", OrquestradorProducao(config_assistente_comercial))
router.registar("suporte", OrquestradorProducao(config_suporte))
router.registar("rh", OrquestradorProducao(config_rh))
# Utilização
resultado = router.rotear("Quantos dias de férias me restam?")
# -> Encaminha automaticamente para o orquestrador de RH
Lista de verificação para produção
Esta lista de verificação é intencionalmente curta. Não visa ser exaustiva, mas cobre os pontos cuja ausência custa em incidentes e não apenas em desconforto — e que não pode adicionar às pressas no dia em que o sistema já está nas mãos dos utilizadores.
lista_verificacao = {
"seguranca": [
"Validar argumentos para cada função",
"Limitação de taxa por utilizador",
"Sanitizar entradas e saídas",
"Sem dados sensíveis nos logs"
],
"fiabilidade": [
"Tentativas com backoff em erros transitórios",
"Disjuntor por serviço externo",
"Timeout por ferramenta e por pedido global",
"Fallback quando uma ferramenta está indisponível"
],
"desempenho": [
"Execução paralela de chamadas independentes",
"Cache de resultados de pesquisa frequentes",
"Limitar o número de iterações do ciclo",
"Escolher o modelo adaptado à complexidade (gpt-5.6-terra vs gpt-5.6-terra)"
],
"observabilidade": [
"Logging estruturado para cada chamada",
"Métricas de latência e custo",
"Alertas sobre taxa de erro",
"Rasto completo de cada pedido"
],
"custos": [
"Orçamento diário com disjuntor",
"Estimativa de custo antes da execução",
"Relatório de gastos semanal",
"Otimização da escolha do modelo por complexidade"
]
}
Pontos-chave
- Decompor em camadas: interface, orquestração, execução, observabilidade
- Utilizar configuração declarativa para definir sistemas
- Rastrear cada execução para monitorização e depuração
- Implementar um gestor de custos com orçamento diário
- Um router inteligente distribui pedidos pelos orquestradores corretos
Teste os seus conhecimentos
Chamada de funções, pesquisa, execução: o arsenal completo em cinco perguntas.
1. O que deve conter um bom esquema de função?
Resposta: Tipos estritos e descrições operacionais por parâmetro — este é o contrato que o modelo utiliza para decidir quando chamar e como preencher; a validação rejeita o resto.
2. Pesquisa na Web ou Pesquisa de Ficheiros: como escolher?
Resposta: Pesquisa na Web para informação pública e recente; Pesquisa de Ficheiros para os seus documentos indexados (fragmentação + classificação integrada) — e a pesquisa híbrida combina ambas quando a resposta abrange ambos os mundos.
3. O que permite o Code Interpreter na API?
Resposta: Executar código numa sandbox: processar CSV/Excel/imagens, calcular com precisão, produzir gráficos — o modelo raciocina, o código calcula, a sandbox isola.
4. Para que serve a Pesquisa de Ferramentas?
Resposta: Para expor dinamicamente um grande catálogo de ferramentas: o modelo pesquisa a ferramenta relevante em vez de receber cem esquemas de uma vez — o contexto mantém-se leve, as capacidades permanecem vastas.
5. Que regras se aplicam a uma arquitetura multi-ferramentas em produção?
Resposta: Ferramentas com âmbito claro, tratamento de erros e fallbacks por ferramenta, chamadas paralelas quando independentes, e observabilidade para cada chamada — a robustez é desenhada ferramenta a ferramenta.
Cada ferramenta tem o seu terreno; a produção combina-as — a arquitetura final acima é o seu plano de referência.