Udostępnij przez

Szybki start: tworzenie nowego agenta (klasycznego)

Uwaga / Notatka

Ten dokument odnosi się do portalu Microsoft Foundry (klasycznego).

🔍 Zapoznaj się z dokumentacją rozwiązania Microsoft Foundry (nową), aby dowiedzieć się więcej o nowym portalu.

Uwaga / Notatka

Ten Szybki start dotyczy wcześniejszej wersji agentów. Zobacz przewodnik szybkiego startu usługi Microsoft Foundry w celu użycia nowej wersji interfejsu API.

Usługa Foundry Agent umożliwia tworzenie agentów sztucznej inteligencji dostosowanych do Twoich potrzeb za pomocą niestandardowych instrukcji i wspomaganych przez zaawansowane narzędzia, takie jak interpreter kodu i funkcje dostosowane do potrzeb.

Wymagania wstępne

  • Subskrypcja platformy Azure — utwórz bezpłatnie.
  • Upewnij się, że osoba tworząca konto i projekt ma rolę Właściciela konta usługi Azure AI w zakresie subskrypcji, która przyzna niezbędne uprawnienia do tworzenia projektu
    • Alternatywnie posiadanie roli Współautor lub Właściciel na poziomie subskrypcji umożliwi utworzenie projektu
  • Po utworzeniu projektu upewnij się, że osoba tworząca agenta w projekcie ma rolę użytkownika usługi Azure AI na poziomie projektu

Ważna

Portal Microsoft Foundry obsługuje obecnie tylko podstawową konfigurację agenta. Jeśli chcesz wykonać konfigurację agenta standardowego, zobacz artykuł Konfiguracja środowiska , aby dowiedzieć się więcej.

Tworzenie konta i projektu foundry w portalu Foundry

Aby utworzyć konto i projekt w narzędziu Foundry, wykonaj następujące kroki:

  1. Przejdź do Foundry. Jeśli jesteś w projekcie, wybierz pozycję Foundry w lewym górnym rogu strony, aby przejść do strony głównej.

  2. Skorzystaj z przepływu tworzenia rozpoczynania pracy z agentem, aby uzyskać najszybsze środowisko. Kliknij pozycję Utwórz agenta.

    Zrzut ekranu przedstawiający portal Foundry.

  3. Wprowadź nazwę dla projektu. Jeśli chcesz dostosować wartości domyślne, wybierz pozycję Opcje zaawansowane.

    Zrzut ekranu przedstawiający zaawansowane opcje tworzenia projektu.

  4. Wybierz Utwórz.

  5. Poczekaj, aż twoje zasoby będą gotowe.

    1. Zostanie utworzone konto i projekt (zasób podrzędny twojego konta).
    2. Model gpt-4o zostanie automatycznie wdrożony
    3. Zostanie utworzony domyślny agent

  6. Po zakończeniu nastąpi bezpośrednie miejsce na placu zabaw agenta i możesz rozpocząć tworzenie agentów. Możesz przekazać agentowi instrukcje dotyczące tego, co należy zrobić i jak to zrobić. Na przykład: "Jesteś pomocnym agentem, który może odpowiedzieć na pytania dotyczące lokalizacji geograficznej". Następnie możesz rozpocząć rozmowę z agentem.

    Zrzut ekranu przedstawiający plac zabaw agenta.

    Uwaga / Notatka

    Jeśli podczas próby skonfigurowania lub utworzenia agentów wystąpi błąd uprawnień, upewnij się, że masz użytkownika usługi Azure AI w projekcie.

| Dokumentacja referencyjna | Przykłady | Kod źródłowy biblioteki | Pakiet (NuGet) |

Wymagania wstępne

Konfigurowanie i uruchamianie agenta

Utwórz projekt konsoli .NET.

dotnet new console

Zainstaluj pakiet .NET w projekcie. Jeśli na przykład używasz interfejsu wiersza polecenia platformy .NET, uruchom następujące polecenie.

dotnet add package Azure.AI.Agents.Persistent
dotnet add package Azure.Identity

Następnie, aby uwierzytelnić żądania interfejsu API i uruchomić program, użyj polecenia az login , aby zalogować się do subskrypcji platformy Azure.

az login

Użyj poniższego kodu, aby utworzyć i uruchomić agenta. Aby uruchomić ten kod, musisz uzyskać punkt końcowy dla projektu. Ten ciąg ma format:

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

Ważna

Począwszy od maja 2025 r., usługa agenta AI platformy Azure używa punktu końcowego dla projektów Foundry zamiast parametrów połączenia, które były wcześniej używane w projektach opartych na centrum. Jeśli używasz projektu opartego na centrum, nie będzie można używać bieżących wersji zestawu SDK i interfejsu API REST. Aby uzyskać więcej informacji, zobacz Użycie zestawu SDK z projektami opartymi na centrum.

Punkt końcowy można znaleźć w przeglądzie projektu w portalu Microsoft Foundry w obszarze Biblioteki>foundry.

Zrzut ekranu przedstawiający punkt końcowy w portalu Foundry.

Ustaw ten punkt końcowy w zmiennej środowiskowej o nazwie ProjectEndpoint.

Potrzebna jest również nazwa wdrożenia modelu. Można je znaleźć w menu nawigacji po lewej stronie w obszarze Modele i punkty końcowe .

Zrzut ekranu przedstawiający ekran wdrażania modelu w portalu Foundry.

Zapisz nazwę wdrożenia modelu jako zmienną środowiskową o nazwie 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);

| Dokumentacja referencyjna | Przykłady | Kod źródłowy biblioteki | Pakiet (PyPi) |

Wymagania wstępne

Konfigurowanie i uruchamianie agenta

Uruchom następujące polecenia, aby zainstalować pakiety języka Python.

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

Następnie, aby uwierzytelnić żądania interfejsu API i uruchomić program, użyj polecenia az login , aby zalogować się do subskrypcji platformy Azure.

az login

Użyj poniższego kodu, aby utworzyć i uruchomić agenta. Aby uruchomić ten kod, musisz uzyskać punkt końcowy dla projektu. Ten ciąg ma format:

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

Ważna

Począwszy od maja 2025 r., usługa agenta AI platformy Azure używa punktu końcowego dla projektów Foundry zamiast parametrów połączenia, które były wcześniej używane w projektach opartych na centrum. Jeśli używasz projektu opartego na centrum, nie będzie można używać bieżących wersji zestawu SDK i interfejsu API REST. Aby uzyskać więcej informacji, zobacz Użycie zestawu SDK z projektami opartymi na centrum.

Punkt końcowy można znaleźć w przeglądzie projektu w portalu Microsoft Foundry w obszarze Biblioteki>foundry.

Zrzut ekranu przedstawiający punkt końcowy w portalu Foundry.

Ustaw ten punkt końcowy jako zmienną środowiskową o nazwie PROJECT_ENDPOINT.

Potrzebna jest również nazwa wdrożenia modelu. Można je znaleźć w menu nawigacji po lewej stronie w obszarze Modele i punkty końcowe .

Zrzut ekranu przedstawiający ekran wdrażania modelu w portalu Foundry.

Zapisz nazwę wdrożenia modelu jako zmienną środowiskową o nazwie 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")

| Dokumentacja referencyjna | Przykłady | Kod źródłowy biblioteki | Pakiet (npm) |

Wymagania wstępne

Konfigurowanie i uruchamianie agenta

Kluczowe obiekty w tym kodzie obejmują:

Najpierw zainicjuj nowy projekt TypeScript, uruchamiając polecenie:

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

Uruchom następujące polecenia, aby zainstalować wymagane pakiety npm.

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

Następnie, aby uwierzytelnić żądania interfejsu API i uruchomić program, użyj polecenia az login , aby zalogować się do subskrypcji platformy Azure.

az login

Użyj poniższego kodu, aby odpowiedzieć na pytanie I need to solve the equation '3x + 11 = 14'. Can you help me?matematyczne . Aby uruchomić ten kod, musisz uzyskać punkt końcowy dla projektu. Ten ciąg ma format:

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

Punkt końcowy można znaleźć w przeglądzie projektu w portalu Microsoft Foundry w obszarze Biblioteki>foundry.

Zrzut ekranu przedstawiający punkt końcowy w portalu Foundry.

Ustaw ten punkt końcowy jako zmienną środowiskową o nazwie PROJECT_ENDPOINT w .env pliku.

Potrzebna jest również nazwa wdrożenia modelu. Można je znaleźć w menu nawigacji po lewej stronie w obszarze Modele i punkty końcowe .

Zrzut ekranu przedstawiający ekran wdrażania modelu w portalu Foundry.

Zapisz nazwę wdrożenia modelu jako zmienną środowiskową o nazwie MODEL_DEPLOYMENT_NAME.

Ważna

  • Ten kod startowy używa zmiennych środowiskowych w celach konfiguracyjnych wymagających poufności. Nigdy nie zatwierdzaj pliku .env do kontroli wersji, po upewnieniu się, że .env znajduje się na liście w pliku .gitignore.
  • Pamiętaj: jeśli przypadkowo zatwierdzisz poufne informacje, uznaj te poświadczenia za naruszone i natychmiast je zmień.

Utwórz plik tsconfig.json o następującej zawartości:

{
  "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,
  }
}

Następnie utwórz index.ts plik i wklej następujący kod:

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

Uruchom kod przy użyciu polecenia npx tsx -r dotenv/config index.ts. Ten kod odpowiada na pytanie I need to solve the equation '3x + 11 = 14'. Can you help me?. Odpowiedzi nie są deterministyczne. Dane wyjściowe będą wyglądać podobnie do poniższych danych wyjściowych:

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 ======================
========================================================

Dostępny jest pełny przykładowy kod źródłowy .

| Dokumentacja referencyjna | Próbki | Kod | Pakiet (Maven) |

Wymagania wstępne

Konfigurowanie i uruchamianie agenta

Najpierw utwórz nowy projekt konsoli Java. Do uruchomienia kodu potrzebne będą następujące zależności:

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

Następnie, aby uwierzytelnić żądania interfejsu API i uruchomić program, użyj polecenia az login , aby zalogować się do subskrypcji platformy Azure.

az login

Użyj poniższego kodu, aby utworzyć i uruchomić agenta. Aby uruchomić ten kod, musisz uzyskać punkt końcowy dla projektu. Ten ciąg ma format:

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

Ważna

Począwszy od maja 2025 r., usługa agenta AI platformy Azure używa punktu końcowego dla projektów Foundry zamiast parametrów połączenia, które były wcześniej używane w projektach opartych na centrum. Jeśli używasz projektu opartego na centrum, nie będzie można używać bieżących wersji zestawu SDK i interfejsu API REST. Aby uzyskać więcej informacji, zobacz Użycie zestawu SDK z projektami opartymi na centrum.

Punkt końcowy można znaleźć w przeglądzie projektu w portalu Microsoft Foundry w obszarze Biblioteki>foundry.

Zrzut ekranu przedstawiający punkt końcowy w portalu Foundry.

Ustaw ten punkt końcowy w zmiennej środowiskowej o nazwie PROJECT_ENDPOINT.

Potrzebna jest również nazwa wdrożenia modelu. Można je znaleźć w menu nawigacji po lewej stronie w obszarze Modele i punkty końcowe .

Zrzut ekranu przedstawiający ekran wdrażania modelu w portalu Foundry.

Zapisz nazwę wdrożenia modelu jako zmienną środowiskową o nazwie MODEL_DEPLOYMENT_NAME.

Przykład kodu

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

| Dokumentacja referencyjna |

Wymagania wstępne

Konfigurowanie i uruchamianie agenta

Aby uwierzytelnić żądania interfejsu API, użyj polecenia az login , aby zalogować się do subskrypcji platformy Azure.

az login

Następnie należy pobrać token Entra ID, aby podać go jako autoryzację do wywołań interfejsu API. Pobierz token przy użyciu polecenia CLI:

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

Ustaw token dostępu jako zmienną środowiskową o nazwie AGENT_TOKEN.

Aby pomyślnie wykonać wywołania interfejsu API REST do usługi agenta Foundry, należy użyć punktu końcowego projektu:

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

Na przykład punkt końcowy będzie wyglądać następująco:

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

Ustaw ten punkt końcowy jako zmienną środowiskową o nazwie AZURE_AI_FOUNDRY_PROJECT_ENDPOINT.

Uwaga / Notatka

  • W przypadku api-version parametru wersja interfejsu API ogólnie dostępnego jest 2025-05-01 i najnowsza wersja interfejsu API w wersji zapoznawczej to 2025-05-15-preview. Musisz użyć interfejsu API w wersji zapoznawczej dla narzędzi, które są dostępne w wersji zapoznawczej.
  • Rozważ ustawienie wersji interfejsu API jako zmiennej środowiskowej, takiej jak $API_VERSION.

Utwórz agenta

Uwaga / Notatka

W przypadku usługi Azure AI Agents parametr model wymaga nazwy wdrożenia modelu. Jeśli nazwa wdrożenia modelu jest inna niż nazwa modelu bazowego, należy dostosować kod do "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"
  }'

Tworzenie wątku

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 ''

Dodawanie pytania użytkownika do wątku

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?"
    }'

Uruchom wątek

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",
  }'

Pobierz status przebiegu

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"

Pobieranie odpowiedzi agenta

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

Dalsze kroki

Dowiedz się więcej o narzędziach , których można użyć do rozszerzania możliwości agentów, takich jak uzyskiwanie dostępu do internetu, udostępnianie informacji podstawowych i nie tylko.

  • Last updated on