Publicar el agente como una aplicación de agente

La publicación mueve un agente desde un recurso de desarrollo dentro del proyecto Foundry a un recurso de Azure administrado al que los consumidores externos pueden llamar a través de un punto de conexión estable. Considérelo como el paso que lleva a su agente de "funciona en mi proyecto" a "listo para ser utilizado por otros".

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 del Agente mediante el protocolo Respuestas o el protocolo Actividad.

¿Qué es la publicación?

Durante el desarrollo, desarrollará y probará su agente dentro de un proyecto de 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 de aplicación de agente que encapsula la versión del agente con su propia dirección URL de invocación, directiva de autenticación, identidad única del agente Entra y plan único del agente Entra. Una implementación también se crea como un recurso secundario de la aplicación, haciendo referencia a la versión específica del agente que se publica y que admite 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:

• Uso compartido externo — conceda acceso a compañeros de equipo o clientes sin concederles acceso al proyecto Foundry.

• Punto de conexión estable: la dirección URL de la aplicación sigue siendo la misma incluso cuando se implementan nuevas versiones del agente.

• Identidad de agente distinta: el agente publicado obtiene su propia identidad y plano técnico de agente de Entra, independiente de la identidad y el plano técnico compartidos del proyecto.

• RBAC independiente y autorización: la aplicación del agente es un recurso de Azure independiente con su propio ámbito de RBAC. Puede asignar roles como Foundry User directamente en el recurso Aplicación del agente para controlar quién puede invocarlo.

  Importante

  Recientemente se cambió el nombre de los roles RBAC de Foundry. Foundry User, Foundry Owner, Foundry Account Owner y Foundry Project Manager se llamaban anteriormente Usuario de Azure AI, Propietario de Azure AI, Propietario de la cuenta de Azure AI y Administrador de proyectos de Azure AI. Es posible que siga viendo los nombres anteriores en algunos lugares mientras se implementa el cambio de nombre. El cambio de nombre no modifica los identificadores de rol y los permisos principales.

• Integración de Azure Policy: como recurso de Azure Resource Manager (ARM), la aplicación se puede gestionar mediante Azure Policy.

• Integración con Microsoft 365 Copilot y Teams: distribuya la aplicación del agente en 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 utiliza la identidad de agente compartida del proyecto. Una vez publicado, el agente recibe una identidad dedicada para sí mismo. Las herramientas que utilicen la autenticación de identidad del agente cambiarán de la identidad compartida del proyecto a la identidad única del agente de la aplicación de agente.

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

Prerequisites

• Un proyecto Foundry con al menos una versión de agente creada
• Rol de Administrador de proyectos de Foundry en el ámbito del recurso de Foundry para publicar agentes
• Rol de usuario de Foundry en el ámbito de la aplicación del agente para chatear con un agente publicado mediante el protocolo de API de respuestas
• Familiaridad con el control de acceso basado en rol (RBAC) de Azure 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 como se describe en Preparación del entorno de desarrollo.

Comprende las aplicaciones del agente y sus implementaciones

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 laboral 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 específica e inmutable 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 del agente actúa como una tabla de enrutamiento a implementaciones específicas 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.

Protocols

Un recurso de aplicación de agente ofrece un punto de conexión estable con múltiples opciones de protocolo 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 proporcionada por el extremo del proyecto. Specifically:

• 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 para las conversaciones multiturno.

Protocolo de actividad

Los agentes de foundry también pueden exponer el protocolo de actividad que usa 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. Las siguientes opciones están disponibles:

• Predeterminado (RBAC): quien realiza la llamada debe tener el rol Foundry User (o un rol personalizado con el permiso /applications/invoke/action) en el recurso de 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 RBAC de Foundry, consulte Control de acceso basado en roles para Microsoft Foundry.
• Channels (Azure Bot Service): Cuando se publica en M365/Teams o en A365 como piloto automático, Channels es la 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.

Publicación de 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: la publicación se completa y la versión del agente muestra un estado 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 invocan la aplicación del agente mediante el protocolo Responses debe concedérseles el rol integrado de Azure RBAC Foundry User (o un rol personalizado equivalente) en el recurso de la 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 su 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 la 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 de 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 de Azure).
   • project_name: El 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á configurado como 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"}]
  }
}

Crear un despliegue de agente.

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

Campos obligatorios:

• deploymentType: modo de implementación. Usa Managed para agentes de indicación y flujo de trabajo. Utilice Hosted para agentes alojados.
• 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 alojado:

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

Agentes de solicitud 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 punto de conexión con los usuarios. Después de publicar, compruebe que:

• El recurso de la aplicación del agente existe.
• La implementación 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 quien realiza la llamada tiene el rol de usuario de Foundry en el recurso Agent Application.

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 del 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 desplegar un agente con un nombre diferente, debe:

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 política 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 autores de las llamadas necesitan el rol de usuario de Foundry (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 concreta, por lo que puede conceder acceso a un único agente publicado sin dar a los usuarios acceso a todo su proyecto de Foundry ni a 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 publicar, invoca el agente a través de su punto de conexión mediante el protocolo de 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 de agente en Microsoft 365 Copilot y Teams, consulta Publicar agentes en Microsoft 365 Copilot y Microsoft Teams.

Para publicar su agente como piloto automático, consulte Publicar un agente como piloto automático en Agent 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:

• Rol de usuario de Foundry en el ámbito de Agent Application
• Los paquetes openai y azure-identity instalados y autenticados tal como se describe en Preparar tu entorno de desarrollo

Utilice el cliente OpenAI con el punto de conexión de aplicaciones de agente

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 Usuario de Foundry en el recurso aplicación del agente.

Consideraciones de seguridad y privacidad

• Utilizar el menor privilegio. 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. Utilice el punto de conexión de la aplicación de agente y RBAC en los recursos de la aplicación.
• No inserte tokens de acceso en el código fuente, los scripts o las aplicaciones cliente. Utiliza 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 experiencias multiturno. 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.

FAQs

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

Actualmente hay una limitación temporal en la que los agentes publicados solo admiten interacciones de la API de respuestas sin estado (es decir, no hay 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 cuales hemos construido no proporcionan aislamiento de datos nativo, 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
• Más información sobre los agentes hospedados
• Obtenga información sobre cómo publicar agentes en Microsoft 365 Copilot y Microsoft Teams
• Migra de aplicaciones de agente al nuevo modelo de agente

Pasos siguientes