Registro y administración de agentes personalizados

El plano de control de Microsoft Foundry proporciona administración centralizada y observabilidad para los agentes que se ejecutan en distintas plataformas e infraestructuras. Puede registrar agentes personalizados, que se ejecutan en servicios de proceso de Azure u otros entornos en la nube, para obtener visibilidad sobre sus operaciones y controlar su comportamiento.

En este artículo se muestra cómo registrar un agente personalizado en el Plano de Control Foundry. Aprenderá a configurar el agente para el registro, configurar la recopilación de telemetría y usar las funcionalidades de administración del plano de control.

Prerrequisitos

Antes de empezar, asegúrese de que tiene:

• Una cuenta de Azure con una suscripción activa. Si no tiene una, cree una cuenta gratuita de Azure, que incluye una suscripción de evaluación gratuita.

• Un proyecto de fundición. Si no tiene uno, cree un proyecto.

• Foundry usa Azure API Management para registrar agentes como API. Configura AI Gateway en el recurso Foundry.

• Un agente que implemente y exponga a través de un punto de conexión accesible (ya sea un punto de conexión público o un punto de conexión accesible desde la red donde implemente el recurso Foundry).

Adición de un agente personalizado

Puede registrar un agente personalizado en el plano de control. Desarrolle el agente en la tecnología que prefiera, tanto las soluciones de plataforma como de infraestructura.

Al registrar un agente personalizado, Foundry usa Azure API Management para actuar como proxy para las comunicaciones con el agente, por lo que puede controlar el acceso y supervisar la actividad.

Al registrar un agente personalizado, la arquitectura resultante es la siguiente:

Verifica tu agente

Compruebe que el agente cumple los requisitos de registro:

Prepare su proyecto de Foundry

Los agentes personalizados se incorporan a los proyectos de Foundry. Antes de registrar el agente, asegúrese de configurar el proyecto correctamente.

1. Inicie sesión en Microsoft Foundry. Asegúrese de que el interruptor New Foundry está activado. Estos pasos hacen referencia a Foundry (nuevo).

   

2. Asegúrese de que AI Gateway está configurado en el proyecto:

   1. Seleccione Ejecutar>Panel de administración.

   2. Abra la pestaña Puerta de enlace de IA.

   3. En la página se enumeran todas las puertas de enlace de IA configuradas y asignadas a un recurso Foundry. Compruebe si el recurso Foundry que desea usar tiene una puerta de enlace de AI asociada.

      

   4. Si el recurso Foundry que quiere usar no tiene configurada una puerta de enlace de IA (no aparece), agregue una mediante la opción Agregar puerta de enlace de IA. AI Gateway es gratis de configurar y desbloquea potentes características de gobernanza, como la seguridad, la telemetría y los límites de velocidad para tus agentes, herramientas y modelos.

   5. Para más información sobre cómo configurar AI Gateway, consulte Creación de una puerta de enlace de AI.

3. Asegúrese de que tiene la observabilidad configurada en el proyecto. El plano de control usa el recurso de Azure Application Insights asociado al proyecto seleccionado para emitir telemetría para ayudarle a diagnosticar el agente:

   1. Seleccione Ejecutar>Panel de administración.

   2. En Todos los proyectos, use el cuadro de búsqueda para buscar el proyecto.

   3. Seleccione el proyecto.

   4. Seleccione la pestaña Recursos conectados.

   5. Asegúrese de que hay un recurso asociado en la categoría Application Insights.

      

   6. Si no hay ningún recurso asociado, agregue uno seleccionando Agregar conexión y seleccione Application Insights.

   7. El proyecto está configurado para la observabilidad y el seguimiento.

Registro del agente

Para registrar el agente, siga estos pasos:

1. Seleccione Operar en la navegación superior derecha.

2. Seleccione el panel Información general .

3. Seleccione Agente de registro.

   

4. Aparece el asistente de registro. En primer lugar, complete los detalles sobre el agente que desea registrar. Las siguientes propiedades describen el agente tal y como se ejecuta en su plataforma

   Propiedad	Description	Obligatorio
   Dirección URL del agente	Representa el endpoint (URL) donde se ejecuta el agente y recibe solicitudes. En general, pero en función del protocolo, indique la dirección URL base que usan los clientes. Por ejemplo, si tu agente interactúa con la API de finalizaciones de chat de OpenAI, debes indicar https://<host>/v1/ sin incluir /chat/completions, ya que los clientes generalmente lo añaden.	Sí
   Protocolo	El protocolo de comunicación compatible con su agente. Use HTTP en general, o si el agente admite A2A de forma más específica, especifíquelo.	Sí
   Dirección URL de la tarjeta del agente de A2A	Ruta de acceso a la especificación JSON de la tarjeta del agente. Si no lo especifica, el sistema usa el valor predeterminado /.well-known/agent-card.json.	No
   Identificador del agente de OpenTelemetry	El id. de agente que utiliza su agente para emitir trazas de acuerdo con las convenciones semánticas de OpenTelemetry para la IA Generativa. Los rastros lo indican en el atributo gen_ai.agents.id para los intervalos con el nombre de la operación create_agent. Si no especifica esto, el sistema utiliza el valor de nombre del agente para encontrar las trazas y registros que reporta este nuevo agente.	No
   Dirección URL del portal de administración	Dirección URL del portal de administración donde puede realizar más operaciones de administración para este agente. Foundry puede almacenar este valor para facilitar el acceso. Foundry no tiene acceso para realizar operaciones directamente en dicho portal de administración.	No

5. A continuación, configure cómo desea que el agente aparezca en el plano de control:

   Propiedad	Description	Obligatorio
   Proyecto	Proyecto en el que se registra el agente. Foundry usa la pasarela de IA configurada en el recurso donde reside el proyecto para configurar el punto de conexión de entrada hacia el agente. Solo puede seleccionar proyectos con AI Gateway habilitado en sus recursos. Si no ve ninguno, configure AI Gateway en su recurso de Foundry. También es aconsejable configurar Azure Application Insights en el proyecto seleccionado. Foundry usa el recurso de Azure Application Insights del proyecto para almacenar trazas y registros.	Sí
   Nombre del agente	Nombre del agente como quiere que aparezca en Foundry. El sistema también puede usar este nombre para buscar seguimientos y registros pertinentes en Azure Application Insights si no especifica un valor diferente en el campo Id. de agente de OpenTelemetry.	Sí
   Descripción	Una descripción clara sobre este agente.	No

6. Guarde los cambios.

7. Foundry agrega al nuevo agente. Seleccione la pestaña Recursos del panel izquierdo para comprobar la lista de agentes.

8. Para mostrar solo agentes personalizados, use el filtro Origen y seleccione Personalizado.

   

Conecte a los clientes con el agente

Al registrar su agente en Foundry, obtendrá una nueva dirección URL para que sus clientes la usen. Foundry actúa como proxy para las comunicaciones con el agente, por lo que puede controlar el acceso y supervisar la actividad.

Para distribuir la nueva dirección URL para que los clientes llamen al agente:

1. Seleccione el agente personalizado mediante el selector de radio.

2. En el panel de detalles de la derecha, en Dirección URL del agente, seleccione la opción copiar.

   

3. Use la nueva dirección URL para llamar al agente en lugar del punto de conexión original.

En este ejemplo, implementará un agente de LangGraph y los clientes usarán el SDK de LangGraph para consumirlo. El cliente usa el valor de la nueva URL del agente. Este código crea un hilo, envía un mensaje que pregunta sobre el tiempo y devuelve la respuesta en streaming.

from langgraph_sdk import get_client

client = get_client(url="https://apim-my-foundry-resource.azure-api.net/my-custom-agent/") 

async def stream_run():
   thread = await client.threads.create()
   input_data = {"messages": [{"role": "human", "content": "What's the weather in LA?"}]}
   
   async for chunk in client.runs.stream(thread['thread_id'], assistant_id="your_assistant_id", input=input_data):
       print(chunk)

Salida esperada: el agente procesa el mensaje y transmite las respuestas como fragmentos. Cada fragmento contiene resultados parciales de la ejecución del agente, que pueden incluir llamadas a la función meteorológica y la respuesta final sobre el tiempo en Los Ángeles.

Bloquear y desbloquear el agente

En el caso de los agentes personalizados, Foundry no tiene acceso a la infraestructura subyacente donde se ejecuta el agente, por lo que las operaciones de arranque y parada no están disponibles. Sin embargo, Foundry puede bloquear las solicitudes entrantes al agente, lo que impide que los clientes lo consuman. Esta funcionalidad permite a los administradores deshabilitar un agente si se comporta mal.

Para bloquear las solicitudes entrantes al agente:

1. Seleccione Operar en la navegación superior derecha.

2. Seleccione Recursos en el panel izquierdo.

3. Seleccione el agente que desea bloquear. Aparece el panel de información.

4. Seleccione Estado de actualización y, a continuación, seleccione Bloquear.

   

5. Confirme la operación.

Después de bloquear el agente, el estado del agente en Foundry se muestra como Bloqueado. Los agentes en estado Bloqueado se ejecutan en su infraestructura asociada, pero no pueden aceptar solicitudes entrantes. Foundry bloquea cualquier intento de interactuar con el agente.

Para desbloquear el agente:

1. Seleccione Estado de actualización y, a continuación, seleccione Desbloquear.

2. Confirme la operación.

Habilitación de la telemetría para el agente

Foundry usa el estándar abierto OpenTelemetry para comprender qué agentes están haciendo. Si el proyecto tiene configurada Azure Application Insights, Foundry registra las solicitudes en Azure Application Insights de forma predeterminada. Esta telemetría también se usa para calcular:

• Runs
• Frecuencia de errores
• Uso (si está disponible)

Para obtener el mejor nivel de fidelidad, Foundry espera que los agentes personalizados cumplan las convenciones semánticas de la solución generative AI en el estándar OpenTelemetry.

Ver ejecuciones y registros

Puede ver los rastros y registros enviados a Foundry. Para verlos haga lo siguiente:

1. Seleccione Operar en la navegación superior derecha.

2. Seleccione Recursos en el panel izquierdo.

3. Seleccione el agente.

4. Se muestran secciones de seguimiento.

5. Verá una entrada para cada llamada HTTP realizada al punto de conexión del agente.

6. Para ver los detalles, seleccione una entrada:

   

   Sugerencia

   En este ejemplo, puede ver cómo los clientes usan el punto de conexión del nuevo agente para comunicarse con el agente. En el ejemplo se muestra un agente utilizando el Protocolo de Agente de LangChain. Los clientes usan la ruta /runs/stream.

7. Observe en este ejemplo que, además de la publicación HTTP, no hay más detalles en el seguimiento. Esto se debe a que no se agregó ninguna instrumentación adicional al código del agente. Consulte la sección siguiente para aprender a instrumentar el código y obtener más detalles, como llamadas a herramientas, llamadas LLM, etc.

Implementar agentes de código personalizados

Si crea su agente con código personalizado, debe instrumentar su solución para que emita trazas de acuerdo con el estándar OpenTelemetry y las envíe a Azure Application Insights. La instrumentación permite a Foundry tener acceso a un mayor nivel de detalle sobre lo que está haciendo el agente.

Envíe trazas al recurso Azure Application Insights de su proyecto utilizando su clave de instrumentación. Para obtener la clave de instrumentación asociada al proyecto, siga las instrucciones que se indican en Habilitación del seguimiento en el proyecto.

En este ejemplo, configuras un agente desarrollado con LangGraph para emitir trazas en el estándar OpenTelemetry. El seguimiento captura todas las operaciones del agente, incluidas las llamadas a herramientas y las interacciones del modelo, y las envía a Azure Application Insights para la supervisión.

Este código usa el paquete langchain-azure-ai . Obtenga información sobre cómo instrumentar soluciones específicas con OpenTelemetry en función del lenguaje de programación y del marco que se usa en la solución en Language APIs & SDKs..

pip install -U langchain-azure-ai[opentelemetry]

A continuación, configure su agente:

from langchain.agents import create_agent
from langchain_azure_ai.callbacks.tracers import AzureAIOpenTelemetryTracer

application_insights_connection_string = 'InstrumentationKey="12345678...'

tracer = AzureAIOpenTelemetryTracer(
    connection_string=application_insights_connection_string,
    enable_content_recording=True,
)

def get_weather(city: str) -> str:
    """Get weather for a given city."""
    return f"It's always sunny in {city}!"

agent = create_agent(
    model="openai:gpt-5.1",
    tools=[get_weather],
    system_prompt="You are a helpful assistant",
).with_config({ "callbacks": [tracer] })

Salida esperada: el agente se ejecuta normalmente al emitir automáticamente seguimientos de OpenTelemetry a Azure Application Insights. Los registros incluyen nombres de operaciones, duraciones, llamadas a modelos, invocaciones de herramientas y uso de tokens. Puede ver estos seguimientos en el portal de Foundry en la sección Seguimientos.

Instrumentación de soluciones de plataforma

Si el agente se ejecuta en una solución de plataforma que admite OpenTelemetry, pero no admite Azure Application Insights, debe implementar un recopilador de OpenTelemetry y configurar el software para enviar datos de OTLP al recopilador (configuración estándar de OpenTelemetry).

Configure el recopilador con el exportador de Azure Monitor para reenviar datos a Application Insights mediante la cadena de conexión. Para más información sobre cómo implementar, consulte Configuración de OpenTelemetry de Azure Monitor.

Solución de problemas de rastros

Si no ve rastros, compruebe lo siguiente:

Contenido relacionado

• ¿Qué es el plano de control de Microsoft Foundry?
• Supervisión de agentes en toda la flota
• Optimización del costo y el rendimiento en toda la flota del agente