Hermes Agent 接入 AWS Bedrock：云上大模型服务集成指南

Hermes Agent 原生支持 Amazon Bedrock 作为推理提供者，使用的是 Converse API 而非 OpenAI 兼容端点。这意味着你可以完整接入 Bedrock 生态：IAM 认证、Guardrails 内容防护、跨区域推理配置，以及所有基础模型。

前置条件

• AWS 凭证 — 支持 boto3 凭证链中的任意来源：
  • IAM 实例角色（EC2、ECS、Lambda — 零配置）
  • AWS_ACCESS_KEY_ID + AWS_SECRET_ACCESS_KEY 环境变量
  • AWS_PROFILE 用于 SSO 或命名配置文件
  • aws configure 用于本地开发
• boto3 — 通过 pip install hermes-agent[bedrock] 安装
• IAM 权限 — 至少需要：
  • bedrock:InvokeModel 和 bedrock:InvokeModelWithResponseStream（用于推理）
  • bedrock:ListFoundationModels 和 bedrock:ListInferenceProfiles（用于模型发现）

EC2 / ECS / Lambda 提示：在 AWS 计算资源上，只需附加一个带有 AmazonBedrockFullAccess 的 IAM 角色即可，无需 API 密钥，无需 .env 配置 — Hermes 会自动检测实例角色。

快速开始

# 安装 Bedrock 支持
pip install hermes-agent[bedrock]

# 选择 Bedrock 作为提供者
hermes model
# → 选择 "More providers..." → "AWS Bedrock"
# → 选择区域和模型

# 开始对话
hermes chat

配置说明

运行 hermes model 后，~/.hermes/config.yaml 中会包含以下配置：

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

区域设置

通过以下方式设置 AWS 区域（优先级从高到低）：

1. config.yaml 中的 bedrock.region
2. AWS_REGION 环境变量
3. AWS_DEFAULT_REGION 环境变量
4. 默认值：us-east-1

Guardrails 内容防护

要将 Amazon Bedrock Guardrails 应用于所有模型调用：

bedrock:
  region: us-east-2
  guardrail:
    guardrail_identifier: "abc123def456"  # 来自 Bedrock 控制台
    guardrail_version: "1"                # 版本号或 "DRAFT"
    stream_processing_mode: "async"       # "sync" 或 "async"
    trace: "disabled"                     # "enabled"、"disabled" 或 "enabled_full"

模型发现

Hermes 通过 Bedrock 控制平面自动发现可用模型。你可以自定义发现行为：

bedrock:
  discovery:
    enabled: true
    provider_filter: ["anthropic", "amazon"]  # 仅显示这些提供商
    refresh_interval: 3600                     # 缓存 1 小时

可用模型

Bedrock 模型使用推理配置文件 ID 进行按需调用。hermes model 选择器会自动展示这些模型，推荐模型排在顶部：

跨区域推理：前缀为 us. 的模型使用跨区域推理配置文件，提供更好的容量和跨 AWS 区域的自动故障转移。前缀为 global. 的模型会在全球所有可用区域间路由。

会话中切换模型

在对话中使用 /model 命令：

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

诊断工具

hermes doctor

诊断工具会检查以下内容：

• AWS 凭证是否可用（环境变量、IAM 角色、SSO）
• boto3 是否已安装
• Bedrock API 是否可达（ListFoundationModels）
• 当前区域可用模型数量

网关（消息平台集成）

Bedrock 支持所有 Hermes 网关平台（Telegram、Discord、Slack、飞书等）。配置 Bedrock 作为提供者后，正常启动网关即可：

hermes gateway setup
hermes gateway start

网关会读取 config.yaml 并使用相同的 Bedrock 提供者配置。

常见问题排查

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

Hermes 按以下顺序检查凭证：

1. AWS_BEARER_TOKEN_BEDROCK
2. AWS_ACCESS_KEY_ID + AWS_SECRET_ACCESS_KEY
3. AWS_PROFILE
4. EC2 实例元数据（IMDS）
5. ECS 容器凭证
6. Lambda 执行角色

如果均未找到，请运行 aws configure 或为计算实例附加 IAM 角色。

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

请使用推理配置文件 ID（带有 us. 或 global. 前缀）而非裸基础模型 ID。例如：

• :x: anthropic.claude-sonnet-4-6
• :white_check_mark: us.anthropic.claude-sonnet-4-6

"ThrottlingException"

你已触达 Bedrock 单模型速率限制。Hermes 会自动带退避重试。要提高限制，请在 AWS Service Quotas 控制台申请配额提升。

一键 AWS 部署

如需在 EC2 上通过 CloudFormation 实现全自动化部署：

sample-hermes-agent-on-aws-with-bedrock — 自动创建 VPC、IAM 角色、EC2 实例并配置 Bedrock。支持在任意区域一键部署。