Partilhar via

Como usar o Serviço Azure AI Agent com Ferramentas Especificadas OpenAPI

  • Artigo

Agora você pode conectar seu Agente de IA do Azure a uma API externa usando uma ferramenta especificada da OpenAPI 3.0, permitindo interoperabilidade escalável com vários aplicativos. Habilite suas ferramentas personalizadas para autenticar acesso e conexões com identidades gerenciadas (Microsoft Entra ID) para maior segurança, tornando-o ideal para integração com infraestrutura ou serviços Web existentes.

A ferramenta OpenAPI Specified melhora sua experiência de chamada de função fornecendo integrações de API padronizadas, automatizadas e escaláveis que aprimoram os recursos e a eficiência do seu agente. As especificações OpenAPI fornecem um padrão formal para descrever APIs HTTP. Isso permite que as pessoas entendam como uma API funciona, como uma sequência de APIs funciona em conjunto, gera código de cliente, cria testes, aplica padrões de design e muito mais. Atualmente, suportamos 3 tipos de autenticação com as ferramentas especificadas OpenAPI 3.0: anonymous, API key, managed identity.

Suporte de uso

Suporte de fundição de IA do Azure Python SDK SDK C# API REST Configuração básica do agente Configuração padrão do agente
✔️ ✔️ ✔️ ✔️ ✔️

Pré-requisitos

  1. Certifique-se de ter concluído os pré-requisitos e as etapas de configuração no início rápido.

  2. Verifique a especificação OpenAPI para os seguintes requisitos:

    1. operationId deve conter apenas letras, - e _. Você pode modificá-lo para atender ao requisito. Recomendamos o uso de nome descritivo para ajudar os modelos a decidir com eficiência qual função usar.

Autenticação com chave de API

  1. Verifique se a especificação OpenAPI suporta chaves de API: ela tem securitySchemes seção e tem um esquema do tipo apiKey. Por exemplo:

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

    Se os esquemas de segurança incluírem vários regimes, recomendamos manter apenas um deles.

  2. Remova qualquer parâmetro na especificação OpenAPI que precise de chave API, porque a chave API será armazenada e passada através de uma conexão, conforme descrito mais adiante neste artigo.

  3. Crie uma custom keys conexão para armazenar sua chave de API.

    1. Vá para o portal do Azure AI Foundry e selecione o Projeto AI. Clique em recursos conectados. Uma captura de tela do botão de configurações para um projeto de IA.

    2. Selecione + nova conexão na página de configurações.

      Nota

      Se você regenerar a chave da API em uma data posterior, precisará atualizar a conexão com a nova chave.

      Uma captura de tela da tela de conexões para o projeto de IA.

    3. Selecione chaves personalizadas em outros tipos de recursos.

      Uma captura de tela da seleção de chaves personalizadas para o projeto de IA.

    4. Introduza as seguintes informações

      • chave: name do seu esquema de segurança. Neste exemplo, deve ser x-api-key 
               "securitySchemes": {
          "apiKeyHeader": {
                    "type": "apiKey",
                    "name": "x-api-key",
                    "in": "header"
                }
        }
      • Valor: YOUR_API_KEY
      • Nome da conexão: YOUR_CONNECTION_NAME (Você usará esse nome de conexão no código de exemplo abaixo.)
      • Acesso: pode escolher apenas este projeto ou partilhado com todos os projetos. Apenas certifique-se de que, no código de exemplo abaixo, o projeto para o qual você inseriu a cadeia de conexão tenha acesso a essa conexão.

Etapa 1: Criar um cliente de projeto

Crie um objeto cliente, que conterá a cadeia de conexão para se conectar ao seu projeto de IA e outros recursos.

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"],
)

Etapa 2: Criar a definição da ferramenta OpenAPI Spec

Talvez você queira armazenar a especificação OpenAPI em outro arquivo e importar o conteúdo para inicializar a ferramenta. Observe que o código de exemplo está usando anonymous como tipo de autenticação.

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)

Se você quiser usar a conexão, que armazena a chave da API, para autenticação, substitua a linha por

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

O seu ID de ligação tem o aspeto de /subscriptions/{subscription ID}/resourceGroups/{resource group name}/providers/Microsoft.MachineLearningServices/workspaces/{project name}/connections/{connection name}.

Se você quiser usar a identidade gerenciada para autenticação, substitua a linha por

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

Um exemplo do público seria https://cognitiveservices.azure.com/.

Etapa 3: Criar um agente e um thread

# Create agent with OpenAPI tool and process assistant run
with project_client:
    agent = project_client.agents.create_agent(
        model="gpt-4o",
        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}")

Etapa 4: Criar uma execução e verificar a saída

Crie uma execução e observe que o modelo usa a ferramenta OpenAPI Spec para fornecer uma resposta à pergunta do usuário.

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