Condividi tramite

Introduzione rapida: Creare un nuovo agente

Note

Questo documento fa riferimento al portale di Microsoft Foundry (versione classica).

🔍Per informazioni sul nuovo portale, vedere la documentazione di Microsoft Foundry (nuova).

Note

Questa guida rapida si riferisce alla versione precedente degli agenti. Consulta la guida introduttiva di Microsoft Foundry per usare la nuova versione dell'API.

Il servizio agente Foundry consente di creare agenti di intelligenza artificiale personalizzati in base alle proprie esigenze tramite istruzioni personalizzate e aumentata da strumenti avanzati come interprete del codice e funzioni personalizzate.

Prerequisites

  • Una sottoscrizione di Azure: crearne una gratuitamente.
  • Assicurarsi che l'utente che crea l'account e il progetto abbia il ruolo di Azure AI Account Owner nell'ambito della sottoscrizione, che conceda le autorizzazioni necessarie per la creazione del progetto.
    • In alternativa, avere il ruolo Collaboratore o Collaboratore Servizi cognitivi a livello di sottoscrizione consentirà la creazione del progetto
  • Dopo aver creato il progetto, assicurarsi che l'utente che crea l'agente all'interno del progetto abbia il ruolo Utente di Intelligenza artificiale di Azure a livello di progetto

Important

Il portale di Microsoft Foundry supporta attualmente solo la configurazione dell'agente di base. Per eseguire una configurazione standard dell'agente, vedere l'articolo Configurazione dell'ambiente per altre informazioni.

Creare un account e un progetto Foundry nel portale foundry

Per creare un account e un progetto in Foundry, seguire questa procedura:

  1. Vai a Foundry. Se si è in un progetto, selezionare Foundry in alto a sinistra della pagina per passare alla home page.

  2. Usare il flusso di creazione attività iniziali dell'agente per un'esperienza più rapida. Fare clic su Crea un agente.

    Screenshot del portale Foundry.

  3. Immettere un nome per il progetto. Per personalizzare i valori predefiniti, selezionare Opzioni avanzate.

    Screenshot delle opzioni avanzate per la creazione di un progetto.

  4. Fare clic su Crea.

  5. Attendere che le risorse siano fornite.

    1. Verrà creato un account e un progetto (risorsa figlio dell'account).
    2. Il modello gpt-4o verrà distribuito automaticamente
    3. Verrà creato un agente predefinito

  6. Al termine, atterrerai direttamente nel playground degli agenti e potrai iniziare a creare agenti. È possibile fornire all'agente istruzioni su cosa fare e come farlo. Ad esempio: "Si è un agente utile che può rispondere a domande sulla geografia". È quindi possibile iniziare a chattare con l'agente.

    Screenshot del playground dell'agente.

    Note

    Se si riceve un errore di autorizzazione durante il tentativo di configurare o creare agenti, assicurarsi di disporre dell'utente di Intelligenza artificiale di Azure nel progetto.

| Documentazione di riferimento | Esempi | Codice sorgente della libreria | Pacchetto (NuGet) |

Prerequisites

  • Ambiente dell'agente configurato
  • Assegnare il ruolo Controllo degli accessi in base al ruolo dell'utente di Piattaforma di Azure AI a ogni membro del team che deve creare o modificare gli agenti usando l'SDK o Agent Playground
    • Questo ruolo deve essere assegnato nell'ambito del progetto
    • Autorizzazioni minime necessarie: agents/*/read, agents/*/action, agents/*/delete

Configurare ed eseguire un agente

Creare un progetto console .NET.

dotnet new console

Installare il pacchetto .NET nel progetto. Ad esempio, se si usa l'interfaccia della riga di comando di .NET, eseguire il comando seguente.

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

Successivamente, per autenticare le richieste API ed eseguire il programma, usare il comando az login per accedere alla sottoscrizione di Azure.

az login

Usare il codice seguente per creare ed eseguire un agente. Per eseguire questo codice, sarà necessario ottenere l'endpoint per il progetto. Questa stringa è nel formato:

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

Important

A partire da maggio 2025, il servizio Azure AI Agent usa un endpoint per i progetti Foundry anziché la stringa di connessione usata in precedenza per i progetti basati su hub. Se si usa un progetto basato su hub, non sarà possibile usare le versioni correnti dell'SDK e dell'API REST. Per altre informazioni, vedere Utilizzo dell'SDK con progetti basati su hub.

È possibile trovare l'endpoint nella panoramica del progetto nel portale di Microsoft Foundry, in Librerie>foundry.

Una screenshot che mostra l'endpoint nel portale Foundry.

Impostare questo endpoint in una variabile di ambiente denominata ProjectEndpoint.

È anche necessario il nome della distribuzione del modello. È possibile trovarla in Modelli + Endpoint nel menu di spostamento a sinistra.

Screenshot che mostra la schermata di distribuzione modello nel portale Foundry.

Salvare il nome della distribuzione del modello come variabile di ambiente denominata 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);

| Documentazione di riferimento | Esempi | Codice sorgente della libreria | Pacchetto (PyPi) |

Prerequisites

  • Ambiente dell'agente configurato
  • Assegnare il ruolo Controllo degli accessi in base al ruolo dell'utente di Piattaforma di Azure AI a ogni membro del team che deve creare o modificare gli agenti usando l'SDK o Agent Playground
    • Questo ruolo deve essere assegnato nell'ambito del progetto
    • Autorizzazioni minime necessarie: agents/*/read, agents/*/action, agents/*/delete

Configurare ed eseguire un agente

Eseguire i comandi seguenti per installare i pacchetti Python.

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

Successivamente, per autenticare le richieste API ed eseguire il programma, usare il comando az login per accedere alla sottoscrizione di Azure.

az login

Usare il codice seguente per creare ed eseguire un agente. Per eseguire questo codice, sarà necessario ottenere l'endpoint per il progetto. Questa stringa è nel formato:

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

Important

A partire da maggio 2025, il servizio Azure AI Agent usa un endpoint per i progetti Foundry anziché la stringa di connessione usata in precedenza per i progetti basati su hub. Se si usa un progetto basato su hub, non sarà possibile usare le versioni correnti dell'SDK e dell'API REST. Per altre informazioni, vedere Utilizzo dell'SDK con progetti basati su hub.

È possibile trovare l'endpoint nella panoramica del progetto nel portale di Microsoft Foundry, in Librerie>foundry.

Una screenshot che mostra l'endpoint nel portale Foundry.

Impostare questo endpoint come variabile di ambiente denominata PROJECT_ENDPOINT.

È anche necessario il nome della distribuzione del modello. È possibile trovarla in Modelli + Endpoint nel menu di spostamento a sinistra.

Screenshot che mostra la schermata di distribuzione modello nel portale Foundry.

Salvare il nome della distribuzione del modello come variabile di ambiente denominata 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")

| Documentazione di riferimento | Esempi | Codice sorgente della libreria | Pacchetto (npm) |

Prerequisites

  • Ambiente dell'agente configurato
  • Assegnare il ruolo Controllo degli accessi in base al ruolo dell'utente di Piattaforma di Azure AI a ogni membro del team che deve creare o modificare gli agenti usando l'SDK o Agent Playground
    • Questo ruolo deve essere assegnato nell'ambito del progetto
    • Autorizzazioni minime necessarie: agents/*/read, agents/*/action, agents/*/delete

Configurare ed eseguire un agente

Gli oggetti chiave in questo codice includono:

Per prima cosa, inizializzare un nuovo progetto TypeScript eseguendo:

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

Eseguire i comandi seguenti per installare i pacchetti npm necessari.

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

Successivamente, per autenticare le richieste API ed eseguire il programma, usare il comando az login per accedere alla sottoscrizione di Azure.

az login

Usare il codice seguente per rispondere alla domanda I need to solve the equation '3x + 11 = 14'. Can you help me?matematica . Per eseguire questo codice, è necessario ottenere l'endpoint per il progetto. Questa stringa è nel formato:

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

È possibile trovare l'endpoint nella panoramica del progetto nel portale di Microsoft Foundry, in Librerie>foundry.

Una screenshot che mostra l'endpoint nel portale Foundry.

Impostare questo endpoint come variabile di ambiente denominata PROJECT_ENDPOINT in un .env file.

È anche necessario il nome della distribuzione del modello. È possibile trovarla in Modelli + Endpoint nel menu di spostamento a sinistra.

Screenshot che mostra la schermata di distribuzione modello nel portale Foundry.

Salvare il nome della distribuzione del modello come variabile di ambiente denominata MODEL_DEPLOYMENT_NAME.

Important

  • Questo codice di avvio rapido usa le variabili di ambiente per la configurazione sensibile. Non eseguire mai il commit del file .env nel sistema di controllo delle versioni, assicurati che .env sia elencato nel file .gitignore.
  • Tenere presente che se si esegue accidentalmente il commit di informazioni riservate, prendere in considerazione le credenziali compromesse e ruotarle immediatamente.

Creare un file tsconfig.json con il contenuto seguente:

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

Creare quindi un index.ts file e incollarlo nel codice seguente:

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

Eseguire il codice usando npx tsx -r dotenv/config index.ts. Questo codice risponde alla domanda I need to solve the equation '3x + 11 = 14'. Can you help me?. Le risposte non sono deterministiche, l'output sarà simile all'output seguente:

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

Il codice sorgente di esempio completo è disponibile.

| Documentazione di riferimento | Esempi | Codice sorgente della libreria | Pacchetto (Maven) |

Prerequisites

  • Ambiente dell'agente configurato
  • Assegnare il ruolo Controllo degli accessi in base al ruolo dell'utente di Piattaforma di Azure AI a ogni membro del team che deve creare o modificare gli agenti usando l'SDK o Agent Playground
    • Questo ruolo deve essere assegnato nell'ambito del progetto
    • Autorizzazioni minime necessarie: agents/*/read, agents/*/action, agents/*/delete

Configurare ed eseguire un agente

Creare prima di tutto un nuovo progetto di console Java. Per eseguire il codice sono necessarie le dipendenze seguenti:

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

Successivamente, per autenticare le richieste API ed eseguire il programma, usare il comando az login per accedere alla sottoscrizione di Azure.

az login

Usare il codice seguente per creare ed eseguire un agente. Per eseguire questo codice, è necessario ottenere l'endpoint per il progetto. Questa stringa è nel formato:

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

Important

A partire da maggio 2025, il servizio Azure AI Agent usa un endpoint per i progetti Foundry anziché la stringa di connessione usata in precedenza per i progetti basati su hub. Se si usa un progetto basato su hub, non sarà possibile usare le versioni correnti dell'SDK e dell'API REST. Per altre informazioni, vedere Utilizzo dell'SDK con progetti basati su hub.

È possibile trovare l'endpoint nella panoramica del progetto nel portale di Microsoft Foundry, in Librerie>foundry.

Una screenshot che mostra l'endpoint nel portale Foundry.

Impostare questo endpoint in una variabile di ambiente denominata PROJECT_ENDPOINT.

È anche necessario il nome della distribuzione del modello. È possibile trovarla in Modelli + Endpoint nel menu di spostamento a sinistra.

Screenshot che mostra la schermata di distribuzione modello nel portale Foundry.

Salvare il nome della distribuzione del modello come variabile di ambiente denominata MODEL_DEPLOYMENT_NAME.

Esempio di codice

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

| Documentazione di riferimento |

Prerequisites

  • Ambiente dell'agente configurato
  • Assegnare il ruolo Controllo degli accessi in base al ruolo dell'utente di Piattaforma di Azure AI a ogni membro del team che deve creare o modificare gli agenti usando l'SDK o Agent Playground
    • Questo ruolo deve essere assegnato nell'ambito del progetto
    • Autorizzazioni minime necessarie: agents/*/read, agents/*/action, agents/*/delete

Configurare ed eseguire un agente

Per autenticare le richieste API, usare il comando az login per accedere alla sottoscrizione di Azure.

az login

Successivamente, è necessario recuperare il token ENTRA ID per fornire come autorizzazione alle chiamate API. Recuperare il token usando il comando CLI:

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

Impostare il token di accesso come variabile di ambiente denominata AGENT_TOKEN.

Per effettuare correttamente chiamate API REST al servizio Foundry Agent, è necessario usare l'endpoint del progetto:

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

Ad esempio, l'endpoint avrà un aspetto simile al seguente:

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

Impostare questo endpoint come variabile di ambiente denominata AZURE_AI_FOUNDRY_PROJECT_ENDPOINT.

Note

  • Per api-version il parametro, la versione dell'API GA è 2025-05-01 e la versione più recente dell'API di anteprima è 2025-05-15-preview. È necessario usare l'API di anteprima per gli strumenti in anteprima.
  • Prendere in considerazione la possibilità di rendere la versione dell'API una variabile di ambiente, ad esempio $API_VERSION.

Creare un agente

Note

Con il servizio Azure AI Agents il model parametro richiede il nome della distribuzione del modello. Se il nome della distribuzione del modello è diverso dal nome del modello sottostante, è necessario modificare il codice in "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"
  }'

Creare un thread

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

Aggiungere una domanda utente al 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?"
    }'

Eseguire il thread

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

Recuperare lo stato dell'esecuzione

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"

Recuperare la risposta dell'agente

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

Passaggi successivi

Informazioni sugli strumenti che è possibile usare per estendere le funzionalità degli agenti, ad esempio l'accesso al Web, fornire informazioni di base e altro ancora.

  • Last updated on