Pular para o conteúdo
fernando.moretes.com
BlogEstudosCursosE-booksOpen SourcePodcasts
Loading…
Fernando Azevedo

Arquiteto de TI Especialista

Arquitetura, AWS, IA em produção, sistemas financeiros e FinOps, escritos a partir do que foi operado, com os números.

  • LinkedIn
  • GitHub
  • E-mail

Conteúdo

  • Blog
  • Estudos de arquitetura
  • Cursos
  • E-books
  • Open Source
  • Podcasts
  • Assuntos
  • Trilhas

Ferramentas

  • Moretes Architect MCP
  • Well-Architected self-check
  • Arquitetura deste site
  • Números públicos
  • Histórico de estudo

Sobre

  • Comunidade
  • Hugging Face
  • IA Builder
  • Perfil
  • Currículo (CV)
  • Trabalhe comigo
  • Media kit
  • RSS do blog
  • RSS dos estudos
  • Artigos narrados (podcast)
  • llms.txt
  • Termos, privacidade e uso de IA

(c) 2026 Fernando Francisco Azevedo

Blog/Artigo
RSSMarkdownLLMs
IA & AgentesAnatomia do Padrão

Implemente e teste uma calculadora de capacidade MCP: lacunas, premissas explícitas e hospedagem AWS

16 de nov. de 2026 12 minAvançado Com apoio de IA000 visualizações00 reproduções
Ouvir artigo

cerca de 12 min · áudio gerado ao tocar

Apenas um pico de 500 requisições por segundo não permite estimar concorrência sem a duração do processamento. Execute uma calculadora MCP local, preserve essa lacuna e depois forneça uma duração explicitamente hipotética para testar o cenário.

Uma fronteira AWS restrita

Capacidade é calculada em memória; cotas e logs são dependências operacionais, não evidências de negócio.

AWS · public hosting
  • API Gateway
  • Lambda · capacity_plan
  • DynamoDB · quota + usage
  • CloudWatch · minimal logs

Uma equipe de produto informa um requisito: sua API de pedidos precisa suportar um pico de 500 requisições por segundo. Você está construindo um assistente de arquitetura que chama ferramentas e quer usá-lo em uma conversa inicial de capacidade. Antes de recomendar recursos, o que ele consegue calcular apenas com esse número?

Não consegue calcular concorrência. Neste exercício simplificado, concorrência é a quantidade de requisições processadas ao mesmo tempo, estimada pela taxa de chegada multiplicada pela duração do processamento. Se hipoteticamente adotarmos 250 milissegundos, teremos 500 × 0,250 = 125 requisições concorrentes. Com 30% de folga e arredondamento, chegamos a 163. São cálculos de cenário: a equipe não informou essa duração, portanto 163 não é um requisito aprovado para produção.

Este tutorial é para desenvolvedores que criam ferramentas MCP para assistentes de arquitetura. MCP permite que um cliente descubra e chame ferramentas de um servidor. Vamos acompanhar uma ferramenta determinística pequena, capacity_plan, para aprender a preservar informações ausentes no schema de entrada e na resposta. Você executará a implementação publicada, examinará as mudanças de código e testará respostas reais do protocolo. Não vamos construir um arquiteto autônomo, avaliar um modelo, escolher instâncias AWS nem implantar nova infraestrutura.

A implementação faz parte do meu workbench aberto Moretes Architect MCP, versão 0.5.0. Ele contém outras ferramentas, mas este artigo acompanha apenas capacity_plan e seu tratamento de validação. A implantação pública existente utiliza API Gateway, Lambda e uma tabela DynamoDB operacional. O exercício principal roda localmente, sem credenciais AWS nem modelo de linguagem; a seção final explica como essa ferramenta se encaixa na hospedagem AWS existente.

O problema concreto veio do relato de primeira utilização de Pin Xiong na issue #19 do GitHub do workbench. Um cliente chamou a ferramenta anterior com entradas incompletas e recebeu uma rejeição. Quando o chamador fornecia valores hipotéticos, a resposta não os separava claramente dos requisitos informados. Esse relato motivou a implementação 0.5.0 examinada aqui. É evidência sobre esta ferramenta, não uma afirmação de que todo assistente inventa entradas nem de que a correção elimina alucinações.

O que será implementado e verificado

Vamos separar três situações: uma requisição inválida, que precisa de correção; um cenário válido porém incompleto, que deve conservar as lacunas; e um cenário completo com premissas, que pode produzir números sem se tornar um requisito aprovado.

O resultado executável será um cliente MCP no terminal e um teste de aceitação repetível. Primeiro, envie apenas o pico conhecido: espere concorrência null e a lista de campos ausentes. Depois, forneça entradas explicitamente hipotéticas: espere 125/163, ainda sem validação do workload. Por fim, teste entradas inválidas e repita as verificações por HTTP local. Os trechos explicam como implementar esse comportamento em sua própria ferramenta; instalar o pacote não implementa todo o seu fluxo de arquitetura.

Os pré-requisitos são Node.js 22.13 ou superior, npm e um terminal. A instalação dos pacotes utiliza rede. Os cálculos locais não precisam de credenciais AWS nem de um modelo pago. Um cliente de IDE que utilize seu próprio modelo continua sujeito ao plano desse cliente; o laboratório não mede o comportamento desse modelo.

1. Comece pelo que a equipe realmente informou

Execute a versão fixada e indique explicitamente que o tráfego é de pico:

npx --yes --package moretes-aws-architect-mcp@0.5.0 \
  moretes-architect call capacity_plan \
  --arg requestsPerSecond=500 --arg rateType=peak \
  --arg 'inputProvenance={"requestsPerSecond":"provided"}'

Os campos relevantes do resultado são:

{
  "validated": false,
  "status": "insufficient-inputs",
  "insufficientInputs": ["durationMs", "payloadKB"],
  "averageConcurrency": null,
  "plannedConcurrency": null,
  "dailyRequests": null,
  "dailyPayloadGB": null
}

A chamada funcionou. O cenário de negócio é que está incompleto. O cliente pode perguntar pelos dados ausentes. Converter null em zero ou esconder esses campos na apresentação apagaria justamente a informação que interessa à decisão.

O parâmetro rateType=peak evita outra conclusão indevida. Um pico de 500 requisições/s não estabelece o volume diário. Por compatibilidade, unspecified ainda calcula um cenário condicionado a uma taxa sustentada: isso não é previsão de demanda. Declare o tipo de taxa em vez de depender desse default.

2. Corrija o contrato de entrada

Exigir todos os números transforma uma ferramenta em um formulário que o cliente pode preencher sem evidência. Na implementação, a taxa é obrigatória; duração e payload são opcionais:

const shape = {
  requestsPerSecond: z.number().nonnegative().max(1e9),
  durationMs: z.number().nonnegative().max(86400000).optional(),
  payloadKB: z.number().nonnegative().max(1e9).optional(),
  headroom: z.number().min(1).max(10).optional(),
  rateType: z.enum(['peak', 'sustained', 'unspecified'])
    .default('unspecified')
};

Esse trecho integra o registro de uma ferramenta existente; não constitui um servidor completo. A implementação integral também declara o objeto estrito de proveniência por campo. Copiar somente o cálculo deixaria de fora a validação e o tratamento do protocolo.

Ao publicar o schema para o cliente, use o modo de entrada do Zod:

z.toJSONSchema(schema, { io: 'input' });

Entrada e saída deixam de ser contratos idênticos quando há defaults. Neste projeto, exportar o modo errado fazia campos com default parecerem obrigatórios na descoberta. O teste deve conferir o tools/list efetivo: o array required de capacity_plan contém somente requestsPerSecond.

3. Calcule apenas o que os dados permitem

O núcleo da conta pode continuar pequeno:

const headroom = a.headroom ?? 1.3;
const concurrency = a.durationMs === undefined
  ? null : a.requestsPerSecond * a.durationMs / 1000;
const dailyRequests = a.rateType === 'peak'
  ? null : a.requestsPerSecond * 86400;
const dailyPayloadGB = dailyRequests === null || a.payloadKB === undefined
  ? null : dailyRequests * a.payloadKB / 1e6;

Sem duração, não calculamos concorrência. Sem payload, não calculamos volume de dados; isso não impede a concorrência quando a duração foi fornecida. Uma taxa de pico não vira volume diário. Zero é um valor informado; undefined representa ausência. Por isso, verificações explícitas e o operador de coalescência nula são preferíveis a testes de truthiness.

Esses números descrevem um cenário, não determinam uma reserva de concorrência da Lambda, um pool de conexões, uma instância ou uma cota de serviço. Retries, batching, caudas de latência, distribuição das chegadas e saturação das dependências exigem evidências próprias. O nome legado averageConcurrency não significa medição: com uma taxa de pico, ele representa a conta sob aquela taxa escolhida.

4. Mantenha cada premissa ao lado do valor

Agora podemos experimentar valores hipotéticos, identificados como tais:

npx --yes --package moretes-aws-architect-mcp@0.5.0 \
  moretes-architect call capacity_plan \
  --arg requestsPerSecond=500 --arg durationMs=250 \
  --arg payloadKB=4 --arg headroom=1.3 --arg rateType=peak \
  --arg 'inputProvenance={"requestsPerSecond":"provided","durationMs":"assumed","payloadKB":"assumed","headroom":"assumed"}'

A conta resulta em 500 × 0,250 = 125. Com a folga, ceil(125 × 1,3) = 163. São valores calculados para o cenário, não resultados de benchmark. O volume diário continua null porque a taxa é de pico.

Uma projeção do objeto provenance mostra:

{
  "requestsPerSecond": { "value": 500, "origin": "provided" },
  "durationMs": { "value": 250, "origin": "assumed" },
  "payloadKB": { "value": 4, "origin": "assumed" },
  "headroom": { "value": 1.3, "origin": "assumed" }
}

Se headroom não for informado, sua origem será server-default. Um número recebido sem identificação será caller-unspecified. Rotular um valor ausente não faz esse valor existir.

O limite dessa solução precisa ficar explícito: o cliente pode chamar um chute de measured. O servidor não verifica a medição nem prova a aprovação do responsável pelo workload. Um fluxo de produção precisa de registro de evidências, data da medição e responsável. validated: false conserva a diferença entre executar aritmética e aprovar uma arquitetura.

5. Transforme o erro em uma pergunta acionável

Incompletude do cenário e entrada inválida não devem produzir a mesma mensagem opaca. Se a taxa obrigatória estiver ausente, uma projeção do resultado MCP é:

{
  "isError": true,
  "structuredContent": {
    "kind": "input-validation-error",
    "validated": false,
    "missing": ["requestsPerSecond"],
    "issues": [{ "path": ["requestsPerSecond"], "code": "invalid_type" }]
  }
}

O resultado completo também tem um bloco de texto legível. Para uma taxa negativa, missing fica vazio e issues aponta o campo inválido. Caminhos aninhados podem identificar campos de um item sem depender da redação da mensagem.

A especificação MCP citada define resultados estruturados e schemas de saída. Conteúdo estruturado produzido pelo servidor não garante o texto que um modelo escreverá depois. Aqui, os testes verificam a descoberta e as chamadas pelo SDK real. O erro estruturado inclui caminhos e códigos, não os valores recebidos; nomes de campos também podem revelar contexto, então use apenas dados sintéticos no endpoint público.

6. Verifique o pacote publicado pelo protocolo

Baixe o ZIP do laboratório, extraia em um diretório descartável novo e localize a pasta lab/. Ela contém dependências fixadas, lockfile e acceptance.test.mjs. Execute:

cd lab
npm ci --ignore-scripts --no-fund --no-audit
npm test

O teste inicia o servidor publicado por stdio com ferramentas de conta desabilitadas. Um cliente real do SDK verifica seis cenários:

| Cenário | Resultado verificado |

| --- | --- |

| Pico sem duração/payload | Saídas dependentes null e duas entradas ausentes |

| Premissas declaradas | 125 e 163, com as origens assumidas preservadas |

| Taxa obrigatória ausente | Erro estruturado apontando requestsPerSecond |

| Taxa negativa | Campo inválido, sem alegar ausência |

| Duração sem origem | caller-unspecified e cenário diário condicionado visível |

| Valores zero | Zero continua sendo dado informado |

O teste também confirma a indisponibilidade da ferramenta de identidade da conta nesse modo. As respostas sintéticas ficam em evidence/stdio-results.json; leia-as separadamente de qualquer explicação de modelo.

Em 9 de novembro de 2026, esse exercício local com o pacote publicado passou. Trata-se de um teste Node com os cenários acima, não de seis testes de carga. A suíte mais ampla do projeto 0.5.0 tem 60 testes; são escopos diferentes. Não medimos percentuais de redução de alucinação, economia, latência ou adoção.

Inicie, verifique e encerre o transporte HTTP

No terminal A, dentro de lab/, execute o servidor publicado apenas em loopback:

HOST=127.0.0.1 PORT=18787 ENABLE_AWS_ACCOUNT_TOOLS=false \
  node node_modules/moretes-aws-architect-mcp/dist/http.js

No terminal B, no mesmo diretório:

curl -fsS http://127.0.0.1:18787/health
MCP_TEST_URL=http://127.0.0.1:18787/mcp npm test

O health deve informar versão 0.5.0 e accountTools: false. As mesmas verificações agora passam por um cliente Streamable HTTP real. Stdio e HTTP local passaram em 9 de novembro; os resultados ficam separados em evidence/stdio-results.json e evidence/http-results.json. O runner rejeita destinos HTTP remotos. Se a porta estiver ocupada, encerre sua própria instância anterior ou altere a porta de forma consistente; não finalize processos de terceiros.

Para limpar, pressione Ctrl+C no terminal A e confirme que o health não alcança mais aquela instância. Quando não precisar dos pacotes, remova somente o diretório descartável que você criou, preservando as evidências necessárias à revisão. O laboratório não cria recursos AWS, portanto não existe teardown AWS a executar. O serviço público é outra implantação e tem seu próprio runbook.

Se o servidor parecer parado ao ser iniciado diretamente, ele está esperando mensagens MCP por stdio: use o cliente ou o CLI. Se os resultados divergirem, confira a versão instalada e o lockfile. Se a IDE esconder o conteúdo estruturado, inspecione a trilha real de ferramentas em vez de tratar o texto do assistente como resposta do servidor.

7. A fronteira AWS deve ser menor que a capacidade do assistente

O caminho público é cliente → API Gateway → Lambda. A função usa DynamoDB para cotas/contadores agregados e CloudWatch para logs operacionais mínimos. O cálculo de capacidade permanece em memória: não chama Bedrock nem lê a infraestrutura do cliente.

Ferramentas autenticadas de conta são locais e opt-in. A role do runtime público está limitada aos próprios logs e à tabela de cotas/uso; não recebe credenciais de clientes. Anotações descrevem a intenção da ferramenta. O registro das ferramentas e o IAM delimitam os caminhos de implementação permitidos.

A separação permite um ciclo de validação local barato, um ponto compartilhado stateless na Lambda e uma cota hospedada que sobrevive a reinícios por estar no DynamoDB. Em troca, o endpoint público tem limites e dependências operacionais: não é um tenant isolado nem oferece SLA. Preservar null exige suporte do cliente; um formatador legado ainda pode esconder a lacuna. A superfície menor é uma escolha de engenharia, não uma recomendação de tornar pública qualquer tarefa de arquitetura.

O manifesto público permite comparar descritores, schemas de saída e anotações. Use uma baseline revisada e a versão exata. Um hash não é assinatura, auditoria de segurança nem prova de que o comportamento da implementação permaneceu igual.

Para revisar a hospedagem, consulte o template e o runbook. O script do mantenedor é intencionalmente fixado à conta do proprietário; não deve ser executado sem adaptação em outra conta. O exercício local não cria recursos. Implantar um fork revisado pode gerar consumo AWS; cotas e alertas de budget não são um limite financeiro absoluto.

Checklist de aceitação

  • Entradas opcionais ausentes continuam visíveis, com saídas dependentes null.
  • Entradas obrigatórias inválidas produzem erros estruturados.
  • Defaults e premissas mantêm origens distintas.
  • Pico e tráfego sustentado são tratados separadamente.
  • O cliente suporta resultados anuláveis e proveniência autodeclarada.
  • Os testes verificam descoberta e protocolo, além da conta numérica.
  • A superfície pública não tem caminho para credenciais de conta ou escritas de providers.
  • Evidências externas, cálculos e explicações de modelo permanecem distinguíveis.

Um schema não torna um agente confiável por si só. Ele pode tornar a incerteza visível o suficiente para revisão. O passo seguinte é conectar essa visibilidade à coleta de evidências, à aprovação do responsável e a testes medidos do workload, antes que um cenário se torne uma decisão de produção.

Referências e evidências

  • MCP: ferramentas e resultados estruturados, versão citada
  • Implementação de capacidade 0.5.0
  • Handler de validação estruturada
  • Relato de primeira utilização e respostas originais, com crédito a Pin Xiong
  • Release e verificação de produção

Para quem revisar: qual entrada ausente mudaria sua próxima decisão? Que evidência você exigiria para aceitar um valor marcado como medido? Um contraexemplo útil vale mais que um elogio.

Transparência: esta explicação foi preparada com apoio de IA. Os comandos do pacote e os cenários sintéticos foram executados; comportamento de modelos e desempenho do workload não foram medidos.

Revisão de produção pelos seis pilares

Excelência operacional

Fixe versões, inspecione a trilha real de ferramentas, retenha respostas sintéticas e revise mudanças de contrato antes de atualizar.

Segurança

Mantenha ferramentas de conta/providers fora do registro público e restrinja IAM aos próprios dados operacionais. Não envie entradas de clientes ao exercício público.

Confiabilidade

Separe requisições inválidas de cenários incompletos válidos. Lacunas permanecem explícitas; cálculo bem-sucedido não garante disponibilidade.

Eficiência de performance

Limite entradas e calcule localmente; obtenha distribuições do workload e evidências de cauda de latência antes de dimensionar dependências.

Otimização de custos

O laboratório local não cria recursos AWS. Requisições hospedadas consomem serviços; cotas e alertas de budget não são teto financeiro absoluto.

Sustentabilidade

Reutilize cálculos determinísticos locais e encerre o HTTP descartável após verificar. Não há alegação de economia ambiental medida.

Antipadrões para evitar

  • Substituir lacunas por zero ou defaults inventados.
  • Tratar o pico como tráfego diário sustentado.
  • Tratar o rótulo measured, um teste ou hash como evidência de negócio verificada independentemente.

Visão C4 do desenho

Um cliente solicita aritmética de cenário ao workbench público; operações autenticadas de conta continuam locais e opt-in.

Containers

C4

MCP client

MCP SDK / stdio or HTTP

Fornece entradas e apresenta resultados estruturados.

C4

Public AWS runtime

API Gateway / Lambda / DynamoDB / CloudWatch

API Gateway e Lambda atendem MCP stateless com armazenamento operacional restrito.

Componentes

C4

Input contract

Schema estrito, lacunas opcionais e caminhos de erro estruturados.

C4

Deterministic calculator

Calcula valores dependentes somente com as entradas disponíveis.

C4

Evidence projection

Preserva origens autodeclaradas e limites visíveis.

Veredito

Use resultados parciais tipados para tornar a incerteza revisável. Exija evidência do workload antes de aceitar uma decisão de capacidade.

#mcp#aws-lambda#ai-agents#solution-architecture#testing
Compartilhar:LinkedInWhatsAppXBaixar em Markdown
Fonte analisada: capacity_plan implementation and acceptance lab v0.5.0
Próximo passo
Agentes de IA em produção na AWSComo eu desenho, oriento e audito agentes que vão ao ar, com os números e as fontes.Ver o IA BuilderTrilha Arquiteto de IA, gratuitaFundamentos, LLMs, RAG, tools, MCP e arquitetura na AWS, em aulas curtas e interativas.Começar a trilha

Continue lendo

IA & AgentesQuatro padrões de engenharia que separam multiagente de prompt chainO Google publicou os quatro padrões de engenharia que apareceram nos vencedores do AI Agents Challenge. Nenhum deles é sobre modelo: são interface de ferramenta, mensageria assíncrona, validação estrutural e roteamento barato antes da inferência. Reviso cada um com o que muda ao levá-lo para AgentCore, EventBridge e Bedrock, e onde o protótipo do desafio não sobrevive à produção.Ler IA & AgentesMigrando agentes do GPT-5.6 Terra para o GPT-6.1 Terra no BedrockO GPT-6.1 Terra chegou ao Amazon Bedrock em 26/10/2026 com preço de token pelo menos 50% menor que o do GPT-5.6 Terra. O model card, no entanto, muda região de origem, suporte de API, cache e quota em relação ao modelo anterior. Este é o roteiro que eu seguiria para migrar um agente em produção sem descobrir essas diferenças pelo plantão.Ler IA & AgentesO agente caiu depois da mudança. Você deve repetir?A ferramenta mudou o alvo, mas o processo morreu antes de confirmar o resultado. Dois experimentos locais mostram por que um timeout não prova falha, como um recibo permite recuperar a operação e quando o estado correto ainda exige investigação.Ler
AnteriorCofre air-gapped com EBS Archive: o pré-mortem de um RTO de 72 horas
Gostou desta análise? Receba a próxima.

Deep dives de arquitetura, AWS, IA e mercado: direto no seu email. Grátis.

Sem spam · cancele quando quiser

Pergunte ao Fernando sobre isto

Uma resposta focada sobre este artigo, do meu assistente de IA, baseada no meu trabalho.

AWS Builder Center

Este artigo também está no AWS Builder Center, onde a comunidade AWS discute. Comente lá, ou aqui embaixo, eu respondo nos dois.

Discutir no Builder Center 5 0

Participe da conversa

Entre para comentar

Confirme seu e-mail para participar, você também recebe a newsletter. Sem senha.

Neste artigo
ArquiteturaWell-ArchitectedAntipadrõesC4Veredito