Agents V2 Python 版

agents-v2-py

分类编程

作者Agentic Awesome Skills 社区

许可MIT

评分4.50/5

使用2.6K

Azure AI 托管代理 (Python)

使用 Azure AI Projects SDK 中的 ImageBasedHostedAgentDefinition 构建基于容器的托管代理。

安装

bash

pip install azure-ai-projects>=2.0.0b3 azure-identity

最低 SDK 版本： 托管代理支持需要 2.0.0b3 或更高版本。

环境变量

bash

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) - 账户级能力主机需设置 enablePublicHostingEnvironment=true
4. SDK 版本 - 确保 azure-ai-projects>=2.0.0b3

身份验证

请始终使用 DefaultAzureCredential：

python

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. 导入

python

import os
from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import (
    ImageBasedHostedAgentDefinition,
    ProtocolVersionRecord,
    AgentProtocol,
)

2. 创建托管代理

python

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. 列出代理版本

python

versions = client.agents.list_versions(agent_name="my-hosted-agent")
for version in versions:
    print(f"Version: {version.version}, State: {version.state}")

4. 删除代理版本

python

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 参数指定了
指定您的代理支持哪些协议：

python

from azure.ai.projects.models import ProtocolVersionRecord, AgentProtocol
RESPONSES 协议 - 标准代理响应
container_protocol_versions=[
    ProtocolVersionRecord(protocol=AgentProtocol.RESPONSES, version="v1")
]

可用协议：
| 协议 | 描述 |
|----------|-------------|
| AgentProtocol.RESPONSES | 用于代理交互的标准响应协议 |

资源分配

为您的容器指定 CPU 和内存：

python

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)

python

tools=[{"type": "code_interpreter"}]

MCP 工具

python

tools=[
    {"type": "code_interpreter"},
    {
        "type": "mcp",
        "server_label": "my-mcp-server",
        "server_url": "https://my-mcp-server.example.com"
    }
]

多个工具

python

tools=[
    {"type": "code_interpreter"},
    {"type": "file_search"},
    {
        "type": "mcp",
        "server_label": "custom-tool",
        "server_url": "https://custom-tool.example.com"
    }
]

环境变量

向您的容器传递配置：

python

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。

完整示例

python

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"已创建托管代理: {agent.name}")
    print(f"版本: {agent.version}")
    print(f"状态: {agent.state}")
    
    return agent
if __name__ == "__main__":
    create_hosted_agent()

异步模式

python

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| 未配置能力主机 (Capability Host) | 创建账户级能力主机 | |ProtocolVersionNotSupported | 协议版本无效 | 使用 AgentProtocol.RESPONSES 且版本为 "v1" |


最佳实践

1. 镜像版本化 - 在生产环境中请使用具体标签，而非 latest`
2. 最小资源配置 - 从最低 CPU/内存开始，根据需要逐步扩容
3. 环境变量 - 所有配置均使用环境变量，严禁硬编码
4. 错误处理 - 将代理创建过程封装在 try/except 块中
5. 资源清理 - 删除不使用的代理版本以释放资源

参考链接

Azure AI Projects SDK

托管代理文档

Azure 容器注册表 (ACR)

适用场景

本技能适用于执行概览中所描述的工作流或操作。

局限性

仅在任务明确符合上述范围时使用此技能。

不要将输出结果视为针对特定环境的验证、测试或专家评审的替代方案。

如果缺失必要的输入、权限、安全边界或成功标准，请停止操作并请求澄清。

Agents V2 Python 版

Azure AI 托管代理 (Python)

安装

环境变量

前置条件

身份验证

核心工作流

1. 导入

2. 创建托管代理

3. 列出代理版本

4. 删除代理版本

ImageBasedHostedAgentDefinition 参数

协议版本

RESPONSES 协议 - 标准代理响应

资源分配

工具配置

代码解释器 (Code Interpreter)

MCP 工具

多个工具

环境变量

完整示例

异步模式

常见错误

最佳实践

参考链接

适用场景

局限性

扫码进交流群