Conectar agentes a ferramentas OpenAPI

Exemplo completo

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)

O que esse código faz

Este exemplo cria um agente com uma ferramenta OpenAPI que chama a API de clima wttr.in usando autenticação anônima. Ao executar o código:

1. Ele carrega a especificação openAPI do tempo de um arquivo JSON local.
2. Cria um agente com a ferramenta de clima configurada para acesso anônimo.
3. Envia uma consulta perguntando sobre o tempo de Seattle.
4. O agente usa a ferramenta OpenAPI para chamar a API do tempo e retorna resultados formatados.
5. Limpa excluindo a versão do agente.

Entradas necessárias

• Valores de cadeia de caracteres na parte superior do script: PROJECT_ENDPOINT, OPENAPI_CONNECTION_NAME
• Arquivo local: weather_openapi.json (especificação OpenAPI)

Saída esperada

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

Erros comuns

• FileNotFoundError: arquivo de especificação OpenAPI não encontrado no caminho especificado
• AuthenticationError: credenciais inválidas ou permissões insuficientes ou ausentes securitySchemes na especificação OpenAPI para autenticação de chave de API
• Formato inválido operationId na especificação OpenAPI causa falha no registro da ferramenta
• Chave de API não injetada: verifique se a especificação OpenAPI inclui ambas as seções securitySchemes e security, e se o nome da chave corresponde à conexão do projeto.

Exemplo de uso de agentes com a ferramenta OpenAPI

Este exemplo demonstra como usar os serviços descritos por uma especificação OpenAPI usando um agente. Ele usa o serviço wttr.in para obter o clima e seu arquivo de especificação weather_openapi.json. Este exemplo usa métodos síncronos da biblioteca de cliente do Azure AI Projects. Para obter um exemplo que usa métodos assíncronos, consulte o sample no SDK do Azure para .NET repositório no 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);
    }
}

O que esse código faz

Este exemplo de C# cria um agente com uma ferramenta OpenAPI que recupera informações meteorológicas de wttr.in usando autenticação anônima. Ao executar o código:

1. Ele lê a especificação openAPI do tempo de um arquivo JSON local.
2. Cria um agente com a ferramenta meteorológica configurada.
3. Envia uma solicitação perguntando sobre o clima de Seattle usando a ferramenta OpenAPI.
4. O agente chama a API do tempo e retorna os resultados.
5. Limpa excluindo o agente.

Entradas necessárias

• Valor da string embutida: projectEndpoint (ponto de extremidade do projeto Foundry)
• Arquivo local: Assets/weather_openapi.json (especificação OpenAPI)

Saída esperada

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

Erros comuns

• FileNotFoundException: arquivo de especificação OpenAPI não encontrado na pasta Ativos
• UnauthorizedAccessException: credenciais inválidas ou permissões RBAC insuficientes
• Chave de API não injetada: verifique se sua especificação OpenAPI inclui ambas as seções securitySchemes (em components) e security com nomes de esquema correspondentes

Exemplo de uso de agentes com a ferramenta OpenAPI no serviço Web, exigindo autenticação

Neste exemplo, você usa serviços com uma especificação OpenAPI usando o agente em um cenário que requer autenticação. Use a especificação do TripAdvisor.

O serviço TripAdvisor requer autenticação baseada em chave. Para criar uma conexão no portal Azure, abra Microsoft Foundry e, no painel esquerdo, selecione Management center e selecione Conectados. Por fim, crie uma nova conexão do tipo de chaves personalizadas . Nomeie-o tripadvisor e adicione um par de valores de chave. Adicione uma chave nomeada key e insira um valor com sua chave do 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);
    }
}

O que esse código faz

Este exemplo de C# demonstra o uso de uma ferramenta OpenAPI com autenticação de chave de API por meio de uma conexão de projeto. Ao executar o código:

1. Ele carrega a especificação OpenAPI do TripAdvisor de um arquivo local.
2. Obtém a conexão de projeto tripadvisor que contém sua chave de API.
3. Cria um agente com a ferramenta TripAdvisor configurada para usar a conexão para autenticação.
4. Envia um pedido de recomendações de hotel em Paris.
5. O agente chama a API do TripAdvisor usando sua chave de API armazenada e retorna resultados.
6. Limpa excluindo o agente.

Entradas necessárias

• Valor da string embutida: projectEndpoint (ponto de extremidade do projeto Foundry)
• Arquivo local: Assets/tripadvisor_openapi.json
• Conexão do projeto: tripadvisor com a chave de API válida configurada

Saída esperada

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

Erros comuns

• ConnectionNotFoundException: nenhuma conexão de projeto nomeada tripadvisor encontrada.
• AuthenticationException: chave de API inválida na conexão do projeto ou configuração ausente/incorreta securitySchemes na especificação OpenAPI.
• Ferramenta não usada: Verificar ToolChoice = ResponseToolChoice.CreateRequiredChoice() força o uso da ferramenta.
• Chave de API não passada para a API: Verifique se a especificação OpenAPI tem as seções adequadas securitySchemes e security configuradas.

Criar um agente Java com recursos de ferramenta OpenAPI

Este exemplo Java cria um agente com uma ferramenta OpenAPI usando com.azure:azure-ai-agents e um arquivo de especificação OpenAPI local. O exemplo usa autenticação anônima e chama um endpoint de API pública.

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

O que esse código faz

Este exemplo em Java cria um agente com uma ferramenta OpenAPI e executa uma resposta com escopo de conversação.

1. Carrega a especificação OpenAPI de openapi_spec.json.
2. Cria uma versão do agente com OpenApiTool.
3. Cria uma conversa e adiciona uma mensagem de usuário.
4. Cria uma resposta passando AgentReference e a ID da conversa.
5. Limpa excluindo a versão do agente.

Entradas necessárias

• Valor da string embutida: projectEndpoint (ponto de extremidade do projeto Foundry)
• Arquivo local: openapi_spec.json (especificação do OpenAPI 3.0 ou 3.1)

Saída esperada

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

Erros comuns

• Invalid OpenAPI specification: analise o JSON do OpenAPI em um objeto antes de passá-lo para OpenApiFunctionDefinition.
• Invalid conversation id: crie uma conversa e passe conversation.id() para createAzureResponse via ResponseCreateParams.builder().conversation().
• AuthenticationFailedException: Verifique DefaultAzureCredential se pode obter um token para a conta na qual você está conectado.

Os exemplos a seguir mostram como chamar uma ferramenta OpenAPI usando a API REST.

Obtenha um token de acesso:

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

Autenticação anônima

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

Autenticação de chave de API (conexão de projeto)

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

Autenticação de identidade gerenciada

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

O que esse código faz

Este exemplo de API REST mostra como chamar uma ferramenta OpenAPI com métodos de autenticação diferentes. A solicitação:

1. Envia uma consulta ao agente perguntando sobre o tempo de Seattle.
2. Inclui a definição embutida da ferramenta OpenAPI em linha com a especificação da API de previsão do tempo.
3. Mostra três opções de autenticação (anônimo, chave de API por meio de conexão de projeto, identidade gerenciada) como alternativas comentadas.
4. O agente usa a ferramenta para chamar a API de clima e retorna resultados formatados.

Entradas necessárias

• Variáveis de ambiente: FOUNDRY_PROJECT_ENDPOINT, , AGENT_TOKEN. FOUNDRY_MODEL_DEPLOYMENT_NAME
• Para autenticação de chave de API: WEATHER_APP_PROJECT_CONNECTION_ID.
• Para autenticação de identidade gerenciada: MANAGED_IDENTITY_AUDIENCE.
• Especificação openapi embutida no corpo da solicitação.

Saída esperada

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

Erros comuns

• 401 Unauthorized: inválido ou ausente AGENT_TOKEN, ou chave de API não injetada porque securitySchemes e security estão ausentes em sua especificação OpenAPI
• 404 Not Found: nome de implantação de modelo ou ponto de extremidade incorreto
• 400 Bad Request: especificação de OpenAPI malformada ou configuração de autenticação inválida
• Chave de API não enviada com solicitação: verifique se a components.securitySchemes seção em sua especificação OpenAPI está configurada corretamente (não vazia) e corresponde ao nome da chave de conexão do projeto

Criar um agente com recursos de ferramenta OpenAPI

O exemplo de código TypeScript a seguir demonstra como criar um agente de IA com recursos da ferramenta OpenAPI, usando o cliente dos projetos de IA do Azure e sincronizado. O agente pode chamar APIs externas definidas pelas especificações do OpenAPI. Para obter uma versão javaScript deste exemplo, consulte o sample no repositório SDK do Azure para JavaScript no 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);
});

O que esse código faz

Este exemplo de TypeScript cria um agente com uma ferramenta OpenAPI para dados meteorológicos usando autenticação anônima. Ao executar o código:

1. Ele carrega a especificação openAPI do tempo de um arquivo JSON local.
2. Cria um agente com a ferramenta meteorológica configurada.
3. Envia uma solicitação de streaming perguntando sobre o clima e o planejamento de roupas de Seattle.
4. Processa a resposta de streaming e exibe deltas à medida que chegam.
5. Ele força o uso de ferramentas usando tool_choice: "required" para garantir que a API seja chamada.
6. Limpa excluindo o agente.

Entradas necessárias

• Valor da string embutida: PROJECT_ENDPOINT (ponto de extremidade do projeto Foundry)
• Arquivo local: ../assets/weather_openapi.json (especificação OpenAPI)

Saída esperada

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!

Erros comuns

• Error: OpenAPI specification not found: caminho de arquivo incorreto ou arquivo ausente
• AuthenticationError: credenciais de Azure inválidas
• A chave de API não está funcionando: se você alternar de anônimo para autenticação de chave de API, verifique se sua especificação OpenAPI está securitySchemes configurada e security configurada corretamente

Criar um agente que usa ferramentas OpenAPI autenticadas com uma conexão de projeto

O exemplo de código TypeScript a seguir demonstra como criar um agente de IA que usa ferramentas OpenAPI autenticadas por meio de uma conexão de projeto. O agente carrega a especificação OpenAPI do TripAdvisor de ativos locais e pode invocar a API por meio da conexão de projeto configurada. Para obter uma versão javaScript deste exemplo, consulte o sample no repositório SDK do Azure para JavaScript no 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);
});

O que esse código faz

Este exemplo de TypeScript demonstra o uso de uma ferramenta OpenAPI com autenticação de chave de API por meio de uma conexão de projeto. Ao executar o código:

1. Ele carrega a especificação OpenAPI do TripAdvisor de um arquivo local.
2. Ele configura a autenticação usando a TRIPADVISOR_CONNECTION_ID constante.
3. Ele cria um agente com a ferramenta TripAdvisor que utiliza a conexão do projeto para facilitar a autenticação por chave de API.
4. Ele envia uma solicitação de transmissão para obter detalhes de localização do TripAdvisor.
5. Ele força o uso de ferramentas usando tool_choice: "required" para garantir que a API seja chamada.
6. Ele processa e exibe a resposta de transmissão em tempo real.
7. A limpeza é realizada ao excluir o agente.

Entradas necessárias

• Valores de cadeia de caracteres embutidas: PROJECT_ENDPOINT, TRIPADVISOR_CONNECTION_ID
• Arquivo local: ../assets/tripadvisor_openapi.json
• Conexão do projeto configurada com a chave de API do TripAdvisor

Saída esperada

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!

Erros comuns

• Error: OpenAPI specification not found: verifique o caminho do arquivo.
• Conexão não encontrada: verifique se TRIPADVISOR_CONNECTION_ID está correta e a conexão existe.
• AuthenticationException: chave de API inválida na conexão do projeto.
• Chave de API não injetada em solicitações: sua especificação OpenAPI deve incluir seções apropriadas em securitySchemes (sob components) e security. O nome da chave em securitySchemes deve corresponder à chave na conexão do seu projeto.
• Content type is not supported: atualmente, somente esses dois tipos de conteúdo do corpo da solicitação têm suporte: application/json e application/json-patch+json. Os tipos de conteúdo de resposta não são restritos.