name: agents-v2-pydescription: “Build container-based Foundry Agents with Azure AI Projects SDK (ImageBasedHostedAgentDefinition). Use when creating hosted agents with custom container images in Azure AI Foundry.”risk: criticalsource: communitydate_added: “2026-02-27”Azure AI 托管代理Python使用 Azure AI Projects SDK 中的ImageBasedHostedAgentDefinition构建基于容器的托管代理。安装pipinstallazure-ai-projects2.0.0b3 azure-identity最低 SDK 版本需要2.0.0b3或更高版本以支持托管代理。环境变量AZURE_AI_PROJECT_ENDPOINThttps://resource.services.ai.azure.com/api/projects/project先决条件在创建托管代理之前容器镜像- 构建并推送到 Azure 容器注册表 (ACR)ACR 拉取权限- 授予你项目的托管身份在 ACR 上的AcrPull角色功能主机- 帐户级功能主机enablePublicHostingEnvironmenttrueSDK 版本- 确保azure-ai-projects2.0.0b3身份验证始终使用DefaultAzureCredentialfromazure.identityimportDefaultAzureCredentialfromazure.ai.projectsimportAIProjectClient credentialDefaultAzureCredential()clientAIProjectClient(endpointos.environ[AZURE_AI_PROJECT_ENDPOINT],credentialcredential)核心工作流程1. 导入importosfromazure.identityimportDefaultAzureCredentialfromazure.ai.projectsimportAIProjectClientfromazure.ai.projects.modelsimport(ImageBasedHostedAgentDefinition,ProtocolVersionRecord,AgentProtocol,)2. 创建托管代理clientAIProjectClient(endpointos.environ[AZURE_AI_PROJECT_ENDPOINT],credentialDefaultAzureCredential())agentclient.agents.create_version(agent_namemy-hosted-agent,definitionImageBasedHostedAgentDefinition(container_protocol_versions[ProtocolVersionRecord(protocolAgentProtocol.RESPONSES,versionv1)],cpu1,memory2Gi,imagemyregistry.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(fCreated agent:{agent.name}(version:{agent.version}))3. 列出代理版本versionsclient.agents.list_versions(agent_namemy-hosted-agent)forversioninversions:print(fVersion:{version.version}, State:{version.state})4. 删除代理版本client.agents.delete_version(agent_namemy-hosted-agent,versionagent.version)基于图像的托管代理定义参数ParameterTypeRequiredDescriptioncontainer_protocol_versionslist[ProtocolVersionRecord]YesProtocol versions the agent supportsimagestrYesFull container image path (registry/image:tag)cpustrNoCPU allocation (e.g., “1”, “2”)memorystrNoMemory allocation (e.g., “2Gi”, “4Gi”)toolslist[dict]NoTools available to the agentenvironment_variablesdict[str, str]NoEnvironment variables for the container协议版本container_protocol_versions参数指定您的代理支持哪些协议fromazure.ai.projects.modelsimportProtocolVersionRecord,AgentProtocol# RESPONSES protocol - standard agent responsescontainer_protocol_versions[ProtocolVersionRecord(protocolAgentProtocol.RESPONSES,versionv1)]可用协议ProtocolDescriptionAgentProtocol.RESPONSESStandard response protocol for agent interactions资源分配为您的容器指定 CPU 和内存definitionImageBasedHostedAgentDefinition(container_protocol_versions[...],imagemyregistry.azurecr.io/my-agent:latest,cpu2,# 2 CPU coresmemory4Gi# 4 GiB memory)资源限制ResourceMinMaxDefaultCPU0.541Memory1Gi8Gi2Gi工具配置向您的托管代理添加工具代码解释器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。完整示例importosfromazure.identityimportDefaultAzureCredentialfromazure.ai.projectsimportAIProjectClientfromazure.ai.projects.modelsimport(ImageBasedHostedAgentDefinition,ProtocolVersionRecord,AgentProtocol,)defcreate_hosted_agent():Create a hosted agent with custom container image.clientAIProjectClient(endpointos.environ[AZURE_AI_PROJECT_ENDPOINT],credentialDefaultAzureCredential())agentclient.agents.create_version(agent_namedata-processor-agent,definitionImageBasedHostedAgentDefinition(container_protocol_versions[ProtocolVersionRecord(protocolAgentProtocol.RESPONSES,versionv1)],imagemyregistry.azurecr.io/data-processor:v1.0,cpu2,memory4Gi,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(fCreated hosted agent:{agent.name})print(fVersion:{agent.version})print(fState:{agent.state})returnagentif__name____main__:create_hosted_agent()异步模式importosfromazure.identity.aioimportDefaultAzureCredentialfromazure.ai.projects.aioimportAIProjectClientfromazure.ai.projects.modelsimport(ImageBasedHostedAgentDefinition,ProtocolVersionRecord,AgentProtocol,)asyncdefcreate_hosted_agent_async():Create a hosted agent asynchronously.asyncwithDefaultAzureCredential()ascredential:asyncwithAIProjectClient(endpointos.environ[AZURE_AI_PROJECT_ENDPOINT],credentialcredential)asclient:agentawaitclient.agents.create_version(agent_nameasync-agent,definitionImageBasedHostedAgentDefinition(container_protocol_versions[ProtocolVersionRecord(protocolAgentProtocol.RESPONSES,versionv1)],imagemyregistry.azurecr.io/async-agent:latest,cpu1,memory2Gi))returnagent常见错误ErrorCauseSolutionImagePullBackOffACR pull permission deniedGrantAcrPullrole to project’s managed identityInvalidContainerImageImage not foundVerify image path and tag exist in ACRCapabilityHostNotFoundNo capability host configuredCreate account-level capability hostProtocolVersionNotSupportedInvalid protocol versionUseAgentProtocol.RESPONSESwith versionv1最佳实践给你的镜像标注版本- 在生产环境中使用具体标签而不是latest最少资源- 从最少的 CPU/内存开始根据需要扩展环境变量- 用于所有配置切勿硬编码错误处理- 将代理创建包装在 try/except 块中清理- 删除未使用的代理版本以释放资源参考链接Azure AI Projects SDKHosted Agents DocumentationAzure Container Registry何时使用此技能可用于执行概述中描述的工作流程或操作。限制仅当任务明确符合上述描述的范围时才使用此技能。不要将输出视为环境特定验证、测试或专家审查的替代品。如果缺少所需的输入、权限、安全界限或成功标准请停下来并要求澄清。