---

name: agents-v2-py description: "使用 Azure AI Projects SDK（ImageBasedHostedAgentDefinition）构建基于容器的 Foundry Agents。适用于在 Azure AI Foundry 中创建自定义容器镜像的托管代理。" risk: unknown source: community date_added: "2026-02-27"

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>

前置条件

创建托管代理之前：

1. 容器镜像 - 构建并推送到 Azure Container Registry (ACR)
2. ACR 拉取权限 - 为项目的托管标识授予 ACR 上的 AcrPull 角色
3. Capability Host - 账户级别的 capability host，设置 enablePublicHostingEnvironment=true
4. 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 |

工具配置

为托管代理添加工具：

Code Interpreter

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"
    }
]

环境变量

将配置传递给容器：