Inicio rápido: Creación de un nuevo proyecto de Servicio de Agente de Azure AI - Azure AI services

Requisitos previos

Una suscripción a Azure (cree una cuenta gratuita).
Asegúrese de que tiene asignada el Desarrollador de Azure AIRol RBAC.

Compatibilidad con la configuración básica del agente

Antes de empezar, determine si desea realizar una configuración básica del agente o una configuración de agente estándar. La Fundición de Azure AI solo admite la configuración básica del agente.

Configuración básica: los agentes usan recursos de almacenamiento y búsqueda multiinquilino totalmente administrados por Microsoft. No tiene visibilidad ni control sobre estos recursos subyacentes de Azure. Se puede crear una configuración básica mediante el Portal de la Fundición de IA de Azure o una plantilla de bicep automatizada.

Configuración estándar: los agentes usan recursos de almacenamiento y búsqueda de un solo inquilino propiedad del cliente. Con esta configuración, tiene visibilidad y control total sobre estos recursos, pero incurre en costes en función del uso. La configuración estándar solo se puede realizar mediante una plantilla de bicep automatizada.

Importante

El Portal de la Fundición de IA de Azure solo admite la configuración básica en este momento. Si desea realizar una configuración de agente estándar, use las otras pestañas de la parte superior del artículo para obtener información sobre la configuración del agente estándar.

Creación de un centro de conectividad y un proyecto en el Portal de la Fundición de IA de Azure

Para crear un nuevo centro y un proyecto, necesita el rol Propietario o Colaborador en el grupo de recursos o en un centro existente. Si no puede crear un centro debido a permisos, póngase en contacto con el administrador.

Para crear un proyecto en Azure AI Foundry, siga estos pasos:

Ir a Azure AI Foundry. Si está en un proyecto, seleccione Azure AI Foundry en la parte superior izquierda de la página para ir a la página Inicio.
Seleccione + Crear proyecto.
Escriba un nombre para el proyecto.
Si tiene un centro, verá el que ha usado más recientemente.
Si tiene acceso a más de un centro, puede seleccionar otro centro en la lista desplegable.
Si desea crear uno nuevo, seleccione Crear nuevo centro y proporcione un nombre. Si desea personalizar los valores predeterminados, consulte la Documentación de Azure AI Foundry.
Seleccione Crear.

Implementación de un modelo

Inicie sesión en Azure AI Foundry.
Vaya al proyecto o cree un nuevo proyecto en el portal de Azure AI Foundry.
En la información general del proyecto, seleccione Agentes, que se encuentra en Compilar y personalizar.
Seleccione el recurso de Azure OpenAI.
Seleccione una implementación demodelo para que use el Agente. Si no tiene uno, se abrirá una pantalla para implementar un nuevo modelo. De lo contrario, puede seleccionar Implementar un modelo.

Uso del área de juegos del agente

El Área de juegos de Agentes le permite explorar, crear prototipos y probar agentes sin necesidad de ejecutar ningún código. Desde esta página puede iterar y experimentar rápidamente con nuevas ideas.

En la pantalla Crear y depurar los agentes, seleccione el agente o cree uno nuevo con Nuevo agente. El panel Configuración de la derecha es donde puede cambiar sus parámetros y herramientas.

Opcionalmente, puede asignar un nombre al agente distinto del generado para él y agregar instrucciones para ayudar a mejorar su rendimiento. Proporcione a su agente instrucciones claras sobre qué hacer y cómo hacerlo. Incluya tareas específicas, su orden y las instrucciones especiales, como el estilo de tono o interacción.

Sugerencia

El agente puede acceder a varias herramientas, como el intérprete de código que amplía sus funcionalidades, como la capacidad de buscar en la web con Bing, ejecutar código, etc. En el panel Configuración, desplácese hacia abajo hasta Conocimiento y acción y seleccione Agregar para ver las herramientas disponibles para su uso.

Consulte también

Consulte los modelos que puede usar con agentes.

Requisitos previos

Una suscripción a Azure (cree una cuenta gratuita).
La última versión de .NET
Asegúrese de tener asignado el rol de RBACDesarrollador de Azure AI en el nivel adecuado.
Instala la CLI de Azure y la extensión de aprendizaje automático. Si ya tiene instalada la CLI, asegúrese de que está actualizada a la última versión.

Configuración de su proyecto de Agente y Centro de Azure AI

En la siguiente sección se muestra cómo configurar los recursos necesarios para dar los primeros pasos con Azure AI Agent Service:

Creación de un Centro de Azure AI para configurar el entorno de su aplicación y los recursos de Azure.
La creación de un proyecto de Azure AI en su Centro crea un punto de conexión al que puede llamar su aplicación y configura los servicios de la aplicación para acceder a los recursos de su inquilino.
Conexión de un recurso de Azure OpenAI o un recurso de Servicios de Azure AI

Elegir configuración básica o estándar del agente

Configuración básica: los agentes usan recursos de almacenamiento y búsqueda multiinquilino totalmente administrados por Microsoft. No tiene visibilidad ni control sobre estos recursos subyacentes de Azure.

Configuración estándar: los agentes usan recursos de almacenamiento y búsqueda de un solo inquilino propiedad del cliente. Con esta configuración, tiene visibilidad y control total sobre estos recursos, pero incurre en costes en función del uso.

Nota

Puede usar las siguientes plantillas de bicep automatizadas para realizar un agente estándar o básico. También puede crear un agente básico mediante el Portal de la Fundición de IA de Azure. La Fundición de IA de Azure no admite actualmente la configuración del agente estándar.

Descripción e implementación automática	Diagrama (haga clic para acercar)
Implemente una configuración básica del agente que use identidad administrada para la autenticación. Los recursos para el centro de IA, el proyecto de IA, la cuenta de almacenamiento y los servicios de IA se crean por usted. La cuenta de Servicios de IA se conecta a su proyecto y centro y se implementa un modelo gpt-4o-mini en la región de eastus. De forma predeterminada, se usa un almacén de claves administrado por Microsoft.
Implemente una configuración estándar del agente que use identidad administrada para la autenticación. Los recursos para el centro de IA, el proyecto de IA, el almacén de claves, la cuenta de almacenamiento, los servicios de IA y la Búsqueda de IA se crean por usted. Los Servicios de IA, la Búsqueda de IA, el almacén de claves y la cuenta de almacenamiento están conectados a su proyecto y a su centro. Un modelo gpt-4o-mini se implementa en la región de eastus.

Descripción e implementación automática

Diagrama (haga clic para acercar)

Implemente una configuración básica del agente que use identidad administrada para la autenticación. Los recursos para el centro de IA, el proyecto de IA, la cuenta de almacenamiento y los servicios de IA se crean por usted.

La cuenta de Servicios de IA se conecta a su proyecto y centro y se implementa un modelo gpt-4o-mini en la región de eastus. De forma predeterminada, se usa un almacén de claves administrado por Microsoft.

Implemente una configuración estándar del agente que use identidad administrada para la autenticación.

Los recursos para el centro de IA, el proyecto de IA, el almacén de claves, la cuenta de almacenamiento, los servicios de IA y la Búsqueda de IA se crean por usted.

Los Servicios de IA, la Búsqueda de IA, el almacén de claves y la cuenta de almacenamiento están conectados a su proyecto y a su centro. Un modelo gpt-4o-mini se implementa en la región de eastus.

[Opcional] Selección de modelos en plantilla de implementación automática

Puede personalizar el modelo usando su agente editando los parámetros del modelo en la plantilla de implementación automática. Para implementar un modelo diferente, es necesario actualizar al menos los parámetros modelName y modelVersion.

De manera predeterminada, la plantilla de implementación está configurada con los siguientes valores:

Parámetro del modelo	Valor predeterminado
modelName	gpt-4o-mini
modelFormat	OpenAI (para Azure OpenAI)
modelVersion	2024-07-18
modelSkuName	GlobalStandard
modelLocation	estado

Importante

No cambie el parámetro modelFormat.

Las plantillas solo admiten con la implementación de modelos de Azure OpenAI. Consulte qué modelos de OpenAI son compatibles en la documentación de Modelos compatibles con el modelo de Azure AI Agent Service.

[Opcional] Use sus propios recursos en la configuración del agente

Nota

Si usa un recurso de AI Services o Azure OpenAI existente, no se implementará ningún modelo. Puede implementar un modelo en el recurso una vez completada la configuración del agente.

Use un recurso de AI Services, Azure OpenAI, una cuenta de almacenamiento o una instancia de Búsqueda de Azure AI o Azure Blob Storage existente, para lo que debe especificar el identificador completo del recurso de arm en el archivo de parámetros:

aiServiceAccountResourceId
aiSearchServiceResourceId
aiStorageAccountResourceId

Si desea usar un recurso de Azure OpenAI existente, deberá actualizar los parámetros aiServiceAccountResourceId y aiServiceKind en el archivo de parámetros. El parámetro aiServiceKind debe establecerse en AzureOpenAI.

Para más información, consulte Uso de recursos propios.

Configuración y ejecución de un agente

Componente	Descripción
Agente	IA personalizada que usa modelos de IA junto con herramientas.
Herramienta	Las herramientas ayudan a ampliar la capacidad de un agente para responder con fiabilidad y precisión durante una conversación. Por ejemplo, conectando con bases de conocimientos definidas por el usuario para fundamentar el modelo, o habilitando la búsqueda en la Web para proporcionar información actualizada.
Subproceso	Una sesión de conversación entre un agente y un usuario. Los subprocesos almacenan mensajes y controlan automáticamente el truncamiento para ajustar el contenido a un contexto del modelo.
Mensaje	Un mensaje creado por un agente o un usuario. Los mensajes pueden incluir texto, imágenes y otros archivos. Los mensajes se almacenan como una lista en el subproceso.
Ejecutar	Activación de un agente para empezar a ejecutarse en función del contenido de la conversación. El agente usa su configuración y los mensajes de la conversación para realizar tareas llamando a modelos y herramientas. Como parte de una ejecución, el agente anexa mensajes a la conversación.
Paso de ejecución	Una lista detallada de los pasos que tomó el agente como parte de una ejecución. Un agente puede llamar a herramientas o crear mensajes durante su ejecución. Examinar los pasos de ejecución le permite comprender cómo el agente obtiene sus resultados.

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

Consola

dotnet add package Azure.AI.Projects
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.

Azure CLI

az login

Use el código siguiente para crear y ejecutar un agente. Para ejecutar este código, deberá crear una cadena de conexión usando la información de su proyecto. Esta cadena tiene el formato:

<HostName>;<AzureSubscriptionId>;<ResourceGroup>;<ProjectName>

Sugerencia

También puede encontrar su cadena de conexión en la información general de su proyecto en el portal de Azure AI Foundry, en Detalles del proyecto>Cadena de conexión del proyecto.

HostName puede encontrarse navegando hasta su discovery_url y eliminando el https:// inicial y el /discovery final. Para buscar discovery_url, ejecute este comando de la CLI:

Azure CLI

az ml workspace show -n {project_name} --resource-group {resource_group_name} --query discovery_url

Por ejemplo, la cadena de conexión puede tener un aspecto similar al siguiente:

eastus.api.azureml.ms;12345678-abcd-1234-9fc6-62780b3d3e05;my-resource-group;my-project-name

Establezca esta cadena de conexión como una variable de entorno denominada PROJECT_CONNECTION_STRING.

C#

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

#nullable disable

using Azure.Identity;

namespace Azure.AI.Projects.Tests;

public class Sample_Agent
{
    static async Task Main()
    {
        var connectionString = Environment.GetEnvironmentVariable("PROJECT_CONNECTION_STRING");

        AgentsClient client = new AgentsClient(connectionString, new DefaultAzureCredential());

        // Step 1: Create an agent
        Response<Agent> agentResponse = await client.CreateAgentAsync(
            model: "gpt-4o-mini",
            name: "My Agent",
            instructions: "You are a helpful agent.",
            tools: new List<ToolDefinition> { new CodeInterpreterToolDefinition() });
        Agent agent = agentResponse.Value;

        // Intermission: agent should now be listed

        Response<PageableList<Agent>> agentListResponse = await client.GetAgentsAsync();

        //// Step 2: Create a thread
        Response<AgentThread> threadResponse = await client.CreateThreadAsync();
        AgentThread thread = threadResponse.Value;

        // Step 3: Add a message to a thread
        Response<ThreadMessage> messageResponse = await client.CreateMessageAsync(
            thread.Id,
            MessageRole.User,
            "I need to solve the equation `3x + 11 = 14`. Can you help me?");
        ThreadMessage message = messageResponse.Value;

        // Intermission: message is now correlated with thread
        // Intermission: listing messages will retrieve the message just added

        Response<PageableList<ThreadMessage>> messagesListResponse = await client.GetMessagesAsync(thread.Id);
        //Assert.That(messagesListResponse.Value.Data[0].Id == message.Id);

        // Step 4: Run the agent
        Response<ThreadRun> runResponse = await client.CreateRunAsync(
            thread.Id,
            agent.Id,
            additionalInstructions: "");
        ThreadRun run = runResponse.Value;

        do
        {
            await Task.Delay(TimeSpan.FromMilliseconds(500));
            runResponse = await client.GetRunAsync(thread.Id, runResponse.Value.Id);
        }
        while (runResponse.Value.Status == RunStatus.Queued
            || runResponse.Value.Status == RunStatus.InProgress);

        Response<PageableList<ThreadMessage>> afterRunMessagesResponse
            = await client.GetMessagesAsync(thread.Id);
        IReadOnlyList<ThreadMessage> messages = afterRunMessagesResponse.Value.Data;

        // Note: messages iterate from newest to oldest, with the messages[0] being the most recent
        foreach (ThreadMessage threadMessage in messages)
        {
            Console.Write($"{threadMessage.CreatedAt:yyyy-MM-dd HH:mm:ss} - {threadMessage.Role,10}: ");
            foreach (MessageContent contentItem in threadMessage.ContentItems)
            {
                if (contentItem is MessageTextContent textItem)
                {
                    Console.Write(textItem.Text);
                }
                else if (contentItem is MessageImageFileContent imageFileItem)
                {
                    Console.Write($"<image from ID: {imageFileItem.FileId}");
                }
                Console.WriteLine();
            }
        }
    }
}

Requisitos previos

Una suscripción a Azure (cree una cuenta gratuita).
Python 3.8 o versiones posteriores
Asegúrese de tener asignado el rol de RBACDesarrollador de Azure AI en el nivel adecuado.
Instala la CLI de Azure y la extensión de aprendizaje automático. Si ya tiene instalada la CLI, asegúrese de que está actualizada a la última versión.

Configuración de su proyecto de Agente y Centro de Azure AI

En la siguiente sección se muestra cómo configurar los recursos necesarios para dar los primeros pasos con Azure AI Agent Service:

Creación de un Centro de Azure AI para configurar el entorno de su aplicación y los recursos de Azure.
La creación de un proyecto de Azure AI en su Centro crea un punto de conexión al que puede llamar su aplicación y configura los servicios de la aplicación para acceder a los recursos de su inquilino.
Conexión de un recurso de Azure OpenAI o un recurso de Servicios de Azure AI

Elegir configuración básica o estándar del agente

Configuración básica: los agentes usan recursos de almacenamiento y búsqueda multiinquilino totalmente administrados por Microsoft. No tiene visibilidad ni control sobre estos recursos subyacentes de Azure.

Configuración estándar: los agentes usan recursos de almacenamiento y búsqueda de un solo inquilino propiedad del cliente. Con esta configuración, tiene visibilidad y control total sobre estos recursos, pero incurre en costes en función del uso.

Nota

Puede usar las siguientes plantillas de bicep automatizadas para realizar un agente estándar o básico. También puede crear un agente básico mediante el Portal de la Fundición de IA de Azure. La Fundición de IA de Azure no admite actualmente la configuración del agente estándar.

Descripción e implementación automática	Diagrama (haga clic para acercar)
Implemente una configuración básica del agente que use identidad administrada para la autenticación. Los recursos para el centro de IA, el proyecto de IA, la cuenta de almacenamiento y los servicios de IA se crean por usted. La cuenta de Servicios de IA se conecta a su proyecto y centro y se implementa un modelo gpt-4o-mini en la región de eastus. De forma predeterminada, se usa un almacén de claves administrado por Microsoft.
Implemente una configuración estándar del agente que use identidad administrada para la autenticación. Los recursos para el centro de IA, el proyecto de IA, el almacén de claves, la cuenta de almacenamiento, los servicios de IA y la Búsqueda de IA se crean por usted. Los Servicios de IA, la Búsqueda de IA, el almacén de claves y la cuenta de almacenamiento están conectados a su proyecto y a su centro. Un modelo gpt-4o-mini se implementa en la región de eastus.

Descripción e implementación automática

Diagrama (haga clic para acercar)

Implemente una configuración básica del agente que use identidad administrada para la autenticación. Los recursos para el centro de IA, el proyecto de IA, la cuenta de almacenamiento y los servicios de IA se crean por usted.

La cuenta de Servicios de IA se conecta a su proyecto y centro y se implementa un modelo gpt-4o-mini en la región de eastus. De forma predeterminada, se usa un almacén de claves administrado por Microsoft.

Implemente una configuración estándar del agente que use identidad administrada para la autenticación.

Los recursos para el centro de IA, el proyecto de IA, el almacén de claves, la cuenta de almacenamiento, los servicios de IA y la Búsqueda de IA se crean por usted.

Los Servicios de IA, la Búsqueda de IA, el almacén de claves y la cuenta de almacenamiento están conectados a su proyecto y a su centro. Un modelo gpt-4o-mini se implementa en la región de eastus.

[Opcional] Selección de modelos en plantilla de implementación automática

Puede personalizar el modelo usando su agente editando los parámetros del modelo en la plantilla de implementación automática. Para implementar un modelo diferente, es necesario actualizar al menos los parámetros modelName y modelVersion.

De manera predeterminada, la plantilla de implementación está configurada con los siguientes valores:

Parámetro del modelo	Valor predeterminado
modelName	gpt-4o-mini
modelFormat	OpenAI (para Azure OpenAI)
modelVersion	2024-07-18
modelSkuName	GlobalStandard
modelLocation	estado

Importante

No cambie el parámetro modelFormat.

Las plantillas solo admiten con la implementación de modelos de Azure OpenAI. Consulte qué modelos de OpenAI son compatibles en la documentación de Modelos compatibles con el modelo de Azure AI Agent Service.

[Opcional] Use sus propios recursos en la configuración del agente

Nota

Si usa un recurso de AI Services o Azure OpenAI existente, no se implementará ningún modelo. Puede implementar un modelo en el recurso una vez completada la configuración del agente.

Use un recurso de AI Services, Azure OpenAI, una cuenta de almacenamiento o una instancia de Búsqueda de Azure AI o Azure Blob Storage existente, para lo que debe especificar el identificador completo del recurso de arm en el archivo de parámetros:

aiServiceAccountResourceId
aiSearchServiceResourceId
aiStorageAccountResourceId

Si desea usar un recurso de Azure OpenAI existente, deberá actualizar los parámetros aiServiceAccountResourceId y aiServiceKind en el archivo de parámetros. El parámetro aiServiceKind debe establecerse en AzureOpenAI.

Para más información, consulte Uso de recursos propios.

Configuración y ejecución de un agente

Componente	Descripción
Agente	IA personalizada que usa modelos de IA junto con herramientas.
Herramienta	Las herramientas ayudan a ampliar la capacidad de un agente para responder con fiabilidad y precisión durante una conversación. Por ejemplo, conectando con bases de conocimientos definidas por el usuario para fundamentar el modelo, o habilitando la búsqueda en la Web para proporcionar información actualizada.
Subproceso	Una sesión de conversación entre un agente y un usuario. Los subprocesos almacenan mensajes y controlan automáticamente el truncamiento para ajustar el contenido a un contexto del modelo.
Mensaje	Un mensaje creado por un agente o un usuario. Los mensajes pueden incluir texto, imágenes y otros archivos. Los mensajes se almacenan como una lista en el subproceso.
Ejecutar	Activación de un agente para empezar a ejecutarse en función del contenido de la conversación. El agente usa su configuración y los mensajes de la conversación para realizar tareas llamando a modelos y herramientas. Como parte de una ejecución, el agente anexa mensajes a la conversación.
Paso de ejecución	Una lista detallada de los pasos que tomó el agente como parte de una ejecución. Un agente puede llamar a herramientas o crear mensajes durante su ejecución. Examinar los pasos de ejecución le permite comprender cómo el agente obtiene sus resultados.

Ejecute los siguientes comandos para instalar los paquetes de Python.

Consola

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.

Azure CLI

az login

Use el código siguiente para crear y ejecutar un agente. Para ejecutar este código, deberá crear una cadena de conexión usando la información de su proyecto. Esta cadena tiene el formato:

<HostName>;<AzureSubscriptionId>;<ResourceGroup>;<ProjectName>

Sugerencia

También puede encontrar su cadena de conexión en la información general de su proyecto en el portal de Azure AI Foundry, en Detalles del proyecto>Cadena de conexión del proyecto.

HostName puede encontrarse navegando hasta su discovery_url y eliminando el https:// inicial y el /discovery final. Para buscar discovery_url, ejecute este comando de la CLI:

Azure CLI

az ml workspace show -n {project_name} --resource-group {resource_group_name} --query discovery_url

Por ejemplo, la cadena de conexión puede tener un aspecto similar al siguiente:

eastus.api.azureml.ms;12345678-abcd-1234-9fc6-62780b3d3e05;my-resource-group;my-project-name

Establezca esta cadena de conexión como una variable de entorno denominada PROJECT_CONNECTION_STRING.

Python

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

# Create an Azure AI Client from a connection string, copied from your Azure AI Foundry project.
# At the moment, it should be in the format "<HostName>;<AzureSubscriptionId>;<ResourceGroup>;<ProjectName>"
# HostName can be found by navigating to your discovery_url and removing the leading "https://" and trailing "/discovery"
# To find your discovery_url, run the CLI command: az ml workspace show -n {project_name} --resource-group {resource_group_name} --query discovery_url
# Project Connection example: eastus.api.azureml.ms;12345678-abcd-1234-9fc6-62780b3d3e05;my-resource-group;my-project-name
# Customer needs to login to Azure subscription via Azure CLI and set the environment variables

project_client = AIProjectClient.from_connection_string(
    credential=DefaultAzureCredential(), conn_str=os.environ["PROJECT_CONNECTION_STRING"]
)

with project_client:
    # Create an instance of the CodeInterpreterTool
    code_interpreter = CodeInterpreterTool()

    # The CodeInterpreterTool needs to be included in creation of the agent
    agent = project_client.agents.create_agent(
        model="gpt-4o-mini",
        name="my-agent",
        instructions="You are helpful agent",
        tools=code_interpreter.definitions,
        tool_resources=code_interpreter.resources,
    )
    print(f"Created agent, agent ID: {agent.id}")

    # Create a thread
    thread = project_client.agents.create_thread()
    print(f"Created thread, thread ID: {thread.id}")

    # Create a message
    message = project_client.agents.create_message(
        thread_id=thread.id,
        role="user",
        content="Could you please create a bar chart for the operating profit using the following data and provide the file to me? Company A: $1.2 million, Company B: $2.5 million, Company C: $3.0 million, Company D: $1.8 million",
    )
    print(f"Created message, message ID: {message.id}")

    # Run the agent
    run = project_client.agents.create_and_process_run(thread_id=thread.id, assistant_id=agent.id)
    print(f"Run finished with status: {run.status}")

    if run.status == "failed":
        # Check if you got "Rate limit is exceeded.", then you want to get more quota
        print(f"Run failed: {run.last_error}")

    # Get messages from the thread
    messages = project_client.agents.list_messages(thread_id=thread.id)
    print(f"Messages: {messages}")

    # Get the last message from the sender
    last_msg = messages.get_last_text_message_by_role("assistant")
    if last_msg:
        print(f"Last Message: {last_msg.text.value}")

    # Generate an image file for the bar chart
    for image_content in messages.image_contents:
        print(f"Image File ID: {image_content.image_file.file_id}")
        file_name = f"{image_content.image_file.file_id}_image_file.png"
        project_client.agents.save_file(file_id=image_content.image_file.file_id, file_name=file_name)
        print(f"Saved image file to: {Path.cwd() / file_name}")

    # Print the file path(s) from the messages
    for file_path_annotation in messages.file_path_annotations:
        print(f"File Paths:")
        print(f"Type: {file_path_annotation.type}")
        print(f"Text: {file_path_annotation.text}")
        print(f"File ID: {file_path_annotation.file_path.file_id}")
        print(f"Start Index: {file_path_annotation.start_index}")
        print(f"End Index: {file_path_annotation.end_index}")
        project_client.agents.save_file(file_id=file_path_annotation.file_path.file_id, file_name=Path(file_path_annotation.text).name)

    # Delete the agent once done
    project_client.agents.delete_agent(agent.id)
    print("Deleted agent")

| Documentación de referencia | Código fuente de la biblioteca | Paquete (PyPi) |

Requisitos previos

Una suscripción a Azure (cree una cuenta gratuita).
Python 3.8 o versiones posteriores
Asegúrese de tener asignado el rol de RBACDesarrollador de Azure AI en el nivel adecuado.
Para poder utilizar el recurso de Servicios de Azure AI, se necesita el rol de Usuario de OpenAI de Cognitive Services asignado.
Instala la CLI de Azure y la extensión de aprendizaje automático. Si ya tiene instalada la CLI, asegúrese de que está actualizada a la última versión.

Configuración de su proyecto de Agente y Centro de Azure AI

En la siguiente sección se muestra cómo configurar los recursos necesarios para dar los primeros pasos con Azure AI Agent Service:

Creación de un Centro de Azure AI para configurar el entorno de su aplicación y los recursos de Azure.
La creación de un proyecto de Azure AI en su Centro crea un punto de conexión al que puede llamar su aplicación y configura los servicios de la aplicación para acceder a los recursos de su inquilino.
Conexión de un recurso de Azure OpenAI o un recurso de Servicios de Azure AI

Elegir configuración básica o estándar del agente

Configuración básica: los agentes usan recursos de almacenamiento y búsqueda multiinquilino totalmente administrados por Microsoft. No tiene visibilidad ni control sobre estos recursos subyacentes de Azure.

Configuración estándar: los agentes usan recursos de almacenamiento y búsqueda de un solo inquilino propiedad del cliente. Con esta configuración, tiene visibilidad y control total sobre estos recursos, pero incurre en costes en función del uso.

Nota

Puede usar las siguientes plantillas de bicep automatizadas para realizar un agente estándar o básico. También puede crear un agente básico mediante el Portal de la Fundición de IA de Azure. La Fundición de IA de Azure no admite actualmente la configuración del agente estándar.

Descripción e implementación automática	Diagrama (haga clic para acercar)
Implemente una configuración básica del agente que use identidad administrada para la autenticación. Los recursos para el centro de IA, el proyecto de IA, la cuenta de almacenamiento y los servicios de IA se crean por usted. La cuenta de Servicios de IA se conecta a su proyecto y centro y se implementa un modelo gpt-4o-mini en la región de eastus. De forma predeterminada, se usa un almacén de claves administrado por Microsoft.
Implemente una configuración estándar del agente que use identidad administrada para la autenticación. Los recursos para el centro de IA, el proyecto de IA, el almacén de claves, la cuenta de almacenamiento, los servicios de IA y la Búsqueda de IA se crean por usted. Los Servicios de IA, la Búsqueda de IA, el almacén de claves y la cuenta de almacenamiento están conectados a su proyecto y a su centro. Un modelo gpt-4o-mini se implementa en la región de eastus.

Descripción e implementación automática

Diagrama (haga clic para acercar)

Implemente una configuración básica del agente que use identidad administrada para la autenticación. Los recursos para el centro de IA, el proyecto de IA, la cuenta de almacenamiento y los servicios de IA se crean por usted.

La cuenta de Servicios de IA se conecta a su proyecto y centro y se implementa un modelo gpt-4o-mini en la región de eastus. De forma predeterminada, se usa un almacén de claves administrado por Microsoft.

Implemente una configuración estándar del agente que use identidad administrada para la autenticación.

Los recursos para el centro de IA, el proyecto de IA, el almacén de claves, la cuenta de almacenamiento, los servicios de IA y la Búsqueda de IA se crean por usted.

Los Servicios de IA, la Búsqueda de IA, el almacén de claves y la cuenta de almacenamiento están conectados a su proyecto y a su centro. Un modelo gpt-4o-mini se implementa en la región de eastus.

[Opcional] Selección de modelos en plantilla de implementación automática

Puede personalizar el modelo usando su agente editando los parámetros del modelo en la plantilla de implementación automática. Para implementar un modelo diferente, es necesario actualizar al menos los parámetros modelName y modelVersion.

De manera predeterminada, la plantilla de implementación está configurada con los siguientes valores:

Parámetro del modelo	Valor predeterminado
modelName	gpt-4o-mini
modelFormat	OpenAI (para Azure OpenAI)
modelVersion	2024-07-18
modelSkuName	GlobalStandard
modelLocation	estado

Importante

No cambie el parámetro modelFormat.

Las plantillas solo admiten con la implementación de modelos de Azure OpenAI. Consulte qué modelos de OpenAI son compatibles en la documentación de Modelos compatibles con el modelo de Azure AI Agent Service.

[Opcional] Use sus propios recursos en la configuración del agente

Nota

Si usa un recurso de AI Services o Azure OpenAI existente, no se implementará ningún modelo. Puede implementar un modelo en el recurso una vez completada la configuración del agente.

Use un recurso de AI Services, Azure OpenAI, una cuenta de almacenamiento o una instancia de Búsqueda de Azure AI o Azure Blob Storage existente, para lo que debe especificar el identificador completo del recurso de arm en el archivo de parámetros:

aiServiceAccountResourceId
aiSearchServiceResourceId
aiStorageAccountResourceId

Si desea usar un recurso de Azure OpenAI existente, deberá actualizar los parámetros aiServiceAccountResourceId y aiServiceKind en el archivo de parámetros. El parámetro aiServiceKind debe establecerse en AzureOpenAI.

Para más información, consulte Uso de recursos propios.

Configuración y ejecución de un agente

Componente	Descripción
Agente	IA personalizada que usa modelos de IA junto con herramientas.
Herramienta	Las herramientas ayudan a ampliar la capacidad de un agente para responder con fiabilidad y precisión durante una conversación. Por ejemplo, conectando con bases de conocimientos definidas por el usuario para fundamentar el modelo, o habilitando la búsqueda en la Web para proporcionar información actualizada.
Subproceso	Una sesión de conversación entre un agente y un usuario. Los subprocesos almacenan mensajes y controlan automáticamente el truncamiento para ajustar el contenido a un contexto del modelo.
Mensaje	Un mensaje creado por un agente o un usuario. Los mensajes pueden incluir texto, imágenes y otros archivos. Los mensajes se almacenan como una lista en el subproceso.
Ejecutar	Activación de un agente para empezar a ejecutarse en función del contenido de la conversación. El agente usa su configuración y los mensajes de la conversación para realizar tareas llamando a modelos y herramientas. Como parte de una ejecución, el agente anexa mensajes a la conversación.
Paso de ejecución	Una lista detallada de los pasos que tomó el agente como parte de una ejecución. Un agente puede llamar a herramientas o crear mensajes durante su ejecución. Examinar los pasos de ejecución le permite comprender cómo el agente obtiene sus resultados.

Ejecute los siguientes comandos para instalar los paquetes de Python.

Consola

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

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.

Azure CLI

az login

Use el código siguiente para crear y ejecutar un agente. Para ejecutar este código, deberá crear una cadena de conexión usando la información de su proyecto. Esta cadena tiene el formato:

<HostName>;<AzureSubscriptionId>;<ResourceGroup>;<ProjectName>

Sugerencia

También puede encontrar su cadena de conexión en la información general de su proyecto en el portal de Azure AI Foundry, en Detalles del proyecto>Cadena de conexión del proyecto.

HostName puede encontrarse navegando hasta su discovery_url y eliminando el https:// inicial y el /discovery final. Para buscar discovery_url, ejecute este comando de la CLI:

Azure CLI

az ml workspace show -n {project_name} --resource-group {resource_group_name} --query discovery_url

Por ejemplo, la cadena de conexión puede tener un aspecto similar al siguiente:

eastus.api.azureml.ms;12345678-abcd-1234-9fc6-62780b3d3e05;my-resource-group;my-project-name

Establezca esta cadena de conexión como una variable de entorno denominada PROJECT_CONNECTION_STRING.

Python

import os, time
from azure.ai.projects import AIProjectClient
from azure.identity import DefaultAzureCredential
from openai import AzureOpenAI


with AIProjectClient.from_connection_string(
    credential=DefaultAzureCredential(),
    conn_str=os.environ["PROJECT_CONNECTION_STRING"],
) as project_client:

    # Explicit type hinting for IntelliSense
    client: AzureOpenAI = project_client.inference.get_azure_openai_client(
        # The latest API version is 2024-10-01-preview
        api_version = os.environ.get("AZURE_OPENAI_API_VERSION"),
    )

    with client:
        agent = client.beta.assistants.create(
            model="gpt-4o-mini", name="my-agent", instructions="You are a helpful agent"
        )
        print(f"Created agent, agent ID: {agent.id}")

        thread = client.beta.threads.create()
        print(f"Created thread, thread ID: {thread.id}")

        message = client.beta.threads.messages.create(thread_id=thread.id, role="user", content="Hello, tell me a joke")
        print(f"Created message, message ID: {message.id}")

        run = client.beta.threads.runs.create(thread_id=thread.id, assistant_id=agent.id)

        # Poll the run while run status is queued or in progress
        while run.status in ["queued", "in_progress", "requires_action"]:
            time.sleep(1)  # Wait for a second
            run = client.beta.threads.runs.retrieve(thread_id=thread.id, run_id=run.id)
            print(f"Run status: {run.status}")

        client.beta.assistants.delete(agent.id)
        print("Deleted agent")

        messages = client.beta.threads.messages.list(thread_id=thread.id)
        print(f"Messages: {messages}")

Requisitos previos

Una suscripción a Azure (cree una cuenta gratuita).
LTS de Node.js
Asegúrese de tener asignado el rol de RBACDesarrollador de Azure AI en el nivel adecuado.
Instala la CLI de Azure y la extensión de aprendizaje automático. Si ya tiene instalada la CLI, asegúrese de que está actualizada a la última versión.

Configuración de su proyecto de Agente y Centro de Azure AI

En la siguiente sección se muestra cómo configurar los recursos necesarios para dar los primeros pasos con Azure AI Agent Service:

Creación de un Centro de Azure AI para configurar el entorno de su aplicación y los recursos de Azure.
La creación de un proyecto de Azure AI en su Centro crea un punto de conexión al que puede llamar su aplicación y configura los servicios de la aplicación para acceder a los recursos de su inquilino.
Conexión de un recurso de Azure OpenAI o un recurso de Servicios de Azure AI

Elegir configuración básica o estándar del agente

Configuración básica: los agentes usan recursos de almacenamiento y búsqueda multiinquilino totalmente administrados por Microsoft. No tiene visibilidad ni control sobre estos recursos subyacentes de Azure.

Configuración estándar: los agentes usan recursos de almacenamiento y búsqueda de un solo inquilino propiedad del cliente. Con esta configuración, tiene visibilidad y control total sobre estos recursos, pero incurre en costes en función del uso.

Nota

Puede usar las siguientes plantillas de bicep automatizadas para realizar un agente estándar o básico. También puede crear un agente básico mediante el Portal de la Fundición de IA de Azure. La Fundición de IA de Azure no admite actualmente la configuración del agente estándar.

Descripción e implementación automática	Diagrama (haga clic para acercar)
Implemente una configuración básica del agente que use identidad administrada para la autenticación. Los recursos para el centro de IA, el proyecto de IA, la cuenta de almacenamiento y los servicios de IA se crean por usted. La cuenta de Servicios de IA se conecta a su proyecto y centro y se implementa un modelo gpt-4o-mini en la región de eastus. De forma predeterminada, se usa un almacén de claves administrado por Microsoft.
Implemente una configuración estándar del agente que use identidad administrada para la autenticación. Los recursos para el centro de IA, el proyecto de IA, el almacén de claves, la cuenta de almacenamiento, los servicios de IA y la Búsqueda de IA se crean por usted. Los Servicios de IA, la Búsqueda de IA, el almacén de claves y la cuenta de almacenamiento están conectados a su proyecto y a su centro. Un modelo gpt-4o-mini se implementa en la región de eastus.

Descripción e implementación automática

Diagrama (haga clic para acercar)

Implemente una configuración básica del agente que use identidad administrada para la autenticación. Los recursos para el centro de IA, el proyecto de IA, la cuenta de almacenamiento y los servicios de IA se crean por usted.

La cuenta de Servicios de IA se conecta a su proyecto y centro y se implementa un modelo gpt-4o-mini en la región de eastus. De forma predeterminada, se usa un almacén de claves administrado por Microsoft.

Implemente una configuración estándar del agente que use identidad administrada para la autenticación.

Los recursos para el centro de IA, el proyecto de IA, el almacén de claves, la cuenta de almacenamiento, los servicios de IA y la Búsqueda de IA se crean por usted.

Los Servicios de IA, la Búsqueda de IA, el almacén de claves y la cuenta de almacenamiento están conectados a su proyecto y a su centro. Un modelo gpt-4o-mini se implementa en la región de eastus.

[Opcional] Selección de modelos en plantilla de implementación automática

Puede personalizar el modelo usando su agente editando los parámetros del modelo en la plantilla de implementación automática. Para implementar un modelo diferente, es necesario actualizar al menos los parámetros modelName y modelVersion.

De manera predeterminada, la plantilla de implementación está configurada con los siguientes valores:

Parámetro del modelo	Valor predeterminado
modelName	gpt-4o-mini
modelFormat	OpenAI (para Azure OpenAI)
modelVersion	2024-07-18
modelSkuName	GlobalStandard
modelLocation	estado

Importante

No cambie el parámetro modelFormat.

Las plantillas solo admiten con la implementación de modelos de Azure OpenAI. Consulte qué modelos de OpenAI son compatibles en la documentación de Modelos compatibles con el modelo de Azure AI Agent Service.

[Opcional] Use sus propios recursos en la configuración del agente

Nota

Si usa un recurso de AI Services o Azure OpenAI existente, no se implementará ningún modelo. Puede implementar un modelo en el recurso una vez completada la configuración del agente.

Use un recurso de AI Services, Azure OpenAI, una cuenta de almacenamiento o una instancia de Búsqueda de Azure AI o Azure Blob Storage existente, para lo que debe especificar el identificador completo del recurso de arm en el archivo de parámetros:

aiServiceAccountResourceId
aiSearchServiceResourceId
aiStorageAccountResourceId

Si desea usar un recurso de Azure OpenAI existente, deberá actualizar los parámetros aiServiceAccountResourceId y aiServiceKind en el archivo de parámetros. El parámetro aiServiceKind debe establecerse en AzureOpenAI.

Para más información, consulte Uso de recursos propios.

Configuración y ejecución de un agente

Componente	Descripción
Agente	IA personalizada que usa modelos de IA junto con herramientas.
Herramienta	Las herramientas ayudan a ampliar la capacidad de un agente para responder con fiabilidad y precisión durante una conversación. Por ejemplo, conectando con bases de conocimientos definidas por el usuario para fundamentar el modelo, o habilitando la búsqueda en la Web para proporcionar información actualizada.
Subproceso	Una sesión de conversación entre un agente y un usuario. Los subprocesos almacenan mensajes y controlan automáticamente el truncamiento para ajustar el contenido a un contexto del modelo.
Mensaje	Un mensaje creado por un agente o un usuario. Los mensajes pueden incluir texto, imágenes y otros archivos. Los mensajes se almacenan como una lista en el subproceso.
Ejecutar	Activación de un agente para empezar a ejecutarse en función del contenido de la conversación. El agente usa su configuración y los mensajes de la conversación para realizar tareas llamando a modelos y herramientas. Como parte de una ejecución, el agente anexa mensajes a la conversación.
Paso de ejecución	Una lista detallada de los pasos que tomó el agente como parte de una ejecución. Un agente puede llamar a herramientas o crear mensajes durante su ejecución. Examinar los pasos de ejecución le permite comprender cómo el agente obtiene sus resultados.

Ejecute los comandos siguientes para instalar los paquetes de npm.

Consola

npm install @azure/ai-projects
npm 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.

Azure CLI

az login

Use el código siguiente para crear y ejecutar un agente. Para ejecutar este código, deberá crear una cadena de conexión usando la información de su proyecto. Esta cadena tiene el formato:

<HostName>;<AzureSubscriptionId>;<ResourceGroup>;<ProjectName>

Sugerencia

También puede encontrar su cadena de conexión en la información general de su proyecto en el portal de Azure AI Foundry, en Detalles del proyecto>Cadena de conexión del proyecto.

HostName puede encontrarse navegando hasta su discovery_url y eliminando el https:// inicial y el /discovery final. Para buscar discovery_url, ejecute este comando de la CLI:

Azure CLI

az ml workspace show -n {project_name} --resource-group {resource_group_name} --query discovery_url

Por ejemplo, la cadena de conexión puede tener un aspecto similar al siguiente:

eastus.api.azureml.ms;12345678-abcd-1234-9fc6-62780b3d3e05;my-resource-group;my-project-name

Establezca esta cadena de conexión como una variable de entorno denominada PROJECT_CONNECTION_STRING.

JavaScript

// index.js

import {
  AIProjectsClient,
  DoneEvent,
  ErrorEvent,
  isOutputOfType,
  MessageStreamEvent,
  RunStreamEvent,
  ToolUtility,
} from "@azure/ai-projects";
import { DefaultAzureCredential } from "@azure/identity";

const connectionString =
  process.env["AZURE_AI_PROJECTS_CONNECTION_STRING"] || "<project connection string>";

if (!connectionString) {
  throw new Error("AZURE_AI_PROJECTS_CONNECTION_STRING must be set in the environment variables");
}

export async function main() {
  const client = AIProjectsClient.fromConnectionString(
    connectionString || "",
    new DefaultAzureCredential(),
  );

  // Step 1 code interpreter tool
  const codeInterpreterTool = ToolUtility.createCodeInterpreterTool();

  // Step 2 an agent
  const agent = await client.agents.createAgent("gpt-4o-mini", {
    name: "my-agent",
    instructions: "You are a helpful agent",
    tools: [codeInterpreterTool.definition],
    toolResources: codeInterpreterTool.resources,
  });

  // Step 3 a thread
  const thread = await client.agents.createThread();

  // Step 4 a message to thread
  await client.agents.createMessage(
    thread.id, {
    role: "user",
    content: "I need to solve the equation `3x + 11 = 14`. Can you help me?",
  });

  // Intermission is now correlated with thread
  // Intermission messages will retrieve the message just added

  // Step 5 the agent
  const streamEventMessages = await client.agents.createRun(thread.id, agent.id).stream();

  for await (const eventMessage of streamEventMessages) {
    switch (eventMessage.event) {
      case RunStreamEvent.ThreadRunCreated:
        break;
      case MessageStreamEvent.ThreadMessageDelta:
        {
          const messageDelta = eventMessage.data;
          messageDelta.delta.content.forEach((contentPart) => {
            if (contentPart.type === "text") {
              const textContent = contentPart;
              const textValue = textContent.text?.value || "No text";
            }
          });
        }
        break;

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

  // 6. Print the messages from the agent
  const messages = await client.agents.listMessages(thread.id);

  // Messages iterate from oldest to newest
  // messages[0] is the most recent
  for (let i = messages.data.length - 1; i >= 0; i--) {
    const m = messages.data[i];
    if (isOutputOfType(m.content[0], "text")) {
      const textContent = m.content[0];
      console.log(`${textContent.text.value}`);
      console.log(`---------------------------------`);
    }
  }

  // 7. Delete the agent once done
  await client.agents.deleteAgent(agent.id);
}

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

La salida contiene la indicación y las respuestas.

I need to solve the equation `3x + 11 = 14`. Can you help me?
---------------------------------
Sure! I can help you solve the equation \(3x + 11 = 14\).

To solve this equation, we need to isolate the variable \(x\). Let's go ahead and solve it.
---------------------------------
The solution to the equation \(3x + 11 = 14\) is \(x = 1\). 

Therefore, the value of \(x\) that satisfies the equation is 1. 

Let me know if you need help with anything else!
---------------------------------

Requisitos previos

Una suscripción a Azure (cree una cuenta gratuita).
LTS de Node.js
TypeScript 5.x
Asegúrese de tener asignado el rol de RBACDesarrollador de Azure AI en el nivel adecuado.
Instala la CLI de Azure y la extensión de aprendizaje automático. Si ya tiene instalada la CLI, asegúrese de que está actualizada a la última versión.

Configuración de su proyecto de Agente y Centro de Azure AI

En la siguiente sección se muestra cómo configurar los recursos necesarios para dar los primeros pasos con Azure AI Agent Service:

Creación de un Centro de Azure AI para configurar el entorno de su aplicación y los recursos de Azure.
La creación de un proyecto de Azure AI en su Centro crea un punto de conexión al que puede llamar su aplicación y configura los servicios de la aplicación para acceder a los recursos de su inquilino.
Conexión de un recurso de Azure OpenAI o un recurso de Servicios de Azure AI

Elegir configuración básica o estándar del agente

Configuración básica: los agentes usan recursos de almacenamiento y búsqueda multiinquilino totalmente administrados por Microsoft. No tiene visibilidad ni control sobre estos recursos subyacentes de Azure.

Configuración estándar: los agentes usan recursos de almacenamiento y búsqueda de un solo inquilino propiedad del cliente. Con esta configuración, tiene visibilidad y control total sobre estos recursos, pero incurre en costes en función del uso.

Nota

Puede usar las siguientes plantillas de bicep automatizadas para realizar un agente estándar o básico. También puede crear un agente básico mediante el Portal de la Fundición de IA de Azure. La Fundición de IA de Azure no admite actualmente la configuración del agente estándar.

Descripción e implementación automática	Diagrama (haga clic para acercar)
Implemente una configuración básica del agente que use identidad administrada para la autenticación. Los recursos para el centro de IA, el proyecto de IA, la cuenta de almacenamiento y los servicios de IA se crean por usted. La cuenta de Servicios de IA se conecta a su proyecto y centro y se implementa un modelo gpt-4o-mini en la región de eastus. De forma predeterminada, se usa un almacén de claves administrado por Microsoft.
Implemente una configuración estándar del agente que use identidad administrada para la autenticación. Los recursos para el centro de IA, el proyecto de IA, el almacén de claves, la cuenta de almacenamiento, los servicios de IA y la Búsqueda de IA se crean por usted. Los Servicios de IA, la Búsqueda de IA, el almacén de claves y la cuenta de almacenamiento están conectados a su proyecto y a su centro. Un modelo gpt-4o-mini se implementa en la región de eastus.

Descripción e implementación automática

Diagrama (haga clic para acercar)

Implemente una configuración básica del agente que use identidad administrada para la autenticación. Los recursos para el centro de IA, el proyecto de IA, la cuenta de almacenamiento y los servicios de IA se crean por usted.

La cuenta de Servicios de IA se conecta a su proyecto y centro y se implementa un modelo gpt-4o-mini en la región de eastus. De forma predeterminada, se usa un almacén de claves administrado por Microsoft.

Implemente una configuración estándar del agente que use identidad administrada para la autenticación.

Los recursos para el centro de IA, el proyecto de IA, el almacén de claves, la cuenta de almacenamiento, los servicios de IA y la Búsqueda de IA se crean por usted.

Los Servicios de IA, la Búsqueda de IA, el almacén de claves y la cuenta de almacenamiento están conectados a su proyecto y a su centro. Un modelo gpt-4o-mini se implementa en la región de eastus.

[Opcional] Selección de modelos en plantilla de implementación automática

Puede personalizar el modelo usando su agente editando los parámetros del modelo en la plantilla de implementación automática. Para implementar un modelo diferente, es necesario actualizar al menos los parámetros modelName y modelVersion.

De manera predeterminada, la plantilla de implementación está configurada con los siguientes valores:

Parámetro del modelo	Valor predeterminado
modelName	gpt-4o-mini
modelFormat	OpenAI (para Azure OpenAI)
modelVersion	2024-07-18
modelSkuName	GlobalStandard
modelLocation	estado

Importante

No cambie el parámetro modelFormat.

Las plantillas solo admiten con la implementación de modelos de Azure OpenAI. Consulte qué modelos de OpenAI son compatibles en la documentación de Modelos compatibles con el modelo de Azure AI Agent Service.

[Opcional] Use sus propios recursos en la configuración del agente

Nota

Si usa un recurso de AI Services o Azure OpenAI existente, no se implementará ningún modelo. Puede implementar un modelo en el recurso una vez completada la configuración del agente.

Use un recurso de AI Services, Azure OpenAI, una cuenta de almacenamiento o una instancia de Búsqueda de Azure AI o Azure Blob Storage existente, para lo que debe especificar el identificador completo del recurso de arm en el archivo de parámetros:

aiServiceAccountResourceId
aiSearchServiceResourceId
aiStorageAccountResourceId

Si desea usar un recurso de Azure OpenAI existente, deberá actualizar los parámetros aiServiceAccountResourceId y aiServiceKind en el archivo de parámetros. El parámetro aiServiceKind debe establecerse en AzureOpenAI.

Para más información, consulte Uso de recursos propios.

Configuración y ejecución de un agente

Componente	Descripción
Agente	IA personalizada que usa modelos de IA junto con herramientas.
Herramienta	Las herramientas ayudan a ampliar la capacidad de un agente para responder con fiabilidad y precisión durante una conversación. Por ejemplo, conectando con bases de conocimientos definidas por el usuario para fundamentar el modelo, o habilitando la búsqueda en la Web para proporcionar información actualizada.
Subproceso	Una sesión de conversación entre un agente y un usuario. Los subprocesos almacenan mensajes y controlan automáticamente el truncamiento para ajustar el contenido a un contexto del modelo.
Mensaje	Un mensaje creado por un agente o un usuario. Los mensajes pueden incluir texto, imágenes y otros archivos. Los mensajes se almacenan como una lista en el subproceso.
Ejecutar	Activación de un agente para empezar a ejecutarse en función del contenido de la conversación. El agente usa su configuración y los mensajes de la conversación para realizar tareas llamando a modelos y herramientas. Como parte de una ejecución, el agente anexa mensajes a la conversación.
Paso de ejecución	Una lista detallada de los pasos que tomó el agente como parte de una ejecución. Un agente puede llamar a herramientas o crear mensajes durante su ejecución. Examinar los pasos de ejecución le permite comprender cómo el agente obtiene sus resultados.

Ejecute los comandos siguientes para instalar los paquetes de npm.

Consola

npm install @azure/ai-projects
npm 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.

Azure CLI

az login

Use el código siguiente para crear y ejecutar un agente. Para ejecutar este código, deberá crear una cadena de conexión usando la información de su proyecto. Esta cadena tiene el formato:

<HostName>;<AzureSubscriptionId>;<ResourceGroup>;<ProjectName>

Sugerencia

También puede encontrar su cadena de conexión en la información general de su proyecto en el portal de Azure AI Foundry, en Detalles del proyecto>Cadena de conexión del proyecto.

HostName puede encontrarse navegando hasta su discovery_url y eliminando el https:// inicial y el /discovery final. Para buscar discovery_url, ejecute este comando de la CLI:

Azure CLI

az ml workspace show -n {project_name} --resource-group {resource_group_name} --query discovery_url

Por ejemplo, la cadena de conexión puede tener un aspecto similar al siguiente:

eastus.api.azureml.ms;12345678-abcd-1234-9fc6-62780b3d3e05;my-resource-group;my-project-name

Establezca esta cadena de conexión como una variable de entorno denominada PROJECT_CONNECTION_STRING.

TypeScript

// index.ts

import type {
  MessageDeltaChunk,
  MessageDeltaTextContent,
  MessageTextContentOutput,
} from "@azure/ai-projects";
import {
  AIProjectsClient,
  DoneEvent,
  ErrorEvent,
  isOutputOfType,
  MessageStreamEvent,
  RunStreamEvent,
  ToolUtility,
} from "@azure/ai-projects";
import { DefaultAzureCredential } from "@azure/identity";

const connectionString =
  process.env["AZURE_AI_PROJECTS_CONNECTION_STRING"] || "<project connection string>";

if (!connectionString) {
  throw new Error("AZURE_AI_PROJECTS_CONNECTION_STRING must be set in the environment variables");
}

export async function main(): Promise<void> {
  const client = AIProjectsClient.fromConnectionString(
    connectionString || "",
    new DefaultAzureCredential(),
  );

  // Step 1: Create code interpreter tool
  const codeInterpreterTool = ToolUtility.createCodeInterpreterTool();

  // Step 2: Create an agent
  const agent = await client.agents.createAgent("gpt-4o-mini", {
    name: "my-agent",
    instructions: "You are a helpful agent",
    tools: [codeInterpreterTool.definition],
    toolResources: codeInterpreterTool.resources,
  });

  // Step 3: Create a thread
  const thread = await client.agents.createThread();

  // Step 4: Add a message to thread
  await client.agents.createMessage(
    thread.id, {
    role: "user",
    content: "I need to solve the equation `3x + 11 = 14`. Can you help me?",
  });

  // Intermission: message is now correlated with thread
  // Intermission: listing messages will retrieve the message just added

  // Step 5: Run the agent
  const streamEventMessages = await client.agents.createRun(thread.id, agent.id).stream();

  for await (const eventMessage of streamEventMessages) {
    switch (eventMessage.event) {
      case RunStreamEvent.ThreadRunCreated:
        break;
      case MessageStreamEvent.ThreadMessageDelta:
        {
          const messageDelta = eventMessage.data as MessageDeltaChunk;
          messageDelta.delta.content.forEach((contentPart) => {
            if (contentPart.type === "text") {
              const textContent = contentPart as MessageDeltaTextContent;
              const textValue = textContent.text?.value || "No text";
            }
          });
        }
        break;

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

  // 6. Print the messages from the agent
  const messages = await client.agents.listMessages(thread.id);

  // Messages iterate from oldest to newest
  // messages[0] is the most recent
  for (let i = messages.data.length - 1; i >= 0; i--) {
    const m = messages.data[i];
    if (isOutputOfType<MessageTextContentOutput>(m.content[0], "text")) {
      const textContent = m.content[0] as MessageTextContentOutput;
      console.log(`${textContent.text.value}`);
      console.log(`---------------------------------`);
    }
  }

  // 7. Delete the agent once done
  await client.agents.deleteAgent(agent.id);
}

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

La salida contiene la indicación y las respuestas.

I need to solve the equation `3x + 11 = 14`. Can you help me?
---------------------------------
Sure! I can help you solve the equation \(3x + 11 = 14\).

To solve this equation, we need to isolate the variable \(x\). Let's go ahead and solve it.
---------------------------------
The solution to the equation \(3x + 11 = 14\) is \(x = 1\). 

Therefore, the value of \(x\) that satisfies the equation is 1. 

Let me know if you need help with anything else!
---------------------------------

| Documentación de referencia |

Requisitos previos

Una suscripción a Azure (cree una cuenta gratuita).
Asegúrese de tener asignado el rol de RBACDesarrollador de Azure AI en el nivel adecuado.
Para poder utilizar el recurso de Servicios de Azure AI, se necesita el rol de Usuario de OpenAI de Cognitive Services asignado.
Instala la CLI de Azure y la extensión de aprendizaje automático. Si ya tiene instalada la CLI, asegúrese de que está actualizada a la última versión.

Configuración de su proyecto de Agente y Centro de Azure AI

En la siguiente sección se muestra cómo configurar los recursos necesarios para dar los primeros pasos con Azure AI Agent Service:

Creación de un Centro de Azure AI para configurar el entorno de su aplicación y los recursos de Azure.
La creación de un proyecto de Azure AI en su Centro crea un punto de conexión al que puede llamar su aplicación y configura los servicios de la aplicación para acceder a los recursos de su inquilino.
Conexión de un recurso de Azure OpenAI o un recurso de Servicios de Azure AI

Elegir configuración básica o estándar del agente

Configuración básica: los agentes usan recursos de almacenamiento y búsqueda multiinquilino totalmente administrados por Microsoft. No tiene visibilidad ni control sobre estos recursos subyacentes de Azure.

Configuración estándar: los agentes usan recursos de almacenamiento y búsqueda de un solo inquilino propiedad del cliente. Con esta configuración, tiene visibilidad y control total sobre estos recursos, pero incurre en costes en función del uso.

Nota

Puede usar las siguientes plantillas de bicep automatizadas para realizar un agente estándar o básico. También puede crear un agente básico mediante el Portal de la Fundición de IA de Azure. La Fundición de IA de Azure no admite actualmente la configuración del agente estándar.

Descripción e implementación automática	Diagrama (haga clic para acercar)
Implemente una configuración básica del agente que use identidad administrada para la autenticación. Los recursos para el centro de IA, el proyecto de IA, la cuenta de almacenamiento y los servicios de IA se crean por usted. La cuenta de Servicios de IA se conecta a su proyecto y centro y se implementa un modelo gpt-4o-mini en la región de eastus. De forma predeterminada, se usa un almacén de claves administrado por Microsoft.
Implemente una configuración estándar del agente que use identidad administrada para la autenticación. Los recursos para el centro de IA, el proyecto de IA, el almacén de claves, la cuenta de almacenamiento, los servicios de IA y la Búsqueda de IA se crean por usted. Los Servicios de IA, la Búsqueda de IA, el almacén de claves y la cuenta de almacenamiento están conectados a su proyecto y a su centro. Un modelo gpt-4o-mini se implementa en la región de eastus.

Descripción e implementación automática

Diagrama (haga clic para acercar)

Implemente una configuración básica del agente que use identidad administrada para la autenticación. Los recursos para el centro de IA, el proyecto de IA, la cuenta de almacenamiento y los servicios de IA se crean por usted.

La cuenta de Servicios de IA se conecta a su proyecto y centro y se implementa un modelo gpt-4o-mini en la región de eastus. De forma predeterminada, se usa un almacén de claves administrado por Microsoft.

Implemente una configuración estándar del agente que use identidad administrada para la autenticación.

Los recursos para el centro de IA, el proyecto de IA, el almacén de claves, la cuenta de almacenamiento, los servicios de IA y la Búsqueda de IA se crean por usted.

Los Servicios de IA, la Búsqueda de IA, el almacén de claves y la cuenta de almacenamiento están conectados a su proyecto y a su centro. Un modelo gpt-4o-mini se implementa en la región de eastus.

[Opcional] Selección de modelos en plantilla de implementación automática

Puede personalizar el modelo usando su agente editando los parámetros del modelo en la plantilla de implementación automática. Para implementar un modelo diferente, es necesario actualizar al menos los parámetros modelName y modelVersion.

De manera predeterminada, la plantilla de implementación está configurada con los siguientes valores:

Parámetro del modelo	Valor predeterminado
modelName	gpt-4o-mini
modelFormat	OpenAI (para Azure OpenAI)
modelVersion	2024-07-18
modelSkuName	GlobalStandard
modelLocation	estado

Importante

No cambie el parámetro modelFormat.

Las plantillas solo admiten con la implementación de modelos de Azure OpenAI. Consulte qué modelos de OpenAI son compatibles en la documentación de Modelos compatibles con el modelo de Azure AI Agent Service.

[Opcional] Use sus propios recursos en la configuración del agente

Nota

Si usa un recurso de AI Services o Azure OpenAI existente, no se implementará ningún modelo. Puede implementar un modelo en el recurso una vez completada la configuración del agente.

Use un recurso de AI Services, Azure OpenAI, una cuenta de almacenamiento o una instancia de Búsqueda de Azure AI o Azure Blob Storage existente, para lo que debe especificar el identificador completo del recurso de arm en el archivo de parámetros:

aiServiceAccountResourceId
aiSearchServiceResourceId
aiStorageAccountResourceId

Si desea usar un recurso de Azure OpenAI existente, deberá actualizar los parámetros aiServiceAccountResourceId y aiServiceKind en el archivo de parámetros. El parámetro aiServiceKind debe establecerse en AzureOpenAI.

Para más información, consulte Uso de recursos propios.

Configuración y ejecución de un agente

Componente	Descripción
Agente	IA personalizada que usa modelos de IA junto con herramientas.
Herramienta	Las herramientas ayudan a ampliar la capacidad de un agente para responder con fiabilidad y precisión durante una conversación. Por ejemplo, conectando con bases de conocimientos definidas por el usuario para fundamentar el modelo, o habilitando la búsqueda en la Web para proporcionar información actualizada.
Subproceso	Una sesión de conversación entre un agente y un usuario. Los subprocesos almacenan mensajes y controlan automáticamente el truncamiento para ajustar el contenido a un contexto del modelo.
Mensaje	Un mensaje creado por un agente o un usuario. Los mensajes pueden incluir texto, imágenes y otros archivos. Los mensajes se almacenan como una lista en el subproceso.
Ejecutar	Activación de un agente para empezar a ejecutarse en función del contenido de la conversación. El agente usa su configuración y los mensajes de la conversación para realizar tareas llamando a modelos y herramientas. Como parte de una ejecución, el agente anexa mensajes a la conversación.
Paso de ejecución	Una lista detallada de los pasos que tomó el agente como parte de una ejecución. Un agente puede llamar a herramientas o crear mensajes durante su ejecución. Examinar los pasos de ejecución le permite comprender cómo el agente obtiene sus resultados.

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

Azure CLI

az login

A continuación, deberá capturar el token de Id. de Entra para proporcionar como autorización a las llamadas API. Capture el token mediante el comando de la CLI:

Azure CLI

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

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

Para realizar correctamente llamadas API de REST al servicio Azure AI Agents, deberá usar el punto de conexión como se indica a continuación:

https://<HostName>/agents/v1.0/subscriptions/<AzureSubscriptionId>/resourceGroups/<ResourceGroup>/providers/Microsoft.MachineLearningServices/workspaces/<ProjectName>

HostName puede encontrarse navegando hasta su discovery_url y eliminando el https:// inicial y el /discovery final. Para buscar discovery_url, ejecute este comando de la CLI:

Azure CLI

az ml workspace show -n {project_name} --subscription {subscription_name} --resource-group {resource_group_name} --query discovery_url

Por ejemplo, el punto de conexión puede tener un aspecto similar al siguiente:

https://eastus.api.azureml.ms/agents/v1.0/subscriptions/12345678-abcd-1234-abcd-123456789000/resourceGroups/my-resource-group/providers/Microsoft.MachineLearningServices/workspaces/my-project-name

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

Crear un agente

Nota

Con Azure AI Agents Service, el parámetro model requiere el nombre de implementación de modelo. Si el nombre de implementación de modelo es diferente al del modelo subyacente, tendría que ajustar el código a "model": "{your-custom-model-deployment-name}".

Consola

curl $AZURE_AI_AGENTS_ENDPOINT/assistants?api-version=2024-12-01-preview \
  -H "Authorization: Bearer $AZURE_AI_AGENTS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "instructions": "You are a helpful agent.",
    "name": "my-agent",
    "tools": [{"type": "code_interpreter"}],
    "model": "gpt-4o-mini"
  }'

Creación de un subproceso

Consola

curl $AZURE_AI_AGENTS_ENDPOINT/threads?api-version=2024-12-01-preview \
  -H "Authorization: Bearer $AZURE_AI_AGENTS_TOKEN" \
  -H "Content-Type: application/json" \
  -d ''

Adición de una pregunta de usuario al subproceso

Consola

curl $AZURE_AI_AGENTS_ENDPOINT/threads/thread_abc123/messages?api-version=2024-12-01-preview \
  -H "Authorization: Bearer $AZURE_AI_AGENTS_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

Consola

curl $AZURE_AI_AGENTS_ENDPOINT/threads/thread_abc123/runs?api-version=2024-12-01-preview \
  -H "Authorization: Bearer $AZURE_AI_AGENTS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "assistant_id": "asst_abc123",
  }'

Recuperación del estado de la ejecución

Consola

curl $AZURE_AI_AGENTS_ENDPOINT/threads/thread_abc123/runs/run_abc123?api-version=2024-12-01-preview \
  -H "Authorization: Bearer $AZURE_AI_AGENTS_TOKEN"

Recuperación de la respuesta del agente

Consola

curl $AZURE_AI_AGENTS_ENDPOINT/threads/thread_abc123/messages?api-version=2024-12-01-preview \
  -H "Authorization: Bearer $AZURE_AI_AGENTS_TOKEN"

Compartir a través de

Inicio rápido: Creación de un nuevo agente (versión preliminar)

Requisitos previos

Compatibilidad con la configuración básica del agente

Creación de un centro de conectividad y un proyecto en el Portal de la Fundición de IA de Azure

Implementación de un modelo

Uso del área de juegos del agente

Consulte también

Requisitos previos

Configuración de su proyecto de Agente y Centro de Azure AI

Elegir configuración básica o estándar del agente

[Opcional] Selección de modelos en plantilla de implementación automática

[Opcional] Use sus propios recursos en la configuración del agente

Configuración y ejecución de un agente

Requisitos previos

Configuración de su proyecto de Agente y Centro de Azure AI

Elegir configuración básica o estándar del agente

[Opcional] Selección de modelos en plantilla de implementación automática

[Opcional] Use sus propios recursos en la configuración del agente

Configuración y ejecución de un agente

Requisitos previos

Configuración de su proyecto de Agente y Centro de Azure AI

Elegir configuración básica o estándar del agente

[Opcional] Selección de modelos en plantilla de implementación automática

[Opcional] Use sus propios recursos en la configuración del agente

Configuración y ejecución de un agente

Requisitos previos

Configuración de su proyecto de Agente y Centro de Azure AI

Elegir configuración básica o estándar del agente

[Opcional] Selección de modelos en plantilla de implementación automática

[Opcional] Use sus propios recursos en la configuración del agente

Configuración y ejecución de un agente

Requisitos previos

Configuración de su proyecto de Agente y Centro de Azure AI

Elegir configuración básica o estándar del agente

[Opcional] Selección de modelos en plantilla de implementación automática

[Opcional] Use sus propios recursos en la configuración del agente

Configuración y ejecución de un agente

Requisitos previos

Configuración de su proyecto de Agente y Centro de Azure AI

Elegir configuración básica o estándar del agente

[Opcional] Selección de modelos en plantilla de implementación automática

[Opcional] Use sus propios recursos en la configuración del agente

Configuración y ejecución de un agente

Crear un agente

Creación de un subproceso

Adición de una pregunta de usuario al subproceso

Ejecución del subproceso

Recuperación del estado de la ejecución

Recuperación de la respuesta del agente

Comentarios

Recursos adicionales