Semantic Kernel 集成 Amazon Bedrock Agents：在 AWS 上构建、调用与编排 AI Agent 的完整指南

Semantic Kernel 集成 Amazon Bedrock Agents在 AWS 上构建、调用与编排 AI Agent 的完整指南【免费下载链接】semantic-kernelIntegrate cutting-edge LLM technology quickly and easily into your apps项目地址: https://gitcode.com/GitHub_Trending/se/semantic-kernel导读Amazon Bedrock Agents 是 AWS 提供的托管式 Agent 服务可以在 AWS 云端快速创建并运行 AI Agent而 Semantic Kernel 的 Bedrock 集成层Microsoft.SemanticKernel.Agents.Bedrock则把两者打通让开发者用统一的 Semantic Kernel Agent 抽象去创建、配置、调用 Bedrock Agent并把 Kernel 函数直接注册为 Agent 的工具action group。读完本文你将掌握如何在 .NET 中创建并调用 Bedrock Agent、如何为其接入 Kernel 函数、代码解释器、用户输入与知识库等能力以及流式调用、会话线程、Trace 观测和声明式 YAML 定义等进阶用法。本文以 dotnet/src/Agents/Bedrock/README.md 为主线结合该集成模块的源码与示例深入展开。一、集成概览Bedrock Agents 与 Semantic Kernel 的角色分工根据模块 README 的定义AWS Bedrock Agents 是一项托管服务允许用户在 AWS 云中快速搭建并运行 AI Agent。Semantic Kernel 的集成包Microsoft.SemanticKernel.Agents.Bedrock见 Agents.Bedrock.csproj在此基础上提供了一层 .NET 抽象BedrockAgent继承自 Semantic Kernel 的Agent是对 Bedrock Agent 服务的专门实现BedrockAgent.cs。它同时持有两个 AWS SDK 客户端——IAmazonBedrockAgent管理面用于创建/准备/删除 Agent与IAmazonBedrockAgentRuntime运行时面用于执行会话。BedrockAgentThread代表一次对话会话底层对应 Bedrock 的 sessionBedrockAgentThread.cs。BedrockAgentChannel是AgentChannel的专门实现让 Bedrock Agent 可以参与AgentGroupChat等多方协作场景BedrockAgentChannel.cs。从工程层面看该包通过 NuGet 引用AWSSDK.BedrockAgent与AWSSDK.BedrockAgentRuntime两个官方 AWS SDK目标框架为net10.0;net8.0;netstandard2.0。需要说明的是项目源码中以SKEXP0110实验性警告标注了该集成VersionSuffix为alpha属于评估期特性API 在未来版本中可能调整。1.1 从源码看调用链路一个典型的调用会经过如下链路见 BedrockAgent.cs 与 BedrockAgentInvokeExtensions.csBedrockAgent.InvokeAsync校验消息非空、确保最后一条是用户消息并创建/复用BedrockAgentThread构造InvokeAgentRequest其中AgentAliasId默认使用工作草稿别名TSTALIASID即BedrockAgent.WorkingDraftAgentAlias常量也可通过BedrockAgentInvokeOptions.AgentAliasId覆盖通过RuntimeClient.InvokeAgentAsync发起调用并逐事件消费响应流响应流中的事件会被分别处理为普通文本PayloadPart、文件FilePart、函数调用ReturnControlPayload与 TraceTracePart当收到函数调用事件且函数自动调用被启用时集成层会直接在本地Kernel中执行对应的 Kernel 函数并把结果封装为SessionState.ReturnControlInvocationResults回传给 Bedrock形成一轮完整的工具调用闭环。1.2 两个关键 API 形态BedrockAgent同时提供两种调用形态详见 BedrockAgent.csInvokeAsync(...)非流式调用返回IAsyncEnumerableAgentResponseItemChatMessageContent将多个响应片段聚合成一个ChatMessageContentInvokeStreamingAsync(...)流式调用返回IAsyncEnumerableAgentResponseItemStreamingChatMessageContent。从源码看Bedrock 对流式与非流式使用同一 API集成层通过设置StreamingConfigurations.StreamFinalResponse true开启流式并将响应逐块转换为流式消息。每次调用都需要至少一条消息否则会抛出InvalidOperationException(The Bedrock agent requires a message to be invoked.)。二、前置条件AWS 账号、模型访问权限与 IAM 配置在开始编码前需要完成 AWS 侧的准备。示例目录的说明文件 GettingStartedWithAgents/BedrockAgent/README.md 给出了完整的准备工作AWS 账号与模型访问权限需要在 AWS 控制台为账号开通对目标基础模型Foundation Model的访问权限安装并配置 AWS CLI本地需要安装 AWS CLI 并完成凭据配置如aws configure因为示例与运行时都会通过默认凭据链访问 Bedrock 服务准备 IAM 角色AgentResourceRoleArnAgent 执行需要委托给某个 IAM 角色。在 AWS 控制台 IAM 服务的Roles中找到目标角色其摘要页中的 ARN 即所需值开通bedrock:InvokeModelWithResponseStream权限运行时调用依赖该动作需在角色的权限策略中手动添加。2.1 用 user-secrets 管理配置示例使用 .NET User Secrets 存储敏感配置dotnet user-secrets set BedrockAgent:AgentResourceRoleArn arn:aws:iam::...:role/... dotnet user-secrets set BedrockAgent:FoundationModel ...FoundationModel的值即你在 AWS 侧有权访问的模型 ID例如 Anthropic Claude 系列等必须以 AWS 控制台实际开通的模型为准。此外知识库场景还需要BedrockAgent:KnowledgeBaseId见声明式示例 Step07_BedrockAgent_Declarative.cs。三、快速开始创建 Agent 并完成首次对话示例 Step01_BedrockAgent.cs 展示了最基础的用法包含「新建 Agent」「使用已有 Agent」「流式调用」三个场景。3.1 新建一个 Bedrock Agent// 1. 在 Bedrock Agent 服务上创建 Agent 并等待其进入 PREPARED 状态 var agentModel await this.Client.CreateAndPrepareAgentAsync(this.GetCreateAgentRequest(agentName)); // 2. 包装为 Semantic Kernel 的 BedrockAgent var bedrockAgent new BedrockAgent(agentModel, this.Client, this.RuntimeClient); // 3. 创建会话线程并调用 AgentThread bedrockAgentThread new BedrockAgentThread(this.RuntimeClient); var responses bedrockAgent.InvokeAsync( new ChatMessageContent(AuthorRole.User, Why is the sky blue in one sentence?), bedrockAgentThread, null); await foreach (ChatMessageContent response in responses) { Console.WriteLine(response.Content); } // 4. 清理资源 await bedrockAgent.Client.DeleteAgentAsync(new() { AgentId bedrockAgent.Id }); await bedrockAgentThread.DeleteAsync();这里的关键扩展方法CreateAndPrepareAgentAsync在 BedrockAgentExtensions.cs 中实现先CreateAgentAsync创建再等待 Agent 从CREATING进入NOT_PREPARED状态随后调用PrepareAgentAndWaitUntilPreparedAsync依次等待PREPARING与PREPARED两个状态。状态轮询默认每 2 秒一次、最多 5 次尝试超时抛出TimeoutException——这解释了为什么创建后需要等待片刻才能调用。3.2 使用 AWS 上已存在的 Agent如果 Agent 已在 AWS 控制台创建好只需通过 ID 获取并包装var getAgentResponse await this.Client.GetAgentAsync(new() { AgentId bedrock-agent-id }); var bedrockAgent new BedrockAgent(getAgentResponse.Agent, this.Client, this.RuntimeClient);BedrockAgent的构造函数会从 AWS 的 Agent 模型中同步Id、Name、Description、Instructions等属性。需要特别留意的是源码注释明确指出Bedrock Agent 不支持在运行时替换指令因此该 Agent 类型不支持 prompt template详见 BedrockAgent.cs 的构造函数注释。3.3 流式调用var streamingResponses bedrockAgent.InvokeStreamingAsync( new ChatMessageContent(AuthorRole.User, UserQuery), bedrockAgentThread, null); await foreach (StreamingChatMessageContent response in streamingResponses) { Console.WriteLine(response.Content); }四、Tools/Functions把 Kernel 函数注册为 Bedrock 工具这是集成层的核心能力。README 指出Bedrock Agents 通过action group动作组使用工具而该集成允许用户把 Kernel 函数直接注册为 Bedrock Agent 的工具。4.1 一行代码注册全部 Kernel 函数示例 Step03_BedrockAgent_Functions.cs 展示了完整流程// 1. 创建 Kernel 并挂载插件 Kernel kernel new(); kernel.Plugins.Add(KernelPluginFactory.CreateFromTypeWeatherPlugin()); // 2. 包装 Bedrock Agent 并绑定 Kernel var bedrockAgent new BedrockAgent(agentModel, this.Client, this.RuntimeClient); // 3. 一键创建 Kernel 函数 action group 并重新 prepare Agent await bedrockAgent.CreateKernelFunctionActionGroupAsync(); // 4. 调用Agent 会在需要时自动调用 Kernel 函数 var responses bedrockAgent.InvokeAsync( new ChatMessageContent(AuthorRole.User, What is the weather in Seattle?), null);其中插件用标准的[KernelFunction]与[Description]声明例如[KernelFunction, Description(Provides real-time weather information.)] public string Current([Description(The location to get the weather for.)] string location) $The current weather in {location} is 72 degrees.;4.2 底层实现函数 Schema 的自动映射CreateKernelFunctionActionGroupAsync的无参重载会调用agent.Kernel.ToFunctionSchema()见 BedrockAgentExtensions.cs其实现位于 BedrockFunctionSchemaExtensions.cs遍历Kernel.Plugins中所有插件的所有函数生成Function含Name、Description、Parameters参数类型通过ToAmazonType映射为 Bedrock 的类型体系string → String、bool → Boolean、整数类型 →Integer、浮点类型 →Number、数组类型 →Array遇到不支持的参数类型会抛出ArgumentExceptionRequireConfirmation固定为DISABLED——源码注释说明Bedrock 支持在调用函数前要求用户确认但当前集成尚未实现该特性因此统一关闭action group 采用RETURN_CONTROL自定义控制方式即模型输出工具调用意图后交回给客户端Semantic Kernel 侧真正执行函数。4.3 函数自动调用的闭环在 BedrockAgentInvokeExtensions.cs 中响应流的ReturnControlPayload事件会被解析为FunctionCallContent列表保留函数名、参数与InvocationId并在元数据中记录ActionGroup与ActionInvocationType。随后若函数调用开关开启复用FunctionCallsProcessor读取FunctionChoiceBehavior.Auto()配置集成层调用FunctionCallContent.InvokeAsync(agent.Kernel, ...)在本地并行执行函数结果通过SessionState.ReturnControlInvocationResults回传给 Bedrock触发下一轮模型推理循环带有请求序号上限防止函数调用陷入死循环由于 Bedrock 不支持多模态工具结果当函数返回图片ImageContent时会返回一个固定的不支持错误消息ImageContentNotSupportedErrorMessage。该示例还演示了并行函数调用What is the current weather in Seattle and what is the weather forecast in Seattle?会触发Current与Forecast两个函数的并行执行复杂类型如返回MenuItem[]也能被序列化为文本结果供模型使用。五、启用代码解释Code InterpretationREADME 指出Bedrock Agents 可以借助code interpretation特性编写并执行代码这与 OpenAI 提供的 Code Interpreter 能力类似。在 Semantic Kernel 中启用只需调用 BedrockAgentExtensions.cs 中的CreateCodeInterpreterActionGroupAsyncvar bedrockAgent new BedrockAgent(agentModel, this.Client, this.RuntimeClient); await bedrockAgent.CreateCodeInterpreterActionGroupAsync();示例 Step02_BedrockAgent_CodeInterpreter.cs 中用户让 Agent 根据数据画柱状图Agent 自动生成并执行 Python 代码最终把生成的图表文件返回给客户端。集成层在响应中把FilePart事件转换为BinaryContent见 BedrockAgentInvokeExtensions.cs 的HandleFilesEvent文件名记录在Metadata[Name]中开发者可以这样落盘if (response.Items.Count 0) { var binaryContent response.Items.OfTypeBinaryContent().FirstOrDefault(); var filePath Path.Combine(dir, binaryContent.Metadata![Name]!.ToString()!); binaryContent.WriteToFile(filePath, overwrite: true); }从实现看CreateCodeInterpreterActionGroupAsync本质上是为 Agent 创建一个基于AMAZON.CodeInterpreter父签名ParentActionGroupSignature的 action group并在创建后自动等待 Agent 重新进入PREPARED状态。六、启用用户输入User InputREADME 说明Bedrock Agents 可以在工具调用缺少必要信息时向用户请求补充输入。启用该能力后Agent 会主动向用户提问缺失信息如果关闭Agent 则会自行猜测缺失信息。Semantic Kernel 集成通过EnableUserInputActionGroupAsync开启同样位于 BedrockAgentExtensions.csawait bedrockAgent.EnableUserInputActionGroupAsync();其实现与代码解释器类似为 Agent 创建基于AMAZON.UserInput父签名的 action group 并重新 prepare。这意味着该能力是云端 Agent 级别的配置一旦启用Agent 在推理过程中遇到参数缺失时会生成「询问用户」的意图而不再是自行补全。七、知识库Knowledge Base开箱即用的 RAGREADME 指出Bedrock Agents 可以引用 AWS 上保存的数据执行 RAG 任务在 AWS 中称为knowledge base。Semantic Kernel 集成通过 BedrockAgentExtensions.cs 中的三个方法管理知识库关联// 关联知识库需要有效的 KnowledgeBaseId并附上用途描述 await bedrockAgent.AssociateAgentKnowledgeBaseAsync( knowledgeBaseId, You will find information here.); // 解除关联 await bedrockAgent.DisassociateAgentKnowledgeBaseAsync(knowledgeBaseId); // 列出当前关联的知识库 var response await bedrockAgent.ListAssociatedKnowledgeBasesAsync();从实现细节看关联/解除关联都以AgentVersion ?? DRAFT作为版本号发起请求并在操作完成后自动等待 Agent 重新 prepare——也就是说知识库变更同样会触发 Agent 的重新准备流程。示例 Step05_BedrockAgent_FileSearch.cs 展示了「Agent 关联知识库后回答What is Semantic Kernel?」的完整用法前提是你已经在 AWS 上创建好知识库并把文档数据同步进去。关联后Agent 会在需要时自动从知识库检索信息并基于检索结果作答形成完整的 RAG 链路。八、多代理协作Multi-agent当前集成不支持及原因README 在最后一部分明确给出了边界Bedrock Agents 本身支持 multi-agent workflows用于处理更复杂的任务但它的多代理模式与 Semantic Kernel 采用的不同因此当前集成不支持该能力。从源码结构看该结论是合理的Semantic Kernel 的多代理协作建立在AgentGroupChat/AgentChannel抽象之上而BedrockAgentChannel见 BedrockAgentChannel.cs走的是「单 Agent 单会话」的对话通道模型并不对接 Bedrock 云端的多代理编排协议。不过这不代表 Bedrock Agent 无法参与多代理会话。示例 Step06_BedrockAgent_AgentChat.cs 演示了在 Semantic Kernel 侧让一个 Bedrock Agent 与一个ChatCompletionAgent组成AgentGroupChat互相对话var chat new AgentGroupChat(bedrockAgent, chatCompletionAgent) { ExecutionSettings new() { TerminationStrategy new MultiTurnTerminationStrategy(2), } }; chat.AddChatMessage(new ChatMessageContent(AuthorRole.User, userQuery)); await foreach (var response in chat.InvokeAsync()) { /* 处理回复 */ }BedrockAgentChannel在这里承担了桥接职责。由于Bedrock 要求对话历史在 user/assistant 之间严格交替该通道会在相邻消息角色相同时插入内容为[SILENCE]的占位消息源码中MessagePlaceholder常量并在发送前确保最后一条消息是用户消息EnsureLastMessageIsUser。这些细节保证了 Bedrock Agent 可以在 Semantic Kernel 的多方会话中稳定工作同时规避了云端「多代理编排」这一不兼容点。九、进阶Trace 观测、会话线程与声明式定义9.1 用 Trace 观察 Agent 的思考过程BedrockAgentInvokeOptions见 BedrockAgentInvokeOptions.cs提供两个可选参数参数类型说明AgentAliasIdstring?要调用的 Agent 别名 ID不设置时使用工作草稿别名TSTALIASIDEnableTracebool是否启用 Trace以观测 Agent 的思考过程示例 Step04_BedrockAgent_Trace.cs 展示了如何开启并消费 TraceBedrockAgentInvokeOptions options new() { EnableTrace true }; var responses bedrockAgent.InvokeAsync( [new ChatMessageContent(AuthorRole.User, userQuery)], agentThread, options); await foreach (ChatMessageContent response in responses) { if (response.InnerContent is Listobject? innerContents) { var traceParts innerContents.OfTypeTracePart().ToList(); foreach (var tracePart in traceParts) { // 读取 tracePart.Trace例如 OrchestrationTrace } } }从 BedrockAgentInvokeExtensions.cs 的HandleTraceEvent看TracePart事件会被包装为ChatMessageContent存入InnerContent。示例的输出展示了 orchestration trace 中模型调用前后的完整输入输出与 token 用量InputTokens/OutputTokens可用于调试工具调用决策、估算成本与排查问题。9.2 会话线程与生命周期管理BedrockAgentThreadBedrockAgentThread.cs把 Bedrock 的 session 封装为可复用的对话线程创建线程调用运行时 SDK 的CreateSessionAsync返回SessionId删除线程依次调用EndSessionAsync与DeleteSessionAsync清理云端会话也可以直接new BedrockAgentThread(runtimeClient, sessionId)携带既有 session id 继续对话。示例代码中普遍使用try/finally在会话结束后删除线程避免云端资源泄漏。另外BedrockAgent.CreateSessionId()提供了生成唯一会话 id 的便捷方法。9.3 声明式 YAML 定义 Agent通过 BedrockAgentFactory.csAgentFactory的专门实现类型标识为bedrock_agentBedrock Agent 可以像其他 SK Agent 一样用 YAML 声明式创建。示例 Step07_BedrockAgent_Declarative.cs 提供了 5 种声明式用法1基础创建type: bedrock_agent name: StoryAgent description: Story Telling Agent instructions: Tell a story suitable for children about the topic provided by the user. model: id: ${BedrockAgent:FoundationModel} connection: type: bedrock agent_resource_role_arn: ${BedrockAgent:AgentResourceRoleArn}2复用已有 Agent只需 id 与 typeid: ${BedrockAgent:AgentId} type: bedrock_agent3启用代码解释器tools: - type: code_interpreter4注册函数工具需在options.parameters中声明每个参数的名称、类型、是否必填与描述tools: - id: Current type: function description: Provides real-time weather information. options: parameters: - name: location type: string required: true description: The location to get the weather for.5关联知识库tools: - type: knowledge_base description: You will find information here. options: knowledge_base_id: ${BedrockAgent:KnowledgeBaseId}工厂的解析逻辑在 BedrockAgentDefinitionExtensions.cs 中按工具类型分别调用CreateCodeInterpreterActionGroupAsync、CreateKernelFunctionActionGroupAsync从 YAML 中的function工具生成FunctionSchema和AssociateAgentKnowledgeBaseAsync然后统一等待 Agent prepare 完成。创建时通过agent_resource_role_arn来自model.connection的扩展数据指定 IAM 角色 ARN。创建后即可通过factory.CreateAgentFromYamlAsync(text, ...)获得可调用的Agent实例。十、能力边界与注意事项小结结合 README 与源码汇总该集成的关键边界能力支持情况说明Kernel 函数作为工具action group✅ 支持自动映射 SchemaRETURN_CONTROL 本地自动执行代码解释器✅ 支持云端执行代码返回文件BinaryContent用户输入✅ 支持缺失信息时向用户提问而非猜测知识库 RAG✅ 支持关联/解除关联/列出知识库多代理工作流❌ 不支持Bedrock 的编排模式与 SK 不同可用AgentGroupChat在 SK 侧编排Prompt 模板❌ 不支持Bedrock 运行时不允许替换指令函数调用用户确认RequireConfirmation❌ 暂不支持固定为DISABLED多模态工具结果❌ 不支持图片结果返回固定的不支持消息此外还需注意本集成属于实验性特性SKEXP0110API 可能变更所有云端操作依赖 AWS 账号的模型访问权限、IAM 角色与bedrock:InvokeModelWithResponseStream权限Agent 创建、prepare、action group 变更后都必须等待其进入PREPARED状态才能调用示例中默认的轮询间隔为 2 秒、最多 5 次尝试。十一、结语Semantic Kernel 的 Bedrock 集成把「AWS 托管 Agent 服务」与「SK 统一的 Agent 抽象」结合起来你在 AWS 侧获得稳定的托管运行时在 .NET 侧则复用 SK 的 Kernel、插件、函数调用、群聊与声明式定义等一整套开发体验。源码与示例GettingStartedWithAgents/BedrockAgent 目录下的 Step01Step07完整覆盖了从基础调用、函数工具、代码解释、知识库到 Trace 观测与 YAML 声明式的全部路径可作为上手该集成的最佳参考。【免费下载链接】semantic-kernelIntegrate cutting-edge LLM technology quickly and easily into your apps项目地址: https://gitcode.com/GitHub_Trending/se/semantic-kernel创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考