Depurar un agente hospedado

Diagnostique y corrija problemas comunes al compilar, ejecutar e implementar agentes con azd ai agent para Microsoft Foundry. Comience con los comandos de diagnóstico. A continuación, use las secciones basadas en síntomas para solucionar problemas de autenticación, desarrollo local, implementación, comandos directos, registros y rutinas.

Prerequisites

Recopilación del contexto de diagnóstico

Antes de profundizar en errores específicos, use estos comandos para recopilar contexto:

# Check extension version
azd ai agent version

# Verify Azure authentication
azd auth login

# Show current environment configuration
azd env get-values

# View agent details
azd ai agent show

# Show the resolved Foundry project endpoint and where it came from
azd ai project show

# Stream production logs
azd ai agent monitor --follow

Para un informe de estado estructurado, ejecute azd ai agent doctor. Para obtener más información, consulte Diagnosticar un proyecto con Agent Doctor.

Diagnóstico de la latencia de invocación

Utilice los encabezados de depuración de latencia para determinar si una solicitud lenta del agente hospedado pasó tiempo en la plataforma, en el aprovisionamiento de la infraestructura, en la espera del contenedor o en el procesamiento de la solicitud en su agente. Estos encabezados son señales de diagnóstico, no SLA ni métricas de facturación.

Habilite el diagnóstico en cada solicitud estableciendo x-ms-debug-latency-enabled: true. Si la solicitud no incluye este encabezado, la respuesta no incluirá los x-ms-debug-latency-* encabezados.

  1. Agregar el encabezado de latencia a una solicitud del protocolo Responses o Invocations de un agente alojado. En este ejemplo se usa el protocolo Responses:

    ENDPOINT="https://{account}.services.ai.azure.com/api/projects/{project}"
API_VERSION="v1"
TOKEN=$(az account get-access-token \
  --resource https://ai.azure.com \
  --query accessToken -o tsv)
AGENT="my-code-agent"

curl --http2 -i -X POST \
  "$ENDPOINT/agents/$AGENT/endpoint/protocols/openai/responses?api-version=$API_VERSION" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "x-ms-debug-latency-enabled: true" \
  -d '{"model":"gpt-5.4-mini","input":"Hello, agent!","stream":false}'

  2. Inspeccione los encabezados de respuesta. Todos los valores de latencia son milisegundos enteros:

    Cabecera Meaning
    x-ms-debug-latency-session-start-type Tipo de inicio de sesión que desencadenó la solicitud: un inicio en frío (cold), un inicio en caliente (warm) o una reanudación desde inactividad (resume).
    x-ms-debug-latency-platform-preprocessing-ms Tiempo de la plataforma para la admisión, la autenticación, la búsqueda de sesión y la orquestación. No incluye retrasos en el aprovisionamiento de micro vm ni en la preparación del contenedor. Disponible para inicios de sesión en frío, en caliente y reanudados.
    x-ms-debug-latency-infra-setup-ms Es hora de aprovisionar la micro-VM. Se omite para las solicitudes "calientes".
    x-ms-debug-latency-container-readiness-ms Tiempo desde la creación de la micro-VM hasta que el contenedor indique que está listo. Se omite para las solicitudes "calientes".
    x-ms-debug-latency-container-response-ms Tiempo transcurrido desde el reenvío del proxy hasta que se confirman los encabezados de respuesta. Incluye la transferencia de solicitudes, la configuración de conexión, el control del agente, los reintentos y el almacenamiento en búfer de directivas de salida.
    x-ms-debug-latency-response-begin-ms Tiempo total de aceptación del servicio hasta que se confirman los encabezados de respuesta. Este valor no es el tiempo hasta el primer byte del cuerpo de la respuesta ni hasta el primer evento enviado por el servidor.

    Los cuatro componentes de temporización suman x-ms-debug-latency-response-begin-ms. En una solicitud "fría" o reanudada, si la plataforma no puede capturar todos los límites de aprovisionamiento, omite los encabezados de infraestructura y de disponibilidad e incluye ese tiempo en el preprocesamiento de la plataforma.

  3. Use el tipo de inicio de sesión y el componente de tiempo más grande para identificar el origen probable de retraso:

    Result Interpretación Qué hacer
    x-ms-debug-latency-session-start-type es cold o resume, y x-ms-debug-latency-infra-setup-ms es alto La plataforma ha dedicado tiempo a aprovisionar la micro-VM. Compara varias solicitudes en frío o reanudadas. Si el retraso persiste, registre el identificador de respuesta, la marca de tiempo y los encabezados de latencia para una solicitud de soporte técnico.
    x-ms-debug-latency-session-start-type es cold o resume, y x-ms-debug-latency-container-readiness-ms es alto El contenedor tardó mucho en iniciarse e indicar que estaba listo. Mida los tiempos de inicialización en los registros de inicio, reduzca el trabajo antes de que el endpoint de disponibilidad pase a estar disponible y precompile el código de la aplicación siempre que sea posible.
    x-ms-debug-latency-platform-preprocessing-ms es alto para cualquier tipo de inicio de sesión El retraso se produjo en la plataforma antes del aprovisionamiento de micro-VM o la preparación del contenedor. Cree una solicitud de soporte técnico. Incluya el identificador de respuesta, la marca de tiempo, el tipo de inicio de sesión y los encabezados de latencia.
    x-ms-debug-latency-container-response-ms, x-ms-debug-latency-first-byte-ms o el first_byte_ms del trailer es alto El retraso se produjo después de iniciarse el reenvío a través del proxy. Instrumenta el gestor de solicitudes e inspecciona los registros del agente, las llamadas al modelo, las llamadas a herramientas, los reintentos y el almacenamiento en búfer de salida.

Reducción del tiempo de preparación del contenedor

El valor de preparación del contenedor incluye el tiempo necesario para iniciar el proceso, cargar la aplicación y devolver HTTP 200 desde /readiness. Agregue marcas de tiempo a los registros de inicio para identificar importaciones lentas, carga de dependencias, llamadas de red y otro trabajo de inicialización.

Aplique estas optimizaciones a los pasos lentos que identifique:

  • Instale las dependencias y compile código al compilar la imagen. No ejecute la instalación, restauración ni compilación del paquete en el inicio del contenedor.
  • Use una compilación de varias fases y excluya herramientas de compilación, cachés de paquetes, pruebas y otros archivos de desarrollo de la imagen en tiempo de ejecución.
  • Evite las invocaciones al modelo, las migraciones, el descubrimiento de herramientas y las descargas de recursos antes de que todo esté listo. Paralelizar la inicialización independiente que debe completarse primero.
  • Manténgase /readiness centrado en si el agente puede aceptar solicitudes. Si aplaza la inicialización, mida la primera solicitud para asegurarse de que no ha desplazado el retraso de inicio al control de solicitudes.

Instale las dependencias en un entorno virtual que luego copiará en la imagen de ejecución. Compile las dependencias con el mejor esfuerzo, por lo que un archivo no analizable en un paquete de terceros no produce un error en la compilación. Compile la aplicación estrictamente para que los errores de sintaxis produzcan un error en la compilación.

FROM python:3.13-slim AS build

WORKDIR /app
RUN python -m venv /opt/venv
ENV PATH="/opt/venv/bin:$PATH"

COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY . .
RUN PYTHONDONTWRITEBYTECODE= python -m compileall -q /opt/venv \
      || true; \
    PYTHONDONTWRITEBYTECODE= python -m compileall -q /app

FROM python:3.13-slim AS final

ENV PATH="/opt/venv/bin:$PATH"
WORKDIR /app

COPY --from=build /opt/venv /opt/venv
COPY --from=build /app /app

# Precompile the standard library in the runtime image.
RUN PYTHONDONTWRITEBYTECODE= python -m compileall -q \
    "$(python -c "import sysconfig; print(sysconfig.get_path('stdlib'))")" \
    || true

CMD ["python", "main.py"]

Borrar PYTHONDONTWRITEBYTECODE para este paso de compilación permite a Python escribir el código de bytes en la imagen. La variable de entorno bloquea las escrituras de código de bytes, no lecturas, por lo que el contenedor en ejecución todavía puede usar los archivos compilados.

Referencia: compileall - Bibliotecas de Python de compilación de bytes

Compile cualquiera de las imágenes para la arquitectura x86-64 requerida por los agentes hospedados:

docker build --platform linux/amd64 -t my-agent:latest .

Aquí, linux/amd64 es una plataforma de Docker, no un identificador de tiempo de ejecución de .NET.

Referencia: Requisitos de contenedor del agente hospedado

Investigación de la latencia del agente y del modelo

Si la preparación del contenedor es rápida, pero la respuesta del contenedor o el tiempo hasta el primer byte son altos, centre su investigación en la trayectoria de la solicitud después de que comience el reenvío. Ejecute azd ai agent monitor --follow mientras reproduce la solicitud y añada trazabilidad en las llamadas al modelo, las llamadas a herramientas, los servicios externos, los reintentos y la serialización de la respuesta. Para más información, consulte Supervisión de los registros del agente hospedado.

Para un agente que llama a un modelo de lenguaje grande, mida la latencia del modelo por separado antes de cambiar la implementación. Compara el tiempo hasta el primer token, el tiempo entre tokens, el recuento de tokens generados, el tamaño de la solicitud, la utilización del despliegue y la limitación de tráfico. Después, evalúe la elección del modelo, los límites del token de salida, el streaming y la separación de cargas de trabajo. Consulte Mejorar el rendimiento de Azure OpenAI.

Si las mediciones muestran limitaciones de capacidad sostenidas para una carga de trabajo predecible, evalúe una implementación con capacidad aprovisionada y dimensiónela en función de los tokens de entrada observados, los tokens de salida y la tasa de solicitudes. Consulte Rendimiento aprovisionado.

Inspección de los tiempos de finalización

En HTTP/2 o versiones posteriores, el servicio puede devolver el trailer de respuesta de tipo best-effort x-ms-debug-latency-final. Repite los valores del encabezado de respuesta y puede agregar estos campos:

Campo Meaning
first_byte_ms Tiempo desde la aceptación por parte del servicio hasta el primer byte del cuerpo de la respuesta o el primer evento enviado por el servidor.
total_last_byte_ms Tiempo desde la aceptación del servicio hasta que se complete el reenvío de respuesta.

El trailer utiliza un formato versionado y delimitado por punto y coma:

x-ms-debug-latency-final: v=1;start=cold;platform_pre_ms=...;
  infra_ms=...;ready_ms=...;container_response_ms=...;
  response_begin_ms=...;first_byte_ms=...;total_last_byte_ms=...

Las respuestas HTTP/1.1 no incluyen este tráiler. Un trailer también puede no aparecer tras una cancelación, una desconexión del cliente, un error durante la transmisión o cuando una pasarela o un SDK no conservan los trailers. Trate los encabezados de respuesta como contrato de diagnóstico garantizado.

Recuperación de los resultados de latencia almacenada

El servicio almacena los intervalos capturados con la respuesta o la invocación. Una solicitud GET posterior para la misma respuesta o identificador de invocación devuelve los tiempos de la solicitud original como encabezados de respuesta. La solicitud GET no requiere la cabecera de latencia y no mide la solicitud GET en sí.

La solicitud GET también puede devolver estos valores de finalización como encabezados normales:

Cabecera Meaning
x-ms-debug-latency-first-byte-ms Tiempo hasta el primer byte del cuerpo de la respuesta.
x-ms-debug-latency-total-last-byte-ms Tiempo hasta completar el reenvío de la respuesta.

El almacenamiento es finalmente coherente, por lo que es posible que una solicitud GET inmediatamente después de la solicitud original no incluya todavía los encabezados. Para una respuesta o invocación asincrónica, solo están disponibles los valores de sobrecarga de la plataforma: tipo de inicio de sesión, preprocesamiento de la plataforma, configuración de la infraestructura y preparación del contenedor. Los encabezados de latencia no se emiten para las respuestas fallidas del proxy ni para las solicitudes de WebSocket (invocations_ws).

Corrección de errores de autenticación

Corregir AuthenticationError

Síntomas: El agente no se inicia localmente o devuelve un error 401/403 al llamar al modelo de IA.

Causas y correcciones:

  • Credenciales expiradas: ejecute azd auth login para actualizar la sesión de Azure.
  • Suscripción incorrecta : compruebe con azd env get-values | grep AZURE_SUBSCRIPTION_ID y compare con la suscripción del proyecto Foundry.
  • Faltan roles RBAC: tu identidad necesita el acceso Foundry User o equivalente en el proyecto de Foundry.

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.

Tu identidad también necesita Cognitive Services OpenAI User para utilizar las implementaciones de modelos.

Corregir AuthorizationFailed durante el aprovisionamiento

Síntomas:azd up o azd provision falla con un error de permisos.

Corrección: Solicite el rol Colaborador en la suscripción de Azure. Para CI/CD, la entidad de servicio también necesita Foundry Owner.

Corregir SubscriptionNotRegistered

Síntomas: Se produce un error en el aprovisionamiento porque no se registra un proveedor de recursos necesario.

Corrección:

az provider register --namespace Microsoft.CognitiveServices
az provider register --namespace Microsoft.ContainerRegistry

Corrección de problemas de desarrollo local

Corrección de la conexión rechazada en el puerto 8088

Síntomas:azd ai agent invoke --local no se puede conectar.

Causas y correcciones:

  • Agente que no se está ejecutando: inícielo con azd ai agent run en un terminal independiente.

  • Conflicto de puertos: otro proceso usa el puerto 8088. Deténgalo o use un puerto personalizado:

    azd ai agent run --port 9090
azd ai agent invoke --local --port 9090 "Hello!"

  • Fallo al iniciar -- compruebe la salida de error en el terminal donde se está ejecutando azd ai agent run. Entre las causas comunes se incluyen la falta de dependencias, errores de importación o valores incorrectos de startupCommand en azure.yaml.

Corrección de errores de instalación de dependencias

Síntomas:azd ai agent run se produce un error durante la instalación de dependencias.

Causas y correcciones:

  • Versión en tiempo de ejecución incorrecta: asegúrese de que está instalado Python 3.10 o .NET 8+.
  • Falta requirements.txt o .csproj : la CLI detecta automáticamente el tipo de proyecto de estos archivos. Compruebe que existen en el directorio del agente.
  • Problemas de red : el proxy corporativo puede bloquear los registros de paquetes. Compruebe la configuración de pip o dotnet.

Corrige ResourceNotFound o DeploymentNotFound

Síntomas: El agente se inicia, pero genera un error al intentar llamar al modelo.

Causas y correcciones:

  • Error de coincidencia de punto de conexión : ejecute azd env get-values y compruebe que FOUNDRY_PROJECT_ENDPOINT coincide con el punto de conexión que se muestra en el portal de Foundry.
  • No coincide el nombre de implementación del modelo -- El nombre de implementación del modelo configurado en azure.yaml debe coincidir con el nombre de implementación de su proyecto de Foundry. Compruebe el portal en Implementaciones.
  • Recursos no aprovisionados : si aún no se ha ejecutado azd up , los recursos en la nube no existirán. Ejecute azd up primero y, a continuación, pruebe localmente. El agente local todavía llama a modelos hospedados en la nube.

Corrección de problemas de implementación

Corrección de errores de compilación de contenedor

Síntomas:azd up produce un error durante la fase de compilación de Docker.

Causas y correcciones:

  • Falta el Dockerfile -- Asegúrese de que el directorio del agente contenga un Dockerfile. Si se inicializó a partir de una plantilla, se genera automáticamente.
  • Errores de contexto de compilación : Dockerfile debe estar en el directorio especificado por la ruta de acceso del servicio project en azure.yaml.
  • Instalación de dependencias en Docker : si se produce un error en la restauración de pip/dotnet dentro del contenedor, compruebe que requirements.txt o .csproj tiene todas las dependencias ancladas correctamente.

Corrija los bloqueos o los tiempos de espera de azd up

Síntomas: El aprovisionamiento o la implementación tardan mucho tiempo.

Causas y correcciones:

  • Primera implementación: la primera azd up aprovisiona todos los recursos de Azure, incluido el proyecto Foundry, ACR, la identidad administrada y la implementación del modelo, y puede tardar entre 5 y 10 minutos. Las implementaciones posteriores son más rápidas.
  • Compilación remota : de forma predeterminada, las imágenes de contenedor se compilan de forma remota en ACR. Esto puede ser más lento, pero no requiere Docker localmente. Para compilar localmente en su lugar, establezca docker.remoteBuild: false en la azure.yaml configuración del servicio.
  • Capacidad de región : algunas regiones pueden tener capacidad limitada para determinadas SKU de modelo. Pruebe otra región si el aprovisionamiento falla de manera sistemática.

Reparar un agente que se despliega pero no responde

Síntomas:azd ai agent invoke se agota el tiempo de espera o devuelve errores tras una implementación correcta.

Causas y correcciones:

  • Error del sondeo de estado -- Su contenedor debe responder a GET /readiness en el puerto 8088 con un estado 200. Compruebe los registros con azd ai agent monitor --follow.
  • Error de coincidencia de protocolo : asegúrese de que el protocolo definido en el azure.ai.agent servicio azure.yaml coincide con lo que implementa el código. Si azure.yaml indica responses pero el código solo controla invocations, o viceversa, se produce un error en las solicitudes.
  • El contenedor se bloquea -- Compruebe los registros del sistema en busca de eventos de reinicio: azd ai agent monitor --type system. Entre las causas comunes se incluyen excepciones no controladas y problemas de memoria insuficiente. Aumente los recursos de contenedor en azure.yaml si es necesario.

Corrección de errores de comando directo

Estos errores proceden de los azd ai comandos directos, como azd ai connection, azd ai toolboxy azd ai routine, cuando se ejecutan en un proyecto Foundry.

Solución: puntos de conexión del proyecto de Foundry no resuelto

Síntomas: Un comando directo sale con No Foundry project endpoint resolved. Run azd ai project set to set one, or pass --project-endpoint.

Causa: La CLI no pudo encontrar un endpoint de proyecto de Foundry en ninguna de las fuentes admitidas: el indicador --project-endpoint, el entorno activo azd, la configuración global o la variable de entorno FOUNDRY_PROJECT_ENDPOINT.

Correcciones:

  • Ejecute azd ai project set <endpoint> para almacenar el punto de conexión en la configuración global azd (~/.azd/config.json).
  • Pase --project-endpoint (-p) en cada comando: azd ai connection list -p https://my-proj.services.ai.azure.com/api/projects/my-project.
  • Configure FOUNDRY_PROJECT_ENDPOINT en su entorno de shell.

Para obtener el orden de resolución completo y cuándo gana cada origen, consulte Descripción del contexto del proyecto azd.

Solucionar errores de creación de recursos existentes

Síntomas:azd ai connection create, azd ai toolbox create, azd ai routine create o azd ai skill create falla con un error de «ya existe».

Causa: Por diseño, create no es upsert. El modo de error predeterminado impide que un desarrollador sobrescriba silenciosamente el estado de otro en un proyecto de Foundry compartido.

Correcciones:

  • Elija otro nombre y vuelva a ejecutarlo.
  • Pasa --force cuando el comando create lo admita, para reemplazar el recurso existente mediante una operación PUT de ARM. La sustitución es destructiva: sobrescribe el recurso existente y se pierde cualquier desviación derivada de ediciones manuales en el portal, metadatos o credenciales. El azd ai toolbox create comando no admite --force. Elimine el cuadro de herramientas existente o use un nuevo nombre en su lugar.

Solucionar la salida de credenciales connection show

Síntomas:azd ai connection show <name> devuelve el nombre, el tipo, el destino y el tipo de autenticación de la conexión, pero no hay ninguna clave de API ni valor de credencial.

Causa: Por diseño, los valores de credenciales nunca se devuelven de forma predeterminada. Requieren la marca explícita --show-credentials .

Corrección:

azd ai connection show tavily-conn --show-credentials

Esto invoca la API del plano de datos y requiere permisos de plano de datos en el proyecto Foundry, como Foundry User o equivalente. Si solo tienes acceso al plano de administración Reader o Contributor, la llamada genera un error con un 403. Solicita al responsable del proyecto el rol del plano de datos.

Leer registros del agente

Use azd ai agent monitor para inspeccionar el comportamiento del agente:

# Stream all recent logs
azd ai agent monitor --follow

# View system-level events (container starts, crashes, restarts)
azd ai agent monitor --type system

# Filter to a specific session
azd ai agent monitor --session-id <session-id>

Entre los patrones de registro comunes se incluyen:

Mensaje de registro Meaning
Listening on 0.0.0.0:8088 El agente se inició correctamente.
AuthenticationError Un problema de credenciales o de RBAC. Compruebe la identidad administrada.
ModelNotFound El nombre de implementación del modelo no coincide con azure.yaml.
Reinicio del contenedor en eventos del sistema Bucle de errores. Compruebe los errores de código o aumente los límites de recursos.

Diagnóstico de errores rutinarios

Las rutinas fallan de forma distinta a las llamadas interactivas agent invoke porque no hay ningún llamante presente para mostrar el error. Una rutina es una ejecución de un agente activada por temporizador, recurrente, activada por una incidencia de GitHub o activada por un evento personalizado. Use azd ai routine run list para inspeccionar lo que ha ocurrido.

Inspeccionar ejecuciones anteriores

# Recent runs of a routine: trigger time, agent input/output, status, trace link
azd ai routine run list daily-digest

Filtrar por fallos

# Failed runs only, with an OData filter
azd ai routine run list daily-digest --filter "status eq 'failed'"

Combine con --top para ampliar o restringir la ventana.

Profundizar en una ejecución concreta

# Full detail for the most recent runs as JSON, then look up the run you care about
azd ai routine run list daily-digest --top 5 --output json

La salida JSON incluye el payload de entrada, la respuesta del agente y un enlace profundo a la traza distribuida, la misma traza que vería en una invocación interactiva.

Volver a activar manualmente una rutina

Si necesita reproducir un error o probar una corrección, active la rutina a petición con dispatch:

azd ai routine dispatch daily-digest
azd ai routine dispatch triage-issues --input '{"issue":{"number":42}}'

dispatch se ejecuta de forma asincrónica e imprime un identificador de envío. Compruebe el resultado con azd ai routine run list <name>.

Corrección de una ejecución rutinaria con errores

azd ai routine run list muestra la ejecución con status: failed. Siga el vínculo de seguimiento para ver el error del agente subyacente, como el error del modelo, el error de la herramienta o el tiempo de espera. Las soluciones por parte del agente son las mismas que para los errores interactivos. Consulte Corrección de errores de autenticación y Lectura de los registros del agente.

Corregir una rutina que nunca se activa

Si azd ai routine run list no devuelve ninguna ejecución, significa que el propio desencadenador no se está activando:

  1. Compruebe que la rutina está habilitada: azd ai routine show <name>. Busque enabled: true.
  2. Para los desencadenadores timer, comprueba que --at sea una fecha futura y que aún no se haya activado.
  3. Para los desencadenadores recurring, compruebe que la expresión --cron es válida y que --time-zone es lo que esperaba.
  4. Para los desencadenadores github-issue, compruebe que --connection-id corresponda a una conexión válida y que el repositorio de GitHub y --issue-event coincidan con los eventos que emite el repositorio.
  5. Para los desencadenadores custom, compruebe que el ámbito de --provider, --event-name y --parameters coincida con los eventos que publica el proveedor.

Obtener más ayuda

  • Modo de depuración: añada --debug a cualquier comando azd para obtener una salida detallada.
  • Azure portal: compruebe el proyecto Foundry en el portal de Azure para ver el estado de los recursos y los diagnósticos.
  • Informa de un error -- Informa de problemas en github.com/Azure/azure-dev/issues.

Contenido relacionado

  • Se actualizó por última vez el