kscz0000 Azure AI 托管代理（Python）
使用 Azure AI Projects SDK 中的 ImageBasedHostedAgentDefinition 构建基于容器的托管代理。
安装
pip install azure-ai-projects>=2.0.0b3 azure-identity
最低 SDK 版本： 需要版本 2.0.0b3 或更高版本才支持托管代理。
环境变量
AZURE_AI_PROJECT_ENDPOINT=https://<resource>.services.ai.azure.com/api/projects/<project>
前置条件
创建托管代理之前：
- 容器镜像 - 构建并推送到 Azure Container Registry (ACR)
- ACR 拉取权限 - 为项目的托管标识授予 ACR 的
AcrPull角色 - 能力宿主 - 账户级别的能力宿主，需启用
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. 创建托管代理
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"Created agent: {agent.name} (version: {agent.version})")
3. 列出代理版本
versions = client.agents.list_versions(agent_name="my-hosted-agent")
for version in versions:
print(f"Version: {version.version}, State: {version.state}")
4. 删除代理版本
client.agents.delete_version(
agent_name="my-hosted-agent",
version=agent.version
)
ImageBasedHostedAgentDefinition 参数
| 参数 | 类型 | 必需 | 描述 |
|---|---|---|---|
container_protocol_versions |
list[ProtocolVersionRecord] |
是 | 代理支持的协议版本 |
image |
str |
是 | 完整容器镜像路径（registry/image:tag） |
cpu |
str |
否 | CPU 分配（例如 "1"、"2"） |
memory |
str |
否 | 内存分配（例如 "2Gi"、"4Gi"） |
tools |
list[dict] |
否 | 代理可用的工具 |
environment_variables |
dict[str, str] |
否 | 容器的环境变量 |
协议版本
container_protocol_versions 参数指定代理支持的协议：
from azure.ai.projects.models import ProtocolVersionRecord, AgentProtocol
# RESPONSES 协议 - 标准代理响应
container_protocol_versions=[
ProtocolVersionRecord(protocol=AgentProtocol.RESPONSES, version="v1")
]
可用协议：
| 协议 | 描述 |
|---|---|
AgentProtocol.RESPONSES |
代理交互的标准响应协议 |
资源分配
为容器指定 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 |
工具配置
为托管代理添加工具：
代码解释器
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():
"""使用自定义容器镜像创建托管代理。"""
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"Created hosted agent: {agent.name}")
print(f"Version: {agent.version}")
print(f"State: {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():
"""异步创建托管代理。"""
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 |
未配置能力宿主 | 创建账户级别的能力宿主 |
ProtocolVersionNotSupported |
协议版本无效 | 使用 AgentProtocol.RESPONSES 和版本 "v1" |
最佳实践
- 镜像版本化 - 生产环境中使用具体标签，而非
latest - 最小资源 - 从最小 CPU/内存开始，按需扩展
- 环境变量 - 用于所有配置，切勿硬编码
- 错误处理 - 用 try/except 块包装代理创建逻辑
- 清理 - 删除未使用的代理版本以释放资源
参考链接
使用场景
本技能适用于执行概述中描述的工作流或操作。
限制
- 仅当任务明确符合上述描述的范围时使用本技能。
- 输出内容不应替代特定环境的验证、测试或专家评审。
- 如果缺少必需的输入、权限、安全边界或成功标准，请停止并请求澄清。