hosted-agents-v2-py

Name: hosted-agents-v2-py
Author: sickn33

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

リポジトリ

hosted-agents-v2-py について

Azure AI Projects SDKでコンテナベースのホステッドエージェントを作成・管理する、手順中心のPythonスキルです。エージェントのバージョン操作に加え、イメージ設定や前提条件を扱います。

主な機能

01コンテナベースのホステッドエージェント作成
02エージェントバージョンの一覧表示と削除
03プロトコルとコンテナーリソースの設定
04レジストリアクセス要件の確認

活用シーン

01コンテナイメージを使ったホステッドエージェントの準備
02特定バージョンの確認または削除

MCP 対応

サーバーURLとラベルを含むアプリケーション固有のMCPツール設定例を示します。この設定だけではツールの作成や権限付与は行われないと説明しています。

インストール

コマンドをコピーしてターミナルで実行します。

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

インストール後、Claude Code で/hosted-agents-v2-pyを入力して読み込まれたか確認します。

詳細

互換性とメンテナンス

この互換性グループの主要な編集パスです。手順のみのプロセスはローカルに保持され、実行可能なサポートファイルは同梱されていないため、既存のインストールは引き続きオフラインで動作します。これは共有の手順であり、追加の機能ではありません。既存のマニフェストまたはクライアント設定で使用されている場合は、呼び出し可能な ID を維持してください。 2026-09-05 に AAS で変更されました。元のメタデータとライセンス表記は保持されています。

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
カテゴリ: エージェントワークフロー
インストール数: 55
GitHub スター: 48,675

問題を報告