Desarrollo del agente con la CLI para desarrolladores de Azure

Importante

Los elementos marcados (versión preliminar) de este artículo se encuentran actualmente en versión preliminar pública. Esta versión preliminar se ofrece sin acuerdo de nivel de servicio y no se recomienda para las 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 hospedado listo para producción en Microsoft Foundry. 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 proyecto a partir de una plantilla o el código existente. Inicio rápido: Implementación de un agente hospedado
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 y pruebe localmente. Introducción a las 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 azd ai agent extensión se centra en los agentes hospedados.

Tipo Description Cuándo se deben usar
Agente alojado en servidor Una aplicación en contenedor que compila en código, empaqueta como una imagen de Docker e implementa en Foundry. 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.

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.

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 azure.ai.agent servicio define el agente hospedado en línea y usa uses: para hacer referencia a otros servicios, como el proyecto, las conexiones, los cuadros de herramientas, las aptitudes y las rutinas. No hay ningún archivo independiente agent.yaml o agent.manifest.yaml en el modelo de proyecto del agente hospedado actual azd.

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 azd proyecto, los comandos resuelven el punto de conexión del proyecto de Foundry a partir del entorno azd activo.
  • Fuera de un proyecto azd, establezca el contexto activo una vez con azd ai project set <endpoint>, o pase --project-endpoint en un comando de recurso individual (connection, toolbox, skill o routine). Como alternativa, azd ai lee la variable de entorno FOUNDRY_PROJECT_ENDPOINT.
  • Un entorno dentro del proyecto siempre tiene prioridad sobre el contexto global, por lo que al cambiar de directorio a un proyecto, la CLI se redirige al puntos de conexión de ese 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.

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 Secuencia de mensajes dentro de una sesión. Foundry administra el historial de conversaciones y puede hidratarlo entre solicitudes.

Las sesiones se identifican mediante .session_id Al ejecutar azd ai agent invoke, Foundry reutiliza la sesión de la última invocación de forma predeterminada. Use --new-session para iniciar una sesión nueva o --session-id <id> para dirigirse a una sesión específica.

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. Cada grupo de comandos expone los verbos estándar create, update, delete, show, y list .

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 ejecuta tu agente con un conjunto de datos, puntúa las respuestas con uno o más evaluadores y genera un informe con una señal de calidad agregada. Se administra con azd ai agent eval.
  • 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.

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.

# 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

Contenido relacionado

  • Last updated on