Schnellstart: Erstellen eines neuen Agents

Note

Dieses Dokument bezieht sich auf das Microsoft Foundry(klassische) Portal.

🔍 Zeigen Sie die Microsoft Foundry-Dokumentation (neu) an, um mehr über das neue Portal zu erfahren.

Note

Diese Schnellstartanleitung richtet sich an die vorherige Version von Agents. Sehen Sie sich die Schnellstartanleitung für Microsoft Foundry an, um die neue Version der API zu verwenden.

Der Foundry Agent Service ermöglicht es Ihnen, KI-Agenten zu erstellen, die auf Ihre Anforderungen zugeschnitten sind, indem benutzerdefinierte Anweisungen genutzt und durch erweiterte Tools wie Code-Interpreter und benutzerdefinierte Funktionen ergänzt werden.

Prerequisites

Azure-Abonnement – kostenloses Abonnement erstellen.
Stellen Sie sicher, dass die Person, die das Konto und das Projekt erstellt, über die Rolle des Azure AI-Kontobesitzers im Abonnementbereich verfügt, wodurch die erforderlichen Berechtigungen zum Erstellen des Projekts gewährt werden.
- Alternativ kann die Erstellung des Projekts durch die Rolle Mitwirkender oder Cognitive Services-Mitwirkender auf Abonnementebene ermöglicht werden.
Nachdem das Projekt erstellt wurde, stellen Sie sicher, dass die Person, die den Agent innerhalb des Projekts erstellt, über die Azure AI-Benutzerrolle auf Projektebene verfügt.

Important

Das Microsoft Foundry-Portal unterstützt derzeit nur das Grundlegende Agent-Setup. 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 Foundry-Portal

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

Wechseln Sie zu Foundry. Wenn Sie sich in einem Projekt befinden, wählen Sie "Foundry" oben links auf der Seite 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. Sie können Ihren Agenten Anweisungen dazu geben, was zu tun ist und wie Sie es tun können. Beispiel: "Sie sind ein hilfreicher Agent, der Fragen zur Geografie beantworten kann." Anschließend können Sie mit Ihrem Agenten chatten.

Note

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.

Prerequisites

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

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>

Important

Ab Mai 2025 verwendet der Azure AI-Agent-Dienst einen Endpunkt für Foundry-Projekte anstelle der Verbindungszeichenfolge, die zuvor für Hub-basierte Projekte verwendet wurde. Wenn Sie ein hubbasiertes Projekt verwenden, können Sie die aktuellen Versionen des SDK und der REST-API nicht verwenden. Weitere Informationen finden Sie unter SDK-Verwendung mit hubbasierten Projekten.

Sie finden Ihren Endpunkt in der Übersicht für Ihr Projekt im Microsoft Foundry-Portal unter Libraries>Foundry.

Legen Sie diesen Endpunkt in einer Umgebungsvariable mit dem Namen ProjectEndpointfest.

Außerdem benötigen Sie den Bereitstellungsnamen Ihres Modells. Sie finden sie in "Modelle + Endpunkte " im linken Navigationsmenü.

Speichern Sie den Namen ihres Modellbereitstellungsnamens als Umgebungsvariable namens ModelDeploymentName.

using Azure;
using Azure.AI.Agents.Persistent;
using Azure.Identity;
using System.Diagnostics;

var projectEndpoint = System.Environment.GetEnvironmentVariable("ProjectEndpoint");
var modelDeploymentName = System.Environment.GetEnvironmentVariable("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 begin 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;
        }
    }
}

//If you want to delete your agent, uncomment the following lines:
//client.Threads.DeleteThread(threadId: thread.Id);
//client.Administration.DeleteAgent(agentId: agent.Id);

Prerequisites

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

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>

Important

Sie finden Ihren Endpunkt in der Übersicht für Ihr Projekt im Microsoft Foundry-Portal unter Libraries>Foundry.

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

Außerdem benötigen Sie den Bereitstellungsnamen Ihres Modells. Sie finden sie in "Modelle + Endpunkte " im linken Navigationsmenü.

Speichern Sie den Namen ihres Modellbereitstellungsnamens als Umgebungsvariable namens MODEL_DEPLOYMENT_NAME.

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

# Create an AIProjectClient instance
project_client = AIProjectClient(
    endpoint=os.getenv("PROJECT_ENDPOINT"),
    credential=DefaultAzureCredential(),  
    # Use Azure Default Credential for authentication
)

with project_client:

    code_interpreter = CodeInterpreterTool()

    agent = project_client.agents.create_agent(
        model=os.getenv("MODEL_DEPLOYMENT_NAME"),  # Model deployment name
        name="my-agent",  # Name of the agent
        instructions="""You politely help with math questions. 
        Use the Code Interpreter tool when asked to visualize numbers.""",  
        # Instructions for the agent
        tools=code_interpreter.definitions,  # Attach the tool
        tool_resources=code_interpreter.resources,  # Attach tool resources
    )
    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}")

    question = """Draw a graph for a line with a slope of 4 
    and y-intercept of 9 and provide the file to me?"""

    # Add a message to the thread
    message = project_client.agents.messages.create(
        thread_id=thread.id,
        role="user",  # Role of the message sender
        content=question,  # 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,
        additional_instructions="""Please address the user as Jane Doe.
        The user has a premium account.""",
    )

    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)
    print(f"Messages: {messages}")

    for message in messages:
        print(f"Role: {message.role}, Content: {message.content}")
        for this_content in message.content:
            print(f"Content Type: {this_content.type}, Content Data: {this_content}")
            if this_content.text.annotations:
                for annotation in this_content.text.annotations:
                    print(f"Annotation Type: {annotation.type}, Text: {annotation.text}")
                    print(f"Start Index: {annotation.start_index}")
                    print(f"End Index: {annotation.end_index}")
                    print(f"File ID: {annotation.file_path.file_id}")
                    # Save every image file in the message
                    file_id = annotation.file_path.file_id
                    file_name = f"{file_id}_image_file.png"
                    project_client.agents.files.save(file_id=file_id, file_name=file_name)
                    print(f"Saved image file to: {Path.cwd() / file_name}")
    #Uncomment these lines to delete the agent when done
    #project_client.agents.delete_agent(agent.id)
    #print("Deleted agent")

Prerequisites

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

Node.js LTS

Konfigurieren und Ausführen eines Agents

Zu den wichtigsten Objekten in diesem Code gehören:

AgentsClient

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

npm init -y
npm pkg set type="module"

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

npm install @azure/ai-agents @azure/identity
npm install @types/node typescript --save-dev

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 die mathematische Frage I need to solve the equation '3x + 11 = 14'. Can you help me?zu beantworten. 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>

Sie finden Ihren Endpunkt in der Übersicht für Ihr Projekt im Microsoft Foundry-Portal unter Libraries>Foundry.

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

Außerdem benötigen Sie den Bereitstellungsnamen Ihres Modells. Sie finden sie in "Modelle + Endpunkte " im linken Navigationsmenü.

Speichern Sie den Namen ihres Modellbereitstellungsnamens als Umgebungsvariable namens MODEL_DEPLOYMENT_NAME.

Important

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 eine tsconfig.json Datei mit folgendem Inhalt:

{
  "compilerOptions": {
    "module": "nodenext",
    "target": "esnext",
    "types": ["node"],
    "lib": ["esnext"],
    "sourceMap": true,
    "declaration": true,
    "declarationMap": true,
    "noUncheckedIndexedAccess": true,
    "exactOptionalPropertyTypes": true,
    "strict": true,
    "verbatimModuleSyntax": true,
    "isolatedModules": true,
    "noUncheckedSideEffectImports": true,
    "moduleDetection": "force",
    "skipLibCheck": true,
  }
}

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

import { AgentsClient } from "@azure/ai-agents";
import { DefaultAzureCredential } from "@azure/identity";

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

  // Create an agent
  const agent = await client.createAgent(modelDeploymentName, {
    name: "my-agent",
    instructions: "You are a helpful agent specialized in math. When providing mathematical explanations, use plain text formatting with simple characters like +, -, *, / for operations. Do not use LaTeX formatting with backslashes or special notation. Make your explanations clear and easy to read in a terminal.",
  });
  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}`);

  // List all threads for the agent
  const threads = client.threads.list();
  console.log(`Threads for agent ${agent.id}:`);
  for await (const t of threads) {
    console.log(`Thread ID: ${t.id} created at: ${t.createdAt}`);
  }

  // Create a message
  const message = await client.messages.create(thread.id, "user", "I need to solve the equation `3x + 11 = 14`. Can you help me?");
  console.log(`Created message, message ID : ${message.id}`);

  // Create and poll a run
  console.log("Creating run...");
  const run = await client.runs.createAndPoll(thread.id, agent.id, {
    pollingOptions: {
      intervalInMs: 2000,
    },
    onResponse: (response): void => {
      const parsedBody =
        typeof response.parsedBody === "object" && response.parsedBody !== null
          ? response.parsedBody
          : null;
      const status = parsedBody && "status" in parsedBody ? parsedBody.status : "unknown";
      console.log(`Received response with status: ${status}`);
    },
  });
  console.log(`Run finished with status: ${run.status}`);

  const messagesIterator = client.messages.list(thread.id);
  console.log("\n\n========================================================");
  console.log("=================== CONVERSATION RESULTS ===================");
  console.log("========================================================\n");
  
  // Collect all messages first
  const messages = [];
  for await (const m of messagesIterator) {
    messages.push(m);
  }
  
  // Reverse the order of messages (or sort by timestamp if available)
  messages.reverse();
  
  // Display messages in the new order
  for (const m of messages) {
    if (m.role === "user") {
      console.log(`\n❓ USER QUESTION: ${
        Array.isArray(m.content) && m.content[0]?.type === "text" && 'text' in m.content[0]
          ? m.content[0].text.value
          : JSON.stringify(m.content)
      }`);
    } else if (m.role === "assistant") {
      console.log("\n🤖 ASSISTANT'S ANSWER:");
      console.log("--------------------------------------------------");
      
      // Extract and print the text content in a more readable format
      if (m.content && Array.isArray(m.content)) {
        for (const content of m.content) {
          if (content.type === "text" && 'text' in content) {
            console.log(content.text?.value);
          } else {
            console.log(content);
          }
        }
      } else {
        console.log(JSON.stringify(m.content, null, 2));
      }
      console.log("--------------------------------------------------\n");
    }
  }
  
  console.log("\n========================================================");
  console.log("====================== END OF RESULTS ======================");
  console.log("========================================================\n");

  // Clean up
  await client.threads.delete(thread.id);
  await client.deleteAgent(agent.id);
}

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

Führen Sie den Code mit npx tsx -r dotenv/config index.ts aus. Dieser Code beantwortet die Frage I need to solve the equation '3x + 11 = 14'. Can you help me?. Antworten sind nicht deterministisch, Ihre Ausgabe sieht ähnlich wie die folgende Ausgabe aus:

Created agent, agent ID : asst_X4yDNWrdWKb8LN0SQ6xlzhWk
Created thread, thread ID : thread_TxqZcHL2BqkNWl9dFzBYMIU6
Threads for agent asst_X4yDNWrdWKb8LN0SQ6xlzhWk:
...
Created message, message ID : msg_R0zDsXdc2UbfsNXvS1zeS6hk
Creating run...
Received response with status: queued
Received response with status: in_progress
Received response with status: completed
Run finished with status: completed


========================================================
=================== CONVERSATION RESULTS ===================
========================================================


❓ USER QUESTION: I need to solve the equation `3x + 11 = 14`. Can you help me?

🤖 ASSISTANT'S ANSWER:
--------------------------------------------------
Certainly! Let's solve the equation step by step:

We have:
3x + 11 = 14

### Step 1: Eliminate the constant (+11) on the left-hand side.
Subtract 11 from both sides:
3x + 11 - 11 = 14 - 11
This simplifies to:
3x = 3

We have:
3x + 11 = 14

### Step 1: Eliminate the constant (+11) on the left-hand side.
Subtract 11 from both sides:
3x + 11 - 11 = 14 - 11
This simplifies to:
3x = 3

### Step 2: Solve for x.
Divide both sides by 3:
3x / 3 = 3 / 3
This simplifies to:
x = 1

### Final Answer:
x = 1
--------------------------------------------------


========================================================
====================== END OF RESULTS ======================
========================================================

Vollständiger Beispielquellcode verfügbar.

Prerequisites

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

Erstellen Sie zunächst ein neues Java-Konsolenprojekt. Zum Ausführen des Codes benötigen Sie die folgenden Abhängigkeiten:

<dependencies>
    <dependency>
        <groupId>com.azure</groupId>
        <artifactId>azure-ai-agents-persistent</artifactId>
        <version>1.0.0-beta.2</version>
    </dependency>
    <dependency>
        <groupId>com.azure</groupId>
        <artifactId>azure-identity</artifactId>
        <version>1.17.0-beta.1</version>
    </dependency>
</dependencies>

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>

Important

Sie finden Ihren Endpunkt in der Übersicht für Ihr Projekt im Microsoft Foundry-Portal unter Libraries>Foundry.

Legen Sie diesen Endpunkt in einer Umgebungsvariable mit dem Namen PROJECT_ENDPOINTfest.

Außerdem benötigen Sie den Bereitstellungsnamen Ihres Modells. Sie finden sie in "Modelle + Endpunkte " im linken Navigationsmenü.

Speichern Sie den Namen ihres Modellbereitstellungsnamens als Umgebungsvariable namens MODEL_DEPLOYMENT_NAME.

Codebeispiel

package com.example.agents;

import com.azure.ai.agents.persistent.MessagesClient;
import com.azure.ai.agents.persistent.PersistentAgentsAdministrationClient;
import com.azure.ai.agents.persistent.PersistentAgentsClient;
import com.azure.ai.agents.persistent.PersistentAgentsClientBuilder;
import com.azure.ai.agents.persistent.RunsClient;
import com.azure.ai.agents.persistent.ThreadsClient;
import com.azure.ai.agents.persistent.models.CodeInterpreterToolDefinition;
import com.azure.ai.agents.persistent.models.CreateAgentOptions;
import com.azure.ai.agents.persistent.models.CreateRunOptions;
import com.azure.ai.agents.persistent.models.MessageImageFileContent;
import com.azure.ai.agents.persistent.models.MessageRole;
import com.azure.ai.agents.persistent.models.MessageTextContent;
import com.azure.ai.agents.persistent.models.PersistentAgent;
import com.azure.ai.agents.persistent.models.PersistentAgentThread;
import com.azure.ai.agents.persistent.models.RunStatus;
import com.azure.ai.agents.persistent.models.ThreadMessage;
import com.azure.ai.agents.persistent.models.ThreadRun;
import com.azure.ai.agents.persistent.models.MessageContent;
import com.azure.core.http.rest.PagedIterable;
import com.azure.identity.DefaultAzureCredentialBuilder;
import java.util.Arrays;

public class AgentSample {

    public static void main(String[] args) {
        // variables for authenticating requests to the agent service 
        String projectEndpoint = System.getenv("PROJECT_ENDPOINT");
        String modelName = System.getenv("MODEL_DEPLOYMENT_NAME");

        // initialize clients to manage various aspects of agent runtime
        PersistentAgentsClientBuilder clientBuilder = new PersistentAgentsClientBuilder()
            .endpoint(projectEndpoint)
            .credential(new DefaultAzureCredentialBuilder().build());
        PersistentAgentsClient agentsClient = clientBuilder.buildClient();
        PersistentAgentsAdministrationClient administrationClient = agentsClient.getPersistentAgentsAdministrationClient();
        ThreadsClient threadsClient = agentsClient.getThreadsClient();
        MessagesClient messagesClient = agentsClient.getMessagesClient();
        RunsClient runsClient = agentsClient.getRunsClient();
        
        
        String agentName = "my-agent"; // the name of the agent
        CreateAgentOptions createAgentOptions = new CreateAgentOptions(modelName)
            .setName(agentName)
            .setInstructions("You are a helpful agent") // system insturctions
            .setTools(Arrays.asList(new CodeInterpreterToolDefinition()));
        PersistentAgent agent = administrationClient.createAgent(createAgentOptions);

        PersistentAgentThread thread = threadsClient.createThread();
        ThreadMessage createdMessage = messagesClient.createMessage(
            thread.getId(),
            MessageRole.USER,
            "I need to solve the equation `3x + 11 = 14`. Can you help me?"); // The message to the agent

        try {
            //run the agent
            CreateRunOptions createRunOptions = new CreateRunOptions(thread.getId(), agent.getId())
                .setAdditionalInstructions("");
            ThreadRun threadRun = runsClient.createRun(createRunOptions);
            // wait for the run to complete before printing the message
            waitForRunCompletion(thread.getId(), threadRun, runsClient);
            printRunMessages(messagesClient, thread.getId());
        } catch (InterruptedException e) {
            throw new RuntimeException(e);
        } finally {
            //cleanup - uncomment these lines if you want to delete the agent
            //threadsClient.deleteThread(thread.getId());
            //administrationClient.deleteAgent(agent.getId());
        }
    }

    // A helper function to print messages from the agent
    public static void printRunMessages(MessagesClient messagesClient, String threadId) {

        PagedIterable<ThreadMessage> runMessages = messagesClient.listMessages(threadId);
        for (ThreadMessage message : runMessages) {
            System.out.print(String.format("%1$s - %2$s : ", message.getCreatedAt(), message.getRole()));
            for (MessageContent contentItem : message.getContent()) {
                if (contentItem instanceof MessageTextContent) {
                    System.out.print((((MessageTextContent) contentItem).getText().getValue()));
                } else if (contentItem instanceof MessageImageFileContent) {
                    String imageFileId = (((MessageImageFileContent) contentItem).getImageFile().getFileId());
                    System.out.print("Image from ID: " + imageFileId);
                }
                System.out.println();
            }
        }
    }

    // a helper function to wait until a run has completed running
    public static void waitForRunCompletion(String threadId, ThreadRun threadRun, RunsClient runsClient)
        throws InterruptedException {

        do {
            Thread.sleep(500);
            threadRun = runsClient.getRun(threadId, threadRun.getId());
        }
        while (
            threadRun.getStatus() == RunStatus.QUEUED
                || threadRun.getStatus() == RunStatus.IN_PROGRESS
                || threadRun.getStatus() == RunStatus.REQUIRES_ACTION);

        if (threadRun.getStatus() == RunStatus.FAILED) {
            System.out.println(threadRun.getLastError().getMessage());
        }
    }
}

| Referenzdokumentation |

Prerequisites

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

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, um die API-Aufrufe als Autorisierung bereitzustellen. 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 Foundry Agent Service erfolgreich zu tätigen, müssen Sie den Endpunkt Ihres Projekts verwenden:

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

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

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

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

Note

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

Note

Beim Azure KI-Agents-Dienst müssen Sie im model-Parameter den Modellimplementierungsnamen angeben. Wenn sich der Name der Modellimplementierung von dem zugrundeliegenden 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"

Nächste Schritte

Erfahren Sie mehr über die Tools, mit denen Sie die Funktionen Ihrer Agenten erweitern können, z. B. indem Sie Zugriff auf das Internet gewähren, Grundinformationen bereitstellen und vieles mehr.

Feedback

War diese Seite hilfreich?

Last updated on 2025-12-03

Freigeben über

Schnellstart: Erstellen eines neuen Agents

Prerequisites

Erstellen eines Foundry-Kontos und Projekts im Foundry-Portal

Prerequisites

Konfigurieren und Ausführen eines Agents

Prerequisites

Konfigurieren und Ausführen eines Agents

Prerequisites

Konfigurieren und Ausführen eines Agents

Prerequisites

Konfigurieren und Ausführen eines Agents

Codebeispiel

Prerequisites

Konfigurieren und Ausführen eines Agents

Einen Agent erstellen

Erstellen eines Threads

Hinzufügen einer Benutzerfrage zum Thread

Thread ausführen

Abrufen des Ausführungsstatus

Antwort des Agenten abrufen

Nächste Schritte

Feedback

Zusätzliche Ressourcen