如何在 Azure AI Foundry 中构建基于容器的托管 Agent

介绍如何利用 Azure AI Projects SDK，通过自定义容器镜像在 Azure AI Foundry 中创建和管理托管 Agent，实现环境隔离与高度可定制的 AI 服务。

为什么需要这个技能

在构建复杂的 AI Agent 时，标准的托管环境往往无法满足特定的运行时依赖、操作系统库或私有工具集的需求。

通过 ImageBasedHostedAgentDefinition，开发者可以将自定义的运行环境打包成容器镜像（Container Image）并推送至 Azure Container Registry (ACR)。这样，Agent 就可以在一个完全受控、可版本化的环境中运行，不仅解决了依赖冲突问题，还能够通过配置 CPU 和内存资源来优化性能。

适用场景

• 需要在 Agent 中运行特定的系统级依赖或第三方二进制软件。
• 必须在特定的容器版本中部署 Agent 以确保环境的一致性。
• 需要为 Agent 配置复杂的环境变量或集成自定义的 MCP (Model Context Protocol) 工具。
• 构建需要高性能计算资源（自定义 CPU/Memory）的 AI 任务处理器。

核心工作流

1. 环境准备

首先安装必要的 SDK 库：

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

确保容器镜像已推送到 ACR，且项目的托管身份（Managed Identity）拥有 AcrPull 权限。

2. 客户端初始化

使用 DefaultAzureCredential 进行身份验证，连接到 Azure AI 项目。

from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient

credential = DefaultAzureCredential()
client = AIProjectClient(
    endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"],
    credential=credential
)

3. 定义并创建托管 Agent

通过 ImageBasedHostedAgentDefinition 指定镜像路径、资源配额及工具集。

from azure.ai.projects.models import ImageBasedHostedAgentDefinition, ProtocolVersionRecord, AgentProtocol

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={
            "MODEL_NAME": "gpt-4o-mini"
        }
    )
)

4. 生命周期管理

可以通过 list_versions 查看所有版本状态，并使用 delete_version 清理不再需要的 Agent 实例。

下载和安装

下载 agents-v2-py 中文版 Skill ZIP

解压后将目录放入你的 AI 工具 skills 文件夹，重启工具后即可使用。具体路径参考内附的 USAGE.zh.md。

你可能还需要

暂无推荐