Mulai cepat: Buat toolbox dan gunakan dengan agen yang di-host

Important

Item yang ditandai sebagai pratinjau dalam artikel ini saat ini masih dalam pratinjau. Pratinjau ini disediakan tanpa perjanjian tingkat layanan, dan Microsoft tidak merekomendasikannya untuk beban kerja produksi. Fitur tertentu mungkin tidak didukung atau mungkin memiliki kemampuan terbatas. Untuk informasi lebih lanjut, lihat Supplemental Terms of Use for Microsoft Azure Previews.

Dalam panduan memulai cepat ini, Anda membuat toolbox yang menggabungkan dua alat di balik satu endpoint terkelola:

Pencarian web, yang mendasarkan respons pada hasil web publik secara real-time.
server Microsoft Learn MCP, yang mendasarkan respons pada dokumentasi resmi Microsoft. Ini adalah titik akhir publik yang tidak memerlukan autentikasi.

Anda kemudian menggunakan toolbox dari agen terhosting yang ditulis dalam Python. Toolkit menyediakan satu endpoint MCP, sehingga agen terhubung ke satu URL dan menemukan semua alat saat runtime. Anda dapat mengubah alat nanti tanpa mengubah kode agen.

Jika Anda menggunakan agen pengodian seperti GitHub Copilot, Microsoft Foundry Skill dapat membantu membangun titik akhir kotak alat, menghubungkannya ke agen yang dihosting, dan menyesuaikan alat sampel.

Prasyarat

Panduan memulai cepat ini berdasarkan toolchain hosted-agent. Selesaikan Prasyarat dalam panduan mulai cepat agen yang dihosting terlebih dahulu, yang mencakup langganan Azure, peran proyek, Python, Azure Developer CLI (azd), dan ekstensi microsoft.foundry.

Untuk jalur SDK Python, gunakan bagian Python nanti di artikel ini alih-alih alur kerja Azure Developer CLI atau Visual Studio Code. Alur tersebut membuat toolbox dengan project_client.toolboxes.create_version(...), lalu mengunggah kode hosted-agent sebagai versi baru dan mengarahkannya ke toolbox tersebut berdasarkan nama.

Instal paket Python yang digunakan dalam jalur ini:

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

Anda memerlukan proyek Foundry yang sudah ada dengan model yang mendukung chat dan telah di-deploy. Langkah SDK Python dalam panduan mulai cepat ini membuat toolbox dan versi hosted-agent, tetapi tidak menyiapkan kerangka proyek Foundry baru atau membuat deployment model untuk Anda.

Untuk jalur SDK .NET, gunakan bagian C# nanti di artikel ini alih-alih alur kerja Azure Developer CLI atau VS Code. Proses itu membuat toolbox dengan AgentToolboxes.CreateVersion(...), lalu mengunggah kode hosted-agent C# sebagai versi baru dan mengarahkannya ke toolbox tersebut berdasarkan namanya.

Anda juga memerlukan .NET 10 SDK atau yang lebih baru, serta proyek Foundry yang sudah ada dengan model yang mendukung chat dan telah di-deploy.

Anda juga memerlukan Visual Studio Code dengan ekstensi Microsoft Foundry Toolkit, dan masuk ke Azure.

Langkah 1: Inisialisasi agen yang dihosting

Inisialisasi agen terhosting dari sampel toolbox Foundry, yang terhubung ke toolbox melalui MCP dan membuat alat-alatnya tersedia bagi model. Anda membuat kotak alat (my-toolbox) di langkah berikutnya dan mengarahkan agen ke titik akhirnya. Jalankan perintah ini dalam direktori kosong.

mkdir my-toolbox-agent && cd my-toolbox-agent
azd ai agent init -t "https://github.com/microsoft-foundry/foundry-samples/blob/main/samples/python/hosted-agents/agent-framework/responses/04-foundry-toolbox/azure.yaml" --src src/toolbox-agent

Ikuti perintah untuk memilih proyek Anda dan penyebaran model yang sudah ada. Saat Anda diminta untuk Memilih alokasi sumber daya kontainer, pilih 1 inti, memori 2Gi. Image kontainer agen memerlukan tier yang lebih tinggi daripada tier default. Flag --src membentuk agen menjadi src/toolbox-agent.

Note

Manifes agen (agent.manifest.yaml) dan definisi agen mandiri (agent.yaml) tidak digunakan lagi. Pada ekstensi Foundry azd (azure.ai.agents 1.0.0-beta.1), semua konfigurasi agen yang dihosting berada dalam satu azure.yaml. Lihat Penulis azure.yaml untuk agen yang dihosting.

Langkah 2: Membuat kotak alat

Buat toolbox, lalu salin endpoint MCP yang dihasilkan. Atur titik akhir tersebut sebagai variabel lingkungan di langkah selanjutnya.

Contoh azure.yaml mendefinisikan toolbox sebagai layanan azure.ai.toolbox dan menghubungkannya ke layanan agen yang dihosting dengan uses:. Jika Anda mengubah konfigurasi kotak alat, edit layanan kotak alat di azure.yaml, bukan src/toolbox-agent/agent.yaml.

Pertama, arahkan perintah kotak alat di proyek Foundry yang Anda pilih selama inisialisasi. Gunakan kembali endpoint yang telah disimpan oleh inisialisasi di lingkungan azd Anda:

azd env set FOUNDRY_PROJECT_ENDPOINT "$(azd env get-value FOUNDRY_PROJECT_ENDPOINT)"

Contoh ini menyertakan toolbox.yaml dalam src/toolbox-agent yang mendefinisikan kedua alat di balik satu endpoint. Buat kotak alat dari file tersebut:

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

Versi pertama menjadi versi default secara otomatis. Perintah ini menampilkan endpoint MCP berversi milik toolbox. Salin nilai Endpoint dari output. Atur TOOLBOX_ENDPOINT sebagai variabel lingkungan di langkah berikutnya. Terlihat seperti di bawah ini:

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

Buka Visual Studio Code dan pilih Foundry Toolkit di Bilah Aktivitas.
Masuk ke akun Azure Anda jika diminta.
Di bawah Sumber Daya Saya, perluas proyek Anda, lalu perluas Alat.
Dalam tampilan Alat , pilih ikon + Tambahkan Kotak Alat .
Masukkan nama kotak alat (my-toolbox) dan deskripsi.
Pilih Pencarian web.
Pilih + Tambahkan alat, pilih untuk menambahkan server MCP jarak jauh, dan masukkan URL https://learn.microsoft.com/api/mcpserver . Server bersifat publik, jadi tidak diperlukan autentikasi.
Pilih Terbitkan. Penerbitan membuat versi pertama kotak alat.
Salin titik akhir MCP kotak alat. Jalankan perintah berikut dan salin endpoint nilai dari output. Atur TOOLBOX_ENDPOINT sebagai variabel lingkungan di langkah berikutnya:
```
azd ai toolbox show my-toolbox --output json
```

Langkah 3: Menyediakan sumber daya Azure

Agen membaca endpoint MCP toolbox dari variabel lingkungan TOOLBOX_ENDPOINT, yang azure.yaml ditentukan dari lingkungan azd Anda. Anda menetapkan nilai tersebut di langkah berikutnya. Sediakan sumber daya Azure untuk agen:

azd provision

Langkah 4: Jalankan agen secara lokal

Untuk agen Python, pastikan layanannya dalam PYTHONNOUSERSITE: "1" mencakup azure.yaml dalam peta env yang ada sebelum startup dan penyebaran. Jangan mengandalkan memuat pengaturan ini di dalam aplikasi Anda. Untuk panduan kompatibilitas dependensi, lihat Mengonfigurasi startup Python.

Arahkan agen lokal ke kotak alat Anda dengan mengatur nilai-nilai ini dalam .env file di src/toolbox-agent. Tempelkan titik akhir yang Anda salin di Langkah 2:
```
FOUNDRY_MODEL_NAME=<your-model-deployment-name>
TOOLBOX_ENDPOINT=<versioned-endpoint-from-step-2>
```
azd ai agent run menyisipkan FOUNDRY_PROJECT_ENDPOINT dan membaca berkas .env untuk menjalankan secara lokal. Contoh ini menangani koneksi toolbox, header, dan autentikasi untuk Anda.
Mulai agen:
```
azd ai agent run
```
Perintah ini membuat lingkungan virtual, menginstal dependensi, dan melayani agen pada http://localhost:8088. Paket pratinjau dapat menghasilkan peringatan pip selama penyiapan. Peringatan ini tidak memblokir.

Di terminal terpisah, kirim perintah yang menjalankan alat:

azd ai agent invoke --local "Find the latest release notes for the Azure CLI on the web."
azd ai agent invoke --local "How do I create a hosted agent in Microsoft Foundry? Use the Microsoft Learn documentation."

Langkah 5: Terapkan ke Foundry Agent Service

Simpan titik akhir yang Anda salin di Langkah 2 di lingkungan Anda azd , yang azure.yaml diselesaikan pada waktu penyebaran. Kemudian buat dan sebarkan kontainer agen:

azd env set TOOLBOX_ENDPOINT "<versioned-endpoint-from-step-2>"
azd deploy

Setelah perintah selesai, output menunjukkan tautan ke taman bermain agen dan titik akhir agen. Panggil agen yang di-deploy:

azd ai agent invoke "What's new in Microsoft Foundry? Use the Microsoft Learn documentation."

Lokasi SDK Python

Gunakan langkah-langkah berikut jika Anda ingin membuat kotak alat dan menyebarkan versi agen yang dihosting dengan menggunakan SDK Python alih-alih alur Azure Developer CLI atau VS Code.

1. Buat atau pilih proyek Foundry

Buka portal Foundry dan buat proyek Foundry, atau pilih yang sudah ada.
Dalam proyek, terapkan model yang mendukung chat seperti gpt-5.4-mini.
Salin titik akhir proyek dari Gambaran Umum dan nama penyebaran dari Build>Deployments.

2. Unduh sampel agen yang dihosting kotak alat

Kloning repositori sampel Foundry:

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

Buat folder yang berfungsi untuk skrip penyebaran. Di folder tersebut, buat .env file dengan nilai-nilai ini:

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>

Langkah 3: Buat kotak alat dengan Python

Buat file bernama create_toolbox.py di folder kerja yang sama dengan .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}")

Jalankan skrip:

python create_toolbox.py

Sampel agen yang dihosting dapat menyelesaikan kotak alat baik dari TOOLBOX_ENDPOINT atau dari FOUNDRY_PROJECT_ENDPOINT plus TOOLBOX_NAME. Jalur ini menggunakan TOOLBOX_NAME, sehingga Anda tidak perlu menyimpan titik akhir versi di .env.

4. Sebarkan agen yang dihosting dengan Python

Buat file bernama deploy_toolbox_agent.py di folder kerja yang sama dengan .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,
                    "PYTHONNOUSERSITE": "1",
                },
                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,
            )

Jalankan skrip:

python deploy_toolbox_agent.py

Skrip ini mengunggah sampel kotak alat sebagai versi agen yang dihosting baru, mengarahkan agen yang dihosting pada versi tersebut untuk sementara waktu, memanggilnya dengan pertanyaan Microsoft Learn, dan memulihkan konfigurasi titik akhir sebelumnya setelah selesai.

5. Verifikasi respons berbasis toolbox

Jika Anda mengonfigurasi toolbox dengan benar, respons menunjukkan bahwa agen host menemukan alat dalam toolbox dan menjawab menggunakan dokumentasi Microsoft Learn.

Lokasi SDK C#

Gunakan jalur ini untuk membuat kotak alat dan menyebarkan sampel agen yang dihosting C# dengan .NET SDK alih-alih alur kerja Azure Developer CLI atau VS Code.

1. Buat atau pilih proyek Foundry

Buka portal Foundry dan buat proyek Foundry, atau pilih yang sudah ada.
Dalam proyek, terapkan model yang mendukung chat seperti gpt-4o.
Salin titik akhir proyek dari Gambaran Umum dan nama penyebaran dari Build>Deployments.

2. Unduh sampel agen yang dihosting kotak alat

Kloning repositori sampel Foundry:

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

Sampel agen yang dihosting C# berada di bawah samples/csharp/hosted-agents/agent-framework/foundry-toolbox-server-side/src/foundry-toolbox-server-side-dotnet-agent-framework. Kode penyebaran dalam langkah berikutnya mengatur variabel lingkungan ini pada kontainer:

Variabel	Description
`FOUNDRY_PROJECT_ENDPOINT`	Titik akhir proyek Foundry.
`AZURE_AI_MODEL_DEPLOYMENT_NAME`	Nama penyebaran model obrolan.
`TOOLBOX_NAME`	Nama kotak alat yang dihubungkan oleh agen.

3. Buat kotak alat dengan C#

Buat aplikasi konsol .NET dan instal paket. API Toolbox masih dalam pratinjau, jadi instal paket prarilis Azure.AI.Projects:

dotnet new console --name create-toolbox
cd create-toolbox
dotnet add package Azure.AI.Projects --prerelease
dotnet add package Azure.Identity

Ganti Program.cs dengan kode berikut dan atur endpoint ke titik akhir proyek Anda:

using Azure.AI.Projects;
using Azure.AI.Projects.Agents;
using Azure.Identity;
using OpenAI;
using OpenAI.Responses;

#pragma warning disable AAIP001, OPENAI001

var endpoint = "https://<account>.services.ai.azure.com/api/projects/<project>";
var toolboxName = "my-toolbox";

AIProjectClient projectClient = new(new Uri(endpoint), new DefaultAzureCredential());
AgentToolboxes toolboxes = projectClient.AgentAdministrationClient.GetAgentToolboxes();

ToolboxVersion created = toolboxes.CreateVersion(
    name: toolboxName,
    tools:
    [
        new WebSearchToolboxTool { Name = "web_search", SearchContextSize = WebSearchToolSearchContextSize.Medium },
        new MCPToolboxTool(serverLabel: "mslearn")
        {
            ServerUri = new Uri("https://learn.microsoft.com/api/mcp"),
            ToolCallApprovalPolicy = new McpToolCallApprovalPolicy(GlobalMcpToolCallApprovalPolicy.NeverRequireApproval),
        },
    ],
    description: "Toolbox with web search and Microsoft Learn MCP.");
Console.WriteLine($"Created toolbox version {created.Version} for {created.Name}");

Jalankan aplikasi:

dotnet run

Sampel agen yang dihosting menyelesaikan kotak alat dari FOUNDRY_PROJECT_ENDPOINT plus TOOLBOX_NAME, sehingga Anda tidak perlu menyimpan titik akhir versi.

4. Sebarkan agen yang dihosting dengan C#

Buat aplikasi konsol kedua untuk kode penyebaran:

dotnet new console --name deploy-toolbox-agent
cd deploy-toolbox-agent
dotnet add package Azure.AI.Projects --prerelease
dotnet add package Azure.AI.Extensions.OpenAI
dotnet add package Azure.Identity

Ganti Program.cs dengan kode berikut. Atur endpoint, chatModel, dan samplePath ke nilai Anda. samplePath adalah jalur lengkap ke folder sumber yang foundry-toolbox-server-side-dotnet-agent-framework Anda kloning di Langkah 2:

using Azure.AI.Extensions.OpenAI;
using Azure.AI.Projects;
using Azure.AI.Projects.Agents;
using Azure.Identity;
using OpenAI.Responses;

#pragma warning disable AAIP001, OPENAI001

var endpoint = "https://<account>.services.ai.azure.com/api/projects/<project>";
var chatModel = "gpt-4o";
var toolboxName = "my-toolbox";
var agentName = "toolbox-agent";
var samplePath =
    @"<path-to-foundry-samples>\samples\csharp\hosted-agents\agent-framework\foundry-toolbox-server-side\src\foundry-toolbox-server-side-dotnet-agent-framework";

AIProjectClient projectClient = new(new Uri(endpoint), new DefaultAzureCredential());
var agentsClient = projectClient.AgentAdministrationClient;

HostedAgentDefinition definition = new(cpu: "1", memory: "2Gi")
{
    Versions = { new ProtocolVersionRecord(ProjectsAgentProtocol.Responses, "2.0.0") },
    CodeConfiguration = new(
        runtime: "dotnet_10",
        entryPoint: ["dotnet", "foundry-toolbox-server-side.dll"],
        dependencyResolution: CodeDependencyResolution.RemoteBuild),
};
definition.EnvironmentVariables.Add("FOUNDRY_PROJECT_ENDPOINT", endpoint);
definition.EnvironmentVariables.Add("AZURE_AI_MODEL_DEPLOYMENT_NAME", chatModel);
definition.EnvironmentVariables.Add("TOOLBOX_NAME", toolboxName);

ProjectsAgentVersion? created = null;
AgentEndpointConfiguration? originalEndpoint = null;
try
{
    created = agentsClient.CreateAgentVersionFromCode(
        agentName, samplePath, new AgentVersionFromCodeMetadata(definition));
    Console.WriteLine($"Created hosted agent version {created.Version}");

    for (var attempt = 1; attempt <= 60; attempt++)
    {
        Thread.Sleep(TimeSpan.FromSeconds(10));
        created = agentsClient.GetAgentVersion(agentName, created.Version);
        Console.WriteLine($"Provisioning status: {created.Status} (attempt {attempt}/60)");
        if (created.Status == AgentVersionStatus.Active) break;
        if (created.Status == AgentVersionStatus.Failed)
            throw new InvalidOperationException("Hosted agent provisioning failed.");
    }

    ProjectsAgentRecord agent = agentsClient.GetAgent(agentName);
    originalEndpoint = agent.AgentEndpoint;
    agentsClient.PatchAgent(agentName, new PatchAgentOptions
    {
        AgentEndpoint = new AgentEndpointConfiguration
        {
            VersionSelector = new([new FixedRatioVersionSelectionRule(created.Version, 100)]),
            ProtocolConfiguration = new() { Responses = new ResponsesProtocolConfiguration() },
        },
    });

    ProjectResponsesClient responsesClient = projectClient.ProjectOpenAIClient
        .GetProjectResponsesClientForAgentEndpoint(agentName);
    ResponseResult response = responsesClient.CreateResponse(
        "How do I create a hosted agent in Microsoft Foundry? Use the Microsoft Learn documentation.");
    Console.WriteLine(response.GetOutputText());
}
finally
{
    if (originalEndpoint is not null)
        agentsClient.PatchAgent(agentName, new PatchAgentOptions { AgentEndpoint = originalEndpoint });
    if (created is not null)
        agentsClient.DeleteAgentVersion(agentName, created.Version, force: true);
}

Jalankan aplikasi:

dotnet run

Kode ini mengunggah sampel kotak alat sebagai versi agen yang dihosting baru, mengarahkan agen yang dihosting pada versi tersebut untuk sementara waktu, memanggilnya dengan pertanyaan Microsoft Learn, dan memulihkan konfigurasi titik akhir sebelumnya saat selesai.

5. Verifikasi respons berbasis toolbox

Jika Anda mengonfigurasi toolbox dengan benar, respons menunjukkan bahwa agen host menemukan alat dalam toolbox dan menjawab menggunakan dokumentasi Microsoft Learn.

Membersihkan sumber daya

Hapus sumber daya setelah selesai sehingga Anda berhenti dikenakan biaya.

Hapus kotak alat:

azd ai toolbox delete my-toolbox --force

Setelah Anda menghapus toolbox, endpoint-nya tidak lagi berfungsi. Hapus itu dari src/toolbox-agent/.env dan bersihkan itu dari lingkungan azd Anda:

azd env set TOOLBOX_ENDPOINT ""

Hapus agen dan sumber daya Azure:

Warning

Jika lingkungan saat ini azd membuat proyek Foundry, azd down secara permanen menghapus grup sumber daya proyek dan semua yang ada di dalamnya. Jika Anda memilih proyek yang sudah ada saat inisialisasi, azd down tidak menghapus proyek, grup sumber dayanya, agen terhosting, dan sumber daya quickstart lainnya. Untuk menghapus sumber daya yang tidak lagi Anda butuhkan dari proyek yang ada, hapus secara terpisah.

azd down

Hapus kotak alat berdasarkan nama:

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"])

Jika Anda membuat grup sumber daya atau proyek khusus untuk panduan mulai cepat ini, hapus grup sumber daya atau proyek tersebut dari portal Azure setelah toolbox, deployment chat, atau agen yang dihosting tidak lagi Anda perlukan.

Kode penyebaran sudah menghapus versi agen yang dihosting dan memulihkan konfigurasi titik akhir sebelumnya setelah selesai. Untuk menghapus toolbox, tambahkan kode ini ke aplikasi konsol yang telah menginstal paket Azure.AI.Projects (prarilis) dan Azure.Identity:

using Azure.AI.Projects;
using Azure.AI.Projects.Agents;
using Azure.Identity;

#pragma warning disable AAIP001

var endpoint = "https://<account>.services.ai.azure.com/api/projects/<project>";
var toolboxName = "my-toolbox";

AIProjectClient projectClient = new(new Uri(endpoint), new DefaultAzureCredential());
projectClient.AgentAdministrationClient.GetAgentToolboxes().Delete(toolboxName);
Console.WriteLine($"Deleted toolbox '{toolboxName}'.");

Troubleshooting

Issue	Solusi
`tools/list` tidak menampilkan alat Microsoft Learn	Pastikan alat `mslearn` di `toolbox.yaml` mengarah ke `https://learn.microsoft.com/api/mcp`.
Agen dimulai tetapi menampilkan `TOOLBOX_ENDPOINT is set but empty` atau tidak memiliki alat	Atur `TOOLBOX_ENDPOINT` ke endpoint berversi dari Langkah 2 di `.env` untuk eksekusi lokal, dan jalankan `azd env set TOOLBOX_ENDPOINT "<endpoint>"` sebelum Anda melakukan deployment.
Panggilan ke endpoint toolbox gagal karena kesalahan otorisasi	Pastikan setiap permintaan menyertakan token Entra yang cakupannya ditetapkan ke `https://ai.azure.com/.default`. Contoh ini melakukannya untuk Anda.
`Connection refused` saat dijalankan secara lokal	Pastikan tidak ada proses lain yang menggunakan port `8088`.

Apa yang Anda pelajari

Dalam panduan memulai cepat ini, Anda:

Membangun perangkat yang menggabungkan pencarian web dan server MCP Microsoft Learn melalui satu endpoint.
Gunakan toolbox dari agen yang dihosting yang terhubung melalui Model Context Protocol dengan Azure Developer CLI, SDK Python, atau SDK .NET.
Menjalankan agen secara lokal atau memvalidasinya dari jarak jauh dan menyebarkannya ke Foundry Agent Service.

Langkah selanjutnya

Tambahkan basis pengetahuan Foundry IQ ke agen terhosting

Saran dan Komentar

Apakah halaman ini membantu?

Terakhir diperbarui pada 2026-09-11

Mulai cepat: Buat toolbox dan gunakan dengan agen yang di-host

Prasyarat

Langkah 1: Inisialisasi agen yang dihosting

Langkah 2: Membuat kotak alat

Langkah 3: Menyediakan sumber daya Azure

Langkah 4: Jalankan agen secara lokal

Langkah 5: Terapkan ke Foundry Agent Service

Lokasi SDK Python

1. Buat atau pilih proyek Foundry

2. Unduh sampel agen yang dihosting kotak alat

Langkah 3: Buat kotak alat dengan Python

4. Sebarkan agen yang dihosting dengan Python

5. Verifikasi respons berbasis toolbox

Lokasi SDK C#

1. Buat atau pilih proyek Foundry

2. Unduh sampel agen yang dihosting kotak alat

3. Buat kotak alat dengan C#

4. Sebarkan agen yang dihosting dengan C#

5. Verifikasi respons berbasis toolbox

Membersihkan sumber daya

Troubleshooting

Apa yang Anda pelajari

Langkah selanjutnya

Konten terkait

Saran dan Komentar

Sumber Daya Tambahan: