Azure AI Agent Service gebruiken met OpenAPI Specified Tools

Artikel
12/20/2024

U kunt uw Azure AI-agent nu verbinden met een externe API met behulp van een opgegeven OpenAPI 3.0-hulpprogramma, waardoor schaalbare interoperabiliteit met verschillende toepassingen mogelijk is. Stel uw aangepaste hulpprogramma's in staat om toegang en verbindingen met beheerde identiteiten (Microsoft Entra ID) te verifiëren voor extra beveiliging, waardoor deze ideaal is voor integratie met bestaande infrastructuur of webservices.

Het hulpprogramma OpenAPI Specified verbetert uw functieaanroepen door gestandaardiseerde, geautomatiseerde en schaalbare API-integraties te bieden die de mogelijkheden en efficiëntie van uw agent verbeteren. OpenAPI-specificaties bieden een formele standaard voor het beschrijven van HTTP-API's. Hierdoor kunnen mensen begrijpen hoe een API werkt, hoe een reeks API's samenwerken, clientcode genereren, tests maken, ontwerpstandaarden toepassen en meer. Momenteel ondersteunen we 3 verificatietypen met de opgegeven Hulpprogramma's openAPI 3.0: anonymous, API key, managed identity.

Vereisten

Zorg ervoor dat u de vereisten en installatiestappen in de quickstart hebt voltooid.
Controleer de OpenAPI-specificatie op de volgende vereisten:
1. operationId mag alleen letters bevatten, - en _. U kunt deze wijzigen om te voldoen aan de vereiste. Het is raadzaam om beschrijvende naam te gebruiken om modellen te helpen efficiënt te bepalen welke functie moet worden gebruikt.

Verifiëren met API-sleutel

Controleer of de OpenAPI-specificatie API-sleutels ondersteunt: deze bevat securitySchemes een sectie en heeft één schema van het type 'apiKey'. Een voorbeeld hiervan is:
```
    "securitySchemes": {
       "apiKeyHeader": {
                 "type": "apiKey",
                 "name": "x-api-key",
                 "in": "header"
             }
     }
```
Als de beveiligingsschema's meerdere schema's bevatten, raden we u aan slechts één van deze schema's te bewaren.
Verwijder een parameter in de OpenAPI-specificatie die api-sleutel nodig heeft, omdat de API-sleutel wordt opgeslagen en doorgegeven via een verbinding, zoals verderop in dit artikel wordt beschreven.
Maak een custom keys verbinding om uw API-sleutel op te slaan.
1. Ga naar de Azure AI Foundry-portal en selecteer het AI-project. Klik op verbonden resources.
2. Selecteer + nieuwe verbinding op de pagina Instellingen.
  
  Notitie
  
  Als u de API-sleutel op een later tijdstip opnieuw genereert, moet u de verbinding met de nieuwe sleutel bijwerken.
3. Selecteer aangepaste sleutels in andere resourcetypen.
4. Geef de volgende informatie op
  - sleutel: name van uw beveiligingsschema. In dit voorbeeld moet dit het geval zijn x-api-key
```
       "securitySchemes": {
          "apiKeyHeader": {
                    "type": "apiKey",
                    "name": "x-api-key",
                    "in": "header"
                }
        }
```
  - waarde: YOUR_API_KEY
  - Verbindingsnaam: YOUR_CONNECTION_NAME (U gebruikt deze verbindingsnaam in de onderstaande voorbeeldcode.)
  - Toegang: u kunt dit project alleen kiezen of gedeeld met alle projecten. Zorg ervoor dat in de onderstaande voorbeeldcode het project dat u hebt ingevoerd verbindingsreeks toegang heeft tot deze verbinding.

Stap 1: Een agent maken met het hulpprogramma OpenAPI Spec

Maak een clientobject dat de verbindingsreeks bevat om verbinding te maken met uw AI-project en andere resources.

Python
C#

import os
import jsonref
from azure.ai.projects import AIProjectClient
from azure.identity import DefaultAzureCredential
from azure.ai.projects.models import OpenApiTool, OpenApiAnonymousAuthDetails


# Create an Azure AI Client from a connection string, copied from your Azure AI Foundry project.
# At the moment, it should be in the format "<HostName>;<AzureSubscriptionId>;<ResourceGroup>;<HubName>"
# Customer needs to login to Azure subscription via Azure CLI and set the environment variables

project_client = AIProjectClient.from_connection_string(
    credential=DefaultAzureCredential(),
    conn_str=os.environ["PROJECT_CONNECTION_STRING"],
)

using System;
using System.Collections.Generic;
using System.IO;
using System.Runtime.CompilerServices;
using System.Text.Json.Serialization;
using System.Text.Json;
using System.Threading.Tasks;
using Azure.Core.TestFramework;
using NUnit.Framework;
using Newtonsoft.Json.Linq;

namespace Azure.AI.Projects.Tests;

public partial class Sample_Agent_OpenAPI : SamplesBase<AIProjectsTestEnvironment>
{
    private static string GetFile([CallerFilePath] string pth = "")
    {
        var dirName = Path.GetDirectoryName(pth) ?? "";
        return Path.Combine(dirName, "weather_openapi.json");
    }

    [Test]
    public async Task OpenAPICallingExample()
    {
        var connectionString = TestEnvironment.AzureAICONNECTIONSTRING;
        var storageQueueUri = TestEnvironment.STORAGE_QUEUE_URI;
        AgentsClient client = new(connectionString, new DefaultAzureCredential());
        var file_path = GetFile();

Stap 2: het hulpprogramma OpenAPI Spec inschakelen

Mogelijk wilt u de OpenAPI-specificatie opslaan in een ander bestand en de inhoud importeren om het hulpprogramma te initialiseren. Let op: de voorbeeldcode wordt gebruikt anonymous als verificatietype.

Python
C#

with open('./weather_openapi.json', 'r') as f:
    openapi_spec = jsonref.loads(f.read())

# Create Auth object for the OpenApiTool (note that connection or managed identity auth setup requires additional setup in Azure)
auth = OpenApiAnonymousAuthDetails()

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

Als u verbinding wilt gebruiken, waarin DE API-sleutel wordt opgeslagen voor verificatie, vervangt u de regel door

auth = OpenApiConnectionAuthDetails(security_scheme=OpenApiConnectionSecurityScheme(connection_id="your_connection_id"))

Uw verbindings-id ziet er als volgt /subscriptions/{subscription ID}/resourceGroups/{resource group name}/providers/Microsoft.MachineLearningServices/workspaces/{project name}/connections/{connection name}uit.

Als u beheerde identiteit wilt gebruiken voor verificatie, vervangt u de regel door

auth = OpenApiManagedAuthDetails(security_scheme=OpenApiManagedSecurityScheme(audience="https://your_identity_scope.com"))

Een voorbeeld van de doelgroep zou zijn https://cognitiveservices.azure.com/.

    #region Snippet:OpenAPIDefineFunctionTools
    OpenApiAnonymousAuthDetails oaiAuth = new();
    OpenApiToolDefinition openapiTool = new(
        name: "get_weather",
        description: "Retrieve weather information for a location",
        spec: BinaryData.FromBytes(File.ReadAllBytes(file_path)),
        auth: oaiAuth
    );

# Create agent with OpenAPI tool and process assistant run
with project_client:
    agent = project_client.agents.create_agent(
        model="gpt-4o-mini",
        name="my-assistant",
        instructions="You are a helpful assistant",
        tools=openapi.definitions
    )
    print(f"Created agent, ID: {agent.id}")

    # Create thread for communication
    thread = project_client.agents.create_thread()
    print(f"Created thread, ID: {thread.id}")

Response<Agent> agentResponse = await client.CreateAgentAsync(
            model: "gpt-4",
            name: "azure-function-agent-foo",
            instructions: "You are a helpful assistant.",
            tools: new List<ToolDefinition> { openapiTool }
            );
Agent agent = agentResponse.Value;
#endregion
Response<AgentThread> threadResponse = await client.CreateThreadAsync();
AgentThread thread = threadResponse.Value;

Stap 4: Een uitvoering maken en de uitvoer controleren

Maak een uitvoering en kijk of het model gebruikmaakt van het hulpprogramma OpenAPI Spec om een antwoord te geven op de vraag van de gebruiker.

Python
C#

# Create message to thread
    message = project_client.agents.create_message(
        thread_id=thread.id,
        role="user",
        content="What's the weather in Seattle?",
    )
    print(f"Created message, ID: {message.id}")

    # Create and process agent run in thread with tools
    run = project_client.agents.create_and_process_run(thread_id=thread.id, assistant_id=agent.id)
    print(f"Run finished with status: {run.status}")

    if run.status == "failed":
        print(f"Run failed: {run.last_error}")

    # Delete the assistant when done
    project_client.agents.delete_agent(agent.id)
    print("Deleted agent")

    # Fetch and log all messages
    messages = project_client.agents.list_messages(thread_id=thread.id)
    print(f"Messages: {messages}")

        #region Snippet:OpenAPIHandlePollingWithRequiredAction
        Response<ThreadMessage> messageResponse = await client.CreateMessageAsync(
            thread.Id,
            MessageRole.User,
            "What's the weather in Seattle?");
        ThreadMessage message = messageResponse.Value;

        Response<ThreadRun> runResponse = await client.CreateRunAsync(thread, agent);

        do
        {
            await Task.Delay(TimeSpan.FromMilliseconds(500));
            runResponse = await client.GetRunAsync(thread.Id, runResponse.Value.Id);
        }
        while (runResponse.Value.Status == RunStatus.Queued
            || runResponse.Value.Status == RunStatus.InProgress
            || runResponse.Value.Status == RunStatus.RequiresAction);
        #endregion

        Response<PageableList<ThreadMessage>> afterRunMessagesResponse
            = await client.GetMessagesAsync(thread.Id);
        IReadOnlyList<ThreadMessage> messages = afterRunMessagesResponse.Value.Data;

        // Note: messages iterate from newest to oldest, with the messages[0] being the most recent
        foreach (ThreadMessage threadMessage in messages)
        {
            Console.Write($"{threadMessage.CreatedAt:yyyy-MM-dd HH:mm:ss} - {threadMessage.Role,10}: ");
            foreach (MessageContent contentItem in threadMessage.ContentItems)
            {
                if (contentItem is MessageTextContent textItem)
                {
                    Console.Write(textItem.Text);
                }
                else if (contentItem is MessageImageFileContent imageFileItem)
                {
                    Console.Write($"<image from ID: {imageFileItem.FileId}");
                }
                Console.WriteLine();
            }
        }

Delen via