microsoft-foundry

Descripción general

¿Qué es el skill microsoft-foundry?

El skill microsoft-foundry es un conjunto curado de flujos de trabajo y documentos de referencia que te guía a través del ciclo de vida completo de los agentes de Azure AI Foundry. Está centrado en la puesta en producción y operación prácticas:

• Creación de agentes prompt y hosted
• Creación de imágenes Docker y envío a Azure Container Registry (ACR)
• Implementación de agentes en Azure AI Foundry
• Configuración de projects, RBAC, quota y connections
• Ejecución de evaluation datasets y gestión de agent-metadata.yaml
• Configuración de agentes en entornos standard y de private-network
• Habilitación de observability, tracing y troubleshooting

Todo el contenido proviene del repositorio microsoft/azure-skills y está estructurado para que puedas operar agentes en Azure AI Foundry sin tener que hacer ingeniería inversa del diseño del repositorio.

¿Para quién es este skill?

Utiliza microsoft-foundry si eres:

• Un ingeniero de backend o de plataforma responsable de implementar y operar agentes de Azure AI Foundry
• Un ingeniero de IA/ML que está moviendo prototipos a un proyecto Foundry en producción
• Un desarrollador que integra agentes de Foundry con servicios existentes, SDKs o herramientas MCP
• Un responsable técnico que debe tomar decisiones sobre RBAC, cuota, redes privadas y configuración de entornos

Si solo necesitas una implementación básica de infraestructura de Azure (App Service, Functions, aplicaciones web genéricas), este skill no es el adecuado; utiliza en su lugar un skill de implementación de Azure más general.

¿Qué problemas resuelve microsoft-foundry?

Este skill está diseñado para resolver estos retos recurrentes:

• "How do I structure my agent repo for Foundry?"
  Usa las indicaciones de references/agent-metadata-contract.md para el diseño de .foundry/ y los campos de agent-metadata.yaml.

• "How do I create and deploy agents consistently?"
  Usa los flujos de trabajo foundry-agent/create y foundry-agent/deploy para crear agentes prompt/hosted, construir contenedores, enviarlos a ACR e iniciar los contenedores de los agentes.

• "How do I configure projects, connections, RBAC, and quota?"
  Sigue project/create, rbac/rbac.md y quota/quota.md para crear proyectos, asignar roles y planear la capacidad.

• "How do I evaluate and observe my agents?"
  Usa foundry-agent/eval-datasets, foundry-agent/observe y foundry-agent/trace para ejecutar evaluaciones por lotes, gestionar datasets y evaluadores, y conectar con recursos de observabilidad.

• "How do I handle standard vs private-network setups?"
  Usa references/standard-agent-setup.md y references/private-network-standard-agent-setup.md para elegir y configurar el modelo de red adecuado.

¿Cuándo encaja bien microsoft-foundry?

Utiliza este skill cuando necesites:

• Implementar agentes prompt o hosted en Azure AI Foundry
• Estandarizar la estructura de proyectos de agentes con .foundry/agent-metadata.yaml
• Integrar herramientas MCP y SDKs de Azure en un flujo de trabajo repetible
• Gestionar RBAC, cuota y planificación de capacidad para cargas de trabajo de agentes
• Ejecutar evaluation datasets y seguir resultados entre entornos
• Configurar la observability usando Application Insights y trazas
• Implementar en configuraciones standard o de private-network (VNet)

No utilices este skill cuando solo necesites:

• Implementación genérica de aplicaciones en Azure (aplicaciones web, Functions, App Service)
• Preparación de alto nivel de cuentas o suscripciones de Azure

En esos casos, combina este skill con otros skills más generales de preparación/implementación en Azure o utiliza un skill dedicado como azure-deploy / azure-prepare.

Cómo usarlo

Instalación

Para añadir microsoft-foundry desde el repositorio microsoft/azure-skills, instálalo con:

npx skills add https://github.com/microsoft/azure-skills --skill microsoft-foundry

Esto pone a disposición los flujos de trabajo y contenido de referencia de microsoft-foundry en tu agente o entorno de herramientas. Tras la instalación, el punto de entrada principal es SKILL.md en la carpeta skills/microsoft-foundry.

Estructura del repositorio y carpetas clave

Después de instalar el skill o abrirlo en el repositorio, verás la siguiente estructura:

• SKILL.md – índice principal del skill y lista de sub-skills
• foundry-agent/ – flujos de trabajo de extremo a extremo para agentes individuales
  • create/ – creación de agentes prompt o hosted
  • deploy/ – compilación e implementación de agentes, incluidos contenedores y ACR
  • eval-datasets/ – gestión de eval datasets y ejecuciones de evaluación
  • invoke/ – invocación de agentes existentes
  • observe/ – configuración de observability y flujos de supervisión
  • trace/ – recopilación de trazas y creación de datasets a partir de ellas
  • troubleshoot/ – guías de troubleshooting para ejecuciones fallidas
• project/
  • create/ – creación y configuración de proyectos de Azure AI Foundry
  • connections.md – guía para connections a nivel de proyecto
• rbac/
  • rbac.md – roles RBAC, permisos y patrones habituales
• quota/
  • quota.md – guía de cuota y planificación de capacidad
  • references/ – planificación de capacidad, resolución de errores, optimización
• references/
  • agent-metadata-contract.md – diseño de .foundry/ y agent-metadata.yaml
  • auth-best-practices.md – patrones de autenticación de Azure y RBAC
  • standard-agent-setup.md – configuración estándar (no aislada) de agentes
  • private-network-standard-agent-setup.md – configuración con VNet/private-link
  • sdk/ – referencias de operaciones vía SDK para cuando MCP tools no estén disponibles

Empieza con SKILL.md para entender los sub-skills y luego profundiza en la carpeta del escenario específico.

Flujo de inicio rápido: de proyecto a agente implementado

Esta sección describe un recorrido práctico usando el contenido del skill microsoft-foundry.

1. Crea o prepara tu proyecto Foundry

1. Abre project/create/create-foundry-project.md.
2. Sigue los pasos para:
   • Crear un Azure AI Foundry project
   • Confirmar el project endpoint (por ejemplo, https://<resource>.services.ai.azure.com/api/projects/<project>)
   • Vincular las connections necesarias (Cosmos DB, Storage, Azure AI Search, etc.) según lo requerido para la configuración estándar
3. Revisa project/connections.md para asegurarte de que tus conexiones de almacenamiento de hilos, archivos y vector store estén correctamente configuradas, especialmente si piensas usar standard agent setup.

2. Configura RBAC y autenticación

1. Lee rbac/rbac.md para verificar:
   • Qué roles se necesitan (Owner, Contributor, User Access Administrator, etc.) en el grupo de recursos y recursos de Foundry
   • Cómo asignar roles siguiendo las prácticas recomendadas de Azure RBAC
2. Abre references/auth-best-practices.md y aplica sus recomendaciones:
   • Usa managed identities y Azure RBAC en producción
   • Restringe DefaultAzureCredential al desarrollo local
   • Elige el tipo de credencial adecuado para producción, CI/CD y entornos de desarrollo

Esto garantiza que tus implementaciones y operaciones de agentes puedan autenticarse de forma confiable sin secretos codificados.

3. Decide entre configuración basic, standard o private-network

1. Abre references/standard-agent-setup.md para entender:
   • Diferencias entre configuraciones Basic y Standard
   • Connections requeridas para la configuración estándar: Cosmos DB, Azure Storage, Azure AI Search y, opcionalmente, Azure AI Services
   • Requisitos previos como roles RBAC en el grupo de recursos
2. Si necesitas aislamiento de red completo, lee references/private-network-standard-agent-setup.md:
   • Requisitos de VNet y subredes (subred del agente y subred de private endpoint)
   • Alineación de región entre los recursos de Foundry y la VNet
   • Uso de la Bicep template oficial para la configuración standard de agentes en red privada

Elige la configuración que se ajuste a tus requisitos de cumplimiento y red antes de pasar a la creación del agente.

4. Estandariza la estructura de tu proyecto de agente

1. Abre references/agent-metadata-contract.md y alinea tu proyecto con la estructura documentada:

   <agent-root>/
     .foundry/
       agent-metadata.yaml
       datasets/
       evaluators/
       results/
   

2. Asegúrate de que agent-metadata.yaml incluya definiciones de entorno con campos como:

   • defaultEnvironment
   • environments.<name>.projectEndpoint
   • environments.<name>.agentName
   • environments.<name>.azureContainerRegistry (para hosted agents)
   • environments.<name>.observability.* (para Application Insights)
   • environments.<name>.testCases[] para paquetes de evaluación

Este archivo se convierte en la fuente de verdad para la configuración específica por entorno, y el resto de los flujos de trabajo de microsoft-foundry parte de que exista y sea correcto.

5. Crea un agente prompt o hosted

1. Para prompt agents, abre foundry-agent/create/create-prompt.md:

   • Entiende la diferencia entre prompt agents y workflows
   • Sigue los pasos para resolver el contexto del proyecto (endpoint, credenciales)
   • Usa MCP tools cuando estén disponibles y recurre al SDK azure-ai-projects según lo documentado
   • Proporciona nombre del agente, deployment del modelo e instrucciones, además de herramientas opcionales (file search, code interpreter, etc.)

2. Para hosted agents, abre foundry-agent/create/create.md:

   • Elige si vas a crear un agente nuevo (greenfield) o convertir un proyecto existente (brownfield)
   • Selecciona framework e idioma según las rutas de ejemplo proporcionadas (frameworks de Python o C#, como Microsoft Agent Framework o LangGraph)
   • Usa la guía para integrarte con el repositorio foundry-samples cuando sea necesario

Al final de este paso deberías tener un proyecto de agente compatible con Foundry listo para su implementación.

6. Compila e implementa el agente

1. Abre foundry-agent/deploy/deploy.md.
2. Sigue el flujo de trabajo que cubre:
   • Análisis del proyecto y recopilación de variables de entorno
   • Generación del Dockerfile y uso de docker / az acr para hosted agents
   • Uso de MCP tools como agent_update, agent_container_control y agent_container_status_get
   • Creación o actualización del deployment e inicio/parada de los contenedores del agente
3. No ejecutes azd up, azd deploy, az acr build o docker build de forma aislada sin revisar esta guía: el skill coordina estos comandos como parte de una canalización de implementación completa.

Una vez completado este paso, tu agente debería estar implementado y accesible a través de Azure AI Foundry.

7. Invoca y prueba el agente

1. Abre foundry-agent/invoke/invoke.md.
2. Usa los patrones documentados para:
   • Resolver el entorno y endpoint correctos a partir de agent-metadata.yaml
   • Invocar el agente con cargas de ejemplo o personalizadas
   • Verificar que las respuestas, herramientas y estado se comportan como esperas

Este es un buen momento para hacer smoke tests antes de ejecutar baterías completas de evaluación.

8. Evalúa e itera

1. Abre foundry-agent/eval-datasets/eval-datasets.md.
2. Utiliza la guía para:
   • Gestionar datasets y evaluadores en .foundry/datasets y .foundry/evaluators
   • Ejecutar flujos de evaluación usando las definiciones testCases de agent-metadata.yaml
   • Guardar resultados en .foundry/results y comparar resultados por entorno o versión de agente
3. Itera sobre tus prompts o instrucciones y vuelve a ejecutar las evaluaciones para seguir las mejoras en el tiempo.

Observability, tracing y troubleshooting

Observability y monitorización

1. Abre foundry-agent/observe/observe.md.
2. Configura la observability según la guía:
   • Vincula Application Insights usando los campos de resource ID y connection string descritos en agent-metadata-contract.md
   • Utiliza los dashboards o consultas recomendados para supervisar latencia, errores y throughput

Esto te permite supervisar el comportamiento en producción y correlacionarlo con cambios de implementación.

Tracing y creación de datasets a partir de trazas

1. Abre foundry-agent/trace/trace.md.
2. Utiliza los flujos de trabajo documentados para:
   • Recopilar trazas de tus agentes
   • Seleccionar y crear datasets a partir de las trazas y guardarlos en .foundry/datasets
   • Integrar esos datasets en los flujos de evaluación para pruebas más realistas

Esto es especialmente útil cuando quieres convertir tráfico real de usuarios en escenarios de evaluación.

Troubleshooting de implementaciones y problemas en tiempo de ejecución

1. Abre foundry-agent/troubleshoot/troubleshoot.md.
2. Sigue las guías de troubleshooting para problemas como:
   • Fallos de implementación y errores al iniciar contenedores
   • Endpoints, credenciales o connections mal configurados
   • Errores de cuota o capacidad (consulta también quota/quota.md y quota/references/*.md)

Utiliza esto junto con logs y telemetría de Application Insights para diagnosticar y resolver problemas.

Cuota, capacidad y optimización

1. Abre quota/quota.md para una vista general de:
   • Cómo se aplica la cuota a modelos y deployments en Azure AI Foundry
   • Cómo razonar sobre la capacidad entre entornos y regiones
2. Revisa los archivos en quota/references/:
   • capacity-planning.md – te ayuda a estimar la capacidad para agentes según el uso
   • error-resolution.md – mapea errores habituales relacionados con cuota a correcciones recomendadas
   • optimization.md – sugiere formas de ajustar cargas de trabajo para mantenerse dentro de los límites de cuota

Este contenido te ayuda a evitar sorpresas al escalar y a mantener los agentes con buena capacidad de respuesta.

Preguntas frecuentes (FAQ)

¿Es obligatorio usar microsoft-foundry para trabajar con Azure AI Foundry?

No. Puedes usar Azure AI Foundry directamente desde el portal de Azure, la CLI o los SDKs. El skill microsoft-foundry es una guía estructurada que agrupa prácticas recomendadas, flujos de trabajo y referencias en un solo lugar, para que puedas configurar projects, agentes y entornos de forma más consistente.

¿Puedo usar microsoft-foundry para servicios de Azure que no sean Foundry?

Utiliza este skill cuando tu objetivo principal sea implementar y operar agentes y proyectos de Azure AI Foundry. Para la implementación general de aplicaciones web, APIs u otros servicios PaaS (App Service, Functions, contenedores genéricos), usa en su lugar un skill o guía de implementación de Azure específica.

¿microsoft-foundry admite tanto agentes prompt como hosted?

Sí. El skill tiene contenido dedicado para ambos casos:

• foundry-agent/create/create-prompt.md cubre prompt agents.
• foundry-agent/create/create.md y foundry-agent/deploy/deploy.md cubren hosted agents, incluyendo contenedorización, ACR y gestión del ciclo de vida del contenedor.

¿Cómo gestiona microsoft-foundry la autenticación y la seguridad?

La seguridad y la autenticación se tratan en references/auth-best-practices.md y rbac/rbac.md:

• Usa managed identities y Azure RBAC en producción
• Reserva DefaultAzureCredential para desarrollo local
• Elige credenciales adecuadas para CI/CD y entornos on-prem

Sigue esos documentos antes de integrar SDKs o MCP tools para evitar configuraciones inseguras o frágiles.

¿Tengo que usar MCP tools o puedo basarme solo en SDKs?

El contenido está escrito para funcionar con MCP tools cuando estén disponibles, pero también documenta alternativas basadas en SDK en la carpeta references/sdk. Por ejemplo, create-prompt.md explica cómo usar por defecto el SDK azure-ai-projects cuando MCP tools no están presentes.

¿Cómo sé si la estructura de mi proyecto de agente es correcta?

Compara tu proyecto con references/agent-metadata-contract.md. Asegúrate de tener:

• Un directorio .foundry/ en la raíz del agente
• Un agent-metadata.yaml válido que incluya entornos y casos de prueba
• Carpetas datasets/, evaluators/ y results/ tal como se describe

Si sigues ese contrato, el resto de los flujos de trabajo de microsoft-foundry se alinearán con la estructura de tu proyecto.

¿Puedo usar microsoft-foundry con configuraciones de red privada (VNet)?

Sí. references/private-network-standard-agent-setup.md ofrece una guía detallada sobre:

• Configuración necesaria de VNet y subredes
• Restricciones regionales entre los recursos de Foundry y la VNet
• Uso de la Bicep template oficial para la configuración standard de agentes en red privada

Utiliza ese documento junto con references/standard-agent-setup.md cuando necesites mantener el tráfico en una red privada.

¿Por dónde debo empezar en el repositorio después de la instalación?

Tras instalar el skill, empieza por:

1. SKILL.md – para una vista general de todos los sub-skills
2. project/create/create-foundry-project.md – para configurar tu proyecto Foundry
3. references/agent-metadata-contract.md – para estandarizar el diseño de tus agentes
4. foundry-agent/create/ y foundry-agent/deploy/ – para compilar e implementar tu primer agente

Luego puedes continuar con eval-datasets, observe, trace, rbac y quota según lo requiera tu escenario.