azure-ai-projects-py

Azure AI Projects Python SDK

使用する場面

Microsoft Foundry のプロジェクト接続、モデルのデプロイ、バージョン管理されたエージェント、評価データセット、クラウド評価ワークフローに使用します。まず、インストールされている SDK の世代を確認してください。v2 のプロジェクトクライアントに、従来のスレッド／実行の手順を適用しないでください。

セットアップとバージョンの境界

分離された環境を使用し、アプリケーションでロックされ、互換性が確認された azure-ai-projects、azure-identity、openai のバージョンを使用してください。過去のサポートファイルは、バージョンを固定した Microsoft のリポジトリに由来します。UPSTREAM-NOTICE.md と UPSTREAM-LICENSE.txt を参照してください。ローカルでの修正内容も、そこに記載されています。

AZURE_AI_PROJECT_ENDPOINT には、認可された正確な HTTPS プロジェクト URL を設定し、AZURE_AI_MODEL_DEPLOYMENT_NAME には、想定上のモデルエイリアスではなく、実際のデプロイ名を設定してください。最小権限の原則に従って、意図したテナント／ID を使用します。資格情報を出力せずに、資格情報チェーンを確認してください。一覧表示タスクでは、接続シークレットを取得しないでください。

確認済みの 2.0.0b4 ソーススナップショットでは、バージョン管理されたエージェント、OpenAI の会話／応答、評価器／メモリ／スケジュール用の beta 名前空間を使用します。従来のエージェントは azure-ai-agents に属します。後続のバージョンでは異なる場合があるため、インストール済みの SDK と Microsoft の移行ガイドを確認してください。

例：明示的に要求されたバージョン管理エージェントを 1 つ作成する

import os
from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import PromptAgentDefinition

with DefaultAzureCredential() as credential:
    with AIProjectClient(endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"], credential=credential) as project:
        agent = project.agents.create_version(
            agent_name="requested-agent",
            definition=PromptAgentDefinition(
                model=os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"],
                instructions="Answer the user’s question using authorized information.",
            ),
        )
        with project.get_openai_client(timeout=60, max_retries=0) as openai:
            response = openai.responses.create(
                input="Hello",
                extra_body={"agent_reference": {"type": "agent_reference", "name": agent.name, "version": agent.version}},
            )
            # Inspect authorized output; do not log private traces or credentials.

安全なワークフロー

1. 正確なテナント／プロジェクト、インストール済みのバージョン、要求されたリソース、データの分類を確認します。
2. モデルを選択する前に、デプロイ／接続のメタデータを読み取ります。曖昧に一致する最初のデプロイを自動選択しないでください。
3. 必要なツールだけを有効にします。モデルのツール呼び出しは提案です。実行する前に、引数、認可、送信先、影響を検証してください。リモート MCP エンドポイントはクラウドから到達可能である必要があります。localhost はユーザーのマシンではありません。
4. 選択済みの承認されたファイルだけをアップロードします。フォルダーの拡張子フィルターでは、シークレットを除外したり、アクセス権を適用したりできません。永続メモリには、テナント／ユーザーごとの適切な分離、保持ルール、削除ルールが必要です。
5. リクエストのタイムアウト、ポーリング、同時実行数、行数、費用に上限を設定します。リソースの作成がタイムアウトした場合は、再試行する前に結果を照合してください。クリーンアップの対象として明示された、タスクで作成したリソースだけを削除してください。

バッチ評価ヘルパー

scripts/run_batch_evaluation.py は、選択した JSONL ファイル全体をアップロードして評価と実行を作成するため、クラウド／モデル料金が発生することがあります。--allow-paid は、この特定のファイル、エンドポイント、評価器、デプロイ、予算についてユーザーが承認した後に実行を許可するオプションです。費用の見積もりや支出の制限機能ではありません。

python scripts/run_batch_evaluation.py --data approved.jsonl --evaluators coherence --deployment approved-deployment --max-rows 100 --max-bytes 1048576 --timeout-seconds 600 --allow-paid --output new-private-results.json

入力行のスキーマは一貫している必要があります。エージェントモードでは、ソースレコードを変更せず、サンプル出力を使用します。不明な評価器や、マッピングされたフィールドの不足がある場合は、アップロード前に失敗します。ポーリングのタイムアウトによってリモート実行がキャンセルされることはありません。出力された評価／実行 ID を確認し、必要に応じてインストール済みサービスで文書化された API を使用してキャンセルしてください。ローカル出力は新規のみで、モードは 0600 です。評価器の名前／スキーマはサービスのバージョンによって異なるため、実行環境で実行する前にレジストリを確認してください。

参考資料

• エージェントの操作とツールの境界
• 評価、組み込み評価器、カスタム評価器
• 接続、デプロイ、データセット／インデックス
• 非同期処理のパターン、確認済み API スナップショット

制限事項

ローカルチェックでは、Azure が利用可能であること、モデルの品質、法令遵守、または安全な自律的ツール利用を証明できません。評価スコアは、サンプリングに基づくバージョン固有の判定です。失敗、スコアの欠落、サンプル数、評価者の設定を報告してください。キーワードチェックは形式の確認であり、コンプライアンス認証ではありません。JSON 出力は解析し、スキーマを検証する必要があります。ドキュメントのレビュー中は、クラウド評価を実行しないでください。