以下为本文档的中文说明

该技能用于构建和管理Python版本的代理系统（v2版本）。它提供代理的创建、配置、执行和监控功能，支持多种代理类型和任务模式。适用于需要使用Python开发代理应用的开发者，帮助快速搭建和部署代理工作流，提高开发效率。v2版本在前一代基础上增强了代理的可配置性和扩展性，支持更复杂的工作流编排和更精细的执行控制。该技能提供Python版本的代理系统v2版本，支持多种代理类型的创建和管理。v2版本相比前代增强了代理的可配置性（支持自定义工具和知识库）、扩展性（支持插件化架构）和可观测性（内置日志和监控）。技能涵盖从单代理任务的快速部署到多代理工作流的复杂编排，开发者可以通过简单的配置文件和API调用来定义代理行为和任务流程。该技能适用于需要快速构建和迭代代理应用的Python开发者，降低代理开发的技术门槛。该技能提供了基于Python的v2版本代理系统开发框架，相比前代版本在多个方面进行了重大升级。v2版本支持更灵活的代理配置，开发者可以通过配置文件自定义代理的行为参数、工具集合和知识库；扩展性方面，v2引入了插件化架构，允许社区开发第三方插件来扩展代理的能力边界；可观测性方面，v2内置了完善的日志记录和性能监控接口，方便开发者调试和优化代理行为。技能覆盖从简单的单代理任务到复杂多代理工作流的完整开发场景。

Azure AI Hosted Agents (Python)

Build container-based hosted agents using ImageBasedHostedAgentDefinition from the Azure AI Projects SDK.

Installation

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

Minimum SDK Version: 2.0.0b3 or later required for hosted agent support.

Environment Variables

AZURE_AI_PROJECT_ENDPOINT=https://<resource>.services.ai.azure.com/api/projects/<project>

Prerequisites

Before creating hosted agents:

  1. Container Image - Build and push to Azure Container Registry (ACR)
  2. ACR Pull Permissions - Grant your project’s managed identity AcrPull role on the ACR
  3. Capability Host - Account-level capability host with enablePublicHostingEnvironment=true
  4. SDK Version - Ensure azure-ai-projects>=2.0.0b3

Authentication

Always use 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
)

Core Workflow

1. Imports

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

2. Create Hosted Agent

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. List Agent Versions

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

4. Delete Agent Version

client.agents.delete_version(
    agent_name="my-hosted-agent",
    version=agent.version
)

ImageBasedHostedAgentDefinition Parameters

Parameter Type Required Description
container_protocol_versions list[ProtocolVersionRecord] Yes Protocol versions the agent supports
image str Yes Full container image path (registry/image:tag)
cpu str No CPU allocation (e.g., “1”, “2”)
memory str No Memory allocation (e.g., “2Gi”, “4Gi”)
tools list[dict] No Tools available to the agent
environment_variables dict[str, str] No Environment variables for the container

Protocol Versions

The container_protocol_versions parameter specifies which protocols your agent supports:

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

# RESPONSES protocol - standard agent responses
container_protocol_versions=[
    ProtocolVersionRecord(protocol=AgentProtocol.RESPONSES, version="v1")
]

Available Protocols:

Protocol Description
AgentProtocol.RESPONSES Standard response protocol for agent interactions

Resource Allocation

Specify CPU and memory for your container:

definition=ImageBasedHostedAgentDefinition(
    container_protocol_versions=[...],
    image="myregistry.azurecr.io/my-agent:latest",
    cpu="2",      # 2 CPU cores
    memory="4Gi"  # 4 GiB memory
)

Resource Limits:

Resource Min Max Default
CPU 0.5 4 1
Memory 1Gi 8Gi 2Gi

Tools Configuration

Add tools to your hosted agent:

Code Interpreter

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

MCP Tools

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

Multiple Tools

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

Environment Variables

Pass configuration to your container:

environment_variables={
    "AZURE_AI_PROJECT_ENDPOINT": os.environ["AZURE_AI_PROJECT_ENDPOINT"],
    "MODEL_NAME": "gpt-4o-mini",
    "LOG_LEVEL": "INFO",
    "CUSTOM_CONFIG": "value"
}

Best Practice: Never hardcode secrets. Use environment variables or Azure Key Vault.

Complete Example

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():
    """Create a hosted agent with custom container image."""
    
    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()

Async Pattern

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():
    """Create a hosted agent asynchronously."""
    
    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

Common Errors

Error Cause Solution
ImagePullBackOff ACR pull permission denied Grant AcrPull role to project’s managed identity
InvalidContainerImage Image not found Verify image path and tag exist in ACR
CapabilityHostNotFound No capability host configured Create account-level capability host
ProtocolVersionNotSupported Invalid protocol version Use AgentProtocol.RESPONSES with version "v1"

Bes

t Practices

  1. Version Your Images - Use specific tags, not latest in production
  2. Minimal Resources - Start with minimum CPU/memory, scale up as needed
  3. Environment Variables - Use for all configuration, never hardcode
  4. Error Handling - Wrap agent creation in try/except blocks
  5. Cleanup - Delete unused agent versions to free resources

Reference Links

When to Use

This skill is applicable to execute the workflow or actions described in the overview.

Limitations

  • Use this skill only when the task clearly matches the scope described above.
  • Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
  • Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.
# 人工智能
Logo
AI Agent技术社区

Agent 垂直技术社区，欢迎活跃、内容共建。

更多推荐

cover

从「能说」到「能做」：一份理清 AI Agent 的学习笔记

avatar AI Agent技术社区
cover

DeepSeek Harness 深度解析：一切皆插件的开源 AI Agent 框架如何运行？

avatar AI Agent技术社区
cover

2026年，集团企业想要AI落地，选RPA还是Agent？

avatar AI Agent技术社区