Azure AI 托管 Agent (Python)
使用 Azure AI Projects SDK 中的 ImageBasedHostedAgentDefinition 构建基于容器的托管 Agent。
安装
pip install azure-ai-projects>=2.0.0b3 azure-identity
最低 SDK 版本： 2.0.0b3 或更高版本以支持托管 Agent。
环境变量
AZURE_AI_PROJECT_ENDPOINT=https://<resource>.services.ai.azure.com/api/projects/<project>
先决条件
创建托管 Agent 前需完成：
- 容器镜像 - 构建并推送到 Azure 容器注册表 (ACR)
- ACR 拉取权限 - 为项目的托管标识授予 ACR 的
AcrPull角色 - Capability Host - 账户级别的 Capability Host，设置
enablePublicHostingEnvironment=true - SDK 版本 - 确保
azure-ai-projects>=2.0.0b3
身份验证
始终使用 DefaultAzureCredential：
from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient
credential = DefaultAzureCredential()
client = AIProjectClient(
endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"],
credential=credential
)
核心工作流
1. 导入
import os
from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import (
ImageBasedHostedAgentDefinition,
ProtocolVersionRecord,
AgentProtocol,
)
2. 创建托管 Agent
client = AIProjectClient(
endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"],
credential=DefaultAzureCredential()
)
agent = client.agents.create_version(
agent_name="my-hosted-agent",
definition=ImageBasedHostedAgentDefinition(
container_protocol_versions=[
ProtocolVersionRecord(protocol=AgentProtocol.RESPONSES, version="v1")
],
cpu="1",
memory="2Gi",
image="myregistry.azurecr.io/my-agent:latest",
tools=[{"type": "code_interpreter"}],
environment_variables={
"AZURE_AI_PROJECT_ENDPOINT": os.environ["AZURE_AI_PROJECT_ENDPOINT"],
"MODEL_NAME": "gpt-4o-mini"
}
)
)
print(f"已创建 Agent: {agent.name} (版本: {agent.version})")
3. 列出 Agent 版本
versions = client.agents.list_versions(agent_name="my-hosted-agent")
for version in versions:
print(f"版本: {version.version}, 状态: {version.state}")
4. 删除 Agent 版本
client.agents.delete_version(
agent_name="my-hosted-agent",
version=agent.version
)
ImageBasedHostedAgentDefinition 参数
| 参数 | 类型 | 必需 | 描述 |
|---|---|---|---|
container_protocol_versions | list[ProtocolVersionRecord] | 是 | Agent 支持的协议版本 |
image | str | 是 | 完整容器镜像路径 (registry/image:tag) |
cpu | str | 否 | CPU 分配 (例如 "1", "2") |
memory | str | 否 | 内存分配 (例如 "2Gi", "4Gi") |
tools | list[dict] | 否 | Agent 可用的工具 |
environment_variables | dict[str, str] | 否 | 容器的环境变量 |
协议版本
container_protocol_versions 参数指定 Agent 支持的协议：
from azure.ai.projects.models import ProtocolVersionRecord, AgentProtocol
# RESPONSES 协议 - 标准 Agent 响应
container_protocol_versions=[
ProtocolVersionRecord(protocol=AgentProtocol.RESPONSES, version="v1")
]
可用协议：
| 协议 | 描述 |
|---|---|
AgentProtocol.RESPONSES | 用于 Agent 交互的标准响应协议 |
资源分配
指定容器的 CPU 和内存：
definition=ImageBasedHostedAgentDefinition(
container_protocol_versions=[...],
image="myregistry.azurecr.io/my-agent:latest",
cpu="2", # 2 个 CPU 核心
memory="4Gi" # 4 GiB 内存
)
资源限制：
| 资源 | 最小值 | 最大值 | 默认值 |
|---|---|---|---|
| CPU | 0.5 | 4 | 1 |
| 内存 | 1Gi | 8Gi | 2Gi |
工具配置
向托管 Agent 添加工具：
代码解释器
tools=[{"type": "code_interpreter"}]
MCP 工具
tools=[
{"type": "code_interpreter"},
{
"type": "mcp",
"server_label": "my-mcp-server",
"server_url": "https://my-mcp-server.example.com"
}
]
多工具
tools=[
{"type": "code_interpreter"},
{"type": "file_search"},
{
"type": "mcp",
"server_label": "custom-tool",
"server_url": "https://custom-tool.example.com"
}
]
环境变量
将配置传递给容器：
environment_variables={
"AZURE_AI_PROJECT_ENDPOINT": os.environ["AZURE_AI_PROJECT_ENDPOINT"],
"MODEL_NAME": "gpt-4o-mini",
"LOG_LEVEL": "INFO",
"CUSTOM_CONFIG": "value"
}
最佳实践： 切勿硬编码机密。使用环境变量或 Azure Key Vault。
完整示例
import os
from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import (
ImageBasedHostedAgentDefinition,
ProtocolVersionRecord,
AgentProtocol,
)
def create_hosted_agent():
"""使用自定义容器镜像创建托管 Agent。"""
client = AIProjectClient(
endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"],
credential=DefaultAzureCredential()
)
agent = client.agents.create_version(
agent_name="data-processor-agent",
definition=ImageBasedHostedAgentDefinition(
container_protocol_versions=[
ProtocolVersionRecord(
protocol=AgentProtocol.RESPONSES,
version="v1"
)
],
image="myregistry.azurecr.io/data-processor:v1.0",
cpu="2",
memory="4Gi",
tools=[
{"type": "code_interpreter"},
{"type": "file_search"}
],
environment_variables={
"AZURE_AI_PROJECT_ENDPOINT": os.environ["AZURE_AI_PROJECT_ENDPOINT"],
"MODEL_NAME": "gpt-4o-mini",
"MAX_RETRIES": "3"
}
)
)
print(f"已创建托管 Agent: {agent.name}")
print(f"版本: {agent.version}")
print(f"状态: {agent.state}")
return agent
if __name__ == "__main__":
create_hosted_agent()
异步模式
import os
from azure.identity.aio import DefaultAzureCredential
from azure.ai.projects.aio import AIProjectClient
from azure.ai.projects.models import (
ImageBasedHostedAgentDefinition,
ProtocolVersionRecord,
AgentProtocol,
)
async def create_hosted_agent_async():
"""异步创建托管 Agent。"""
async with DefaultAzureCredential() as credential:
async with AIProjectClient(
endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"],
credential=credential
) as client:
agent = await client.agents.create_version(
agent_name="async-agent",
definition=ImageBasedHostedAgentDefinition(
container_protocol_versions=[
ProtocolVersionRecord(
protocol=AgentProtocol.RESPONSES,
version="v1"
)
],
image="myregistry.azurecr.io/async-agent:latest",
cpu="1",
memory="2Gi"
)
)
return agent
常见错误
| 错误 | 原因 | 解决方案 |
|---|---|---|
ImagePullBackOff | ACR 拉取权限被拒绝 | 为项目的托管标识授予 AcrPull 角色 |
InvalidContainerImage | 镜像未找到 | 验证镜像路径和标签是否存在于 ACR 中 |
CapabilityHostNotFound | 未配置 Capability Host | 创建账户级别的 Capability Host |
ProtocolVersionNotSupported | 无效的协议版本 | 使用 AgentProtocol.RESPONSES 及版本 "v1" |
最佳实践
- 版本化镜像 - 在生产环境中使用具体标签，而非
latest - 最小资源 - 从最小的 CPU/内存开始，根据需求扩展
- 环境变量 - 用于所有配置，切勿硬编码
- 错误处理 - 将 Agent 创建包裹在 try/except 块中
- 清理 - 删除未使用的 Agent 版本以释放资源
参考链接
使用时机
本技能适用于执行概述中描述的工作流或操作。
限制
- 仅当任务明确符合上述范围时使用本技能。
- 请勿将输出视为特定环境验证、测试或专家审查的替代品。
- 如果缺少必需的输入、权限、安全边界或成功标准，请停止并请求澄清。