Compartilhar via

Como usar o Serviço do Agente de IA do Azure com ferramentas especificadas para OpenAPI

  • Artigo

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

A ferramenta Especificada do OpenAPI melhora sua experiência de chamada de função fornecendo integrações de API padronizadas, automatizadas e escalonáveis que aprimoram os recursos e a eficiência do agente. 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 funcionam juntas, geram código do cliente, criam testes, aplicam padrões de design e muito mais. Atualmente, há suporte para 3 tipos de autenticação com as ferramentas especificadas do OpenAPI 3.0: anonymous, API key, managed identity.

Suporte de uso

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

Pré-requisitos

  1. Verifique se você concluiu os pré-requisitos e as etapas de instalaçã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 usar um nome descritivo para ajudar os modelos a decidirem 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 a seção securitySchemes 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 esquemas, recomendamos manter apenas um deles.

  2. Remova qualquer parâmetro na especificação OpenAPI que exija chave de API, pois a chave de API será armazenada e passada por meio de uma conexão, conforme descrito posteriormente neste artigo.

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

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

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

      Observação

      Se você regenerar a chave de API posteriormente, precisará atualizar a conexão com a nova chave.

      Uma captura de tela da tela de conexões do projeto de IA.

    3. Selecione chaves personalizadas em outros tipos de recurso.

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

    4. Insira 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"
                }
        }
      • value: YOUR_API_KEY
      • Nome da conexão: YOUR_CONNECTION_NAME (Você usará este nome de conexão no código de exemplo abaixo.)
      • Acesso: você pode escolher somente este projeto ou compartilhado com todos os projetos. Apenas verifique se, no código de exemplo abaixo, o projeto para o qual você inseriu a cadeia de conexão tem 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 projeto de IA e a 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: Crie 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 de API, para autenticação, substitua a linha por

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

Sua ID de conexão se parece com /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-alvo seria https://cognitiveservices.azure.com/.

Etapa 3: Crie 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 Especificação OpenAPI 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}")