クイック スタート: ツールボックスを構築し、ホストされているエージェントで使用する

Python SDK パスについては、Azure Developer CLI または VS Code ワークフローの代わりに、この記事の後半の「Python」セクションを使用してください。 その手順では、project_client.toolboxes.create_version(...) を使用してツールボックスを作成し、hosted-agent のコードを新しいバージョンとしてアップロードしたうえで、そのツールボックス名を指定して参照させます。

このパスで使用するPython パッケージをインストールします。

pip install "azure-ai-projects>=2.3.0" azure-identity python-dotenv

チャット対応モデルがデプロイされた既存の Foundry プロジェクトが必要です。 このクイック スタートの Python SDK パスでは、ツールボックスと hosted-agent バージョンが作成されますが、新しい Foundry プロジェクトをスキャフォールディングしたり、モデルデプロイを作成したりすることはありません。

また、Azureにサインインした Microsoft Foundry Toolkit 拡張機能を使用したVisual Studio Codeも必要です。

このサンプルには、1 つのエンドポイントの背後にある両方のツールを定義するtoolbox.yamlのsrc/toolbox-agentが含まれています。 そのファイルからツールボックスを作成します。

azd ai toolbox create my-toolbox --from-file ./src/toolbox-agent/toolbox.yaml

最初のバージョンが自動的に既定のバージョンになります。 このコマンドは、ツールボックスのバージョン管理された MCP エンドポイントを出力します。 出力から Endpoint 値をコピーします。 次の手順で TOOLBOX_ENDPOINT 環境変数として設定します。 次のようになります：

https://<account>.services.ai.azure.com/api/projects/<project>/toolboxes/my-toolbox/versions/1/mcp?api-version=v1

1. Visual Studio Code開き、アクティビティ バーで Foundry Toolkit を選択します。

2. メッセージが表示されたら、Azure アカウントにサインインします。

3. [ マイ リソース] でプロジェクトを展開し、[ ツール] を展開します。

4. [ツール] ビューで、[+ ツールボックスの追加] アイコンを選択します。

5. ツールボックス名 (my-toolbox) と説明を入力します。

6. [Web 検索] を選択します。

7. [+ ツールの追加] を選択し、リモート MCP サーバーを追加することを選択し、サーバー URL https://learn.microsoft.com/api/mcp入力します。 サーバーはパブリックであるため、認証は必要ありません。

8. 公開を選択します。 発行すると、ツールボックスの最初のバージョンが作成されます。

9. ツールボックスの MCP エンドポイントをコピーします。 次のコマンドを実行し、出力から endpoint 値をコピーします。 次の手順で TOOLBOX_ENDPOINT 環境変数として設定します。

   azd ai toolbox show my-toolbox --output json
   

Python SDK パス

Azure Developer CLI または VS Code フローではなく、Python SDK を使用してツールボックスを作成し、ホストエージェント バージョンをデプロイする場合は、次の手順を使用します。

1. Foundry プロジェクトを作成または選択する

1. Foundry ポータルを開き、Foundry プロジェクトを作成するか、既存のプロジェクトを選択します。
2. プロジェクトで、 gpt-5.4-miniなどのチャット対応モデルをデプロイします。
3. [概要] からプロジェクト エンドポイントをコピーし、ビルド>Deployments からデプロイ名をコピーします。

2. ツールボックス hosted-agent サンプルをダウンロードする

Foundry サンプル リポジトリを複製します。

git clone https://github.com/microsoft-foundry/foundry-samples.git

配置スクリプトの作業フォルダーを作成します。 そのフォルダーに、次の値を含む .env ファイルを作成します。

FOUNDRY_PROJECT_ENDPOINT=<your-project-endpoint>
AZURE_AI_MODEL_DEPLOYMENT_NAME=<your-model-deployment-name>
FOUNDRY_HOSTED_AGENT_NAME=toolbox-agent
TOOLBOX_NAME=my-toolbox
FOUNDRY_SAMPLE_PATH=<full-path-to-foundry-samples/samples/python/hosted-agents/agent-framework/responses/04-foundry-toolbox/src/agent-framework-agent-with-foundry-toolbox-responses>

手順 3: Pythonを使用してツールボックスを作成する

create_toolbox.pyと同じ作業フォルダーに .env という名前のファイルを作成します。

import os

from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import MCPToolboxTool, WebSearchToolboxTool
from azure.identity import DefaultAzureCredential
from dotenv import load_dotenv

load_dotenv()

endpoint = os.environ["FOUNDRY_PROJECT_ENDPOINT"].rstrip("/")
toolbox_name = os.environ["TOOLBOX_NAME"]

with (
    DefaultAzureCredential() as credential,
    AIProjectClient(endpoint=endpoint, credential=credential) as project_client,
):
    created = project_client.toolboxes.create_version(
        name=toolbox_name,
        description="Toolbox with web search and Microsoft Learn MCP.",
        tools=[
            WebSearchToolboxTool(
                name="web_search",
                search_context_size="medium",
            ),
            MCPToolboxTool(
                server_label="mslearn",
                server_url="https://learn.microsoft.com/api/mcp",
                require_approval="never",
            ),
        ],
    )
    print(f"Created toolbox version {created.version} for {created.name}")

    mcp_endpoint = (
        f"{endpoint}/toolboxes/{created.name}/versions/"
        f"{created.version}/mcp?api-version=v1"
    )
    print(f"Toolbox version: {created.version}")
    print(f"Toolbox MCP endpoint: {mcp_endpoint}")

スクリプトを実行します。

python create_toolbox.py

サンプルのホステッド エージェントは、TOOLBOX_ENDPOINT から、または FOUNDRY_PROJECT_ENDPOINT と TOOLBOX_NAME の組み合わせから、ツールボックスを解決できます。 このパスでは TOOLBOX_NAMEを使用するため、バージョン管理されたエンドポイントを .envに格納する必要はありません。

4. Pythonを使用してホステッド エージェントをデプロイする

deploy_toolbox_agent.pyと同じ作業フォルダーに .env という名前のファイルを作成します。

import os
import tempfile
import time
import zipfile
from pathlib import Path

from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import (
    AgentEndpointConfig,
    CodeConfiguration,
    CodeDependencyResolution,
    FixedRatioVersionSelectionRule,
    HostedAgentDefinition,
    ProtocolConfiguration,
    ProtocolVersionRecord,
    ResponsesProtocolConfiguration,
    VersionSelector,
)
from azure.identity import DefaultAzureCredential
from dotenv import load_dotenv

load_dotenv()

endpoint = os.environ["FOUNDRY_PROJECT_ENDPOINT"]
model_name = os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"]
agent_name = os.environ.get("FOUNDRY_HOSTED_AGENT_NAME", "toolbox-agent")
toolbox_name = os.environ["TOOLBOX_NAME"]
sample_path = Path(os.environ["FOUNDRY_SAMPLE_PATH"]).resolve()


def create_code_zip(source_dir: Path) -> Path:
    zip_path = Path(tempfile.gettempdir()) / f"{agent_name}.zip"
    excluded = {".git", ".venv", "__pycache__", ".env"}

    with zipfile.ZipFile(zip_path, "w", zipfile.ZIP_DEFLATED) as zip_file:
        for path in source_dir.rglob("*"):
            if not path.is_file():
                continue
            if any(part in excluded for part in path.parts):
                continue
            zip_file.write(path, path.relative_to(source_dir))

    return zip_path


def wait_for_active_version(project_client: AIProjectClient, version: str) -> None:
    for attempt in range(60):
        time.sleep(10)
        details = project_client.agents.get_version(
            agent_name=agent_name,
            agent_version=version,
        )
        status = details["status"]
        print(f"Provisioning status: {status} (attempt {attempt + 1}/60)")

        if status == "active":
            return

        if status == "failed":
            raise RuntimeError(f"Hosted agent provisioning failed: {dict(details)}")

    raise RuntimeError("Timed out waiting for the hosted agent version to become active.")


code_zip_path = create_code_zip(sample_path)

with (
    code_zip_path.open("rb") as code_stream,
    DefaultAzureCredential() as credential,
    AIProjectClient(endpoint=endpoint, credential=credential) as project_client,
):
    original_agent_endpoint = None
    created = None

    try:
        created = project_client.agents.create_version_from_code(
            agent_name=agent_name,
            description="Hosted agent with Foundry Toolbox integration.",
            definition=HostedAgentDefinition(
                cpu="1",
                memory="2Gi",
                code_configuration=CodeConfiguration(
                    runtime="python_3_13",
                    entry_point=["python", "main.py"],
                    dependency_resolution=CodeDependencyResolution.REMOTE_BUILD,
                ),
                environment_variables={
                    "FOUNDRY_PROJECT_ENDPOINT": endpoint,
                    "AZURE_AI_MODEL_DEPLOYMENT_NAME": model_name,
                    "TOOLBOX_NAME": toolbox_name,
                },
                protocol_versions=[
                    ProtocolVersionRecord(protocol="responses", version="2.0.0")
                ],
            ),
            code=code_stream,
        )

        print(f"Created hosted agent version {created.version}")
        wait_for_active_version(project_client, created.version)

        original_agent_endpoint = project_client.agents.get(
            agent_name=agent_name
        ).agent_endpoint
        project_client.agents.update_details(
            agent_name=agent_name,
            agent_endpoint=AgentEndpointConfig(
                version_selector=VersionSelector(
                    version_selection_rules=[
                        FixedRatioVersionSelectionRule(
                            agent_version=created.version,
                            traffic_percentage=100,
                        ),
                    ]
                ),
                protocol_configuration=ProtocolConfiguration(
                    responses=ResponsesProtocolConfiguration()
                ),
            ),
        )

        with project_client.get_openai_client(agent_name=agent_name) as openai_client:
            response = openai_client.responses.create(
                input=(
                    "How do I create a hosted agent in Microsoft Foundry? "
                    "Use the Microsoft Learn documentation."
                ),
            )
            if response.status != "completed":
                raise RuntimeError(f"Agent invocation failed: {response.error}")
            print(response.output_text)
    finally:
        if original_agent_endpoint is not None:
            project_client.agents.update_details(
                agent_name=agent_name,
                agent_endpoint=original_agent_endpoint,
            )

        if created is not None:
            project_client.agents.delete_version(
                agent_name=agent_name,
                agent_version=created.version,
                force=True,
            )

スクリプトを実行します。

python deploy_toolbox_agent.py

このスクリプトは、ツールボックス サンプルを新しい hosted-agent バージョンとしてアップロードし、そのバージョンでホストされているエージェントを一時的にポイントし、Microsoft Learn の質問を使用して呼び出し、完了すると以前のエンドポイント構成を復元します。

5. ツールボックスに基づく応答を確認する

ツールボックスを正しく構成すると、ホストされたエージェントがツールボックス ツールを検出し、Microsoft Learn ドキュメントを使用して回答したことを示す応答が表示されます。

ツールボックスを削除します。

azd ai toolbox delete my-toolbox --force

ツールボックスを削除すると、そのエンドポイントは動作を停止します。 src/toolbox-agent/.envから削除し、azd環境からクリアします。

azd env set TOOLBOX_ENDPOINT ""

エージェントとそのAzureリソースを削除します。

azd down

名前でツールボックスを削除します。

import os

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

load_dotenv()

with (
    DefaultAzureCredential() as credential,
    AIProjectClient(
        endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
        credential=credential,
    ) as project_client,
):
    project_client.toolboxes.delete(name=os.environ["TOOLBOX_NAME"])

このクイック スタート用に専用のリソース グループまたはプロジェクトを作成した場合は、ツールボックス、チャット展開、またはホストされたエージェントが不要になった後、Azure ポータルから削除します。