agents-v2-py

Name: agents-v2-py
Author: sickn33

github.com/sickn33Agent 工作流48.7k165 次安装今天更新

代码仓库

关于 agents-v2-py

agents-v2-py 是兼容性技能，提供使用 Azure AI Projects SDK 创建和管理容器化 Azure AI 托管 Agent 的 Python 操作说明。内容涵盖版本管理、协议配置、资源设置和部署前提。

主要功能

01创建托管 Agent 版本
02列出和删除 Agent 版本
03配置容器镜像与资源
04设置 Agent 支持的协议
05检查注册表权限和前提条件

适用场景

01准备容器化托管 Agent
02检查 Agent 版本和配置详情
03Azure 资源部署前核查前提条件

MCP 相关

指南示例说明如何在所选容器运行时或框架中配置 MCP 工具。它提醒，这不会自动意味着 HostedAgentDefinition 存在 tools 字段，也不会单独配置 MCP 访问权限。

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/sickn33/agentic-awesome-skills --skill agents-v2-py

安装后在 Claude Code 中输入/agents-v2-py确认已加载。

详细介绍

兼容性与维护

hosted-agents-v2-py 的兼容性别名；如果现有契约未要求使用此 ID，请在新引用中使用该 ID。仅包含说明的流程仍在本地；不捆绑可执行支持文件，因此现有安装可继续离线运行。此兼容性指南介绍托管 Agent 流程，不代表新增功能；较早的副本可能使用已停用的预览名称。如果现有清单或客户端配置使用此可调用 ID，请予以保留。于 2026-09-05 在 AAS 中修改；保留了原始元数据和许可证声明。

Azure AI Hosted Agents（Python）

使用 Azure AI Projects SDK 中的 HostedAgentDefinition 构建基于容器的托管 Agent。

安装

pip install 'azure-ai-projects==2.3.0' azure-identity

这些是与当前 Microsoft 托管 Agent 指南一致的 SDK 2.3.0 说明片段。预配之前，请验证已安装的架构和服务支持情况；检查文档不等同于云集成测试。

环境变量

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

先决条件

创建托管 Agent 之前：

容器镜像 - 构建并推送到 Azure Container Registry (ACR)
ACR 拉取权限 - 根据权限模式，为项目身份授予受支持的注册表角色；当前托管 Agent 指南使用 Container Registry Repository Reader
功能主机 - 确认当前项目/区域是否提供托管 Agent，以及应用程序的网络策略；不要自动启用公共托管
SDK 版本 - 确保 azure-ai-projects==2.3.0

身份验证

针对目标租户/订阅使用获准的 Azure 凭据流程；以下示例使用 DefaultAzureCredential：

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

import os

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 (
    HostedAgentDefinition,
    ContainerConfiguration,
    ProtocolVersionRecord,
    AgentEndpointProtocol,
)

2. 创建托管 Agent

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

agent = client.agents.create_version(
    agent_name="my-hosted-agent",
    definition=HostedAgentDefinition(
        protocol_versions=[
            ProtocolVersionRecord(protocol=AgentEndpointProtocol.RESPONSES, version="2.0.0")
        ],
        cpu="1",
        memory="2Gi",
        container_configuration=ContainerConfiguration(image=os.environ["REVIEWED_CONTAINER_IMAGE"]),
        environment_variables={
            "AZURE_AI_PROJECT_ENDPOINT": os.environ["AZURE_AI_PROJECT_ENDPOINT"],
            "MODEL_NAME": os.environ["MODEL_DEPLOYMENT_NAME"]
        }
    )
)

print(f"Created agent: {agent.name} (version: {agent.version})")

3. 列出 Agent 版本

versions = client.agents.list_versions(agent_name="my-hosted-agent")
for version in versions:
    print(f"Version: {version.version}")  # Inspect supported status fields via get_version

检查实际返回的模型，确认其支持的字段；创建了某个版本并不能证明运行中的容器运行正常。请通过受支持的上下文管理器或 close() 方法关闭同步客户端/凭据资源。

4. 删除 Agent 版本

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

HostedAgentDefinition 参数

参数	类型	必填	描述
`protocol_versions`	`list[ProtocolVersionRecord]`	是	Agent 支持的协议版本
`container_configuration`	`ContainerConfiguration`	部署镜像时必填	已审核的注册表镜像引用
`cpu`	`str`	否	CPU 分配量（例如，“1”、“2”）
`memory`	`str`	否	内存分配量（例如，“2Gi”、“4Gi”）
`environment_variables`	`dict[str, str]`	否	容器的环境变量

协议版本

protocol_versions 参数用于指定 Agent 支持的协议：

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

# RESPONSES protocol - standard agent responses
protocol_versions=[
    ProtocolVersionRecord(protocol=AgentEndpointProtocol.RESPONSES, version="2.0.0")
]

可用协议：

协议	描述
`AgentEndpointProtocol.RESPONSES`	Agent 交互的标准响应协议

资源分配

为容器指定 CPU 和内存：

definition=HostedAgentDefinition(
    protocol_versions=[...],
    container_configuration=ContainerConfiguration(image=os.environ["REVIEWED_CONTAINER_IMAGE"]),
    cpu="2",      # 2 CPU cores
    memory="4Gi"  # 4 GiB memory
)

示例资源规格；预配前请确认区域/SKU 限制：

资源	最小值	最大值	默认值
CPU	0.5	4	1
内存	1Gi	8Gi	2Gi

工具配置

在所选容器运行时/框架中配置工具支持。以下工具字典描述的是特定应用的意图；不要假设 HostedAgentDefinition 存在 tools 字段，也不要假设定义该字段就能预配工具或授予权限：

代码解释器

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": os.environ["MODEL_DEPLOYMENT_NAME"],
    "LOG_LEVEL": "INFO",
    "CUSTOM_CONFIG": "value"
}

最佳实践： 在配置中保留非机密部署名称和经过审核的不可变镜像引用；机密信息需要使用平台实际提供的受保护注入机制。任意环境字典并不能建立 Key Vault 集成。

完整示例

import os
from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import (
    HostedAgentDefinition,
    ContainerConfiguration,
    ProtocolVersionRecord,
    AgentEndpointProtocol,
)

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=HostedAgentDefinition(
            protocol_versions=[
                ProtocolVersionRecord(
                    protocol=AgentEndpointProtocol.RESPONSES,
                    version="2.0.0"
                )
            ],
            container_configuration=ContainerConfiguration(image=os.environ["REVIEWED_CONTAINER_IMAGE"]),
            cpu="2",
            memory="4Gi",
            environment_variables={
                "AZURE_AI_PROJECT_ENDPOINT": os.environ["AZURE_AI_PROJECT_ENDPOINT"],
                "MODEL_NAME": os.environ["MODEL_DEPLOYMENT_NAME"],
                "MAX_RETRIES": "3"
            }
        )
    )
    
    print(f"Created hosted agent: {agent.name}")
    print(f"Version: {agent.version}")
    # Poll get_version status with a deadline before treating deployment as active.
    
    return agent

if __name__ == "__main__":
    create_hosted_agent()

异步模式

import os
from azure.identity.aio import DefaultAzureCredential
from azure.ai.projects.aio import AIProjectClient
from azure.ai.projects.models import (
    HostedAgentDefinition,
    ContainerConfiguration,
    ProtocolVersionRecord,
    AgentEndpointProtocol,
)

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=HostedAgentDefinition(
                    protocol_versions=[
                        ProtocolVersionRecord(
                            protocol=AgentEndpointProtocol.RESPONSES,
                            version="2.0.0"
                        )
                    ],
                    container_configuration=ContainerConfiguration(image=os.environ["REVIEWED_CONTAINER_IMAGE"]),
                    cpu="1",
                    memory="2Gi"
                )
            )
            return agent

常见错误

错误	原因	解决方案
`ImagePullBackOff`	ACR 拉取权限被拒绝	验证注册表权限模式，以及项目身份是否具有范围限定的读取者角色
`InvalidContainerImage`	找不到镜像	验证 ACR 中存在该镜像路径和标签
`CapabilityHostNotFound`	未配置能力主机	创建账户级能力主机
`ProtocolVersionNotSupported`	协议版本无效	使用 `AgentEndpointProtocol.RESPONSES`，版本为 `"2.0.0"`

最佳实践

为镜像设置版本 - 生产环境中使用特定标签，不要使用 latest
资源配置从简 - 从最低 CPU/内存配置开始，按需扩容
环境变量 - 所有配置都使用环境变量，绝不硬编码
错误处理 - 使用 try/except 块包装 Agent 创建过程
清理 - 删除未使用的 Agent 版本以释放资源

参考链接

适用场景

用于审查或创建明确要求的、基于容器的 Foundry 托管 Agent。首先确认镜像摘要、订阅/租户、区域、服务可用性、权限和成本范围。创建 Agent、授予角色和删除版本都属于云端写入操作；只有在用户授权范围内才能执行。

审查示例

给定一个固定版本的容器镜像和测试项目，检查 SDK 模型字段和注册表拉取权限，然后准备创建请求。仅在获得授权后进行预配，并记录确切返回的版本和观察到的运行状况。不要将删除无关版本作为例行清理操作。预期结果应是特定版本的回执，而不是假定部署成功。

限制

仅当任务明确符合上述范围时才使用此技能。
不要将输出视为环境特定验证、测试或专家审查的替代品。
如果缺少必需输入、权限、安全边界或成功标准，请停止并请求澄清。

支持 Markdown

登录后评论

基本信息

作者: sickn33
仓库: sickn33/agentic-awesome-skills
分类: Agent 工作流
安装次数: 165
GitHub Stars: 48,675

报告问题