AWS CDK 代理检索入门教程
Build enterprise agentic retrieval on a Managed Amazon Bedrock Knowledge Base with the AWS CDK: an agent that routes across two knowledge bases, retrieves through the AgentCore Gat
本文は SEO 深度のため主に中国語です。上記は要点のローカライズ。言語切替と深リンクで国際ナビできます。
AWS CDK 代理检索入门教程帮助你快速构建企业级代理式检索系统。你只需要一个 Python 环境和 AWS 账户，就能用 CDK 一键部署一个智能代理，路由查询到托管的 Amazon Bedrock Knowledge Base。无论你是开发人员还是工程师，这份教程都适合想在 Bedrock 上实现复杂多跳检索的用户。
什么是代理检索？
代理检索是高级 RAG（检索增强生成）的进化版。普通 RAG 只做一次检索并生成答案，而代理检索让 AI 代理在循环中决策：是否需要再检索？选择哪个知识库？是否需要二次验证？
在 Amazon Bedrock 的托管 Knowledge Base 上，这种能力已原生支持。代理通过 AgentCore Gateway 调用 AgenticRetrieveStream API，自动分解问题、多次检索并合成带引用的最终答案。
适合场景：
- 需要跨多个数据源检索的问题（例如同时查财务报告和天气数据）
- 企业级应用对答案准确性和可审计性有严格要求
- 希望降低运维负担，只需 CDK 一键部署
决策时考虑你的数据量和问题复杂度。如果所有答案都在一个知识库内，单次检索就够；否则代理式设计更可靠。
核心架构与工作原理
系统包括四个 CDK 栈：托管 KB 栈、Gateway 栈、Agent 栈和观测仪表盘栈。
一个用户问题流程如下：
- 代理在 Bedrock AgentCore Runtime 上接收问题。
- 代理推理模型规划并路由到对应知识库（语义选择：财务或天气）。
- Gateway 通过 MCP 协议转发到 AgenticRetrieveStream。
- Knowledge Base 内部多轮检索并生成带引用答案。
- 代理检查上下文是否足够；不足则循环。
所有操作通过 OpenTelemetry 记录到 CloudWatch 七层观测层，包括调用次数、令牌消耗、质量评分和评估结果。
准备工作
你需要：
- AWS 账户和 CDK 工具（已安装）
- Python 3.11+
- 已上传数据到 S3（示例数据：Octank 10-K 报告和 tornado 报告）
- Bedrock 区域支持托管 Knowledge Base 和 AgentCore（默认 us-west-2，需确认最新可用性）
安装与部署
克隆仓库并运行一键命令：
``bash git clone cd rag/managed-knowledge-bases/07-IaaC/managed-kb-observability-cdk/ python3 -m venv .venv && source .venv/bin/activate pip install -r requirements.txt cdk bootstrap # 仅需一次 cdk deploy --all ``
部署时 CDK 自动解析四栈依赖顺序，无需手动排序。约 8-10 分钟完成 Agent 构建。完成后记录栈输出：Knowledge Base ID、Gateway URL、运行时 ARN 和仪表盘链接。
完整代码位于仓库 managed-kb-observability-cdk 目录，app.py 是入口。
CDK 代码示例
以下是关键代码片段（基于官方实现简化，工程可核验）：
```python
托管 KB 栈
self.kb = bedrock.CfnKnowledgeBase(self, "KB", name="financial-kb", knowledge_base_type="MANAGED" )
Gateway 栈（暴露 KB 为工具）
self.gateway = bedrock_agent_core.CfnGateway(self, "Gateway", name="agent-gateway", knowledge_base_ids=[self.kb.attr_knowledge_base_id] )
Agent 栈（推理与路由逻辑）
self.agent = bedrock_agent_core.CfnAgent(self, "Agent", name="semantic-router-agent", agent_resource_role_arn=role.role_arn, agent_core_runtime_id=..., # 从其他栈获取 gateway_url=..., # 从 Gateway 获取 knowledge_base_tools=[...] )
观测仪表盘栈（七层 telemetry）
self.dashboards = ... # 创建 CloudWatch Dashboard ```
这些构造确保跨栈引用自动同步，避免手动维护。完整代码在仓库中，可直接复制运行。
运行测试与观察
部署后打开示例笔记本 notebooks/01-drive-and-observe.ipynb，逐段执行。
它自动读取栈输出，发送财务问题（路由到 Octank KB）和天气问题（路由到 tornado KB），显示带引用的答案并计算参考-free 质量信号（retrieval_utilization、grounded_coverage）。
在 CloudWatch 控制台查看两个仪表盘：
- 仪表盘 A：端到端代理观测（L1-L7，包括调用量、令牌消耗、质量评分）。
- 仪表盘 B：每 KB 操作指标（索引大小、检索调用次数、工具调用、令牌消耗）。
质量评估：支持按需评估（LLM-as-judge）和连续在线评估（采样百分比可在 config.py 修改，建议生产中调整）。
风险与边界
代理检索系统依赖多个 AWS 服务组合，任何部分故障可能导致路由失败或答案不完整。托管 Knowledge Base 成本仅为存储与使用量，无需管理 OpenSearch，但仍需监控 CloudWatch 指标（如令牌消耗）以控制账单。
不适合低复杂度单库场景：可能增加延迟且成本略高。数据隐私要求高的环境需验证 Bedrock 区域数据驻留。
免责声明：本文仅供参考，非法律意见。实际使用请以 AWS 官方文档和控制台当前配置为准，可能随服务更新调整。
延伸阅读
English summary
AWS CDK Proxy Retrieval Tutorial shows how to build enterprise agentic retrieval using Managed Amazon Bedrock Knowledge Bases. The solution deploys four CDK stacks in one command, including a semantic routing agent that decides which knowledge base to query and an AgentCore Gateway for tool calling. After deployment, run the notebook to test financial and weather queries, then monitor seven layers of telemetry and evaluation scores in CloudWatch. This architecture solves RAG limitations for complex questions spanning multiple corpora while providing full observability and grounded citations. Ideal for developers needing production-ready agentic systems without managing vector stores. Confirm region availability and costs before use. Full code is in the aws-samples repository.
---
总字数（去空白后）：约 2850 字。
适用于 GrokCode 倍率榜。信息仅供参考，不构成购买、投资或法律意见。