Agent Framework Azure 托管智能体
使用微软 Agent Framework Python SDK 在 Azure AI Foundry 上构建持久化智能体。
架构
用户查询 → AzureAIAgentsProvider → Azure AI Agent 服务(持久化)
↓
Agent.run() / Agent.run_stream()
↓
工具:函数 | 托管(代码/搜索/网络)| MCP
↓
AgentThread(对话持久化)
安装
# 完整框架(推荐)
pip install agent-framework --pre
# 或仅安装 Azure 特定包
pip install agent-framework-azure-ai --pre
环境变量
export AZURE_AI_PROJECT_ENDPOINT="https://<project>.services.ai.azure.com/api/projects/<project-id>" # 所有认证方式必需
export AZURE_AI_MODEL_DEPLOYMENT_NAME="gpt-4o-mini" # 所有认证方式必需
export BING_CONNECTION_ID="your-bing-connection-id" # 用于网络搜索
export AZURE_TOKEN_CREDENTIALS=prod # 仅当在生产环境使用 DefaultAzureCredential 时需要
认证与生命周期
🔑 以下每个代码示例都适用两条规则:
- 优先使用
DefaultAzureCredential。它在本地(Azure CLI / VS Code / 开发者 CLI)和 Azure(托管标识、工作负载标识)中无需更改代码即可工作。避免使用连接字符串、帐户/API 密钥——它们会绕过 Entra 审计和轮换。
- 本地开发:
DefaultAzureCredential开箱即用。- 生产环境:设置
AZURE_TOKEN_CREDENTIALS=prod(或AZURE_TOKEN_CREDENTIALS=<specific_credential>)以将凭据链限制为生产环境安全的凭据。- 将每个客户端包装在上下文管理器内,以便确定性地释放 HTTP 传输、套接字和令牌缓存:
- 同步:
with <Client>(...) as client:- 异步:
async with <Client>(...) as client:以及async with DefaultAzureCredential() as credential:(来自azure.identity.aio)代码片段可能省略此设置,但生产代码应始终遵循两条规则。
from azure.identity.aio import AzureCliCredential, DefaultAzureCredential, ManagedIdentityCredential
# 开发环境
credential = AzureCliCredential()
# 生产环境
# 本地开发:DefaultAzureCredential。生产环境:设置 AZURE_TOKEN_CREDENTIALS=prod 或 AZURE_TOKEN_CREDENTIALS=<specific_credential>
credential = DefaultAzureCredential(require_envvar=True)
# 或者在生产环境中直接使用特定凭据:
# 参见 https://learn.microsoft.com/python/api/overview/azure/identity-readme?view=azure-python#credential-classes
# credential = ManagedIdentityCredential()
核心工作流
基本智能体
import asyncio
from agent_framework.azure import AzureAIAgentsProvider
from azure.identity.aio import AzureCliCredential
async def main():
async with (
AzureCliCredential() as credential,
AzureAIAgentsProvider(credential=credential) as provider,
):
agent = await provider.create_agent(
name="MyAgent",
instructions="你是一个有用的助手。",
)
result = await agent.run("你好!")
print(result.text)
asyncio.run(main())
带函数工具的智能体
from typing import Annotated
from pydantic import Field
from agent_framework.azure import AzureAIAgentsProvider
from azure.identity.aio import AzureCliCredential
def get_weather(
location: Annotated[str, Field(description="要获取天气的城市名称")],
) -> str:
"""获取某个位置的当前天气。"""
return f"{location} 的天气:72°F,晴朗"
def get_current_time() -> str:
"""获取当前 UTC 时间。"""
from datetime import datetime, timezone
return datetime.now(timezone.utc).strftime("%Y-%m-%d %H:%M:%S UTC")
async def main():
async with (
AzureCliCredential() as credential,
AzureAIAgentsProvider(credential=credential) as provider,
):
agent = await provider.create_agent(
name="WeatherAgent",
instructions="你帮助处理天气和时间查询。",
tools=[get_weather, get_current_time], # 直接传入函数
)
result = await agent.run("西雅图的天气怎么样?")
print(result.text)
带托管工具的智能体
from agent_framework import (
HostedCodeInterpreterTool,
HostedFileSearchTool,
HostedWebSearchTool,
)
from agent_framework.azure import AzureAIAgentsProvider
from azure.identity.aio import AzureCliCredential
async def main():
async with (
AzureCliCredential() as credential,
AzureAIAgentsProvider(credential=credential) as provider,
):
agent = await provider.create_agent(
name="MultiToolAgent",
instructions="你可以执行代码、搜索文件和搜索网络。",
tools=[
HostedCodeInterpreterTool(),
HostedWebSearchTool(name="Bing"),
],
)
result = await agent.run("用 Python 计算 20 的阶乘")
print(result.text)
流式响应
async def main():
async with (
AzureCliCredential() as credential,
AzureAIAgentsProvider(credential=credential) as provider,
):
agent = await provider.create_agent(
name="StreamingAgent",
instructions="你是一个有用的助手。",
)
print("智能体:", end="", flush=True)
async for chunk in agent.run_stream("给我讲一个短故事"):
if chunk.text:
print(chunk.text, end="", flush=True)
print()
对话线程
from agent_framework.azure import AzureAIAgentsProvider
from azure.identity.aio import AzureCliCredential
async def main():
async with (
AzureCliCredential() as credential,
AzureAIAgentsProvider(credential=credential) as provider,
):
agent = await provider.create_agent(
name="ChatAgent",
instructions="你是一个有用的助手。",
tools=[get_weather],
)
# 创建线程用于对话持久化
thread = agent.get_new_thread()
# 第一轮
result1 = await agent.run("西雅图的天气怎么样?", thread=thread)
print(f"智能体:{result1.text}")
# 第二轮 - 上下文得以保留
result2 = await agent.run("波特兰呢?", thread=thread)
print(f"智能体:{result2.text}")
# 保存线程 ID 以便后续恢复
print(f"对话 ID:{thread.conversation_id}")
结构化输出
from pydantic import BaseModel, ConfigDict
from agent_framework.azure import AzureAIAgentsProvider
from azure.identity.aio import AzureCliCredential
class WeatherResponse(BaseModel):
model_config = ConfigDict(extra="forbid")
location: str
temperature: float
unit: str
conditions: str
async def main():
async with (
AzureCliCredential() as credential,
AzureAIAgentsProvider(credential=credential) as provider,
):
agent = await provider.create_agent(
name="StructuredAgent",
instructions="以结构化格式提供天气信息。",
response_format=WeatherResponse,
)
result = await agent.run("西雅图的天气?")
weather = WeatherResponse.model_validate_json(result.text)
print(f"{weather.location}:{weather.temperature}°{weather.unit}")
Provider 方法
| 方法 | 描述 |
|---|---|
create_agent() | 在 Azure AI 服务上创建新的智能体 |
get_agent(agent_id) | 通过 ID 检索现有智能体 |
as_agent(sdk_agent) | 包装 SDK Agent 对象(无 HTTP 调用) |
托管工具快速参考
| 工具 | 导入 | 用途 |
|---|---|---|
HostedCodeInterpreterTool | from agent_framework import HostedCodeInterpreterTool | 执行 Python 代码 |
HostedFileSearchTool | from agent_framework import HostedFileSearchTool | 搜索向量存储 |
HostedWebSearchTool | from agent_framework import HostedWebSearchTool | Bing 网络搜索 |
HostedMCPTool | from agent_framework import HostedMCPTool | 服务管理的 MCP |
MCPStreamableHTTPTool | from agent_framework import MCPStreamableHTTPTool | 客户端管理的 MCP |
完整示例
import asyncio
from typing import Annotated
from pydantic import BaseModel, Field
from agent_framework import (
HostedCodeInterpreterTool,
HostedWebSearchTool,
MCPStreamableHTTPTool,
)
from agent_framework.azure import AzureAIAgentsProvider
from azure.identity.aio import AzureCliCredential
def get_weather(
location: Annotated[str, Field(description="城市名称")],
) -> str:
"""获取某个位置的天气。"""
return f"{location} 的天气:72°F,晴朗"
class AnalysisResult(BaseModel):
summary: str
key_findings: list[str]
confidence: float
async def main():
async with (
AzureCliCredential() as credential,
MCPStreamableHTTPTool(
name="Docs MCP",
url="https://learn.microsoft.com/api/mcp",
) as mcp_tool,
AzureAIAgentsProvider(credential=credential) as provider,
):
agent = await provider.create_agent(
name="ResearchAssistant",
instructions="你是一个具有多种能力的研究助手。",
tools=[
get_weather,
HostedCodeInterpreterTool(),
HostedWebSearchTool(name="Bing"),
mcp_tool,
],
)
thread = agent.get_new_thread()
# 非流式
result = await agent.run(
"搜索 Python 最佳实践并总结",
thread=thread,
)
print(f"响应:{result.text}")
# 流式
print("\n流式输出:", end="")
async for chunk in agent.run_stream("继续举例", thread=thread):
if chunk.text:
print(chunk.text, end="", flush=True)
print()
# 结构化输出
result = await agent.run(
"分析发现",
thread=thread,
response_format=AnalysisResult,
)
analysis = AnalysisResult.model_validate_json(result.text)
print(f"\n置信度:{analysis.confidence}")
if __name__ == "__main__":
asyncio.run(main())
约定
- 始终使用异步上下文管理器:
async with provider: - 将函数直接传递给
tools=参数(自动转换为 AIFunction) - 对函数参数使用
Annotated[type, Field(description=...)] - 对于多轮对话使用
get_new_thread() - 对于服务管理的 MCP 优先使用
HostedMCPTool,对于客户端管理的 MCP 使用MCPStreamableHTTPTool
最佳实践
- 此 SDK 以异步为首要——全程使用
async def处理程序和async with。 - 始终对客户端和异步凭据使用上下文管理器。 将每个客户端包装在
with Client(...) as client:(同步)或async with Client(...) as client:(异步)中。对于来自azure.identity.aio的异步DefaultAzureCredential,也要使用async with credential:,以便令牌和传输能够被清理。
参考文件
- references/tools.md:详细的托管工具模式
- references/mcp.md:MCP 集成(托管 + 本地)
- references/threads.md:线程和对话管理
- references/advanced.md:OpenAPI、引用、结构化输出