Registro y administración de agentes personalizados

Microsoft Foundry Control Plane 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 Azure servicios de proceso 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 Foundry Control Plane. Aprenderá a configurar el agente para el registro, configurar la recopilación de datos y usar las funcionalidades de administración del plano de control de Foundry.

Requisitos previos

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

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

• Una puerta de enlace de IA configurada en el recurso Foundry. Foundry usa Azure API Management para registrar agentes como API.

• Un agente que implantas y expones a través de un punto de conexión accesible. El punto de conexión puede ser un punto de conexión público o un punto de conexión accesible desde la red donde se implementa el recurso Foundry.

Adición de un agente personalizado

Puede registrar un agente personalizado en el Plano de Control de Foundry. Desarrolle el agente en la tecnología que prefiera, tanto para soluciones de plataforma como de infraestructura.

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

En el diagrama siguiente se muestra la arquitectura resultante al registrar un agente personalizado.

Verifique su agente

Compruebe que el agente cumple los requisitos de registro:

Prepara tu proyecto de Foundry

Antes de registrar el agente personalizado que agregó a un proyecto foundry, 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 (new).

   

2. Asegúrese de que una puerta de enlace de IA esté configurada en el proyecto:

   1. En la barra de herramientas, seleccione Operar.

   2. En el panel izquierdo, seleccione Administrador.

   3. Abra la pestaña Pasarela de IA.

   4. En el panel 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 IA asociada.

      

   5. 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 AI .

      Una puerta de enlace de IA es gratuita para configurar y desbloquear características de gobernanza eficaces, como seguridad, datos de diagnóstico y límites de velocidad para los agentes, las herramientas y los modelos. Para más información, consulte Creación de una puerta de enlace de IA.

3. Asegúrese de que tiene la observabilidad configurada en el proyecto. Foundry Control Plane usa el recurso de Application Insights asociado al proyecto seleccionado para emitir datos para ayudarle a diagnosticar el agente.

   1. En la barra de herramientas, seleccione Operar.

   2. En el panel izquierdo, seleccione Administrador.

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

   4. Seleccione el proyecto.

   5. Seleccione la pestaña Recursos conectados .

   6. Asegúrese de que hay un recurso asociado en la categoría AppInsights .

      

   7. Si no hay ningún recurso asociado, agregue uno seleccionando Agregar conexión>de Application Insights.

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

Registra el agente (activo)

1. En la barra de herramientas, seleccione Operar.

2. En el panel Información general , seleccione Registrar recurso.

   

3. Aparece el asistente de registro. En primer lugar, complete los detalles sobre el agente que desea registrar. Las siguientes propiedades describen el agente a medida que se ejecuta en su plataforma:

   Propiedad	Descripción	Obligatorio
   Dirección URL del agente	El endpoint (dirección 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 usa la API de finalización de chats de OpenAI, indica https://<host>/v1/ sin /chat/completions porque generalmente los clientes lo agregan.	Sí
   Protocolo	El protocolo de comunicación que su agente admite. Usa HTTP en general. O, si su agente admite A2A de manera más específica, indique esa opción.	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 tu agente utiliza para emitir trazas según las convenciones semánticas de OpenTelemetry para la inteligencia artificial generativa. Los seguimientos lo indican en el atributo gen_ai.agent.id para spans con el nombre create_agent de la operación. Si no especifica este valor, el sistema usa el valor nombre del agente para buscar seguimientos y registros que notifica 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 mayor comodidad. Foundry no tiene acceso para realizar operaciones directamente en este portal.	No

4. Configure cómo desea que el agente aparezca en el Plano de Control Foundry:

   Propiedad	Descripción	Obligatorio
   Project	El proyecto donde registras al agente. Foundry usa el gateway de IA configurado en el recurso que contiene el proyecto para configurar el punto de conexión de entrada al agente. Solo puede seleccionar proyectos que tengan habilitada una puerta de enlace de IA en sus recursos. Si no ve ninguna puerta de enlace de IA, configure una puerta de enlace de IA en el recurso Foundry. También se recomienda configurar Application Insights en el proyecto seleccionado. Foundry utiliza el recurso de Application Insights del proyecto para procesar seguimientos 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 relevantes en Application Insights si no especifica un valor diferente para el identificador del agente de OpenTelemetry.	Sí
   Descripción	Una descripción clara sobre este agente.	No

5. Guarde los cambios.

6. Foundry ha agregado el nuevo agente. Para ver la lista de agentes, seleccione Recursos en el panel izquierdo.

7. 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. Dado que Foundry actúa como proxy para las comunicaciones con el agente, puede controlar el acceso y supervisar la actividad.

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

1. Seleccione el agente personalizado.

2. En el panel de detalles, 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, desplegará un agente de LangGraph. Los clientes usan el SDK de LangGraph para consumirlo. El cliente usa el nuevo valor de dirección URL del agente. Este código crea un subproceso, envía un mensaje que pregunta sobre el tiempo y transmite la respuesta.

import asyncio
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)

asyncio.run(stream_run())

Salida esperada: el agente procesa el mensaje y transmite las respuestas como fragmentos. Cada fragmento contiene resultados parciales de la ejecución del agente. Estos resultados pueden incluir llamadas de herramientas a la función meteorológica y la respuesta final sobre el tiempo de 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 no están disponibles las operaciones de inicio y detener. Sin embargo, Foundry puede bloquear las solicitudes entrantes al agente para que los clientes no puedan usarlas. Esta funcionalidad permite a los administradores deshabilitar un agente si se comporta mal.

Para bloquear las solicitudes entrantes al agente:

1. En la barra de herramientas, seleccione Operar.

2. En el panel izquierdo, seleccione Activos.

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 valor estado del agente en Foundry está bloqueado. Los agentes en el 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 datos de diagnóstico para el agente

Foundry usa el estándar abierto OpenTelemetry para comprender qué agentes están haciendo. Si el proyecto tiene configurado Application Insights, Foundry registra las solicitudes en Application Insights de forma predeterminada. Foundry también usa estos datos para calcular:

• Ejecuciones
• Tasa de errores
• Uso (si está disponible)

Para obtener el mejor nivel de fidelidad, Foundry espera que los agentes personalizados cumplan las convenciones semánticas para las soluciones de IA generativas en el estándar OpenTelemetry.

Visualización de rastros y registros que se envían a Foundry

1. En la barra de herramientas, seleccione Operar.

2. En el panel izquierdo, seleccione Activos.

3. Seleccione el agente.

4. En la sección Trazas se muestra una entrada para cada llamada HTTP realizada al endpoint del agente.

   Para ver los detalles, seleccione una entrada.

   

   Propina

   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 servido con el Protocolo de Agente de LangChain. Los clientes usan la ruta /runs/stream.

En este ejemplo, el seguimiento no incluye ningún detalle más allá de la publicación HTTP. El código del agente no incluye ninguna instrumentación adicional. En la sección siguiente, aprenderá a instrumentar el código y a obtener detalles como llamadas a herramientas y llamadas de modelo de lenguaje grande (LLM).

Instrumentar agentes de código personalizados

Si compila el agente mediante código personalizado, instrumente la solución para emitir seguimientos según el estándar OpenTelemetry y enviarlos a Application Insights. La instrumentación proporciona acceso a Foundry para obtener información detallada sobre lo que está haciendo el agente.

Envíe rastros al recurso de Application Insights de su proyecto mediante la clave de instrumentación. Para obtener la clave de instrumentación asociada al proyecto, siga las instrucciones de Conexión de Application Insights al proyecto de Foundry.

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

Este código usa el paquete langchain-azure-ai . Para obtener instrucciones sobre cómo instrumentar soluciones específicas con OpenTelemetry, en función del lenguaje de programación y el marco que usa la solución, consulte API de lenguaje y SDK.

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

A continuación, instrumente el 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 Application Insights. Los seguimientos incluyen nombres de operación, duraciones, llamadas de modelo, invocaciones de herramientas y uso de tokens. Puede ver estos seguimientos en el portal de Foundry, en la sección Seguimientos .

Soluciones de plataforma de instrumentos

Si el agente se ejecuta en una solución de plataforma que admite OpenTelemetry, pero no admite Application Insights, implemente un recopilador de OpenTelemetry y configure 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 el cadena de conexión. Para obtener más información sobre cómo implementarlo, consulte Configure Azure Monitor OpenTelemetry.

Solución de problemas de seguimientos

Si no ve rastros, compruebe los siguientes aspectos:

Contenido relacionado

• ¿Qué es el Plano de Control de Microsoft Foundry?
• Monitorea la salud y el rendimiento de los agentes en toda tu flota
• Optimización del costo y el rendimiento del modelo