使用 Amazon Bedrock AgentCore 构建由 AI 驱动的设备维修助手

管理重型农业机械的设备维修通常需要技术人员在没有合适零件的情况下诊断问题，导致多次现场上门、停机时间延长以及重大经济损失，尤其是在收获季节。

在本文中，你将使用 Amazon Bedrock AgentCore 构建一个由 AI 驱动的设备维修助手，帮助农民和现场技术人员通过自然语言诊断设备问题、识别所需零件，并访问制造商批准的维修流程。该解决方案使用 AgentCore Runtime 与 Strands Agents SDK、Amazon Nova 2 Lite 作为基础模型、Amazon Bedrock Knowledge Base 用于检索增强生成（RAG），以及 AgentCore Memory 用于会话持久化。

解决方案概述

该解决方案将一个 Web 前端与托管在 AgentCore 上的代理相结合，该代理使用已索引的制造商文档来回答设备诊断问题。

Amazon Cognito 管理用户身份验证，AWS Amplify 托管 Web 应用程序。设备维修代理运行在 AgentCore Runtime 上，并使用 Strands Agents SDK 构建。它查询一个 Bedrock Knowledge Base，其中包含已索引的设备手册、零件目录和维修文档。AgentCore Memory 跨会话维护对话历史，因此技术人员无需重复上下文即可提出后续问题。

下图展示了这些组件如何协同工作。

该架构包含以下关键部分：

A 部分 – 身份验证和前端：CloudFormation 堆栈部署 Amazon Cognito（User Pool、Identity Pool）用于身份验证，并部署 AWS Amplify 用于托管 React Web 应用程序。用户通过 Cognito 进行身份验证，前端直接与 AgentCore Runtime 端点通信。

B 节 – AgentCore Runtime：AgentCore Runtime 托管基于 Strands 的智能体，并公开 /invocations 端点。前端使用 Cognito Bearer token 直接调用此端点。智能体的 invoke() 入口点会根据载荷中的 path 字段在内部路由请求（/chat 用于 AI 查询，/issues 用于 CRUD 操作），为后端操作提供单一入口点，并内置会话管理和健康检查。

C 节 – AI 处理：Strands Agent 使用自定义的 search_equipment_knowledge 工具，该工具通过 retrieve_and_generate API 调用 Bedrock Knowledge Base。Knowledge Base 使用 Amazon OpenSearch Serverless 进行向量搜索，并使用 Amazon Titan Embeddings 进行语义匹配，对存储在 Amazon S3 中的设备文档建立索引。

以下代码片段展示了智能体的 Knowledge Base 检索工具如何查询制造商文档：

@tool
def search_equipment_knowledge(query: str) -> str:
    """Search equipment manuals, parts catalogs, and repair docs."""
    response = bedrock_agent_runtime.retrieve_and_generate(
        input={"text": query},
        retrieveAndGenerateConfiguration={
            "type": "KNOWLEDGE_BASE",
            "knowledgeBaseConfiguration": {
                "knowledgeBaseId": KNOWLEDGE_BASE_ID,
                "modelArn": f"arn:aws:bedrock:{REGION}::foundation-model/{MODEL_ID}",
            },
        },
    )
    return response.get("output", {}).get("text", "No results found.")

D 节 – 数据和记忆：Amazon DynamoDB 存储设备服务工单（问题 CRUD 操作）。AgentCore Memory 提供用于会话内上下文的短期记忆，以及用于跨会话事实持久化的长期记忆。Amazon CloudWatch 和 AWS X-Ray 提供自动可观测性。

以下步骤描述了技术人员提问时的请求流程：

1. 技术人员打开 Web 应用程序，并通过 Amazon Cognito 进行身份验证。
2. 技术人员通过聊天界面提交问题。
3. 前端使用 Cognito Bearer 令牌将查询发送到 AgentCore Runtime /invocations 端点。
4. AgentCore 验证令牌，将请求路由到代理，并从先前对话中检索相关上下文。
5. Strands Agent 将查询发送到 Amazon Nova 2 Lite 进行推理。
6. 该模型调用 search_equipment_knowledge 工具，该工具查询 Bedrock Knowledge Base。
7. Knowledge Base 搜索已编入索引的设备手册，并返回带有来源引用的相关文档。
8. 该模型会综合生成包含维修流程和零件建议的诊断响应。
9. 响应会返回给技术人员，并附带来源归因以供验证。

前提条件

开始之前，请确认您已具备：

• 一个具有适当权限、可部署 AgentCore 代理的 AWS 账户。有关所需的 IAM 权限，请参阅 AgentCore Runtime 的 IAM Permissions。
• 在你的部署 AWS 区域中拥有 Amazon Nova 2 Lite 的 Amazon Bedrock 模型访问权限。你也可以使用自己选择的其他受支持模型。有关当前模型可用性，请参阅 Model support by AWS Region。
• 已安装 AWS Command Line Interface (AWS CLI) v2.0 或更高版本，并使用适当的凭证完成配置。
• 已安装 Python 3.10 或更高版本。
• 终端或命令提示符访问权限。

成本估算：对于测试，主要成本来自 Amazon Bedrock 模型调用（Amazon Nova 2 Lite 的输入/输出 token 价格为每百万个 0.30/2.50 美元）和 Bedrock Knowledge Base（OpenSearch Serverless 在启用期间约为每小时 0.24 美元）。其他服务（AgentCore Runtime、Amazon DynamoDB、Amazon S3、Amazon Cognito、AWS Amplify）在测试用量下属于 AWS Free Tier 范围。有关详细估算，请使用 AWS Pricing Calculator。

重要提示：请在同一个 AWS Region 中部署所有资源。CloudFormation 堆栈、Knowledge Base 和 AgentCore 启动命令必须使用相同的 Region。

创建 Knowledge Base

在部署代理之前，请创建并填充包含农业设备文档的 Amazon Bedrock 知识库。该知识库为诊断建议和维修指导提供源材料。

步骤 1：准备您的文档

为了进行测试，请从 John Deere Technical Information Store 下载设备手册。您也可以使用自己组织的设备文档。在本博客中，我们使用 John Deere 1023E 和 1025R 紧凑型多功能拖拉机操作员手册。

收集并整理您的农业设备文档：

• 设备手册（推荐使用 PDF 格式）
• 技术服务指南和故障排除文档
• 包含零件编号和规格的零件目录
• 维护计划和预防性保养说明
• 安全规程和制造商警告

文档准备提示：

• 确认文档可进行文本搜索（不是扫描图像）
• 使用一致的命名规范（例如，Manufacturer_Model_DocumentType.pdf）
• 移除任何不应对所有用户开放访问的专有信息

步骤 2：为 Knowledge Base 创建一个 S3 存储桶

aws s3 mb s3://agriculture-kb-documents-<unique-suffix>
aws s3 cp ./equipment-docs s3://agriculture-kb-documents-<unique-suffix> --recursive

步骤 3：创建 Bedrock Knowledge Base

按照说明使用以下设置创建 Knowledge Base：

• 知识库名称：Agriculture-Equipment-Repair-KB
• 数据源：s3://agriculture-kb-documents-<unique-suffix>（第 2 步中创建的存储桶）
• 解析策略：Amazon Bedrock 默认解析器
• 分块策略：默认分块
• 嵌入模型：Amazon Titan Embeddings G1 – Text
• 向量存储：快速创建新的向量存储（Amazon OpenSearch Serverless）

步骤 4：同步并测试知识库

创建知识库后，同步您的数据源以开始摄取文档（通常需要 10–20 分钟）。有关详细信息，请参见“同步以摄取您的数据源”。使用 Bedrock 控制台中的测试功能，验证知识库是否能响应示例查询。从详情页面记录知识库 ID。

部署解决方案

步骤 5：部署支持基础设施

1. 启动 CloudFormation 堆栈。你将被重定向到 AWS CloudFormation 控制台。
2. 在堆栈参数中，模板 URL 将会预先填充。对于堆栈名称，输入你的部署名称（默认：ag-repair-assist）。对于 KnowledgeBaseId，输入上一节中记录的知识库 ID。查看并创建堆栈。
3. 成功部署后，请从 CloudFormation 堆栈的 Outputs 选项卡中记录以下值：AgentCoreExecutionRoleArn——配置代理时使用；CognitoDiscoveryUrl——配置代理时使用；UserPoolClientId——配置代理时使用；EquipmentIssuesTableName——部署代理时使用；UserPoolId——配置前端时使用；IdentityPoolId——配置前端时使用；AmplifyConsoleUrl——用于前端部署；AmplifyAppUrl——你的应用程序 URL

步骤 6：部署代理（从你的本地计算机）

在已配置 AWS 凭证的本地终端中运行以下命令。需要 Python 3.10 或更高版本。

1. 创建项目目录并设置环境

mkdir agriculture-repair-agent && cd agriculture-repair-agent
python3 -m venv .venv
source .venv/bin/activate

1. 安装 AgentCore 工具包和依赖项

pip install "bedrock-agentcore-starter-toolkit>=0.1.21" strands-agents strands-agents-tools boto3

• 接下来，下载并解压代理代码。其中包含两个文件：agriculture_repair_agent.py（代理逻辑）和 requirements.txt（依赖项）。
• 配置代理。此命令会为你的 AgentCore 部署设置执行角色、OAuth 和内存设置：

agentcore configure -e agriculture_repair_agent.py

1. 出现提示时，输入以下值：

Agent Name: Press Enter to use the default name (agriculture_repair_agent)
Requirements File: Press Enter to confirm requirements.txt dependency file
Deployment Configuration: Select Choice 1. "Direct Code Deploy - Python only, no Docker required" and press Enter.
Select Python runtime version: If you have multiple Python versions, select 3.10 or higher
Execution Role: paste <AgentCoreExecutionRoleArn> from Step 5 CloudFormation Outputs and press Enter.
S3 Bucket URI/Path: Enter <URI path> for the S3 bucket that was created in Step 2 and press Enter.
Configure OAuth authorizer instead?: Choose yes and press Enter.
Enter OAuth Discovery URL: paste <CognitoDiscoveryUrl> from Step 5 CloudFormation Outputs and press Enter.
Enter allowed OAuth client IDs: paste <UserPoolClientId> from Step 5 CloudFormation Outputs and press Enter.
Enter allowed OAuth audience: press Enter to skip (leave empty, the access token uses the client_id claim, not aud)
Enter allowed OAuth allowed scopes: press Enter to skip (leave empty)
Enter allowed OAuth custom claims as JSON string: press Enter to skip (leave empty)
Configure request header allowlist?: press Enter to accept default (no)
Memory Configuration: Press Enter to create new memory
Enable long-term memory?: Yes

设置后的代理配置详情

1. 将代理部署到 AgentCore Runtime。无需本地 Docker。该过程大约需要 5–10 分钟。

agentcore launch --env KNOWLEDGE_BASE_ID=<your-kb-id> --env TABLE_NAME=<EquipmentIssuesTableName from Step 5 CloudFormation Outputs> --env MODEL_ID=us.amazon.nova-2-lite-v1:0

1. 完成后，请记录输出中的 Agent Runtime ARN。

CloudFormation 堆栈会创建具备所需权限的代理执行角色。无需额外的 IAM 配置。

步骤 7：部署前端

1. 从上面的链接下载 ML-18699-FrontEnd.zip。
2. 导航到步骤 5 CloudFormation 输出中的 AmplifyConsoleUrl。
3. 点击 Deploy updates，选择 Drag and drop 方法，点击 Choose .zip folder，然后点击 Save and Deploy。
4. 等待部署完成。

使用 Web 应用程序

打开第 5 步 CloudFormation 输出中的 AmplifyAppUrl。首次启动时，系统会提示你输入配置详细信息。输入 CloudFormation 堆栈输出（第 5 步）和代理部署（第 6 步）中的值。

保存配置后，使用“注册”选项创建账户，验证你的电子邮件，然后登录。

登录后，您将看到主仪表板。

以下是一些可尝试的示例查询：

问题分析：

Prompt: My John Deere 1023E series tractor is losing hydraulic pressure on the left side when lifting heavy implements. The pressure drops from 2500 PSI to about 1800 PSI under load.

技术人员聊天：

Prompt: What hydraulic fluid is recommended for John Deere 1025R?

清理

重要提示：此解决方案部署的 AWS 资源在删除之前会持续产生费用。这包括 Amazon DynamoDB、Amazon S3、AWS Amplify 托管和 Amazon Cognito。AgentCore Runtime 和 Amazon Bedrock 仅在使用时产生费用。请完成以下所有清理步骤，以停止产生费用。

警告：删除 S3 存储桶会永久移除所有已存储的设备文档。继续之前，请备份您希望保留的任何文件。

1. 删除代理：

agentcore destroy

1. 删除 CloudFormation 堆栈：

aws cloudformation delete-stack --stack-name ag-repair-assist

1. 删除知识库：

在 Amazon Bedrock Knowledge Bases 控制台中，选择 Agriculture-Equipment-Repair-KB，然后选择删除。

1. 清空并删除 S3 存储桶：

aws s3 rm s3://agriculture-kb-documents-<unique-suffix> --recursive
aws s3 rb s3://agriculture-kb-documents-<unique-suffix>

实施注意事项

数据管理和知识库设置 随着制造商发布新的设备型号并修订现有文档，知识库也必须相应演进。定期同步计划与自动化工作流相结合，使系统能够无缝处理新上传内容。

Amazon Bedrock AgentCore 配置 不同的故障排除场景需要不同级别的技术复杂度和响应准确性。Strands Agents 代码优先的方法允许你通过更改 MODEL_ID 环境变量来切换模型。AgentCore Memory 配置增加了会话智能。短期记忆在诊断会话内保持上下文，而长期记忆则跨会话保留技术人员专长、农户机队详情和重复出现的问题模式。应根据文档语料库的广度和深度来调优检索配置 top_k 和 relevance_score 阈值。

可扩展性 要添加新功能（库存检查、零件订购、经销商沟通），请向智能体代码添加新的 @tool 函数。无需更改基础设施。

合规与安全 每一项维修建议都必须符合制造商保修条款和安全指南。贯穿整个系统的安全协议可确保用户收到有关维修流程相关危险的主动警告。农业设备涉及高压液压系统、电气系统、旋转机械以及其他潜在危险部件。系统必须突出显示关键安全注意事项。

扩展至企业级 该解决方案设计轻量，适用于测试和评估。在扩展到生产环境时，请考虑以下增强措施：

• Amazon Bedrock Guardrails：添加提示攻击检测和内容过滤，以防范设备描述中的恶意输入。配置拒绝主题，防止代理提供其领域范围之外的指导。
• API 防护：在 AgentCore Runtime 端点前部署 Amazon CloudFront，并结合 AWS WAF 实现速率限制和 OWASP 防护。
• 多因素身份验证：启用 Amazon Cognito MFA（基于 TOTP 的软件令牌），以增强用户身份验证。
• 可观测性和告警：AgentCore 会自动生成可通过 Amazon CloudWatch 生成式 AI 可观测性仪表板查看的指标、日志和跟踪。为代理错误率和响应延迟配置告警。启用 Amazon Bedrock 模型调用日志记录以用于审计追踪。
• 数据生命周期：为设备文档版本控制实施 Amazon S3 生命周期策略，并为问题数据备份实施 Amazon DynamoDB 时间点恢复。
• 多区域部署：对于全球现场服务团队，在多个 AWS 区域部署 AgentCore Runtime，并配置包含本地化设备文档的区域专用 Knowledge Bases。

后续步骤

部署并测试此解决方案后，请考虑以下增强功能：

• 零件订购集成：添加一个 @tool，用于连接到您的零件库存系统，使代理能够检查库存可用性，并直接从诊断对话中下单。
• 经销商沟通：添加一个 @tool，通过 Amazon Simple Email Service（Amazon SES）或 Amazon Simple Notification Service（Amazon SNS）将诊断摘要发送给最近的授权经销商。
• 物联网遥测集成：通过 AWS IoT Core 连接设备传感器，在检测到异常读数时自动创建问题，并为代理预先填充诊断上下文。
• 移动现场应用：为技术人员构建可在现场使用、针对移动端优化的前端，并为连接受限区域提供离线缓存。

结论

这款 AI 驱动的设备维修助手展示了 Amazon Bedrock AgentCore 如何改进农业现场服务运营。通过将代码优先的 Strands Agent 与 Bedrock Knowledge Base 中全面的制造商文档相结合，该解决方案可在技术人员到达现场之前，为其提供精确的诊断建议和零部件识别。

该实现的主要优势包括：

• 缩短平均解决时间：通过基于制造商文档的 AI 驱动分析，实现更快速的诊断和维修
• 提高一次修复率：全面的服务前分析确保技术人员到场时携带正确的零件并掌握正确的流程
• 对话记忆：AgentCore Memory 在多轮诊断会话中保持上下文，并跨会话持久保存知识
• 简化的运维：单个 AgentCore Runtime 端点取代了对独立 API Gateway、Lambda 和 Bedrock Agent 资源的需求
• 内置可观测性：自动 X-Ray 跟踪和 CloudWatch 集成提供端到端可见性，无需额外设置
• 代码优先开发：Strands Agent 的 @tool 装饰器模式让你能够扩展功能，并在部署前进行本地测试

可扩展的架构确保组织能够根据其特定设备组合和服务需求调整这一基础。添加新工具（用于零件订购、库存检查或经销商沟通）只需要一个新的 @tool 函数，无需进行基础设施变更。

本博文中的示例代码根据 MIT-0 许可证提供。详情请参阅 LICENSE 文件。

免责声明：本内容仅供参考，不应被视为法律或合规建议。客户有责任对本文档中的信息以及对 AWS 产品或服务的任何使用进行独立评估。

资源

• Amazon Bedrock AgentCore 文档
• 正文：Strands Agents SDK
• Amazon Bedrock 用户指南
• Amazon Bedrock 知识库

关于作者