使用 Semantic Kernel Python 构建 Azure AI Agents环境配置、Agent 定义与速率限制实战指南【免费下载链接】semantic-kernelIntegrate cutting-edge LLM technology quickly and easily into your apps项目地址: https://gitcode.com/GitHub_Trending/se/semantic-kernel导读本文围绕 Semantic Kernel Python 仓库中azure_ai_agent概念示例集及其配套 README系统讲解如何基于 Azure AI Agents 服务创建、配置并运行 Agent从.env环境变量、Azure CLI 凭据与项目客户端的初始化到 Agent 定义的新建与复用、Azure AI Search 工具挂载再到轮询间隔与速率限制的调优。读完本文你将能够独立跑通azure_ai_agent_azure_ai_search.py这类示例并把其中沉淀的配置模式迁移到自己的业务场景中。示例集概览azure_ai_agent 提供了哪些能力在 python/samples/concepts/agents/azure_ai_agent 目录下Semantic Kernel 提供了 26 个围绕 Azure AI Agent 的概念示例覆盖了该功能面的大部分使用形态基础能力azure_ai_agent_streaming.py流式输出、azure_ai_agent_message_callback.py及其_streaming变体消息回调、azure_ai_agent_prompt_templating.py提示词模板、azure_ai_agent_structured_outputs.py结构化输出、azure_ai_agent_truncation_strategy.py截断策略工具挂载azure_ai_agent_azure_ai_search.pyAzure AI Search 检索、azure_ai_agent_bing_grounding.pyBing 联网搜索、azure_ai_agent_code_interpreter_streaming_with_message_callback.py代码解释器、azure_ai_agent_file_manipulation.py文件操作、azure_ai_agent_mcp_streaming.pyMCP 集成、azure_ai_agent_deep_research_streaming.py深度研究函数与过滤器azure_ai_agent_as_kernel_function.pyAgent 作为 Kernel Function、azure_ai_agent_auto_func_invocation_filter.py及其流式变体自动函数调用过滤器声明式 Agentazure_ai_agent_declarative_*.py一组示例涵盖 Azure AI Search、Bing Grounding、Code Interpreter、File Search、函数调用、OpenAPI、模板化以及基于已有 Agent ID 复用等场景。配套的 README 位于 python/samples/getting_started_with_agents/azure_ai_agent/README.md是理解这些示例前置条件与运行方式的第一手资料下文展开的内容均以它和示例源码为基准。环境准备安装依赖与配置.env安装可选 Azure 依赖运行任何 Azure AI Agent 示例前需要安装带azure可选依赖的 Semantic Kernel Python 包pip install semantic-kernel官方快速开始文档建议参照 Azure AI 服务Quickstart: Create a new agentPython / Azure SDK 标签页完成资源创建且 Azure AI Agent 资源至少应配置为Basic 或 Standard SKU部分高级工具能力需要 Standard。配置环境变量在仓库根目录放置.env文件写入如下三项AZURE_AI_AGENT_ENDPOINT example-endpoint-string AZURE_AI_AGENT_MODEL_DEPLOYMENT_NAME example-deployment-name AZURE_AI_AGENT_API_VERSION example-api-version其中 endpoint 的格式为https://resource.services.ai.azure.com/api/projects/project-name可以在 Azure AI Foundry 门户ai.azure.com的项目详情页找到。这些环境变量与源码中的设置类一一对应。查看 python/semantic_kernel/agents/azure_ai/azure_ai_agent_settings.py 可以看到AzureAIAgentSettings的完整定义env_prefix: ClassVar[str] AZURE_AI_AGENT_ model_deployment_name: str endpoint: str | None None agent_id: str | None None bing_connection_id: str | None None azure_ai_search_connection_id: str | None None azure_ai_search_index_name: str | None None api_version: str | None None deep_research_model: str | None None它继承自KernelBaseSettingsenv_prefix AZURE_AI_AGENT_决定了配置项的读取前缀。从中可以注意到两点除文档提及的三项外设置类还支持agent_id复用已有 Agent、bing_connection_id、azure_ai_search_connection_id、azure_ai_search_index_name对应 Search / Bing 工具的连接配置分别由AZURE_AI_AGENT_BING_CONNECTION_ID等环境变量注入、deep_research_model深度研究模型等可选字段除model_deployment_name为必填外其余字段均可选——这意味你可以直接在代码中构造AzureAIAgentSettings并手动指定 endpoint / api_version而不必全部依赖环境变量。配置 AI Project Client凭据与客户端初始化认证方式所有 Azure AI Agent 示例都采用 Azure CLI 凭据进行认证。运行前需先在终端执行az login完成登录然后在代码中引入异步凭据类from azure.identity.aio import AzureCliCredential创建项目客户端最简洁的初始化方式是结合异步上下文管理器async with ( AzureCliCredential() as creds, AzureAIAgent.create_client(credentialcreds) as client, ): # Your operational code here也可以显式传入 endpoint 与可选的 api-versionapi_version 不传时使用服务端默认值ai_agent_settings AzureAIAgentSettings() async with ( AzureCliCredential() as creds, AzureAIAgent.create_client( credentialcreds, endpointai_agent_settings.endpoint, api_versionai_agent_settings.api_version, ) as client, ): # operational logicAzureAIAgent.create_client(...)内部完成 Azure AI Projects 客户端的构建与连接管理async with保证了使用完毕后客户端的正确释放这是官方示例统一遵循的资源管理模式。创建与复用 Agent 定义新建 Agent 定义客户端初始化完成后通过client.agents.create_agent(...)创建 Agent 定义再以client和definition实例化AzureAIAgent# Create agent definition agent_definition await client.agents.create_agent( modelai_agent_settings.model_deployment_name, nameAGENT_NAME, instructionsAGENT_INSTRUCTIONS, ) # Create the AzureAI Agent agent AzureAIAgent( clientclient, definitionagent_definition, )此后即可创建 thread、向 Agent 追加聊天消息并调用agent.invoke(...)传入输入与可选参数进行交互。create_agent还可以接收tools、tool_resources、headers如启用预览功能的{x-ms-enable-preview: true}等参数用于在定义阶段就挂载工具。复用已有 Agent 定义某些场景下例如 Agent 已在门户中配置好工具、参数或知识源与其每次新建不如直接复用。此时把create_agent换成get_agent即可agent_definition await client.agents.get_agent(agent_id)这与设置类中的agent_id字段是配套能力。仓库中还提供了专门演示该模式的示例step7_azure_ai_agent_retrieval.py位于 python/samples/getting_started_with_agents/azure_ai_agent 目录。实战示例运行 azure_ai_agent_azure_ai_search.py示例目录 README 重点讲解的azure_ai_agent_azure_ai_search.py完整源码见 python/samples/concepts/agents/azure_ai_agent/azure_ai_agent_azure_ai_search.py演示如何创建一个挂载 Azure AI Search 工具的 Agent基于官方hotels-sample-index回答关于酒店的问题。前置条件运行该示例前需要满足Azure AI Agent 项目采用 Standard 配置Python / Azure SDK 标签页的快速开始Azure AI Search 服务中已创建名为hotels-sample-index的有效索引示例查询的是 Azure AI Search 自带的酒店演示数据。README 同时指出配置索引的方式不止一种除了参考示例数据模型的方式外也可以遵循 Azure AI Search 资源中 Import and Vectorize Data 等官方教程来创建索引并生成向量Agent 项目已配置对应的 Knowledge Source使 Agent 具备使用 Azure AI Search 工具的权限。关键调用链拆解示例的核心流程可以拆解为四步第一步初始化客户端与设置ai_agent_settings AzureAIAgentSettings() async with ( AzureCliCredential() as creds, AzureAIAgent.create_client(credentialcreds, endpointai_agent_settings.endpoint) as client, ):第二步发现 Search 连接并构建工具ai_search_conn_id async for connection in client.connections.list(): if connection.type ConnectionType.AZURE_AI_SEARCH: ai_search_conn_id connection.id break ai_search AzureAISearchTool(index_connection_idai_search_conn_id, index_nameAZURE_AI_SEARCH_INDEX_NAME)这里通过client.connections.list()遍历项目已配置的连接按ConnectionType.AZURE_AI_SEARCH筛选出 Search 连接的 ID再据此构造AzureAISearchTool。注意示例默认的索引名为hotels-sample-index如需更换请同步修改源码顶部的常量。第三步创建带工具的 Agent 定义agent_definition await client.agents.create_agent( modelai_agent_settings.model_deployment_name, instructionsAnswer questions about hotels using your index., toolsai_search.definitions, tool_resourcesai_search.resources, headers{x-ms-enable-preview: true}, ) agent AzureAIAgent( clientclient, definitionagent_definition, )tools传入AzureAISearchTool的工具定义tool_resources传入工具所需的资源描述索引连接与索引名二者共同把检索能力绑定到 Agent 上。第四步线程内多轮对话与清理thread: AzureAIAgentThread None user_inputs [ Which hotels are available with full-sized kitchens in Nashville, TN?, Fun hotels with free WiFi., ] try: for user_input in user_inputs: print(f# User: {user_input}\n) async for response in agent.invoke(messagesuser_input, threadthread): print(f# Agent: {response}\n) thread response.thread finally: # Cleanup: Delete the thread and agent await thread.delete() if thread else None await client.agents.delete_agent(agent.id)几个值得注意的细节thread初始为None第一次invoke时服务端会自动创建线程并通过response.thread返回把返回值赋回thread即可实现多轮对话的上下文延续示例在finally中显式删除线程与 Agent这是避免在 Azure 侧遗留资源的推荐做法从示例附带的运行输出可以看到Agent 的回答中带有【3:0†source】这类引用标记表明检索到的酒店信息确实来源于索引命中这正是 Search 工具在推理链路中生效的直接证据。请求与速率限制降低轮询频率的两种方式默认情况下Semantic Kernel 的 Agent 对 run 状态的轮询间隔为250 ms。当你的默认请求限额较低时高频轮询可能很快触达 API 请求限制。官方给出两种应对方案方案一调整 AzureAIAgent 的 polling_options通过RunPollingOptions把轮询间隔从默认 250ms 放慢到 1 秒或任意偏好值以显著减少 API 调用次数# Required imports from datetime import timedelta from semantic_kernel.agents.run_polling_options import RunPollingOptions # Configure the polling options as part of the AzureAIAgent agent AzureAIAgent( clientclient, definitionagent_definition, polling_optionsRunPollingOptions(run_polling_intervaltimedelta(seconds1)), )run_polling_interval使用datetime.timedelta表达语义直观。代价是单次运行的完成延迟可能略有上升——轮询间隔变长后对 run 状态变化的感知会变慢适合对实时性要求不高的批处理场景。方案二在 Azure AI Foundry 中提升速率限制也可以在 Azure AI Foundry 门户中进入项目部署设置Connected Azure OpenAI Service Resource调高部署的Rate LimitTokens per minute。由于Requests per minute限额与 Token 限额联动提升 Token 限额即可间接放宽每分钟请求数从根源上缓解限额压力。两种方式可组合使用业务侧调大轮询间隔以降低请求频率平台侧提升限额以扩大请求预算从而让示例或生产代码在限流环境下更稳定地运行。小结围绕 Azure AI Agents本仓库沉淀了一套清晰的使用范式AzureAIAgentSettings负责从环境变量收敛配置AzureCliCredentialAzureAIAgent.create_client负责认证与客户端生命周期create_agent/get_agent负责定义的新建与复用AzureAISearchTool等工具对象负责能力挂载RunPollingOptions负责在限额约束下调节轮询节奏。若想进一步深入可继续阅读同目录下的流式输出、函数调用过滤器、MCP、声明式 Agent 等示例它们共享同一套初始化骨架区别仅在于工具与调用方式的不同。【免费下载链接】semantic-kernelIntegrate cutting-edge LLM technology quickly and easily into your apps项目地址: https://gitcode.com/GitHub_Trending/se/semantic-kernel创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 使用 Semantic Kernel Python 构建 Azure AI Agents：环境配置、Agent 定义与速率限制实战指南
使用 Semantic Kernel Python 构建 Azure AI Agents环境配置、Agent 定义与速率限制实战指南【免费下载链接】semantic-kernelIntegrate cutting-edge LLM technology quickly and easily into your apps项目地址: https://gitcode.com/GitHub_Trending/se/semantic-kernel导读本文围绕 Semantic Kernel Python 仓库中azure_ai_agent概念示例集及其配套 README系统讲解如何基于 Azure AI Agents 服务创建、配置并运行 Agent从.env环境变量、Azure CLI 凭据与项目客户端的初始化到 Agent 定义的新建与复用、Azure AI Search 工具挂载再到轮询间隔与速率限制的调优。读完本文你将能够独立跑通azure_ai_agent_azure_ai_search.py这类示例并把其中沉淀的配置模式迁移到自己的业务场景中。示例集概览azure_ai_agent 提供了哪些能力在 python/samples/concepts/agents/azure_ai_agent 目录下Semantic Kernel 提供了 26 个围绕 Azure AI Agent 的概念示例覆盖了该功能面的大部分使用形态基础能力azure_ai_agent_streaming.py流式输出、azure_ai_agent_message_callback.py及其_streaming变体消息回调、azure_ai_agent_prompt_templating.py提示词模板、azure_ai_agent_structured_outputs.py结构化输出、azure_ai_agent_truncation_strategy.py截断策略工具挂载azure_ai_agent_azure_ai_search.pyAzure AI Search 检索、azure_ai_agent_bing_grounding.pyBing 联网搜索、azure_ai_agent_code_interpreter_streaming_with_message_callback.py代码解释器、azure_ai_agent_file_manipulation.py文件操作、azure_ai_agent_mcp_streaming.pyMCP 集成、azure_ai_agent_deep_research_streaming.py深度研究函数与过滤器azure_ai_agent_as_kernel_function.pyAgent 作为 Kernel Function、azure_ai_agent_auto_func_invocation_filter.py及其流式变体自动函数调用过滤器声明式 Agentazure_ai_agent_declarative_*.py一组示例涵盖 Azure AI Search、Bing Grounding、Code Interpreter、File Search、函数调用、OpenAPI、模板化以及基于已有 Agent ID 复用等场景。配套的 README 位于 python/samples/getting_started_with_agents/azure_ai_agent/README.md是理解这些示例前置条件与运行方式的第一手资料下文展开的内容均以它和示例源码为基准。环境准备安装依赖与配置.env安装可选 Azure 依赖运行任何 Azure AI Agent 示例前需要安装带azure可选依赖的 Semantic Kernel Python 包pip install semantic-kernel官方快速开始文档建议参照 Azure AI 服务Quickstart: Create a new agentPython / Azure SDK 标签页完成资源创建且 Azure AI Agent 资源至少应配置为Basic 或 Standard SKU部分高级工具能力需要 Standard。配置环境变量在仓库根目录放置.env文件写入如下三项AZURE_AI_AGENT_ENDPOINT example-endpoint-string AZURE_AI_AGENT_MODEL_DEPLOYMENT_NAME example-deployment-name AZURE_AI_AGENT_API_VERSION example-api-version其中 endpoint 的格式为https://resource.services.ai.azure.com/api/projects/project-name可以在 Azure AI Foundry 门户ai.azure.com的项目详情页找到。这些环境变量与源码中的设置类一一对应。查看 python/semantic_kernel/agents/azure_ai/azure_ai_agent_settings.py 可以看到AzureAIAgentSettings的完整定义env_prefix: ClassVar[str] AZURE_AI_AGENT_ model_deployment_name: str endpoint: str | None None agent_id: str | None None bing_connection_id: str | None None azure_ai_search_connection_id: str | None None azure_ai_search_index_name: str | None None api_version: str | None None deep_research_model: str | None None它继承自KernelBaseSettingsenv_prefix AZURE_AI_AGENT_决定了配置项的读取前缀。从中可以注意到两点除文档提及的三项外设置类还支持agent_id复用已有 Agent、bing_connection_id、azure_ai_search_connection_id、azure_ai_search_index_name对应 Search / Bing 工具的连接配置分别由AZURE_AI_AGENT_BING_CONNECTION_ID等环境变量注入、deep_research_model深度研究模型等可选字段除model_deployment_name为必填外其余字段均可选——这意味你可以直接在代码中构造AzureAIAgentSettings并手动指定 endpoint / api_version而不必全部依赖环境变量。配置 AI Project Client凭据与客户端初始化认证方式所有 Azure AI Agent 示例都采用 Azure CLI 凭据进行认证。运行前需先在终端执行az login完成登录然后在代码中引入异步凭据类from azure.identity.aio import AzureCliCredential创建项目客户端最简洁的初始化方式是结合异步上下文管理器async with ( AzureCliCredential() as creds, AzureAIAgent.create_client(credentialcreds) as client, ): # Your operational code here也可以显式传入 endpoint 与可选的 api-versionapi_version 不传时使用服务端默认值ai_agent_settings AzureAIAgentSettings() async with ( AzureCliCredential() as creds, AzureAIAgent.create_client( credentialcreds, endpointai_agent_settings.endpoint, api_versionai_agent_settings.api_version, ) as client, ): # operational logicAzureAIAgent.create_client(...)内部完成 Azure AI Projects 客户端的构建与连接管理async with保证了使用完毕后客户端的正确释放这是官方示例统一遵循的资源管理模式。创建与复用 Agent 定义新建 Agent 定义客户端初始化完成后通过client.agents.create_agent(...)创建 Agent 定义再以client和definition实例化AzureAIAgent# Create agent definition agent_definition await client.agents.create_agent( modelai_agent_settings.model_deployment_name, nameAGENT_NAME, instructionsAGENT_INSTRUCTIONS, ) # Create the AzureAI Agent agent AzureAIAgent( clientclient, definitionagent_definition, )此后即可创建 thread、向 Agent 追加聊天消息并调用agent.invoke(...)传入输入与可选参数进行交互。create_agent还可以接收tools、tool_resources、headers如启用预览功能的{x-ms-enable-preview: true}等参数用于在定义阶段就挂载工具。复用已有 Agent 定义某些场景下例如 Agent 已在门户中配置好工具、参数或知识源与其每次新建不如直接复用。此时把create_agent换成get_agent即可agent_definition await client.agents.get_agent(agent_id)这与设置类中的agent_id字段是配套能力。仓库中还提供了专门演示该模式的示例step7_azure_ai_agent_retrieval.py位于 python/samples/getting_started_with_agents/azure_ai_agent 目录。实战示例运行 azure_ai_agent_azure_ai_search.py示例目录 README 重点讲解的azure_ai_agent_azure_ai_search.py完整源码见 python/samples/concepts/agents/azure_ai_agent/azure_ai_agent_azure_ai_search.py演示如何创建一个挂载 Azure AI Search 工具的 Agent基于官方hotels-sample-index回答关于酒店的问题。前置条件运行该示例前需要满足Azure AI Agent 项目采用 Standard 配置Python / Azure SDK 标签页的快速开始Azure AI Search 服务中已创建名为hotels-sample-index的有效索引示例查询的是 Azure AI Search 自带的酒店演示数据。README 同时指出配置索引的方式不止一种除了参考示例数据模型的方式外也可以遵循 Azure AI Search 资源中 Import and Vectorize Data 等官方教程来创建索引并生成向量Agent 项目已配置对应的 Knowledge Source使 Agent 具备使用 Azure AI Search 工具的权限。关键调用链拆解示例的核心流程可以拆解为四步第一步初始化客户端与设置ai_agent_settings AzureAIAgentSettings() async with ( AzureCliCredential() as creds, AzureAIAgent.create_client(credentialcreds, endpointai_agent_settings.endpoint) as client, ):第二步发现 Search 连接并构建工具ai_search_conn_id async for connection in client.connections.list(): if connection.type ConnectionType.AZURE_AI_SEARCH: ai_search_conn_id connection.id break ai_search AzureAISearchTool(index_connection_idai_search_conn_id, index_nameAZURE_AI_SEARCH_INDEX_NAME)这里通过client.connections.list()遍历项目已配置的连接按ConnectionType.AZURE_AI_SEARCH筛选出 Search 连接的 ID再据此构造AzureAISearchTool。注意示例默认的索引名为hotels-sample-index如需更换请同步修改源码顶部的常量。第三步创建带工具的 Agent 定义agent_definition await client.agents.create_agent( modelai_agent_settings.model_deployment_name, instructionsAnswer questions about hotels using your index., toolsai_search.definitions, tool_resourcesai_search.resources, headers{x-ms-enable-preview: true}, ) agent AzureAIAgent( clientclient, definitionagent_definition, )tools传入AzureAISearchTool的工具定义tool_resources传入工具所需的资源描述索引连接与索引名二者共同把检索能力绑定到 Agent 上。第四步线程内多轮对话与清理thread: AzureAIAgentThread None user_inputs [ Which hotels are available with full-sized kitchens in Nashville, TN?, Fun hotels with free WiFi., ] try: for user_input in user_inputs: print(f# User: {user_input}\n) async for response in agent.invoke(messagesuser_input, threadthread): print(f# Agent: {response}\n) thread response.thread finally: # Cleanup: Delete the thread and agent await thread.delete() if thread else None await client.agents.delete_agent(agent.id)几个值得注意的细节thread初始为None第一次invoke时服务端会自动创建线程并通过response.thread返回把返回值赋回thread即可实现多轮对话的上下文延续示例在finally中显式删除线程与 Agent这是避免在 Azure 侧遗留资源的推荐做法从示例附带的运行输出可以看到Agent 的回答中带有【3:0†source】这类引用标记表明检索到的酒店信息确实来源于索引命中这正是 Search 工具在推理链路中生效的直接证据。请求与速率限制降低轮询频率的两种方式默认情况下Semantic Kernel 的 Agent 对 run 状态的轮询间隔为250 ms。当你的默认请求限额较低时高频轮询可能很快触达 API 请求限制。官方给出两种应对方案方案一调整 AzureAIAgent 的 polling_options通过RunPollingOptions把轮询间隔从默认 250ms 放慢到 1 秒或任意偏好值以显著减少 API 调用次数# Required imports from datetime import timedelta from semantic_kernel.agents.run_polling_options import RunPollingOptions # Configure the polling options as part of the AzureAIAgent agent AzureAIAgent( clientclient, definitionagent_definition, polling_optionsRunPollingOptions(run_polling_intervaltimedelta(seconds1)), )run_polling_interval使用datetime.timedelta表达语义直观。代价是单次运行的完成延迟可能略有上升——轮询间隔变长后对 run 状态变化的感知会变慢适合对实时性要求不高的批处理场景。方案二在 Azure AI Foundry 中提升速率限制也可以在 Azure AI Foundry 门户中进入项目部署设置Connected Azure OpenAI Service Resource调高部署的Rate LimitTokens per minute。由于Requests per minute限额与 Token 限额联动提升 Token 限额即可间接放宽每分钟请求数从根源上缓解限额压力。两种方式可组合使用业务侧调大轮询间隔以降低请求频率平台侧提升限额以扩大请求预算从而让示例或生产代码在限流环境下更稳定地运行。小结围绕 Azure AI Agents本仓库沉淀了一套清晰的使用范式AzureAIAgentSettings负责从环境变量收敛配置AzureCliCredentialAzureAIAgent.create_client负责认证与客户端生命周期create_agent/get_agent负责定义的新建与复用AzureAISearchTool等工具对象负责能力挂载RunPollingOptions负责在限额约束下调节轮询节奏。若想进一步深入可继续阅读同目录下的流式输出、函数调用过滤器、MCP、声明式 Agent 等示例它们共享同一套初始化骨架区别仅在于工具与调用方式的不同。【免费下载链接】semantic-kernelIntegrate cutting-edge LLM technology quickly and easily into your apps项目地址: https://gitcode.com/GitHub_Trending/se/semantic-kernel创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考