PaulKnauer/strands-agents-demo
GitHub: PaulKnauer/strands-agents-demo
一个基于 Strands Agents SDK 与 AWS AgentCore 的 AI Agent 最小化参考实现，内置完整的 NIST AI RMF 合规层，涵盖审计日志、Guardrails 防护、红队 CI 和监控仪表板。
Stars: 1 | Forks: 0
# strands-agents-demo
这是一个使用 [Strands Agents SDK](https://strandsagents.com) 构建并部署到 [AWS AgentCore](https://aws.amazon.com/bedrock/agentcore/) 的 AI Agent 最小化、可 Fork 的参考实现。该 Agent 根据出生日期计算一个人已经活了多少天——这是一个刻意简化的用例，旨在让关注点集中在框架模式上，而非业务逻辑。
本项目还附带完整的 **NIST AI RMF 合规层**（Epic 4）——包括治理文档、审计日志、Bedrock Guardrails、自动化红队 CI 以及 CloudWatch 合规仪表板。请参阅下文的 [NIST AI RMF 合规性](#nist-ai-rmf-compliance)。
## 本项目演示的内容
**Agent 模式：**
| 模式 | 位置 |
|---------|-------|
| `@tool` 装饰器 —— 定义 LLM 可调用的自定义工具 | `agent.py` |
| 通过环境变量切换模型提供者（Bedrock ↔ Gemini，无需修改代码） | `agent.py`, `.env.example` |
| 使用 Strands `Agent()` 的对话式 REPL 循环 | `agent.py` |
| 一键 AgentCore 部署及 IAM 配置 | `deploy/deploy.py` |
| 自动化的工具调用可观测性 —— 零自定义日志代码 | AgentCore 控制台 |
| 单文件 Agent，只需修改一个文件即可 Fork | `agent.py` |
**NIST AI RMF 负责 AI 模式：**
| 模式 | 位置 |
|---------|-------|
| AI 系统卡、风险登记册和治理章程 | `docs/` |
| 审计日志钩子 —— 通过 Strands 生命周期记录 JSONL 工具调用轨迹 | `compliance/hooks.py` |
| Bedrock Guardrails —— PII 脱敏、Prompt 注入防御、内容过滤 | `deploy/guardrail.yaml` |
| 自动化红队 CI —— 确定性安全边界测试 + promptfoo 对抗性探测 | `tests/unit/test_safety_boundaries.py`, `compliance/promptfoo-redteam.yaml` |
| CloudWatch 合规仪表板 —— Guardrails 拦截率 + 审计轨迹 | `deploy/create_dashboard.py` |
## 目录
- [前置条件](#prerequisites)
- [本地设置](#local-setup)
- [VS Code 调试](#vs-code-debugging)
- [AgentCore 部署](#agentcore-deployment)
- [NIST AI RMF 合规性](#nist-ai-rmf-compliance)
- [项目结构](#project-structure)
- [工作原理](#how-it-works)
- [Make 目标](#make-targets)
- [故障排除](#troubleshooting)
- [贡献指南](#contributing)
## 前置条件
**本地运行所需：**
- Python 3.11+ ([下载](https://www.python.org/downloads/))
- 启用了 Amazon Bedrock 的 AWS 账户
- 在 `us-east-1` 区域获得 **`anthropic.claude-3-haiku-20240307-v1:0`** 的 Bedrock 模型访问权限
_(控制台 → Amazon Bedrock → 模型访问权限 → 请求访问权限)_
- 已配置 AWS 凭证 —— 使用 `aws configure` (CLI) 或环境变量：
export AWS_ACCESS_KEY_ID=...
export AWS_SECRET_ACCESS_KEY=...
**AgentCore 部署的额外要求：**
- 已安装并配置 AWS CLI
- 具有以下权限的 IAM 用户/角色：
- `bedrock-agentcore-control:*`
- `s3:CreateBucket`, `s3:PutObject`, `s3:HeadBucket`, `s3:PutEncryptionConfiguration`
- `iam:CreateRole`, `iam:GetRole`, `iam:PutRolePolicy`
- `sts:GetCallerIdentity`
**可选（仅用于 Gemini 备用方案）：**
- Google AI Studio API 密钥 ([免费获取](https://aistudio.google.com/apikey))
## 本地设置
```
# 1. 克隆仓库
git clone https://github.com/PaulKnauer/strands-agents-demo.git
cd strands-agents-demo
# 2. 创建并激活虚拟环境
python -m venv venv
source venv/bin/activate # macOS / Linux
# venv\Scripts\activate # Windows
# 3. 安装依赖
pip install -r requirements.txt
# 4. 配置环境变量
cp .env.example .env
```
编辑 `.env` 并填入你的值：
```
MODEL_PROVIDER=bedrock
MODEL_ID=anthropic.claude-3-haiku-20240307-v1:0
AWS_REGION=us-east-1
AGENT_NAME=age-in-days-demo
```
```
# 5. 运行 agent
python agent.py
```
**交互示例：**
```
Age-in-Days Agent (type 'exit' to quit)
You: I was born on 14th March 1990
Agent: You were born 13,149 days ago! That's quite a journey — you've
lived through some remarkable decades. 🎂
You: exit
```
**快捷方式：** `make install && make run`
## VS Code 调试
按下 **F5** —— 包含的 `.vscode/launch.json` 会启动 `agent.py`，并自动附加调试器及加载 `.env`。无需手动 `export`。
验证方法：在 `get_today_date()` 内部设置断点，按 F5，输入出生日期，执行过程将在断点处暂停。
## AgentCore 部署
AgentCore 将 Agent 作为托管的云 Runtime 运行，并提供自动化的工具调用追踪。部署脚本会配置所有 AWS 基础设施 —— 无需在控制台操作。
**步骤 1：** 首先确认本地 Agent 可以正常工作（完成 [本地设置](#local-setup)）。
**步骤 2：** 部署：
```
python deploy/deploy.py
# 或：make deploy
```
脚本会执行 5 个步骤，并在完成时打印端点 URL：
```
🚀 Deploying agent 'age_in_days_demo' to AgentCore in us-east-1...
Step 1/5: Ensuring S3 bucket...
Created S3 bucket: bedrock-agentcore-code-123456789012-us-east-1
Step 2/5: Packaging and uploading agent code...
Uploaded 4,231,847 bytes → s3://...
Step 3/5: Ensuring IAM execution role...
Created IAM role: AmazonBedrockAgentCoreRuntime_age_in_days_demo
Step 4/5: Deploying AgentCore runtime (idempotent)...
Creating new AgentCore runtime 'age_in_days_demo'...
Step 5/5: Waiting for runtime to be ready...
Waiting for agent to be ready ........... ✅
🎉 Agent deployed successfully!
Endpoint URL: https://bedrock-agentcore.us-east-1.amazonaws.com/runtimes/.../invocations
```
**步骤 3：** 验证已部署的 Agent 能够响应：
```
python deploy/verify.py
# 或：make verify
```
预期输出：
```
Verifying deployed agent 'age_in_days_demo' in us-east-1...
Runtime ARN: arn:aws:bedrock-agentcore:...
Test prompt: "I was born on 14th March 1990"
Agent responded (in 3.2s):
You were born 13,149 days ago! ...
Verification complete.
Next: open the AgentCore console to confirm get_today_date tool traces are visible.
```
**步骤 4：** 在 [AgentCore 控制台](https://console.aws.amazon.com/bedrock-agentcore/) → 你的 Agent → 调用历史 中查看工具追踪。每次 `get_today_date` 调用都会追踪其输入和输出 —— 无需编写日志代码。
**清理**（完成后）：
```
python deploy/teardown.py
# 或：make teardown
```
## NIST AI RMF 合规性
本项目的 Epic 4 实现了完整的 [NIST AI 风险管理框架 (AI RMF 1.0)](https://airc.nist.gov/RMF) 合规层。四个 NIST AI RMF 职能如下所述：
| NIST 职能 | 子类别 | 制品 | `make` 命令 |
|---|---|---|---|
| **GOVERN（治理）** | 1.1, 1.3, 1.4, 1.7, 6.1 | [`docs/governance-charter.md`](docs/governance-charter.md) —— 角色、风险容忍度、审查周期 | — |
| **GOVERN（治理）** | 1.1, 1.3, 1.4, 6.1 | [`docs/ai-system-card.md`](docs/ai-system-card.md) —— 系统目的、危害类别、第三方组件 | — |
| **MAP（映射）** | 1.1, 2.2, 5.1 | [`docs/risk-register.md`](docs/risk-register.md) —— 风险识别和缓解状态 | — |
| **MAP（映射）** | 1.1, 2.2 | [`docs/ai-system-card.md`](docs/ai-system-card.md) —— 数据流和危害分析 | — |
| **MEASURE（度量）** | 2.4 | [`deploy/guardrail.yaml`](deploy/guardrail.yaml) + [`deploy/create_dashboard.py`](deploy/create_dashboard.py) —— Guardrails 拦截率监控 | `make dashboard` |
| **MEASURE（度量）** | 2.5 | [`compliance/hooks.py`](compliance/hooks.py) + [`deploy/create_dashboard.py`](deploy/create_dashboard.py) —— 工具调用审计轨迹 | `make dashboard` |
| **MANAGE（管理）** | 1.3, 2.2 | [`deploy/guardrail.yaml`](deploy/guardrail.yaml) —— Bedrock Guardrails（PII 脱敏、Prompt 注入防御、内容过滤） | `make deploy` |
| **MANAGE（管理）** | 2.4 | [`docs/risk-register.md`](docs/risk-register.md) + CloudWatch 仪表板 —— 事件追踪和审计轨迹 | `make dashboard` |
| **MANAGE（管理）** | 4.1 | [`docs/ai-system-card.md`](docs/ai-system-card.md) —— 人工监督机制 | — |
| **MEASURE（度量）** | 2.4, 2.5 (自动化) | [`tests/unit/test_safety_boundaries.py`](tests/unit/test_safety_boundaries.py), [`compliance/promptfoo-redteam.yaml`](compliance/promptfoo-redteam.yaml) —— 红队 CI | `make redteam` |
**关键合规文件：**
- `docs/` —— 三份治理文档（系统卡、风险登记册、治理章程）
- `compliance/hooks.py` —— `AuditLoggingHook` 附加到 Strands 生命周期，并在每次工具调用时发出 JSONL 审计记录
- `deploy/guardrail.yaml` —— Bedrock Guardrails 策略，应用于本地 REPL (`agent.py`) 和 AgentCore 云 Runtime (`deploy/app.py`)
- `deploy/create_dashboard.py` —— 部署 `NIST-RMF-AgentCompliance` CloudWatch 仪表板；在部署 Agent 后运行 `make dashboard`
## 项目结构
```
strands-agents-demo/
│
├── agent.py # The agent — @tool, model config, Agent(), REPL loop
│ # < 150 lines; local development only (Strands SDK)
│
├── requirements.txt # Pinned dependencies
│
├── .env.example # Environment variable template — copy to .env
│
├── deploy/
│ ├── app.py # Cloud runtime entrypoint (boto3 direct, no Strands SDK)
│ ├── deploy.py # Provisions S3, IAM role, AgentCore runtime (idempotent)
│ ├── verify.py # Post-deploy smoke test — invokes the live endpoint
│ ├── teardown.py # Deletes AgentCore runtime, IAM role, and CloudWatch dashboard
│ ├── guardrail.yaml # Bedrock Guardrails policy — PII redaction, prompt-injection defence
│ ├── create_dashboard.py # CloudWatch NIST-RMF-AgentCompliance dashboard (idempotent)
│ └── start.sh # (unused locally) dependency install + launch for runtime
│
├── compliance/
│ ├── hooks.py # AuditLoggingHook — JSONL tool-call audit trail (NIST MEASURE-2.5)
│ └── promptfoo-redteam.yaml # Adversarial probe suite for red-team CI
│
├── docs/
│ ├── ai-system-card.md # System card — purpose, data flows, harm categories (GOVERN, MAP)
│ ├── risk-register.md # Risk register — identified risks and mitigations (MAP)
│ └── governance-charter.md # Governance charter — roles, risk tolerance, review cadence (GOVERN)
│
├── tests/
│ ├── unit/ # Unit tests for agent.py, app.py, deploy scripts, compliance hooks
│ ├── integration/ # Integration tests for the agentic tool-calling loop
│ └── evals/ # Deterministic behavioural contract tests
│
├── .vscode/
│ ├── launch.json # F5 debug config — loads .env automatically
│ └── extensions.json # Recommended VS Code extensions
│
├── Makefile # Shortcuts: install, run, deploy, verify, test, lint, redteam, dashboard
│
├── _bmad/ # BMAD framework core — agents, skills, workflows (not agent code)
└── _bmad-output/ # BMAD planning artifacts (PRD, architecture, stories)
# Not part of the agent implementation
```
### 为什么有两个 Agent 的 Python 文件？
`agent.py` 使用 **Strands Agents SDK** —— 这是简洁的高级 API，使本 Demo 易读且易于 Fork。它作为本地交互式 REPL 运行。
`deploy/app.py` 在 AgentCore 云 Runtime 中直接使用 **boto3**。由于 Strands SDK 无法在 AgentCore 30 秒的启动窗口内完成 pip 安装，因此 `app.py` 使用 Bedrock Converse API 重新实现了相同的 Agent 行为（相同的系统提示词和工具）。这是部署约束，而非架构偏好。
**Agent 在两个环境中的行为完全相同。** 如果你 Fork 本项目并添加工具，请同时添加到 `agent.py`（`@tool` 装饰器）和 `deploy/app.py`（`TOOLS` 列表 + `_run_agent` 中的处理程序）。
## 工作原理
```
User types: "I was born on 14th March 1990"
│
▼
REPL loop (agent.py) passes input to Strands Agent()
│
▼
Agent sends to LLM (Bedrock / Gemini) with system prompt + tool list
│
▼
LLM decides: I need today's date → calls get_today_date tool
│
▼
get_today_date() returns: "2026-03-18" ← stdlib datetime, no network call
│
▼
LLM calculates: days between 1990-03-14 and 2026-03-18 = 13,149
│
▼
LLM responds: "You were born 13,149 days ago! 🎂"
│
▼
Response printed to terminal
```
在 AgentCore（云端）中，相同的流程通过 Bedrock Converse API 在 `deploy/app.py` 内部运行。LLM 调用 `get_today_date` 的每一步都会自动捕获在 AgentCore 控制台中 —— 包括输入、输出和延迟 —— 无需编写自定义日志代码。
### 模型提供者切换
在 `.env` 中更改两个环境变量 —— 无需修改代码：
```
# Amazon Bedrock (默认)
MODEL_PROVIDER=bedrock
MODEL_ID=anthropic.claude-3-haiku-20240307-v1:0
# Google Gemini (免费层回退)
MODEL_PROVIDER=gemini
MODEL_ID=gemini-2.0-flash
GOOGLE_API_KEY=your-key-here
# 此外：pip install strands-agents[gemini]
```
## Make 目标
```
make install # Create venv and install dependencies
make run # Run the agent locally (python agent.py)
make deploy # Deploy to AgentCore (python deploy/deploy.py)
make verify # Verify deployed agent (python deploy/verify.py)
make teardown # Delete AgentCore runtime, IAM role, and CloudWatch dashboard
make dashboard # Create/update CloudWatch NIST-RMF compliance dashboard
make redteam # Run promptfoo adversarial red-team scan (requires Node.js + AWS creds)
make test # Run unit + eval tests (134 tests)
make test-unit # Unit tests only
make lint # Check formatting with black (no changes made)
make format # Auto-format all Python files with black
```
## 故障排除
**部署期间出现 `AccessDeniedException`**
你的 IAM 用户缺少权限。请检查 [前置条件](#prerequisites) 部分中所需的策略操作。参阅 [AgentCore 权限指南](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-permissions.html)。
**`ResourceNotFoundException` —— 区域错误**
AgentCore 仅在特定区域可用。请确认 `.env` 中的 `AWS_REGION=us-east-1`（或 `us-west-2`）。
**启动时出现 `KeyError: 'MODEL_PROVIDER'` 或类似错误**
`.env` 缺失或变量未设置。请运行 `cp .env.example .env` 并填写所有必需的值。
**来自 Bedrock 的模型访问错误**
你的账户必须启用 `anthropic.claude-3-haiku-20240307-v1:0`。请前往 AWS Console → Amazon Bedrock → 模型访问权限 → 找到 Claude 3 Haiku → 请求访问权限。
**`venv/bin/python: No such file or directory`**
你尚未创建虚拟环境。请先运行 `python -m venv venv && source venv/bin/activate`。
**`make verify` 失败 —— Agent 已部署但无响应**
请在 [AgentCore 控制台](https://console.aws.amazon.com/bedrock-agentcore/) 中检查 Runtime 状态。如果状态不是 `READY`，请重新运行 `make deploy`。如果显示 `FAILED`，请检查控制台链接的 CloudWatch 日志。
**部署成功但验证超时**
默认验证超时为 30 秒。请在 `.env` 中设置 `VERIFY_TIMEOUT_SECONDS=60` 并重试。
## 贡献指南
1. 所有 Python 文件必须通过 `make lint`（black 格式化）。
2. 所有测试必须通过：`make test`。
3. 切勿提交 `.env`、AWS 凭证或 API 密钥。
4. 添加新工具时：同时更新 `agent.py`（`@tool` 装饰器）和 `deploy/app.py`（`TOOLS` 列表 + `_run_agent` 中的工具处理程序）。
5. 保持 `agent.py` 在 150 行以内 —— 如果超出，请提取到 `tools.py`。
6. 本仓库使用 [BMAD 方法论](https://github.com/bmad-agents/bmad-method) —— 在实施更改前请使用 `/bmad-create-story`，在提交前请使用 `/bmad-code-review`。
标签：AI治理, API集成, AWS AgentCore, AWS Bedrock, Bedrock Guardrails, CISA项目, CloudWatch Dashboard, DevSecOps, IAM 权限, LLM 应用, NIST AI RMF, PII 脱敏, Python, Strands Agents SDK, 上游代理, 人工智能, 人工智能安全, 参考实现, 可观测性, 合规性, 审计日志, 年龄计算器, 开源框架, 持续集成, 提示词注入防御, 无后门, 生成式 AI, 用户模式Hook绕过, 逆向工具