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

Arquiteturas multi-ferramentas em produção

Aula 20 de 20 Atualizada a 2 de novembro de 2026 Programador
Nesta página
  1. Arquiteturas multi-ferramentas em produção
  2. Arquitetura em camadas
  3. Orquestrador de produção
  4. Configuração declarativa
  5. Observabilidade e monitorização
  6. Gestão de custos
  7. Padrão: router inteligente
  8. Lista de verificação para produção
  9. Pontos-chave
  10. Teste os seus conhecimentos

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 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 · 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.