Publica tu agente como una aplicación de agente

La publicación promueve un agente desde un activo de desarrollo dentro de tu proyecto Foundry hacia un recurso de Azure administrado al que los consumidores externos pueden acceder a través de un punto de conexión estable. Piense en él como el paso que mueve el agente de "funciona en mi proyecto" a "listo para que otros lo usen".

En este artículo se muestra cómo publicar un agente, configurar su autenticación y permisos, invocar la aplicación del agente mediante el protocolo de API de respuestas y actualizar la aplicación del agente a medida que implementa nuevas versiones del agente. Después de la publicación, puede invocar la Aplicación de Agente mediante el protocolo Responses o Activity.

¿Qué es la publicación?

Durante el desarrollo, creas y pruebas tu agente dentro de un proyecto Foundry. El proyecto le ofrece a usted y a sus compañeros de equipo un área de trabajo compartida, pero no está diseñada para una distribución amplia, ya que todos los usuarios con acceso al proyecto pueden interactuar con todos los agentes y compartir el mismo contexto de conversación y permisos. La publicación es el paso que mueve un agente fuera de ese espacio de desarrollo compartido y a un recurso de Azure listo para producción.

Al publicar una versión del agente, Foundry crea un recurso Agent Application que encapsula la versión del agente con una dirección URL de invocación propia, directiva de autenticación, identidad única del agente Entra y un plan único del agente Entra. Una implementación también se crea como un recurso secundario de la aplicación, refiriéndose a la versión específica del agente que se está publicando y admitiendo la gestión del ciclo de vida de inicio y parada.

¿Por qué publicar?

La publicación proporciona funcionalidades que el desarrollo de nivel de proyecto no proporciona:

• Compartición externa — Conceda acceso a compañeros de equipo o clientes sin concederles acceso a su proyecto Foundry.
• Punto de conexión estable: la dirección URL de la aplicación sigue siendo la misma, aunque se implementen nuevas versiones del agente.
• Identidad de agente distinta: el agente publicado obtiene su propia identidad de agente Entra y modelo de agente Entra, independiente de la identidad compartida y el modelo del proyecto.
• Independent RBAC y autorización: la aplicación del agente es un recurso de Azure independiente con su propio ámbito de RBAC. Puede asignar roles como Usuario de Azure AI directamente en el recurso de aplicación de agente para controlar quién puede invocarlo.
• Integración con Azure Policy: como recurso de Azure Resource Manager (ARM), la aplicación se puede gobernar mediante las directivas de Azure.
• Integración con la Microsoft 365 Copilot y Teams — Distribuya su aplicación de agente a canales como Microsoft 365 Copilot y Teams.

¿Qué cambios se producen al publicar?

El cambio más importante es la identidad. Un agente no publicado usa la identidad del agente compartido del proyecto. Una vez publicado, el agente recibe una identidad dedicada propia. Las herramientas que usen la autenticación de la identidad del agente cambiarán de la identidad compartida del proyecto a la identidad única del agente de la aplicación.

¿Qué hay que ver?

Dado que la identidad cambia, los permisos no se transfieren automáticamente. Al publicar un agente, debe reasignar los permisos de RBAC a la nueva identidad del agente para los recursos a los que el agente necesita acceder. Si omite este paso, las llamadas a herramientas que funcionan durante el desarrollo producen errores de autorización una vez publicado el agente.

Requisitos previos

• Un Proyecto Foundry con al menos creada una versión del agente
• rol Azure AI Project Manager dentro del ámbito de recursos de Foundry para publicar agentes
• Rol de usuario de Azure AI en el alcance de la aplicación del agente para chatear con un agente publicado mediante el Protocolo de Respuestas de la API
• Familiaridad con el control de acceso basado en roles de Azure (RBAC) para la configuración de permisos
• Familiaridad con los conceptos de identidad del agente en Foundry
• Instale los entornos de ejecución de lenguaje necesarios, las herramientas globales y las extensiones de Visual Studio Code tal y como se describe en Prepare el entorno de desarrollo

Comprender las aplicaciones y las implementaciones del agente

Antes de publicar, es importante comprender la relación entre proyectos, versiones de agente, aplicaciones e implementaciones.

Un proyecto Foundry es un concepto de organización del trabajo que agrupa recursos relacionados, como agentes, archivos e índices. Un agente representa una unidad compuesta, definida por sus instrucciones, modelo y herramientas. Una versión del agente captura una instantánea inmutable específica de un agente. Cada vez que realice cambios en el agente, como actualizar el mensaje o agregar herramientas, se crea una nueva versión del agente. Cada versión del agente se expone en el proyecto Foundry, donde los desarrolladores con acceso al proyecto pueden crear, ejecutar y probarlo.

Una aplicación de agente proyecta uno o varios agentes como servicio, direccionables de forma independiente, controlables y equipados con funcionalidades de administración de contenido y ciclo de vida. Proporciona una interfaz duradera que establece la autenticación, la identidad y un punto de entrada estable para los consumidores. Una implementación es una instancia en ejecución de una versión del agente dentro de una aplicación que se puede iniciar, detener y actualizar para hacer referencia a las nuevas versiones del agente.

Administración de versiones y enrutamiento

Cada aplicación de agente actúa como una tabla de enrutamiento para despliegues específicos del agente. Actualmente, una aplicación del agente admite una implementación activa, que dirige 100% del tráfico recibido por el punto de conexión de la aplicación a esa implementación. Al publicar una nueva versión del agente en una aplicación existente, 100% del tráfico recibido por el punto de conexión de la aplicación se dirige a la implementación que hace referencia a la nueva versión del agente.

Protocolos

Un recurso de la aplicación del agente expone un punto de conexión estable con varias opciones de protocolos y autenticación.

Protocolo de respuestas

Los agentes de Foundry exponen de forma predeterminada un protocolo compatible con OpenAI basado en respuestas para interactuar con agentes.

En el caso de las aplicaciones, este punto de conexión se expone en:

https://{accountName}.services.ai.azure.com/api/projects/{projectName}/applications/{applicationName}/protocols/openai

La API compatible con OpenAI expuesta a través de aplicaciones se ha modificado para asegurarse de que las conversaciones de los usuarios permanecen privadas. Esta restricción es temporal y se quitará una vez que admitamos el aislamiento del usuario final. Como resultado, la API es más limitada que la API de OpenAI que sirve el endpoint del proyecto. Específicamente:

• Solo se admite la API de respuestas sin estado (POST /responses).
• Otras API, como /conversations, /files, /vector_storesy /containers son inaccesibles.

Esta limitación significa que el cliente debe almacenar el historial de conversaciones en conversaciones de varios turnos.

Protocolo de actividad

Los agentes de foundry también pueden exponer el Activity Protocol usado por Azure Bot Service.

En el caso de las aplicaciones, este punto de conexión se expone en:

https://{accountName}.services.ai.azure.com/api/projects/{projectName}/applications/{applicationName}/protocols/activityprotocol

Autenticación

Puede configurar la autenticación de usuario final entrante en la aplicación. Están disponibles las siguientes opciones:

• Default (RBAC): el autor de la llamada debe tener el rol Azure ai User (o un rol personalizado con el permiso /applications/invoke/action) en el recurso Aplicación del agente. Elija esta opción si desea invocar la aplicación del agente mediante el protocolo de API de respuestas. Para obtener más información sobre los roles de control de acceso basado en roles (RBAC) de Foundry, consulte Control de acceso basado en roles para Microsoft Foundry.
• Channels (Azure Bot Service): al publicar en M365/Teams o en A365 como trabajador digital, los canales son el método de autenticación que se utiliza. Esto se selecciona automáticamente en la interfaz de usuario a través del flujo de publicación de M365/Teams.

No se admite la autenticación de clave de API para invocar aplicaciones del agente. Usa Microsoft Entra ID (Azure RBAC) para autorizar a los llamantes.

Publicar un agente

Portal de fundición

En esta sección se muestra cómo publicar un agente mediante la interfaz del portal foundry.

1. En el Generador de agentes, cree o seleccione una versión del agente que quiera publicar.

2. Seleccione Publicar agente para crear una aplicación de agente y una implementación.

Resultado esperado: se completa la publicación y la versión del agente muestra un estado de publicado.

3. Configure la autenticación para la aplicación del agente:

   • De forma predeterminada, el tipo de autenticación se establece en RBAC (Role-Based Access Control).
   • A los usuarios que llaman a la aplicación del agente mediante el Protocolo de Respuestas se les debe conceder el rol integrado de Azure RBAC Azure AI User (o un rol personalizado equivalente) en el recurso de aplicación del agente.

4. Asignar permisos para la autenticación de herramientas:

   • Si el agente incluye herramientas que usan la identidad del agente para la autenticación, la identidad del agente recién creada debe tener los permisos adecuados.
   • Vaya a cada recurso de Azure al que el agente accede y asigne el rol RBAC necesario a la nueva identidad del agente.

5. Después de publicar, puede hacer lo siguiente:

   • Comparta el punto de conexión publicado con consumidores externos o intégrelo en la aplicación existente.
   • Comparta y chate con la aplicación en canales como Teams/M365 Copilot.

REST API

Para publicar una versión del agente, debe crear una aplicación e implementación que haga referencia a su versión del agente.

Antes de empezar

1. Inicie sesión y adquiera un token de acceso de Azure Resource Manager:

az login
az account get-access-token --resource https://management.azure.com

Utilice el valor accessToken como encabezado Authorization: Bearer <token> en las siguientes solicitudes.

Si desea capturar solo el valor del token (por ejemplo, para su uso en un script), use:

az account get-access-token --resource https://management.azure.com --query accessToken -o tsv

2. Recopile los valores que necesita para la dirección URL de solicitud.

   • subscription_id: Use la suscripción que contiene el recurso Foundry. Puede encontrarlo en el portal de Azure (Subscriptions) o ejecutando az account show --query id -o tsv.
   • resource_group: el grupo de recursos que contiene el recurso Foundry. Puede encontrarlo en la página Overview del recurso Foundry en el portal de Azure.
   • account_name: el nombre del recurso Foundry (el nombre del recurso Azure).
   • project_name: Nombre del proyecto Foundry.
   • application_name y deployment_name: elija nombres para la aplicación del agente y la implementación que desea crear.

3. Elija un api-version.

1. Creación de una aplicación de agente.

Para obtener una referencia de propiedad completa y un ejemplo de infraestructura como código (Bicep) para aplicaciones del agente, consulte la referencia de plantilla de Azure Resource Manager para Microsoft. CognitiveServices/accounts/projects/applications.

Campo obligatorio: establezca el agentName campo en el nombre del agente que desea publicar.

En el ejemplo siguiente solo se muestran los campos mínimos obligatorios. De forma predeterminada, authorizationPolicy está establecido en Default (Azure RBAC) y trafficRoutingPolicy enruta todo el tráfico a la primera implementación.

PUT https://management.azure.com/subscriptions/{{subscription_id}}/resourceGroups/{{resource_group}}/providers/Microsoft.CognitiveServices/accounts/{{account_name}}/projects/{{project_name}}/applications/{{application_name}}?api-version={{api_version}}
Authorization: Bearer {{token}}
Content-Type: application/json

{
  "properties":{
    "agents": [{"agentName": "Publishing Agent"}]
  }
}

2. Crear una implementación de agente.

Para obtener una referencia de propiedad completa y un ejemplo de infraestructura como código (Bicep) para implementaciones del agente, consulte la referencia de plantilla de Azure Resource Manager para Microsoft. CognitiveServices/accounts/projects/applications/agentDeployments.

Campos obligatorios:

• deploymentType: El modo de implementación. Utilice Managed para agentes de instancia y flujo de trabajo. Utilice Hosted para agentes hospedados.
• agents: nombre del agente y versión que se va a implementar.
• protocols: el protocolo que expone la implementación. Para las respuestas, establezca protocol como Responses y version como 1.0.

Más campos obligatorios para solo hospedado

• minReplicas: establece el número mínimo de réplicas.
• maxReplicas: establece el número máximo de réplicas.

Agentes de indicación y de flujo de trabajo

PUT https://management.azure.com/subscriptions/{{subscription_id}}/resourceGroups/{{resource_group}}/providers/Microsoft.CognitiveServices/accounts/{{account_name}}/projects/{{project_name}}/applications/{{application_name}}/agentdeployments/{{deployment_name}}?api-version={{api_version}}
Authorization: Bearer {{token}}
Content-Type: application/json

{
  "properties":{
    "displayName": "Test Managed Deployment",
    "deploymentType": "Managed",
    "protocols": [
        {
          "protocol": "Responses",
          "version": "1.0"
        }
    ],
    "agents": [
        {
            "agentName": "Publishing Agent",
            "agentVersion": "1"
        }
    ]
  }
}    

Agentes hospedados

PUT https://management.azure.com/subscriptions/{{subscription_id}}/resourceGroups/{{resource_group}}/providers/Microsoft.CognitiveServices/accounts/{{account_name}}/projects/{{project_name}}/applications/{{application_name}}/agentdeployments/{{deployment_name}}?api-version={{api_version}}
Authorization: Bearer {{token}}
Content-Type: application/json
{
  "properties": {
    "displayName": "Test Hosted Deployment",
    "deploymentType": "Hosted",
    "minReplicas": 1,
    "maxReplicas": 1,
    "protocols": [
        {
            "protocol": "Responses",
            "version": "1.0"
        }
    ],
    "agents": [
        {
            "agentName": "ContainerAgent",
            "agentVersion": "1"
        }
    ]
  }
}

3. Comprobar que la implementación se está ejecutando

Las implementaciones del agente de solicitud y flujo de trabajo suelen empezar a ejecutarse automáticamente. Las implementaciones del agente hospedado heredan el estado de la versión del agente publicado, si se detiene la versión, la implementación también se detiene.

Para comprobar el estado actual, obtenga el recurso de implementación e inspeccione la propiedad state:

GET https://management.azure.com/subscriptions/{{subscription_id}}/resourceGroups/{{resource_group}}/providers/Microsoft.CognitiveServices/accounts/{{account_name}}/projects/{{project_name}}/applications/{{application_name}}/agentdeployments/{{deployment_name}}?api-version={{api_version}}
Authorization: Bearer {{token}}

Use la siguiente llamada para iniciar una implementación detenida:

POST https://management.azure.com/subscriptions/{{subscription_id}}/resourceGroups/{{resource_group}}/providers/Microsoft.CognitiveServices/accounts/{{account_name}}/projects/{{project_name}}/applications/{{application_name}}/agentdeployments/{{deployment_name}}/start?api-version={{api_version}}
Authorization: Bearer {{token}}
Content-Type: application/json

Comprobación de que la publicación se realizó correctamente

Confirme que el agente se publicó correctamente antes de compartir el endpoint con los consumidores. Después de publicar, compruebe que:

• La aplicación de agente existe.
• El despliegue se está ejecutando.
• Puede invocar el punto de conexión de la aplicación.

Comprobación rápida mediante una llamada al punto de conexión

Para ejecutar los siguientes comandos, necesita el CLI de Azure.

1. Obtenga un token de acceso para el usuario que llama.

az account get-access-token --resource https://ai.azure.com

2. Llame al punto de conexión de la aplicación del agente (protocolo de respuestas).

curl -X POST \
  "https://<foundry-resource-name>.services.ai.azure.com/api/projects/<project-name>/applications/<app-name>/protocols/openai/responses?api-version=2025-11-15-preview" \
  -H "Authorization: Bearer <access-token>" \
  -H "Content-Type: application/json" \
  -d '{"input":"Say hello"}'

Si recibe 403 Forbidden, confirme que el autor de la llamada tiene el rol de usuario de IA de Azure en el recurso Aplicación del agente.

Actualizar una aplicación de agente publicada

Cuando necesite implementar una nueva versión del agente, actualice la aplicación existente y la implementación para hacer referencia a la nueva versión del agente.

Portal de fundición

1. En el Generador de agentes, vaya a la versión específica del agente que desea publicar.

2. Seleccione Publicar actualizaciones.

3. Confirme la actualización. La aplicación de agente dirige automáticamente el 100% del tráfico a la nueva versión del agente.

La dirección URL del punto de conexión estable permanece sin cambios, lo que garantiza que la actualización no interrumpa a los consumidores de nivel inferior.

REST API

Si el nombre del agente sigue siendo el mismo y solo desea implementar una nueva versión del agente, actualice la implementación para hacer referencia a una nueva versión del agente.

PUT https://management.azure.com/subscriptions/{{subscription_id}}/resourceGroups/{{resource_group}}/providers/Microsoft.CognitiveServices/accounts/{{account_name}}/projects/{{project_name}}/applications/{{application_name}}/agentdeployments/{{deployment_name}}?api-version={{api_version}}
Authorization: Bearer {{token}}
Content-Type: application/json

{
  "properties":{
    "description": "This is a managed deployment",
     "displayName": "Test Managed Deployment",
    "deploymentType": "Managed",
    "protocols": [
        {
          "protocol": "Responses",
          "version": "1.0"
        }
    ],
    "agents": [
        {
            "agentName": "Publishing Agent",
            "agentVersion": "<updated-agent-version>"
        }
    ]
  }
}

Para implementar un agente con un nombre diferente, debe hacer lo siguiente:

1. Actualice la aplicación del agente para permitir el nuevo nombre del agente.
2. Cree o actualice una implementación para hacer referencia a la nueva versión del agente.
3. Si creó una nueva implementación, actualice la directiva de enrutamiento de tráfico de la Aplicación del Agente para que el 100% del tráfico vaya a la nueva implementación.

Concesión de acceso a los usuarios para invocar un agente publicado

Después de publicar un agente, los usuarios que llaman necesitan el rol Azure AI User (o un rol personalizado que incluya el permiso Microsoft.CognitiveServices/accounts/projects/applications/invoke/action) en el recurso Agent Application. Esta asignación de roles se limita a la aplicación de agente individual, por lo que puede conceder acceso a un único agente publicado sin conceder a los usuarios acceso a todo el proyecto Foundry u otros agentes.

Para obtener más información sobre Azure RBAC, consulte Control de acceso basado en roles para Microsoft Foundry

Invoca tu aplicación de agente

Después de publicarlo, invoque el agente a través de su punto de conexión mediante el protocolo api de respuestas o el protocolo de actividad. El protocolo de actividad se usa cuando el agente se publica para Microsoft 365 y Teams.

Para usar tu aplicación del agente en Microsoft 365 Copilot y Teams, consulta Publicar agentes en Microsoft 365 Copilot y Microsoft Teams.

Para publicar el agente como trabajador digital, consulte Publicación de un agente como trabajador digital en el Agente 365

Invocación mediante el protocolo de API de respuestas

Para invocar la aplicación del agente mediante el protocolo de API de respuestas, necesita:

• Usuario de Azure IA en el contexto de la aplicación del agente
• Los paquetes openai y azure-identity instalados y autenticados como se describe en Prepare su entorno de desarrollo

Uso del cliente de OpenAI con el endpoint de aplicaciones de agentes

from openai import OpenAI 
from azure.identity import DefaultAzureCredential, get_bearer_token_provider 

# Replace placeholders with your resource, project, and app names
BASE_URL = "https://<foundry-resource-name>.services.ai.azure.com/api/projects/<project-name>/applications/<app-name>/protocols/openai"

# Create OpenAI client authenticated with Azure credentials
openai = OpenAI(
    api_key=get_bearer_token_provider(DefaultAzureCredential(), "https://ai.azure.com/.default"),
    base_url=BASE_URL,
    default_query={"api-version": "2025-11-15-preview"}
)

# Send a request to the published agent
response = openai.responses.create( 
  input="Write a haiku", 
) 
print(f"Response output: {response.output_text}")

Este enfoque se autentica mediante credenciales de Azure y requiere que el autor de la llamada tenga el rol de usuario de IA de Azure en el recurso aplicación del agente.

Consideraciones de seguridad y privacidad

• Use privilegios mínimos. Conceda a los usuarios el rol mínimo que necesitan (por ejemplo, separar los permisos de publicación de los permisos de invocación).
• Evite compartir el acceso al proyecto cuando solo necesite compartir un agente. Utiliza el punto de conexión de la aplicación del agente y RBAC en el recurso de la aplicación.
• No inserte tokens de acceso en el código fuente, los scripts o las aplicaciones cliente. Usa los flujos de autenticación de Microsoft Entra adecuados para tu aplicación.
• Planee los cambios de identidad al publicar. Las llamadas de herramienta autenticadas por la identidad del agente usan la identidad de la aplicación después de publicar, no la identidad del proyecto.
• Almacene el historial de conversaciones en el cliente si necesita interacciones de varios turnos. Las aplicaciones del agente restringen actualmente las API y no almacenan respuestas.

Limitaciones

Los agentes publicados como Aplicaciones de Agente tienen las siguientes limitaciones:

Solución de problemas

Limpieza de recursos

Si ya no necesita un punto de conexión publicado, elimine el recurso Application Azure del agente (y sus implementaciones). La eliminación de la aplicación no elimina las versiones del agente en el proyecto Foundry.

Referencia: Propiedades de implementación y aplicación del agente

Use las tablas siguientes al crear solicitudes de API REST o necesite comprender los campos devueltos en las respuestas.

Preguntas más frecuentes

¿Por qué no se conservan las conversaciones para los agentes publicados? ¿Por qué solo se admiten respuestas sin estado?

Actualmente, existe una limitación temporal donde los agentes publicados solo admiten interacciones con la API de respuestas que son sin estado (es decir, no existen conversaciones persistentes). Ya está en curso el trabajo para corregirlo.

La razón de esta limitación es que, aunque Foundry Agent Service admite el historial de conversaciones administrados, aún no aplica el aislamiento del usuario final entre las conversaciones dentro del mismo proyecto. En otras palabras, si alguien conoce el identificador de conversación de otro usuario, podría acceder a ese historial de conversaciones aunque no sea suyo. Esto es aceptable en un contexto de desarrollo dentro de un solo proyecto, pero no es aceptable para producción, donde los clientes necesitan un aislamiento estricto de conversación por usuario.

Las aplicaciones de agente están diseñadas para exponer la funcionalidad a una audiencia diferente (por ejemplo, otras de la organización o los clientes), independientes de los desarrolladores de proyectos, con versiones estables, configuración y acceso controlado. Dado ese objetivo, los usuarios de aplicaciones de agente esperan naturalmente que sus interacciones con la aplicación sean privadas y no sean visibles para otros usuarios. Esto no es posible actualmente porque las API de OpenAI para un solo usuario sobre las que hemos trabajado no proporcionan aislamiento nativo de datos, y necesitamos construir esa capa de aislamiento nosotros mismos. Hasta que se admita el aislamiento completo de datos del usuario final para las aplicaciones, solo están disponibles las respuestas sin estado. Esta limitación es temporal.

¿Cuál es el modelo de precios de un agente publicado? ¿El costo se basa en un modelo de consumo o el cliente incurre en cargos simplemente porque el recurso de aplicación (punto de conexión) tiene implementada la infraestructura subyacente una vez que se publica el agente?

Los agentes publicados usan un modelo de pago por publicador: el publicador (propietario del proyecto Foundry) incurre en costos basados en la infraestructura subyacente que se implementa cuando el agente se publica como una aplicación, no en función del consumo por llamada. Los usuarios finales de la aplicación publicada no incurren en ningún costo de forma predeterminada, aunque los clientes pueden optar por colocar su propia capa de medición o facturación delante de la aplicación si quieren implementar un modelo basado en el consumo para su organización o usuarios externos.

Contenido relacionado

• Más información sobre los conceptos de identidad del agente en Foundry
• Aprenda sobre los agentes hospedados
• Obtenga información sobre cómo publicar agentes para Microsoft 365 Copilot y Microsoft Teams
• Migración de aplicaciones del agente al nuevo modelo de agente

Pasos siguientes