Desarrollo del agente con la CLI para desarrolladores de 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.

Tipos de agente

La azd ai agent extensión se centra en los agentes hospedados.

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.

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.

Para consultar la especificación completa, véase Contrato de tiempo de ejecución del agente hospedado.

Sesiones y conversaciones

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.

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

• Inicio rápido: Implementación del primer agente hospedado
• ¿Qué son los agentes alojados?
• Contrato del entorno de ejecución del agente alojado
• Ciclo de vida de desarrollo del agente