Semantic Kernel 使用 Azure AI Agents 入门指南从环境配置到限流优化【免费下载链接】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 编写的中文技术指南核心主题是在 Semantic Kernel 中接入 Azure AI FoundryAzure AI Agents 服务并完成 Agent 的创建、调用与性能调优。读完本文你将掌握.env环境变量与 Azure CLI 认证的配置方法、AzureAIAgent.create_client项目客户端与AzureAIAgent的初始化方式、Agent 定义的新建与复用技巧以及通过RunPollingOptions调整轮询频率和提升 Azure AI Foundry 速率限制的实战方案。示例代码全部来自 python/samples/getting_started_with_agents/azure_ai_agent 目录源码佐证来自 python/semantic_kernel/agents/azure_ai 目录。1. 前置准备资源、依赖与认证1.1 创建 Azure AI Agent 资源在使用 Semantic Kernel 连接 Azure AI Agents 之前需要先在 Azure 侧准备资源。仓库 README 建议按照微软官方 Quickstart: Create a new agent 指南完成资源创建需要特别注意的是你的 Azure AI Agent 资源必须配置为至少 Basic 或 Standard SKU否则后续的客户端初始化与运行轮询可能无法正常工作。说明官方快速入门指南要求你预先创建好 Azure AI Foundry 项目并部署一个模型本文不再赘述其 Web 端操作细节聚焦于 Semantic Kernel 侧的代码集成。1.2 安装 Semantic Kernel 的 azure 依赖如果尚未安装 Semantic Kernel需要先通过 pip 安装。官方文档说明 Azure AI Agent 功能位于可选的azure依赖包中pip install semantic-kernel当前仓库的 Python 实现中Azure AI Agent 相关代码位于 python/semantic_kernel/agents/azure_ai 目录核心类AzureAIAgent标注了experimental装饰器见 azure_ai_agent.py说明该功能仍处于实验阶段API 可能随版本演进发生变化。1.3 配置 .env 环境变量在运行任何 Azure AI Agent 示例之前需要在仓库根目录下的.env文件中写入以下三个关键配置README 明确要求.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这三个变量与源码中AzureAIAgentSettings的字段一一对应。从 azure_ai_agent_settings.py 可以看到AzureAIAgentSettings继承自KernelBaseSettings其env_prefix固定为AZURE_AI_AGENT_各字段及对应的环境变量如下设置字段环境变量是否必填说明model_deployment_nameAZURE_AI_AGENT_MODEL_DEPLOYMENT_NAME是Azure AI Foundry 中部署的模型部署名称endpointAZURE_AI_AGENT_ENDPOINT否建议填Foundry 项目端点格式见下文api_versionAZURE_AI_AGENT_API_VERSION否Azure AI Agents API 版本号agent_idAZURE_AI_AGENT_AGENT_ID否复用已有 Agent 时的 IDbing_connection_idAZURE_AI_AGENT_BING_CONNECTION_ID否Bing 搜索连接 ID用于 Bing Grounding 工具azure_ai_search_connection_idAZURE_AI_AGENT_AZURE_AI_SEARCH_CONNECTION_ID否Azure AI Search 连接 IDazure_ai_search_index_nameAZURE_AI_AGENT_AZURE_AI_SEARCH_INDEX_NAME否Azure AI Search 索引名称deep_research_modelAZURE_AI_AGENT_DEEP_RESEARCH_MODEL否Deep Research 使用的模型endpoint 格式README 说明端点可以在 Azure AI Foundry 门户ai.azure.com中查到其格式为https://resource.services.ai.azure.com/api/projects/project-name其中resource是你的 Azure AI 资源名称project-name是 Foundry 项目名称。提示如果你不想把endpoint写在.env里也可以在调用AzureAIAgent.create_client(...)时通过endpoint参数显式传入详见第 2 节。1.4 使用 Azure CLI 完成身份认证仓库 README 与示例代码均采用AzureCliCredential进行认证这是 Azure Identity SDK 提供的异步凭据类。运行示例前需要先在 shell 中执行az login该命令会打开浏览器引导你登录 Azure 账号登录成功后AzureCliCredential即可自动使用当前 CLI 登录态访问 Azure 服务。所有示例代码都使用异步版本的凭据类from azure.identity.aio import AzureCliCredential注意必须从azure.identity.aio导入异步版本因为AzureAIAgent的客户端是异步的AIProjectClient见 azure_ai_agent.py 中client: AIProjectClient的类型声明。2. 创建 AI Project 客户端2.1 最小可用写法配置好环境变量并完成登录后第一步是创建项目客户端。README 给出的最小写法如下async with ( AzureCliCredential() as creds, AzureAIAgent.create_client(credentialcreds) as client, ): # Your operational code here这里使用 Python 的async with将凭据与客户端组合成上下文管理器确保资源被正确释放。create_client是AzureAIAgent的静态工厂方法源码见 azure_ai_agent.py其内部逻辑是若未显式传入endpoint则实例化AzureAIAgentSettings()并从环境变量读取端点若仍为空则抛出AgentInitializationException(Please provide a valid Azure AI endpoint.)若传入了api_version则附加到客户端参数中若检测到应用信息APP_INFO则自动附加 Semantic Kernel 的用户代理字符串SEMANTIC_KERNEL_USER_AGENT最终返回一个AIProjectClient来自azure.ai.projects.aio。2.2 显式传入端点与 API 版本README 也给出了显式传参的写法适合不想或不能依赖.env文件的场景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 logic此处直接从AzureAIAgentSettings()读取endpoint与api_version字段——它们分别对应.env中的AZURE_AI_AGENT_ENDPOINT与AZURE_AI_AGENT_API_VERSION。3. 创建 Agent 定义并初始化 AzureAIAgent3.1 创建新的 Agent 定义客户端就绪后即可在 Azure AI Agent 服务上创建 Agent 定义。README 给出的核心代码# Create agent definition agent_definition await client.agents.create_agent( modelai_agent_settings.model_deployment_name, nameAGENT_NAME, instructionsAGENT_INSTRUCTIONS, )create_agent的三个核心参数含义model模型部署名称对应环境变量AZURE_AI_AGENT_MODEL_DEPLOYMENT_NAMEnameAgent 在服务端的显示名称instructions系统提示词定义 Agent 的行为准则。3.2 实例化 Semantic Kernel 的 AzureAIAgent拿到agent_definition后将它和client一起交给 Semantic Kernel 的AzureAIAgent类完成包装# Create the AzureAI Agent agent AzureAIAgent( clientclient, definitionagent_definition, )从源码看AzureAIAgent.__init__见 azure_ai_agent.py会自动从definition中提取name、description、id与instructions等字段填充到 Agent 对象中如果definition没有名称则会用随机 ASCII 名称兜底azure_agent_8位随机串。此外AzureAIAgent还支持传入kernel、plugins、arguments、prompt_template_config、polling_options、mcp_tool_approval_callback等可选参数。3.3 发起对话并处理线程Agent 包装完成后就可以创建线程thread、向 Agent 发送消息并取得回复。完整的端到端流程可以参考入门示例 step01_azure_ai_agent.py其核心逻辑如下# 1. 创建 Agent 定义 agent_definition await client.agents.create_agent( modelAzureAIAgentSettings().model_deployment_name, nameAssistant, instructionsAnswer the users questions., ) # 2. 包装为 Semantic Kernel Agent agent AzureAIAgent(clientclient, definitionagent_definition) # 3. 线程初始为 None首次调用会自动创建 thread: AzureAIAgentThread None try: for user_input in USER_INPUTS: response await agent.get_response(messagesuser_input, threadthread) print(f# {response.name}: {response}) thread response.thread # 用返回的线程继续下一轮对话 finally: # 4. 清理删除线程与 Agent await thread.delete() if thread else None await client.agents.delete_agent(agent.id)这个示例有几个值得注意的实现细节线程由服务端维护示例注释明确指出对话历史由 Agent 服务自动与线程关联客户端代码无需自行维护聊天记录。AzureAIAgentThread的实现见 azure_ai_agent.py内部封装了threads.create/threads.delete/get_messages等操作。get_response与invoke的区别get_response返回单个最终回复AgentResponseItem适合一问一答invoke是异步生成器可以逐个产出可见消息并支持on_intermediate_message回调处理中间步骤如函数调用过程invoke_stream则提供流式输出。三者都是AzureAIAgent的公开方法源码 azure_ai_agent.py。消息参数灵活性get_response/invoke的messages参数既可以是str也可以是ChatMessageContent还可以是两者的列表。3.4 复用已有 Agent 定义在某些场景下例如 Agent 已在 Azure 门户或 CLI 中创建、或希望跨多次运行复用同一个 Agent无需重复创建可以直接通过 Agent ID 获取已有定义agent_definition await client.agents.get_agent( agent_idyour-agent-id, )之后照常包装为AzureAIAgent即可。README 指出此用法对应的完整示例是 step07_azure_ai_agent_retrieval.py。该示例还演示了另一个细节复用 Agent 时不要在清理阶段删除 Agent 定义——示例中只删除了线程注释明确写道 Do not clean up the agent so it can be used again以保证下次仍能按同一agent_id取回。如果希望在代码中通过agent_id环境变量AZURE_AI_AGENT_AGENT_ID来定位 Agent可以将其填入.env然后在get_agent中读取AzureAIAgentSettings().agent_id。3.5 进阶为 Agent 挂载 Plugin 与声明式 YAML虽然 README 本身聚焦于基础流程但仓库中的相邻示例可以帮你快速拓展能力为 Agent 添加 Semantic Kernel Plugin参考 step02_azure_ai_agent_plugin.py只需在构造AzureAIAgent时传入plugins[MenuPlugin()]Agent 即可在对话中自动调用插件函数如查询菜单特价、菜品价格。声明式 YAML 创建 Agent参考 step08_azure_ai_agent_declarative.py可通过AgentRegistry.create_from_yaml(...)从 YAML 规格创建 Agent规格中支持${AzureAI:ChatModelId}这类占位符由AzureAIAgent.resolve_placeholders解析源码见 azure_ai_agent.py。多 Agent 群聊参考 step03_azure_ai_agent_group_chat.py可将多个AzureAIAgent放入AgentGroupChat并配合自定义TerminationStrategy完成多角色协作。4. 请求频率与速率限制管理4.1 问题的来源Azure AI Agent 服务的默认请求限制可能较低这会影响轮询 Run 状态的频率上限。在 Semantic Kernel 的调用链中提交消息后框架会循环查询 Run 的执行状态直到状态变为completed。从 agent_thread_actions.py 的源码可以看到轮询循环的实现polling_status [queued, in_progress, cancelling] error_message_states [failed, cancelled, expired, incomplete] while run.status ! completed: run await cls._poll_run_status( agentagent, runrun, thread_idthread_id, polling_optionspolling_options or agent.polling_options, ) if run.status in cls.error_message_states: # 处理失败/取消/过期/不完整等终态 ...而_poll_loop内部会先按轮询间隔sleep再发起一次runs.get请求源码 agent_thread_actions.pycount 0 while True: await asyncio.sleep(polling_options.get_polling_interval(count).total_seconds()) count 1 run await agent.client.agents.runs.get(run_idrun.id, thread_idthread_id) if run.status not in cls.polling_status: break也就是说每次轮询都会产生一次对runs.get的 API 调用。默认 250ms 的轮询间隔在请求配额紧张时很容易触发限流。为此README 提供了两种解决思路。4.2 方案一调整轮询选项RunPollingOptionsAzureAIAgent接受一个polling_options参数类型为RunPollingOptions定义见 run_polling_options.py。默认轮询间隔为 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)), )RunPollingOptions中与轮询相关的字段及其默认值源码 run_polling_options.py如下字段默认值作用run_polling_interval250ms常规轮询间隔即 README 提到的默认 250msrun_polling_backoff1s超过退避阈值后使用的轮询间隔run_polling_backoff_threshold2迭代次数超过该阈值后启用退避间隔run_polling_timeout1 分钟单次 Run 轮询的总超时时间超时抛出asyncio.TimeoutErrormessage_synchronization_delay250ms消息同步延迟default_polling_interval/default_polling_backoff/default_polling_backoff_threshold/default_message_synchronization_delay同上对应的默认值备份字段轮询间隔的实际取值由get_polling_interval(iteration_count)决定见 run_polling_options.pydef get_polling_interval(self, iteration_count: int) - timedelta: return ( self.run_polling_backoff if iteration_count self.run_polling_backoff_threshold else self.run_polling_interval )即前run_polling_backoff_threshold次按run_polling_interval250ms轮询之后自动切换到run_polling_backoff1s实现前期高频、后期低频的自适应降频兼顾响应速度与请求配额。此外轮询选项还支持调用级覆盖get_response、invoke、invoke_stream都接受polling_options参数且源码注释说明运行级run-level的polling_options会覆盖 Agent 级配置见 agent_thread_actions.py 中_poll_run_status的调用处。4.3 方案二在 Azure AI Foundry 提高速率限制除了调整客户端轮询频率还可以从服务端入手直接在 Azure AI Foundry 中调整部署的限流配置。README 明确说明可以调整部署的 Rate LimitTokens per minute每分钟令牌数该数值会影响 Rate LimitRequests per minute每分钟请求数。该配置可在 Azure AI Foundry 中项目部署设置下的 Connected Azure OpenAI Service Resource已连接的 Azure OpenAI 服务资源中进行修改。操作位置Azure AI Foundry → 你的项目 → 部署Deployments→ 选择模型部署 → 速率限制设置。提高每分钟令牌配额后每分钟允许的请求数上限也会相应提升从而允许更频繁的 Run 状态轮询。4.4 两种方案的取舍维度调整RunPollingOptions提高 Foundry 速率限制生效范围仅当前 Agent/当前调用整个部署下的所有请求改动成本代码侧一行参数即刻生效门户操作需具备相应权限典型场景快速规避偶发限流、降低请求量生产环境稳定提升吞吐副作用响应延迟可能增加可能产生更高费用实际项目中建议两者结合先用RunPollingOptions将间隔调至 500ms~1s 降低请求压力再按业务量评估是否需要提升 Foundry 侧配额。5. 示例全景与后续学习路径azure_ai_agent示例目录 python/samples/getting_started_with_agents/azure_ai_agent 一共包含 10 个递进式示例可作为深入学习的地图示例文件主题step01_azure_ai_agent.py基础对话创建 Agent、线程与get_responsestep02_azure_ai_agent_plugin.py为 Agent 挂载 Semantic Kernel Pluginstep03_azure_ai_agent_group_chat.py多 Agent 群聊与终止策略step04_azure_ai_agent_code_interpreter.pyCode Interpreter 代码解释工具step05_azure_ai_agent_file_search.py文件搜索工具step06_azure_ai_agent_openapi.pyOpenAPI 工具集成step07_azure_ai_agent_retrieval.py复用已有 Agent 定义README 明确推荐step08_azure_ai_agent_declarative.py声明式 YAML 创建 Agentstep09_azure_ai_agent_mcp.pyMCPModel Context Protocol工具集成step10_azure_ai_agent_deep_research.pyDeep Research 能力如果你的项目需要团队协作或参考更多 Agent 模式可以继续阅读仓库根目录的 python/samples/getting_started_with_agents 下的其他入门指南以及 python/semantic_kernel/agents 中的 Agent 抽象与编排源码。6. 常见问题排查FAQAgentInitializationException: Please provide a valid Azure AI endpoint.说明.env未配置AZURE_AI_AGENT_ENDPOINT且调用create_client时也未显式传入endpoint。请核对.env位置必须在仓库根目录与变量名拼写。认证失败 / 403确认已在终端执行az login并登录到包含该 AI 项目的租户同时确认资源 SKU 至少为 Basic 或 Standard。频繁触发 429 限流按第 4 节方案一将run_polling_interval调大如 1s或按方案二在 Foundry 中提升每分钟令牌配额。想保留 Agent 供下次使用使用get_agent复用定义并在清理阶段只删除线程、不要删除 Agent参考 step07_azure_ai_agent_retrieval.py 的注释说明。结语本文以 Azure AI Agent 入门 README 为骨架覆盖了从.env配置、Azure CLI 认证、项目客户端创建到 Agent 定义新建/复用、线程对话再到轮询限流调优的完整链路并结合 python/semantic_kernel/agents/azure_ai 目录下的源码揭示了create_client、AzureAIAgentThread、RunPollingOptions与轮询循环的底层实现。掌握这些内容后你即可在 Semantic Kernel 项目中稳定地接入 Azure AI Agents并依据自身配额合理编排轮询策略。【免费下载链接】semantic-kernelIntegrate cutting-edge LLM technology quickly and easily into your apps项目地址: https://gitcode.com/GitHub_Trending/se/semantic-kernel创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考