Подключение агентов к средствам OpenAPI

Полный пример

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)

Что делает этот код

В этом примере создается агент с инструментом OpenAPI, который вызывает API погоды wttr.in с помощью анонимной проверки подлинности. При запуске кода:

1. Она загружает спецификацию OpenAPI погоды из локального JSON-файла.
2. Создает агент с средством погоды, настроенным для анонимного доступа.
3. Отправляет запрос с просьбой о погоде Сиэтла.
4. Агент использует средство OpenAPI для вызова API погоды и возвращает форматированные результаты.
5. Очищает, удаляя версию агента.

Обязательные входные данные

• Строковые значения в верхней части скрипта: PROJECT_ENDPOINTOPENAPI_CONNECTION_NAME
• Локальный файл: weather_openapi.json (спецификация OpenAPI)

Ожидаемые выходные данные

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

Распространенные ошибки

• FileNotFoundError: файл спецификации OpenAPI не найден по указанному пути
• AuthenticationError: недопустимые учетные данные, недостаточно разрешений, или отсутствует securitySchemes в спецификации OpenAPI для аутентификации ключа API
• Недопустимый operationId формат в спецификации OpenAPI приводит к сбою регистрации средства
• Ключ API не введен: убедитесь, что спецификация OpenAPI включает оба раздела и то, что имя ключа соответствует подключению к проекту.

Пример использования агентов с инструментом OpenAPI

В этом примере показано, как использовать службы, описанные спецификацией OpenAPI с помощью агента. Она использует службу wttr.in для получения погоды и файла спецификации weather_openapi.json. В этом примере используются синхронные методы клиентской библиотеки Azure AI Projects. Пример использования асинхронных методов см. в образце из репозитория Azure SDK для .NET на 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);
    }
}

Что делает этот код

В этом примере C# создается агент с инструментом OpenAPI, который извлекает сведения о погоде из wttr.in с помощью анонимной проверки подлинности. При запуске кода:

1. Он считывает спецификацию погоды OpenAPI из локального JSON-файла.
2. Создает агент с настроенным инструментом погоды.
3. Отправляет запрос о погоде Сиэтла с помощью средства OpenAPI.
4. Агент вызывает API погоды и возвращает результаты.
5. Удаляет агент, очищая систему.

Обязательные входные данные

• Встроенное строковое значение: projectEndpoint (ваша конечная точка проекта Foundry)
• Локальный файл: Assets/weather_openapi.json (спецификация OpenAPI)

Ожидаемые выходные данные

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

Распространенные ошибки

• FileNotFoundException: файл спецификации OpenAPI не найден в папке "Ресурсы"
• UnauthorizedAccessException: недопустимые учетные данные или недостаточно разрешений RBAC
• Ключ API не добавлен: убедитесь, что спецификация OpenAPI содержит как securitySchemes (в components), так и security разделы, чтобы имена схем совпадали.

Пример использования агентов с средством OpenAPI в веб-службе, требующий проверки подлинности

В этом примере используются службы со спецификацией OpenAPI с помощью агента в сценарии, требующего проверки подлинности. Вы используете спецификацию TripAdvisor.

Служба TripAdvisor требует проверки подлинности на основе ключей. Чтобы создать подключение на портале Azure, откройте Microsoft Foundry и на левой панели выберите центр Management и выберите Соединяемые ресурсы. Наконец, создайте новое подключение типа пользовательских ключей . Назовите его tripadvisor и добавьте пару "ключ-значение". Добавьте ключ с именем key и введите значение с помощью ключа TripAdvisor.

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

Что делает этот код

В этом примере C# демонстрируется использование средства OpenAPI с проверкой подлинности ключа API через подключение к проекту. При запуске кода:

1. Она загружает спецификацию TripAdvisor OpenAPI из локального файла.
2. Получает tripadvisor подключение проекта, включающее ваш ключ API.
3. Создает агент с инструментом TripAdvisor, настроенным на использование соединения для аутентификации.
4. Отправляет запрос на рекомендации по отелям в Париже.
5. Агент вызывает API TripAdvisor с помощью сохраненного ключа API и возвращает результаты.
6. Удаляет агент, очищая систему.

Обязательные входные данные

• Встроенное строковое значение: projectEndpoint (ваша конечная точка проекта Foundry)
• Локальный файл: Assets/tripadvisor_openapi.json
• Подключение к проекту: tripadvisor с валидным ключом API.

Ожидаемые выходные данные

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

Распространенные ошибки

• ConnectionNotFoundException: не найдено подключение проекта с именем tripadvisor.
• AuthenticationException: Неверный ключ API в подключении проекта, или отсутствует/неправильная конфигурация securitySchemes в спецификации OpenAPI.
• Средство не используется: убедитесь, что проверка ToolChoice = ResponseToolChoice.CreateRequiredChoice() принуждает использовать инструмент.
• Ключ API не передан в API: убедитесь, что спецификация OpenAPI правильно настроена и разделы securitySchemes и security сконфигурированы.

Создание агента Java с помощью возможностей инструментов OpenAPI

В этом Java примере создается агент с инструментом OpenAPI с помощью com.azure:azure-ai-agents и локального файла спецификации OpenAPI. В примере используется анонимная проверка подлинности и вызывается общедоступная конечная точка API.

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

Что делает этот код

В этом примере на Java создается агент с помощью инструмента OpenAPI и выполняется ответ в рамках разговора.

1. Загружает спецификацию OpenAPI из openapi_spec.json.
2. Создаёт версию агента OpenApiTool.
3. Создает беседу и добавляет сообщение пользователя.
4. Создает ответ, передавая AgentReference и идентификатор разговора.
5. Очищает, удаляя версию агента.

Обязательные входные данные

• Встроенное строковое значение: projectEndpoint (ваша конечная точка проекта Foundry)
• Локальный файл: openapi_spec.json (спецификация OpenAPI 3.0 или 3.1)

Ожидаемые выходные данные

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

Распространенные ошибки

• Invalid OpenAPI specification: Разобрать JSON OpenAPI в объект перед передачей в OpenApiFunctionDefinition.
• Invalid conversation id: Создайте беседу и передайте conversation.id()createAzureResponse через ResponseCreateParams.builder().conversation().
• AuthenticationFailedException: убедитесь, что DefaultAzureCredential вы можете получить токен для вашей учетной записи входа.

В следующих примерах показано, как вызвать средство OpenAPI с помощью REST API.

Получение токена доступа:

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

Анонимная проверка подлинности

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

Проверка подлинности ключа API (подключение к проекту)

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

Проверка подлинности удостоверения с управлением

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

Что делает этот код

В этом примере REST API показано, как вызвать средство OpenAPI с различными методами проверки подлинности. Запрос:

1. Отправляет запрос агенту с просьбой о погоде Сиэтла.
2. Включает определение средства OpenAPI в соответствие со спецификацией API погоды.
3. Показывает три варианта проверки подлинности (анонимный, ключ API через подключение проекта, управляемое удостоверение) в качестве закомментированных альтернатив.
4. Агент использует средство для вызова API погоды и возвращает форматированные результаты.

Обязательные входные данные

• Переменные среды: FOUNDRY_PROJECT_ENDPOINT, AGENT_TOKEN, FOUNDRY_MODEL_DEPLOYMENT_NAME.
• Для проверки подлинности ключа API: WEATHER_APP_PROJECT_CONNECTION_ID
• Для проверки подлинности управляемой идентификации: MANAGED_IDENTITY_AUDIENCE
• Встроенная спецификация OpenAPI в тексте запроса.

Ожидаемые выходные данные

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

Распространенные ошибки

• 401 Unauthorized: недопустимый или отсутствующий AGENT_TOKEN, или ключ API не внедрён, так как securitySchemes и security отсутствуют в спецификации OpenAPI.
• 404 Not Found: неправильное имя конечной точки или развертывания модели
• 400 Bad Request: неправильно сформированная спецификация OpenAPI или недопустимая конфигурация проверки подлинности
• Ключ API не отправлен с запросомcomponents.securitySchemes: убедитесь, что раздел в спецификации OpenAPI правильно настроен (не пуст) и соответствует имени ключа подключения проекта.

Создание агента с помощью возможностей инструментов OpenAPI

В следующем примере кода TypeScript показано, как создать агент ИИ с возможностями средства OpenAPI, используя OpenApiTool и клиент синхронных проектов Azure AI. Агент может вызывать внешние API, определенные спецификациями OpenAPI. Версию JavaScript этого примера см. в sample в репозитории JavaScript Azure SDK на 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);
});

Что делает этот код

В этом примере TypeScript создается агент с инструментом OpenAPI для данных о погоде с помощью анонимной проверки подлинности. При запуске кода:

1. Она загружает спецификацию OpenAPI погоды из локального JSON-файла.
2. Создает агент с настроенным инструментом погоды.
3. Отправляет запрос потоковой передачи, спрашивая о погоде в Сиэтле и планировании одежды.
4. Обрабатывает потоковый ответ и отображает изменения по мере поступления.
5. Он принудительно использует средство, tool_choice: "required" чтобы убедиться, что API вызывается.
6. Удаляет агент, очищая систему.

Обязательные входные данные

• Встроенное строковое значение: PROJECT_ENDPOINT (ваша конечная точка проекта Foundry)
• Локальный файл: ../assets/weather_openapi.json (спецификация OpenAPI)

Ожидаемые выходные данные

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!

Распространенные ошибки

• Error: OpenAPI specification not found: неправильный путь к файлу или отсутствующий файл
• AuthenticationError: недопустимые учетные данные Azure
• Ключ API не работает: если вы переключаетесь с анонимной аутентификации на авторизацию с использованием ключа API, убедитесь, что спецификация OpenAPI и securitySchemes и security настроены правильно.

Создание агента, использующего средства OpenAPI, прошедший проверку подлинности с подключением к проекту

В следующем примере кода TypeScript показано, как создать агент ИИ, использующий средства OpenAPI, прошедшие проверку подлинности через подключение к проекту. Агент загружает спецификацию TripAdvisor OpenAPI из локальных ресурсов и может вызывать API с помощью настроенного подключения проекта. Версию JavaScript этого примера см. в sample в репозитории JavaScript Azure SDK на 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);
});

Что делает этот код

В этом примере TypeScript демонстрируется использование средства OpenAPI с проверкой подлинности ключа API через подключение к проекту. При запуске кода:

1. Она загружает спецификацию TripAdvisor OpenAPI из локального файла.
2. Он настраивает проверку подлинности с помощью TRIPADVISOR_CONNECTION_ID константы.
3. Он создает агента, используя инструмент TripAdvisor, который применяет подключение проекта для аутентификации с помощью API-ключа.
4. Он отправляет потоковый запрос для получения сведений о местоположениях на TripAdvisor.
5. Он принудительно использует средство, tool_choice: "required" чтобы убедиться, что API вызывается.
6. Он обрабатывает и отображает ответ потоковой передачи.
7. Она очищается путем удаления агента.

Обязательные входные данные

• Встроенные строковые значения: PROJECT_ENDPOINT, TRIPADVISOR_CONNECTION_ID
• Локальный файл: ../assets/tripadvisor_openapi.json
• Параметры подключения проекта с использованием ключа API TripAdvisor.

Ожидаемые выходные данные

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!

Распространенные ошибки

• Error: OpenAPI specification not found: проверьте путь к файлу.
• Соединение не найдено: проверьте, что TRIPADVISOR_CONNECTION_ID верно и соединение существует.
• AuthenticationException: некорректный ключ API в подключении проекта.
• Ключ API не интегрирован в запросы: спецификация OpenAPI должна содержать правильные разделы securitySchemes (под components) и security. Имя ключа в securitySchemes должно соответствовать ключу в подключении вашего проекта.
• Content type is not supported: в настоящее время поддерживаются только два типа контента текста запроса: application/json и application/json-patch+json. Типы контента ответа не ограничены.