基于 Claude 与 Amazon Bedrock 构建客户支持 Agentclaude-quickstarts 实战指南【免费下载链接】claude-quickstartsA collection of projects designed to help developers quickly get started with building deployable applications using the Claude API项目地址: https://gitcode.com/GitHub_Trending/an/claude-quickstarts本指南以 claude-quickstarts 仓库中的customer-support-agent项目为核心系统讲解如何基于 Claude 大模型与 Amazon Bedrock Knowledge Bases 构建一个具备知识检索、情绪识别、人工转接与高度可定制 UI 的客户支持聊天应用。读完本文你将掌握该项目的环境配置、Bedrock RAG 知识库搭建、模型切换、结构化响应解析、AWS Amplify 部署以及按需裁剪界面的完整方案。项目概览与核心特性customer-support-agent是一个面向客户支持场景的聊天界面示例核心组合是「Claude 模型对话 Amazon Bedrock 知识检索RAG」。从 README 与源码可以归纳出以下核心能力AI 对话基于 Anthropic 的 Claude 模型生成回复由 API 路由 统一调用anthropic-ai/sdkBedrock RAG 检索通过 BedrockAgentRuntimeClient 调用知识库为对话注入上下文实时思考过程与调试信息展示接口返回thinking、debug等字段前端侧边栏实时渲染知识来源可视化RAG 检索到的来源文件名、片段、相关性分数通过响应头回传并展示在右侧边栏用户情绪检测与人工转接模型输出user_mood与redirect_to_agent触发「转接人工」按钮高可定制 UI基于 shadcn/ui 组件构建支持主题、布局灵活配置。快速启动按照 README 的指引只需五步即可在本地跑起来克隆本仓库claude-quickstarts在customer-support-agent目录安装依赖npm install配置环境变量见下文「环境变量与密钥配置」启动开发服务器npm run dev浏览器打开http://localhost:3000。需要说明的运行前提customer-support-agent/package.json中声明了engines: { node: 18.17.0 }建议使用 Node.js 18.17.0 及以上版本框架为 Next.js 14.2.5React 18依赖中包含aws-sdk/client-bedrock-agent-runtime、anthropic-ai/sdk等核心库。环境变量与密钥配置在项目根目录创建.env.local文件填入以下变量ANTHROPIC_API_KEYyour_anthropic_api_key BAWS_ACCESS_KEY_IDyour_aws_access_key BAWS_SECRET_ACCESS_KEYyour_aws_secret_key注意 AWS 相关变量名前有一个额外的BBAWS_*而非AWS_*。README 明确说明这是为部署阶段准备的AWS Amplify 不允许以AWS开头的环境变量名因此统一加前缀规避该限制。从源码看app/lib/utils.ts 中的 Bedrock 客户端正是通过process.env.BAWS_ACCESS_KEY_ID与process.env.BAWS_SECRET_ACCESS_KEY读取凭证const bedrockClient new BedrockAgentRuntimeClient({ region: us-east-1, // Make sure this matches your Bedrock region credentials: { accessKeyId: process.env.BAWS_ACCESS_KEY_ID!, secretAccessKey: process.env.BAWS_SECRET_ACCESS_KEY!, }, });这里有两个容易踩坑的细节一是region硬编码为us-east-1需要与你的 Bedrock 知识库所在区域保持一致二是.env.local仅作用于本地开发部署到 Amplify 时要在控制台另行配置见部署章节。获取 Claude API Key访问 Anthropic 控制台console.anthropic.com注册或登录账号点击 Get API keys复制密钥填入.env.local。获取 AWS Access Key 与 Secret Key登录 AWS 管理控制台进入 IAM身份与访问管理控制台左侧菜单点击Users点击Create user创建新用户创建用户截图在 Set Permission 页面选择Attach policies directly授权方式截图权限策略选择AmazonBedrockFullAccess策略选择截图完成 Review 并创建用户在用户 Summary 页面点击Create access key选择 Application running on an AWS compute service按需填写描述后创建页面会一次性展示 Access Key ID 与 Secret Access Key务必妥善保存密钥截图因为关闭后无法再次查看将两个密钥填入.env.local。安全提醒密钥只应在创建时可见请勿公开分享建议为最小权限原则考虑生产环境可用更细粒度的策略替代AmazonBedrockFullAccess。Amazon Bedrock RAG 集成这是项目的核心差异化能力对话前先到 Bedrock 知识库中检索相关内容再把检索结果拼进系统提示词让 Claude 基于知识库内容回答。检索链路与实现原理前端把用户最新消息与选中的知识库 ID 通过POST /api/chat发给后端app/lib/utils.ts 中的retrieveContext(query, knowledgeBaseId, n 3)完成检索const input: RetrieveCommandInput { knowledgeBaseId: knowledgeBaseId, retrievalQuery: { text: query }, retrievalConfiguration: { vectorSearchConfiguration: { numberOfResults: n }, }, }; const command new RetrieveCommand(input); const response await bedrockClient.send(command);其关键行为包括默认返回n 3条向量检索结果可按需调整召回数量若knowledgeBaseId为空或检索抛错会安全降级返回空上下文并置isRagWorking false不会中断对话见 route.ts 的 try/catch 分支检索结果会被组装为RAGSource[]含id、fileName、snippet、score通过响应头x-rag-sources回传前端用于来源可视化最终上下文以纯文本拼接进系统提示词${isRagWorking ? retrievedContext : No information found for this query.}并在debug.context_used中记录是否实际使用了知识库上下文。配置你的知识库确保 AWS 账号已开通 Bedrock 访问权限在目标区域创建 Bedrock 知识库将文档/语料索引进知识库步骤见下文编辑 components/ChatArea.tsx 中的knowledgeBases数组替换为你的知识库 ID 与名称const knowledgeBases: KnowledgeBase[] [ { id: your-knowledge-base-id, name: Your KB Name }, // Add more knowledge bases as needed ];应用会在对话过程中使用这些知识库做上下文检索。前端顶栏也提供了知识库下拉选择器与模型下拉并列便于在多个知识库之间切换。如何创建自己的知识库进入 AWS 控制台选择Amazon Bedrock左侧菜单 More 下点击Knowledge base点击Create knowledge base创建入口截图为知识库命名可保留 Create a new service role 默认选项选择数据源示例中使用 Amazon S3数据源选择截图。若用 S3需先创建 bucket 并上传文件也可以在知识库创建后再上传点击Next选择数据位置可以是 S3 bucket、文件夹甚至单个文档点击Next选择 embedding 模型示例使用 Titan Text Embeddings 2选择Quick create a new vector store快速创建向量存储确认并创建知识库从知识库概览页获取knowledge base ID填入knowledgeBases数组。切换模型项目支持多个 Claude 模型并通过下拉菜单切换。在 components/ChatArea.tsx 中models数组定义了可用模型仓库当前默认包含三个const models: Model[] [ { id: claude-3-haiku-20240307, name: Claude 3 Haiku }, { id: claude-haiku-4-5-20251001, name: Claude 4.5 Haiku }, { id: claude-3-5-sonnet-20240620, name: Claude 3.5 Sonnet }, ];当前选中的模型由selectedModelstate 控制const [selectedModel, setSelectedModel] useState(claude-haiku-4-5-20251001);UI 层使用DropdownMenu组件渲染模型列表选中后更新selectedModel并在提交请求时通过model字段传给/api/chat最终作为anthropic.messages.create({ model, ... })的入参。README 中给出的默认选中值为claude-3-haiku-20240307而当前仓库源码默认值为claude-haiku-4-5-20251001以实际代码为准添加新模型只需向models数组追加{ id, name }即可。后端 API 与结构化响应机制customer-support-agent/app/api/chat/route.ts是前后端通信的核心。除了调用 Claude它还承担了「结构化输出」的关键职责。Zod 响应 Schema为保证模型输出可被前端可靠解析路由使用 Zod 定义了响应结构const responseSchema z.object({ response: z.string(), thinking: z.string(), user_mood: z.enum([ positive, neutral, negative, curious, frustrated, confused, ]), suggested_questions: z.array(z.string()), debug: z.object({ context_used: z.boolean() }), matched_categories: z.array(z.string()).optional(), redirect_to_agent: z.object({ should_redirect: z.boolean(), reason: z.string().optional(), }).optional(), });模型生成的内容经过sanitizeAndParseJSON清洗把字符串值内部的换行转义为\n后再JSON.parse后通过该 Schema 校验保证响应字段完整、类型正确。系统提示词与 JSON 输出系统提示词把检索到的上下文、支持分类列表与 JSON 输出格式一并交给模型要求其「整个响应必须是一个合法 JSON 对象」并给出了带转接与不带转接两种示例。值得注意的实现技巧是请求会把消息末尾追加一个内容为{的 assistant 消息anthropicMessages.push({ role: assistant, content: { })诱导模型从「对象起始括号」之后继续生成随后在拼装响应时补上前缀{从而显著提升 JSON 输出的稳定性。响应头与调试信息接口除返回 JSON body 外还通过响应头传递辅助信息x-rag-sourcesRAG 检索到的知识来源JSON 序列化X-Debug-Data服务端调试信息包含收到的消息数、最新消息长度、API Key 前缀掩码如sk-****与时间戳长度限制为 1000 字符。前端 ChatArea.tsx 会解析x-rag-sources并派发updateRagSources事件供右侧边栏展示解析X-Debug-Data输出到控制台。服务端还通过performance.now()对「用户输入接收、RAG 开始/完成、Claude 生成、API 完成」等阶段计时并打印日志便于定位延迟瓶颈。支持分类matched_categories分类清单定义在 app/lib/customer_support_categories.json 中默认包含 8 个类别account账号、billing计费、feature功能、internal内部、legal法律、other其他、technical技术、usage使用每个类别附带若干关键词。系统提示词会要求模型在回答之外将命中类别 ID 写入matched_categories数组多个命中可返回多个 ID无命中返回空数组——这套机制可以支撑后续的工单自动分类与统计。用户情绪检测与人工转接这是该项目区别于普通聊天机器人的体验设计。模型在每次响应中输出user_mood六档情绪标签positive / neutral / negative / curious / frustrated / confusedredirect_to_agent是否建议转接人工及原因suggested_questions建议的追问问题前端渲染为可点击的快捷按钮点击后自动作为新消息提交。当redirect_to_agent.should_redirect为true时前端MessageContent会渲染UISelector组件展示一个Talk to a human按钮点击后派发humanAgentRequested自定义事件携带 reason、mood、timestamp方便业务方接入真实的客服排队/工单系统。服务端也会在转接触发时输出 AGENT REDIRECT TRIGGERED!与原因日志。同时系统提示词约束当检索不到相关信息、信息与问题无关或问题与产品无关时应引导用户转接人工。界面定制项目基于 shadcn/ui 组件体系构建定制路径清晰UI 组件修改 components/ui 目录下的基础组件按钮、卡片、对话框、下拉菜单、输入框、头像等全局样式调整 app/globals.css 中的主题变量页面布局在 app/page.tsx 中调整顶层导航、左右侧边栏与聊天区的组合侧边栏组件通过dynamic(..., { ssr: false })按需加载主题色板编辑 styles/themes.js其结构如下// styles/themes.js export const themes { neutral: { light: { // Light mode colors for neutral theme }, dark: { // Dark mode colors for neutral theme } }, // Add more themes here };新增主题或调整现有主题只需修改该文件的颜色值主题切换由 components/theme-provider.tsx 配合next-themes完成。使用 AWS Amplify 部署Amplify 构建配置进入 AWS 控制台选择Amplify点击Create new app选择 GitHub或其他代码托管平台作为源码来源选择本仓库将构建配置YAML编辑为以下内容仓库中的 amplify.yml 即为该配置的成品版本version: 1 frontend: phases: preBuild: commands: - npm ci --cache .npm --prefer-offline build: commands: - npm run build # Next.js build runs first - echo ANTHROPIC_API_KEY$ANTHROPIC_API_KEY .env - echo KNOWLEDGE_BASE_ID$KNOWLEDGE_BASE_ID .env - echo BAWS_ACCESS_KEY_ID$BAWS_ACCESS_KEY_ID .env - echo BAWS_SECRET_ACCESS_KEY$BAWS_SECRET_ACCESS_KEY .env artifacts: baseDirectory: .next files: - **/* cache: paths: - .next/cache/**/* - .npm/**/*要点说明preBuild阶段用npm ci做可复现安装build阶段先执行 Next.js 构建再把 Amplify 环境变量写入.env供服务端读取注意此处引入了 README 中提到的KNOWLEDGE_BASE_ID即知识库 ID 在部署场景下也走环境变量注入cache阶段缓存.next/cache与.npm以加速后续构建。选择新建服务角色或复用已有角色见下文「Service Role」点击Advanced settings添加环境变量ANTHROPIC_API_KEYyour_anthropic_api_key BAWS_ACCESS_KEY_IDyour_aws_access_key BAWS_SECRET_ACCESS_KEYyour_aws_secret_key再次强调加B前缀的原因AWS 不允许 Amplify 中出现以AWS开头的环境变量名所以这里的键名沿用了BAWS_*。点击Save and deploy开始部署。Service Role服务角色部署完成后如果选择了新建服务角色还需补齐 Bedrock 访问权限进入部署页面选中刚创建的部署点击App settings复制Service role ARN到 IAM 控制台找到该角色为该角色附加AmazonBedrockFullAccess策略。这样 Amplify 应用才具备与 Amazon Bedrock 交互的权限避免部署成功但 RAG 检索全部失败。灵活的侧边栏配置与 NPM 脚本项目支持按需裁剪界面布局左/右侧边栏由根目录 config.ts 通过环境变量控制type Config { includeLeftSidebar: boolean; includeRightSidebar: boolean; }; const config: Config { includeLeftSidebar: process.env.NEXT_PUBLIC_INCLUDE_LEFT_SIDEBAR true, includeRightSidebar: process.env.NEXT_PUBLIC_INCLUDE_RIGHT_SIDEBAR true, }; export default config;两个环境变量的含义NEXT_PUBLIC_INCLUDE_LEFT_SIDEBAR设为true时包含左侧边栏展示思考过程、情绪、匹配分类NEXT_PUBLIC_INCLUDE_RIGHT_SIDEBAR设为true时包含右侧边栏展示 RAG 知识来源。package.json 预置了对应的 NPM 脚本npm run dev # 完整应用双侧边栏默认 npm run build # 构建完整应用双侧边栏默认 npm run dev:full # 同 npm run dev npm run dev:left # 仅左侧边栏 npm run dev:right # 仅右侧边栏 npm run dev:chat # 仅聊天区无侧边栏 npm run build:full # 同 npm run build npm run build:left # 构建仅左侧边栏 npm run build:right # 构建仅右侧边栏 npm run build:chat # 构建仅聊天区无侧边栏这些脚本通过在执行next dev/next build前设置对应环境变量来切换布局例如dev:chat实质是NEXT_PUBLIC_INCLUDE_LEFT_SIDEBARfalse NEXT_PUBLIC_INCLUDE_RIGHT_SIDEBARfalse next dev。配合 app/page.tsx 中的条件渲染config.includeLeftSidebar LeftSidebar /等即可按测试、开发或生产需求灵活定制界面形态。当某侧边栏被禁用时ChatArea.tsx 仍会监听对应的自定义事件updateSidebar/updateRagSources只是改为在控制台输出方便你自行决定数据如何处理。附录原型声明按 README 附录 的说明本项目定位为原型prototype以 as-is 形式提供不适用于生产或关键任务环境可能包含缺陷与不一致之处。使用前请知悉软件以预发布/beta/试用形态提供开发者不对使用造成的任何问题、数据丢失或损害负责不提供任何明示或暗示的担保支持可能有限或不可用使用风险自负。如需在生产环境落地建议在充分测试、加固安全与可观测性之后再进行。项目整体作为 claude-quickstarts 仓库的一部分旨在帮助开发者快速上手基于 Claude API 构建可部署的应用。【免费下载链接】claude-quickstartsA collection of projects designed to help developers quickly get started with building deployable applications using the Claude API项目地址: https://gitcode.com/GitHub_Trending/an/claude-quickstarts创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考