Compartilhar via

Início Rápido: Criar um novo agente

  • Artigo

O Serviço do Agente de IA do Azure permite que você crie agentes de IA adaptados às suas necessidades por meio de instruções personalizadas e aumentadas por ferramentas avançadas, como interpretador de código e funções personalizadas.

| Documentação de referência | Exemplos | Código-fonte da biblioteca | Pacote (NuGet) |

Pré-requisitos

Configurar o seu projeto de Agente e Hub de IA do Azure

A seção a seguir mostra como configurar os recursos necessários para começar a usar o Serviço de Agente de IA do Azure:

  1. Criando um Hub de IA do Azure para configurar o seu ambiente de aplicativo e recursos do Azure.

  2. A criação de um projeto de IA do Azure em seu Hub cria um ponto de extremidade para o seu aplicativo chamar e configura serviços de aplicativo para acessar recursos em seu locatário.

  3. Conectar um recurso do OpenAI do Azure ou um recurso dos Serviços de IA do Azure

Escolher a Configuração de Agente Básico ou Standard

Configuração Básica: os agentes usam recursos de pesquisa e armazenamento multilocatários totalmente gerenciados pela Microsoft. Você não tem visibilidade ou controle sobre esses recursos subjacentes do Azure.

Configuração Standard: os agentes usam recursos de pesquisa e armazenamento de locatário único de propriedade do cliente. Com essa configuração, você tem controle total e visibilidade sobre esses recursos, mas incorre em custos com base no seu uso.

Descrição e Implantação Automática Diagrama (clique para ampliar)
Implante uma configuração básica de operador que usa Identidade Gerenciada para autenticação. Os recursos para o hub de IA, projeto de IA, conta de armazenamento e Serviços de IA foram criados para você.

A conta dos Serviços de IA está conectada ao seu projeto e hub, e um modelo gpt-4o-mini foi implantado na região eastus. Um cofre de chaves gerenciado pela Microsoft será usado por padrão.

Implantar no Azure 		Um diagrama de arquitetura para a configuração básica do agente.
Implante uma configuração padrão de operador que usa Identidade Gerenciada para autenticação.

Recursos para o hub de IA, o projeto de IA, o cofre de chaves, a conta de armazenamento, os Serviços de IA e a Pesquisa de IA são criados para você.

Os Serviços de IA, a Pesquisa de IA, o cofre de chaves e a conta de armazenamento estão conectados ao seu projeto e hub. Um modelo gpt-4o-mini está implantado na região eastus.

Implantar no Azure 		Um diagrama de arquitetura para a configuração do agente padrão.

[Opcional] Seleção de modelo no modelo de reimplantação automática

Você pode personalizar o modelo usado pelo agente editando os parâmetros de modelo no modelo de reimplantação automática. Para implantar um modelo diferente, você precisa atualizar pelo menos os parâmetros modelName e modelVersion.

Por padrão, o modelo de implantação é configurado com os seguintes valores:

Parâmetro de Modelo Valor Padrão
modelName gpt-4o-mini
modelFormat OpenAI (para o Serviço OpenAI do Azure)
modelVersion 2024-07-18
modelSkuName GlobalStandard
modelLocation eastus

Importante

Não altere o parâmetro modelFormat.

Os modelos dão suporte apenas à implantação de modelos do Serviço OpenAI do Azure. Veja quais modelos do Serviço OpenAI do Azure têm suporte na documentação Suporte a modelos do Serviço de Agente de IA do Azure.

[Opcional] Use seus próprios recursos durante a configuração do agente

Observação

Se você usar um recurso existente de Serviços de IA ou Serviço OpenAI do Azure, nenhum modelo será implantado. Você pode implantar um modelo no recurso após a conclusão da configuração do agente.

Use um recurso existente de Serviços de IA, Serviço OpenAI do Azure, Pesquisa de IA e/ou Armazenamento de Blobs do Azure fornecendo a ID de recurso ARM completa no arquivo de parâmetros:

  • aiServiceAccountResourceId
  • aiSearchServiceResourceId
  • aiStorageAccountResourceId

Se você quiser usar um recurso existente do Serviço OpenAI do Azure, será necessário atualizar os parâmetros aiServiceAccountResourceId e aiServiceKind no arquivo de parâmetros. O parâmetro aiServiceKind deve ser definido como AzureOpenAI.

Para obter mais informações, consulte como usar seus próprios recursos.

Configurar e executar um agente

Componente Descrição
Agente IA personalizada que usa modelos de IA em conjunto com ferramentas.
Ferramenta As ferramentas ajudam a estender a capacidade de um agente de responder de forma confiável e precisa durante a conversa. Como conectar-se a bases de dados de conhecimento definidas pelo usuário para aterrar o modelo ou habilitar a pesquisa na Web para fornecer informações atuais.
Thread Uma sessão de conversa entre um agente e um usuário. Os Threads armazenam Mensagens e manipulam automaticamente o truncamento para ajustar o conteúdo no contexto de um modelo.
Mensagem Uma mensagem criada por um agente ou um usuário. As mensagens podem incluir texto, imagens e outros arquivos. As mensagens são armazenadas como uma lista no Thread.
Executar Ativação de um agente para começar a ser executado com base no conteúdo do Thread. O agente usa a sua configuração e as Mensagens do Thread para executar tarefas chamando modelos e ferramentas. Como parte de uma execução, o agente acrescenta Mensagens ao Thread.
Etapa de Execução Uma lista detalhada das etapas que o agente tomou como parte de uma execução. Um agente pode chamar ferramentas ou criar Mensagens durante a sua execução. Examinar as etapas de execução permite que você entenda como o agente está chegando aos resultados.

Instale o pacote .NET em seu projeto. Por exemplo, se você estiver usando a CLI do .NET, execute o comando a seguir.

dotnet add package Azure.AI.Projects
dotnet add package Azure.Identity

Em seguida, para autenticar suas solicitações de API e executar o programa, use o comando az login para entrar em sua assinatura do Azure.

az login

Use o código a seguir para criar e executar um agente. Para executar este código, você precisará criar uma cadeia de conexão usando informações do seu projeto. Esta cadeia de caracteres está no formato:

<HostName>;<AzureSubscriptionId>;<ResourceGroup>;<ProjectName>

Dica

Você também pode encontrar sua cadeia de conexão na visão geral do seu projeto no portal da Azure AI Foundry, em Detalhes do projeto>Cadeia de conexão do projeto. Uma captura de tela mostrando a cadeia de conexão no portal do Azure AI Foundry.

HostName pode ser encontrado navegando até o seu discovery_url e removendo o entrelinhamento https:// e o /discovery à direita. Para localizar o seu discovery_url, execute este comando da CLI:

az ml workspace show -n {project_name} --resource-group {resource_group_name} --query discovery_url

Por exemplo, a sua cadeia de conexão pode ser semelhante a:

eastus.api.azureml.ms;12345678-abcd-1234-9fc6-62780b3d3e05;my-resource-group;my-project-name

Defina esta cadeia de conexão como uma variável de ambiente chamada PROJECT_CONNECTION_STRING.

// Copyright (c) Microsoft Corporation. All rights reserved.
// Licensed under the MIT License.

#nullable disable

using Azure.Identity;

namespace Azure.AI.Projects.Tests;

public class Sample_Agent
{
    static async Task Main()
    {
        var connectionString = Environment.GetEnvironmentVariable("AZURE_AI_CONNECTION_STRING");

        AgentsClient client = new AgentsClient(connectionString, new DefaultAzureCredential());

        // Step 1: Create an agent
        Response<Agent> agentResponse = await client.CreateAgentAsync(
            model: "gpt-4o-mini",
            name: "My Agent",
            instructions: "You are a helpful agent.",
            tools: new List<ToolDefinition> { new CodeInterpreterToolDefinition() });
        Agent agent = agentResponse.Value;

        // Intermission: agent should now be listed

        Response<PageableList<Agent>> agentListResponse = await client.GetAgentsAsync();

        //// Step 2: Create a thread
        Response<AgentThread> threadResponse = await client.CreateThreadAsync();
        AgentThread thread = threadResponse.Value;

        // Step 3: Add a message to a thread
        Response<ThreadMessage> messageResponse = await client.CreateMessageAsync(
            thread.Id,
            MessageRole.User,
            "I need to solve the equation `3x + 11 = 14`. Can you help me?");
        ThreadMessage message = messageResponse.Value;

        // Intermission: message is now correlated with thread
        // Intermission: listing messages will retrieve the message just added

        Response<PageableList<ThreadMessage>> messagesListResponse = await client.GetMessagesAsync(thread.Id);
        //Assert.That(messagesListResponse.Value.Data[0].Id == message.Id);

        // Step 4: Run the agent
        Response<ThreadRun> runResponse = await client.CreateRunAsync(
            thread.Id,
            agent.Id,
            additionalInstructions: "");
        ThreadRun run = runResponse.Value;

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

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

| Documentação de referência | Exemplos | Código-fonte da biblioteca | Pacote (PyPi) |

Pré-requisitos

Configurar o seu projeto de Agente e Hub de IA do Azure

A seção a seguir mostra como configurar os recursos necessários para começar a usar o Serviço de Agente de IA do Azure:

  1. Criando um Hub de IA do Azure para configurar o seu ambiente de aplicativo e recursos do Azure.

  2. A criação de um projeto de IA do Azure em seu Hub cria um ponto de extremidade para o seu aplicativo chamar e configura serviços de aplicativo para acessar recursos em seu locatário.

  3. Conectar um recurso do OpenAI do Azure ou um recurso dos Serviços de IA do Azure

Escolher a Configuração de Agente Básico ou Standard

Configuração Básica: os agentes usam recursos de pesquisa e armazenamento multilocatários totalmente gerenciados pela Microsoft. Você não tem visibilidade ou controle sobre esses recursos subjacentes do Azure.

Configuração Standard: os agentes usam recursos de pesquisa e armazenamento de locatário único de propriedade do cliente. Com essa configuração, você tem controle total e visibilidade sobre esses recursos, mas incorre em custos com base no seu uso.

Descrição e Implantação Automática Diagrama (clique para ampliar)
Implante uma configuração básica de operador que usa Identidade Gerenciada para autenticação. Os recursos para o hub de IA, projeto de IA, conta de armazenamento e Serviços de IA foram criados para você.

A conta dos Serviços de IA está conectada ao seu projeto e hub, e um modelo gpt-4o-mini foi implantado na região eastus. Um cofre de chaves gerenciado pela Microsoft será usado por padrão.

Implantar no Azure 		Um diagrama de arquitetura para a configuração básica do agente.
Implante uma configuração padrão de operador que usa Identidade Gerenciada para autenticação.

Recursos para o hub de IA, o projeto de IA, o cofre de chaves, a conta de armazenamento, os Serviços de IA e a Pesquisa de IA são criados para você.

Os Serviços de IA, a Pesquisa de IA, o cofre de chaves e a conta de armazenamento estão conectados ao seu projeto e hub. Um modelo gpt-4o-mini está implantado na região eastus.

Implantar no Azure 		Um diagrama de arquitetura para a configuração do agente padrão.

[Opcional] Seleção de modelo no modelo de reimplantação automática

Você pode personalizar o modelo usado pelo agente editando os parâmetros de modelo no modelo de reimplantação automática. Para implantar um modelo diferente, você precisa atualizar pelo menos os parâmetros modelName e modelVersion.

Por padrão, o modelo de implantação é configurado com os seguintes valores:

Parâmetro de Modelo Valor Padrão
modelName gpt-4o-mini
modelFormat OpenAI (para o Serviço OpenAI do Azure)
modelVersion 2024-07-18
modelSkuName GlobalStandard
modelLocation eastus

Importante

Não altere o parâmetro modelFormat.

Os modelos dão suporte apenas à implantação de modelos do Serviço OpenAI do Azure. Veja quais modelos do Serviço OpenAI do Azure têm suporte na documentação Suporte a modelos do Serviço de Agente de IA do Azure.

[Opcional] Use seus próprios recursos durante a configuração do agente

Observação

Se você usar um recurso existente de Serviços de IA ou Serviço OpenAI do Azure, nenhum modelo será implantado. Você pode implantar um modelo no recurso após a conclusão da configuração do agente.

Use um recurso existente de Serviços de IA, Serviço OpenAI do Azure, Pesquisa de IA e/ou Armazenamento de Blobs do Azure fornecendo a ID de recurso ARM completa no arquivo de parâmetros:

  • aiServiceAccountResourceId
  • aiSearchServiceResourceId
  • aiStorageAccountResourceId

Se você quiser usar um recurso existente do Serviço OpenAI do Azure, será necessário atualizar os parâmetros aiServiceAccountResourceId e aiServiceKind no arquivo de parâmetros. O parâmetro aiServiceKind deve ser definido como AzureOpenAI.

Para obter mais informações, consulte como usar seus próprios recursos.

Configurar e executar um agente

Componente Descrição
Agente IA personalizada que usa modelos de IA em conjunto com ferramentas.
Ferramenta As ferramentas ajudam a estender a capacidade de um agente de responder de forma confiável e precisa durante a conversa. Como conectar-se a bases de dados de conhecimento definidas pelo usuário para aterrar o modelo ou habilitar a pesquisa na Web para fornecer informações atuais.
Thread Uma sessão de conversa entre um agente e um usuário. Os Threads armazenam Mensagens e manipulam automaticamente o truncamento para ajustar o conteúdo no contexto de um modelo.
Mensagem Uma mensagem criada por um agente ou um usuário. As mensagens podem incluir texto, imagens e outros arquivos. As mensagens são armazenadas como uma lista no Thread.
Executar Ativação de um agente para começar a ser executado com base no conteúdo do Thread. O agente usa a sua configuração e as Mensagens do Thread para executar tarefas chamando modelos e ferramentas. Como parte de uma execução, o agente acrescenta Mensagens ao Thread.
Etapa de Execução Uma lista detalhada das etapas que o agente tomou como parte de uma execução. Um agente pode chamar ferramentas ou criar Mensagens durante a sua execução. Examinar as etapas de execução permite que você entenda como o agente está chegando aos resultados.

Execute os comandos a seguir para instalar os pacotes do Python.

pip install azure-ai-projects
pip install azure-identity

Em seguida, para autenticar suas solicitações de API e executar o programa, use o comando az login para entrar em sua assinatura do Azure.

az login

Use o código a seguir para criar e executar um agente. Para executar este código, você precisará criar uma cadeia de conexão usando informações do seu projeto. Esta cadeia de caracteres está no formato:

<HostName>;<AzureSubscriptionId>;<ResourceGroup>;<ProjectName>

Dica

Você também pode encontrar sua cadeia de conexão na visão geral do seu projeto no portal da Azure AI Foundry, em Detalhes do projeto>Cadeia de conexão do projeto. Uma captura de tela mostrando a cadeia de conexão no portal do Azure AI Foundry.

HostName pode ser encontrado navegando até o seu discovery_url e removendo o entrelinhamento https:// e o /discovery à direita. Para localizar o seu discovery_url, execute este comando da CLI:

az ml workspace show -n {project_name} --resource-group {resource_group_name} --query discovery_url

Por exemplo, a sua cadeia de conexão pode ser semelhante a:

eastus.api.azureml.ms;12345678-abcd-1234-9fc6-62780b3d3e05;my-resource-group;my-project-name

Defina esta cadeia de conexão como uma variável de ambiente chamada PROJECT_CONNECTION_STRING.

import os
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import CodeInterpreterTool
from azure.identity import DefaultAzureCredential
from typing import Any
from pathlib import Path

# 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>;<ProjectName>"
# HostName can be found by navigating to your discovery_url and removing the leading "https://" and trailing "/discovery"
# To find your discovery_url, run the CLI command: az ml workspace show -n {project_name} --resource-group {resource_group_name} --query discovery_url
# Project Connection example: eastus.api.azureml.ms;12345678-abcd-1234-9fc6-62780b3d3e05;my-resource-group;my-project-name
# 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"]
)

with project_client:
    # Create an instance of the CodeInterpreterTool
    code_interpreter = CodeInterpreterTool()

    # The CodeInterpreterTool needs to be included in creation of the agent
    agent = project_client.agents.create_agent(
        model="gpt-4o-mini",
        name="my-agent",
        instructions="You are helpful agent",
        tools=code_interpreter.definitions,
        tool_resources=code_interpreter.resources,
    )
    print(f"Created agent, agent ID: {agent.id}")

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

    # Create a message
    message = project_client.agents.create_message(
        thread_id=thread.id,
        role="user",
        content="Could you please create a bar chart for the operating profit using the following data and provide the file to me? Company A: $1.2 million, Company B: $2.5 million, Company C: $3.0 million, Company D: $1.8 million",
    )
    print(f"Created message, message ID: {message.id}")

    # Run the agent
    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":
        # Check if you got "Rate limit is exceeded.", then you want to get more quota
        print(f"Run failed: {run.last_error}")

    # Get messages from the thread
    messages = project_client.agents.list_messages(thread_id=thread.id)
    print(f"Messages: {messages}")

    # Get the last message from the sender
    last_msg = messages.get_last_text_message_by_role("assistant")
    if last_msg:
        print(f"Last Message: {last_msg.text.value}")

    # Generate an image file for the bar chart
    for image_content in messages.image_contents:
        print(f"Image File ID: {image_content.image_file.file_id}")
        file_name = f"{image_content.image_file.file_id}_image_file.png"
        project_client.agents.save_file(file_id=image_content.image_file.file_id, file_name=file_name)
        print(f"Saved image file to: {Path.cwd() / file_name}")

    # Print the file path(s) from the messages
    for file_path_annotation in messages.file_path_annotations:
        print(f"File Paths:")
        print(f"Type: {file_path_annotation.type}")
        print(f"Text: {file_path_annotation.text}")
        print(f"File ID: {file_path_annotation.file_path.file_id}")
        print(f"Start Index: {file_path_annotation.start_index}")
        print(f"End Index: {file_path_annotation.end_index}")
        project_client.agents.save_file(file_id=file_path_annotation.file_path.file_id, file_name=Path(file_path_annotation.text).name)

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

| Documentação de referência | Código-fonte da biblioteca | Pacote (PyPi) |

Pré-requisitos

Configurar o seu projeto de Agente e Hub de IA do Azure

A seção a seguir mostra como configurar os recursos necessários para começar a usar o Serviço de Agente de IA do Azure:

  1. Criando um Hub de IA do Azure para configurar o seu ambiente de aplicativo e recursos do Azure.

  2. A criação de um projeto de IA do Azure em seu Hub cria um ponto de extremidade para o seu aplicativo chamar e configura serviços de aplicativo para acessar recursos em seu locatário.

  3. Conectar um recurso do OpenAI do Azure ou um recurso dos Serviços de IA do Azure

Escolher a Configuração de Agente Básico ou Standard

Configuração Básica: os agentes usam recursos de pesquisa e armazenamento multilocatários totalmente gerenciados pela Microsoft. Você não tem visibilidade ou controle sobre esses recursos subjacentes do Azure.

Configuração Standard: os agentes usam recursos de pesquisa e armazenamento de locatário único de propriedade do cliente. Com essa configuração, você tem controle total e visibilidade sobre esses recursos, mas incorre em custos com base no seu uso.

Descrição e Implantação Automática Diagrama (clique para ampliar)
Implante uma configuração básica de operador que usa Identidade Gerenciada para autenticação. Os recursos para o hub de IA, projeto de IA, conta de armazenamento e Serviços de IA foram criados para você.

A conta dos Serviços de IA está conectada ao seu projeto e hub, e um modelo gpt-4o-mini foi implantado na região eastus. Um cofre de chaves gerenciado pela Microsoft será usado por padrão.

Implantar no Azure 		Um diagrama de arquitetura para a configuração básica do agente.
Implante uma configuração padrão de operador que usa Identidade Gerenciada para autenticação.

Recursos para o hub de IA, o projeto de IA, o cofre de chaves, a conta de armazenamento, os Serviços de IA e a Pesquisa de IA são criados para você.

Os Serviços de IA, a Pesquisa de IA, o cofre de chaves e a conta de armazenamento estão conectados ao seu projeto e hub. Um modelo gpt-4o-mini está implantado na região eastus.

Implantar no Azure 		Um diagrama de arquitetura para a configuração do agente padrão.

[Opcional] Seleção de modelo no modelo de reimplantação automática

Você pode personalizar o modelo usado pelo agente editando os parâmetros de modelo no modelo de reimplantação automática. Para implantar um modelo diferente, você precisa atualizar pelo menos os parâmetros modelName e modelVersion.

Por padrão, o modelo de implantação é configurado com os seguintes valores:

Parâmetro de Modelo Valor Padrão
modelName gpt-4o-mini
modelFormat OpenAI (para o Serviço OpenAI do Azure)
modelVersion 2024-07-18
modelSkuName GlobalStandard
modelLocation eastus

Importante

Não altere o parâmetro modelFormat.

Os modelos dão suporte apenas à implantação de modelos do Serviço OpenAI do Azure. Veja quais modelos do Serviço OpenAI do Azure têm suporte na documentação Suporte a modelos do Serviço de Agente de IA do Azure.

[Opcional] Use seus próprios recursos durante a configuração do agente

Observação

Se você usar um recurso existente de Serviços de IA ou Serviço OpenAI do Azure, nenhum modelo será implantado. Você pode implantar um modelo no recurso após a conclusão da configuração do agente.

Use um recurso existente de Serviços de IA, Serviço OpenAI do Azure, Pesquisa de IA e/ou Armazenamento de Blobs do Azure fornecendo a ID de recurso ARM completa no arquivo de parâmetros:

  • aiServiceAccountResourceId
  • aiSearchServiceResourceId
  • aiStorageAccountResourceId

Se você quiser usar um recurso existente do Serviço OpenAI do Azure, será necessário atualizar os parâmetros aiServiceAccountResourceId e aiServiceKind no arquivo de parâmetros. O parâmetro aiServiceKind deve ser definido como AzureOpenAI.

Para obter mais informações, consulte como usar seus próprios recursos.

Configurar e executar um agente

Componente Descrição
Agente IA personalizada que usa modelos de IA em conjunto com ferramentas.
Ferramenta As ferramentas ajudam a estender a capacidade de um agente de responder de forma confiável e precisa durante a conversa. Como conectar-se a bases de dados de conhecimento definidas pelo usuário para aterrar o modelo ou habilitar a pesquisa na Web para fornecer informações atuais.
Thread Uma sessão de conversa entre um agente e um usuário. Os Threads armazenam Mensagens e manipulam automaticamente o truncamento para ajustar o conteúdo no contexto de um modelo.
Mensagem Uma mensagem criada por um agente ou um usuário. As mensagens podem incluir texto, imagens e outros arquivos. As mensagens são armazenadas como uma lista no Thread.
Executar Ativação de um agente para começar a ser executado com base no conteúdo do Thread. O agente usa a sua configuração e as Mensagens do Thread para executar tarefas chamando modelos e ferramentas. Como parte de uma execução, o agente acrescenta Mensagens ao Thread.
Etapa de Execução Uma lista detalhada das etapas que o agente tomou como parte de uma execução. Um agente pode chamar ferramentas ou criar Mensagens durante a sua execução. Examinar as etapas de execução permite que você entenda como o agente está chegando aos resultados.

Execute os comandos a seguir para instalar os pacotes do Python.

pip install azure-ai-projects
pip install azure-identity
pip install openai

Em seguida, para autenticar suas solicitações de API e executar o programa, use o comando az login para entrar em sua assinatura do Azure.

az login

Use o código a seguir para criar e executar um agente. Para executar este código, você precisará criar uma cadeia de conexão usando informações do seu projeto. Esta cadeia de caracteres está no formato:

<HostName>;<AzureSubscriptionId>;<ResourceGroup>;<ProjectName>

Dica

Você também pode encontrar sua cadeia de conexão na visão geral do seu projeto no portal da Azure AI Foundry, em Detalhes do projeto>Cadeia de conexão do projeto. Uma captura de tela mostrando a cadeia de conexão no portal do Azure AI Foundry.

HostName pode ser encontrado navegando até o seu discovery_url e removendo o entrelinhamento https:// e o /discovery à direita. Para localizar o seu discovery_url, execute este comando da CLI:

az ml workspace show -n {project_name} --resource-group {resource_group_name} --query discovery_url

Por exemplo, a sua cadeia de conexão pode ser semelhante a:

eastus.api.azureml.ms;12345678-abcd-1234-9fc6-62780b3d3e05;my-resource-group;my-project-name

Defina esta cadeia de conexão como uma variável de ambiente chamada PROJECT_CONNECTION_STRING.

import os, time
from azure.ai.projects import AIProjectClient
from azure.identity import DefaultAzureCredential
from openai import AzureOpenAI


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

    # Explicit type hinting for IntelliSense
    client: AzureOpenAI = project_client.inference.get_azure_openai_client(
        # The latest API version is 2024-10-01-preview
        api_version = os.environ.get("AZURE_OPENAI_API_VERSION"),
    )

    with client:
        agent = client.beta.assistants.create(
            model="gpt-4o-mini", name="my-agent", instructions="You are a helpful agent"
        )
        print(f"Created agent, agent ID: {agent.id}")

        thread = client.beta.threads.create()
        print(f"Created thread, thread ID: {thread.id}")

        message = client.beta.threads.messages.create(thread_id=thread.id, role="user", content="Hello, tell me a joke")
        print(f"Created message, message ID: {message.id}")

        run = client.beta.threads.runs.create(thread_id=thread.id, assistant_id=agent.id)

        # Poll the run while run status is queued or in progress
        while run.status in ["queued", "in_progress", "requires_action"]:
            time.sleep(1)  # Wait for a second
            run = client.beta.threads.runs.retrieve(thread_id=thread.id, run_id=run.id)
            print(f"Run status: {run.status}")

        client.beta.assistants.delete(agent.id)
        print("Deleted agent")

        messages = client.beta.threads.messages.list(thread_id=thread.id)
        print(f"Messages: {messages}")

| Documentação de referência | Exemplos | Código-fonte da biblioteca | Pacote (npm) |

Pré-requisitos

Configurar o seu projeto de Agente e Hub de IA do Azure

A seção a seguir mostra como configurar os recursos necessários para começar a usar o Serviço de Agente de IA do Azure:

  1. Criando um Hub de IA do Azure para configurar o seu ambiente de aplicativo e recursos do Azure.

  2. A criação de um projeto de IA do Azure em seu Hub cria um ponto de extremidade para o seu aplicativo chamar e configura serviços de aplicativo para acessar recursos em seu locatário.

  3. Conectar um recurso do OpenAI do Azure ou um recurso dos Serviços de IA do Azure

Escolher a Configuração de Agente Básico ou Standard

Configuração Básica: os agentes usam recursos de pesquisa e armazenamento multilocatários totalmente gerenciados pela Microsoft. Você não tem visibilidade ou controle sobre esses recursos subjacentes do Azure.

Configuração Standard: os agentes usam recursos de pesquisa e armazenamento de locatário único de propriedade do cliente. Com essa configuração, você tem controle total e visibilidade sobre esses recursos, mas incorre em custos com base no seu uso.

Descrição e Implantação Automática Diagrama (clique para ampliar)
Implante uma configuração básica de operador que usa Identidade Gerenciada para autenticação. Os recursos para o hub de IA, projeto de IA, conta de armazenamento e Serviços de IA foram criados para você.

A conta dos Serviços de IA está conectada ao seu projeto e hub, e um modelo gpt-4o-mini foi implantado na região eastus. Um cofre de chaves gerenciado pela Microsoft será usado por padrão.

Implantar no Azure 		Um diagrama de arquitetura para a configuração básica do agente.
Implante uma configuração padrão de operador que usa Identidade Gerenciada para autenticação.

Recursos para o hub de IA, o projeto de IA, o cofre de chaves, a conta de armazenamento, os Serviços de IA e a Pesquisa de IA são criados para você.

Os Serviços de IA, a Pesquisa de IA, o cofre de chaves e a conta de armazenamento estão conectados ao seu projeto e hub. Um modelo gpt-4o-mini está implantado na região eastus.

Implantar no Azure 		Um diagrama de arquitetura para a configuração do agente padrão.

[Opcional] Seleção de modelo no modelo de reimplantação automática

Você pode personalizar o modelo usado pelo agente editando os parâmetros de modelo no modelo de reimplantação automática. Para implantar um modelo diferente, você precisa atualizar pelo menos os parâmetros modelName e modelVersion.

Por padrão, o modelo de implantação é configurado com os seguintes valores:

Parâmetro de Modelo Valor Padrão
modelName gpt-4o-mini
modelFormat OpenAI (para o Serviço OpenAI do Azure)
modelVersion 2024-07-18
modelSkuName GlobalStandard
modelLocation eastus

Importante

Não altere o parâmetro modelFormat.

Os modelos dão suporte apenas à implantação de modelos do Serviço OpenAI do Azure. Veja quais modelos do Serviço OpenAI do Azure têm suporte na documentação Suporte a modelos do Serviço de Agente de IA do Azure.

[Opcional] Use seus próprios recursos durante a configuração do agente

Observação

Se você usar um recurso existente de Serviços de IA ou Serviço OpenAI do Azure, nenhum modelo será implantado. Você pode implantar um modelo no recurso após a conclusão da configuração do agente.

Use um recurso existente de Serviços de IA, Serviço OpenAI do Azure, Pesquisa de IA e/ou Armazenamento de Blobs do Azure fornecendo a ID de recurso ARM completa no arquivo de parâmetros:

  • aiServiceAccountResourceId
  • aiSearchServiceResourceId
  • aiStorageAccountResourceId

Se você quiser usar um recurso existente do Serviço OpenAI do Azure, será necessário atualizar os parâmetros aiServiceAccountResourceId e aiServiceKind no arquivo de parâmetros. O parâmetro aiServiceKind deve ser definido como AzureOpenAI.

Para obter mais informações, consulte como usar seus próprios recursos.

Configurar e executar um agente

Componente Descrição
Agente IA personalizada que usa modelos de IA em conjunto com ferramentas.
Ferramenta As ferramentas ajudam a estender a capacidade de um agente de responder de forma confiável e precisa durante a conversa. Como conectar-se a bases de dados de conhecimento definidas pelo usuário para aterrar o modelo ou habilitar a pesquisa na Web para fornecer informações atuais.
Thread Uma sessão de conversa entre um agente e um usuário. Os Threads armazenam Mensagens e manipulam automaticamente o truncamento para ajustar o conteúdo no contexto de um modelo.
Mensagem Uma mensagem criada por um agente ou um usuário. As mensagens podem incluir texto, imagens e outros arquivos. As mensagens são armazenadas como uma lista no Thread.
Executar Ativação de um agente para começar a ser executado com base no conteúdo do Thread. O agente usa a sua configuração e as Mensagens do Thread para executar tarefas chamando modelos e ferramentas. Como parte de uma execução, o agente acrescenta Mensagens ao Thread.
Etapa de Execução Uma lista detalhada das etapas que o agente tomou como parte de uma execução. Um agente pode chamar ferramentas ou criar Mensagens durante a sua execução. Examinar as etapas de execução permite que você entenda como o agente está chegando aos resultados.

Execute os comandos a seguir para instalar os pacotes npm.

npm install @azure/ai-projects
npm install @azure/identity

Em seguida, para autenticar suas solicitações de API e executar o programa, use o comando az login para entrar em sua assinatura do Azure.

az login

Use o código a seguir para criar e executar um agente. Para executar este código, você precisará criar uma cadeia de conexão usando informações do seu projeto. Esta cadeia de caracteres está no formato:

<HostName>;<AzureSubscriptionId>;<ResourceGroup>;<ProjectName>

Dica

Você também pode encontrar sua cadeia de conexão na visão geral do seu projeto no portal da Azure AI Foundry, em Detalhes do projeto>Cadeia de conexão do projeto. Uma captura de tela mostrando a cadeia de conexão no portal do Azure AI Foundry.

HostName pode ser encontrado navegando até o seu discovery_url e removendo o entrelinhamento https:// e o /discovery à direita. Para localizar o seu discovery_url, execute este comando da CLI:

az ml workspace show -n {project_name} --resource-group {resource_group_name} --query discovery_url

Por exemplo, a sua cadeia de conexão pode ser semelhante a:

eastus.api.azureml.ms;12345678-abcd-1234-9fc6-62780b3d3e05;my-resource-group;my-project-name

Defina esta cadeia de conexão como uma variável de ambiente chamada PROJECT_CONNECTION_STRING.

// index.js

import {
  AIProjectsClient,
  DoneEvent,
  ErrorEvent,
  isOutputOfType,
  MessageStreamEvent,
  RunStreamEvent,
  ToolUtility,
} from "@azure/ai-projects";
import { DefaultAzureCredential } from "@azure/identity";

const connectionString =
  process.env["AZURE_AI_PROJECTS_CONNECTION_STRING"] || "<project connection string>";

if (!connectionString) {
  throw new Error("AZURE_AI_PROJECTS_CONNECTION_STRING must be set in the environment variables");
}

export async function main() {
  const client = AIProjectsClient.fromConnectionString(
    connectionString || "",
    new DefaultAzureCredential(),
  );

  // Step 1 code interpreter tool
  const codeInterpreterTool = ToolUtility.createCodeInterpreterTool();

  // Step 2 an agent
  const agent = await client.agents.createAgent("gpt-4o-mini", {
    name: "my-agent",
    instructions: "You are a helpful agent",
    tools: [codeInterpreterTool.definition],
    toolResources: codeInterpreterTool.resources,
  });

  // Step 3 a thread
  const thread = await client.agents.createThread();

  // Step 4 a message to thread
  await client.agents.createMessage(
    thread.id, {
    role: "user",
    content: "I need to solve the equation `3x + 11 = 14`. Can you help me?",
  });

  // Intermission is now correlated with thread
  // Intermission messages will retrieve the message just added

  // Step 5 the agent
  const streamEventMessages = await client.agents.createRun(thread.id, agent.id).stream();

  for await (const eventMessage of streamEventMessages) {
    switch (eventMessage.event) {
      case RunStreamEvent.ThreadRunCreated:
        break;
      case MessageStreamEvent.ThreadMessageDelta:
        {
          const messageDelta = eventMessage.data;
          messageDelta.delta.content.forEach((contentPart) => {
            if (contentPart.type === "text") {
              const textContent = contentPart;
              const textValue = textContent.text?.value || "No text";
            }
          });
        }
        break;

      case RunStreamEvent.ThreadRunCompleted:
        break;
      case ErrorEvent.Error:
        console.log(`An error occurred. Data ${eventMessage.data}`);
        break;
      case DoneEvent.Done:
        break;
    }
  }

  // 6. Print the messages from the agent
  const messages = await client.agents.listMessages(thread.id);

  // Messages iterate from oldest to newest
  // messages[0] is the most recent
  for (let i = messages.data.length - 1; i >= 0; i--) {
    const m = messages.data[i];
    if (isOutputOfType(m.content[0], "text")) {
      const textContent = m.content[0];
      console.log(`${textContent.text.value}`);
      console.log(`---------------------------------`);
    }
  }

  // 7. Delete the agent once done
  await client.agents.deleteAgent(agent.id);
}

main().catch((err) => {
  console.error("The sample encountered an error:", err);
});

A saída contém o prompt e as respostas.

I need to solve the equation `3x + 11 = 14`. Can you help me?
---------------------------------
Sure! I can help you solve the equation \(3x + 11 = 14\).

To solve this equation, we need to isolate the variable \(x\). Let's go ahead and solve it.
---------------------------------
The solution to the equation \(3x + 11 = 14\) is \(x = 1\). 

Therefore, the value of \(x\) that satisfies the equation is 1. 

Let me know if you need help with anything else!
---------------------------------

| Documentação de referência | Exemplos | Código-fonte da biblioteca | Pacote (npm) |

Pré-requisitos

Configurar o seu projeto de Agente e Hub de IA do Azure

A seção a seguir mostra como configurar os recursos necessários para começar a usar o Serviço de Agente de IA do Azure:

  1. Criando um Hub de IA do Azure para configurar o seu ambiente de aplicativo e recursos do Azure.

  2. A criação de um projeto de IA do Azure em seu Hub cria um ponto de extremidade para o seu aplicativo chamar e configura serviços de aplicativo para acessar recursos em seu locatário.

  3. Conectar um recurso do OpenAI do Azure ou um recurso dos Serviços de IA do Azure

Escolher a Configuração de Agente Básico ou Standard

Configuração Básica: os agentes usam recursos de pesquisa e armazenamento multilocatários totalmente gerenciados pela Microsoft. Você não tem visibilidade ou controle sobre esses recursos subjacentes do Azure.

Configuração Standard: os agentes usam recursos de pesquisa e armazenamento de locatário único de propriedade do cliente. Com essa configuração, você tem controle total e visibilidade sobre esses recursos, mas incorre em custos com base no seu uso.

Descrição e Implantação Automática Diagrama (clique para ampliar)
Implante uma configuração básica de operador que usa Identidade Gerenciada para autenticação. Os recursos para o hub de IA, projeto de IA, conta de armazenamento e Serviços de IA foram criados para você.

A conta dos Serviços de IA está conectada ao seu projeto e hub, e um modelo gpt-4o-mini foi implantado na região eastus. Um cofre de chaves gerenciado pela Microsoft será usado por padrão.

Implantar no Azure 		Um diagrama de arquitetura para a configuração básica do agente.
Implante uma configuração padrão de operador que usa Identidade Gerenciada para autenticação.

Recursos para o hub de IA, o projeto de IA, o cofre de chaves, a conta de armazenamento, os Serviços de IA e a Pesquisa de IA são criados para você.

Os Serviços de IA, a Pesquisa de IA, o cofre de chaves e a conta de armazenamento estão conectados ao seu projeto e hub. Um modelo gpt-4o-mini está implantado na região eastus.

Implantar no Azure 		Um diagrama de arquitetura para a configuração do agente padrão.

[Opcional] Seleção de modelo no modelo de reimplantação automática

Você pode personalizar o modelo usado pelo agente editando os parâmetros de modelo no modelo de reimplantação automática. Para implantar um modelo diferente, você precisa atualizar pelo menos os parâmetros modelName e modelVersion.

Por padrão, o modelo de implantação é configurado com os seguintes valores:

Parâmetro de Modelo Valor Padrão
modelName gpt-4o-mini
modelFormat OpenAI (para o Serviço OpenAI do Azure)
modelVersion 2024-07-18
modelSkuName GlobalStandard
modelLocation eastus

Importante

Não altere o parâmetro modelFormat.

Os modelos dão suporte apenas à implantação de modelos do Serviço OpenAI do Azure. Veja quais modelos do Serviço OpenAI do Azure têm suporte na documentação Suporte a modelos do Serviço de Agente de IA do Azure.

[Opcional] Use seus próprios recursos durante a configuração do agente

Observação

Se você usar um recurso existente de Serviços de IA ou Serviço OpenAI do Azure, nenhum modelo será implantado. Você pode implantar um modelo no recurso após a conclusão da configuração do agente.

Use um recurso existente de Serviços de IA, Serviço OpenAI do Azure, Pesquisa de IA e/ou Armazenamento de Blobs do Azure fornecendo a ID de recurso ARM completa no arquivo de parâmetros:

  • aiServiceAccountResourceId
  • aiSearchServiceResourceId
  • aiStorageAccountResourceId

Se você quiser usar um recurso existente do Serviço OpenAI do Azure, será necessário atualizar os parâmetros aiServiceAccountResourceId e aiServiceKind no arquivo de parâmetros. O parâmetro aiServiceKind deve ser definido como AzureOpenAI.

Para obter mais informações, consulte como usar seus próprios recursos.

Configurar e executar um agente

Componente Descrição
Agente IA personalizada que usa modelos de IA em conjunto com ferramentas.
Ferramenta As ferramentas ajudam a estender a capacidade de um agente de responder de forma confiável e precisa durante a conversa. Como conectar-se a bases de dados de conhecimento definidas pelo usuário para aterrar o modelo ou habilitar a pesquisa na Web para fornecer informações atuais.
Thread Uma sessão de conversa entre um agente e um usuário. Os Threads armazenam Mensagens e manipulam automaticamente o truncamento para ajustar o conteúdo no contexto de um modelo.
Mensagem Uma mensagem criada por um agente ou um usuário. As mensagens podem incluir texto, imagens e outros arquivos. As mensagens são armazenadas como uma lista no Thread.
Executar Ativação de um agente para começar a ser executado com base no conteúdo do Thread. O agente usa a sua configuração e as Mensagens do Thread para executar tarefas chamando modelos e ferramentas. Como parte de uma execução, o agente acrescenta Mensagens ao Thread.
Etapa de Execução Uma lista detalhada das etapas que o agente tomou como parte de uma execução. Um agente pode chamar ferramentas ou criar Mensagens durante a sua execução. Examinar as etapas de execução permite que você entenda como o agente está chegando aos resultados.

Execute os comandos a seguir para instalar os pacotes npm.

npm install @azure/ai-projects
npm install @azure/identity

Em seguida, para autenticar suas solicitações de API e executar o programa, use o comando az login para entrar em sua assinatura do Azure.

az login

Use o código a seguir para criar e executar um agente. Para executar este código, você precisará criar uma cadeia de conexão usando informações do seu projeto. Esta cadeia de caracteres está no formato:

<HostName>;<AzureSubscriptionId>;<ResourceGroup>;<ProjectName>

Dica

Você também pode encontrar sua cadeia de conexão na visão geral do seu projeto no portal da Azure AI Foundry, em Detalhes do projeto>Cadeia de conexão do projeto. Uma captura de tela mostrando a cadeia de conexão no portal do Azure AI Foundry.

HostName pode ser encontrado navegando até o seu discovery_url e removendo o entrelinhamento https:// e o /discovery à direita. Para localizar o seu discovery_url, execute este comando da CLI:

az ml workspace show -n {project_name} --resource-group {resource_group_name} --query discovery_url

Por exemplo, a sua cadeia de conexão pode ser semelhante a:

eastus.api.azureml.ms;12345678-abcd-1234-9fc6-62780b3d3e05;my-resource-group;my-project-name

Defina esta cadeia de conexão como uma variável de ambiente chamada PROJECT_CONNECTION_STRING.

// index.ts

import type {
  MessageDeltaChunk,
  MessageDeltaTextContent,
  MessageTextContentOutput,
} from "@azure/ai-projects";
import {
  AIProjectsClient,
  DoneEvent,
  ErrorEvent,
  isOutputOfType,
  MessageStreamEvent,
  RunStreamEvent,
  ToolUtility,
} from "@azure/ai-projects";
import { DefaultAzureCredential } from "@azure/identity";

const connectionString =
  process.env["AZURE_AI_PROJECTS_CONNECTION_STRING"] || "<project connection string>";

if (!connectionString) {
  throw new Error("AZURE_AI_PROJECTS_CONNECTION_STRING must be set in the environment variables");
}

export async function main(): Promise<void> {
  const client = AIProjectsClient.fromConnectionString(
    connectionString || "",
    new DefaultAzureCredential(),
  );

  // Step 1: Create code interpreter tool
  const codeInterpreterTool = ToolUtility.createCodeInterpreterTool();

  // Step 2: Create an agent
  const agent = await client.agents.createAgent("gpt-4o-mini", {
    name: "my-agent",
    instructions: "You are a helpful agent",
    tools: [codeInterpreterTool.definition],
    toolResources: codeInterpreterTool.resources,
  });

  // Step 3: Create a thread
  const thread = await client.agents.createThread();

  // Step 4: Add a message to thread
  await client.agents.createMessage(
    thread.id, {
    role: "user",
    content: "I need to solve the equation `3x + 11 = 14`. Can you help me?",
  });

  // Intermission: message is now correlated with thread
  // Intermission: listing messages will retrieve the message just added

  // Step 5: Run the agent
  const streamEventMessages = await client.agents.createRun(thread.id, agent.id).stream();

  for await (const eventMessage of streamEventMessages) {
    switch (eventMessage.event) {
      case RunStreamEvent.ThreadRunCreated:
        break;
      case MessageStreamEvent.ThreadMessageDelta:
        {
          const messageDelta = eventMessage.data as MessageDeltaChunk;
          messageDelta.delta.content.forEach((contentPart) => {
            if (contentPart.type === "text") {
              const textContent = contentPart as MessageDeltaTextContent;
              const textValue = textContent.text?.value || "No text";
            }
          });
        }
        break;

      case RunStreamEvent.ThreadRunCompleted:
        break;
      case ErrorEvent.Error:
        console.log(`An error occurred. Data ${eventMessage.data}`);
        break;
      case DoneEvent.Done:
        break;
    }
  }

  // 6. Print the messages from the agent
  const messages = await client.agents.listMessages(thread.id);

  // Messages iterate from oldest to newest
  // messages[0] is the most recent
  for (let i = messages.data.length - 1; i >= 0; i--) {
    const m = messages.data[i];
    if (isOutputOfType<MessageTextContentOutput>(m.content[0], "text")) {
      const textContent = m.content[0] as MessageTextContentOutput;
      console.log(`${textContent.text.value}`);
      console.log(`---------------------------------`);
    }
  }

  // 7. Delete the agent once done
  await client.agents.deleteAgent(agent.id);
}

main().catch((err) => {
  console.error("The sample encountered an error:", err);
});

A saída contém o prompt e as respostas.

I need to solve the equation `3x + 11 = 14`. Can you help me?
---------------------------------
Sure! I can help you solve the equation \(3x + 11 = 14\).

To solve this equation, we need to isolate the variable \(x\). Let's go ahead and solve it.
---------------------------------
The solution to the equation \(3x + 11 = 14\) is \(x = 1\). 

Therefore, the value of \(x\) that satisfies the equation is 1. 

Let me know if you need help with anything else!
---------------------------------