Invocación de un agente hospedado con la CLI para desarrolladores de Azure

Use azd ai agent invoke para enviar mensajes al agente, ya sea la versión implementada en Microsoft Foundry o una instancia en ejecución local. Aprenderás a elegir un agente, utilizar puntos de conexión directos, administrar sesiones, enviar archivos, fijar versiones e inspeccionar respuestas sin procesar.

Prerequisites

Invocar el agente desplegado

  • Envíe un prompt al agente desplegado:

    azd ai agent invoke "What is Microsoft Foundry?"

Invocación de un agente específico

  • Si el proyecto contiene varios agentes, especifique cuál se va a invocar:

    azd ai agent invoke my-agent "What is Microsoft Foundry?"

Invocar un punto de conexión desplegado específico

Cuando quiera invocar un agente implementado específico sin depender del entorno de azd activo o azure.yaml, use --agent-endpoint para apuntar directamente a la dirección URL del agente implementado. Este patrón es útil desde un script fuera del proyecto, desde un agente de codificación o al probar una versión específica del agente.

  • Introduzca el punto de conexión del agente implementado:

    azd ai agent invoke \
   --agent-endpoint https://my-project.services.ai.azure.com/api/projects/my-project/agents/release-summarizer/versions/3 \
   "Summarize today's release notes."

    --agent-endpoint anula el entorno de azd y la resolución de azure.yaml, por lo que no hace falta estar dentro de un directorio de proyecto de azd para usarlo.

Invocar localmente

  • Invoque un agente local:

    azd ai agent invoke --local "Hello!"

    El agente ya debe estar en ejecución con azd ai agent run en otro terminal.

Invocar en un puerto local personalizado

  • Si el agente se ejecuta en un puerto no predeterminado, pase --port:

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

Elección de un protocolo

El protocolo utilizado para la invocación viene determinado por el protocols campo del azure.ai.agent servicio en azure.yaml.

  • responses : envía una solicitud estándar de API de respuestas de OpenAI con {"input": "your message"}. El historial de conversaciones se administra automáticamente.
  • invocations -- envía cualquier carga útil que espere el código de su agente. Use --input-file (-f) con un archivo JSON que coincida con el esquema que define el controlador.

Para los agentes invocations, consulte el README del ejemplo o inspeccione el punto de entrada del controlador para comprender la carga útil esperada.

  • Si el agente implementa varios protocolos, pase --protocol (-p) para elegir:

    azd ai agent invoke --protocol invocations -f request.json

Administrar sesiones

Las sesiones se conservan por agente. Al invocar un agente, azd guarda el identificador de sesión localmente para que el siguiente invoke continúe automáticamente la misma sesión y mantenga el historial de conversaciones entre llamadas.

Iniciar una nueva sesión

  • Descarte la sesión guardada y comience de nuevo:

    azd ai agent invoke --new-session "Start fresh"

Uso de un identificador de sesión específico

  • Pase un identificador de sesión existente:

    azd ai agent invoke --session-id my-session-123 "Continue conversation"

Enviar un archivo como entrada

Para cargas estructuradas o grandes, especialmente con el invocations protocolo, pase un archivo JSON.

  1. Enviar un archivo:

    azd ai agent invoke -f request.json

  2. O bien, envíe un archivo a un agente específico:

    azd ai agent invoke my-agent -f request.json

Invocar una versión implementada

Cuando un agente tiene varias versiones desplegadas, fije una concreta con --version. azd crea o reutiliza una sesión respaldada por esa versión, por lo que cada versión mantiene su propio estado de conversación.

  • Fijar una versión:

    azd ai agent invoke --version 3 "Use the v3 prompt"

    --version no se puede combinar con --local o --session-id porque las sesiones están enlazadas a una versión cuando se crean.

Establecimiento de un tiempo de espera personalizado

  • Indique un tiempo de espera en segundos:

    azd ai agent invoke --timeout 300 "Process this large dataset"

    El tiempo de espera predeterminado es de 1800 segundos (30 minutos). Use --timeout 0 para que no haya tiempo de espera.

Transmitir claves de aislamiento

Los agentes configurados con el aislamiento basado en encabezados de Foundry requieren claves individuales por usuario o por chat en cada solicitud. Páselos con --user-isolation-key y --chat-isolation-key.

  • Pasar claves de aislamiento con la solicitud:

    azd ai agent invoke \
   --user-isolation-key "$USER_KEY" \
   --chat-isolation-key "$CHAT_KEY" \
   "Hello!"

Para obtener el patrón completo, incluida la forma en que las sesiones, los archivos y los comandos de supervisión usan las mismas marcas, consulte Paso de claves de aislamiento a un agente hospedado.

Inspeccione la respuesta HTTP sin procesar

Cuando necesite ver exactamente lo que devolvió el servidor, incluidos los encabezados de respuesta, como la versión del agente, la línea de estado y el cuerpo sin modificar, pase --output raw (-o raw).

  • Solicitud de salida en bruto:

    azd ai agent invoke --output raw "Hello!"

    En modo raw, se suprimen las líneas de resumen legibles, como Session: y Invocation:, y la respuesta HTTP se muestra literalmente. Este modo es útil para depurar el comportamiento del servidor y confirmar qué versión del agente controló la llamada.

Contenido relacionado

  • Last updated on