Menyambungkan agen ke alat OpenAPI

Hubungkan agen Microsoft Foundry Anda ke API eksternal menggunakan spesifikasi OpenAPI 3.0 dan 3.1. Model Foundry yang mendukung agen Anda dapat memanggil layanan eksternal, mengambil data real time, dan memperluas kemampuannya di luar fungsi bawaan.

Spesifikasi OpenAPI menentukan cara standar untuk menjelaskan API HTTP sehingga Anda dapat mengintegrasikan layanan yang ada dengan agen Anda. Microsoft Foundry mendukung tiga metode autentikasi: anonymous, API key, dan managed identity. Untuk bantuan memilih metode autentikasi, lihat Memilih metode autentikasi.

Dukungan penggunaan

Tabel berikut ini memperlihatkan SDK dan dukungan penyiapan.

dukungan Microsoft Foundry	Python SDK	C# SDK	JavaScript SDK	Java SDK	REST API	Penyiapan agen dasar	Penyiapan agen standar
✔️	✔️	✔️	✔️	✔️	✔️	✔️	✔️

Catatan

Untuk Java, gunakan paket com.azure:azure-ai-agents untuk alat agen OpenAPI. Paket com.azure:azure-ai-projects saat ini tidak mengekspos jenis alat agen OpenAPI.

Prasyarat

Sebelum memulai, pastikan Anda memiliki:

• Langganan Azure dengan izin yang tepat.
• Azure peran RBAC: Kontributor atau Pemilik pada proyek Foundry.
• Proyek Foundry yang dibuat dengan endpoin yang sudah dikonfigurasi.
• Model AI yang disebarkan dalam proyek Anda.
• Lingkungan agen dasar atau standar.
• SDK terinstal untuk bahasa pilihan Anda:
  • Python: azure-ai-projects
  • C#: Azure.AI.Extensions.OpenAI
  • TypeScript/JavaScript: @azure/ai-projects
  • Java: com.azure:azure-ai-agents

Variabel lingkungan

Variabel	Deskripsi
FOUNDRY_PROJECT_ENDPOINT	URL titik akhir proyek Foundry Anda (bukan titik akhir layanan OpenAPI eksternal).
FOUNDRY_MODEL_DEPLOYMENT_NAME	Nama model yang Anda sebarkan.
OPENAPI_PROJECT_CONNECTION_NAME	(Untuk autentikasi kunci API) Nama koneksi proyek Anda untuk layanan OpenAPI.

• File spesifikasi OpenAPI 3.0 atau 3.1 yang memenuhi persyaratan berikut:
  • Setiap fungsi harus memiliki operationId (diperlukan untuk alat OpenAPI).
  • operationId hanya boleh berisi huruf, -, dan _.
  • Gunakan nama deskriptif untuk membantu model memutuskan fungsi mana yang akan digunakan secara efisien.
  • Jenis konten isi permintaan yang didukung: application/json, application/json-patch+json
• Untuk autentikasi identitas terkelola: Peran pembaca atau lebih tinggi pada sumber daya layanan target.
• Untuk autentikasi kunci/token API: koneksi proyek yang dikonfigurasi dengan kunci API atau token Anda. Lihat Menambahkan koneksi baru ke proyek Anda.

Catatan

Nilai FOUNDRY_PROJECT_ENDPOINT mengacu pada titik akhir proyek Microsoft Foundry Anda, bukan titik akhir layanan OpenAPI eksternal. Anda dapat menemukan titik akhir ini di portal Microsoft Foundry di bawah halaman Gambaran Umum proyek Anda. Titik akhir ini diperlukan untuk mengautentikasi layanan agen dan terpisah dari titik akhir OpenAPI apa pun yang ditentukan dalam file spesifikasi Anda.

Memahami batasan

• Spesifikasi OpenAPI Anda harus disertakan operationId untuk setiap operasi, dan operationId hanya dapat menyertakan huruf, -, dan _.
• Jenis konten isi permintaan yang didukung: application/json, application/json-patch+json.
• Untuk autentikasi kunci API, gunakan satu skema keamanan kunci API per alat OpenAPI. Jika Anda memerlukan beberapa skema keamanan, buat beberapa alat OpenAPI.

Contoh kode

Catatan

• Anda memerlukan paket SDK terbaru. SDK .NET saat ini dalam pratinjau. Lihat quickstart untuk detailnya.
• Jika Anda menggunakan kunci API untuk autentikasi, ID koneksi Anda harus dalam format /subscriptions/{{subscriptionID}}/resourceGroups/{{resourceGroupName}}/providers/Microsoft.CognitiveServices/accounts/{{foundryAccountName}}/projects/{{foundryProjectName}}/connections/{{foundryConnectionName}}.

Penting

Agar autentikasi kunci API berfungsi, file spesifikasi OpenAPI Anda harus mencakup:

1. securitySchemes Bagian dengan konfigurasi kunci API Anda, seperti nama header dan nama parameter.
2. security Bagian yang mereferensikan skema keamanan.
3. Koneksi proyek yang dikonfigurasi dengan nama dan nilai kunci yang cocok.

Tanpa konfigurasi ini, kunci API tidak disertakan dalam permintaan. Untuk instruksi penyiapan terperinci, lihat bagian Mengautentikasi dengan kunci API .

Anda juga dapat menggunakan autentikasi berbasis token (misalnya, token Pembawa) dengan menyimpan token dalam koneksi proyek. Untuk autentikasi token Pembawa, buat koneksi Kunci kustom dengan kunci diatur ke Authorization dan nilai diatur ke Bearer <token> (ganti <token> dengan token Anda yang sebenarnya). Kata Bearer diikuti dengan spasi harus disertakan dalam nilai . Untuk detailnya, lihat Menyiapkan koneksi token Pembawa.

Contoh lengkap

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"
OPENAPI_CONNECTION_NAME = "my-openapi-connection"

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

# If you want to use key-based authentication
# IMPORTANT: Your OpenAPI spec must include securitySchemes and security sections
# Example spec structure for API key auth:
# {
#   "components": {
#     "securitySchemes": {
#       "apiKeyHeader": {
#         "type": "apiKey",
#         "name": "x-api-key",  # This must match the key name in your project connection
#         "in": "header"
#       }
#     }
#   },
#   "security": [{"apiKeyHeader": []}]
# }
#
# For Bearer token authentication, use this securitySchemes structure instead:
# {
#   "components": {
#     "securitySchemes": {
#       "bearerAuth": {
#         "type": "apiKey",
#         "name": "Authorization",
#         "in": "header"
#       }
#     }
#   },
#   "security": [{"bearerAuth": []}]
# }
# Then set connection key = "Authorization" and value = "Bearer <token>"
# The word "Bearer" followed by a space MUST be included in the value.

openapi_connection = project.connections.get(OPENAPI_CONNECTION_NAME)
connection_id = openapi_connection.id

openapi_key_auth_tool = {
    "type": "openapi",
    "openapi": {
        "name": "get_weather",
        "spec": openapi_weather,  # Must include securitySchemes and security sections
        "auth": {
            "type": "project_connection",
            "security_scheme": {
                "project_connection_id": connection_id
            }
        },
    }
}

# If you want to use Managed Identity authentication
openapi_mi_auth_tool = {
    "type": "openapi",
    "openapi": {
        "name": "get_weather",
        "description": "Retrieve weather information for a location.",
        "spec": openapi_weather,
        "auth": {
            "type": "managed_identity",
            "security_scheme": {
                "audience": "https://storage.azure.com"  # Resource identifier of the target service
            }
        },
    }
}

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)

Apa yang dilakukan kode ini

Contoh ini membuat agen dengan alat OpenAPI yang memanggil API cuaca wttr.in menggunakan autentikasi anonim. Saat Anda menjalankan kode:

1. Ini memuat spesifikasi OpenAPI cuaca dari file JSON lokal.
2. Membuat agen dengan alat cuaca yang dikonfigurasi untuk akses anonim.
3. Mengirim kueri yang menanyakan tentang cuaca Seattle.
4. Agen menggunakan alat OpenAPI untuk memanggil API cuaca dan mengembalikan hasil yang diformat.
5. Bersihkan dengan menghapus versi agen.

Input yang diperlukan

• Nilai string di bagian atas skrip: PROJECT_ENDPOINT, OPENAPI_CONNECTION_NAME
• File lokal: weather_openapi.json (Spesifikasi OpenAPI)

Output yang diharapkan

Agent created (id: asst_abc123, name: MyAgent23, version: 1)
Response created: The weather in Seattle is currently cloudy with a temperature of 52°F (11°C)...

Cleaning up...
Agent deleted

Kesalahan umum

• FileNotFoundError: File spesifikasi OpenAPI tidak ditemukan pada jalur yang ditentukan
• AuthenticationError: Kredensial yang tidak valid atau izin yang tidak mencukupi, atau hilang securitySchemes dalam spesifikasi OpenAPI untuk autentikasi kunci API
• Format tidak valid operationId dalam spesifikasi OpenAPI menyebabkan kegagalan pendaftaran alat
• Kunci API tidak disuntikkan: Verifikasi spesifikasi OpenAPI Anda menyertakan bagian securitySchemes dan security , dan bahwa nama kunci cocok dengan koneksi proyek Anda

Sampel penggunaan Agen dengan alat OpenAPI

Contoh ini menunjukkan cara menggunakan layanan yang dijelaskan oleh spesifikasi OpenAPI dengan menggunakan agen. Ini menggunakan layanan wttr.in untuk mendapatkan data cuaca dan file spesifikasi weather_openapi.json. Contoh ini menggunakan metode sinkron dari pustaka klien proyek AI Azure. Misalnya yang menggunakan metode asinkron, lihat sample di Azure SDK untuk repositori .NET pada GitHub.

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

Apa yang dilakukan kode ini

Contoh C# ini membuat agen dengan alat OpenAPI yang mengambil informasi cuaca dari wttr.in dengan menggunakan autentikasi anonim. Saat Anda menjalankan kode:

1. Ini membaca spesifikasi OpenAPI cuaca dari file JSON lokal.
2. Membuat agen dengan alat cuaca yang dikonfigurasi.
3. Mengirim permintaan yang menanyakan tentang cuaca Seattle menggunakan alat OpenAPI.
4. Agen memanggil API cuaca dan mengembalikan hasilnya.
5. Membersihkan dengan menghapus agen tersebut.

Input yang diperlukan

• Nilai string sebaris: projectEndpoint (titik akhir proyek Foundry Anda)
• File lokal: Assets/weather_openapi.json (Spesifikasi OpenAPI)

Output yang diharapkan

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

Kesalahan umum

• FileNotFoundException: File spesifikasi OpenAPI tidak ditemukan di folder Aset
• UnauthorizedAccessException: Kredensial tidak valid atau izin RBAC yang tidak mencukupi
• Kunci API tidak disuntikkan: Verifikasi bahwa spesifikasi OpenAPI Anda mencakup securitySchemes (di components) dan security bagian yang memiliki nama skema yang sesuai.

Sampel penggunaan Agen dengan alat OpenAPI di layanan Web, yang memerlukan autentikasi

Dalam contoh ini, Anda menggunakan layanan dengan spesifikasi OpenAPI dengan menggunakan agen dalam skenario yang memerlukan autentikasi. Anda menggunakan spesifikasi TripAdvisor.

Layanan TripAdvisor memerlukan autentikasi berbasis kunci. Untuk membuat koneksi di portal Azure, buka Microsoft Foundry dan, di panel kiri pilih Pusat pengelolaan lalu pilih sumber daya Koneksi. Terakhir, buat koneksi baru jenis Kunci kustom . Beri nama tripadvisor dan tambahkan pasangan nilai kunci. Tambahkan kunci bernama key dan masukkan nilai dengan kunci TripAdvisor Anda.

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 Agent with `OpenAPIAgentTool` and 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.";
        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 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);
    }
}

Apa yang dilakukan kode ini

Contoh C# ini menunjukkan menggunakan alat OpenAPI dengan autentikasi kunci API melalui koneksi proyek. Saat Anda menjalankan kode:

1. Ini memuat spesifikasi TripAdvisor OpenAPI dari file lokal.
2. Mengakses koneksi proyek yang berisi tripadvisor kunci API Anda.
3. Membuat agen dengan alat TripAdvisor yang telah dikonfigurasi untuk menggunakan koneksi sebagai autentikasi.
4. Mengirimkan permintaan rekomendasi hotel di Paris.
5. Agen memanggil API TripAdvisor menggunakan kunci API tersimpan dan mengembalikan hasil.
6. Membersihkan dengan menghapus agen tersebut.

Input yang diperlukan

• Nilai string sebaris: projectEndpoint (titik akhir proyek Foundry Anda)
• File lokal: Assets/tripadvisor_openapi.json
• koneksi proyek: tripadvisor dikonfigurasi dengan kunci API yang valid

Output yang diharapkan

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

Kesalahan umum

• ConnectionNotFoundException: Tidak ada koneksi proyek bernama tripadvisor ditemukan.
• AuthenticationException: Kunci API tidak valid dalam koneksi proyek, atau konfigurasi yang hilang/salah securitySchemes dalam spesifikasi OpenAPI.
• Alat tidak digunakan: Memastikan ToolChoice = ResponseToolChoice.CreateRequiredChoice() memaksa penggunaan alat.
• Kunci API tidak diteruskan ke API: Pastikan spesifikasi OpenAPI memiliki beberapa bagian securitySchemes dan security yang dikonfigurasi dengan tepat.

Membuat agen Java dengan kemampuan alat OpenAPI

Contoh Java ini membuat agen dengan alat OpenAPI dengan menggunakan com.azure:azure-ai-agents dan file spesifikasi OpenAPI lokal. Sampel menggunakan autentikasi anonim dan memanggil titik akhir API publik.

import com.azure.ai.agents.AgentsClient;
import com.azure.ai.agents.AgentsClientBuilder;
import com.azure.ai.agents.ConversationsClient;
import com.azure.ai.agents.ResponsesClient;
import com.azure.ai.agents.models.*;
import com.azure.core.util.BinaryData;
import com.azure.identity.DefaultAzureCredentialBuilder;
import com.azure.json.JsonProviders;
import com.azure.json.JsonReader;
import com.openai.models.conversations.Conversation;
import com.openai.models.conversations.items.ItemCreateParams;
import com.openai.models.responses.EasyInputMessage;
import com.openai.models.responses.Response;
import com.openai.models.responses.ResponseCreateParams;

import java.nio.file.Paths;
import java.util.Arrays;
import java.util.Map;

public class OpenApiAgentJavaSample {
    public static void main(String[] args) throws Exception {
        // Format: "https://resource_name.ai.azure.com/api/projects/project_name"
        String projectEndpoint = "your_project_endpoint";

        AgentsClientBuilder builder = new AgentsClientBuilder()
            .endpoint(projectEndpoint)
            .credential(new DefaultAzureCredentialBuilder().build());

        AgentsClient agentsClient = builder.buildAgentsClient();
        ResponsesClient responsesClient = builder.buildResponsesClient();
        ConversationsClient conversationsClient = builder.buildConversationsClient();

        Map<String, BinaryData> spec = OpenApiFunctionDefinition.readSpecFromFile(
            Paths.get("openapi_spec.json"));

        OpenApiFunctionDefinition toolDefinition = new OpenApiFunctionDefinition(
            "httpbin_get",
            spec,
            new OpenApiAnonymousAuthDetails())
            .setDescription("Get request metadata from an OpenAPI endpoint.");

        PromptAgentDefinition agentDefinition = new PromptAgentDefinition("gpt-4.1-mini")
            .setInstructions("Use the OpenAPI tool for HTTP request metadata.")
            .setTools(Arrays.asList(new OpenApiTool(toolDefinition)));

        AgentVersionDetails agentVersion = agentsClient.createAgentVersion("openapiValidationAgentJava", agentDefinition);
        System.out.println("Agent: " + agentVersion.getName() + ", version: " + agentVersion.getVersion());

        Conversation conversation = conversationsClient.getConversationService().create();
        conversationsClient.getConversationService().items().create(
            ItemCreateParams.builder()
                .conversationId(conversation.id())
                .addItem(EasyInputMessage.builder()
                    .role(EasyInputMessage.Role.USER)
                    .content("Use the OpenAPI tool and summarize the returned URL and origin in one sentence.")
                    .build())
                .build());

        try {
            AgentReference agentReference = new AgentReference(agentVersion.getName()).setVersion(agentVersion.getVersion());
            ResponseCreateParams.Builder options = ResponseCreateParams.builder().maxOutputTokens(300L);
            Response response = responsesClient.createAzureResponse(
                new AzureCreateResponseOptions().setAgentReference(agentReference),
                options.conversation(conversation.id()));

            String text = response.output().stream()
                .filter(item -> item.isMessage())
                .map(item -> item.asMessage().content()
                    .get(item.asMessage().content().size() - 1)
                    .asOutputText()
                    .text())
                .reduce((first, second) -> second)
                .orElse("<no message output>");

            System.out.println("Status: " + response.status().map(Object::toString).orElse("unknown"));
            System.out.println("Response: " + text);
        } finally {
            agentsClient.deleteAgentVersion(agentVersion.getName(), agentVersion.getVersion());
            System.out.println("Agent deleted");
        }
    }
}

Apa yang dilakukan kode ini

Contoh Java ini membuat agen dengan alat OpenAPI dan menjalankan respons dalam lingkup percakapan.

1. Memuat spesifikasi OpenAPI dari openapi_spec.json.
2. Membuat versi agen dengan OpenApiTool.
3. Membuat percakapan dan menambahkan pesan pengguna.
4. Membuat respons dengan menyampaikan AgentReference dan ID percakapan.
5. Bersihkan dengan menghapus versi agen.

Input yang diperlukan

• Nilai string sebaris: projectEndpoint (titik akhir proyek Foundry Anda)
• File lokal: openapi_spec.json (Spesifikasi OpenAPI 3.0 atau 3.1)

Output yang diharapkan

Agent: openapiValidationAgentJava, version: 1
Status: completed
Response: The API response reports URL ... and origin ...
Agent deleted

Kesalahan umum

• Invalid OpenAPI specification: Uraikan OpenAPI JSON ke dalam objek sebelum meneruskannya ke OpenApiFunctionDefinition.
• Invalid conversation id: Buat percakapan dan teruskan conversation.id() ke createAzureResponse melalui ResponseCreateParams.builder().conversation().
• AuthenticationFailedException: Verifikasi DefaultAzureCredential dapat memperoleh token untuk akun Anda yang sudah masuk.

Contoh berikut menunjukkan cara memanggil alat OpenAPI dengan menggunakan REST API.

Dapatkan token akses:

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

Autentikasi anonim

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": "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" }
                  }
                }
              }
            }
          }
        }
      }
    ]
  }'

Autentikasi kunci API (koneksi proyek)

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": [] }
            ]
          }
        }
      }
    ]
  }'

Autentikasi identitas terkelola

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" }
                  }
                }
              }
            }
          }
        }
      }
    ]
  }'

Apa yang dilakukan kode ini

Contoh REST API ini menunjukkan cara memanggil alat OpenAPI dengan metode autentikasi yang berbeda. Permintaan:

1. Mengirim kueri ke agen yang menanyakan tentang cuaca Seattle.
2. Termasuk definisi alat OpenAPI sebaris dengan spesifikasi API cuaca.
3. Menampilkan tiga opsi autentikasi (anonim, kunci API melalui koneksi proyek, identitas terkelola) sebagai alternatif yang dikomentari.
4. Agen menggunakan alat untuk memanggil API cuaca dan mengembalikan hasil yang diformat.

Input yang diperlukan

• Variabel lingkungan: FOUNDRY_PROJECT_ENDPOINT, AGENT_TOKEN, FOUNDRY_MODEL_DEPLOYMENT_NAME.
• Untuk autentikasi kunci API: WEATHER_APP_PROJECT_CONNECTION_ID.
• Untuk autentikasi identitas terkelola: MANAGED_IDENTITY_AUDIENCE.
• Spesifikasi OpenAPI internal dalam isi permintaan.

Output yang diharapkan

{
  "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)..."
        }
      ]
    }
  ]
}

Kesalahan umum

• 401 Unauthorized: Kunci tidak valid atau hilang AGENT_TOKEN, atau API tidak disuntikkan karena securitySchemes dan security hilang dalam spesifikasi OpenAPI Anda
• 404 Not Found: Nama titik akhir atau penyebaran model yang salah
• 400 Bad Request: Spesifikasi OpenAPI salah format atau konfigurasi autentikasi yang tidak valid
• Kunci API tidak dikirim dengan permintaan: Verifikasi components.securitySchemes bagian dalam spesifikasi OpenAPI Anda dikonfigurasi dengan benar (tidak kosong) dan cocok dengan nama kunci koneksi proyek Anda

Membuat agen dengan kemampuan alat OpenAPI

Contoh kode TypeScript berikut menunjukkan cara membuat agen AI dengan kemampuan alat OpenAPI dengan menggunakan OpenApiTool dan klien Proyek AI Azure sinkron. Agen dapat memanggil API eksternal yang ditentukan oleh spesifikasi OpenAPI. Untuk versi JavaScript dari contoh ini, lihat sample di Azure SDK untuk repositori JavaScript di GitHub.

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();

  // Create an agent with the OpenAPI weather 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: [createWeatherTool(weatherSpec)],
  });

  // 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: { 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);
});

Apa yang dilakukan kode ini

Contoh TypeScript ini membuat agen dengan alat OpenAPI untuk data cuaca dengan menggunakan autentikasi anonim. Saat Anda menjalankan kode:

1. Ini memuat spesifikasi OpenAPI cuaca dari file JSON lokal.
2. Membuat agen dengan alat cuaca yang dikonfigurasi.
3. Mengirim permintaan streaming yang menanyakan tentang cuaca di Seattle dan perencanaan pakaian.
4. Memproses respons streaming dan menampilkan delta saat tiba.
5. Ini mengharuskan penggunaan alat dengan menggunakan tool_choice: "required" untuk memastikan API dipanggil.
6. Membersihkan dengan menghapus agen tersebut.

Input yang diperlukan

• Nilai string sebaris: PROJECT_ENDPOINT (titik akhir proyek Foundry Anda)
• File lokal: ../assets/weather_openapi.json (Spesifikasi OpenAPI)

Output yang diharapkan

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!

Kesalahan umum

• Error: OpenAPI specification not found: Jalur file salah atau file hilang
• AuthenticationError: Kredensial Azure tidak valid
• Kunci API tidak berfungsi: Jika beralih dari autentikasi kunci anonim ke API, pastikan spesifikasi OpenAPI Anda telah securitySchemes dan security dikonfigurasi dengan benar

Membuat agen yang menggunakan alat OpenAPI yang diautentikasi dengan koneksi proyek

Contoh kode TypeScript berikut menunjukkan cara membuat agen AI yang menggunakan alat OpenAPI yang diautentikasi melalui koneksi proyek. Agen memuat spesifikasi TripAdvisor OpenAPI dari aset lokal dan dapat memanggil API melalui koneksi proyek yang dikonfigurasi. Untuk versi JavaScript dari contoh ini, lihat sample di Azure SDK untuk repositori JavaScript di GitHub.

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: { 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);
});

Apa yang dilakukan kode ini

Contoh TypeScript ini menunjukkan penggunaan alat OpenAPI dengan autentikasi kunci API melalui koneksi proyek. Saat Anda menjalankan kode:

1. Ini memuat spesifikasi TripAdvisor OpenAPI dari file lokal.
2. Ini mengonfigurasi autentikasi dengan menggunakan TRIPADVISOR_CONNECTION_ID konstanta.
3. Ini membuat agen dengan alat TripAdvisor yang menggunakan koneksi proyek untuk autentikasi kunci API.
4. Ini mengirimkan permintaan data streaming untuk detail lokasi di platform TripAdvisor.
5. Ini mengharuskan penggunaan alat dengan menggunakan tool_choice: "required" untuk memastikan API dipanggil.
6. Ini memproses dan menampilkan respons streaming.
7. Pembersihan dilakukan dengan menghapus agen.

Input yang diperlukan

• Nilai string sebaris: PROJECT_ENDPOINT, TRIPADVISOR_CONNECTION_ID
• File lokal: ../assets/tripadvisor_openapi.json
• Koneksi proyek dikonfigurasi dengan kunci API TripAdvisor

Output yang diharapkan

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!

Kesalahan umum

• Error: OpenAPI specification not found: Periksa jalur file.
• Koneksi tidak ditemukan: Verifikasi TRIPADVISOR_CONNECTION_ID benar dan koneksi ada.
• AuthenticationException: Kunci API tidak valid dalam koneksi proyek.
• Kunci API tidak dimasukkan dalam permintaan: Spesifikasi OpenAPI Anda harus menyertakan bagian yang sesuai dalam securitySchemes (di bawah components) dan security. Nama kunci di securitySchemes harus cocok dengan kunci dalam koneksi proyek Anda.
• Content type is not supported: Saat ini, hanya dua jenis konten isi permintaan ini yang didukung: application/json dan application/json-patch+json. Jenis konten respons tidak dibatasi.

Pertimbangan keamanan dan data

Saat Anda menghubungkan agen ke alat OpenAPI, agen dapat mengirim parameter permintaan yang berasal dari input pengguna ke API target.

• Gunakan koneksi proyek untuk rahasia (kunci API dan token). Hindari meletakkan rahasia dalam file spesifikasi OpenAPI atau kode sumber.
• Tinjau data apa yang diterima API dan apa yang dikembalikannya sebelum Anda menggunakan alat dalam produksi.
• Gunakan akses hak istimewa terkecil. Untuk identitas terkelola, tetapkan hanya peran yang diperlukan layanan target.

Mengautentikasi dengan kunci API

Dengan menggunakan autentikasi kunci API, Anda dapat mengautentikasi spesifikasi OpenAPI dengan menggunakan berbagai metode seperti kunci API atau token Pembawa. Anda hanya dapat menggunakan satu skema keamanan kunci API per spesifikasi OpenAPI. Jika Anda memerlukan beberapa skema keamanan, buat beberapa alat spesifikasi OpenAPI.

1. Perbarui skema keamanan spesifikasi OpenAPI Anda. Ini memiliki securitySchemes bagian dan satu skema jenis apiKey. Misalnya:

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

   Anda biasanya hanya perlu memperbarui field `name`, yang sesuai dengan nama `key` dalam koneksi. Jika skema keamanan menyertakan beberapa skema, simpan hanya salah satunya.

2. Perbarui spesifikasi OpenAPI Anda untuk menyertakan bagian security:

   "security": [
        {  
        "apiKeyHeader": []  
        }  
    ]
   

3. Hapus parameter apa pun dalam spesifikasi OpenAPI yang memerlukan kunci API, karena kunci API disimpan dan diteruskan melalui koneksi, seperti yang dijelaskan nanti di artikel ini.

4. Buat koneksi untuk menyimpan kunci API Anda.

5. Buka portal Foundry dan buka proyek Anda.

6. Buat atau pilih koneksi yang menyimpan rahasia. Lihat Menambahkan koneksi baru ke proyek Anda.

   Catatan

   Jika Anda meregenerasi kunci API di kemudian hari, Anda perlu memperbarui koneksi dengan kunci baru.

7. Masukkan informasi berikut

   • kunci: name kolom skema keamanan Anda. Dalam contoh ini, seharusnya x-api-key

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

   • nilai: YOUR_API_KEY

8. Setelah membuat koneksi, Anda dapat menggunakannya melalui SDK atau REST API. Gunakan tab di bagian atas artikel ini untuk melihat contoh kode.

Mengatur koneksi dengan token Bearer

Anda dapat menggunakan autentikasi berbasis token (misalnya, token Pembawa) dengan jenis autentikasi yang sama yang project_connection digunakan untuk kunci API. Perbedaan utamanya adalah cara Anda mengonfigurasi spesifikasi OpenAPI dan koneksi proyek.

Spesifikasi OpenAPI Anda akan terlihat seperti ini:

  BearerAuth:
    type: http
    scheme: bearer
    bearerFormat: JWT

Anda perlu:

1. Perbarui spesifikasi securitySchemes OpenAPI Anda untuk digunakan Authorization sebagai nama header:

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

2. security Tambahkan bagian yang mereferensikan skema:

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

3. Buat koneksi Kunci kustom di proyek Foundry Anda:

   1. Buka portal Foundry dan buka proyek Anda.
   2. Buat atau pilih koneksi yang menyimpan rahasia. Lihat Menambahkan koneksi baru ke proyek Anda.
   3. Masukkan nilai berikut:
      • kunci: (harus cocok dengan kolom dalam Anda)
      • nilai: Bearer <token> (ganti <token> dengan token aktual Anda)

   Penting

   Nilai harus menyertakan kata Bearer diikuti dengan spasi sebelum token. Misalnya: Bearer eyJhbGciOiJSUzI1NiIs.... Jika Anda menghilangkan Bearer , API menerima token mentah tanpa awalan skema otorisasi yang diperlukan, dan permintaan gagal.

4. Setelah Anda membuat koneksi, gunakan dengan tipe autentikasi project_connection dalam kode Anda, sama seperti Anda melakukannya untuk autentikasi kunci API. ID koneksi menggunakan format yang sama: /subscriptions/{{subscriptionID}}/resourceGroups/{{resourceGroupName}}/providers/Microsoft.CognitiveServices/accounts/{{foundryAccountName}}/projects/{{foundryProjectName}}/connections/{{foundryConnectionName}}.

Mengautentikasi dengan menggunakan identitas terkelola (Microsoft Entra ID)

Microsoft Entra ID adalah layanan manajemen identitas dan akses berbasis cloud yang dapat digunakan karyawan Anda untuk mengakses sumber daya eksternal. Dengan menggunakan Microsoft Entra ID, Anda dapat menambahkan keamanan tambahan ke API Anda tanpa perlu menggunakan kunci API. Saat Anda menyiapkan autentikasi identitas terkelola, agen mengautentikasi melalui alat Foundry yang digunakannya.

Penting

Autentikasi identitas terkelola hanya berfungsi saat layanan target menerima token Microsoft Entra ID. Jika API target menggunakan skema autentikasi kustom yang tidak mendukung Microsoft Entra ID, gunakan kunci API atau token Bearer sebagai gantinya.

Memahami URI audiens

audience (terkadang disebut pengidentifikasi sumber daya atau URI ID aplikasi) memberi tahu Microsoft Entra ID layanan atau API mana yang dimaksudkan untuk diakses oleh token. Nilai audiens harus sesuai dengan apa yang diharapkan layanan target, atau autentikasi gagal dengan kesalahan 401.

Catatan

Audiens bukan titik akhir proyek Foundry Anda. Ini adalah pengidentifikasi sumber daya dari layanan target yang dipanggil alat OpenAPI Anda.

Tabel berikut ini mencantumkan URI audiens untuk layanan Azure umum:

Layanan target	URI Audiens
Azure Storage	https://storage.azure.com
Azure Key Vault	https://vault.azure.net
Pencarian Azure AI	https://search.azure.com
Azure Logic Apps	https://logic.azure.com
Azure API Management (lapisan manajemen)	https://management.azure.com
API dilindungi oleh pendaftaran aplikasi Microsoft Entra (termasuk APIM dengan OAuth)	URI ID Aplikasi dari pendaftaran aplikasi Anda (misalnya, api://<client-id>)

Tips

Jika Anda menggunakan Azure API Management untuk melindungi API kustom dengan kebijakan validasi OAuth 2.0, audiens adalah URI ID Application dari pendaftaran aplikasi yang melindungi API — bukan https://management.azure.com. Audiens bidang manajemen hanya berlaku untuk operasi Azure Resource Manager pada sumber daya APIM itu sendiri.

Untuk informasi selengkapnya tentang cara agen mengautentikasi dengan Microsoft Entra ID, lihat identitas dan autentikasi Agent.

Menemukan dan memverifikasi audiens Anda

Gunakan langkah-langkah berikut untuk menentukan dan memverifikasi nilai audiens yang benar:

• Untuk layanan Azure: Periksa dokumentasi layanan untuk pengidentifikasi sumber daya Microsoft Entra ID. Sebagian besar layanan Azure mencantumkan URI audiens dalam dokumentasi autentikasi mereka.
• Untuk API yang dilindungi oleh pendaftaran aplikasi Microsoft Entra: Di portal Azure, buka Microsoft Entra ID>Pendaftaran aplikasi> pilih aplikasi Anda >Buat API. URI ID Aplikasi di bagian atas halaman adalah nilai audiens Anda.
• Untuk memverifikasi audiens token: Dekodekan token akses di https://jwt.ms dan periksa aud klaim. Nilai aud harus sesuai dengan audiens yang diharapkan layanan target Anda.

Menyiapkan autentikasi identitas terkelola

Untuk menyiapkan autentikasi dengan menggunakan Identitas Terkelola:

1. Pastikan sumber daya Foundry Anda mengaktifkan identitas terkelola yang ditetapkan sistem.

   cuplikan layar

2. Buat sumber daya untuk layanan yang ingin Anda sambungkan melalui spesifikasi OpenAPI.

3. Tetapkan akses yang tepat ke sumber daya.

   1. Pilih Access Control untuk sumber daya Anda.

   2. Pilih Tambahkan lalu tambahkan penetapan peran di bagian atas layar.

      cuplikan layar yang memperlihatkan pengatur penetapan peran di portal Azure.

   3. Pilih penetapan peran yang diperlukan, biasanya memerlukan setidaknya peran PEMBACA. Lalu pilih Berikutnya.

   4. Pilih Identitas terkelola lalu pilih pilih anggota.

   5. Di menu dropdown identitas terkelola, cari Akun Foundry lalu pilih akun Foundry agen Anda.

   6. Pilih Selesai.

4. Setelah menyelesaikan penyiapan, Anda dapat melanjutkan dengan menggunakan alat melalui portal Foundry, SDK, atau REST API. Gunakan tab di bagian atas artikel ini untuk melihat sampel kode.

Memecahkan masalah kesalahan umum

Gejala	Kemungkinan penyebabnya	Resolusi
Kunci API tidak disertakan dalam permintaan.	Spesifikasi OpenAPI bagian securitySchemes atau security hilang.	Verifikasi apakah spesifikasi OpenAPI Anda mencakup bagian components.securitySchemes dan bagian tingkat atas security. Pastikan skema name cocok dengan nama kunci dalam koneksi proyek Anda.
Agen tidak memanggil alat OpenAPI.	Pilihan alat tidak diatur atau operationId tidak deskriptif.	Gunakan tool_choice="required" untuk memaksa pemanggilan alat. Pastikan operationId nilai deskriptif sehingga model dapat memilih operasi yang tepat.
Autentikasi gagal untuk identitas yang dikelola.	Identitas yang dikelola tidak diaktifkan atau tidak ada penetapan peran.	Aktifkan identitas terkelola yang ditetapkan sistem pada sumber daya Foundry Anda. Tetapkan peran yang diperlukan (Pembaca atau lebih tinggi) pada layanan target.
Identitas terkelola memberikan respons 401 meskipun peran sudah ditetapkan.	URI audiens tidak cocok dengan apa yang diharapkan layanan target.	Verifikasi URI audiens sesuai dengan pengenal sumber daya dari layanan target. Untuk layanan Azure, periksa dokumentasi layanan. Untuk API yang dilindungi Microsoft Entra, gunakan URI ID Aplikasi dari pendaftaran aplikasi Anda. Dekodekan token di https://jwt.ms dan konfirmasi klaim aud cocok. Lihat Memahami URI audiens.
Token identitas terkelola ditolak oleh API target.	Layanan target tidak menerima token Microsoft Entra ID.	Konfirmasikan bahwa layanan target mendukung autentikasi Microsoft Entra ID. Jika tidak, gunakan kunci API atau autentikasi token Pembawa sebagai gantinya.
Permintaan gagal dengan 400 Permintaan Buruk.	Spesifikasi OpenAPI tidak cocok dengan API aktual.	Validasi spesifikasi OpenAPI Anda terhadap API aktual. Periksa nama parameter, jenis, dan bidang yang diperlukan.
Permintaan gagal, 401 Tidak Terotorisasi.	Kunci API atau token tidak valid atau kedaluwarsa.	Regenerasi kunci/token API dan perbarui koneksi proyek Anda. Pastikan ID koneksi sudah benar.
Alat mengembalikan format respons yang tidak terduga.	Skema respons tidak ditentukan dalam spesifikasi OpenAPI.	Tambahkan skema respons ke spesifikasi OpenAPI Anda untuk pemahaman model yang lebih baik.
operationId kesalahan validasi.	Karakter tidak valid dalam operationId.	Gunakan hanya huruf, -, dan _ dalam operationId nilai. Hapus angka dan karakter khusus.
Kesalahan koneksi tidak ditemukan.	Nama koneksi dan ID tidak cocok.	Verifikasi OPENAPI_PROJECT_CONNECTION_NAME cocok dengan nama koneksi dalam proyek Foundry Anda.
Token pembawa tidak dikirim dengan benar.	Nilai koneksi tidak memiliki prefiks Bearer .	Atur nilai koneksi ke Bearer <token> (dengan kata Bearer dan spasi sebelum token). Verifikasi bahwa spesifikasi securitySchemes OpenAPI menggunakan "name": "Authorization".

Pilih metode autentikasi

Tabel berikut membantu Anda memilih metode autentikasi yang tepat untuk alat OpenAPI Anda:

Metode autentikasi	Terbaik untuk	Kompleksitas penyiapan
Anonim	API Publik tanpa autentikasi	Rendah
Kunci API	API non-Microsoft dengan akses berbasis kunci	Menengah
Identitas terkelola	layanan Azure dan API yang dilindungi ID Microsoft Entra. Mengharuskan layanan target menerima token Microsoft Entra ID dan mendukung Azure RBAC atau kontrol akses berbasis Microsoft Entra.	Menengah-Tinggi

Konten terkait

• Menambahkan koneksi baru ke proyek Anda
• Menyiapkan lingkungan Anda untuk Foundry Agent Service
• Identitas dan autentikasi agen
• Ekspos API dan konfigurasikan cakupan (Microsoft Entra ID)
• Agen REST API (Pratinjau)