AWS Bedrock

O Hermes Agent suporta o Amazon Bedrock como provedor nativo. Isso te dá acesso completo ao ecossistema do Bedrock: autenticação IAM, Guardrails, perfis de inferência entre regiões e todos os modelos de base.

O Hermes roteia cada família de modelos pela API que a serve melhor:

Família de modelos	Rota de API	Por quê
Anthropic Claude	SDK da Anthropic (AnthropicBedrock)	Cache de prompt, orçamentos de raciocínio, raciocínio adaptativo — recursos que a Converse não expõe
OpenAI GPT-5.5 / GPT-5.6 (Sol, Terra, Luna)	Endpoint OpenAI Responses do Bedrock Mantle (bedrock-mantle.<region>.api.aws/openai/v1)	Estes modelos são exclusivos do Mantle — os cartões de modelo deles listam bedrock-runtime/Converse como não suportados
Todo o resto (Nova, DeepSeek, Llama, GPT-OSS, …)	Converse API nativa (bedrock-runtime)	Conjunto completo de recursos do Bedrock: Guardrails, perfis de inferência, streaming

As três rotas compartilham a mesma cadeia de credenciais da AWS e a mesma resolução de região — não é preciso configuração separada. As requisições ao endpoint do Mantle são autenticadas com AWS_BEARER_TOKEN_BEDROCK quando ela está definida, ou assinadas com SigV4 pela cadeia padrão de credenciais do boto3, caso contrário.

Pré-requisitos

• Credenciais da AWS — qualquer fonte suportada pela cadeia de credenciais do boto3:
  • Papel IAM de instância (EC2, ECS, Lambda — zero configuração)
  • Variáveis de ambiente AWS_ACCESS_KEY_ID + AWS_SECRET_ACCESS_KEY
  • AWS_PROFILE para SSO ou perfis nomeados
  • aws configure para desenvolvimento local
• boto3 — instale com cd ~/.hermes/hermes-agent && uv pip install -e ".[bedrock]"
• Permissões IAM — no mínimo:
  • bedrock:InvokeModel e bedrock:InvokeModelWithResponseStream (para inferência)
  • bedrock:ListFoundationModels e bedrock:ListInferenceProfiles (para descoberta de modelos)

EC2 / ECS / Lambda

Em computação da AWS, anexe um papel IAM com AmazonBedrockFullAccess e pronto. Sem chaves de API, sem configuração no .env — o Hermes detecta o papel da instância automaticamente.

Início rápido

# Instala com suporte a Bedrock
cd ~/.hermes/hermes-agent && uv pip install -e ".[bedrock]"

# Seleciona o Bedrock como seu provedor
hermes model
# → Escolha "More providers..." → "AWS Bedrock"
# → Selecione a sua região e o modelo

# Comece a conversar
hermes chat

Configuração

Depois de rodar o hermes model, o seu ~/.hermes/config.yaml vai conter:

model:
  default: us.anthropic.claude-sonnet-4-6
  provider: bedrock
  base_url: https://bedrock-runtime.us-east-2.amazonaws.com

bedrock:
  region: us-east-2

Região

Defina a região da AWS de qualquer uma destas formas (da maior prioridade para a menor):

1. bedrock.region no config.yaml
2. Variável de ambiente AWS_REGION
3. Variável de ambiente AWS_DEFAULT_REGION
4. Padrão: us-east-1

Guardrails

Para aplicar os Guardrails do Amazon Bedrock a todas as invocações de modelo:

bedrock:
  region: us-east-2
  guardrail:
    guardrail_identifier: "abc123def456"  # Do console do Bedrock
    guardrail_version: "1"                # Número da versão ou "DRAFT"
    stream_processing_mode: "async"       # "sync" ou "async"
    trace: "disabled"                     # "enabled", "disabled" ou "enabled_full"

Descoberta de modelos

O Hermes descobre automaticamente os modelos disponíveis pelo plano de controle do Bedrock. Você pode personalizar a descoberta:

bedrock:
  discovery:
    enabled: true
    provider_filter: ["anthropic", "amazon"]  # Mostra só estes provedores
    refresh_interval: 3600                     # Cache por 1 hora

Cache de prompt (cachePoint)

O Hermes aplica cache de prompt automaticamente no caminho da Converse API do Bedrock, inserindo marcadores cachePoint depois do prompt de sistema, das definições de ferramenta e da mensagem mais recente. Como mandar um bloco cachePoint para um modelo que não o suporta levanta uma ValidationException, os marcadores só são acrescentados para modelos numa lista de permitidos conhecidamente boa (IDs de modelo da Anthropic Claude e da Amazon Nova); modelos desconhecidos ficam sem marcador de cache por padrão. Os modelos Claude normalmente usam o caminho do SDK AnthropicBedrock, que tem o próprio cache de prompt — o caminho cachePoint da Converse cobre a Nova e o recuo de Claude por token bearer. Nenhuma configuração é necessária; leituras/escritas de cache aparecem na contabilidade de uso.

Sondagem da janela de contexto

Para modelos cuja janela de contexto não está na tabela estática do Hermes, o Hermes pode sondar o limite real mandando requisições grandes demais em faixas fixas (~1,3 M e ~2,2 M tokens) e lendo o maximum reportado no erro de validação de tamanho do Bedrock. Os valores sondados alimentam o mesmo cache de metadados da tabela estática; entradas velhas em cache que subnotificam a janela de um modelo (por exemplo, entradas semeadas antes de a janela de 1 M de um modelo virar geral) são descartadas automaticamente em favor do valor conhecido maior.

Modelos disponíveis

Os modelos do Bedrock usam IDs de perfil de inferência para invocação sob demanda. O seletor do hermes model mostra esses IDs automaticamente, com os modelos recomendados no topo:

Modelo	ID	Notas
Claude Sonnet 4.6	us.anthropic.claude-sonnet-4-6	Recomendado — melhor equilíbrio entre velocidade e capacidade
Claude Opus 4.6	us.anthropic.claude-opus-4-6-v1	O mais capaz
Claude Haiku 4.5	us.anthropic.claude-haiku-4-5-20251001-v1:0	O Claude mais rápido
OpenAI GPT-5.6 Sol	openai.gpt-5.6-sol	Modelo de fronteira da OpenAI (via Bedrock Mantle)
OpenAI GPT-5.6 Terra	openai.gpt-5.6-terra	Equilibrado (via Bedrock Mantle)
OpenAI GPT-5.6 Luna	openai.gpt-5.6-luna	Rápido, em conta (via Bedrock Mantle)
OpenAI GPT-5.5	openai.gpt-5.5	Carro-chefe anterior da OpenAI (via Bedrock Mantle)
Amazon Nova Pro	us.amazon.nova-pro-v1:0	O carro-chefe da Amazon
Amazon Nova Micro	us.amazon.nova-micro-v1:0	O mais rápido e mais barato
DeepSeek V3.2	deepseek.v3.2	Modelo aberto forte
Llama 4 Scout 17B	us.meta.llama4-scout-17b-instruct-v1:0	O mais recente da Meta

Inferência entre regiões

Modelos com o prefixo us. usam perfis de inferência entre regiões, que oferecem melhor capacidade e contingência automática entre regiões da AWS. Modelos com o prefixo global. roteiam por todas as regiões disponíveis no mundo. Os IDs de modelo openai.* da OpenAI são servidos pelo Bedrock Mantle na região configurada e não usam prefixos de perfil de inferência.

Trocar de modelo no meio da sessão

Use o comando /model durante uma conversa:

/model us.amazon.nova-pro-v1:0
/model deepseek.v3.2
/model us.anthropic.claude-opus-4-6-v1

Diagnóstico

hermes doctor

O doctor confere:

• Se as credenciais da AWS estão disponíveis (variáveis de ambiente, papel IAM, SSO)
• Se o boto3 está instalado
• Se a API do Bedrock está alcançável (ListFoundationModels)
• Quantos modelos estão disponíveis na sua região

Gateway (plataformas de mensagens)

O Bedrock funciona com todas as plataformas de gateway do Hermes (Telegram, Discord, Slack, Feishu etc.). Configure o Bedrock como seu provedor e depois suba o gateway normalmente:

hermes gateway setup
hermes gateway start

O gateway lê o config.yaml e usa a mesma configuração de provedor do Bedrock.

Diagnóstico de problemas

"No API key found" / "No AWS credentials"

O Hermes procura credenciais nesta ordem:

1. AWS_BEARER_TOKEN_BEDROCK
2. AWS_ACCESS_KEY_ID + AWS_SECRET_ACCESS_KEY
3. AWS_PROFILE
4. Metadados de instância EC2 (IMDS)
5. Credenciais de contêiner ECS
6. Papel de execução do Lambda

Se nenhuma for encontrada, rode aws configure ou anexe um papel IAM à sua instância de computação.

"Invocation of model ID ... with on-demand throughput isn't supported"

Use um ID de perfil de inferência (com o prefixo us. ou global.) em vez do ID pelado do modelo de base. Por exemplo:

• ❌ anthropic.claude-sonnet-4-6
• ✅ us.anthropic.claude-sonnet-4-6

"ThrottlingException"

Você bateu no limite de taxa por modelo do Bedrock. O Hermes tenta de novo automaticamente, com recuo. Para aumentar os limites, peça um aumento de cota no console do AWS Service Quotas.

Implantação na AWS com um clique

Para uma implantação totalmente automatizada em EC2 com CloudFormation:

sample-hermes-agent-on-aws-with-bedrock — cria VPC, papel IAM, instância EC2 e configura o Bedrock automaticamente. Implante em qualquer região com um clique.

---