Schnellstart: Erstellen eines neuen Agents

2025-06-30

Mit dem Azure AI Foundry Agentendienst können Sie KI-Agenten erstellen, die auf Ihre Anforderungen zugeschnitten sind, indem Sie benutzerdefinierte Anweisungen nutzen und diese durch erweiterte Tools wie Code-Interpreter und benutzerdefinierte Funktionen ergänzen.

Voraussetzungen

Azure-Abonnement – kostenloses Abonnement erstellen.
Stellen Sie sicher, dass die Person, die das Konto und das Projekt erstellt, über die Rolle " Azure AI-Kontobesitzer " im Abonnementbereich verfügt.
- Alternativ erfüllt auch die Rolle "Mitwirkender" oder "Cognitive Services Contributor" auf Abonnementebene diese Anforderung.

Von Bedeutung

Das Azure AI Foundry-Portal unterstützt derzeit nur die grundlegenden Agent-Sätze. Wenn Sie ein Standard-Agent-Setup durchführen möchten, lesen Sie den Artikel " Umgebungssetup" , um mehr zu erfahren.

Erstellen eines Foundry-Kontos und Projekts im Azure AI Foundry-Portal

Führen Sie die folgenden Schritte aus, um ein Konto und projekt in Azure AI Foundry zu erstellen:

Wechseln Sie zu Azure KI Foundry. Wählen Sie in einem Projekt oben links auf der Seite Azure KI Foundry aus, um zur Startseite zu wechseln.
Verwenden Sie den Erstellungsflow für Erste Schritte mit Agents für die schnellste Erfahrung. Klicken Sie auf "Agent erstellen".
Geben Sie einen Namen für das Projekt ein. Wenn Sie die Standardwerte anpassen möchten, wählen Sie "Erweiterte Optionen" aus.
Wählen Sie "Erstellen" aus.
Warten Sie, bis Ihre Ressourcen bereitgestellt werden.
1. Es werden ein Konto und ein Projekt (untergeordnete Ressource Ihres Kontos) erstellt.
2. Das gpt-4o-Modell wird automatisch bereitgestellt.
3. Ein Standard-Agent wird erstellt.
Nach Abschluss landen Sie direkt im Agent-Spielplatz und können mit der Erstellung von Agents beginnen.

Hinweis

Wenn Sie beim Versuch, Agents zu konfigurieren oder zu erstellen, einen Berechtigungsfehler erhalten, stellen Sie sicher, dass Sie im Projekt über die Rolle Azure AI-Benutzer verfügen.

Voraussetzungen

Einrichten einer Agentumgebung
Weisen Sie die Azure AI UserRBAC-Rolle jedem Teammitglied zu, das Agents mit dem SDK oder Agent Playground erstellen oder bearbeiten muss.
- Diese Rolle muss auf Projektebene zugewiesen werden.
- Erforderliche Mindestberechtigungen: Agents/*/lesen, Agents/*/action, Agents/*/delete

Konfigurieren und Ausführen eines Agents

Komponente	BESCHREIBUNG
Vertreter	Benutzerdefinierte KI, die KI-Modelle in Verbindung mit Tools verwendet.
Werkzeug	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.
Faden	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.
Laufen	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.

Erstellen Sie ein .NET-Konsolenprojekt.

dotnet new console

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.Agents.Persistent
dotnet add package Azure.Identity

Verwenden Sie als Nächstes zum Authentifizieren Ihrer API-Anforderungen und zum Ausführen des Programms den Befehl az login, um sich bei Ihrem Azure-Abonnement anzumelden.

az login

Verwenden Sie den folgenden Code, um einen Agent zu erstellen und auszuführen. Um diesen Code auszuführen, müssen Sie den Endpunkt für Ihr Projekt abrufen. Das Format dieser Zeichenfolge lautet:

https://<AIFoundryResourceName>.services.ai.azure.com/api/projects/<ProjectName>

Tipp

Sie finden Ihren Endpunkt auch in der Übersicht für Ihr Projekt im Azure AI Foundry-Portal unter Bibliotheken>Azure AI Foundry.

Ihr Endpunkt kann z. B. etwa wie folgt aussehen:

https://myresource.services.ai.azure.com/api/projects/myproject

Legen Sie diesen Endpunkt in einer appsetting-Variablen mit dem Namen ProjectEndpointfest.

using Azure;
using Azure.AI.Agents.Persistent;
using Azure.Identity;
using Microsoft.Extensions.Configuration;
using System.Diagnostics;

IConfigurationRoot configuration = new ConfigurationBuilder()
    .SetBasePath(AppContext.BaseDirectory)
    .AddJsonFile("appsettings.json", optional: false, reloadOnChange: true)
    .Build();

var projectEndpoint = configuration["ProjectEndpoint"];
var modelDeploymentName = configuration["ModelDeploymentName"];

//Create a PersistentAgentsClient and PersistentAgent.
PersistentAgentsClient client = new(projectEndpoint, new DefaultAzureCredential());

//Give PersistentAgent a tool to execute code using CodeInterpreterToolDefinition.
PersistentAgent agent = client.Administration.CreateAgent(
    model: modelDeploymentName,
    name: "My Test Agent",
    instructions: "You politely help with math questions. Use the code interpreter tool when asked to visualize numbers.",
    tools: [new CodeInterpreterToolDefinition()]
);

//Create a thread to establish a session between Agent and a User.
PersistentAgentThread thread = client.Threads.CreateThread();

//Ask a question of the Agent.
client.Messages.CreateMessage(
    thread.Id,
    MessageRole.User,
    "Hi, Agent! Draw a graph for a line with a slope of 4 and y-intercept of 9.");

//Have Agent beging processing user's question with some additional instructions associated with the ThreadRun.
ThreadRun run = client.Runs.CreateRun(
    thread.Id,
    agent.Id,
    additionalInstructions: "Please address the user as Jane Doe. The user has a premium account.");

//Poll for completion.
do
{
    Thread.Sleep(TimeSpan.FromMilliseconds(500));
    run = client.Runs.GetRun(thread.Id, run.Id);
}
while (run.Status == RunStatus.Queued
    || run.Status == RunStatus.InProgress
    || run.Status == RunStatus.RequiresAction);

//Get the messages in the PersistentAgentThread. Includes Agent (Assistant Role) and User (User Role) messages.
Pageable<PersistentThreadMessage> messages = client.Messages.GetMessages(
    threadId: thread.Id,
    order: ListSortOrder.Ascending);

//Display each message and open the image generated using CodeInterpreterToolDefinition.
foreach (PersistentThreadMessage threadMessage in messages)
{
    foreach (MessageContent content in threadMessage.ContentItems)
    {
        switch (content)
        {
            case MessageTextContent textItem:
                Console.WriteLine($"[{threadMessage.Role}]: {textItem.Text}");
                break;
            case MessageImageFileContent imageFileContent:
                Console.WriteLine($"[{threadMessage.Role}]: Image content file ID = {imageFileContent.FileId}");
                BinaryData imageContent = client.Files.GetFileContent(imageFileContent.FileId);
                string tempFilePath = Path.Combine(AppContext.BaseDirectory, $"{Guid.NewGuid()}.png");
                File.WriteAllBytes(tempFilePath, imageContent.ToArray());
                client.Files.DeleteFile(imageFileContent.FileId);

                ProcessStartInfo psi = new()
                {
                    FileName = tempFilePath,
                    UseShellExecute = true
                };
                Process.Start(psi);
                break;
        }
    }
}

//Clean up test resources.
client.Threads.DeleteThread(threadId: thread.Id);
client.Administration.DeleteAgent(agentId: agent.Id);

Voraussetzungen

Einrichten einer Agentumgebung
Weisen Sie die Azure AI UserRBAC-Rolle jedem Teammitglied zu, das Agents mit dem SDK oder Agent Playground erstellen oder bearbeiten muss.
- Diese Rolle muss auf Projektebene zugewiesen werden.
- Erforderliche Mindestberechtigungen: Agents/*/lesen, Agents/*/action, Agents/*/delete

Konfigurieren und Ausführen eines Agents

Komponente	BESCHREIBUNG
Vertreter	Benutzerdefinierte KI, die KI-Modelle in Verbindung mit Tools verwendet.
Werkzeug	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.
Faden	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.
Laufen	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 im Rahmen 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 als Nächstes zum Authentifizieren Ihrer API-Anforderungen und zum Ausführen des Programms den Befehl az login, um sich bei Ihrem Azure-Abonnement anzumelden.

az login

Verwenden Sie den folgenden Code, um einen Agent zu erstellen und auszuführen. Um diesen Code auszuführen, müssen Sie den Endpunkt für Ihr Projekt abrufen. Das Format dieser Zeichenfolge lautet:

https://<AIFoundryResourceName>.services.ai.azure.com/api/projects/<ProjectName>

Tipp

Sie finden Ihren Endpunkt auch in der Übersicht für Ihr Projekt im Azure AI Foundry-Portal unter Bibliotheken>Azure AI Foundry.

Ihr Endpunkt kann z. B. etwa wie folgt aussehen:

https://myresource.services.ai.azure.com/api/projects/myproject

Legen Sie diesen Endpunkt als Umgebungsvariable mit dem Namen PROJECT_ENDPOINT fest.

import os
from azure.ai.projects import AIProjectClient
from azure.identity import DefaultAzureCredential
from azure.ai.agents.models import CodeInterpreterTool

# Create an Azure AI Client from an endpoint, copied from your Azure AI Foundry project.
# You need to login to Azure subscription via Azure CLI and set the environment variables
project_endpoint = os.environ["PROJECT_ENDPOINT"]  # Ensure the PROJECT_ENDPOINT environment variable is set

# Create an AIProjectClient instance
project_client = AIProjectClient(
    endpoint=project_endpoint,
    credential=DefaultAzureCredential(),  # Use Azure Default Credential for authentication
)

code_interpreter = CodeInterpreterTool()
with project_client:
    # Create an agent with the Bing Grounding tool
    agent = project_client.agents.create_agent(
        model=os.environ["MODEL_DEPLOYMENT_NAME"],  # Model deployment name
        name="my-agent",  # Name of the agent
        instructions="You are a helpful agent",  # Instructions for the agent
        tools=code_interpreter.definitions,  # Attach the tool
    )
    print(f"Created agent, ID: {agent.id}")

    # Create a thread for communication
    thread = project_client.agents.threads.create()
    print(f"Created thread, ID: {thread.id}")
    
    # Add a message to the thread
    message = project_client.agents.messages.create(
        thread_id=thread.id,
        role="user",  # Role of the message sender
        content="What is the weather in Seattle today?",  # Message content
    )
    print(f"Created message, ID: {message['id']}")
    
    # Create and process an agent run
    run = project_client.agents.runs.create_and_process(thread_id=thread.id, agent_id=agent.id)
    print(f"Run finished with status: {run.status}")
    
    # Check if the run failed
    if run.status == "failed":
        print(f"Run failed: {run.last_error}")
    
    # Fetch and log all messages
    messages = project_client.agents.messages.list(thread_id=thread.id)
    for message in messages:
        print(f"Role: {message.role}, Content: {message.content}")
    
    # Delete the agent when done
    project_client.agents.delete_agent(agent.id)
    print("Deleted agent")

Voraussetzungen

Einrichten einer Agentumgebung
Weisen Sie die Azure AI UserRBAC-Rolle jedem Teammitglied zu, das Agents mit dem SDK oder Agent Playground erstellen oder bearbeiten muss.
- Diese Rolle muss auf Projektebene zugewiesen werden.
- Erforderliche Mindestberechtigungen: Agents/*/lesen, Agents/*/action, Agents/*/delete

Konfigurieren und Ausführen eines Agents

Komponente	BESCHREIBUNG
Vertreter	Benutzerdefinierte KI, die KI-Modelle mit Tools verwendet.
Werkzeug	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.
Faden	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.
Laufen	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 im Rahmen 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.

Zu den wichtigsten Objekten in diesem Code gehören:

Initialisieren Sie zunächst ein neues Projekt, indem Sie Folgendes ausführen:

npm init -y

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

npm install @azure/ai-agents @azure/identity
npm install dotenv

Verwenden Sie als Nächstes zum Authentifizieren Ihrer API-Anforderungen und zum Ausführen des Programms den Befehl az login, um sich bei Ihrem Azure-Abonnement anzumelden.

az login

Verwenden Sie den folgenden Code, um einen Agent zu erstellen und auszuführen, der eine CSV-Datei mit Daten hochlädt, und generiert dann ein Balkendiagramm aus diesen Daten. Um diesen Code auszuführen, müssen Sie den Endpunkt für Ihr Projekt abrufen. Das Format dieser Zeichenfolge lautet:

https://<AIFoundryResourceName>.services.ai.azure.com/api/projects/<ProjectName>

Tipp

Sie finden Ihren Endpunkt auch in der Übersicht für Ihr Projekt im Azure AI Foundry-Portal unter Bibliotheken>Azure AI Foundry.

Ihr Endpunkt sieht z. B. ungefähr wie folgt aus:

https://myresource.services.ai.azure.com/api/projects/myproject

Legen Sie diesen Endpunkt als Umgebungsvariable mit dem Namen PROJECT_ENDPOINT in einer .env-Datei fest.

Von Bedeutung

Dieser Schnellstartcode verwendet Umgebungsvariablen für die vertrauliche Konfiguration. Comitten Sie ihre .env-Datei niemals zur Versionskontrolle, indem Sie sicherstellen, dass .env in Ihrer .gitignore-Datei aufgelistet ist.
Denken Sie daran: Wenn Sie versehentlich vertrauliche Informationen eingeben, betrachten Sie diese Daten als kompromittiert und wechseln Sie sie sofort aus.

Erstellen Sie als Nächstes eine index.js Datei, und fügen Sie sie in den folgenden Code ein:

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

/**
 * This sample demonstrates how to use agent operations with code interpreter from the Azure Agents service.
 *
 * @summary demonstrates how to use agent operations with code interpreter.
 */
// @ts-nocheck
import type {
  MessageDeltaChunk,
  MessageDeltaTextContent,
  MessageImageFileContent,
  MessageTextContent,
  ThreadRun,
} from "@azure/ai-agents";
import {
  RunStreamEvent,
  MessageStreamEvent,
  DoneEvent,
  ErrorEvent,
  AgentsClient,
  isOutputOfType,
  ToolUtility,
} from "@azure/ai-agents";
import { DefaultAzureCredential } from "@azure/identity";

import * as fs from "fs";
import path from "node:path";
import "dotenv/config";

const projectEndpoint = process.env["PROJECT_ENDPOINT"] || "<project endpoint>";
const modelDeploymentName = process.env["MODEL_DEPLOYMENT_NAME"] || "gpt-4o";

export async function main(): Promise<void> {
  // Create an Azure AI Client
  const client = new AgentsClient(projectEndpoint, new DefaultAzureCredential());

  // Upload file and wait for it to be processed
  const filePath = "./data/nifty500QuarterlyResults.csv";
  const localFileStream = fs.createReadStream(filePath);
  const localFile = await client.files.upload(localFileStream, "assistants", {
    fileName: "myLocalFile",
  });

  console.log(`Uploaded local file, file ID : ${localFile.id}`);

  // Create code interpreter tool
  const codeInterpreterTool = ToolUtility.createCodeInterpreterTool([localFile.id]);

  // Notice that CodeInterpreter must be enabled in the agent creation, otherwise the agent will not be able to see the file attachment
  const agent = await client.createAgent(modelDeploymentName, {
    name: "my-agent",
    instructions: "You are a helpful agent",
    tools: [codeInterpreterTool.definition],
    toolResources: codeInterpreterTool.resources,
  });
  console.log(`Created agent, agent ID: ${agent.id}`);

  // Create a thread
  const thread = await client.threads.create();
  console.log(`Created thread, thread ID: ${thread.id}`);

  // Create a message
  const message = await client.messages.create(
    thread.id,
    "user",
    "Could you please create a bar chart in the TRANSPORTATION sector for the operating profit from the uploaded CSV file and provide the file to me?",
  );

  console.log(`Created message, message ID: ${message.id}`);

  // Create and execute a run
  const streamEventMessages = await client.runs.create(thread.id, agent.id).stream();

  for await (const eventMessage of streamEventMessages) {
    switch (eventMessage.event) {
      case RunStreamEvent.ThreadRunCreated:
        console.log(`ThreadRun status: ${(eventMessage.data as ThreadRun).status}`);
        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";
              console.log(`Text delta received:: ${textValue}`);
            }
          });
        }
        break;

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

  // Delete the original file from the agent to free up space (note: this does not delete your version of the file)
  await client.files.delete(localFile.id);
  console.log(`Deleted file, file ID : ${localFile.id}`);

  // Print the messages from the agent
  const messagesIterator = client.messages.list(thread.id);
  const messagesArray = [];
  for await (const m of messagesIterator) {
    messagesArray.push(m);
  }
  console.log("Messages:", messagesArray);

  // Get most recent message from the assistant
// Get most recent message from the assistant
  const assistantMessage = messagesArray.find((msg) => msg.role === "assistant");
  if (assistantMessage) {
    // Look for an image file in the assistant's message
    const imageFileOutput = assistantMessage.content.find(content => 
      content.type === "image_file" && content.imageFile?.fileId);
    
    if (imageFileOutput) {
      try {
        // Save the newly created file
        console.log(`Saving new files...`);
        const imageFile = imageFileOutput.imageFile.fileId;
        const imageFileName = path.resolve(
          "./data/" + (await client.files.get(imageFile)).filename + "ImageFile.png",
        );
        console.log(`Image file name : ${imageFileName}`);

        const fileContent = await client.files.getContent(imageFile).asNodeStream();
        if (fileContent && fileContent.body) {
          const chunks = [];
          for await (const chunk of fileContent.body) {
            chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
          }
          const buffer = Buffer.concat(chunks);
          fs.writeFileSync(imageFileName, buffer);
          console.log(`Successfully saved image to ${imageFileName}`);
        } else {
          console.error("No file content available in the response");
        }
      } catch (error) {
        console.error("Error saving image file:", error);
      }
    } else {
      console.log("No image file found in assistant's message");
    }
  } else {
    console.log("No assistant message found");
  }

  // Iterate through messages and print details for each annotation
  console.log(`Message Details:`);
  messagesArray.forEach((m) => {
    console.log(`File Paths:`);
    console.log(`Type: ${m.content[0].type}`);
    if (isOutputOfType<MessageTextContent>(m.content[0], "text")) {
      const textContent = m.content[0] as MessageTextContent;
      console.log(`Text: ${textContent.text.value}`);
    }
    console.log(`File ID: ${m.id}`);
    // firstId and lastId are properties of the paginator, not the messages array
    // Removing these references as they don't exist in this context
  });

  // Delete the agent once done
  await client.deleteAgent(agent.id);
  console.log(`Deleted agent, agent ID: ${agent.id}`);
}

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

Führen Sie den Code mit node index.js aus. Dieser Code generiert eine PNG-Balkendiagramm-Bilddatei im TRANSPORT-Sektor für den betriebswirtschaftlichen Gewinn aus der hochgeladenen CSV-Datei und stellt die Datei für Sie bereit. Vollständiger Beispielquellcode verfügbar.

| Referenzdokumentation |

Voraussetzungen

Einrichten einer Agentumgebung
Weisen Sie die Azure AI UserRBAC-Rolle jedem Teammitglied zu, das Agents mit dem SDK oder Agent Playground erstellen oder bearbeiten muss.
- Diese Rolle muss auf Projektebene zugewiesen werden.
- Erforderliche Mindestberechtigungen: Agents/*/lesen, Agents/*/action, Agents/*/delete

Konfigurieren und Ausführen eines Agents

Komponente	BESCHREIBUNG
Vertreter	Benutzerdefinierte KI, die KI-Modelle in Verbindung mit Tools verwendet.
Werkzeug	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.
Faden	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.
Laufen	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 im Rahmen 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.

API-Aufrufinformationen

Verwenden Sie zum Authentifizieren Ihrer API-Anforderungen den Befehl az login, um sich bei Ihrem Azure-Abonnement anzumelden.

az login

Als Nächstes müssen Sie das Entra ID-Token abrufen, die Sie für die Autorisierung der API-Aufrufe benötigen. Rufen Sie das Token mithilfe des folgenden CLI-Befehls ab:

az account get-access-token --resource 'https://ai.azure.com' | jq -r .accessToken | tr -d '"'

Legen Sie das Zugriffstoken als Umgebungsvariable mit dem Namen AGENT_TOKEN fest.

Um REST-API-Aufrufe an den Azure AI Foundry Agent Service erfolgreich zu tätigen, müssen Sie den Endpunkt wie folgt verwenden:

https://<your_ai_service_name>.services.ai.azure.com/api/projects/<your_project_name>

Ihr Endpunkt kann z. B. etwa wie folgt aussehen:

https://exampleaiservice.services.ai.azure.com/api/projects/project

Legen Sie diesen Endpunkt als Umgebungsvariable mit dem Namen AZURE_AI_FOUNDRY_PROJECT_ENDPOINT fest.

Hinweis

Für die api-version Parameter ist die GA-API-Version 2025-05-01 und die neueste Vorschau-API-Version ist 2025-05-15-preview. Sie müssen die Vorschau-API für Tools verwenden, die sich in der Vorschau befinden.
Erwägen Sie, Ihre API-Version als Umgebungsvariable zu verwenden, wie z. B. $API_VERSION.

Einen Agent erstellen

Hinweis

Beim Azure KI-Agents-Dienst müssen Sie im model-Parameter den Modellimplementierungsnamen angeben. Wenn sich der Name der Modellimplementierung von dem zugrunde liegenden Modellnamen unterscheidet, ändern Sie den Code zu "model": "{your-custom-model-deployment-name}".

curl --request POST \
  --url $AZURE_AI_FOUNDRY_PROJECT_ENDPOINT/assistants?api-version=2025-05-01 \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "instructions": "You are a helpful agent.",
    "name": "my-agent",
    "tools": [{"type": "code_interpreter"}],
    "model": "gpt-4o-mini"
  }'

Erstellen eines Threads

curl --request POST \
  --url $AZURE_AI_FOUNDRY_PROJECT_ENDPOINT/threads?api-version=2025-05-01 \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d ''

Hinzufügen einer Benutzerfrage zum Thread

curl --request POST \
  --url $AZURE_AI_FOUNDRY_PROJECT_ENDPOINT/threads/thread_abc123/messages?api-version=2025-05-01 \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
      "role": "user",
      "content": "I need to solve the equation `3x + 11 = 14`. Can you help me?"
    }'

Thread ausführen

curl --request POST \
  --url $AZURE_AI_FOUNDRY_PROJECT_ENDPOINT/threads/thread_abc123/runs?api-version=2025-05-01 \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "assistant_id": "asst_abc123",
  }'

Abrufen des Ausführungsstatus

curl --request GET \
  --url $AZURE_AI_FOUNDRY_PROJECT_ENDPOINT/threads/thread_abc123/runs/run_abc123?api-version=2025-05-01 \
  -H "Authorization: Bearer $AGENT_TOKEN"

Antwort des Agenten abrufen

curl --request GET \
  --url $AZURE_AI_FOUNDRY_PROJECT_ENDPOINT/threads/thread_abc123/messages?api-version=2025-05-01 \
  -H "Authorization: Bearer $AGENT_TOKEN"

Freigeben über

Schnellstart: Erstellen eines neuen Agents

Voraussetzungen

Erstellen eines Foundry-Kontos und Projekts im Azure AI Foundry-Portal

Voraussetzungen

Konfigurieren und Ausführen eines Agents

Voraussetzungen

Konfigurieren und Ausführen eines Agents

Voraussetzungen

Konfigurieren und Ausführen eines Agents

Voraussetzungen

Konfigurieren und Ausführen eines Agents

API-Aufrufinformationen

Einen Agent erstellen

Erstellen eines Threads

Hinzufügen einer Benutzerfrage zum Thread

Thread ausführen

Abrufen des Ausführungsstatus

Antwort des Agenten abrufen

Feedback

Zusätzliche Ressourcen