Så här använder du Azure AI Agent Service med OpenAPI-angivna verktyg

Artikel
12/20/2024

Nu kan du ansluta din Azure AI-agent till ett externt API med ett OpenAPI 3.0-angivet verktyg, vilket möjliggör skalbar samverkan med olika program. Aktivera dina anpassade verktyg för att autentisera åtkomst och anslutningar med hanterade identiteter (Microsoft Entra-ID) för ökad säkerhet, vilket gör det idealiskt för integrering med befintlig infrastruktur eller webbtjänster.

OpenAPI-angivet verktyg förbättrar funktionens samtalsupplevelse genom att tillhandahålla standardiserade, automatiserade och skalbara API-integreringar som förbättrar agentens funktioner och effektivitet. OpenAPI-specifikationer tillhandahåller en formell standard för att beskriva HTTP-API:er. På så sätt kan användarna förstå hur ett API fungerar, hur en sekvens med API:er fungerar tillsammans, generera klientkod, skapa tester, tillämpa designstandarder med mera. För närvarande stöder vi tre autentiseringstyper med de OpenAPI 3.0-angivna verktygen: anonymous, API key, managed identity.

Förutsättningar

Kontrollera att du har slutfört förutsättningarna och installationsstegen i snabbstarten.
Kontrollera OpenAPI-specifikationen för följande krav:
1. operationId får endast innehålla bokstäver - och _. Du kan ändra den för att uppfylla kravet. Vi rekommenderar att du använder beskrivande namn för att hjälpa modeller att effektivt bestämma vilken funktion som ska användas.

Autentisera med API-nyckel

Kontrollera att OpenAPI-specifikationen stöder API-nycklar: den har securitySchemes avsnittet och har ett schema av typen "apiKey". Ett exempel är:
```
    "securitySchemes": {
       "apiKeyHeader": {
                 "type": "apiKey",
                 "name": "x-api-key",
                 "in": "header"
             }
     }
```
Om säkerhetsschemana innehåller flera scheman rekommenderar vi att du bara behåller ett av dem.
Ta bort alla parametrar i OpenAPI-specifikationen som behöver API-nyckel, eftersom API-nyckeln lagras och skickas via en anslutning, enligt beskrivningen senare i den här artikeln.
Skapa en custom keys anslutning för att lagra din API-nyckel.
1. Gå till Azure AI Foundry-portalen och välj AI-projektet. Klicka på Anslutna resurser.
2. Välj + ny anslutning på inställningssidan.
  
  Kommentar
  
  Om du återskapar API-nyckeln vid ett senare tillfälle måste du uppdatera anslutningen med den nya nyckeln.
3. Välj anpassade nycklar i andra resurstyper.
4. Ange följande information:
  - nyckel: name i ditt säkerhetsschema. I det här exemplet bör det vara x-api-key
```
       "securitySchemes": {
          "apiKeyHeader": {
                    "type": "apiKey",
                    "name": "x-api-key",
                    "in": "header"
                }
        }
```
  - värde: YOUR_API_KEY
  - Anslutningsnamn: YOUR_CONNECTION_NAME (Du använder det här anslutningsnamnet i exempelkoden nedan.)
  - Åtkomst: du kan välja antingen endast det här projektet eller delas till alla projekt. Se bara till att det projekt som du angav anslutningssträng för i exempelkoden nedan har åtkomst till den här anslutningen.

Steg 1: Skapa en agent med verktyget OpenAPI Spec

Skapa ett klientobjekt som innehåller anslutningssträng för att ansluta till ditt AI-projekt och andra resurser.

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

Steg 2: Aktivera verktyget OpenAPI Spec

Du kanske vill lagra OpenAPI-specifikationen i en annan fil och importera innehållet för att initiera verktyget. Observera att exempelkoden använder anonymous som autentiseringstyp.

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)

Om du vill använda anslutningen, som lagrar API-nyckeln, för autentisering ersätter du raden med

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

Ditt anslutnings-ID ser ut som /subscriptions/{subscription ID}/resourceGroups/{resource group name}/providers/Microsoft.MachineLearningServices/workspaces/{project name}/connections/{connection name}.

Om du vill använda hanterad identitet för autentisering ersätter du raden med

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

Ett exempel på målgruppen skulle vara 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;

Steg 4: Skapa en körning och kontrollera utdata

Skapa en körning och observera att modellen använder verktyget OpenAPI Spec för att ge ett svar på användarens fråga.

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

Dela via