Nota:
El acceso a esta página requiere autorización. Puede intentar iniciar sesión o cambiar directorios.
El acceso a esta página requiere autorización. Puede intentar cambiar los directorios.
Importante
Los elementos marcados como versión preliminar en este artículo se encuentran actualmente en versión preliminar. Esta versión preliminar se proporciona sin un contrato de nivel de servicio y Microsoft no lo recomienda para cargas de trabajo de producción. Es posible que algunas características no se admitan o que tengan funcionalidades restringidas. Para más información, consulte Términos de uso complementarios para las versiones preliminares de Microsoft Azure.
La CLI de Azure Developer (azd) y su azd ai agent extensión proporcionan un único flujo de trabajo de línea de comandos para pasar de idea a un agente listo para producción en Microsoft Foundry. Puede desarrollar agentes hospedados basados en código y agentes de voz declarativos basados en mensajes. En este artículo se explica el recorrido del desarrollador, los archivos que definen un agente y los conceptos básicos que se encuentran a lo largo del proceso.
Este artículo es para desarrolladores que prefieren un flujo de trabajo centrado en el terminal y automatizable mediante scripts, en lugar del portal de Foundry o de los SDK para distintos lenguajes.
El recorrido del desarrollador
El flujo de trabajo azd ai sigue el mismo ciclo de vida tanto si se crea un pequeño prototipo como si se desarrolla un agente para producción. Se crea la estructura básica de un proyecto una vez y, a medida que este crece, se combinan los comandos según sea necesario.
| Stage | Qué haces | Dónde obtener más información |
|---|---|---|
| Install | Instale azd y las extensiones de Foundry. |
Configuración del entorno de desarrollador |
| Scaffolding para | Inicialice un agente hospedado desde una plantilla o el código existente, o cree un agente de voz basado en mensajes. | Inicio rápido: Implementar un agente alojado o Inicio rápido: Crear un agente de voz con prompt |
| Definir | Configure el agente, las dependencias de implementación del modelo, los protocolos, las herramientas y el entorno en azure.yaml. |
Crea el archivo azure.yaml para los agentes hospedados |
| Develop | Escriba lógica del agente, agregue herramientas mediante un cuadro de herramientas y pruebe localmente. | Introducción al cuadro de herramientas |
| Desplegar | Aprovisione la infraestructura e implemente en Foundry. | Implementación de un agente hospedado |
| Operar | Supervise los registros, administre versiones y automatice las ejecuciones. | Administración de agentes hospedados |
| Evaluate | Mide la calidad del agente y mejora el mensaje de solicitud. | Ejecuta evaluaciones de agentes con la CLI de azd |
Tipos de agente
La extensión azd ai agent admite agentes hospedados, de indicaciones y de voz.
| Tipo | Description | Cuándo se deben usar |
|---|---|---|
| Agente alojado en servidor | Una aplicación que se implementa como código fuente o una imagen de contenedor. | Necesita lógica personalizada, integración de marcos o control total sobre el comportamiento. |
| Agente de indicaciones | Un agente definido completamente a través de instrucciones y configuraciones de herramientas, sin código personalizado. | Quiere un agente rápido controlado por configuración sin escribir código de aplicación. |
| Agente de voz | Un agente de voz de indicaciones declarativo o un contenedor de voz que se conecta a un agente hospedado. | Necesita una experiencia de voz en tiempo real a través de un cliente de Voice Live. |
Los agentes hospedados le proporcionan control total sobre las integraciones de tiempo de ejecución, marco y herramientas, mientras que Foundry controla la infraestructura, el escalado y la administración de sesiones.
Los agentes de voz basados en mensajes no requieren un contenedor personalizado. Si necesita ejecutar una canalización de audio en cascada o de voz a voz personalizada en su propio contenedor, cree un agente de voz con un agente hospedado y use el invocations_ws protocolo .
Para mantener la lógica de conversación en un agente de texto hospedado mientras Voice Live se encarga del audio, utilice el flujo de trabajo del envoltorio de voz hospedado. El envoltorio y el destino son servicios independientes dentro del mismo azure.yaml proyecto. Este flujo no reemplaza el flujo de canalización de audio personalizado invocations_ws existente.
Antes de usar las opciones de la CLI de voz de versión preliminar pública, compruebe la extensión instalada como se describe en los requisitos previos de inicio rápido del agente de voz.
Archivos de configuración
Un proyecto de agente hospedado usa un azure.yaml archivo en la raíz del proyecto para declarar tanto el agente como su modelo de aprovisionamiento e implementación. El archivo usa un modelo de servicio dividido, donde cada servicio con nombre tiene un host valor como azure.ai.project, azure.ai.agent, azure.ai.connection, azure.ai.toolbox, o azure.ai.skillazure.ai.routine.
| File | propósito | Quién lo mantiene |
|---|---|---|
azure.yaml |
Declara el proyecto Foundry, las implementaciones de modelos, el servicio del agente hospedado, las dependencias, los protocolos, las herramientas, las variables de entorno, los recursos de contenedor y la configuración de implementación. Los valores de identidad, modelo, protocolos, herramientas y entorno del agente residen en el azure.ai.agent servicio. |
La inicialización lo genera. Se personaliza según sea necesario. |
El servicio azure.ai.agent define el agente de forma insertada o mediante un $ref raíz explícito a una definición YAML o JSON directa. Se usa azd ai agent add <service> --file <path> para un servicio respaldado por archivos. Los envoltorios parametrizados AgentManifest no son compatibles con la inicialización actual. La lista uses: del servicio hace referencia a dependencias como el proyecto, las conexiones y los Toolbox.
Para un agente de voz basado en mensajes, azure.yaml almacena la definición del agente declarativo, incluido kind: prompt-voice, el modelo, el tipo de modelo y el nombre del agente. No incluye un entorno de ejecución de contenedor del agente hospedado. Para personalizar instrucciones, audio, detección de turnos, transcripción, salida de voz, herramientas y saludos, consulte Configuración de un agente de voz.
Para un envoltorio de voz alojado, conversationEngine.name hace referencia al nombre del servicio del destino alojado. Las órdenes de dependencia del envoltorio uses determinan el despliegue, y conversationEngine.version usa por defecto la versión desplegada por el entorno actual. Consulte la referencia del servicio de voz para los campos de configuración.
Sustitución de variables
Utilice ${VAR_NAME} en azure.yaml para los valores que difieren según el entorno azd. El marcador de posición se resuelve a partir de .azure/<env>/.env en el momento de la implementación o en tiempo de ejecución, por lo que el mismo azure.yaml funciona en entornos como desarrollo, staging y producción.
Dónde se ejecuta la CLI
Los azd ai comandos funcionan tanto dentro como fuera de un azd directorio de proyecto:
- Dentro de un
azdproyecto, los comandos resuelven el punto de conexión del proyecto de Foundry a partir del entornoazdactivo. - Fuera de un proyecto
azd, establezca el contexto activo una vez conazd ai project set <endpoint>, o pase--project-endpointen un comando de recurso individual (connection,toolbox,skilloroutine). Como alternativa,azd ailee la variable de entornoFOUNDRY_PROJECT_ENDPOINT. - Un punto de conexión no vacío resuelto desde el entorno activo tiene prioridad sobre el contexto global. Para conocer la reserva del shell y el comportamiento específico de cada comando, consulte Establecimiento del contexto del proyecto.
Protocols
Un protocolo define el contrato HTTP entre Foundry y el contenedor del agente. Tu agente escucha en el puerto 8088 y ofrece un sondeo de estado, independientemente del protocolo.
| Protocol | Estilo de API | Cuándo se deben usar |
|---|---|---|
responses |
API de respuestas de OpenAI (POST /responses) |
La opción estándar, compatible con el ecosistema de api de OpenAI. |
invocations |
Contrato JSON personalizado (POST /invocations) |
Cuando necesite un control total sobre las cargas de solicitud y respuesta. |
Para consultar la especificación completa, véase Contrato de tiempo de ejecución del agente hospedado.
Esta configuración de protocolo se aplica a los contenedores del agente hospedado. Los agentes de voz basados en instrucciones no configuran un protocolo de agente alojado.
azd ai agent invoke no implementa conversaciones de voz para agentes de voz basados en mensajes ni contenedores de voz hospedados. Para obtener instrucciones sobre el comportamiento y las pruebas de la CLI, consulte Limitaciones del agente de voz.
Sesiones y conversaciones
| Concepto | Description |
|---|---|
| Session | Un entorno de ejecución aislado para una sola interacción del agente. Cada sesión se ejecuta en su propio espacio aislado con recursos dedicados. |
| Conversación | Historial de mensajes para el protocolo de Responses. Las invocaciones no conservan automáticamente el historial de conversaciones. |
Las sesiones se identifican mediante .session_id La CLI guarda la selección de sesión por agente y la reutiliza de forma predeterminada. Use --new-session para iniciar una sesión nueva o --session-id <id> para dirigirse a una sesión específica. La memoria caché no se indexa por usuario delegado; mantenga una asignación explícita de usuarios a sesiones al usar --user-identity.
Recursos de un proyecto Foundry
Un proyecto de Foundry alberga más que solo agentes. También contiene recursos compartidos a los que hacen referencia los agentes en tiempo de ejecución. La CLI administra cada una a través de un grupo de comandos dedicado.
| Resource | ¿Qué es? | Gestionado con |
|---|---|---|
| Connection | Vincula un proyecto foundry a un recurso externo, como un servidor MCP, Búsqueda de Azure AI o Grounding con Bing. | comandos de azd ai connection |
| Caja de herramientas | Colección con nombre de herramientas que los agentes usan en tiempo de ejecución. | comandos de azd ai toolbox |
| Habilidad | Una guía de comportamiento reutilizable compartida entre agentes en el proyecto. | comandos de azd ai skill |
| Rutina | Desencadenador más una acción que invoca a un agente. | comandos de azd ai routine |
Estos recursos se comparten entre desarrolladores y agentes en el mismo proyecto. Sus comandos son distintos: las conexiones y las rutinas tienen update, las aptitudes publican una nueva versión mediante update y los Toolbox usan mutaciones de conexión y de aptitud que generan versiones seguidas de publish.
Evaluación y mejora de un agente
Una vez que se ejecuta un agente, dos flujos de trabajo relacionados le ayudan a medir y mejorar su calidad:
- La evaluación rápida del agente usa
azd ai agent evaly un localeval.yaml, incluyendo el flujo de trabajo del optimizador. La evaluación de proyectos usa la extensiónazd ai evalinstalada por separado yevals/azure.eval.yaml, con orígenes de seguimiento o de conjuntos de datos y puertas de calidad de CI explícitas. Los dos formatos de configuración no son intercambiables. - La optimización reescribe de forma iterativa la indicación de tu agente para mejorar una señal de evaluación. Utiliza una evaluación como función objetivo y genera una indicación candidata que tú revisas y aceptas. Se administra con
azd ai agent optimize.
Para obtener más información, consulte Ejecutar evaluaciones de agentes con la CLI de azd y Optimizar las instrucciones de los agentes.
Grupos de comandos por tarea de desarrollo
Elija un comando para el resultado que necesita. Anexe --help para inspeccionar sus marcas y los formatos de salida admitidos.
| Job | Commands | Guía |
|---|---|---|
| Configuración de un proyecto y de modelos administrados |
azd ai project add, azd ai project deployment add |
Configuración y contexto del proyecto |
| Selección o inspección del contexto del punto de conexión |
azd ai project set, azd ai project show, , azd ai project unset, azd ai project context |
La selección global de puntos de conexión es independiente de las declaraciones de infraestructura. La salida de contexto puede contener secretos. |
| Ver ejemplos o inicializar un agente |
azd ai agent sample list, , azd ai agent init, azd ai agent add |
Inicialización de agentes hospedados, de indicaciones y de voz |
| Análisis, extracción y clasificación de documentos y contenido para los agentes |
azd ai cu analyze, azd ai cu analyzer |
Inicio rápido de la CLI de Azure Content Understanding (versión preliminar) |
| Ejecutar e inspeccionar localmente |
azd ai agent run, azd ai inspector launch |
Desarrollo local |
| Invocar, delegar la identidad del usuario o enviar cabeceras personalizadas | azd ai agent invoke |
Opciones de invocación |
| Inspección, seguimiento o cancelación del trabajo |
azd ai agent invocations show, , azd ai agent invocations follow, azd ai agent invocations cancel |
Invocación de larga duración |
| Inspeccionar o actualizar un punto de conexión |
azd ai agent endpoint show, azd ai agent endpoint update |
Actualizaciones de endpoint y tarjetas |
| Inspeccione el estado, diagnostique problemas o lea los registros |
azd ai agent show, , azd ai agent doctor, azd ai agent monitor |
Diagnóstico y registros |
| Crear, enumerar, inspeccionar, detener o eliminar un sandbox |
azd ai agent sessions create, azd ai agent sessions list, azd ai agent sessions show, azd ai agent sessions stop, azd ai agent sessions delete |
Administración de sesiones |
| Propagación, recuperación o mantenimiento de archivos de espacio aislado |
azd ai agent files upload, azd ai agent files download, azd ai agent files list, azd ai agent files mkdir, azd ai agent files stat, azd ai agent files delete |
Operaciones con archivos de sesión |
| Recuperar código fuente desplegado | azd ai agent code download |
Descargar código o un archivo ZIP |
| Inspección de almacenes duraderos y mantenimiento de elementos compartidos |
azd ai agent state-stores list, azd ai agent state-stores select, , azd ai agent state-stores show, azd ai agent state-stores items |
Operaciones y límites del almacén de estados |
| Adición de dependencias del agente a la configuración de implementación |
azd ai agent connection add, azd ai agent toolbox add |
Ambos servicios ya deben existir en azure.yaml; estos comandos agregan uses entradas, no recursos remotos. |
| Administración de las credenciales y los metadatos de conexión |
azd ai connection create, azd ai connection list, azd ai connection show, azd ai connection update, azd ai connection delete |
Autenticación y mantenimiento de conexiones |
| Creación, control de versiones o descarga de aptitudes reutilizables |
azd ai skill add, azd ai skill create, azd ai skill update, azd ai skill list, azd ai skill show, azd ai skill download, azd ai skill delete |
Flujos de trabajo de aptitudes |
| Creación y administración de Toolbox |
azd ai toolbox add, azd ai toolbox create, azd ai toolbox list, azd ai toolbox show, azd ai toolbox delete |
Configuración de la caja de herramientas |
| Desarrolla y promociona colecciones de herramientas |
azd ai toolbox connection, azd ai toolbox skill, , azd ai toolbox versions list, azd ai toolbox publish |
Las mutaciones se bifurcan a partir de la versión más reciente; la promoción es explícita. |
| Programación, envío o inspección de rutinas |
azd ai routine add, azd ai routine create, azd ai routine list, azd ai routine show, azd ai routine update, azd ai routine enable, azd ai routine disable, azd ai routine dispatch, azd ai routine run list, azd ai routine delete |
Flujos de trabajo rutinarios |
| Genera y ejecuta una evaluación rápida |
azd ai agent eval generate, azd ai agent eval update, azd ai agent eval run, azd ai agent eval list, azd ai agent eval show |
Recursos rápidos de evaluación y optimización |
| Mejora e implementa un candidato de optimización |
azd ai agent optimize, azd ai agent optimize status, azd ai agent optimize list, azd ai agent optimize cancel, azd ai agent optimize apply, azd ai agent optimize deploy |
Flujo de trabajo de optimización |
| Empaquetar o publicar un agente Activity para Teams |
azd ai agent pack, azd ai agent publish |
Distribución de Teams |
| Eliminar una versión hospedada o un agente | azd ai agent delete |
Eliminación del agente |
| Evaluación de un proyecto y aplicación de puertas de calidad |
azd ai eval init, azd ai eval generate, azd ai eval create, azd ai eval run, azd ai eval dataset, azd ai eval evaluator, azd ai eval job |
Evaluación del proyecto; instale azure.ai.evaluations por separado. |
| Registrar y versionar conjuntos de datos reutilizables | azd ai dataset |
Ciclo de vida del conjunto de datos; instale azure.ai.dataset por separado. |
| Enviar, pausar, reanudar, cancelar o implementar trabajos de ajuste fino |
azd ai finetuning init, azd ai finetuning jobs |
Ajuste preciso; instale azure.ai.finetune por separado. |
| Cargar y gestionar pesos de modelo personalizados | azd ai models |
Importación y mantenimiento de modelos personalizados; instale azure.ai.models por separado. |
Cada extensión que agrega comandos expone version; inspeccione la agrupación microsoft.foundry con azd ext list en su lugar. Los grupos de conexiones, rutinas y aptitudes también exponen context para la inspección local del proyecto y del entorno; trate la salida como potencialmente confidencial.
Distribución de agentes de Activity
Después de implementar un agente de protocolo Activity, azd ai agent pack crea appPackage.zip para la instalación de prueba. Usa --output-dir, --display-name y --app-version para personalizar el paquete. Empaquetar no es lo mismo que publicar.
azd ai agent publishpublica a través de Microsoft 365. Los agentes de actividad simple usan la distribución shared de forma predeterminada, a menos que se configure lo contrario; --scope tenant requiere la aprobación del administrador. Digital Workers requiere ámbito de inquilino. Use valores --access-boundary repetibles, --clear-access-boundaries para quitar los límites existentes y valores --optional-permission-scope <resource-app-id>=<scope> repetibles para los permisos opcionales.
personal no es un ámbito de publicación; use pack --scope personal e instale de prueba el paquete para realizar pruebas por usuario.
Ciclo de vida de la implementación
El bucle de desarrollador completo se condensa en una breve secuencia de comandos. Crea una estructura inicial y, a medida que tu proyecto crezca, utiliza los comandos directos.
Para la opción de agente de voz administrado, consulte Inicio rápido: Crear un agente de voz con indicaciones.
# Scaffold a project from a template or your existing code
azd ai agent init
# Run locally and invoke
azd ai agent run
azd ai agent invoke --local "Hello, world!"
# Provision infrastructure and deploy the agent
azd up
# Extend the project with shared resources at any time
azd ai connection create my-search --kind cognitive-search --target https://... --auth-type api-key --key "..."
azd ai routine create daily-digest --trigger recurring --cron "0 7 * * *" --agent-name my-agent
# Evaluate quality
azd ai agent eval generate
azd ai agent eval run
# Tear down all Azure resources
azd down