Hızlı Başlangıç: Araç kutusu oluşturma ve bunu barındırılan bir aracıyla kullanma

Important

Bu makalede işaretlenen (önizleme) öğeler şu anda genel önizleme aşamasındadır. Bu önizleme, hizmet düzeyi sözleşmesi olmadan sağlanır ve üretim iş yükleri için önerilmez. Bazı özellikler desteklenmeyebilir veya kısıtlı özelliklere sahip olabilir. Daha fazla bilgi için bkz. Microsoft Azure Önizlemeleri için Ek Kullanım Koşulları.

Bu hızlı başlangıçta, yönetilen bir uç noktanın arkasında iki aracı birleştiren bir araç kutusu oluşturacaksınız:

  • Yanıtların gerçek zamanlı genel web sonuçlarına dayandırıldığı web araması.
  • Resmi Microsoft belgelerindeki yanıtların dayandırıldığı Microsoft Learn MCP sunucusu. Kimlik doğrulaması gerektirmeyen genel bir uç noktadır.

Ardından araç kutusunu Python ile yazılmış bir barındırılan aracıyı kullanarak tüketirsiniz. Araç kutusu tek bir MCP uç noktası sunar; bu sayede ajan tek bir URL’ye bağlanır ve çalışma zamanında tüm araçları keşfeder. Ajan kodunu değiştirmeden araçları daha sonra değiştirebilirsiniz.

Prerequisites

Bu hızlı başlangıç, barındırılan aracı zincirini temel alır. İlk olarak Azure aboneliğini, proje rollerini, Python, Azure Geliştirici CLI'sini () ve uzantıyı kapsayan barındırılan aracı hızlı başlangıcında azdmicrosoft.foundry tamamlayın.

Python SDK yolu için, bu makalenin devamında Azure Geliştirici CLI veya VS Code iş akışı yerine Python bölümünü kullanın. Bu yöntem, project_client.toolboxes.create_version(...) araç kutusunu oluşturur, ardından barındırılan aracı kodunu yeni bir sürüm olarak yükler ve adıyla bu araç kutusunu işaret eder.

Bu yolda kullanılan Python paketlerini yükleyin:

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

Dağıtılan sohbet özellikli modele sahip mevcut bir Foundry projesine ihtiyacınız vardır. Bu hızlı başlangıçtaki Python SDK yolu araç kutusunu ve barındırılan aracı sürümünü oluşturur, ancak yeni bir Foundry projesinin iskelesini oluşturmaz veya sizin için bir model dağıtımı oluşturmaz.

Ayrıca, Azure’da oturum açmış ve Microsoft Foundry Toolkit uzantısına sahip Visual Studio Code’a da ihtiyacınız vardır.

1. Adım: Barındırılan aracıyı başlatma

MCP üzerinden bir araç kutusuna bağlanan ve araçlarını modele sunan Foundry araç kutusu örneğinden barındırılan aracıyı başlatın. Sonraki adımda araç kutusunu (my-toolbox) oluşturur ve aracıyı uç noktasına yönlendirirsiniz. Bu komutları boş bir dizinde çalıştırın.

mkdir my-toolbox-agent && cd my-toolbox-agent
azd ai agent init -m "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

Projenizi ve mevcut bir model dağıtımını seçmek için istemleri izleyin. Kapsayıcı kaynağı ayırmayı seçin sorulduğunda 1 çekirdek, 2Gi bellek'i seçin. Ajanın konteyner imajı varsayılan düzeyden daha fazlasını gerektirir. --src bayrağı, ajanı src/toolbox-agent içinde oluşturur.

Uyarı

Aracı bildirimleri (agent.manifest.yaml) ve tek başına aracı tanımları (agent.yaml) kullanım dışıdır. Foundry azd uzantılarından (azure.ai.agents 1.0.0-beta.1) itibaren, barındırılan aracıya ilişkin tüm yapılandırma tek bir azure.yaml içinde yer alır. Bkz. Barındırılan aracılar için azure.yaml dosyası yazma.

2. Adım: Araç kutusunu oluşturma

Araç kutusunu oluşturun ve ardından döndürdüğü MCP uç noktasını kopyalayın. Sonraki adımlarda bu uç noktayı ortam değişkeni olarak ayarlayın.

Örneğin azure.yaml, araç kutusunu bir azure.ai.toolbox hizmet olarak tanımlar ve bunu uses: ile barındırılan aracı hizmete bağlar. Araç kutusu yapılandırmasını değiştirirseniz, araç kutusu hizmetini azure.yaml içinde düzenleyin, src/toolbox-agent/agent.yaml içinde değil.

İlk olarak, araç kutusu komutlarını başlatma sırasında seçtiğiniz Foundry projesine işaret edin. Başlatmanın ortamınızda zaten kaydettiği azd uç noktasını yeniden kullanın:

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

Örnek, tek bir uç noktanın arkasındaki her iki aracı da tanımlayan bir toolbox.yaml öğesini src/toolbox-agent içinde içerir. Bu dosyadan araç kutusunu oluşturun:

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

İlk sürüm otomatik olarak varsayılan sürüm olur. komutu, araç kutusunun sürümlenmiş MCP uç noktasını yazdırır. Çıkıştan Endpoint değeri kopyalayın. Sonraki adımlarda ortam değişkeni olarak TOOLBOX_ENDPOINT ayarlayın. Şunun gibi görünür:

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

  1. Visual Studio Code açın ve Etkinlik Çubuğu'nda Döküm Araç Seti'ni seçin.

  2. İstenirse Azure hesabınızda oturum açın.

  3. Kaynaklarım'ın altında projenizi genişletin ve ardından Araçlar'ı genişletin.

  4. Araçlar görünümünde + Araç Kutusu Ekle simgesini seçin.

  5. Araç kutusu adını (my-toolbox) ve açıklamayı girin.

  6. Web araması'yı seçin.

  7. + Araç ekle'yi seçin, uzak bir MCP sunucusu eklemeyi seçin ve sunucu URL'sini https://learn.microsoft.com/api/mcpgirin. Sunucu genel olduğundan kimlik doğrulaması gerekmez.

  8. Yayımla’yı seçin. Yayımlama, araç kutusunun ilk sürümünü oluşturur.

  9. Araç kutusunun MCP uç noktasını kopyalayın. Aşağıdaki komutu çalıştırın ve çıktıdaki endpoint değeri kopyalayın. Sonraki adımlarda ortam değişkeni olarak TOOLBOX_ENDPOINT ayarlayın:

    azd ai toolbox show my-toolbox --output json

3. Adım: Azure kaynakları sağlama

Ajan, araç kutusunun MCP uç noktasını TOOLBOX_ENDPOINT ortam değişkeninden okur; bu değişken, azure.yaml tarafından azd ortamınızdan çözümlenir. Bu değeri sonraki adımlarda ayarlarsınız. Ajanın Azure kaynaklarını hazırlayın:

azd provision

4. Adım: Ajanı yerel olarak çalıştırın

  1. Yerel aracıyı, .env içindeki src/toolbox-agent dosyasında bu değerleri ayarlayarak araç kutunuza yönlendirin. 2. Adımda kopyaladığınız uç noktayı yapıştırın:

    FOUNDRY_MODEL_NAME=<your-model-deployment-name>
TOOLBOX_ENDPOINT=<versioned-endpoint-from-step-2>

    azd ai agent run, yerel çalıştırmalarda FOUNDRY_PROJECT_ENDPOINT enjekte eder ve .env dosyasını okur. Örnek uygulama, araç kutusu bağlantısını, üst bilgileri ve kimlik doğrulamasını sizin için yönetir.

  2. Aracıyı başlatın:

    azd ai agent run

    Bu komut bir sanal ortam oluşturur, bağımlılıkları yükler ve aracıya üzerinde http://localhost:8088hizmet eder. Önizleme paketleri kurulum sırasında pip uyarıları üretebilir. Bu uyarılar engelleyici değildir.

  3. Ayrı bir terminalde, araçları sınayan istemler gönderin:

    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."

5. Adım: Foundry Ajan Hizmetine Dağıtma

2. Adım'da kopyaladığınız uç noktayı, dağıtım sırasında çözümlenen azd ortamınızda azure.yaml saklayın. Ardından ajan kapsayıcısını oluşturun ve dağıtın:

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

Komut tamamlandığında, çıktı ajan oyun alanı ve ajan uç noktası bağlantılarını gösterir. Dağıtılan ajanı çağırın:

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

Python SDK yolu

Araç kutusunu oluşturmak ve Azure Geliştirici CLI veya VS Code akışı yerine Python SDK'sını kullanarak barındırılan aracı sürümünü dağıtmak istiyorsanız aşağıdaki adımları kullanın.

1. Dökümhane projesi oluşturma veya seçme

  1. Foundry portalını açın ve bir Dökümhane projesi oluşturun veya var olan bir projeyi seçin.
  2. Projede, gpt-5.4-mini gibi sohbet özellikli bir model dağıtın.
  3. Genel Bakış'tan proje uç noktasını ve Derleme>Dağıtımları'ndan dağıtım adını kopyalayın.

2. toolbox hosted-agent örneğini indirin

Foundry örnekleri deposunu klonlayın:

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

Dağıtım betikleri için bir çalışma klasörü oluşturun. Bu klasörde şu değerlere sahip bir .env dosya oluşturun:

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. Adım: Python ile araç kutusunu oluşturma

ile aynı çalışma klasöründe create_toolbox.pyadlı .env bir dosya oluşturun:

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

Betiği Çalıştırın:

python create_toolbox.py

Örnek barındırılan aracı, araç kutusunu ya TOOLBOX_ENDPOINT içinden ya da FOUNDRY_PROJECT_ENDPOINT ile birlikte TOOLBOX_NAME içinden çözümleyebilir. Bu yol, TOOLBOX_NAME kullanır, bu nedenle sürümlü uç noktayı .env içinde depolamanız gerekmez.

4. Barındırılan aracıyı Python ile dağıtma

ile aynı çalışma klasöründe deploy_toolbox_agent.pyadlı .env bir dosya oluşturun:

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,
            )

Betiği Çalıştırın:

python deploy_toolbox_agent.py

Bu betik, araç kutusu örneğini yeni bir barındırılan aracı sürümü olarak karşıya yükler, barındırılan aracıyı geçici olarak bu sürüme yönlendirir, ona bir Microsoft Learn sorusu yönelterek çağırır ve işlem tamamlandığında önceki uç nokta yapılandırmasını geri yükler.

5. Araç kutusu destekli yanıtı doğrulayın

Araç kutusunu doğru şekilde yapılandırırsanız, yanıt barındırılan aracının araç kutusundaki araçları keşfettiğini ve Microsoft Learn belgelerini kullanarak yanıt verdiğini gösterir.

Kaynakları temizle

İşiniz bittiğinde kaynakları silin, böylece ücretlendirmeyi durdurun.

Araç kutusunu silin:

azd ai toolbox delete my-toolbox --force

Araç kutusunu sildikten sonra uç noktası çalışmayı durdurur. Bunu src/toolbox-agent/.env içinden kaldırın ve azd ortamınızdan temizleyin:

azd env set TOOLBOX_ENDPOINT ""

Aracıyı ve Azure kaynaklarını silin:

Warning

Geçerli azd ortam Foundry projesini oluşturduysa, azd down projenin kaynak grubunu ve içindeki her şeyi kalıcı olarak siler. Başlatma sırasında mevcut bir projeyi seçtiyseniz projeyi, azd down kaynak grubunu, barındırılan aracıyı ve diğer hızlı başlangıç kaynaklarını yerinde bırakır. Artık ihtiyacınız olmayan kaynakları mevcut projeden silmek için bunları ayrı olarak silin.

azd down

Araç kutusunu adına göre silin:

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

Bu hızlı başlangıç için ayrılmış bir kaynak grubu veya proje oluşturduysanız, araç kutusuna, sohbet dağıtımına veya barındırılan aracıya artık ihtiyacınız kalmadıktan sonra bunu Azure portalından silin.

Troubleshooting

Issue Çözüm
tools/listMicrosoft Learn araçlarını döndürmez mslearn içindeki toolbox.yaml aracının https://learn.microsoft.com/api/mcp öğesini işaret ettiğini doğrulayın.
Aracı başlar ancak TOOLBOX_ENDPOINT is set but empty bildirir veya araçları yoktur Yerel çalıştırmalar için, TOOLBOX_ENDPOINT içindeki 2. Adımdaki sürümlü uç noktaya .env ayarlayın ve dağıtmadan önce azd env set TOOLBOX_ENDPOINT "<endpoint>" çalıştırın.
Araç kutusu uç noktasına yapılan çağrılar yetkilendirme hatasıyla başarısız oldu Her isteğin, kapsamı https://ai.azure.com/.default ile sınırlandırılmış bir Entra belirteci içerdiğini doğrulayın. Örnek kod bunu sizin için halleder.
Connection refused yerel çalıştırmada 8088 bağlantı noktasını kullanan başka bir işlem olmadığından emin olun.

Öğrendiklerin

Bu hızlı başlangıç rehberinde şunları yapacaksınız:

  • Web araması ile Microsoft Learn MCP sunucusunu tek bir uç nokta arkasında birleştiren bir araç kutusu oluşturdu.
  • Azure Developer CLI veya Python SDK'yı kullanarak, Model Context Protocol üzerinden bağlanan Python'da barındırılan bir ajandan araç kutusunu kullanın.
  • Aracıyı yerel olarak çalıştırma veya uzaktan doğrulama ve Foundry Agent Service’e dağıtma.

Sonraki adım

Barındırılan bir aracıya Foundry IQ bilgi bankası ekleme

İlgili içerik

  • Last updated on