🏗️ Orquestrador Completo

Usar um LLM para decompor um objetivo de alto nível em subtarefas atômicas e executáveis, validando completude e evitando sobreposição entre tarefas.

Sem decomposição estruturada, o orquestrador tenta executar objetivos impossíveis de uma só vez, resultando em falhas e retrabalho caro.

Subtarefa atômica · Critério de completude · Evitar sobreposição · LLM como decompositor · Validação do plano

Representação das tarefas como Directed Acyclic Graph, identificando quais tarefas bloqueiam outras e quais podem ser executadas em paralelo para máxima eficiência.

O DAG é a estrutura que permite paralelismo seguro — executar as tarefas na ordem errada causa falhas em cascata e resultado incorreto.

DAG · Nó bloqueador · Tarefa paralela · Topological sort · Dependência transitiva · Ciclo inválido

Como extrair do objetivo em linguagem natural as dimensões executáveis: O que fazer? Para quem? Com que critérios de sucesso? Qual o formato de entrega esperado?

Objetivos ambíguos geram planos ambíguos. O parsing estruturado força clareza antes de qualquer execução — economiza tokens e evita retrabalho.

Structured extraction · Critério de sucesso · Formato de entrega · Stakeholder implícito · Ambiguidade intencional vs. acidental

Estrutura hierárquica onde tarefas de alto nível se decompõem em subtarefas, e subtarefas em ações atômicas — formando uma árvore navegável pelo orquestrador.

A árvore permite rastreamento granular do progresso — saber exatamente em que ponto da execução o sistema está, mesmo em execuções de horas.

Nó raiz · Folha atômica · Nível de abstração · Progresso por nível · Estimativa de profundidade · Limite de recursão

Quando múltiplas tarefas estão desbloqueadas, qual executar primeiro? Critérios: criticidade para o caminho crítico, duração estimada, número de dependentes downstream, custo estimado.

A ordem de execução afeta o tempo total e o custo total. Executar tarefas críticas primeiro reduz o tempo de espera em cascata.

Caminho crítico · Criticidade · FIFO vs. priority queue · Custo de atraso · Estimativa de duração · Score de prioridade

Walkthrough completo: "Prepare due diligence da empresa X" → parsing → 15 subtarefas → DAG com dependências → ordem de execução → estimativa de custo total.

Ver o planejador completo em ação ancora todos os conceitos anteriores em um caso de uso real e representativo do que você vai construir.

Due diligence · Paralelismo de 5 tarefas · 3 ondas de execução · Custo estimado $2.40 · Tempo estimado 12 min · Código Python completo

Dado um pool de agentes especializados (financeiro, jurídico, técnico, redação), qual deve executar cada tarefa? Roteamento errado gera qualidade ruim e custo alto.

O roteamento é a decisão mais impactante do orquestrador — afeta qualidade, custo e latência de toda a execução. Roteamento inteligente pode reduzir custo em 60%.

Pool de agentes · Especialização · Critério de seleção · Fallback · Custo de roteamento errado · Benchmark por tipo de tarefa

Tabela fixa mapeando tipo de tarefa para agente responsável. Simples, previsível, fácil de depurar — mas difícil de manter quando o número de agentes e tipos de tarefa cresce.

Entender roteamento estático primeiro é fundamental — é a baseline contra a qual você compara roteamento dinâmico e mede o ganho real.

Routing table · Manutenção manual · Explosão combinatória · Quando usar · Quando migrar para dinâmico · Exemplo de código

Um agente roteador usa LLM para ler a descrição da tarefa e selecionar o agente mais adequado do pool, com fallback para agente generalista quando nenhum especialista atende.

O roteador LLM escala naturalmente: adicionar um novo agente ao pool requer apenas atualizar a descrição das capacidades, sem alterar tabelas de roteamento.

LLM classifier · Agent capabilities description · Confidence score · Fallback chain · Modelo barato para classificação · Latência de roteamento

Quando há múltiplas instâncias do mesmo tipo de agente, distribuir a carga por disponibilidade, custo atual, ou round-robin para evitar gargalos e timeouts.

Sem load balancing, uma instância fica sobrecarregada enquanto outras ficam ociosas — aumentando latência e risco de timeout no pior momento.

Round-robin · Least connections · Health-aware routing · Agent pool · Concurrency limit · Queue depth por agente

Classificar tarefas por complexidade e rotear para o agente com o modelo mais barato capaz de executar com qualidade aceitável — tarefas simples não precisam de GPT-4o.

Usar GPT-4o para tudo pode custar 30x mais que o necessário. Roteamento por custo é a alavanca mais direta para redução de custo em produção.

Complexity classifier · Tier de modelo · Custo por complexidade · Quality floor · Trade-off custo/qualidade · Tabela de decisão

Implementação completa da classe AgentRouter com pool de agentes, método route(task) → agent, logging de decisões de roteamento e métricas de acerto.

Ver a implementação concreta solidifica os conceitos e dá um template reutilizável para o projeto final da trilha.

AgentPool · route() method · Decision log · Routing accuracy · A/B testing de estratégias · Extensibilidade do roteador

Quando múltiplos agentes executam em paralelo em processos ou máquinas diferentes, o estado compartilhado não pode ficar em memória local — precisa de armazenamento distribuído.

Estado em memória local é a causa número 1 de falhas em sistemas multi-agente reais — funciona no dev, quebra em produção quando há mais de um worker.

Shared state · Race condition · Single source of truth · Eventual consistency · Locking · Atomicidade de operações

Estruturas Redis para orquestrador: hashes para estado de cada tarefa, sorted sets para fila de prioridade, streams para eventos de execução, pub/sub para notificações entre agentes.

Redis é a escolha padrão de mercado para estado de execução rápido — latência sub-milissegundo e estruturas de dados perfeitas para orquestração.

HSET/HGET · ZADD/ZRANGE · XADD/XREAD · TTL de estado · Keyspace para sessão · Atomicidade com MULTI/EXEC

Schema Postgres para dados permanentes: tabelas de execuções históricas, audit log imutável, configurações do orquestrador — o que vai para Redis vs. Postgres e por quê.

Redis é volátil — dados expiram ou são perdidos em restart. Postgres garante que o histórico de execuções, essencial para auditoria e debugging, seja permanente.

Schema de execuções · Audit log append-only · Redis vs. Postgres decision matrix · Sync entre Redis e Postgres · Backup de estado

Cada execução do orquestrador tem um session_id único. Todo estado, log e resultado é associado a ele. TTL de sessão garante limpeza automática de sessões abandonadas.

Sem session management, execuções concorrentes interferem entre si e dados de sessões antigas contaminam novas execuções — bug difícil de reproduzir em produção.

UUID como session_id · Namespace Redis por sessão · TTL automático · Sessão órfã · Cleanup job · Isolamento entre sessões

O orquestrador injeta apenas o contexto relevante para cada agente — não o histórico completo de 1000 mensagens. Técnicas de sumarização e seleção de contexto por relevância.

Context window cheio = custo exponencial e latência alta. Gerenciar o contexto ativamente pode reduzir custo por agente em 70% sem perda de qualidade.

Context budget · Sumarização de histórico · Seleção por relevância · Embedding similarity · Contexto mínimo viável · Sliding window

Se o processo do orquestrador morrer no meio de uma execução, como retomar exatamente do ponto onde parou usando o estado salvo no Redis/Postgres — sem reiniciar do zero.

Execuções longas (horas) em produção sempre enfrentam falhas. Recomeçar do zero pode custar $50+ em tokens. Recuperação de checkpoint é obrigatória em produção.

Checkpoint · Estado de tarefa (PENDING/RUNNING/DONE/FAILED) · Resume logic · Idempotência de tarefas · Detecção de restart · Custo de recuperação

Cada agente emite heartbeat periódico. O supervisor monitora: se heartbeat parar, o agente travou. Distinção entre "trabalhando normalmente" vs. "travado" vs. "crashado".

Sem health monitoring, um agente travado pode bloquear toda a execução indefinidamente enquanto o orquestrador espera um resultado que nunca virá.

Heartbeat interval · Last seen timestamp · Timeout threshold · Dead vs. slow · Processo zumbi · Forced termination

Cada tipo de tarefa tem um SLA de tempo (análise = 30s, relatório = 120s). Se ultrapassar, aciona alerta e potencialmente replanning ou escalação automática.

SLA monitoring transforma intuição em dados. Em vez de "parece lento", você tem "tarefa X está a 2.3x do SLA" e pode agir de forma proativa.

SLA por tipo de tarefa · Warning threshold · Breach threshold · SLA breaches/hora · Impacto cascata · Contrato com downstream

Heurísticas para detectar quando um agente está preso em loop: N tokens gerados sem mudança de estado, N tool calls idênticos consecutivos, N iterações sem progresso mensurável.

Um agente em loop pode gastar $100+ em tokens antes de ser detectado manualmente. Detecção automática de stall é a diferença entre $0.50 e $500 de custo.

Stall threshold · Repetition detection · Progress metric · Loop fingerprint · Interrupção controlada · Log de comportamento repetitivo

Retry inteligente não repete cegamente: retentar com contexto adicional sobre o erro anterior, com modelo diferente, com abordagem alternativa, ou com decomposição diferente da tarefa.

Retry ingênuo (tentar a mesma coisa 3x) falha exatamente da mesma forma 3x. Retry inteligente aumenta a taxa de sucesso de 40% para 85%+ em falhas transientes.

Error context injection · Model fallback · Abordagem alternativa · Exponential backoff · Max retries · Retry budget

Quando N tentativas de retry falharam, acionar replanning completo da subtarefa: gerar nova abordagem usando o estado atual e histórico de falhas como contexto para o planejador.

Replanning é o que diferencia um orquestrador robusto de um script com retry. A capacidade de replanejar é a essência da autonomia controlada.

Replanning trigger · Failure context · Alternative decomposition · Replanning budget · Profundidade máxima de replanning · Escalação após replanning

Definindo triggers claros para escalação humana (custo > $X, ação irreversível, confiança < Y%), implementando notificação assíncrona via Slack/email, interface de aprovação/rejeição.

Human-in-the-loop é o safety net final de qualquer sistema agentic. Um pipeline bem definido garante que humanos são acionados na hora certa — nem cedo demais, nem tarde demais.

Escalation triggers · Async notification · Approval interface · Timeout de aprovação · Default behavior sem resposta · Audit trail de decisões humanas

Cada ação de agente gera log estruturado com: agent_id, task_id, session_id, action_type, input, output, tokens_used, cost, timestamp, duration_ms.

Logs não-estruturados são inúteis para debugging em escala. Logs estruturados permitem queries, alertas e dashboards automáticos sem regex frágil.

JSON structured log · Schema fixo · Campos obrigatórios vs. opcionais · Log level · Correlação por session_id · Retenção de logs

Sequência imutável de todas as ações do orquestrador: quem (agente/humano) decidiu o quê, quando, com que input e com que resultado — requisito enterprise em setores regulados.

Auditoria não é opcional em fintech, saúde ou jurídico. O audit trail é o documento que prova que o sistema agiu dentro dos limites autorizados.

Append-only log · Hash chain · Imutabilidade · Timestamp com timezone · Actor identifier · Event sourcing pattern

Cada agente tem um role, cada role tem permissões específicas de tools que pode usar e ambientes que pode acessar — mesmo modelo de RBAC humano aplicado a agentes.

Sem RBAC, qualquer agente pode usar qualquer tool — um agente de análise poderia deletar dados de produção. RBAC é o princípio de menor privilégio aplicado a agentes.

Role · Permission · Tool allowlist · Environment restriction · Privilege escalation check · Role assignment dinâmico

Tool de leitura de banco: qualquer agente. Tool de escrita: apenas agentes aprovados. Tool de deploy: apenas com aprovação humana explícita. Hierarquia de risco por tool.

Granularidade de permissão por tool é o que permite dar autonomia máxima onde é seguro e exigir aprovação onde há risco real — sem bloquear tudo ou liberar tudo.

Tool risk level · Read vs. write vs. execute · Approval gate · Tool interceptor · Permission middleware · Blast radius de cada tool

Ingerir logs de múltiplos agentes em Elasticsearch ou Loki, permitindo queries cross-agent, alertas automáticos por padrão de log, e retenção configurável por tipo de dado.

Logs distribuídos por agente são impossíveis de analisar manualmente. Centralização é o que torna debugging e auditoria viáveis em escala de dezenas de agentes.

Log aggregation · Elasticsearch index · Loki label · Grafana query · Log retention policy · Custo de armazenamento de log

Como preparar relatório de auditoria mostrando todas as ações de agentes em um período — formato exigido por empresas reguladas em fintech, saúde e jurídico.

Compliance não é uma feature adicional — é o requisito mínimo para que o sistema agentic seja aprovado em ambientes enterprise. Preparar isso desde o início evita reescritas caras.

Relatório de auditoria · Período de retenção obrigatório · Exportação para regulador · Anonimização de dados sensíveis · LGPD/GDPR com agentes · Assinatura digital de logs

Casos reais de agentes em loop que geraram custos de $500+ em menos de uma hora, como isso acontece e por que controles de custo são obrigatórios desde o primeiro deploy.

Sem monitoramento de custo, um bug de loop em produção pode resultar em fatura de $10.000+ em horas. Isso arruinou startups. Não é exagero — é documentado.

Loop de custo · Custo por token · Fatura inesperada · Kill switch · Budget cap emergencial · Postmortem de custo

Cada job tem budget máximo configurável (ex: $5.00). O orquestrador monitora custo acumulado em tempo real e para a execução quando atinge o limite, entregando resultado parcial.

Budget por execução é o controle mais simples e eficaz. Com 5 linhas de código você previne 99% dos overspend acidentais em produção.

Budget per job · Real-time cost tracking · Soft vs. hard limit · Graceful stop · Partial result delivery · Budget warning at 80%

Sistema de alertas multicamada: por execução (acima de X), por hora (acima de Y), por usuário/tenant (acima de Z mensal), com integração Slack e email.

Alertas são a diferença entre descobrir o problema em 5 minutos vs. no fim do mês na fatura. Multicamada garante que nenhum padrão anômalo passe despercebido.

Alert threshold · Slack webhook · Email notification · Alert fatigue · Smart alerting (baselines) · Escalonamento de alerta

Cada execução tem um cost_center associado (departamento, projeto, cliente). Relatório mensal automatizado por cost_center para chargeback e accountability interna.

Sem cost allocation, o custo de IA fica em uma conta genérica sem responsável. Cost allocation cria accountability e incentivo para uso eficiente.

Cost center tag · Chargeback · Showback · Relatório mensal · Departamento vs. projeto vs. cliente · Overhead de infraestrutura

Dashboard mostrando custo total, custo médio por tipo de tarefa, tendência temporal, e comparação com custo humano equivalente para calcular ROI real dos agentes.

ROI é o argumento final para justificar investimento em agentes para stakeholders. Sem dados de custo vs. valor, é difícil manter orçamento para expandir o sistema.

Custo por resultado · Custo humano equivalente · ROI calculado · Break-even point · Tendência de eficiência · Apresentação para C-level

Técnicas para reduzir custo mantendo qualidade: heterogeneous routing por complexidade, caching de resultados similares com embeddings, batching de múltiplas chamadas LLM em uma.

A combinação de roteamento heterogêneo + caching pode reduzir custo total em 70-90% sem perda de qualidade perceptível — transformando o ROI do sistema.

Semantic caching · Batching de prompts · Heterogeneous routing · Cache hit rate · Qualidade mínima aceitável · Medição pré/pós otimização

O conjunto mínimo de métricas técnicas: success_rate por tipo de tarefa, latência P50/P95/P99, tokens_per_task, cost_per_task, error_rate, queue_depth por agente.

Sem métricas técnicas, você opera "no escuro". Com elas, você detecta degradação antes que afete o resultado final e identifica gargalos com precisão cirúrgica.

Success rate · P50/P95/P99 · Error budget · Queue depth · Throughput · Métricas por agente vs. por tipo de tarefa

Métricas que stakeholders de negócio entendem: objetivo_atingido_rate (% dos objetivos finais cumpridos), tempo_total_por_workflow, custo_por_resultado, NPS de usuários do sistema.

Métricas técnicas são para engenheiros. Métricas de negócio são para gestores e diretores — e são elas que determinam o orçamento futuro do projeto.

Goal completion rate · Time to completion · Cost per outcome · Qual é o "resultado" do seu sistema · Métricas de leading vs. lagging

SLI (Service Level Indicator): taxa de sucesso de análise. SLO (Service Level Objective): esse SLI deve ser >= 95% em 99.9% do tempo. Error budget = o que sobra quando o SLO é cumprido.

SLOs transformam "o sistema parece OK" em "o sistema está X% dentro do objetivo acordado". É a linguagem que alinha engenharia e negócio em torno de qualidade.

SLI definition · SLO target · Error budget · Burn rate · SLO breach · Negociação de SLO com stakeholders

Configurar prometheus_client em Python, expor /metrics endpoint, criar contadores e histogramas para métricas de agente, importar dashboard Grafana pronto para uso.

Prometheus + Grafana é o stack padrão de observabilidade em 80% das empresas tech. Saber instrumentar código Python é uma skill de alta demanda e baixa oferta.

prometheus_client · Counter · Histogram · Gauge · PromQL query · Grafana panel · /metrics scraping

Alertar quando taxa de erro supera baseline histórico (não em cada erro isolado), usando detecção de anomalia simples — evitando alert fatigue enquanto captura problemas reais.

Alertas mal calibrados criam alert fatigue — equipe ignora todos os alertas porque 95% são falso positivo. Alertas inteligentes garantem que cada alerta merece atenção.

Baseline histórico · Rolling average · Desvio padrão · False positive rate · Alerta por burn rate de SLO · PagerDuty integration

Painel executivo com: jobs rodando agora, taxa de sucesso nas últimas 24h, custo total hoje, agentes mais utilizados, top erros da semana — projetado para leitura em 30 segundos.

Dashboards executivos são o que fazem líderes confiarem no sistema. Um painel claro aumenta a probabilidade de expansão do orçamento e do escopo do projeto.

KPI panel · Traffic light status · Trend sparkline · Daily summary · Top N erros · Drill-down para detalhes técnicos

Cada execução tem um trace_id único propagado por todos os agentes que participam, permitindo reconstruir o fluxo completo de decisões e ações de ponta a ponta.

Sem trace_id, uma falha em sistema multi-agente pode levar horas para ser diagnosticada — você tem logs de 5 agentes sem saber como eles se relacionam temporalmente.

trace_id · Context propagation · W3C TraceContext · Correlação entre agentes · End-to-end latency · Gargalo identificado por trace

Cada chamada de LLM, cada tool call, cada decisão de roteamento vira um span com parent_span_id, formando uma árvore que representa a hierarquia de chamadas da execução.

A árvore de spans é o mapa de toda execução. Com ela, você vê imediatamente qual span consumiu 80% do tempo — e intervém no lugar certo.

Span · Parent span · Span duration · Span attributes · Waterfall visualization · Critical path no trace

Instrumentar o orquestrador em Python com opentelemetry-sdk, usando decorators e context managers para criar spans, enviando para Jaeger ou Grafana Tempo para visualização.

OpenTelemetry é o padrão aberto que funciona com qualquer backend (Jaeger, Tempo, Zipkin, Datadog). Instrumentar uma vez, mudar de backend sem reescrever código.

opentelemetry-api · Tracer · @tracer.start_as_current_span · OTLP exporter · Jaeger UI · Span attributes para LLM calls

Além do que aconteceu, registrar o por quê: qual foi o raciocínio do LLM para cada decisão de roteamento, cada escolha de tool, cada avaliação de qualidade — rastreabilidade de intenção.

O rastreamento de decisão é o que permite melhorar o sistema iterativamente. Sem entender o porquê de cada escolha, otimização é tentativa e erro cego.

Decision log · Reasoning trace · LLM rationale · Span attribute para decisão · Explainability · Audit de raciocínio

Dado uma execução que falhou, usar o trace para identificar exatamente onde e por que: análise do waterfall, identificação do span problemático, diagnóstico de causa raiz.

Debug de sistema multi-agente sem trace é como depurar código sem stack trace. Com trace, o que levaria horas leva minutos — habilidade indispensável em produção.

Error span · Root cause analysis · Waterfall analysis · Span que falhou vs. span afetado · Reproduzir em staging · Fix verificado via trace

Quando um alerta de latência dispara no Prometheus, como correlacionar automaticamente com o trace específico que causou o problema — navegação direta de métrica para trace.

A correlação completa fecha o loop de observabilidade: alerta → métrica → trace → log → causa raiz. Sem correlação, cada camada existe em silos independentes.

Exemplar (Prometheus) · TraceID em log · Grafana Tempo integration · Click-through de métrica para trace · MELT (Metrics Events Logs Traces)

LangGraph orquestra fluxo, CrewAI abstrai times de agentes, Redis gerencia estado efêmero, Postgres persiste histórico, Prometheus monitora — divisão de responsabilidades clara.

Tentar usar um único produto para tudo resulta em soluções subótimas em todas as dimensões. Entender por que cada ferramenta existe guia escolhas arquiteturais corretas.

Separation of concerns · Best-of-breed vs. all-in-one · Custo de integração · Vendor lock-in · Trade-off complexidade/otimização

Stack de referência 2026 para orquestradores de produção: LangGraph (workflow), CrewAI (teams), Redis (estado), Postgres (persistência), Arize (observabilidade LLM).

Conhecer o stack de referência acelera decisões de arquitetura — você parte de um padrão comprovado e o adapta, em vez de reinventar a roda em cada projeto.

Stack de referência · Versões pinadas · Compatibilidade entre componentes · Custo total de infraestrutura · Alternativas por componente

LangGraph como outer loop de orquestração, CrewAI como nó interno para execução de times, Redis como side-car de estado, Postgres como log store — padrões de comunicação entre eles.

Integrar ferramentas sem padrões claros resulta em acoplamento rígido, onde mudar uma ferramenta exige reescrever tudo. Padrões de integração permitem substituição cirúrgica.

Outer loop · Inner node · Side-car pattern · Event-driven communication · Sync vs. async entre componentes · Circuit breaker entre integrações

Definindo interfaces claras entre componentes com adapters e ports, permitindo trocar Redis por outro KV store sem reescrever o orquestrador — arquitetura hexagonal aplicada a agentes.

Acoplamento rígido mata sistemas a longo prazo. Uma interface bem definida agora permite migração de Redis para DynamoDB em 2 horas em vez de 2 semanas.

Hexagonal architecture · Port · Adapter · Interface abstrata · Dependency injection · Testabilidade por inversão de dependência

Como testar o orquestrador completo sem mockar tudo: testes de contrato entre componentes, test doubles determinísticos para LLMs em testes, testes de integração com Redis/Postgres reais.

Testar sistemas com LLMs é desafiador pela não-determinismo. Aprender a usar test doubles corretos é o que torna o CI/CD viável sem depender de chamadas reais caras.

Contract test · Test double · LLM mock determinístico · Testcontainers para Redis/Postgres · Integration test vs. unit test · CI/CD de orquestrador

O orquestrador completo visualizado: todas as 6 camadas mapeadas para os componentes técnicos específicos, com as conexões e fluxos de dados entre eles.

O diagrama final é a síntese de toda a trilha — e o artefato que você apresentará em entrevistas e revisões de arquitetura para demonstrar domínio do tema.

C4 model simplificado · Diagrama de componentes · Fluxo de dados · Pontos de falha · Escala horizontal · Custo de infraestrutura total

Usar GPT-4o ou Claude Opus para todas as chamadas LLM — inclusive classificações simples, formatações e extrações triviais — resulta em custo 10-50x acima do necessário.

Este é o erro mais comum em sistemas agentic de primeira geração. Compreender o problema é o primeiro passo para a solução que reduz custo na mesma ordem de grandeza.

Custo por modelo · Tabela de preços 2026 · Tarefas simples vs. complexas · Overkill analysis · Custo desperdiçado estimado

Classificar cada chamada LLM por complexidade e rotear para o modelo mais barato com qualidade aceitável: GPT-4o-mini para simples, GPT-4o para médio, o1 para raciocínio profundo.

Heterogeneous routing é a alavanca mais poderosa de redução de custo. Implementado corretamente, reduz custo total em 70-90% enquanto mantém 95%+ da qualidade original.

Model tier (barato/médio/caro) · Complexity threshold · Quality floor · Routing policy · Fallback para tier superior · A/B test de qualidade

Um modelo muito barato (Haiku, GPT-4o-mini) classifica a complexidade de cada tarefa antes do roteamento. O custo do classificador é < 1% do custo total da execução.

O classificador é a chave de todo o sistema de roteamento heterogêneo. Calibrar sua precisão é o que determina quanto custo você economiza vs. quanta qualidade você perde.

Complexity features · Few-shot classifier · Accuracy do classificador · Custo do classificador vs. economia gerada · Calibração com exemplos reais

Planejar uma vez com modelo caro (1 chamada), executar N vezes com modelo barato (N chamadas). Reduz custo total em até 90% em workflows com muitas tarefas de execução.

Plan-and-Execute é o padrão arquitetural mais impactante para redução de custo. Um planejador bem estruturado pode transformar o custo de um workflow de $10 para $1.

Planner (modelo caro) · Executor (modelo barato) · Plano como prompt estruturado · Número de execuções · Custo de planejamento vs. custo total

Quando duas execuções fazem perguntas semanticamente similares ao LLM, retornar resultado cacheado em vez de fazer nova chamada cara. Cache com embeddings detecta similaridade além de match exato.

Em sistemas com múltiplos usuários fazendo perguntas similares, semantic caching pode reduzir chamadas LLM em 40-60%, com impacto proporcional no custo.

Embedding similarity · Cosine distance threshold · Cache hit rate · Cache invalidation · TTL por tipo de query · GPTCache / LangChain cache

Mesmo workflow executado com e sem otimização: tabela comparando custo total, latência e score de qualidade (avaliação por LLM ou humano). Onde aceitar o trade-off qualidade/custo.

Dados de benchmark são o que transforma argumentos de otimização em decisões racionais. Sem medir, você não sabe se a otimização valeu a pena nem onde parar.

Baseline sem otimização · Custo pós-otimização · Qualidade score · Pareto frontier custo/qualidade · Ponto de aceitação · ROI da otimização

Orquestrador de análise competitiva: recebe empresa alvo → coleta dados → analisa → gera relatório. Requisitos funcionais (inputs, outputs, SLAs) e não-funcionais (custo máximo, disponibilidade).

Definir requisitos antes de codificar é o que separa projetos que terminam dos que ficam em refatoração eterna. Requisitos claros guiam cada decisão de implementação.

Requisito funcional · Requisito não-funcional · SLA do sistema · Budget máximo por análise · Definition of Done · Escopo do MVP

Diagrama completo antes do primeiro código: cada uma das 6 camadas mapeada para classes Python específicas, com interfaces e responsabilidades definidas antes de implementar.

Top-down design previne "código espaguete" em sistemas complexos. Definir as interfaces antes do código garante que os componentes se encaixem sem gambiarra.

Classe por camada · Interface definition · Dependency graph de classes · Data model · API interna · Diagrama antes do código

Código Python das Camadas 1-4: IntelligentPlanner (decomposição + DAG), AgentRouter (seleção dinâmica), StateManager com Redis, Supervisor com health check e replanning.

Implementar cada camada sequencialmente, testando antes de avançar, é a metodologia que resulta em código confiável. Cada camada é um milestone verificável.

IntelligentPlanner · AgentRouter · StateManager · Supervisor · Código comentado · Smoke test por camada · Integração progressiva

Camada 5 em código: StructuredLogger com JSON, BudgetMonitor com hard stop, RBACManager com roles simples — governança funcional em menos de 150 linhas de Python.

Governança implementada depois é mais cara e frágil. Implementar junto com o sistema garante que todos os componentes geram logs e respeitam limites desde o primeiro deploy.

StructuredLogger · BudgetMonitor · RBACManager · Middleware de permissão · Log de auditoria automático · Budget hard stop

Camada 6 em código: métricas Prometheus, endpoint /health para readiness probe, suite de testes com pytest cobrindo as integrações críticas do orquestrador.

Observabilidade e testes são o que transforma "funciona no meu laptop" em "funciona em produção". Sem eles, o sistema é uma caixa preta que falha de forma imprevisível.

prometheus_client · /health endpoint · /metrics endpoint · pytest fixtures · Test doubles para LLM · Coverage das camadas críticas

Dockerizar o orquestrador completo com docker-compose (app + Redis + Postgres + Prometheus), escrever README com diagrama de arquitetura e guia de como continuar evoluindo o projeto.

Um projeto que não está no Docker com README claro não existe para outros engenheiros. A entrega profissional do projeto final é o que transforma aprendizado em portfólio.

Dockerfile · docker-compose.yml · README com diagrama · Como escalar para produção · Próximas features · Contribuição para o projeto