Freigeben über

Schnellstart: Erstellen eines neuen Agents

  • Artikel

Mit dem Azure KI-Agent-Dienst können Sie KI-Agents erstellen, die durch benutzerdefinierte Anweisungen auf Ihre Anforderungen zugeschnitten sind und durch fortschrittliche Tools wie Code-Interpreter und benutzerdefinierte Funktionen ergänzt werden.

| Referenzdokumentation | Beispiele | Quellcode der Bibliothek | Paket (NuGet) |

Voraussetzungen

RBAC-Rollen

Stellen Sie sicher, dass sowohl Entwickler als auch Endbenutzer über die folgenden Berechtigungen verfügen:

  • Microsoft.MachineLearningServices/workspaces/agents/read
  • Microsoft.MachineLearningServices/workspaces/agents/action
  • Microsoft.MachineLearningServices/workspaces/agents/delete

Wenn Sie benutzerdefinierte Berechtigungen erstellen möchten, stellen Sie sicher, dass sie folgendes haben:

  • agents/*/read
  • agents/*/action
  • agents/*/delete

Einrichten Ihres Azure KI-Hubs und Agent-Projekts

Im folgenden Abschnitt wird gezeigt, wie Sie die erforderlichen Ressourcen für die ersten Schritte mit dem Azure KI-Agent-Dienst einrichten:

  1. Erstellen eines Azure KI-Hubs zum Einrichten Ihrer App-Umgebung und Azure-Ressourcen.

  2. Durch das Erstellen eines Azure KI-Projekts unter Ihrem Hub wird ein Endpunkt zum Aufrufen durch Ihre App erstellt. Außerdem werden die App-Dienste für den Zugriff auf Ressourcen in Ihrem Mandanten eingerichtet.

  3. Verbinden einer Azure OpenAI-Ressource oder einer Azure KI Services-Ressource

Auswählen des Basic- oder Standard-Agent-Setups

Basic-Setup: Agents verwenden mehrinstanzenfähige Such- und Speicherressourcen, die vollständig von Microsoft verwaltet werden. Sie haben keine Sichtbarkeit oder Kontrolle über diese zugrunde liegenden Azure-Ressourcen.

Standardsetup: Agents verwenden kundeneigene Such- und Speicherressourcen mit einem Mandanten. Mit diesem Setup haben Sie die volle Kontrolle über diese Ressourcen, aber es fallen Kosten basierend auf Ihrer Nutzung an.

Beschreibung und automatische Bereitstellung Diagramm (zum Zoomen klicken)
Stellen Sie ein grundlegendes Agent-Setup bereit, das die verwaltete Identität für die Authentifizierung verwendet. Ressourcen für den KI-Hub, das KI-Projekt, das Speicherkonto und für KI-Dienste werden für Sie erstellt.

Das KI Services-Konto ist mit Ihrem Projekt und Hub verbunden, und es wird ein gpt-4o-mini-Modell in der Region „USA, Osten“ bereitgestellt. Standardmäßig wird ein von Microsoft verwalteter Schlüsseltresor verwendet.

Bereitstellung in Azure		 Ein Architekturdiagramm für das Basic-Setup des Agents.
Stellen Sie ein Agent-Standardsetup bereit, das die verwaltete Identität für die Authentifizierung verwendet.

Ressourcen für den KI-Hub, das KI-Projekt, den Schlüsseltresor, das Speicherkonto, KI-Dienste und KI-Suche werden für Sie erstellt.

Die KI-Dienste, die KI-Suche, der Schlüsseltresor und das Speicherkonto sind mit Ihrem Projekt und Ihrem Hub verbunden. Ein gpt-4o-mini-Modell wird in der Region „USA, Osten“ bereitgestellt.

Bereitstellung in Azure		 Ein Architekturdiagramm für das Standard-Setup des Agents.

[Optional] Modellauswahl in der Vorlage für die automatische Bereitstellung

Sie können das vom Agent verwendete Modell anpassen, indem Sie die Modellparameter in der Vorlage für die automatische Bereitstellung bearbeiten. Um ein anderes Modell bereitzustellen, müssen Sie mindestens die Parameter modelName und modelVersion aktualisieren.

Standardmäßig ist die Bereitstellungsvorlage mit den folgenden Werten konfiguriert:

Modellparameter Standardwert
modelName gpt-4o-mini
modelFormat OpenAI (für Azure OpenAI)
modelVersion 2024-07-18
modelSkuName GlobalStandard
modelLocation eastus

Wichtig

Ändern Sie den Parameter „modelFormat“ nicht.

Die Vorlagen unterstützen nur die Bereitstellung von Azure OpenAI-Modellen. Informationen zu den unterstützten Azure OpenAI-Modellen finden Sie in der Dokumentation zur Modellunterstützung für den Azure KI-Agent-Dienst.

[Optional] Verwenden Ihrer eigenen Ressourcen während der Agenteinrichtung

Hinweis

Wenn Sie eine vorhandene Ressource von KI Services oder Azure OpenAI verwenden, wird kein Modell bereitgestellt. Sie können ein Modell nach Abschluss des Agent-Setups in der Ressource bereitstellen.

Verwenden Sie eine vorhandene Ressource von KI Services, Azure OpenAI, KI Suche und/oder Azure Blob Storage, indem Sie die vollständige ARM-Ressourcen-ID in der Parameterdatei angeben:

  • aiServiceAccountResourceId
  • aiSearchServiceResourceId
  • aiStorageAccountResourceId

Wenn Sie eine vorhandene Azure OpenAI-Ressource verwenden möchten, müssen Sie die Parameter aiServiceAccountResourceId und aiServiceKind in der Parameterdatei aktualisieren. Der aiServiceKind-Parameter sollte auf AzureOpenAI festgelegt werden.

Weitere Informationen finden Sie unter Verwenden Ihrer eigenen Ressourcen.

Konfigurieren und Ausführen eines Agents

Komponente Beschreibung
Agent Benutzerdefinierte KI, die KI-Modelle in Verbindung mit Tools verwendet.
Tool Tools helfen, die Fähigkeit eines Agenten zu erweitern, während der Unterhaltung zuverlässig und präzise zu reagieren. Dazu gehören z. B. das Herstellen einer Verbindung mit benutzerdefinierten Wissensbasen, um das Modell zu grounden, oder das Aktivieren der Websuche, um aktuelle Informationen bereitzustellen.
Thread Eine Unterhaltungssitzung zwischen einem Agent und einem Benutzer. Threads speichern Nachrichten und behandeln automatisch das Abschneiden, um Inhalte in den Kontext eines Modells einzupassen.
Nachricht Eine Nachricht, die von einem Agent oder von einem Benutzer erstellt wurde. Nachrichten können Text, Bilder und andere Dateien enthalten. Nachrichten werden als Liste im Thread gespeichert.
Ausführung Aktivierung eines Agents, der basierend auf dem Inhalt des Threads mit der Ausführung beginnt. Der Agent verwendet seine Konfiguration und die Nachrichten des Threads, um Aufgaben durch Aufrufen von Modellen und Tools auszuführen. Als Teil einer Ausführung fügt der Agent Nachrichten an den Thread an.
Ausführungsschritt Eine detaillierte Liste der Schritte, die der Agent als Teil einer Ausführung ausgeführt hat. Ein Agent kann während seiner Ausführung Tools aufrufen oder Nachrichten erstellen. Wenn Sie die Ausführungsschritte untersuchen, können Sie verstehen, wie der Agent zu seinen Ergebnissen gelangt.

Installieren Sie das folgende .NET-Paket in Ihrem Projekt. Wenn Sie z. B. die .NET-CLI verwenden, führen Sie den folgenden Befehl aus.

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

Verwenden Sie den folgenden Code, um einen Agent zu erstellen und auszuführen. Zum Ausführen dieses Codes müssen Sie eine Verbindungszeichenfolge mithilfe von Informationen aus Ihrem Projekt erstellen. Das Format dieser Zeichenfolge lautet:

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

Tipp

Sie finden Ihre Verbindungszeichenfolge auch in der Übersicht für Ihr Projekt im Azure KI Foundry-Portal unter Projektdetails>Projektverbindungszeichenfolge. Screenshot der Verbindungszeichenfolge im Azure KI Foundry-Portal.

HostName finden Sie, indem Sie zu Ihrer discovery_url navigieren und das führende https:// und nachfolgende /discovery entfernen. Führen Sie den folgenden CLI-Befehl aus, um discovery_url zu finden:

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

Die Verbindungszeichenfolge könnte beispielsweise wie folgt aussehen:

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

Legen Sie diese Verbindungszeichenfolge als Umgebungsvariable namens PROJECT_CONNECTION_STRING fest.

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

| Referenzdokumentation | Beispiele | Quellcode der Bibliothek | Paket (PyPi) |

Voraussetzungen

RBAC-Rollen

Stellen Sie sicher, dass sowohl Entwickler als auch Endbenutzer über die folgenden Berechtigungen verfügen:

  • Microsoft.MachineLearningServices/workspaces/agents/read
  • Microsoft.MachineLearningServices/workspaces/agents/action
  • Microsoft.MachineLearningServices/workspaces/agents/delete

Wenn Sie benutzerdefinierte Berechtigungen erstellen möchten, stellen Sie sicher, dass sie folgendes haben:

  • agents/*/read
  • agents/*/action
  • agents/*/delete

Einrichten Ihres Azure KI-Hubs und Agent-Projekts

Im folgenden Abschnitt wird gezeigt, wie Sie die erforderlichen Ressourcen für die ersten Schritte mit dem Azure KI-Agent-Dienst einrichten:

  1. Erstellen eines Azure KI-Hubs zum Einrichten Ihrer App-Umgebung und Azure-Ressourcen.

  2. Durch das Erstellen eines Azure KI-Projekts unter Ihrem Hub wird ein Endpunkt zum Aufrufen durch Ihre App erstellt. Außerdem werden die App-Dienste für den Zugriff auf Ressourcen in Ihrem Mandanten eingerichtet.

  3. Verbinden einer Azure OpenAI-Ressource oder einer Azure KI Services-Ressource

Auswählen des Basic- oder Standard-Agent-Setups

Basic-Setup: Agents verwenden mehrinstanzenfähige Such- und Speicherressourcen, die vollständig von Microsoft verwaltet werden. Sie haben keine Sichtbarkeit oder Kontrolle über diese zugrunde liegenden Azure-Ressourcen.

Standardsetup: Agents verwenden kundeneigene Such- und Speicherressourcen mit einem Mandanten. Mit diesem Setup haben Sie die volle Kontrolle über diese Ressourcen, aber es fallen Kosten basierend auf Ihrer Nutzung an.

Beschreibung und automatische Bereitstellung Diagramm (zum Zoomen klicken)
Stellen Sie ein grundlegendes Agent-Setup bereit, das die verwaltete Identität für die Authentifizierung verwendet. Ressourcen für den KI-Hub, das KI-Projekt, das Speicherkonto und für KI-Dienste werden für Sie erstellt.

Das KI Services-Konto ist mit Ihrem Projekt und Hub verbunden, und es wird ein gpt-4o-mini-Modell in der Region „USA, Osten“ bereitgestellt. Standardmäßig wird ein von Microsoft verwalteter Schlüsseltresor verwendet.

Bereitstellung in Azure		 Ein Architekturdiagramm für das Basic-Setup des Agents.
Stellen Sie ein Agent-Standardsetup bereit, das die verwaltete Identität für die Authentifizierung verwendet.

Ressourcen für den KI-Hub, das KI-Projekt, den Schlüsseltresor, das Speicherkonto, KI-Dienste und KI-Suche werden für Sie erstellt.

Die KI-Dienste, die KI-Suche, der Schlüsseltresor und das Speicherkonto sind mit Ihrem Projekt und Ihrem Hub verbunden. Ein gpt-4o-mini-Modell wird in der Region „USA, Osten“ bereitgestellt.

Bereitstellung in Azure		 Ein Architekturdiagramm für das Standard-Setup des Agents.

[Optional] Modellauswahl in der Vorlage für die automatische Bereitstellung

Sie können das vom Agent verwendete Modell anpassen, indem Sie die Modellparameter in der Vorlage für die automatische Bereitstellung bearbeiten. Um ein anderes Modell bereitzustellen, müssen Sie mindestens die Parameter modelName und modelVersion aktualisieren.

Standardmäßig ist die Bereitstellungsvorlage mit den folgenden Werten konfiguriert:

Modellparameter Standardwert
modelName gpt-4o-mini
modelFormat OpenAI (für Azure OpenAI)
modelVersion 2024-07-18
modelSkuName GlobalStandard
modelLocation eastus

Wichtig

Ändern Sie den Parameter „modelFormat“ nicht.

Die Vorlagen unterstützen nur die Bereitstellung von Azure OpenAI-Modellen. Informationen zu den unterstützten Azure OpenAI-Modellen finden Sie in der Dokumentation zur Modellunterstützung für den Azure KI-Agent-Dienst.

[Optional] Verwenden Ihrer eigenen Ressourcen während der Agenteinrichtung

Hinweis

Wenn Sie eine vorhandene Ressource von KI Services oder Azure OpenAI verwenden, wird kein Modell bereitgestellt. Sie können ein Modell nach Abschluss des Agent-Setups in der Ressource bereitstellen.

Verwenden Sie eine vorhandene Ressource von KI Services, Azure OpenAI, KI Suche und/oder Azure Blob Storage, indem Sie die vollständige ARM-Ressourcen-ID in der Parameterdatei angeben:

  • aiServiceAccountResourceId
  • aiSearchServiceResourceId
  • aiStorageAccountResourceId

Wenn Sie eine vorhandene Azure OpenAI-Ressource verwenden möchten, müssen Sie die Parameter aiServiceAccountResourceId und aiServiceKind in der Parameterdatei aktualisieren. Der aiServiceKind-Parameter sollte auf AzureOpenAI festgelegt werden.

Weitere Informationen finden Sie unter Verwenden Ihrer eigenen Ressourcen.

Konfigurieren und Ausführen eines Agents

Komponente Beschreibung
Agent Benutzerdefinierte KI, die KI-Modelle in Verbindung mit Tools verwendet.
Tool Tools helfen, die Fähigkeit eines Agenten zu erweitern, während der Unterhaltung zuverlässig und präzise zu reagieren. Dazu gehören z. B. das Herstellen einer Verbindung mit benutzerdefinierten Wissensbasen, um das Modell zu grounden, oder das Aktivieren der Websuche, um aktuelle Informationen bereitzustellen.
Thread Eine Unterhaltungssitzung zwischen einem Agent und einem Benutzer. Threads speichern Nachrichten und behandeln automatisch das Abschneiden, um Inhalte in den Kontext eines Modells einzupassen.
Nachricht Eine Nachricht, die von einem Agent oder von einem Benutzer erstellt wurde. Nachrichten können Text, Bilder und andere Dateien enthalten. Nachrichten werden als Liste im Thread gespeichert.
Ausführung Aktivierung eines Agents, der basierend auf dem Inhalt des Threads mit der Ausführung beginnt. Der Agent verwendet seine Konfiguration und die Nachrichten des Threads, um Aufgaben durch Aufrufen von Modellen und Tools auszuführen. Als Teil einer Ausführung fügt der Agent Nachrichten an den Thread an.
Ausführungsschritt Eine detaillierte Liste der Schritte, die der Agent als Teil einer Ausführung ausgeführt hat. Ein Agent kann während seiner Ausführung Tools aufrufen oder Nachrichten erstellen. Wenn Sie die Ausführungsschritte untersuchen, können Sie verstehen, wie der Agent zu seinen Ergebnissen gelangt.

Führen Sie die folgenden Befehle aus, um die Python-Pakete zu installieren.

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

Verwenden Sie den folgenden Code, um einen Agent zu erstellen und auszuführen. Zum Ausführen dieses Codes müssen Sie eine Verbindungszeichenfolge mithilfe von Informationen aus Ihrem Projekt erstellen. Das Format dieser Zeichenfolge lautet:

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

Tipp

Sie finden Ihre Verbindungszeichenfolge auch in der Übersicht für Ihr Projekt im Azure KI Foundry-Portal unter Projektdetails>Projektverbindungszeichenfolge. Screenshot der Verbindungszeichenfolge im Azure KI Foundry-Portal.

HostName finden Sie, indem Sie zu Ihrer discovery_url navigieren und das führende https:// und nachfolgende /discovery entfernen. Führen Sie den folgenden CLI-Befehl aus, um discovery_url zu finden:

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

Die Verbindungszeichenfolge könnte beispielsweise wie folgt aussehen:

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

Legen Sie diese Verbindungszeichenfolge als Umgebungsvariable namens PROJECT_CONNECTION_STRING fest.

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_sender("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")

| Referenzdokumentation | Quellcode der Bibliothek | Paket (PyPi) |

Voraussetzungen

RBAC-Rollen

Stellen Sie sicher, dass sowohl Entwickler als auch Endbenutzer über die folgenden Berechtigungen verfügen:

  • Microsoft.MachineLearningServices/workspaces/agents/read
  • Microsoft.MachineLearningServices/workspaces/agents/action
  • Microsoft.MachineLearningServices/workspaces/agents/delete

Wenn Sie benutzerdefinierte Berechtigungen erstellen möchten, stellen Sie sicher, dass sie folgendes haben:

  • agents/*/read
  • agents/*/action
  • agents/*/delete

Einrichten Ihres Azure KI-Hubs und Agent-Projekts

Im folgenden Abschnitt wird gezeigt, wie Sie die erforderlichen Ressourcen für die ersten Schritte mit dem Azure KI-Agent-Dienst einrichten:

  1. Erstellen eines Azure KI-Hubs zum Einrichten Ihrer App-Umgebung und Azure-Ressourcen.

  2. Durch das Erstellen eines Azure KI-Projekts unter Ihrem Hub wird ein Endpunkt zum Aufrufen durch Ihre App erstellt. Außerdem werden die App-Dienste für den Zugriff auf Ressourcen in Ihrem Mandanten eingerichtet.

  3. Verbinden einer Azure OpenAI-Ressource oder einer Azure KI Services-Ressource

Auswählen des Basic- oder Standard-Agent-Setups

Basic-Setup: Agents verwenden mehrinstanzenfähige Such- und Speicherressourcen, die vollständig von Microsoft verwaltet werden. Sie haben keine Sichtbarkeit oder Kontrolle über diese zugrunde liegenden Azure-Ressourcen.

Standardsetup: Agents verwenden kundeneigene Such- und Speicherressourcen mit einem Mandanten. Mit diesem Setup haben Sie die volle Kontrolle über diese Ressourcen, aber es fallen Kosten basierend auf Ihrer Nutzung an.

Beschreibung und automatische Bereitstellung Diagramm (zum Zoomen klicken)
Stellen Sie ein grundlegendes Agent-Setup bereit, das die verwaltete Identität für die Authentifizierung verwendet. Ressourcen für den KI-Hub, das KI-Projekt, das Speicherkonto und für KI-Dienste werden für Sie erstellt.

Das KI Services-Konto ist mit Ihrem Projekt und Hub verbunden, und es wird ein gpt-4o-mini-Modell in der Region „USA, Osten“ bereitgestellt. Standardmäßig wird ein von Microsoft verwalteter Schlüsseltresor verwendet.

Bereitstellung in Azure		 Ein Architekturdiagramm für das Basic-Setup des Agents.
Stellen Sie ein Agent-Standardsetup bereit, das die verwaltete Identität für die Authentifizierung verwendet.

Ressourcen für den KI-Hub, das KI-Projekt, den Schlüsseltresor, das Speicherkonto, KI-Dienste und KI-Suche werden für Sie erstellt.

Die KI-Dienste, die KI-Suche, der Schlüsseltresor und das Speicherkonto sind mit Ihrem Projekt und Ihrem Hub verbunden. Ein gpt-4o-mini-Modell wird in der Region „USA, Osten“ bereitgestellt.

Bereitstellung in Azure		 Ein Architekturdiagramm für das Standard-Setup des Agents.

[Optional] Modellauswahl in der Vorlage für die automatische Bereitstellung

Sie können das vom Agent verwendete Modell anpassen, indem Sie die Modellparameter in der Vorlage für die automatische Bereitstellung bearbeiten. Um ein anderes Modell bereitzustellen, müssen Sie mindestens die Parameter modelName und modelVersion aktualisieren.

Standardmäßig ist die Bereitstellungsvorlage mit den folgenden Werten konfiguriert:

Modellparameter Standardwert
modelName gpt-4o-mini
modelFormat OpenAI (für Azure OpenAI)
modelVersion 2024-07-18
modelSkuName GlobalStandard
modelLocation eastus

Wichtig

Ändern Sie den Parameter „modelFormat“ nicht.

Die Vorlagen unterstützen nur die Bereitstellung von Azure OpenAI-Modellen. Informationen zu den unterstützten Azure OpenAI-Modellen finden Sie in der Dokumentation zur Modellunterstützung für den Azure KI-Agent-Dienst.

[Optional] Verwenden Ihrer eigenen Ressourcen während der Agenteinrichtung

Hinweis

Wenn Sie eine vorhandene Ressource von KI Services oder Azure OpenAI verwenden, wird kein Modell bereitgestellt. Sie können ein Modell nach Abschluss des Agent-Setups in der Ressource bereitstellen.

Verwenden Sie eine vorhandene Ressource von KI Services, Azure OpenAI, KI Suche und/oder Azure Blob Storage, indem Sie die vollständige ARM-Ressourcen-ID in der Parameterdatei angeben:

  • aiServiceAccountResourceId
  • aiSearchServiceResourceId
  • aiStorageAccountResourceId

Wenn Sie eine vorhandene Azure OpenAI-Ressource verwenden möchten, müssen Sie die Parameter aiServiceAccountResourceId und aiServiceKind in der Parameterdatei aktualisieren. Der aiServiceKind-Parameter sollte auf AzureOpenAI festgelegt werden.

Weitere Informationen finden Sie unter Verwenden Ihrer eigenen Ressourcen.

Konfigurieren und Ausführen eines Agents

Komponente Beschreibung
Agent Benutzerdefinierte KI, die KI-Modelle in Verbindung mit Tools verwendet.
Tool Tools helfen, die Fähigkeit eines Agenten zu erweitern, während der Unterhaltung zuverlässig und präzise zu reagieren. Dazu gehören z. B. das Herstellen einer Verbindung mit benutzerdefinierten Wissensbasen, um das Modell zu grounden, oder das Aktivieren der Websuche, um aktuelle Informationen bereitzustellen.
Thread Eine Unterhaltungssitzung zwischen einem Agent und einem Benutzer. Threads speichern Nachrichten und behandeln automatisch das Abschneiden, um Inhalte in den Kontext eines Modells einzupassen.
Nachricht Eine Nachricht, die von einem Agent oder von einem Benutzer erstellt wurde. Nachrichten können Text, Bilder und andere Dateien enthalten. Nachrichten werden als Liste im Thread gespeichert.
Ausführung Aktivierung eines Agents, der basierend auf dem Inhalt des Threads mit der Ausführung beginnt. Der Agent verwendet seine Konfiguration und die Nachrichten des Threads, um Aufgaben durch Aufrufen von Modellen und Tools auszuführen. Als Teil einer Ausführung fügt der Agent Nachrichten an den Thread an.
Ausführungsschritt Eine detaillierte Liste der Schritte, die der Agent als Teil einer Ausführung ausgeführt hat. Ein Agent kann während seiner Ausführung Tools aufrufen oder Nachrichten erstellen. Wenn Sie die Ausführungsschritte untersuchen, können Sie verstehen, wie der Agent zu seinen Ergebnissen gelangt.

Führen Sie die folgenden Befehle aus, um die Python-Pakete zu installieren.

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

Verwenden Sie den folgenden Code, um einen Agent zu erstellen und auszuführen. Zum Ausführen dieses Codes müssen Sie eine Verbindungszeichenfolge mithilfe von Informationen aus Ihrem Projekt erstellen. Das Format dieser Zeichenfolge lautet:

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

Tipp

Sie finden Ihre Verbindungszeichenfolge auch in der Übersicht für Ihr Projekt im Azure KI Foundry-Portal unter Projektdetails>Projektverbindungszeichenfolge. Screenshot der Verbindungszeichenfolge im Azure KI Foundry-Portal.

HostName finden Sie, indem Sie zu Ihrer discovery_url navigieren und das führende https:// und nachfolgende /discovery entfernen. Führen Sie den folgenden CLI-Befehl aus, um discovery_url zu finden:

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

Die Verbindungszeichenfolge könnte beispielsweise wie folgt aussehen:

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

Legen Sie diese Verbindungszeichenfolge als Umgebungsvariable namens PROJECT_CONNECTION_STRING fest.

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