agents-v2-py

Name: agents-v2-py
Author: sickn33

github.com/sickn33エージェントワークフロー48.7k165 回インストール今日更新

agents-v2-py について

agents-v2-pyは、Azure AI Projects SDKでコンテナベースのAzure AIホステッドエージェントを作成・管理するPython手順を示す互換スキルです。バージョン管理、プロトコル設定、リソース構成、デプロイ前提を扱います。

主な機能

01ホステッドエージェントのバージョン作成
02バージョンの一覧表示と削除
03コンテナイメージとリソースの設定
04エージェント対応プロトコルの指定
05レジストリ権限と前提条件の確認

活用シーン

01コンテナベースのホステッドエージェントの準備
02エージェントのバージョンと設定の確認
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 を使用してください。手順のみの内容は引き続きローカルにあります。実行可能なサポートファイルは同梱されていないため、既存のインストールは引き続きオフラインで動作します。この互換性ガイドではホステッドエージェントの手順を説明しており、追加の機能を提供するものではありません。古いコピーでは、廃止されたプレビュー名が使われている場合があります。既存のマニフェストまたはクライアント設定で使用されている場合は、呼び出し可能な ID を保持してください。 AAS での変更日：2026-09-05。元のメタデータとライセンスに関する通知は保持されています。

Azure AI Hosted Agents (Python)

Azure AI Projects SDK の HostedAgentDefinition を使用して、コンテナーベースのホステッドエージェントを構築します。

インストール

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

これらは、現在の Microsoft ホステッドエージェントガイドに準拠した SDK 2.3.0 の手順の断片です。プロビジョニングの前に、インストール済みのスキーマとサービスのサポート状況を検証してください。ドキュメントの確認は、クラウド統合テストではありません。

環境変数

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

前提条件

ホステッドエージェントを作成する前に、次のことを確認してください。

コンテナーイメージ - Azure Container Registry（ACR）にビルドしてプッシュします
ACR のプル権限 - プロジェクト ID に、権限モードでサポートされているレジストリロールを付与します。現在のホステッドエージェントガイダンスでは、Container Registry Repository Reader が使用されています
Capability Host - 現在のプロジェクト／リージョンでホステッドエージェントが利用可能か、およびアプリケーションのネットワークポリシーを確認します。パブリックホスティングを自動的に有効にしないでください
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. ホステッドエージェントの作成

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. エージェントのバージョンを一覧表示

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. エージェントのバージョンを削除

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

HostedAgentDefinition のパラメーター

パラメーター	型	必須	説明
`protocol_versions`	`list[ProtocolVersionRecord]`	はい	エージェントがサポートするプロトコルバージョン
`container_configuration`	`ContainerConfiguration`	イメージをデプロイする場合は必須	レビュー済みのレジストリイメージ参照
`cpu`	`str`	いいえ	CPU 割り当て（例："1"、"2"）
`memory`	`str`	いいえ	メモリ割り当て（例："2Gi"、"4Gi"）
`environment_variables`	`dict[str, str]`	いいえ	コンテナー用の環境変数

プロトコルバージョン

protocol_versions パラメーターでは、エージェントがサポートするプロトコルを指定します。

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`	エージェントとの対話に使用する標準的な応答プロトコル

リソースの割り当て

コンテナーの 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 のプル権限が拒否されています	レジストリの権限モードと、プロジェクト ID に対するスコープ付き閲覧者ロールを確認してください
`InvalidContainerImage`	イメージが見つかりません	ACR にイメージのパスとタグが存在することを確認してください
`CapabilityHostNotFound`	ケイパビリティホストが設定されていません	アカウントレベルのケイパビリティホストを作成してください
`ProtocolVersionNotSupported`	プロトコルのバージョンが無効です	バージョン `"2.0.0"` を指定して `AgentEndpointProtocol.RESPONSES` を使用してください

ベストプラクティス

イメージにバージョンを付ける - 本番環境では latest ではなく、具体的なタグを使用してください
リソースを最小限にする - 最小限の CPU／メモリから始め、必要に応じてスケールアップしてください
環境変数 - すべての設定に使用し、ハードコードは避けてください
エラー処理 - エージェントの作成を try/except ブロックで囲んでください
クリーンアップ - 使用していないエージェントのバージョンを削除して、リソースを解放してください

参考リンク

使用する場面

明示的に依頼されたコンテナベースの Foundry ホステッドエージェントをレビューまたは作成する場合に使用してください。まず、イメージダイジェスト、サブスクリプション／テナント、リージョン、サービスの提供状況、権限、コストの範囲を確認してください。エージェントの作成、ロールの付与、バージョンの削除はクラウドへの書き込み操作です。ユーザーの許可範囲内でのみ実行してください。

レビュー例

固定されたコンテナイメージとテストプロジェクトを受け取ったら、SDK のモデルフィールドとレジストリのプルアクセスを確認し、作成リクエストを準備します。許可されている場合に限りプロビジョニングし、返された正確なバージョンと確認した稼働状態を記録してください。定期的なクリーンアップとして、無関係なバージョンを削除しないでください。期待される結果は、デプロイされたと見なすことではなく、バージョン固有の結果記録です。

制限事項

このスキルは、タスクが上記の説明された範囲に明確に合致する場合にのみ使用してください。
出力を、環境固有の検証、テスト、または専門家によるレビューの代わりとして扱わないでください。
必要な入力、権限、安全上の境界、または成功基準が不足している場合は、作業を中断して確認を求めてください。

Markdown 対応

ログインしてコメント

基本情報

作者: sickn33
リポジトリ: sickn33/agentic-awesome-skills
カテゴリ: エージェントワークフロー
インストール数: 165
GitHub スター: 48,675

問題を報告