🏛️ Arquitetura AWS — API Gateway → Router → AgentCore
O sample expõe um único endpoint HTTPS via API Gateway que recebe webhooks de Telegram, Slack, Discord e Feishu. O Lambda router normaliza o payload e invoca o AgentCore Runtime, onde o main.py do Hermes roda dentro de uma microVM Firecracker dedicada.
┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ Telegram │ │ Slack │ │ Discord │ │ Feishu │
└──────┬───────┘ └──────┬───────┘ └──────┬───────┘ └──────┬───────┘
│ webhook │ events │ interactions │ event
└───────────┬──────┴──────────┬───────┴──────────┬───────┘
▼ ▼ ▼
┌─────────────────────────────────────────────┐
│ Amazon API Gateway (HTTP API) │
│ /telegram /slack /discord /feishu │
└────────────────────┬────────────────────────┘
│ POST + signature
▼
┌─────────────────────────────────────────────┐
│ Lambda Router (Node 20 / Python) │
│ - verify signature - normalize payload │
│ - load S3 state - invoke AgentCore │
└────────────────────┬────────────────────────┘
│ InvokeAgentRuntime
▼
┌─────────────────────────────────────────────┐
│ Bedrock AgentCore Runtime │
│ ┌──────────────────────────────────────┐ │
│ │ Firecracker microVM (per session) │ │
│ │ └─► main.py (Hermes Agent) │ │
│ │ ├─► tools (shell/py) │ │
│ │ └─► Bedrock LLM API │ │
│ └──────────────────────────────────────┘ │
└────────────────────┬────────────────────────┘
│ persist state
▼
┌─────────────────┐
│ S3 bucket │
│ sessions/... │
└─────────────────┘💡 Por que essa arquitetura
- •Um endpoint, N canais: adicionar WhatsApp = só implementar adapter no router.
- •Pagamento por uso real: Lambda + AgentCore só cobram quando há mensagem.
- •IAM nativo: roles separadas por componente — router NÃO acessa o bucket todo.
- •Observabilidade unificada: tudo em CloudWatch com trace ID cruzando os 3 serviços.
🔥 Firecracker microVMs — 1 VM por sessão
O AgentCore Runtime usa o mesmo Firecracker que roda Lambda e Fargate por trás — mas o expõe como ambiente persistente por sessão. Cada usuário ganha uma microVM dedicada com isolamento de hypervisor (KVM), cold-start em ~125ms e snapshot/restore nativo.
✓ Modelo correto
- ✓1 microVM por sessão de usuário
- ✓Snapshot ao final, restore na próxima msg
- ✓Idle TTL configurável (default 15min)
- ✓Limite hard de CPU/MEM por VM
✗ Anti-padrões
- ✗1 VM compartilhada entre usuários (vaza estado)
- ✗Manter VM viva 24/7 — perde a vantagem de custo
- ✗Persistir creds dentro da VM (fica no snapshot)
- ✗VM sem limite — bug de loop come orçamento
💡 Dica
Use o sample como referência de mapeamento sessão→VM, não copie idle TTL às cegas. Para chatbot conversacional, 15min é alto; para agente de longa execução (CI bot), 60min faz sentido. Ajuste por canal.
📦 CDK em 4 fases — como o sample organiza
O sample divide a infra em 4 stacks CDK independentes. Cada um pode ser destruído e recriado sem tocar nos outros — você itera nas integrações sem refazer VPC.
NetworkStack
VPC, subnets privadas, NAT, VPC endpoints para Bedrock e S3.
Exporta vpcId e privateSubnetIds para os stacks seguintes.
IamStack
Roles separadas: RouterLambdaRole, AgentCoreExecutionRole, StateBucketReadWriteRole.
Princípio de menor privilégio — router não pode invocar Bedrock, só AgentCore pode.
AgentCoreStack
Recurso AWS::BedrockAgentCore::Runtime com imagem do Hermes, S3 bucket de estado, KMS key.
Aqui mora o main.py empacotado — versione com tag git.
IntegrationsStack
API Gateway HTTP API + Lambda router + Secrets Manager (tokens Telegram/Slack/Discord/Feishu).
É o stack que você mexe ao adicionar canal novo — sem tocar os outros 3.
# Snippet CDK (TypeScript) — AgentCoreStack simplificado
import { Stack, StackProps, Duration } from 'aws-cdk-lib';
import { Bucket, BucketEncryption } from 'aws-cdk-lib/aws-s3';
import { CfnRuntime } from 'aws-cdk-lib/aws-bedrockagentcore';
export class AgentCoreStack extends Stack {
constructor(scope: Construct, id: string, props: StackProps) {
super(scope, id, props);
const stateBucket = new Bucket(this, 'HermesState', {
encryption: BucketEncryption.KMS_MANAGED,
versioned: true,
lifecycleRules: [{ expiration: Duration.days(90) }],
});
new CfnRuntime(this, 'HermesRuntime', {
runtimeName: 'hermes-agent-prod',
containerImage: `${ecrRepo.repositoryUri}:${imageTag}`,
executionRoleArn: agentRole.roleArn,
idleTimeoutSeconds: 900,
environmentVariables: {
HERMES_STATE_BUCKET: stateBucket.bucketName,
BEDROCK_MODEL_ID: 'anthropic.claude-3-5-sonnet-20241022-v2:0',
},
});
}
}
# deploy
$ npm ci && npm run build
$ npx cdk deploy --all --require-approval never💾 Estado em S3 — persistência entre invocações
Como microVMs são efêmeras por design, o sample persiste tudo que precisa sobreviver entre mensagens em um bucket S3 particionado por user_id/session_id: histórico de conversa, memórias de longo prazo, arquivos gerados pelo agente.
# layout do bucket
hermes-state-prod/
├── sessions/
│ └── telegram/
│ └── user_123456/
│ └── session_abc/
│ ├── history.jsonl # mensagens
│ ├── memory.json # facts persistentes
│ └── workspace/ # arquivos do agente
│ ├── output.csv
│ └── analysis.png
└── snapshots/
└── user_123456/
└── vm_state.bin # snapshot Firecracker📊 Padrão de persistência
- history.jsonl — append-only, lido inteiro no início da sessão
- memory.json — sobrescrito a cada turno, contém facts extraídos
- workspace/ — sincronizado bidirecionalmente (download início, upload fim)
- Lifecycle: sessions/* → IA após 30d, Glacier após 90d, expira em 365d
- KMS: bucket key encryption ativo (1 chamada KMS por sessão, não por objeto)
🚪 Lambda Router — multi-canal serverless
O router é a peça mais reutilizável do sample: uma Lambda Node.js que recebe webhooks dos 4 canais, valida assinatura, normaliza para um schema interno e invoca o AgentCore. Adicionar WhatsApp = ~80 linhas no router, zero mudança no resto.
// router.ts (estrutura simplificada do sample)
import { verifyTelegram, verifySlack, verifyDiscord, verifyFeishu } from './adapters';
import { invokeAgentRuntime } from './agentcore';
export async function handler(event: APIGatewayProxyEventV2) {
const channel = event.rawPath.replace('/', ''); // telegram | slack | ...
const adapter = adapters[channel];
// 1. verifica assinatura (HMAC ou OAuth)
if (!adapter.verify(event)) return { statusCode: 401 };
// 2. normaliza payload
const msg = adapter.normalize(event);
// { channel, userId, sessionId, text, attachments }
// 3. invoca AgentCore (async se demorado)
const result = await invokeAgentRuntime({
sessionId: msg.sessionId,
input: msg.text,
metadata: { channel: msg.channel, userId: msg.userId },
});
// 4. responde de volta no canal
return adapter.reply(msg, result.output);
}💡 Dica de produção
Mensagens longas (treino de modelo, scraping pesado) NÃO devem responder síncrono no webhook. Use InvokeAsync + DLQ + responda "processando..." em <3s para evitar timeout do Telegram/Slack (que retentam após 5-10s).
💰 Custos AWS — estimativa real para 1k usuários/mês
Premissa de cálculo: 1.000 usuários ativos mensais, 30 msgs/usuário/mês = 30k invocações, sessão média de 90s, região us-east-1, modelo Claude 3.5 Sonnet via Bedrock.
📊 Breakdown de custo mensal estimado
| Componente | Volume | Preço | Total |
|---|---|---|---|
| API Gateway HTTP API | 30k req | $1.00/M | $0.03 |
| Lambda Router | 30k × 200ms × 256MB | $0.20/M + GB-s | $0.18 |
| AgentCore Runtime | 30k × 90s × 1vCPU/2GB | ~$0.0001/s | $270.00 |
| Bedrock Claude 3.5 Sonnet | ~600M input + 60M output | $3 / $15 per M | $2.700,00 |
| S3 storage + requests | ~50GB + 200k req | $0.023/GB + req | $1.80 |
| CloudWatch logs | ~30GB ingestion | $0.50/GB | $15.00 |
| KMS | 30k requests | $0.03/10k | $0.09 |
| TOTAL estimado | ~$2.987 / mês | ||
O custo é dominado pelo LLM (~90%). AgentCore Runtime é <10% — otimize prompts antes de mexer em infra.
⚠️ Quotas AWS que vão te morder
- • Bedrock TPM: limite default de tokens/min é apertado — peça aumento ANTES de lançar
- • AgentCore concurrent sessions: default ~100; precisa raise para multi-tenant sério
- • Lambda concurrent executions: 1000 por região por default
- • API Gateway burst: 5000 RPS — webhook de canal viral satura sem rate limit
💡 Dica — teste com LocalStack antes
Antes de queimar dólares na AWS real, suba o stack inteiro localmente com LocalStack:
$ docker run -d -p 4566:4566 localstack/localstack
$ export AWS_ENDPOINT_URL=http://localhost:4566
$ npx cdk bootstrap --profile localstack
$ npx cdk deploy --all --profile localstackLocalStack Pro emula AgentCore e Bedrock; a versão Community emula só Lambda/S3/API GW — já dá pra testar o router e o S3 layout.
✅ Resumo do Módulo
Próximo módulo:
5.3 — 📡 Observabilidade em produção: OpenTelemetry, Grafana, SLOs e alertas para enxergar dentro do Hermes em prod.