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 de un proyecto una sola vez y, a continuación, se combinan comandos a medida que el proyecto crece.

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

Tres archivos definen cómo se compila e implementa un agente.

La distinción clave es que agent.yaml describe lo que es tu agente, mientras que azure.yaml describe cómo se implementa.

Los recursos que residen en el propio proyecto Foundry, como conexiones, cuadros de herramientas, aptitudes y rutinas, se administran mediante comandos directos azd ai en lugar de declararse en agent.yaml.

Sustitución de variables

Verá dos sintaxis de variables en los archivos de proyecto del agente:

• ${VAR_NAME} es un azd marcador de posición de variable de entorno. Se resuelve desde .azure/<env>/.env en el momento del despliegue, por lo que el mismo agent.yaml funciona en entornos como desarrollo, preproducción y producción.
• {{ parameter }} es un parámetro de plantilla de manifiesto. Se resuelve cuando se genera un proyecto concreto a partir de una plantilla azd ai agent init.

Dónde se ejecuta la CLI

Los azd ai comandos funcionan tanto dentro como fuera de un azd directorio de proyecto:

• Dentro de un proyecto azd, los comandos determinan el extremo 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 al directorio de un proyecto, la CLI pasa a apuntar al extremo de ese proyecto.

Protocols

Un protocolo define el contrato HTTP entre Foundry y el contenedor del agente. El agente escucha en el puerto 8088 y atiende un sondeo de estado, independientemente del protocolo.

Para obtener la especificación completa, consulte Contrato en 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 varios evaluadores y proporciona un indicador agregado de calidad. Se administra con azd ai agent eval.
• La optimización reescribe iterativamente la instrucción de tu agente para mejorar el resultado de una evaluación. Usa una evaluación como función objetiva y genera un mensaje de candidato que revise y acepte. 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 la estructura inicial una vez y, después, usa los comandos directos a medida que tu proyecto crezca.

# 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