Skip to content

iesussan/foundry-playground

BranchesTags

Repository files navigation

🚀 Foundry Playground - Azure AI Foundry Framework

📋 Descripción General

Foundry Playground es un framework acelerador para la construcción de agentes inteligentes basados en Azure AI Foundry. Este marco de trabajo permite transformar contratos OpenAPI existentes en agentes conversacionales completamente funcionales con sus respectivos backends (BFF - Backend for Frontend), reduciendo drásticamente el tiempo de desarrollo y estandarizando la arquitectura de soluciones basadas en IA Generativa.

🎯 Propósito

El framework aborda el desafío de integrar servicios existentes con agentes de IA mediante:

  1. Automatización de Generación de Código: Transformación automática de contratos OpenAPI en system prompts y funciones invocables
  2. Estandarización de Arquitectura: Patrones consistentes para BFFs que actúan como intermediarios entre clientes y agentes
  3. Aceleración de Desarrollo: Comandos VS Code (/new-agent, /new-bff) que generan código listo para producción
  4. Integración con Azure AI Foundry: Aprovechamiento nativo de capacidades de Azure AI para orquestación de agentes
  5. Flexibilidad de Implementación: Dos tipos de herramientas (function y openapi) para diferentes necesidades

🔀 Dos Modalidades de Agentes

El framework soporta dos tipos de herramientas (tools) para agentes, seleccionables mediante el parámetro functionType:

1️⃣ Function Tools (functionType: "function")

Características:

  • ✅ Requiere generación de BFF con /new-bff
  • ✅ Mayor control sobre lógica de negocio
  • ✅ Permite validación personalizada y transformación de datos
  • ✅ Implementación en Java como clases FunctionTool
  • ✅ Registro automático mediante @Service y FunctionToolRunner

Cuándo usar:

  • Necesitas validar o transformar datos antes de invocar servicios
  • Requieres lógica de negocio intermedia
  • Necesitas manejo de errores personalizado
  • El servicio externo necesita autenticación compleja o propagación de tokens

Flujo:

Usuario → BFF → Azure AI Agent → BFF (ejecuta FunctionTools) → Servicio Externo

2️⃣ OpenAPI Tools (functionType: "openapi")

Características:

  • ✅ NO requiere generación de BFF
  • ✅ Invocación directa del servicio externo desde Azure AI Foundry
  • ✅ Más rápido de implementar
  • ✅ Ideal para APIs simples sin lógica intermedia
  • ✅ Menor overhead operacional

Cuándo usar:

  • API externa simple sin necesidad de transformaciones
  • No requieres lógica de negocio intermedia
  • El servicio externo es accesible directamente desde Azure AI Foundry
  • Quieres minimizar componentes en la arquitectura

Flujo:

Usuario → Azure AI Agent → Servicio Externo (invocación directa)

🏗️ Arquitectura del Framework

Componentes Principales

foundry-playground/
├── .github/prompts/          # Plantillas de generación de código basado en Github Copilot Promptfile
│   ├── new-agent.prompt.md   # Promptfile que da soporte al comando /new-agent
│   ├── new-bff.prompt.md     # Promptfile que da soporte al comando /new-bff
│   └── SYSTEM_PROMPT_TEMPLATE.md
├── agents-backend/            # ⭐ BFF Central que sirve de plantilla para incorporación de nuevas `tools` 
│   ├── agents-api.yaml        # Contrato OpenAPI del BFF
│   └── src/main/java/
│       └── org/microsoft/ai/
│           ├── api/           # Controllers REST
│           └── domain/agents/
│               └── functions/ # ⚡ Function Tools de contexto 
├── infra/
│   ├── agents/                # 🛠️ Herramientas TypeScript para crear agentes
│   │   ├── index.ts           # Script principal de creación
│   │   └── package.json       # Dependencias del SDK de Azure AI
│   └── agent-demos/           # 📁 Agentes generados
│       ├── {agentGenerado}/
│       │   ├── {systemPromptName}.md    # System Prompt generado
│       │   └── {agentNameConf}.yaml     # Configuración generada
│       └── todos/
└── documentation/             # Documentación del framework

Nota Importante:

  • agents-backend/ es el BFF central que sirve contexto para la generación de los nuevos BFF que siguen el arquetipo propuesto. Este da soporte al comando new-bff (solo para functionType: "function")
  • infra/agents/ contiene herramientas TypeScript automatizadas para crear agentes en Azure AI Foundry vía SDK
  • Los comandos /new-agent y /new-bff leen OpenAPI de servicios externos y generan código
  • Con functionType: "function": se genera código en agents-backend/ (BFF completo)
  • Con functionType: "openapi": NO se genera BFF, el agente invoca directamente el servicio externo

Flujo de Arquitectura de acelerador

Flujo end to end

Nota: El flujo varía según el functionType seleccionado en /new-agent:

  • functionType: "function": Requiere generación de BFF con /new-bff
  • functionType: "openapi": NO requiere BFF, invocación directa al servicio
%%{init: {'theme':'base', 'themeVariables': { 'primaryColor':'#107C10','primaryTextColor':'#fff','primaryBorderColor':'#0B5A08','lineColor':'#0B5A08'}}}%%
graph LR
    A["📄 OpenAPI<br/>Contract<br/>Existente"] 
    
    B["⚡ /new-agent<br/>functionType"]
    C["📝 System Prompt<br/>⚙️ Agent Config<br/>📖 README"]
    
    D["⚡ /new-bff<br/>solo function"]
    E["💻 WebClients<br/>🔧 Functions<br/>⚙️ Configs"]
    
    F["🛠️ Herramienta<br/>TypeScript<br/>infra/agents"]
    
    G["☁️ Azure AI<br/>Foundry<br/>Agent"]
    
    H["✅ Agente<br/>Funcional"]
    
    A -->|Analiza| B
    B -->|Genera| C
    
    B -.->|Si functionType<br/>function| D
    D -.->|Genera| E
    
    C -->|Lee YAML| F
    E -.->|Configs BFF<br/>si existe| F
    
    F -->|Crea Agente| G
    G -->|Agent ID| H
    
    style A fill:#0078D4,stroke:#005A9E,color:#fff
    style B fill:#FFB900,stroke:#D39300,color:#000
    style D fill:#FFB900,stroke:#D39300,color:#000,stroke-dasharray: 5 5
    style E fill:#E8E8E8,stroke:#999,color:#000,stroke-dasharray: 5 5
    style F fill:#107C10,stroke:#0B5A08,color:#fff
    style G fill:#50E6FF,stroke:#00B7C3,color:#000
    style H fill:#FF6B9D,stroke:#E60072,color:#fff
Loading

Leyenda:

  • Líneas continuas: Flujo obligatorio
  • Líneas punteadas: Flujo condicional (solo para functionType: "function")

Generación de codigo

graph TB
    A[📄 Contrato OpenAPI<br/>del Servicio Existente]
    
    B["⚡ /new-agent<br/>(con functionType)"]
    C["📝 System Prompt MD<br/>(con clausuras)"]
    D["⚙️ Agent Config YAML<br/>(tools según tipo)"]
    E["📖 README.md<br/>(ejemplos de prueba)"]
    
    F{"functionType?"}
    
    G["⚡ /new-bff<br/>(solo si 'function')"]
    H["💻 WebClient por Tag"]
    I["🔧 FunctionTool por operationId"]
    J["⚙️ Configs Auto-generadas"]
    
    K["⏭️ Saltar al<br/>Deploy"]
    
    A -->|Paso 1| B
    B -->|Genera| C
    B -->|Genera| D
    B -->|Genera| E
    
    D --> F
    
    F -->|"function"| G
    G -->|Genera| H
    G -->|Genera| I
    G -->|Genera| J
    
    F -.->|"openapi"| K
    
    style A fill:#0078D4,stroke:#005A9E,color:#fff
    style B fill:#FFB900,stroke:#D39300,color:#000
    style F fill:#FF6B9D,stroke:#E60072,color:#fff
    style G fill:#2196f3,stroke:#1565c0,stroke-width:3px,color:#fff
    style K fill:#4caf50,stroke:#2e7d32,stroke-width:2px,color:#fff
    style H fill:#E8E8E8,stroke:#666,color:#000
    style I fill:#E8E8E8,stroke:#666,color:#000
    style J fill:#E8E8E8,stroke:#666,color:#000
Loading

Diferencias Clave por Tipo:

Aspecto functionType: "function" functionType: "openapi"
Comando /new-bff ✅ Requerido ❌ No necesario
BFF Generado ✅ Sí (proyecto completo) ❌ No
WebClients ✅ Generados por Tag ❌ No aplica
FunctionTool Classes ✅ Una por operationId ❌ No aplica
Invocación Servicio A través del BFF Directa desde Azure AI
Complejidad Mayor control y lógica Más simple y directo

🔄 Metodología de Trabajo

Fase 1: Generación del Agente (/new-agent)

Entrada: Contrato OpenAPI de un servicio existente

Parámetros Clave:

  • agentName: Nombre descriptivo del agente (camelCase o kebab-case)
  • functionType: Tipo de herramientas del agente
    • function: Tools tipo function con parámetros detallados (requiere BFF implementando FunctionTool)
    • openapi: Tools tipo OpenAPI que referencian directamente el contrato OpenAPI
  • folderName: Directorio donde se generarán los archivos
  • openApiFile: Ruta al archivo OpenAPI 3.x del servicio externo

Proceso:

  1. Validaciones Automáticas: Formato de parámetros, validez del OpenAPI, presencia de operationIds
  2. Filtrado de Operaciones: Solo operaciones relevantes para clientes (excluye administrativas)
  3. Análisis del OpenAPI: Extracción de operationIds, tags, parámetros y respuestas
  4. Generación de System Prompt: Creación de instrucciones especializadas con tono de comunicación y clausuras de protección
  5. Configuración del Agente: Definición de herramientas según functionType en YAML
  6. Mapeo de Responsabilidades: Transformación de endpoints en funciones invocables
  7. Todo el código se genera dentro de: infra/agent-demos/{agentGenerado}

Salida: (generado en infra/agent-demos/{agentGenerado}/)

  • {agentName}_SYSTEM_PROMPT.md - System prompt con instrucciones, tono y clausuras de protección del agente
  • {agentName}.yaml - Configuración completa del agente con tools según functionType
  • README.md - Documentación del agente con ejemplos de uso y casos de prueba
  • Especificación de functions que debe implementar el BFF (solo si functionType es "function")

Fase 2: Generación del BFF (/new-bff) - Solo para functionType: "function"

⚠️ Nota Importante: Esta fase solo es necesaria si en la Fase 1 seleccionaste functionType: function. Si usaste functionType: openapi, el agente invocará directamente el servicio externo sin necesidad de un BFF intermedio.

Entrada: Contrato OpenAPI del servicio externo que sera usado como Custom Function o Tool del agente.

Validaciones Automáticas:

  • Existencia y accesibilidad del archivo OpenAPI
  • Extensión válida (.yaml, .yml o .json)
  • Estructura OpenAPI 3.x válida
  • Presencia de operationIds y tags

Proceso:

  1. Generación de WebClients: Un WebClient especializado por cada Tag del OpenAPI
  2. Implementación de Function Tools: Una clase Java por cada operationId
  3. Configuración Automática: Actualización de AgentConfiguration.java, application-*.yaml y example.env
  4. Registro Automático: Integración con FunctionToolRunner para descubrimiento dinámico
  5. Todo el código se genera dentro de agents-backend/src/main/java/org/microsoft/ai/domain/agents/functions/

Salida (generado en agents-backend/):

  • functions/{tag}/{Tag}WebClient.java - Cliente HTTP especializado por dominio
  • functions/{tag}/{OperationId}Function.java - Implementaciones de FunctionTool (una por operationId)
  • config/AgentConfiguration.java - Con propiedades actualizadas para URLs de backends
  • resources/application-local.yaml - Con nuevas propiedades de configuración
  • resources/application-azure.yaml - Con nuevas propiedades de configuración
  • example.env - Documentación de variables de entorno requeridas
  • Código listo para compilar y desplegar como parte del BFF central

¿Por qué dos tipos de tools?

  • function: Mayor control, permite validación personalizada, transformación de datos y lógica de negocio en el BFF. Agrega la capacidad de comunicación con backends privados a diferencia de la OpenAPI tool en la version actual.
  • openapi: Más rápido para APIs simples que no requieren lógica intermedia, Azure AI Foundry invoca directamente el servicio

Fase 3: Creación del Agente en Azure AI Foundry

Herramienta: Scripts TypeScript automatizados en infra/agents/

Requisitos:

  • Variables de entorno configuradas (AZURE_AI_PROJECT_ENDPOINT, MODEL_DEPLOYMENT_NAME)
  • Dependencias instaladas (npm install en infra/agents/)

Proceso:

  1. Configuración: Variables de entorno para Azure AI Project endpoint y modelo
  2. Ejecución: npm run createAgent ../agent-demos/{agente}/{agente}.yaml
  3. Validación: Verificación de esquemas OpenAPI (si aplica) y system prompts
  4. Procesamiento según tipo:
    • function tools: Genera esquemas de parámetros detallados
    • openapi tools: Valida el esquema OpenAPI y referencia el archivo
  5. Creación: Uso del SDK @azure/ai-agents para crear agente en Azure AI Foundry
  6. Resultado: Agent ID generado para uso en el BFF (si aplica)

Salida:

  • Agente creado en Azure AI Foundry
  • Agent ID para configuración del BFF (si functionType es "function")
  • Tools registradas automáticamente según el tipo:
    • function: Aparecen como funciones individuales con parámetros explícitos
    • openapi: Aparece como referencia al archivo OpenAPI para invocación directa

🛠️ Tecnologías Utilizadas

Frontend (ng-agents-frontend)

  • Angular 21 para interfaz de usuario
  • TypeScript para tipado fuerte
  • SCSS + Tailwind para estilos

Backend (agents-backend)

  • Java 17/21+ con Spring Boot
  • Spring WebFlux para operaciones reactivas
  • Azure AI SDK para integración con Azure AI Foundry (Este mismo enfoque buscaremos de migrarlo a Microsoft Agent Framework)
  • OpenAPI 3.0 para contratos de API
  • Gradle como herramienta de construcción

Herramientas de Creación (infra/agents)

  • TypeScript para scripts de automatización
  • Node.js 18+ como runtime
  • @azure/ai-agents SDK oficial de Azure
  • js-yaml para procesamiento de configuración
  • swagger-parser para validación de OpenAPI

Infraestructura

  • Azure API Management para exposición de servicios públicos y protección de recursos
  • Azure AI Foundry para orquestación de agentes
  • Azure Container Apps para despliegue de microservicios
  • Azure Entra ID para autenticación y autorización
  • Azure Database for PostgreSQL - Flexible Server

🚀 Comenzar

Para Nuevos Usuarios

  1. Quick Start ⚡
    • Crea tu primer agente en 30 minutos (15-20 min con functionType: "openapi")
    • Configuración inicial paso a paso
    • Ejemplo práctico completo con Games Backend
    • Uso de herramientas automatizadas de creación
    • Guía completa para ambos tipos de tools: function y openapi
    • Empieza aquí si es tu primera vez usando este marco de trabajo

🏗️ Entender el Framework

Arquitectura y Diseño

  1. Arquitectura 🏛️
    • Visión general: Dos modalidades arquitectónicas (Function Tools vs OpenAPI Tools)
    • Arquitectura de alto nivel: Diagramas y flujos según functionType
    • Componentes del sistema: Frontend, BFF, Azure AI Foundry, Backend Services
    • Flujos de datos completos: 4 flujos detallados con diagramas Mermaid
      • Flujo de mensajes (Function Tools y OpenAPI Tools)
      • Generación de código con /new-agent
      • Generación de BFF con /new-bff
      • Creación automatizada del agente en Azure AI Foundry
    • Patrones de diseño: Strategy, Registry, Adapter y Facade
    • Seguridad: Propagación de tokens, validación en capas, clausuras de protección
    • Escalabilidad y rendimiento: Programación reactiva, microservicios, caché
    • Diagrama de despliegue: Infraestructura completa en Azure
    • Guía de decisiones: Cuándo usar cada tipo de tool con tabla comparativa

🤝 Contribución

Este framework está diseñado para ser extensible. Para agregar nuevas capacidades:

  1. Extiende las plantillas en .github/prompts/
  2. Agrega nuevos patrones de Function Tools
  3. Mejora las herramientas de creación en infra/agents/
  4. Documenta casos de uso en documentation/

📝 Licencia

[Especificar licencia del proyecto]

Versión: 1.0.0
Última Actualización: Octubre 2025
Mantenido por: Microsoft Apps & AI Platforms Team - MCSA

About

No description, website, or topics provided.

Resources

Readme
Activity

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

No packages published

Languages