Aracıları OpenAPI araçlarına bağlama

OpenAPI 3.0 ve 3.1 belirtimlerini kullanarak Microsoft Foundry aracılarınızı dış API'lere bağlayın. Aracınızı destekleyen Foundry modeli dış hizmetleri çağırabilir, gerçek zamanlı verileri alabilir ve özelliklerini yerleşik işlevlerin ötesine genişletebilir.

OpenAPI belirtimleri , mevcut hizmetleri aracılarınızla tümleştirebilmeniz için HTTP API'lerini açıklamak için standart bir yol tanımlar. Microsoft Foundry üç kimlik doğrulama yöntemini destekler: anonymous, API key ve managed identity. Kimlik doğrulama yöntemi seçmeyle ilgili yardım için bkz. Kimlik doğrulama yöntemi seçme.

Ipucu

Bu aracı araç kutusunu kullanarak eklemeyi düşünün. Araç kutusunu kullanarak aracıları ve çalışma zamanlarını yeniden kullanabilir ve yönetilen bir MCP uç noktası aracılığıyla kimlik bilgisi yönetimi, sürüm oluşturma ve ilke zorlamayı merkezi hale getirebilirsiniz. araç kutusu hızlı başlangıç kılavuzuna bakın.

Önkoşullar

Başlamadan önce şunları yaptığınızdan emin olun:

Doğru izinlere sahip bir Azure aboneliği.
Foundry Kullanıcısı rolü; Foundry projesinde aracılar oluşturmak ve çalıştırmak için.

Önemli

Foundry RBAC rolleri yakın zamanda yeniden adlandırıldı. Foundry User, Foundry Owner, Foundry Hesabı Sahibi ve Foundry Project Manager daha önce Azure Yapay Zeka Kullanıcısı, Azure Yapay Zeka Sahibi, Azure Yapay Zeka Hesabı Sahibi ve Azure Yapay Zeka Project Yöneticisi olarak adlandırıldı. Yeniden adlandırma kullanıma sunulmaya devam ederken bazı yerlerde önceki adları görmeye devam edebilirsiniz. Rol kimlikleri ve temel izinler yeniden adlandırma ile değiştirilmez.
API anahtarı veya belirteç kimlik doğrulaması için bir proje bağlantısı oluşturursanız, Foundry projesinde Foundry Proje Yöneticisi rolüne sahip olursunuz.
Yapılandırılmış bir uç nokta ile oluşturulmuş bir Dökümhane projesi.
Projenizde dağıtılan bir yapay zeka modeli. Hem modelin hem de proje bölgesinin bölgeye ve modele göre Araç desteğinde OpenAPI araçlarını desteklediğini onaylayın.
Temel veya standart aracı ortamı.
Tercih ettiğiniz dil için yüklenen SDK:
- Piton: pip install azure-ai-projects jsonref
- C#: Azure.AI.Extensions.OpenAI
- TypeScript/JavaScript: @azure/ai-projects
- Java: com.azure:azure-ai-agents

Ortam değişkenleri

Değişken	Açıklama
`FOUNDRY_PROJECT_ENDPOINT`	Foundry proje uç noktası URL'niz (dış OpenAPI hizmet uç noktası değil).
`FOUNDRY_MODEL_DEPLOYMENT_NAME`	Dağıtılan modelin adı.
`OPENAPI_PROJECT_CONNECTION_NAME`	(API anahtarı kimlik doğrulaması için) OpenAPI hizmeti için proje bağlantı adınız.

Bu gereksinimleri karşılayan OpenAPI 3.0 veya 3.1 belirtim dosyası:
- Her işlevin bir operationId değeri olmalıdır (OpenAPI aracı için gereklidir).
- operationId yalnızca harfleri, - ve _ içermelidir.
- Modellerin hangi işlevin kullanılacağına verimli bir şekilde karar vermesine yardımcı olması için açıklayıcı adlar kullanın.
- Desteklenen istek gövdesi içerik türleri: application/json, application/json-patch+json
Yönetilen kimlik kimlik doğrulaması için: gerekli API işlemlerine izin veren ve Foundry projesinin yönetilen kimliğine hedef kaynağın kapsamında atanan en az ayrıcalıklı hedef hizmet rolü.
API anahtarı/belirteç kimlik doğrulaması için: API anahtarınız veya belirteciniz ile yapılandırılmış bir proje bağlantısı. Bkz. Projenize yeni bağlantı ekleme.

Not

FOUNDRY_PROJECT_ENDPOINT değeri, dış OpenAPI hizmet uç noktasını değil Microsoft Foundry proje uç noktanızı ifade eder. Bu uç noktayı projenizin Genel Bakış sayfasının altındaki Microsoft Foundry portalında bulabilirsiniz. Bu uç nokta, aracı hizmetinin kimliğini doğrulamak için gereklidir ve belirtim dosyanızda tanımlanan tüm OpenAPI uç noktalarından ayrıdır.

Kullanım desteği

Aşağıdaki tabloda SDK ve kurulum desteği gösterilmektedir.

Microsoft Foundry desteği	Python SDK'sı	C# SDK'sı	JavaScript SDK'sı	Java SDK'sı	REST API	Temel aracı kurulumu	Standart ajan kurulumu
✔️	✔️	✔️	✔️	✔️	✔️	✔️	✔️

Not

Java için OpenAPI aracı araçları için com.azure:azure-ai-agents paketini kullanın. Paket com.azure:azure-ai-projects şu anda OpenAPI aracı araç türlerini kullanıma sunmaz.

Anonim ilk başarı akışını çalıştırın

Aracınızın bir OpenAPI belirtimi yükleyip bir işlem çağırabildiğini doğrulamak için anonim hava durumu API'si ile başlayın. Bu yol, dış API kimlik bilgisi veya Dökümhane projesi bağlantısı gerektirmez.

Önkoşullar'dan seçtiğiniz dil için SDK paketini yükleyin.
weather_openapi.json dosyasını indirin ve örneğin kullandığı assets yoluna kaydedin.
Foundry proje uç noktanızı ve model dağıtım değerlerinizi ayarlayın.
Anonim örneği seçtiğiniz dil bölümünde çalıştırın.
Yanıtın Seattle için geçerli hava durumunu içerdiğini onaylayın ve ardından örnek tarafından oluşturulan aracı sürümünü silin.

Anonim çağrı başarılı olduktan sonra hedef API'nizin gerektirdiği kimlik doğrulamasını yapılandırın. API anahtarı kimlik doğrulaması, taşıyıcı belirteç kimlik doğrulaması ve yönetilen kimlik kimlik doğrulamalarını ayrı çeşitlemeler olarak tutun.

Sınırlamaları anlama

OpenAPI belirtiminizin her işlem için içermesi operationId gerekir ve operationId yalnızca , ve -harflerini _içerebilir.
Desteklenen istek gövdesi içerik türleri: application/json, application/json-patch+json.
API anahtarı kimlik doğrulaması için OpenAPI aracı başına bir API anahtarı güvenlik düzeni kullanın. Birden çok güvenlik düzenine ihtiyacınız varsa, birden çok OpenAPI aracı oluşturun.
API anahtarlarını ve taşıyıcı belirteçlerini, şüpheli maruz kalmadan hemen sonra düzenli olarak ve anında döndürün. Kimlik bilgileri değiştiğinde proje bağlantısını güncelleştirin; kimlik bilgilerini OpenAPI belirtimine veya kaynak koduna yerleştirmeyin.

Araç kutusuna OpenAPI araçları ekleme

OpenAPI belirtimi tarafından açıklanan REST API'leri kullanıma açmak için bu düzeni kullanın. API'nizin auth.type güvenlik modeliyle eşleşen öğesini seçin.

Önemli

Yönetilen kimlik doğrulaması kullandığınızda, hedef hizmette Foundry projenizin yönetilen kimliğine gerekli API işlemlerine izin veren yalnızca en az ayrıcalıklı RBAC rolünü atayın. Örneğin, yalnızca API'nin salt okunur Azure Resource Manager'a erişmesi gerektiğinde hedef Azure kaynağına Okuyucu atayın. Gerekli atama olmadan, aracı API'yi çağırırken bir 401 Unauthorized yanıt alır. Tam kurulum adımları için bkz . Yönetilen kimliği kullanarak kimlik doğrulaması.

Anonim kimlik doğrulaması:

{
  "description": "REST API via OpenAPI spec",
  "tools": [
    {
      "type": "openapi",
      "openapi": {
        "name": "my-api",
        "spec": { "<paste OpenAPI spec object here>" },
        "auth": {
          "type": "anonymous"
        }
      }
    }
  ]
}

Proje bağlantısı kimlik doğrulaması:

API, Foundry proje bağlantısına depolanan bir anahtar veya belirteç gerektirdiğinde bu şablonu kullanın.

{
  "description": "REST API with connection-based auth",
  "tools": [
    {
      "type": "openapi",
      "openapi": {
        "name": "my-api",
        "spec": { "<paste OpenAPI spec object here>" },
        "auth": {
          "type": "connection",
          "security_scheme": {
            "project_connection_id": "<CONNECTION_NAME>"
          }
        }
      }
    }
  ]
}

Yönetilen kimlik doğrulaması:

Hedef API, Microsoft Entra ID aracılığıyla kimlik doğrulaması yaparken bu kalıbı kullanın. Foundry projesinin yönetilen kimliği, aracı adına API'yi çağırır. Bu düzeni kullanmadan önce yönetilen kimliğin hedef hizmette gerekli RBAC rolüne sahip olduğundan emin olun.

{
  "description": "REST API with managed identity auth",
  "tools": [
    {
      "type": "openapi",
      "openapi": {
        "name": "my-api",
        "spec": { "<paste OpenAPI spec object here>" },
        "auth": {
          "type": "managed_identity",
          "security_scheme": {
            "audience": "<TARGET_SERVICE_AUDIENCE>"
          }
        }
      }
    }
  ]
}

from azure.ai.projects.models import OpenAPITool

tools = [
    OpenAPITool(
        name="my-api",
        spec={"<paste OpenAPI spec object here>"},
        auth={"type": "anonymous"},
    )
]

BinaryData specBytes = BinaryData.FromString("<OpenAPI spec JSON>");
ProjectsAgentTool tool = new OpenAPITool(
    new OpenApiFunctionDefinition(
        name: "my-api",
        spec: specBytes,
        openApiAuthentication: new OpenApiAnonymousAuthDetails()
    )
);

ToolboxVersion toolboxVersion = await toolboxClient.CreateToolboxVersionAsync(
    toolboxName: "my-toolbox",
    tools: [tool],
    description: "REST API via OpenAPI spec"
);

const tools = [
  {
    type: "openapi",
    openapi: {
      name: "my-api",
      spec: { /* paste OpenAPI spec object here */ },
      auth: {
        type: "anonymous",
      },
    },
  },
];

Azure Geliştirici CLI ile OpenAPI araç kutusu oluşturma

OpenAPI araçları belirtimi doğrudan altına tools:ekler. Bağlantı tabanlı kimlik doğrulaması (connection_auth) bir proje bağlantısına başvurur; anonim OpenAPI araçları için bağlantı gerekmez.

Adım 1. (İsteğe bağlı) Kimlik doğrulama bağlantısını oluşturma

Anonim OpenAPI araçları için bu adımı atlayın.

# API-key auth (passed by the platform on every call)
# Set OPENAPI_AUTHORIZATION_HEADER in your shell without committing its value.
azd ai connection create my-api-conn \
  --kind remote-tool \
  --target https://api.example.com \
  --auth-type custom-keys \
  --custom-key "Authorization=$OPENAPI_AUTHORIZATION_HEADER"

OpenAPI araçları --auth-type oauth2 bağlantıları da kabul eder. Bayrak kümesinin azd ai connection create tamamı için bkz. Toolbox MCP kimlik doğrulaması ve yapılandırması.

Adım 2. Araç kutusunu tanımlama

OpenAPI spesifikasyonu, tools[].openapi.spec altında satır içindedir.

# my-toolbox.yaml
description: OpenAPI toolbox
tools:
  - type: openapi
    name: my-api
    openapi:
      name: my-api
      spec:
        openapi: "3.0.1"
        info:
          title: "My API"
          version: "1.0"
        servers:
          - url: https://api.example.com/v1
        paths:
          /search:
            get:
              operationId: search
              parameters:
                - name: query
                  in: query
                  required: true
                  schema:
                    type: string
              responses:
                "200":
                  description: OK
      auth:
        type: connection_auth
        connection_id: my-api-conn

Anonim API'ler için auth: bloğunu şununla değiştirin:

      auth:
        type: anonymous
        security_scheme:
          type: anonymous

Adım 3. Araç kutusunu oluşturma

azd ai toolbox create my-toolbox --from-file my-toolbox.yaml

Kod örneklerini çalıştırmadan önce

Güncel tripadvisor_openapi.json spesifikasyonunu indirin ve dil örneğinizin kullandığı assets yoluna kaydedin.

Not

En son SDK paketine ihtiyacınız vardır. .NET SDK şu anda önizleme aşamasındadır. Ayrıntılar için hızlı başlangıç bölümüne bakın.
Kimlik doğrulaması için API anahtarı kullanıyorsanız bağlantı kimliğiniz /subscriptions/{{subscriptionID}}/resourceGroups/{{resourceGroupName}}/providers/Microsoft.CognitiveServices/accounts/{{foundryAccountName}}/projects/{{foundryProjectName}}/connections/{{foundryConnectionName}} biçiminde olmalıdır.

Önemli

API anahtarı kimlik doğrulamasının çalışması için OpenAPI belirtim dosyanız şunları içermelidir:

securitySchemes Başlık adı ve parametre adı gibi API anahtar yapılandırmanızı içeren bir bölüm.
security Güvenlik düzenine başvuran bir bölüm.
Eşleşen anahtar adı ve değeriyle yapılandırılmış bir proje bağlantısı.

Bu yapılandırmalar olmadan API anahtarı isteklere dahil değildir. Ayrıntılı kurulum yönergeleri için API anahtarıyla kimlik doğrulaması bölümüne bakın.

Proje bağlantısında belirteci depolayarak, belirteç tabanlı kimlik doğrulamasını (örneğin, Bearer belirteç) de kullanabilirsiniz. Taşıyıcı jeton kimlik doğrulaması için anahtarı ve değeri Authorization olarak ayarlanmış özel bir Bearer <token> bağlantısı oluşturun (değeri gerçek jetonunuzla değiştirin<token>). Sözcük Bearer ardından bir boşlukla birlikte değere eklenmelidir. Ayrıntılar için bkz. Taşıyıcı belirteci bağlantısı ayarlama.

OpenAPI aracısıyla aracı kullanma örneği

Bu örnekte, aracı kullanarak OpenAPI belirtimi tarafından açıklanan hizmetlerin nasıl kullanılacağı gösterilmektedir. Hava durumunu ve belirtim dosyasını weather_openapi.json almak için wttr.in hizmetini kullanır. sunucu tarafı istem aracısı oluşturmak için Azure AI Projeleri SDK'sını kullanmak için Prompt Agents öğesini veya kısa ömürlü, işlem içi aracı oluşturmak için Microsoft Agent Framework' kullanmak için Hosted Agents öğesini seçin.

Yönlendirme ajanları

import os
import jsonref
from typing import Any, cast
from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import (
    PromptAgentDefinition,
    OpenApiTool,
    OpenApiFunctionDefinition,
    OpenApiAnonymousAuthDetails,
)

# Format: "https://resource_name.ai.azure.com/api/projects/project_name"
PROJECT_ENDPOINT = "your_project_endpoint"

# Create clients to call Foundry API
project = AIProjectClient(
    endpoint=PROJECT_ENDPOINT,
    credential=DefaultAzureCredential(),
)
openai = project.get_openai_client()

weather_asset_file_path = os.path.abspath(
    os.path.join(os.path.dirname(__file__), "../assets/weather_openapi.json")
)

with open(weather_asset_file_path, "r") as f:
    openapi_weather = cast(dict[str, Any], jsonref.loads(f.read()))

# Initialize agent OpenAPI tool using the read in OpenAPI spec
weather_tool = OpenApiTool(
    openapi=OpenApiFunctionDefinition(
        name="get_weather",
        spec=openapi_weather,
        description="Retrieve weather information for a location.",
        auth=OpenApiAnonymousAuthDetails(),
    )
)

agent = project.agents.create_version(
    agent_name="MyAgent",
    definition=PromptAgentDefinition(
        model="gpt-4.1-mini",
        instructions="You are a helpful assistant.",
        tools=[weather_tool],
    ),
)
response = openai.responses.create(
    input="What's the weather in Seattle?",
    extra_body={"agent_reference": {"name": agent.name, "type": "agent_reference"}},
)
print(response.output_text)

# Clean up resources
project.agents.delete_version(agent_name=agent.name, agent_version=agent.version)

Bu örnek, anonim kimlik doğrulaması kullanarak wttr.in hava durumu API'sini çağıran bir OpenAPI aracısıyla bir istem aracısı oluşturur. Araç doğrudan ajan tanımına bağlanır. Kodu çalıştırdığınızda:

Yerel bir JSON dosyasından hava Durumu OpenAPI belirtimini yükler.
Anonim erişim için yapılandırılmış hava durumu aracıyla bir istem aracısı oluşturur.
Seattle'ın hava durumunu soran bir sorgu gönderir.
Aracı, hava durumu API'sini çağırmak için OpenAPI aracını kullanır ve biçimlendirilmiş sonuçlar döndürür.
Aracı sürümünü silerek temizler.

Barındırılan aracılar

Bu örnek, Microsoft Agent Framework’ten FoundryChatClient kullanır ve FoundryToolbox kullanarak toolbox MCP uç noktasına bağlanır. ile pip install "agent-framework-foundry==1.10.4" "azure-ai-projects>=2.3.0,<2.4.0" azure-identity jsonrefuyumlu paket sürümlerini yükleyin, ortam değişkenini FOUNDRY_PROJECT_ENDPOINT ayarlayın ve ile az loginoturum açın. OpenApiToolboxTool araç kutusuna özgü modeldir; yalnızca aracıyı doğrudan bir istem aracısına eklerken kullanın OpenApiTool .

import asyncio
import os
import jsonref
from typing import Any, cast

from agent_framework import Agent
from agent_framework.foundry import FoundryChatClient, FoundryToolbox
from azure.identity import AzureCliCredential
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import (
    OpenApiToolboxTool,
    OpenApiFunctionDefinition,
    OpenApiAnonymousAuthDetails,
)

PROJECT_ENDPOINT = "https://<account>.services.ai.azure.com/api/projects/<project>"


async def main() -> None:
    credential = AzureCliCredential()

    # 1. Create the OpenAPI tool and add it to a toolbox. Using a toolbox is the
    #    recommended way to give agents tools: curate tools once and reuse the
    #    toolbox across agents. See /azure/foundry/agents/concepts/toolbox-overview
    project = AIProjectClient(endpoint=PROJECT_ENDPOINT, credential=credential)

    weather_asset_file_path = os.path.abspath(
        os.path.join(os.path.dirname(__file__), "../assets/weather_openapi.json")
    )
    with open(weather_asset_file_path, "r") as f:
        openapi_weather = cast(dict[str, Any], jsonref.loads(f.read()))

    weather_tool = OpenApiToolboxTool(
        openapi=OpenApiFunctionDefinition(
            name="get_weather",
            spec=openapi_weather,
            description="Retrieve weather information for a location.",
            auth=OpenApiAnonymousAuthDetails(),
        )
    )

    toolbox = project.toolboxes.create_version(
        name="openapi-toolbox",
        description="Toolbox with the OpenAPI weather tool",
        tools=[weather_tool],
    )

    # 2. The toolbox exposes an MCP-compatible endpoint.
    TOOLBOX_MCP_URL = (
        f"{PROJECT_ENDPOINT}/toolboxes/{toolbox.name}"
        f"/versions/{toolbox.version}/mcp?api-version=v1"
    )

    # 3. Attach the toolbox to the hosted agent as an MCP tool.
, timeout=120.0)
    toolbox_tool = FoundryToolbox(credential, url=TOOLBOX_MCP_URL)

agent = Agent(
        client=FoundryChatClient(credential=credential),
        instructions="You are a helpful assistant. Use the OpenAPI weather tool to answer questions.",
        tools=[toolbox_tool],
    )

    result = await agent.run("What's the weather in Seattle?")
    print(f"Agent: {result.text}")


if __name__ == "__main__":
    asyncio.run(main())

Beklenen çıkış

Agent: The weather in Seattle is currently cloudy with a temperature of 52°F (11°C)...

OpenAPI aracısıyla aracı kullanma örneği

Yönlendirme ajanları

Bu örnek, Azure AI Projeleri istemci kitaplığının zaman uyumlu yöntemlerini kullanır. Zaman uyumsuz yöntemler kullanan bir örnek için, GitHub .NET deposu için Azure SDK sample bölümüne bakın.

using System;
using System.IO;
using System.Runtime.CompilerServices;
using Azure.AI.Projects;
using Azure.AI.Extensions.OpenAI;
using Azure.Identity;

class OpenAPIDemo
{
    // Utility method to get the OpenAPI specification file from the Assets folder.
    private static string GetFile([CallerFilePath] string pth = "")
    {
        var dirName = Path.GetDirectoryName(pth) ?? "";
        return Path.Combine(dirName, "Assets", "weather_openapi.json");
    }

    public static void Main()
    {
        // Format: "https://resource_name.ai.azure.com/api/projects/project_name"
        var projectEndpoint = "your_project_endpoint";

        // Create project client to call Foundry API
        AIProjectClient projectClient = new(
            endpoint: new Uri(projectEndpoint),
            tokenProvider: new DefaultAzureCredential());

        // Create an Agent with `OpenAPIAgentTool` and anonymous authentication.
        string filePath = GetFile();
        OpenAPIFunctionDefinition toolDefinition = new(
            name: "get_weather",
            spec: BinaryData.FromBytes(File.ReadAllBytes(filePath)),
            auth: new OpenAPIAnonymousAuthenticationDetails()
        );
        toolDefinition.Description = "Retrieve weather information for a location.";
        OpenAPITool openapiTool = new(toolDefinition);

        // Create the agent definition and the agent version.
        DeclarativeAgentDefinition agentDefinition = new(model: "gpt-4.1-mini")
        {
            Instructions = "You are a helpful assistant.",
            Tools = { openapiTool }
        };
        AgentVersion agentVersion = projectClient.AgentAdministrationClient.CreateAgentVersion(
            agentName: "myAgent",
            options: new(agentDefinition));

        // Create a response object and ask the question about the weather in Seattle, WA.
        ProjectResponsesClient responseClient = projectClient.ProjectOpenAIClient.GetProjectResponsesClientForAgent(agentVersion.Name);
        ResponseResult response = responseClient.CreateResponse(
                userInputText: "Use the OpenAPI tool to print out, what is the weather in Seattle, WA today."
            );
        Console.WriteLine(response.GetOutputText());

        // Finally, delete all the resources created in this sample.
        projectClient.AgentAdministrationClient.DeleteAgentVersion(agentName: agentVersion.Name, agentVersion: agentVersion.Version);
    }
}

Bu kod ne yapar?

Bu C# örneği, anonim kimlik doğrulaması kullanarak wttr.in hava durumu bilgilerini alan bir OpenAPI aracıyla bir aracı oluşturur. Kodu çalıştırdığınızda:

Yerel bir JSON dosyasından hava durumu OpenAPI belirtimini okur.
Hava durumu aracının yapılandırıldığı bir aracı oluşturur.
OpenAPI aracını kullanarak Seattle'ın hava durumunu soran bir istek gönderir.
Ajan hava durumu API'sini çağırır ve sonuçları döndürür.
Aracıyı silerek temizler.

Gerekli girişler

Satır içi dize değeri: projectEndpoint (Dökümhane proje uç noktanız)
Yerel dosya: Assets/weather_openapi.json (OpenAPI belirtimi)

Beklenen çıkış

The weather in Seattle, WA today is cloudy with temperatures around 52°F...

Yaygın hatalar

FileNotFoundException: OpenAPI belirtim dosyası Varlıklar klasöründe bulunamadı
UnauthorizedAccessException: Geçersiz kimlik bilgileri veya yetersiz RBAC izinleri
API anahtarı eklenmedi: OpenAPI belirtiminizin hem (içindesecuritySchemes) components hem de security eşleşen düzen adlarına sahip bölümleri içerdiğini doğrulayın

Barındırılan aracılar

Bu örnek, Azure AI Projeleri SDK'sı ile OpenAPI araç kutusunu oluşturur ve ardından aracıyı barındırılan aracı için kullanılabilir hale getirmek için Microsoft Agent Framework AddFoundryToolboxes tümleştirmesini kullanır. Agent Framework paketlerini yükleyin, AZURE_AI_PROJECT_ENDPOINT proje uç noktasını ve AZURE_AI_MODEL_DEPLOYMENT_NAME ortam değişkenlerini ayarlayın ve az login ile oturum açın.

using System.IO;
using System.Runtime.CompilerServices;
using Azure.AI.AgentServer.Responses;
using Azure.AI.AgentServer.Responses.Models;
using Azure.AI.OpenAI;
using Azure.AI.Projects;
using Azure.AI.Extensions.OpenAI;
using Azure.Identity;
using Microsoft.Agents.AI;
using Microsoft.Agents.AI.Foundry.Hosting;
using Microsoft.Extensions.DependencyInjection;
using OpenAI.Chat;

string GetFile([CallerFilePath] string pth = "")
{
    var dirName = Path.GetDirectoryName(pth) ?? "";
    return Path.Combine(dirName, "Assets", "weather_openapi.json");
}

string projectEndpoint = Environment.GetEnvironmentVariable("AZURE_AI_PROJECT_ENDPOINT")
    ?? "https://<account>.services.ai.azure.com/api/projects/<project>";
string deploymentName = Environment.GetEnvironmentVariable("AZURE_AI_MODEL_DEPLOYMENT_NAME") ?? "gpt-5-mini";

var openAiEndpoint = new Uri(projectEndpoint).GetLeftPart(UriPartial.Authority);
DefaultAzureCredential credential = new();

// 1. Create the OpenAPI tool and add it to a toolbox. Using a toolbox is the
//    recommended way to give agents tools. See /azure/foundry/agents/concepts/toolbox-overview
AIProjectClient projectClient = new(endpoint: new Uri(projectEndpoint), tokenProvider: credential);
string filePath = GetFile();
OpenAPIFunctionDefinition toolDefinition = new(
    name: "get_weather",
    spec: BinaryData.FromBytes(File.ReadAllBytes(filePath)),
    auth: new OpenAPIAnonymousAuthenticationDetails()
);
toolDefinition.Description = "Retrieve weather information for a location.";
ProjectsAgentTool openapiTool = new OpenAPITool(toolDefinition);
ToolboxVersion toolboxVersion = projectClient.AgentAdministrationClient
    .GetAgentToolboxes().CreateToolboxVersion(
        toolboxName: "openapi-toolbox",
        tools: [openapiTool],
        description: "Toolbox with the OpenAPI weather tool");

// Create the hosted agent and register the toolbox integration.
AIAgent agent = projectClient.AsAIAgent(
    model: deploymentName,
    instructions: "You are a helpful assistant with access to the toolbox tools.",
    name: "hosted-toolbox-agent");

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddFoundryResponses(agent);
builder.Services.AddFoundryToolboxes(credential, toolboxVersion.Name);

var app = builder.Build();
app.MapFoundryResponses();
app.Run();

Beklenen çıkış

Aracı, OpenAPI aracı aracılığıyla hava durumu API'sini çağırır ve istenen konum için geçerli koşulları döndürür:

The current weather in Seattle is <temperature> with <conditions>.

Kimliği doğrulanmış API desenleri de dahil olmak üzere tam örnek için bkz. Agent_Step17_OpenAPITools.

OpenAPI aracını kullanan Web hizmetinde aracı kullanımı örneği, kimlik doğrulaması gerektirir.

Bu örnekte, bir araç kutusuna kimliği doğrulanmış bir OpenAPI aracı ekler, araç kutusunu MCP aracı olarak ekler ve aracıyı kimlik doğrulaması gerektiren bir senaryoda kullanırsınız. TripAdvisor spesifikasyonunu kullanıyorsunuz.

TripAdvisor hizmeti anahtar tabanlı kimlik doğrulaması gerektirir. Bağlantı oluşturmak için Microsoft Dökümhanesi'ni açın, sağ üst gezinti bölmesinde Yönet'i seçin, Project ayrıntıları'nı ve ardından Bağlı kaynaklar sekmesini seçin. Son olarak, Özel anahtar türünde yeni bir bağlantı oluşturun. Ad verin tripadvisor ve bir anahtar değer çifti ekleyin. adlı key anahtarı ekleyin ve TripAdvisor anahtarınızla bir değer girin.

class OpenAPIConnectedDemo
{
    // Utility method to get the OpenAPI specification file from the Assets folder.
    private static string GetFile([CallerFilePath] string pth = "")
    {
        var dirName = Path.GetDirectoryName(pth) ?? "";
        return Path.Combine(dirName, "Assets", "tripadvisor_openapi.json");
    }

    public static void Main()
    {
        // Format: "https://resource_name.ai.azure.com/api/projects/project_name"
        var projectEndpoint = "your_project_endpoint";

        // Create project client to call Foundry API
        AIProjectClient projectClient = new(
            endpoint: new Uri(projectEndpoint),
            tokenProvider: new DefaultAzureCredential());

        // Create an OpenAPI tool with authentication by project connection security scheme.
        string filePath = GetFile();
        AIProjectConnection tripadvisorConnection = projectClient.Connections.GetConnection("tripadvisor");
        OpenAPIFunctionDefinition toolDefinition = new(
            name: "tripadvisor",
            spec: BinaryData.FromBytes(File.ReadAllBytes(filePath)),
            auth: new OpenAPIProjectConnectionAuthenticationDetails(new OpenAPIProjectConnectionSecurityScheme(
                projectConnectionId: tripadvisorConnection.Id
            ))
        );
        toolDefinition.Description = "Trip Advisor API to get travel information.";
        ProjectsAgentTool openapiTool = new OpenAPITool(toolDefinition);

        // 1. Add the authenticated OpenAPI tool to a toolbox. Using a toolbox is the
        //    recommended way to give agents tools. See /azure/foundry/agents/concepts/toolbox-overview
        AgentToolboxes toolboxClient = projectClient.AgentAdministrationClient.GetAgentToolboxes();

        ToolboxVersion toolboxVersion = projectClient.AgentAdministrationClient
            .GetAgentToolboxes().CreateToolboxVersion(
                toolboxName: "openapi-toolbox",
                tools: [openapiTool],
                description: "Toolbox with the authenticated TripAdvisor OpenAPI tool");

        // 2. The toolbox exposes an MCP-compatible endpoint.
        var toolboxMcpUrl = new Uri(
            $"{projectEndpoint}/toolboxes/{toolboxVersion.Name}" +
            $"/versions/{toolboxVersion.Version}/mcp?api-version=v1");

        // 3. Create a remote-tool project connection that points at the toolbox endpoint.
        //    Use a user Entra token so the caller's identity is passed through
        //    (audience https://ai.azure.com). Create the connection once, for example
        //    with the Azure Developer CLI:
        //
        //    azd ai connection create openapi-toolbox-conn \
        //      --kind remote-tool \
        //      --target "<toolboxMcpUrl>" \
        //      --auth-type user-entra-token \
        //      --audience https://ai.azure.com
        var toolboxConnectionName = "openapi-toolbox-conn";

        // 4. Attach the toolbox to a prompt agent as an MCP tool.
        McpTool toolboxTool = ResponseTool.CreateMcpTool(
            serverLabel: "toolbox",
            serverUri: toolboxMcpUrl,
            toolCallApprovalPolicy: new McpToolCallApprovalPolicy(
                GlobalMcpToolCallApprovalPolicy.NeverRequireApproval));
        toolboxTool.ProjectConnectionId = toolboxConnectionName;

        // Create the agent definition and the agent version.
        DeclarativeAgentDefinition agentDefinition = new(model: "gpt-4.1-mini")
        {
            Instructions = "You are a helpful assistant.",
            Tools = { toolboxTool }
        };
        AgentVersion agentVersion = projectClient.AgentAdministrationClient.CreateAgentVersion(
            agentName: "myAgent",
            options: new(agentDefinition));

        // Create a response object and ask the question about the hotels in France.
        // Test the Web service access before you run production scenarios.
        // It can be done by setting:
        // ToolChoice = ResponseToolChoice.CreateRequiredChoice()`
        // in the ResponseCreationOptions. This setting will
        // force Agent to use tool and will trigger the error if it is not accessible.
        ProjectResponsesClient responseClient = projectClient.ProjectOpenAIClient.GetProjectResponsesClientForAgent(agentVersion.Name);
        CreateResponseOptions responseOptions = new()
        {
            ToolChoice = ResponseToolChoice.CreateRequiredChoice(),
            InputItems =
            {
                ResponseItem.CreateUserMessageItem("Recommend me 5 top hotels in paris, France."),
            }
        };
        ResponseResult response = responseClient.CreateResponse(
            options: responseOptions
        );
        Console.WriteLine(response.GetOutputText());

        // Finally, delete all the resources we have created in this sample.
        projectClient.AgentAdministrationClient.DeleteAgentVersion(agentName: agentVersion.Name, agentVersion: agentVersion.Version);
    }
}

Bu kod ne yapar?

Bu C# örneği, bir araç kutusu ve proje bağlantısı aracılığıyla API anahtarı kimlik doğrulaması ile OpenAPI aracının kullanılmasını gösterir. Kodu çalıştırdığınızda:

TripAdvisor OpenAPI belirtimini yerel bir dosyadan yükler.
tripadvisor API anahtarınızı içeren proje bağlantısını alır.
Kimlik doğrulaması için bağlantıyı kullanacak şekilde yapılandırılmış TripAdvisor aracını içeren bir araç kutusu sürümü oluşturur.
Araç kutusunu ajana bir MCP aracı olarak bağlar.
Paris'te otel önerileri için bir istek gönderir.
Aracı, depolanan API anahtarınızı kullanarak TripAdvisor API'sini çağırır ve sonuçları döndürür.
Aracıyı silerek temizler.

Gerekli girişler

Satır içi dize değeri: projectEndpoint (Dökümhane proje uç noktanız)
Yerel dosya: Assets/tripadvisor_openapi.json
Project bağlantısı: tripadvisor geçerli bir API anahtarı yapılandırılmış

Beklenen çıkış

Here are 5 top hotels in Paris, France:
1. Hotel Name - Rating: 4.5/5, Location: ...
2. Hotel Name - Rating: 4.4/5, Location: ...
...

Yaygın hatalar

ConnectionNotFoundException: Adlı tripadvisor proje bağlantısı bulunamadı.
AuthenticationException: Proje bağlantısında geçersiz API anahtarı veya OpenAPI belirtiminde eksik/yanlış securitySchemes yapılandırma.
Kullanılmayan araç: Araç kullanımını zorladığını doğrulamak için ToolChoice = ResponseToolChoice.CreateRequiredChoice() kontrol edin.
API anahtarı API'ye geçirilmedi: OpenAPI belirtiminin düzgün securitySchemes olduğundan ve security bölümlerin yapılandırıldığından emin olun.

OpenAPI aracı özellikleriyle Java aracısı oluşturma

Bu Java kurulumu MCP araçlarına başvurabilir, ancak Java SDK henüz bir araç kutusu oluşturma API'sini kullanıma sunmaz.

Ipucu

Önerilen: Çoğu aracı için OpenAPI aracını bir araç kutusu aracılığıyla ekleyin ve araç kutusunu aracınıza MCP aracı olarak ekleyin. Python, REST API, C# veya TypeScript örneğini veya Foundry portalını kullanarak araç kutusunu oluşturun ve ardından Java aracınızdan MCP uç noktasına olarak McpToolbaşvurun.

Aşağıdaki örneklerde, REST API kullanarak OpenAPI aracının nasıl çağrıldığı gösterilmektedir.

Erişim belirteci alma:

AGENT_TOKEN=$(az account get-access-token --scope https://ai.azure.com/.default --query accessToken -o tsv)

Anonim kimlik doğrulaması

OpenAPI araçlarını bir araç kutusu aracılığıyla ekleyin ve ardından araç kutusunu aracınıza MCP aracı olarak ekleyin. Daha fazla bilgi için bkz. Araç kutusu nedir?

OpenAPI hava durumu aracını içeren bir araç kutusu oluşturun:

curl --request POST \
  --url "$FOUNDRY_PROJECT_ENDPOINT/toolboxes/openapi-toolbox/versions?api-version=v1" \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{
    "description": "Toolbox with the OpenAPI weather tool",
    "tools": [
      {
        "type": "openapi",
        "openapi": {
          "name": "weather",
          "description": "Tool to get weather data",
          "auth": { "type": "anonymous" },
          "spec": {
            "openapi": "3.1.0",
            "info": {
              "title": "get weather data",
              "description": "Retrieves current weather data for a location.",
              "version": "v1.0.0"
            },
            "servers": [{ "url": "https://wttr.in" }],
            "paths": {
              "/{location}": {
                "get": {
                  "description": "Get weather information for a specific location",
                  "operationId": "GetCurrentWeather",
                  "parameters": [
                    {
                      "name": "location",
                      "in": "path",
                      "description": "City or location to retrieve the weather for",
                      "required": true,
                      "schema": { "type": "string" }
                    },
                    {
                      "name": "format",
                      "in": "query",
                      "description": "Format in which to return data. Always use 3.",
                      "required": true,
                      "schema": { "type": "integer", "default": 3 }
                    }
                  ],
                  "responses": {
                    "200": {
                      "description": "Successful response",
                      "content": {
                        "text/plain": {
                          "schema": { "type": "string" }
                        }
                      }
                    },
                    "404": { "description": "Location not found" }
                  }
                }
              }
            }
          }
        }
      }
    ]
  }'

Araç kutusu, $FOUNDRY_PROJECT_ENDPOINT/toolboxes/openapi-toolbox/versions/<version>/mcp?api-version=v1 adresinde MCP uyumlu bir uç nokta sunar; burada <version>, önceki çağrının döndürdüğü sürümdür.

Çağıranın kimliğinin iletilebilmesi için kullanıcı Entra belirteci kullanarak araç kutusu uç noktasına işaret eden bir uzak araç projesi bağlantısı oluşturun (hedef kitle https://ai.azure.com).

azd ai connection create openapi-toolbox-conn \
  --kind remote-tool \
  --target "$FOUNDRY_PROJECT_ENDPOINT/toolboxes/openapi-toolbox/versions/<version>/mcp?api-version=v1" \
  --auth-type user-entra-token \
  --audience https://ai.azure.com

Araç kutusunu MCP aracı olarak ekleyip kullanan bir yanıt oluşturun.

curl --request POST \
  --url "$FOUNDRY_PROJECT_ENDPOINT/openai/v1/responses" \
  --header "Authorization: Bearer $AGENT_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "'$FOUNDRY_MODEL_DEPLOYMENT_NAME'",
    "input": "Use the OpenAPI tool to get the weather in Seattle, WA today.",
    "tool_choice": "required",
    "tools": [
      {
        "type": "mcp",
        "server_label": "toolbox",
        "server_url": "'$FOUNDRY_PROJECT_ENDPOINT'/toolboxes/openapi-toolbox/versions/<version>/mcp?api-version=v1",
        "require_approval": "never",
        "project_connection_id": "openapi-toolbox-conn"
      }
    ]
  }'

API anahtarı kimlik doğrulaması (proje bağlantısı)

Bu değişkeni yalnızca anonim akış başarılı olduktan sonra kullanın. Proje bağlantısını ve OpenAPI securitySchemes girişini API anahtarıyla kimlik doğrulaması bölümünde açıklandığı gibi yapılandırın.

curl --request POST \
  --url "$FOUNDRY_PROJECT_ENDPOINT/openai/v1/responses" \
  --header "Authorization: Bearer $AGENT_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "'$FOUNDRY_MODEL_DEPLOYMENT_NAME'",
    "input": "Use the OpenAPI tool to get the weather in Seattle, WA today.",
    "tools": [
      {
        "type": "openapi",
        "openapi": {
          "name": "weather",
          "description": "Tool to get weather data",
          "auth": {
            "type": "project_connection",
            "security_scheme": {
              "project_connection_id": "'$WEATHER_APP_PROJECT_CONNECTION_ID'"
            }
          },
          "spec": {
            "openapi": "3.1.0",
            "info": {
              "title": "get weather data",
              "description": "Retrieves current weather data for a location.",
              "version": "v1.0.0"
            },
            "servers": [{ "url": "https://wttr.in" }],
            "paths": {
              "/{location}": {
                "get": {
                  "description": "Get weather information for a specific location",
                  "operationId": "GetCurrentWeather",
                  "parameters": [
                    {
                      "name": "location",
                      "in": "path",
                      "description": "City or location to retrieve the weather for",
                      "required": true,
                      "schema": { "type": "string" }
                    },
                    {
                      "name": "format",
                      "in": "query",
                      "description": "Format in which to return data. Always use 3.",
                      "required": true,
                      "schema": { "type": "integer", "default": 3 }
                    }
                  ],
                  "responses": {
                    "200": {
                      "description": "Successful response",
                      "content": {
                        "text/plain": {
                          "schema": { "type": "string" }
                        }
                      }
                    },
                    "404": { "description": "Location not found" }
                  }
                }
              }
            },
            "components": {
              "securitySchemes": {
                "apiKeyHeader": {
                  "type": "apiKey",
                  "name": "x-api-key",
                  "in": "header"
                }
              }
            },
            "security": [
              { "apiKeyHeader": [] }
            ]
          }
        }
      }
    ]
  }'

Taşıyıcı belirteç API'sinde aynı project_connection istek şeklini koruyun, ancak Taşıyıcı belirteç bağlantısı ayarlama bölümünde açıklandığı gibi yapılandırılmış bir bağlantı kullanın. Bağlantı değeri ile Bearer başlamalıdır ve ardından bir boşluk olmalıdır.

Yönetilen kimlik doğrulaması

curl --request POST \
  --url "$FOUNDRY_PROJECT_ENDPOINT/openai/v1/responses" \
  --header "Authorization: Bearer $AGENT_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "'$FOUNDRY_MODEL_DEPLOYMENT_NAME'",
    "input": "Use the OpenAPI tool to get the weather in Seattle, WA today.",
    "tools": [
      {
        "type": "openapi",
        "openapi": {
          "name": "weather",
          "description": "Tool to get weather data",
          "auth": {
            "type": "managed_identity",
            "security_scheme": {
              "audience": "'$MANAGED_IDENTITY_AUDIENCE'"
            }
          },
          "spec": {
            "openapi": "3.1.0",
            "info": {
              "title": "get weather data",
              "description": "Retrieves current weather data for a location.",
              "version": "v1.0.0"
            },
            "servers": [{ "url": "https://wttr.in" }],
            "paths": {
              "/{location}": {
                "get": {
                  "description": "Get weather information for a specific location",
                  "operationId": "GetCurrentWeather",
                  "parameters": [
                    {
                      "name": "location",
                      "in": "path",
                      "description": "City or location to retrieve the weather for",
                      "required": true,
                      "schema": { "type": "string" }
                    },
                    {
                      "name": "format",
                      "in": "query",
                      "description": "Format in which to return data. Always use 3.",
                      "required": true,
                      "schema": { "type": "integer", "default": 3 }
                    }
                  ],
                  "responses": {
                    "200": {
                      "description": "Successful response",
                      "content": {
                        "text/plain": {
                          "schema": { "type": "string" }
                        }
                      }
                    },
                    "404": { "description": "Location not found" }
                  }
                }
              }
            }
          }
        }
      }
    ]
  }'

Bu kod ne yapar?

Bu REST API örneği, farklı kimlik doğrulama yöntemleriyle bir OpenAPI aracının nasıl çağrılacaklarını gösterir. İstek:

Anonim kimlik doğrulaması için OpenAPI araç tanımını ve hava durumu API'si belirtimini içeren bir araç kutusu oluşturur.
Araç kutusunu MCP aracı olarak ekleyen ve Seattle'ın hava durumunu soran bir yanıt oluşturur.
Proje bağlantısı ve yönetilen kimlik kimlik doğrulaması aracılığıyla API anahtarı için ek doğrudan REST aracı tanımlarını gösterir.
Aracı, hava durumu API'sini çağırır ve biçimlendirilmiş sonuçlar döndürür.

Gerekli girişler

Ortam değişkenleri: FOUNDRY_PROJECT_ENDPOINT, AGENT_TOKEN, FOUNDRY_MODEL_DEPLOYMENT_NAME.
API anahtarı kimlik doğrulaması için: WEATHER_APP_PROJECT_CONNECTION_ID.
Yönetilen kimlik doğrulaması için: MANAGED_IDENTITY_AUDIENCE.
İstek gövdesinde satır içi OpenAPI belirtimi.

Beklenen çıkış

{
  "id": "resp_abc123",
  "object": "response",
  "output": [
    {
      "type": "message",
      "content": [
        {
          "type": "text",
          "text": "The weather in Seattle, WA today is cloudy with a temperature of 52°F (11°C)..."
        }
      ]
    }
  ]
}

Yaygın hatalar

401 Unauthorized: OpenAPI belirtiminizde geçersiz veya eksik AGENT_TOKEN, veya API anahtarı eklenmedi çünkü securitySchemes ve security eksik.
404 Not Found: Yanlış uç nokta veya model dağıtım adı
400 Bad Request: Hatalı biçimlendirilmiş OpenAPI belirtimi veya geçersiz kimlik doğrulama yapılandırması
API anahtarı istekle gönderilmedi: OpenAPI belirtimlerinizdeki bölümün components.securitySchemes düzgün yapılandırıldığını (boş olmadığını) ve proje bağlantı anahtarı adınızla eşleşip eşleşmediğini doğrulayın

OpenAPI aracı özelliklerine sahip bir ajan oluşturun

Aşağıdaki TypeScript kod örneği, OpenAPI aracını bir araç kutusuna ekleyerek ve araç kutusunu MCP aracı olarak ekleyerek OpenAPI araç özellikleriyle yapay zeka aracısının nasıl oluşturulacağını gösterir. Aracı, OpenAPI belirtimleri tarafından tanımlanan dış API'leri çağırabilir. Bu örneğin JavaScript sürümü için, GitHub javascript deposu için Azure SDK sample bölümüne bakın.

import { DefaultAzureCredential } from "@azure/identity";
import {
  AIProjectClient,
  OpenApiTool,
  OpenApiFunctionDefinition,
  OpenApiAnonymousAuthDetails,
} from "@azure/ai-projects";
import * as fs from "fs";
import * as path from "path";

// Format: "https://resource_name.ai.azure.com/api/projects/project_name"
const PROJECT_ENDPOINT = "your_project_endpoint";
const weatherSpecPath = path.resolve(__dirname, "../assets", "weather_openapi.json");

function loadOpenApiSpec(specPath: string): unknown {
  if (!fs.existsSync(specPath)) {
    throw new Error(`OpenAPI specification not found at: ${specPath}`);
  }

  try {
    const data = fs.readFileSync(specPath, "utf-8");
    return JSON.parse(data);
  } catch (error) {
    throw new Error(`Failed to read or parse OpenAPI specification at ${specPath}: ${error}`);
  }
}

function createWeatherTool(spec: unknown): OpenApiTool {
  const auth: OpenApiAnonymousAuthDetails = { type: "anonymous" };
  const definition: OpenApiFunctionDefinition = {
    name: "get_weather",
    description: "Retrieve weather information for a location using wttr.in",
    spec,
    auth,
  };

  return {
    type: "openapi",
    openapi: definition,
  };
}

export async function main(): Promise<void> {
  const weatherSpec = loadOpenApiSpec(weatherSpecPath);

  // Create clients to call Foundry API
  const project = new AIProjectClient(PROJECT_ENDPOINT, new DefaultAzureCredential());
  const openai = project.getOpenAIClient();

  const weatherTool = createWeatherTool(weatherSpec);

  console.log("Creating a toolbox with the OpenAPI weather tool...");

  // 1. Add the OpenAPI tool to a toolbox. Using a toolbox is the recommended
  //    way to give agents tools. See /azure/foundry/agents/concepts/toolbox-overview
  const toolbox = await project.toolboxes.createVersion(
    "openapi-toolbox",
    [weatherTool],
    { description: "Toolbox with the OpenAPI weather tool" },
  );

  // 2. The toolbox exposes an MCP-compatible endpoint.
  const toolboxMcpUrl =
    `${PROJECT_ENDPOINT}/toolboxes/${toolbox.name}` +
    `/versions/${toolbox.version}/mcp?api-version=v1`;

  // 3. Create a remote-tool project connection that points at the toolbox endpoint.
  //    Use a user Entra token so the caller's identity is passed through
  //    (audience https://ai.azure.com). Create the connection once, for example
  //    with the Azure Developer CLI:
  //
  //    azd ai connection create openapi-toolbox-conn \
  //      --kind remote-tool \
  //      --target "<toolboxMcpUrl>" \
  //      --auth-type user-entra-token \
  //      --audience https://ai.azure.com
  const toolboxConnectionName = "openapi-toolbox-conn";

  // 4. Attach the toolbox to a prompt agent as an MCP tool.
  const agent = await project.agents.createVersion("MyOpenApiAgent", {
    kind: "prompt",
    model: "gpt-4.1-mini",
    instructions:
      "You are a helpful assistant that can call external APIs defined by OpenAPI specs to answer user questions.",
    tools: [
      {
        type: "mcp",
        server_label: "toolbox",
        server_url: toolboxMcpUrl,
        require_approval: "never",
        project_connection_id: toolboxConnectionName,
      },
    ],
  });

  // Send a request and stream the response
  const streamResponse = await openai.responses.create(
    {
      input:
        "What's the weather in Seattle and how should I plan my outfit for the day based on the forecast?",
      stream: true,
    },
    {
      body: {
        agent_reference: { name: agent.name, type: "agent_reference" },
        tool_choice: "required",
      },
    },
  );

  // Process the streaming response
  for await (const event of streamResponse) {
    if (event.type === "response.output_text.delta") {
      process.stdout.write(event.delta);
    } else if (event.type === "response.output_text.done") {
      console.log("\n");
    }
  }

  // Clean up resources
  await project.agents.deleteVersion(agent.name, agent.version);
}

main().catch((err) => {
  console.error("The sample encountered an error:", err);
});

Bu kod ne yapar?

Bu TypeScript örneği, anonim kimlik doğrulaması kullanarak hava durumu verileri için OpenAPI aracıyla bir aracı oluşturur. Kodu çalıştırdığınızda:

Yerel bir JSON dosyasından hava Durumu OpenAPI belirtimini yükler.
Hava durumu aracını içeren bir araç kutusu sürümü oluşturur.
Araç kutusunu ajana MCP aracı olarak bağlar, ardından Seattle'ın hava durumu ve ne giyileceğine dair planlama hakkında akışlı bir istek gönderir.
Akış yanıtını işler ve deltaları geldikçe görüntüler.
tool_choice: "required" kullanarak API'nin çağrıldığından emin olmak için araç kullanımını zorlar.
Aracıyı silerek temizler.

Gerekli girişler

Satır içi dize değeri: PROJECT_ENDPOINT (Dökümhane proje uç noktanız)
Yerel dosya: ../assets/weather_openapi.json (OpenAPI belirtimi)

Beklenen çıkış

Loading OpenAPI specifications from assets directory...
Creating agent with OpenAPI tool...
Agent created (id: asst_abc123, name: MyOpenApiAgent, version: 1)

Sending request to OpenAPI-enabled agent with streaming...
Follow-up response created with ID: resp_xyz789
The weather in Seattle is currently...
Tool call completed: get_weather

Follow-up completed!

Cleaning up resources...
Agent deleted

OpenAPI agent sample completed!

Yaygın hatalar

Error: OpenAPI specification not found: Dosya yolu yanlış veya dosya eksik
AuthenticationError: Geçersiz Azure kimlik bilgileri
API anahtarı çalışmıyor: Anonim kimlik doğrulamasından API anahtarı kimlik doğrulamasına geçiş yapıyorsanız, OpenAPI belirtiminizin ve securitySchemes, security yapılandırmalarınızın düzgün ayarlandığından emin olun.

Proje bağlantısıyla kimliği doğrulanmış OpenAPI araçlarını kullanan bir aracı oluşturma

Aşağıdaki TypeScript kod örneği, proje bağlantısı aracılığıyla kimliği doğrulanmış OpenAPI araçlarını kullanan bir yapay zeka aracısının nasıl oluşturulacağını gösterir. Aracı, yerel varlıklardan TripAdvisor OpenAPI belirtimini yükler ve api'yi yapılandırılan proje bağlantısı aracılığıyla çağırabilir. Bu örneğin JavaScript sürümü için, GitHub javascript deposu için Azure SDK sample bölümüne bakın.

import { DefaultAzureCredential } from "@azure/identity";
import {
  AIProjectClient,
  OpenApiTool,
  OpenApiFunctionDefinition,
  OpenApiProjectConnectionAuthDetails,
} from "@azure/ai-projects";
import * as fs from "fs";
import * as path from "path";

// Format: "https://resource_name.ai.azure.com/api/projects/project_name"
const PROJECT_ENDPOINT = "your_project_endpoint";
const TRIPADVISOR_CONNECTION_ID = "your-tripadvisor-connection-id";
const tripAdvisorSpecPath = path.resolve(__dirname, "../assets", "tripadvisor_openapi.json");

function loadOpenApiSpec(specPath: string): unknown {
  if (!fs.existsSync(specPath)) {
    throw new Error(`OpenAPI specification not found at: ${specPath}`);
  }

  try {
    const data = fs.readFileSync(specPath, "utf-8");
    return JSON.parse(data);
  } catch (error) {
    throw new Error(`Failed to read or parse OpenAPI specification at ${specPath}: ${error}`);
  }
}

function createTripAdvisorTool(spec: unknown): OpenApiTool {
  const auth: OpenApiProjectConnectionAuthDetails = {
    type: "project_connection",
    security_scheme: {
      project_connection_id: TRIPADVISOR_CONNECTION_ID,
    },
  };

  const definition: OpenApiFunctionDefinition = {
    name: "get_tripadvisor_location_details",
    description:
      "Fetch TripAdvisor location details, reviews, or photos using the Content API via project connection auth.",
    spec,
    auth,
  };

  return {
    type: "openapi",
    openapi: definition,
  };
}

export async function main(): Promise<void> {
  const tripAdvisorSpec = loadOpenApiSpec(tripAdvisorSpecPath);

  // Create clients to call Foundry API
  const project = new AIProjectClient(PROJECT_ENDPOINT, new DefaultAzureCredential());
  const openai = project.getOpenAIClient();

  // Create an agent with the OpenAPI project-connection tool
  const agent = await project.agents.createVersion("MyOpenApiConnectionAgent", {
    kind: "prompt",
    model: "gpt-4.1-mini",
    instructions:
      "You are a travel assistant that consults the TripAdvisor Content API via project connection to answer user questions about locations.",
    tools: [createTripAdvisorTool(tripAdvisorSpec)],
  });

  // Send a request and stream the response
  const streamResponse = await openai.responses.create(
    {
      input:
        "Provide a quick overview of the TripAdvisor location 293919 including its name, rating, and review count.",
      stream: true,
    },
    {
      body: {
        agent_reference: { name: agent.name, type: "agent_reference" },
        tool_choice: "required",
      },
    },
  );

  // Process the streaming response
  for await (const event of streamResponse) {
    if (event.type === "response.output_text.delta") {
      process.stdout.write(event.delta);
    } else if (event.type === "response.output_text.done") {
      console.log("\n");
    }
  }

  // Clean up resources
  await project.agents.deleteVersion(agent.name, agent.version);
}

main().catch((err) => {
  console.error("The sample encountered an error:", err);
});

Bu kod ne yapar?

Bu TypeScript örneği, proje bağlantısı aracılığıyla API anahtarı kimlik doğrulaması ile OpenAPI aracının kullanılmasını gösterir. Kodu çalıştırdığınızda:

TripAdvisor OpenAPI belirtimini yerel bir dosyadan yükler.
Kimlik doğrulamasını TRIPADVISOR_CONNECTION_ID sabiti kullanarak yapılandırır.
TripAdvisor aracı kullanan ve API anahtarı kimlik doğrulaması için proje bağlantısını kullanan bir ajan oluşturur.
TripAdvisor konum ayrıntıları için bir aktarım isteği gönderir.
tool_choice: "required" kullanarak API'nin çağrıldığından emin olmak için araç kullanımını zorlar.
Akış yanıtını anında işler ve görüntüler.
Aracıyı silerek temizleme işlemi gerçekleştirilir.

Gerekli girişler

Satır içi dize değerleri: PROJECT_ENDPOINT, TRIPADVISOR_CONNECTION_ID
Yerel dosya: ../assets/tripadvisor_openapi.json
TripAdvisor API anahtarıyla yapılandırılmış Project bağlantısı

Beklenen çıkış

Loading TripAdvisor OpenAPI specification from assets directory...
Creating agent with OpenAPI project-connection tool...
Agent created (id: asst_abc123, name: MyOpenApiConnectionAgent, version: 1)

Sending request to TripAdvisor OpenAPI agent with streaming...
Follow-up response created with ID: resp_xyz789
Location 293919 is the Eiffel Tower in Paris, France. It has a rating of 4.5 stars with over 140,000 reviews...
Tool call completed: get_tripadvisor_location_details

Follow-up completed!

Cleaning up resources...
Agent deleted

TripAdvisor OpenAPI agent sample completed!

Yaygın hatalar

Error: OpenAPI specification not found: Dosya yolunu denetleyin.
Bağlantı bulunamadı: Doğru olduğunu ve bağlantının mevcut olduğunu doğrulayın TRIPADVISOR_CONNECTION_ID .
AuthenticationException: Proje bağlantısında geçersiz API anahtarı.
api anahtarı isteklere eklenmedi: OpenAPI belirtiminiz düzgün securitySchemes (altında components) ve security bölümler içermelidir. içindeki securitySchemes anahtar adı proje bağlantınızdaki anahtarla eşleşmelidir.
Content type is not supported: Şu anda yalnızca şu iki istek gövdesi içerik türü desteklenir: application/json ve application/json-patch+json. Yanıt içerik türleri kısıtlanmamıştır.

Güvenlik ve veriyle ilgili dikkat edilmesi gerekenler

Bir aracıyı OpenAPI aracısına bağladığınızda, aracı kullanıcı girişinden türetilen istek parametrelerini hedef API'ye gönderebilir.

Gizli diziler (API anahtarları ve belirteçler) için proje bağlantılarını kullanın. Gizli bilgileri OpenAPI belirtim dosyasına veya kaynak koduna yerleştirmekten kaçının.
Aracı üretimde kullanmadan önce API'nin aldığı verileri ve döndürdüğü verileri gözden geçirin.
En az ayrıcalıklı erişimi kullanın. Yönetilen kimlik için yalnızca hedef hizmetin gerektirdiği rolleri atayın.

API anahtarıyla kimlik doğrulaması

Üst bilgi veya sorgu parametresinde anahtar bekleyen bir API için bu değişkeni kullanın. OpenAPI aracı başına yalnızca bir API anahtarı güvenlik şeması kullanabilirsiniz. API birden çok güvenlik şeması gerektiriyorsa, birden çok OpenAPI aracı oluşturun.

OpenAPI belirtim güvenlik şemalarınızı güncelleştirin. securitySchemes bölümü ve apiKey türünde bir şeması vardır. Örneğin:
```
 "securitySchemes": {
     "apiKeyHeader": {
             "type": "apiKey",
             "name": "x-api-key",
             "in": "header"
         }
 }
```
Genellikle yalnızca bağlantıdaki name adına key karşılık gelen alanı güncelleştirmeniz gerekir. Güvenlik düzenleri birden çok düzen içeriyorsa, bunlardan yalnızca birini tutun.
OpenAPI belirtiminizi security bölümü içerecek şekilde güncelleyin.
```
"security": [
     {  
     "apiKeyHeader": []  
     }  
 ]
```
Bu makalenin ilerleyen bölümlerinde açıklandığı gibi, API anahtarı depolandığından ve bağlantı üzerinden geçirildiğinden, OpenAPI belirtiminde API anahtarı gerektiren tüm parametreleri kaldırın.
API anahtarınızı depolamak için bir bağlantı oluşturun.
Dökümhane portalına gidin ve projenizi açın.
Gizli bilgiyi depolayan bir bağlantı oluşturun veya seçin. Bkz. Projenize yeni bağlantı ekleme.

Not

API anahtarını daha sonraki bir tarihte yeniden oluşturursanız, bağlantıyı yeni anahtarla güncelleştirmeniz gerekir.

Aşağıdaki bilgileri girin

key: name güvenlik düzeninizin alanı. Bu örnekte, x-api-key

       "securitySchemes": {
          "apiKeyHeader": {
                    "type": "apiKey",
                    "name": "x-api-key",
                    "in": "header"
                }
        }

değer: YOUR_API_KEY

Bağlantı oluşturduktan sonra SDK veya REST API aracılığıyla kullanabilirsiniz. Kod örneklerini görmek için bu makalenin üst kısmındaki sekmeleri kullanın.

Bearer jetonu bağlantısı kurma

Authorization başlığında taşıyıcı belirteç bekleyen bir API için bu varyantı kullanın. API anahtarı kimlik doğrulamasıyla aynı project_connection kimlik doğrulama türünü kullanır, ancak OpenAPI güvenlik düzeni ve bağlantı değerleri farklıdır.

OpenAPI belirtiminiz şu şekilde görünür:

  BearerAuth:
    type: http
    scheme: bearer
    bearerFormat: JWT

Yapmanız gerekenler:

OpenAPI belirtiminizi securitySchemes üst bilgi adı olarak Authorization kullanmak için güncelleyin.

"securitySchemes": {
    "bearerAuth": {
        "type": "apiKey",
        "name": "Authorization",
        "in": "header"
    }
}

Şemaya başvuran bir security bölüm ekleyin:

"security": [
    {
        "bearerAuth": []
    }
]

Foundry projenizde Özel anahtarlar bağlantısı oluşturun:
1. Dökümhane portalına gidin ve projenizi açın.
2. Gizli bilgiyi depolayan bir bağlantı oluşturun veya seçin. Bkz. Projenize yeni bağlantı ekleme.
3. Aşağıdaki değerleri girin:
  - key: Authorization (sizin name içinde yer almakta olan securitySchemes alanıyla eşleşmelidir)
  - value: Bearer <token> (değerini gerçek belirtecinizle değiştirin <token> )
Önemli

Değer, belirtecin önüne bir boşluk eklenerek sözcüğü Bearer içermelidir. Örneğin: Bearer eyJhbGciOiJSUzI1NiIs.... Ön eki ve aşağıdaki alanı atlarsanız Bearer , API gerekli yetkilendirme şeması ön eki olmadan bir ham belirteç alır ve istek başarısız olur.

Bağlantıyı oluşturduktan sonra, API anahtar kimlik doğrulaması için yaptığınız gibi kodunuzda project_connection kimlik doğrulama türünü kullanın. Bağlantı kimliği aynı biçimi kullanır: /subscriptions/{{subscriptionID}}/resourceGroups/{{resourceGroupName}}/providers/Microsoft.CognitiveServices/accounts/{{foundryAccountName}}/projects/{{foundryProjectName}}/connections/{{foundryConnectionName}}.

Yönetilen kimliği kullanarak (Microsoft Entra ID) kimlik doğrulaması yapın.

Microsoft Entra ID çalışanlarınızın dış kaynaklara erişmek için kullanabileceği bulut tabanlı bir kimlik ve erişim yönetimi hizmetidir. Microsoft Entra ID kullanarak API anahtarlarını kullanmanıza gerek kalmadan API'lerinize ek güvenlik ekleyebilirsiniz. Yönetilen kimlik doğrulamasını ayarladığınızda, ajan Foundry aracını kullanarak kimlik doğrulamasını gerçekleştirir.

Önemli

Yönetilen kimlik kimlik doğrulaması yalnızca hedef hizmet Microsoft Entra ID belirteçleri kabul ettiğinde çalışır. Hedef API Microsoft Entra ID desteklemeyen bir özel kimlik doğrulama düzeni kullanıyorsa bunun yerine API anahtarı veya Bearer belirteci kimlik doğrulamasını kullanın.

hedef kitle URI'sini anlama

audience (bazen kaynak tanımlayıcısı veya Uygulama Kimliği URI), belirtecin hangi hizmete veya API'ye erişmeyi amaçladığını, Microsoft Entra ID'ye belirtir. Hedef kitle değeri hedef hizmetin beklediği değerle eşleşmelidir veya kimlik doğrulaması 401 hatasıyla başarısız olur.

Not

İzleyici kitlesi, Foundry proje uç noktanız değildir. OpenAPI aracınızın çağırdığını hedef hizmetin kaynak tanımlayıcısıdır.

Aşağıdaki tabloda, yaygın Azure hizmetleri için hedef kitle URI'leri listelenmektedir:

Hedef hizmet	hedef kitle URI'si
Azure Depolama	`https://storage.azure.com`
Azure Key Vault	`https://vault.azure.net`
Azure Yapay Zeka Arama	`https://search.azure.com`
Azure Logic Apps	`https://logic.azure.com`
Azure API Management (yönetim düzlemi)	`https://management.azure.com`
Microsoft Entra uygulama kaydıyla korunan API (OAuth ile APIM dahil)	Uygulama kaydınızdaki Uygulama Kimliği URI'si (örneğin, `api://<client-id>`)

Ipucu

OAuth 2.0 doğrulama ilkesiyle özel bir API'yi korumak için Azure API Management kullanırsanız hedef kitle, değil API'yi koruyan uygulama kaydından https://management.azure.com olur. Yönetim düzlemi hedef kitlesi yalnızca APIM kaynağının kendisinde Azure Resource Manager işlemler için geçerlidir.

Ajanların Microsoft Entra Kimliği ile nasıl kimlik doğruladıkları hakkında daha fazla bilgi için bkz. Agent identity and authentication.

Hedef kitlenizi bulma ve doğrulama

Doğru hedef kitle değerini belirlemek ve doğrulamak için aşağıdaki adımları kullanın:

Azure hizmetleri için: hizmetin Microsoft Entra ID kaynak tanımlayıcısı belgelerine bakın. çoğu Azure hizmet, kimlik doğrulama belgelerinde hedef kitle URI'sini listeler.
Microsoft Entra uygulama kaydıyla korunan API'ler için: Azure portalında, Microsoft Entra ID>Uygulama Kayıtları> seçin ve uygulamanızı seçin, ardından >Bir API'yi Görüntüle. Sayfanın üst kısmındaki Uygulama Kimliği URI'si hedef kitlenizin değeridir.
Belirtecin hedef kitlesini doğrulamak için: Erişim belirtecini https://jwt.ms çözümleyin ve aud talebini denetleyin. Değer aud , hedef hizmetinizin beklediği hedef kitleyle eşleşmelidir.

Yönetilen kimlik doğrulamayı ayarlama

Yönetilen Kimlik kullanarak kimlik doğrulamasını ayarlamak için:

Foundry kaynağınızda sistem tarafından atanmış yönetilen kimliğin etkinleştirildiğinden emin olun.

OpenAPI belirtimi aracılığıyla bağlanmak istediğiniz hizmet için bir kaynak oluşturun.
Kaynağa uygun erişim atayın.
1. Kaynağınız için Access Control seçin.
2. Ekle'yi seçin ve ardından ekranın üst kısmında rol ataması ekleyin.
OpenAPI belirtiminizde işlemleri veren en az ayrıcalıklı veri düzlemini veya uygulama rolünü seçin. Azure Resource Manager Okuyucu erişimi tek başına veri düzlemi erişimi vermez. Ardından İleri'yi seçin.
Yönetilen kimlik'i ve ardından üyeleri seç'i seçin.
Yönetilen kimlik açılır menüsünde Foundry hesabı arayın ve ardından aracınızın Foundry hesabını seçin.
Son'u seçin.
Kurulumu tamamladığınızda, Aracı Kullanarak Döküm Portalı, SDK veya REST API aracılığıyla devam edebilirsiniz. Kod örneklerini görmek için bu makalenin üst kısmındaki sekmeleri kullanın.

Yaygın hataları giderme

Semptom	Olası neden	Çözünürlük
API anahtarı isteklere dahil değildir.	OpenAPI belirtimi dosyası `securitySchemes` veya `security` bölümler eksik.	OpenAPI belirtiminizin hem `components.securitySchemes` hem de üst düzey `security` bölümü içerdiğini doğrulayın. Düzenin `name` proje bağlantınızdaki anahtar adıyla eşleştiğinden emin olun.
Aracı OpenAPI aracını çağırmaz.	Araç seçimi ayarlanmadı veya `operationId` açıklayıcı değil.	Araç çağrılmasını zorlamak için `tool_choice="required"` kullanın. Modelin doğru işlemi seçebilmesi için değerlerin açıklayıcı olduğundan emin olun `operationId` .
Yönetilen kimlik için kimlik doğrulaması başarısız oluyor.	Yönetilen kimlik etkinleştirilmedi veya rol ataması eksik.	Foundry kaynağınızda sistem tarafından atanan yönetilen kimliği etkinleştirin. OpenAPI belirtimlerinizdeki işlemler için hedef hizmetin en az ayrıcalıklı veri düzlemi veya uygulama rolünü atayın.
Yönetilen kimlik, rol atanmış olsa bile 401 döndürür.	Hedef kitle URI'si hedef hizmetin beklediğiyle eşleşmiyor.	hedef kitle URI'sinin hedef hizmetin kaynak tanımlayıcısı ile eşleştiğinden emin olun. Azure hizmetleri için hizmet belgelerine bakın. Microsoft Entra korumalı API'ler için uygulama kaydınızdaki Uygulama Kimliği URI'sini kullanın. adresinde belirtecin https://jwt.ms kodunu çözerek talep eşleşmelerini `aud` onaylayın. Bkz. İzleyici URI'sini anlama.
Yönetilen kimlik belirteci hedef API tarafından reddedildi.	Hedef hizmet Microsoft Entra ID jetonlarını kabul etmez.	Hedef hizmetin Microsoft Entra ID kimlik doğrulamasını desteklediğini onaylayın. Aksi takdirde API anahtarı veya Bearer jetonu kimlik doğrulama için kullanın.
İstek 400 Hatalı İstek ile başarısız oluyor.	OpenAPI belirtimi gerçek API ile eşleşmiyor.	OpenAPI belirtiminizi gerçek API'ye göre doğrulayın. Parametre adlarını, türlerini ve gerekli alanları denetleyin.
İstek 401 Yetkisiz ile başarısız oluyor.	API anahtarı veya belirteci geçersiz veya süresi dolmuş.	API anahtarını/belirtecini yeniden oluşturun ve proje bağlantınızı güncelleştirin. Bağlantı kimliğinin doğru olduğunu doğrulayın.
Araç beklenmeyen yanıt biçimi döndürür.	Yanıt şeması OpenAPI belirtiminde tanımlanmadı.	Daha iyi model anlamak için OpenAPI belirtiminize yanıt şemaları ekleyin.
`operationId` doğrulama hatası.	içinde `operationId`geçersiz karakterler.	Yalnızca harfleri, `-` ve `_` etiketlerini `operationId` değerlerinde kullanın. Sayıları ve özel karakterleri kaldırın.
Bağlantı bulunamadı hatası.	Bağlantı adı veya kimlik uyuşmazlığı.	Bağlantı adı Foundry projenizde eşleşiyor mu diye `OPENAPI_PROJECT_CONNECTION_NAME` doğrulayın.
Taşıyıcı token doğru gönderilmedi.	Bağlantı değerinde `Bearer` ön eki ve onu izleyen boşluk eksik.	Bağlantı değerini `Bearer <token>` olarak ayarlayın (belirteci kullanmadan önce sözcüğü `Bearer` ve boşluk bırakın). OpenAPI belirtiminin `securitySchemes` kullandığını `"name": "Authorization"`doğrulayın.

Kimlik doğrulama yöntemi seçme

Aşağıdaki tablo, OpenAPI aracınız için doğru kimlik doğrulama yöntemini seçmenize yardımcı olur:

Kimlik doğrulama yöntemi	En iyisi için	Kurulum karmaşıklığı
Anonim	Kimlik doğrulaması olmayan genel API'ler	Düşük
API anahtarı	Anahtar tabanlı erişime sahip Microsoft olmayan API'ler	Orta
Yönetilen kimlik	Azure hizmetleri ve Microsoft Entra ID korumalı API'ler. Hedef hizmetin, Microsoft Entra ID belirteçlerini kabul etmesi ve Azure RBAC veya Microsoft Entra tabanlı erişim denetimini desteklemesi gerekir.	Orta-Yüksek

Geri Bildirim

Bu sayfayı yararlı buldunuz mu?

Last updated on 2026-08-21

Aracıları OpenAPI araçlarına bağlama

Önkoşullar

Ortam değişkenleri

Kullanım desteği

Anonim ilk başarı akışını çalıştırın

Sınırlamaları anlama

Araç kutusuna OpenAPI araçları ekleme

Azure Geliştirici CLI ile OpenAPI araç kutusu oluşturma

Kod örneklerini çalıştırmadan önce

OpenAPI aracısıyla aracı kullanma örneği

Yönlendirme ajanları

Barındırılan aracılar

Beklenen çıkış

OpenAPI aracısıyla aracı kullanma örneği

Yönlendirme ajanları

Bu kod ne yapar?

Gerekli girişler

Beklenen çıkış

Yaygın hatalar

Barındırılan aracılar

Beklenen çıkış

OpenAPI aracını kullanan Web hizmetinde aracı kullanımı örneği, kimlik doğrulaması gerektirir.

Bu kod ne yapar?

Gerekli girişler

Beklenen çıkış

Yaygın hatalar

OpenAPI aracı özellikleriyle Java aracısı oluşturma

Anonim kimlik doğrulaması

API anahtarı kimlik doğrulaması (proje bağlantısı)

Yönetilen kimlik doğrulaması

Bu kod ne yapar?

Gerekli girişler

Beklenen çıkış

Yaygın hatalar

OpenAPI aracı özelliklerine sahip bir ajan oluşturun

Bu kod ne yapar?

Gerekli girişler

Beklenen çıkış

Yaygın hatalar

Proje bağlantısıyla kimliği doğrulanmış OpenAPI araçlarını kullanan bir aracı oluşturma

Bu kod ne yapar?

Gerekli girişler

Beklenen çıkış

Yaygın hatalar

Güvenlik ve veriyle ilgili dikkat edilmesi gerekenler

API anahtarıyla kimlik doğrulaması

Bearer jetonu bağlantısı kurma

Yönetilen kimliği kullanarak (Microsoft Entra ID) kimlik doğrulaması yapın.

hedef kitle URI'sini anlama

Hedef kitlenizi bulma ve doğrulama

Yönetilen kimlik doğrulamayı ayarlama

Yaygın hataları giderme

Kimlik doğrulama yöntemi seçme

İlgili içerik

Geri Bildirim

Ek kaynaklar