Inicio rápido: Creación de un nuevo agente

Note

Este documento hace referencia al portal de Microsoft Foundry (clásico).

🔍 Consulte la documentación de Microsoft Foundry (nuevo) para obtener información sobre el nuevo portal.

Note

Esta guía rápida de inicio es para la versión anterior de los agentes. Consulte el inicio rápido de Microsoft Foundry para usar la nueva versión de la API.

Foundry Agent Service le permite crear agentes de inteligencia artificial adaptados a sus necesidades mediante instrucciones personalizadas y aumentadas por herramientas avanzadas como el intérprete de código y las funciones personalizadas.

Prerequisites

Una suscripción de Azure: cree una gratuitamente.
Asegúrese de que la persona que crea la cuenta y el proyecto tiene el rol propietario de la cuenta de Azure AI en el ámbito de la suscripción, que concederá los permisos necesarios para crear el proyecto.
- Como alternativa, tener el rol Colaborador o Colaborador de Cognitive Services en el nivel de suscripción permitirá la creación del proyecto.
Una vez creado el proyecto, asegúrese de que la persona que crea el agente dentro del proyecto tiene el rol usuario de Azure AI en el nivel de proyecto.

Important

El portal de Microsoft Foundry solo admite la configuración básica del agente en este momento. Si desea realizar una configuración de agente estándar, consulte el artículo Configuración del entorno para obtener más información.

Creación de una cuenta y un proyecto de Foundry en el portal de Foundry

Para crear una cuenta y un proyecto en Foundry, siga estos pasos:

Vaya a Foundry. Si está en un proyecto, seleccione Foundry en la parte superior izquierda de la página para ir a la página Principal.
Use el flujo de creación de introducción del agente para obtener la experiencia más rápida. Haga clic en Crear un agente.
Escriba un nombre para el proyecto. Si desea personalizar los valores predeterminados, seleccione Opciones avanzadas.
Selecciona Crear.
Espere a que se aprovisionen los recursos.
1. Se creará una cuenta y un proyecto (recurso secundario de la cuenta).
2. El modelo gpt-4o se implementará automáticamente.
3. Se creará un agente predeterminado.
Una vez completado, llegará directamente al área de juegos del agente y podrá empezar a crear agentes. Puede proporcionar instrucciones al agente sobre qué hacer y cómo hacerlo. Por ejemplo: "Usted es un agente útil que puede responder preguntas sobre geografía". A continuación, puede empezar a chatear con el agente.

Note

Si recibe un error de permiso al intentar configurar o crear agentes, asegúrese de que tiene el usuario de Azure AI en el proyecto.

Prerequisites

Un entorno de configuración del agente
Asigne el rol RBAC de usuario de Azure AI a cada miembro del equipo que necesite crear o editar agentes mediante el SDK o el área de juegos del agente.
- Este rol debe asignarse en el ámbito del proyecto.
- Permisos mínimos necesarios: agents/*/read, agents/*/action, agents/*/delete

Configuración y ejecución de un agente

Cree un proyecto de consola de .NET.

dotnet new console

Instale el paquete de .NET en el proyecto. Por ejemplo, si usa la CLI de .NET, ejecute el siguiente comando.

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

A continuación, para autenticar las solicitudes de API y ejecutar el programa, use el comando az login para iniciar sesión en la suscripción de Azure.

az login

Use el código siguiente para crear y ejecutar un agente. Para ejecutar este código, deberá obtener el punto de conexión del proyecto. Esta cadena tiene el formato:

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

Important

A partir de mayo de 2025, el servicio de agente de Azure AI utilizará un punto de conexión para los proyectos Foundry en lugar de la cadena de conexión que se usaba anteriormente para proyectos basados en concentradores. Si usa un proyecto basado en concentrador, no podrá usar las versiones actuales del SDK y la API REST. Para más información, consulte Uso del SDK con proyectos basados en concentradores.

Puede encontrar el punto de conexión en la información general del proyecto en el portal de Microsoft Foundry, en Bibliotecas>Foundry.

Establezca este punto de conexión en una variable de entorno denominada ProjectEndpoint.

También necesita el nombre de implementación del modelo. Puede encontrarlo en Modelos y puntos de conexión en el menú de navegación izquierdo.

Guarde el nombre del nombre de implementación del modelo como una variable de entorno denominada 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

Un entorno de configuración del agente
Asigne el rol RBAC de usuario de Azure AI a cada miembro del equipo que necesite crear o editar agentes mediante el SDK o el área de juegos del agente.
- Este rol debe asignarse en el ámbito del proyecto.
- Permisos mínimos necesarios: agents/*/read, agents/*/action, agents/*/delete

Configuración y ejecución de un agente

Ejecute los siguientes comandos para instalar los paquetes de Python.

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

A continuación, para autenticar las solicitudes de API y ejecutar el programa, use el comando az login para iniciar sesión en la suscripción de Azure.

az login

Use el código siguiente para crear y ejecutar un agente. Para ejecutar este código, deberá obtener el punto de conexión del proyecto. Esta cadena tiene el formato:

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

Important

Puede encontrar el punto de conexión en la información general del proyecto en el portal de Microsoft Foundry, en Bibliotecas>Foundry.

Establezca este punto de conexión como una variable de entorno denominada PROJECT_ENDPOINT.

También necesita el nombre de implementación del modelo. Puede encontrarlo en Modelos y puntos de conexión en el menú de navegación izquierdo.

Guarde el nombre del nombre de implementación del modelo como una variable de entorno denominada 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

Un entorno de configuración del agente
Asigne el rol RBAC de usuario de Azure AI a cada miembro del equipo que necesite crear o editar agentes mediante el SDK o el área de juegos del agente.
- Este rol debe asignarse en el ámbito del proyecto.
- Permisos mínimos necesarios: agents/*/read, agents/*/action, agents/*/delete

Node.js LTS

Configuración y ejecución de un agente

Entre los objetos clave de este código se incluyen:

AgentsClient

En primer lugar, inicialice un nuevo proyecto de TypeScript ejecutando:

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

Ejecute los comandos siguientes para instalar los paquetes de npm necesarios.

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

A continuación, para autenticar las solicitudes de API y ejecutar el programa, use el comando az login para iniciar sesión en la suscripción de Azure.

az login

Use el código siguiente para responder a la pregunta I need to solve the equation '3x + 11 = 14'. Can you help me?matemática . Para ejecutar este código, deberá obtener el punto de conexión del proyecto. Esta cadena tiene el formato:

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

Puede encontrar el punto de conexión en la información general del proyecto en el portal de Microsoft Foundry, en Bibliotecas>Foundry.

Establezca este punto de conexión como una variable de entorno denominada PROJECT_ENDPOINT en un .env archivo.

También necesita el nombre de implementación del modelo. Puede encontrarlo en Modelos y puntos de conexión en el menú de navegación izquierdo.

Guarde el nombre del nombre de implementación del modelo como una variable de entorno denominada MODEL_DEPLOYMENT_NAME.

Important

Este código de inicio rápido usa variables de entorno para la configuración confidencial. No confirme nunca el .env archivo en el control de versiones asegurándose de que .env aparece en el .gitignore archivo.
Recuerde: Si confirma accidentalmente información confidencial, tenga en cuenta esas credenciales comprometidas y rotarlas inmediatamente.

Cree un archivo tsconfig.json con el siguiente contenido:

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

A continuación, cree un index.ts archivo y pegue el código siguiente:

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

Ejecute el código mediante npx tsx -r dotenv/config index.ts. Este código responde a la pregunta I need to solve the equation '3x + 11 = 14'. Can you help me?. Las respuestas no son deterministas, la salida tendrá un aspecto similar al siguiente:

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

Código fuente de ejemplo completo disponible.

Prerequisites

Un entorno de configuración del agente
Asigne el rol RBAC de usuario de Azure AI a cada miembro del equipo que necesite crear o editar agentes mediante el SDK o el área de juegos del agente.
- Este rol debe asignarse en el ámbito del proyecto.
- Permisos mínimos necesarios: agents/*/read, agents/*/action, agents/*/delete

Configuración y ejecución de un agente

En primer lugar, cree un nuevo proyecto de consola de Java. Necesitará las siguientes dependencias para ejecutar el código:

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

A continuación, para autenticar las solicitudes de API y ejecutar el programa, use el comando az login para iniciar sesión en la suscripción de Azure.

az login

Use el código siguiente para crear y ejecutar un agente. Para ejecutar este código, deberá obtener el punto de conexión del proyecto. Esta cadena tiene el formato:

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

Important

Puede encontrar el punto de conexión en la información general del proyecto en el portal de Microsoft Foundry, en Bibliotecas>Foundry.

Establezca este punto de conexión en una variable de entorno denominada PROJECT_ENDPOINT.

También necesita el nombre de implementación del modelo. Puede encontrarlo en Modelos y puntos de conexión en el menú de navegación izquierdo.

Guarde el nombre del nombre de implementación del modelo como una variable de entorno denominada MODEL_DEPLOYMENT_NAME.

Ejemplo de código

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

| Documentación de referencia |

Prerequisites

Un entorno de configuración del agente
Asigne el rol RBAC de usuario de Azure AI a cada miembro del equipo que necesite crear o editar agentes mediante el SDK o el área de juegos del agente.
- Este rol debe asignarse en el ámbito del proyecto.
- Permisos mínimos necesarios: agents/*/read, agents/*/action, agents/*/delete

Configuración y ejecución de un agente

Para autenticar las solicitudes de API, use el comando az login para iniciar sesión en la suscripción de Azure.

az login

A continuación, deberá obtener el token de Entra ID para autorizar las llamadas a la API. Capture el token mediante el comando de la CLI:

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

Establezca el token de acceso como una variable de entorno denominada AGENT_TOKEN.

Para realizar correctamente llamadas api REST al servicio del agente Foundry, deberá usar el punto de conexión del proyecto:

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

Por ejemplo, el punto de conexión tendrá un aspecto similar al siguiente:

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

Establezca este punto de conexión como una variable de entorno denominada AZURE_AI_FOUNDRY_PROJECT_ENDPOINT.

Note

Para el parámetro api-version, la versión de la API de disponibilidad general es 2025-05-01 y la versión más reciente de la API en versión preliminar es 2025-05-15-preview. Debe usar la API de versión preliminar para las herramientas que están en versión preliminar.
Considere la posibilidad de convertir la versión de la API en una variable de entorno, como $API_VERSION.

Crear un agente

Note

Con Azure AI Agents Service, el parámetro model requiere el nombre de implementación de modelo. Si el nombre de implementación del modelo es diferente del nombre del modelo subyacente, ajustaría el código a "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"
  }'

Crear un hilo

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

Añade una pregunta de usuario al hilo

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

Ejecución del subproceso

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

Recuperación del estado de la ejecución

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"

Recuperación de la respuesta del agente

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

Pasos siguientes

Obtenga información sobre las herramientas que puede usar para ampliar las funcionalidades de los agentes, como el acceso a la web, proporcionar información básica y mucho más.

Comentarios

¿Le ha resultado útil esta página?

Last updated on 2025-12-03

Compartir a través de

Inicio rápido: Creación de un nuevo agente

Prerequisites

Creación de una cuenta y un proyecto de Foundry en el portal de Foundry

Prerequisites

Configuración y ejecución de un agente

Prerequisites

Configuración y ejecución de un agente

Prerequisites

Configuración y ejecución de un agente

Prerequisites

Configuración y ejecución de un agente

Ejemplo de código

Prerequisites

Configuración y ejecución de un agente

Crear un agente

Crear un hilo

Añade una pregunta de usuario al hilo

Ejecución del subproceso

Recuperación del estado de la ejecución

Recuperación de la respuesta del agente

Pasos siguientes

Comentarios

Recursos adicionales