@envisiongroup/create-alakazam 0.1.1

package/templates/default/README.md

@@ -0,0 +1,66 @@
+# **PROJECT_NAME**
+
+Agents hub [Mastra](https://mastra.ai) construido sobre
+[`@envisiongroup/alakazam`](https://www.npmjs.com/package/@envisiongroup/alakazam).
+
+Todo el wiring transversal (auth Entra ID, storage multi-dialecto, rutas de
+chat/catálogo/adjuntos, observability, CORS) lo resuelve `createAgentsHub()`;
+este repo solo declara su dominio en `src/mastra/`.
+
+## Setup
+
+```bash
+cp .env.sample .env   # rellena AZURE_MODEL_*, AZURE_API_* y OPENAI_API_KEY
+pnpm install
+pnpm dev              # Mastra Studio en http://localhost:4111
+```
+
+> **npm privado**: `@envisiongroup/alakazam` es un paquete restringido del scope
+> `@envisiongroup`. Necesitas un token npm con acceso al scope configurado en tu
+> `~/.npmrc` (`//registry.npmjs.org/:_authToken=...`) antes de `pnpm install`.
+
+## Qué incluye el template
+
+| Recurso                             | Demuestra                                                                                                                                                                                                                                                                        |
+| ----------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `agents/weather-agent`              | Agente mínimo: `hubAgent()` (catálogo + acceso público), `getAzureClient()`, tool propia, scorers, `Memory`.                                                                                                                                                                     |
+| `agents/azure-openai-sandbox-agent` | Patrones avanzados: emisión de reasoning (`emitReasoning: true` en `hubAgent()` + `reasoningSummary`), adjuntos con `fileAttachmentProcessor` (uploads), generación de archivos con `code_interpreter` y links de descarga (downloads), `capabilities` vía `hubAgent()`.         |
+| `agents/azure-claude-sandbox-agent` | Provider alternativo: Claude vía Azure AI Foundry (capa de compatibilidad Responses API), adjuntos PDF/imágenes nativos, fail-closed de uploads Office (sin `code_interpreter`).                                                                                                 |
+| `agents/user-context-agent`         | Contexto del usuario autenticado: `requestContextSchema`, instrucciones dinámicas con la identidad del usuario y tools condicionales según haya (o no) usuario en el `requestContext`. Sin Microsoft Graph (el profile resolver es Noop sin env vars → funciona out-of-the-box). |
+| `tools/weather-tool`                | `createTool` con schemas zod contra una API pública.                                                                                                                                                                                                                             |
+| `workflows/weather-workflow`        | `createWorkflow` + `createStep` con schemas zod y metadata `hubWorkflow()` (catálogo + acceso).                                                                                                                                                                                  |
+| `scorers/weather-scorer`            | Scorers prebuilt de `@mastra/evals` + un scorer LLM-judged custom.                                                                                                                                                                                                               |
+| `access/role-rules.ts`              | Dónde mapear claims del IdP (grupos Entra, dominios, emails) → roles de aplicación.                                                                                                                                                                                              |
+
+Si generaste el proyecto con `--minimal`, solo queda la suite weather (agente,
+tool, workflow y scorer): los tres agents de ejemplo avanzados no se copian.
+
+> **Adjuntos en Mastra Studio (limitación conocida)**: el composer del chat de
+> Studio solo envía `image/*`, PDF, video y audio como _file parts_. Los
+> archivos Office/CSV (DOCX, XLSX, PPTX, CSV) los lee como texto y llegan
+> corruptos al modelo — es un bug de Mastra upstream (vivo en `main` y en
+> `mastra@1.19.0`, sin fix publicado). Para probar el flujo de adjuntos
+> Office de `azure-openai-sandbox-agent` end-to-end usa el SPA autenticado;
+> en Studio puedes probar el pipeline de adjuntos con PDF.
+
+## Convenciones clave
+
+- **Acceso por recurso**: todo agent/workflow registrado declara su acceso en
+  `metadata.envisionHub` vía `hubAgent()` — sin eso el arranque falla
+  (default-deny, fail-fast).
+- **Imports del paquete**: usa los subpaths del exports map, p. ej.
+  `@envisiongroup/alakazam/services/azure-model`. Los archivos internos no
+  son importables.
+- **Peers**: `@mastra/*`, `@ai-sdk/*`, `ai` y `zod` son peerDependencies de
+  alakazam (una sola instancia de Mastra para no romper singletons). Los
+  dialectos de storage (`pg`, `mssql`) son peers opcionales: instálalos solo
+  si cambias el `DATABASE_URL` por defecto.
+
+## Scripts
+
+```bash
+pnpm dev          # desarrollo con Mastra Studio
+pnpm build        # build de producción (mastra build)
+pnpm start        # servir el build
+pnpm typecheck    # tsc --noEmit
+```

package/templates/default/gitignore

@@ -0,0 +1,7 @@
+node_modules/
+dist/
+.mastra/
+.env
+*.db
+*.db-journal
+.DS_Store

package/templates/default/package.json

@@ -0,0 +1,36 @@
+{
+    "name": "__PROJECT_NAME__",
+    "private": true,
+    "version": "0.1.0",
+    "description": "Agents hub Mastra construido sobre @envisiongroup/alakazam.",
+    "type": "module",
+    "engines": {
+        "node": ">=22.13.0"
+    },
+    "scripts": {
+        "dev": "mastra dev",
+        "build": "mastra build",
+        "start": "mastra start",
+        "typecheck": "tsc --noEmit"
+    },
+    "dependencies": {
+        "@envisiongroup/alakazam": "__ALAKAZAM_VERSION__",
+        "@ai-sdk/azure": "^3.0.51",
+        "@ai-sdk/openai": "^3.0.49",
+        "@mastra/ai-sdk": "^1.6.2",
+        "@mastra/core": "^1.51.0",
+        "@mastra/editor": "^0.13.7",
+        "@mastra/evals": "^1.5.1",
+        "@mastra/libsql": "^1.16.0",
+        "@mastra/loggers": "^1.2.0",
+        "@mastra/memory": "^1.23.0",
+        "@mastra/observability": "^1.16.1",
+        "ai": "^6.0.149",
+        "zod": "^4.3.6"
+    },
+    "devDependencies": {
+        "@types/node": "^25.5.0",
+        "mastra": "^1.19.0",
+        "typescript": "^5.9.3"
+    }
+}

package/templates/default/src/mastra/access/role-rules.ts

@@ -0,0 +1,31 @@
+import type { RoleRule } from '@envisiongroup/alakazam';
+
+/**
+ * Reglas del proveedor de identidad → roles de aplicación de este cliente.
+ *
+ * Este es el único lugar del cliente que conoce datos del proveedor de
+ * identidad, como grupos de Entra, dominios y correos. Los agentes y
+ * workflows declaran roles lógicos en `metadata.envisionHub.access`; aquí se
+ * define quién recibe esos roles según sus claims.
+ *
+ * Estado actual: todos los recursos invocables del hub son `{ public: true }`
+ * o `{ internal: true }`, así que no hacen falta reglas. Cuando un recurso
+ * declare `access: { roles: ['mi-rol'] }`, agregar la regla que lo otorga:
+ *
+ * ```ts
+ * // Grupo de Entra ID (Object ID del grupo) → rol de aplicación:
+ * { when: { provider: 'entra', group: '8f14e45f-…' }, grant: 'cochilco-viewer' },
+ * // Dominio (tid Entra / hd Google Workspace) → rol:
+ * { when: { provider: 'google', domain: 'envisiongroup.com' }, grant: 'employee' },
+ * // Email directo → rol (útil para admins puntuales):
+ * { when: { email: 'admin@envisiongroup.com' }, grant: 'hub-admin' },
+ * ```
+ *
+ * Requiere que la App Registration de la API tenga configurado
+ * `groupMembershipClaims` (p. ej. "SecurityGroup") para que el JWT incluya
+ * el claim `groups`. El Object ID del grupo se obtiene en
+ * Entra ID → Groups → propiedad "Object ID".
+ */
+export const ROLE_RULES: RoleRule[] = [
+    // { when: { provider: 'entra', group: '<OBJECT-ID-DEL-GRUPO>' }, grant: 'mi-rol' },
+];

package/templates/default/src/mastra/agents/azure-claude-sandbox-agent/azure-claude-sandbox-agent.ts

@@ -0,0 +1,108 @@
+import { Agent } from '@mastra/core/agent';
+import { Memory } from '@mastra/memory';
+import { getAzureClient } from '@envisiongroup/alakazam/services/azure-model';
+import {
+    fileAttachmentProcessor,
+    uploadGrantStore,
+    uploadProviderRegistry,
+} from '@envisiongroup/alakazam/services/uploads';
+import { attachments, hubAgent } from '@envisiongroup/alakazam';
+
+// Crea el cliente de Azure y selecciona el modelo LLM que se usara.
+const azureClient = getAzureClient();
+
+// Claude se expone mediante Azure AI Foundry. Usamos `getAzureClient` en lugar
+// de `@ai-sdk/anthropic` porque Microsoft ofrece una capa de compatibilidad
+// sobre los deployments de Foundry. Esta capa recibe el formato de Azure OpenAI
+// Responses API y lo convierte internamente al formato de Anthropic Messages.
+// Consideraciones:
+//
+//  + Reutilizamos el mismo SDK y las variables de entorno que gpt-*.
+//  + Los PDF llegan mediante Azure Files (`file_id`), no como base64 inline.
+//    Esto reduce la latencia y el consumo de tokens.
+//  + `provider-selector` resuelve `azure.responses` como `azure-files`, por lo
+//    que también se aplican las validaciones de seguridad y deduplicación.
+//  - Algunas funciones de Claude no están disponibles en esta capa: la visión
+//    puede ser inconsistente, y no se exponen `extended_thinking` ni el
+//    almacenamiento temporal de prompts con TTL personalizado.
+//  - Un cambio en el conversor de Microsoft podría afectar este agente.
+//
+// Si necesitas OCR de imágenes, visión avanzada, `extended_thinking`, cache de
+// prompts, citas u otra función exclusiva de Claude, usa el SDK nativo
+// `@ai-sdk/anthropic` con `getAnthropicClient`. Esa opción requiere configurar
+// `AZURE_ANTHROPIC_BASE_URL`.
+const llmModel = azureClient('claude-opus-4-7');
+
+/**
+ * Agente de prueba general para Claude. Pensado para experimentar con
+ * adjuntos (PDFs principalmente) y validar features del flujo del modulo de
+ * uploads contra el modelo. NO tiene proposito de negocio especifico — para
+ * ese tipo de uso, crear un agente dedicado.
+ */
+export const azureClaudeSandboxAgent = new Agent({
+    id: 'azure-claude-sandbox-agent',
+    name: 'Sandbox Azure Claude',
+    description:
+        'Agente sandbox para probar Claude (via Azure AI Foundry) con adjuntos. Acepta PDFs y los lee nativamente. Sin caso de uso especifico — para experimentar con prompts, adjuntos y comportamiento del modelo.',
+    instructions: `
+Eres un asistente de proposito general construido sobre Claude.
+
+# Como respondes
+- En español, claro y conciso. Sin formalismos innecesarios.
+- Si el usuario te hace una pregunta puntual, contesta directo. No agregues estructura tipo "1, 2, 3" si no aporta.
+- Si el usuario te pide algo que requiere mas analisis (resumir un documento, comparar, extraer datos), si conviene estructurar la respuesta — usa secciones / listas / tablas markdown segun ayude.
+
+# Adjuntos
+- PDFs e imagenes: el usuario puede adjuntar estos archivos y vos los lees directamente como contenido visual. No tenes sandbox de Python.
+- Para cualquier calculo numerico que hagas sobre tablas del PDF o imagen, mostra el desglose paso a paso para que el usuario pueda auditar. No alucines cifras: si una celda no se lee bien, decilo.
+- Otros formatos (XLSX/DOCX/PPTX/CSV): si el usuario adjunta algo asi, indicale que hoy este agente solo soporta PDFs e imagenes. No intentes adivinar contenido.
+
+# Limites
+- No tenes acceso a internet ni a tools externas.
+- No podes generar archivos binarios (Excel, Word, imagenes). Si el usuario los pide, ofrece el contenido como markdown / CSV / texto inline.
+- Si una pregunta requiere informacion que no tenes en el contexto, decilo en vez de inventar.
+    `,
+    model: llmModel,
+    metadata: {
+        ...hubAgent({
+            catalog: { tags: ['sandbox', 'claude', 'azure'] },
+            access: { public: true },
+            capabilities: {
+                attachments: [attachments.pdf, attachments.images],
+            },
+        }),
+    },
+    // No se declara `code_interpreter`: aunque Claude se accede via la capa de
+    // compatibilidad de Azure OpenAI Responses API, el tool `code_interpreter`
+    // NO esta soportado para deployments de Claude (es feature OpenAI-only).
+    // Sin esta tool declarada, el `fileAttachmentProcessor` entra en
+    // fail-closed para Office docs y no intenta subirlos.
+    inputProcessors: [
+        // Intercepta `FileUIPart` inline del usuario. Como `model.provider` es
+        // `azure.responses` (capa de compat), el `provider-selector` resuelve
+        // `azure-files`. Resultado por tipo de adjunto:
+        //
+        //  - PDF: sube a Azure Files API, emite marker firmado con HMAC,
+        //    `processLLMRequest` lo reinyecta como `input_file.file_id`. La
+        //    capa de compat de Foundry traduce eso a Claude `document` block.
+        //  - XLSX/DOCX/PPTX/CSV: delivery seria `code-interpreter-container`,
+        //    pero como NO pasamos `codeInterpreterFactory` el processor entra
+        //    en fail-closed → devuelve la FileUIPart original. El AI SDK la
+        //    rechaza con `AI_UnsupportedFunctionalityError`, error claro.
+        //  - Imagen: no esta en el whitelist actual (`SUPPORTED_UPLOAD_FORMATS`)
+        //    → fluye inline. Resultado depende de si la capa de compat de
+        //    Foundry traduce bien `input_image` a Claude `image` block (a
+        //    veces si, a veces no — feature en evolucion).
+        fileAttachmentProcessor({
+            grantStore: uploadGrantStore,
+            providerRegistry: uploadProviderRegistry,
+            model: llmModel,
+            // SIN `codeInterpreterFactory`: Claude no soporta esa tool. El
+            // fail-closed del processor evita uploads inutiles a Azure para
+            // Office docs.
+        }),
+    ],
+    // SIN outputProcessors: no hay `code_interpreter` generando archivos para
+    // descargar.
+    memory: new Memory(),
+});

package/templates/default/src/mastra/agents/azure-openai-sandbox-agent/azure-openai-sandbox-agent.ts

@@ -0,0 +1,111 @@
+import { Agent } from '@mastra/core/agent';
+import { Memory } from '@mastra/memory';
+import { getAzureClient } from '@envisiongroup/alakazam/services/azure-model';
+import { attachments, hubAgent } from '@envisiongroup/alakazam';
+import {
+    createAzureCodeInterpreterDownloadProcessor,
+    downloadGrantStore,
+} from '@envisiongroup/alakazam/services/downloads';
+import {
+    fileAttachmentProcessor,
+    uploadGrantStore,
+    uploadProviderRegistry,
+} from '@envisiongroup/alakazam/services/uploads';
+import { buildInstructions } from './prompts';
+
+// Crea el cliente de Azure y selecciona el modelo LLM que se usara.
+const azureClient = getAzureClient();
+
+// Asegurate que el modelo especificado exista en tu proyecto de Azure Foundry
+const llmModel = azureClient('gpt-5.4');
+
+/**
+ * Agente de prueba general sobre gpt-5.4 mediante Azure OpenAI Responses API.
+ * Incluye tres capacidades que puedes reutilizar en otros agentes:
+ *
+ *  - `code_interpreter` para procesar adjuntos de Office y generar archivos.
+ *  - `fileAttachmentProcessor` para montar XLSX, DOCX, PPTX y CSV en el
+ *    contenedor del sandbox.
+ *  - `createAzureCodeInterpreterDownloadProcessor` para crear enlaces de
+ *    descarga para los archivos generados.
+ *
+ * Úsalo para experimentar con prompts, adjuntos y respuestas del modelo. No
+ * está asociado a un caso de negocio específico.
+ */
+export const azureOpenAISandboxAgent = new Agent({
+    id: 'azure-openai-sandbox-agent',
+    name: 'Sandbox Azure OpenAI',
+    description:
+        'Agente sandbox para probar gpt-5.4 (via Azure OpenAI Responses API) con adjuntos y generacion de archivos. Acepta PDF / XLSX / DOCX / PPTX / CSV y puede generar archivos como entregable. Sin caso de uso especifico — para experimentar.',
+    instructions: () => buildInstructions(),
+    model: llmModel,
+    // Permite que la ruta envíe al cliente los fragmentos `reasoning-*`.
+    // Sin esta opción, el provider los filtra antes de enviarlos al cliente.
+    //
+    // Para que el reasoning realmente aparezca en el cliente hacen falta
+    // DOS cosas en paralelo:
+    //   1. `emitReasoning: true` en `hubAgent()`
+    //   2. `providerOptions.openai.reasoningSummary: 'auto'` (abajo) — pide
+    //      al provider que genere el summary del reasoning.
+    // Si falta cualquiera de las dos, el reasoning no llega al cliente.
+    metadata: {
+        ...hubAgent({
+            catalog: { tags: ['sandbox', 'openai', 'azure'] },
+            access: { public: true },
+            capabilities: {
+                attachments: [
+                    attachments.pdf,
+                    attachments.images,
+                    attachments.office,
+                ],
+                generatedFiles: true,
+            },
+            emitReasoning: true,
+        }),
+    },
+    defaultOptions: {
+        providerOptions: {
+            openai: {
+                // `reasoningEffort`: cuánto "piensa" el modelo internamente.
+                // `low` mantiene latencia baja para el sandbox.
+                reasoningEffort: 'low', // 'minimal' | 'low' | 'medium' | 'high'
+                // `reasoningSummary: 'auto'`: pide al provider que emita
+                // un resumen del razonamiento como chunks `reasoning-*`
+                // streamed. Combinado con `emitReasoning: true` en
+                // `hubAgent()` (que emite `metadata.emitReasoning`)
+                // y `sendReasoning: true` en el route, el cliente useChat
+                // los renderiza como sección "Razonando…" colapsable.
+                reasoningSummary: 'auto',
+            },
+        },
+    },
+    // `code_interpreter` inicial sin `container.fileIds`. Cuando el usuario
+    // adjunta XLSX, DOCX, PPTX o CSV, `fileAttachmentProcessor` guarda los
+    // identificadores en `requestContext` y reemplaza esta tool por otra que
+    // incluye el contenedor con esos archivos.
+    tools: {
+        code_interpreter: azureClient.tools.codeInterpreter(),
+    },
+    inputProcessors: [
+        fileAttachmentProcessor({
+            grantStore: uploadGrantStore,
+            providerRegistry: uploadProviderRegistry,
+            model: llmModel,
+            // Habilita la rama Office/CSV: cuando hay file_ids en el
+            // requestContext, el processor usa esta factory en
+            // processInputStep para reemplazar el code_interpreter del step
+            // por uno con container cargado.
+            codeInterpreterFactory: (args) =>
+                azureClient.tools.codeInterpreter(args),
+        }),
+    ],
+    outputProcessors: [
+        // Genera enlaces de descarga absolutos usando el origen de la petición.
+        // Funciona detrás de un proxy y tanto en Mastra Studio como en un SPA
+        // con un origen diferente.
+        createAzureCodeInterpreterDownloadProcessor({
+            grantStore: downloadGrantStore,
+        }),
+    ],
+    memory: new Memory(),
+});

package/templates/default/src/mastra/agents/azure-openai-sandbox-agent/prompts/index.ts

@@ -0,0 +1,42 @@
+import {
+    codeInterpreterUsage,
+    composeInstructions,
+    immediateFeedback,
+} from '@envisiongroup/alakazam/prompts/common/index.js';
+
+const immediateFeedbackExamples = [
+    'Recibí el archivo. Voy a revisarlo primero y luego usaré code_interpreter para los cálculos necesarios.',
+    'Ya identifiqué los datos relevantes. Ahora voy a ejecutar el análisis en Python.',
+    'Voy a generar el archivo solicitado y dejarlo listo para descarga.',
+];
+
+const roleAndGoal = `Eres un asistente de propósito general construido sobre gpt-5.4 corriendo en Azure OpenAI.`;
+
+const responseStyle = `# Como respondes
+
+- En español, claro y conciso. Sin formalismos innecesarios.
+- Pregunta directa → respuesta directa. No agregues estructura tipo "1, 2, 3" si no aporta.
+- Si te piden algo que requiere mas analisis (resumir documento, comparar, extraer datos, hacer un calculo grande), si conviene estructurar — usa secciones / listas / tablas markdown segun ayude.`;
+
+const limits = `# Limites
+
+- No tienes acceso a internet ni a tools externas mas allá de \`code_interpreter\`.
+- Si una pregunta requiere informacion que no tienes en el contexto ni en los adjuntos, dilo en vez de inventar.`;
+
+export function buildInstructions() {
+    return composeInstructions([
+        roleAndGoal,
+        immediateFeedback({
+            toolName: 'code_interpreter',
+            examples: immediateFeedbackExamples,
+        }),
+        responseStyle,
+        codeInterpreterUsage({
+            toolName: 'code_interpreter',
+            additionalRules: [
+                'Para una pregunta puntual con una cuenta corta (por ejemplo, 1 + 1), no es necesario abrir un sandbox.',
+            ],
+        }),
+        limits,
+    ]);
+}

package/templates/default/src/mastra/agents/user-context-agent/prompts/index.ts

@@ -0,0 +1,93 @@
+import type {
+    AuthenticatedUserContextValue,
+    EnrichedUserProfile,
+} from '@envisiongroup/alakazam';
+
+const responseStyle = `# Como respondes
+
+- En español, claro y conciso.
+- Pregunta directa → respuesta directa. No agregues estructura tipo "1, 2, 3" si no aporta.`;
+
+const limits = `# Limites
+
+- No tienes acceso a internet ni a tools externas más allá de las declaradas.
+- Si una pregunta requiere información que no tienes en el contexto, dilo en vez de inventar.`;
+
+/**
+ * Instrucciones del `user-context-agent`: cambian según haya (o no) un
+ * usuario autenticado en el `requestContext` del request. Es la demo del
+ * patrón "instrucciones dinámicas por contexto".
+ *
+ * - SIN usuario: el agente explica qué demuestra y que el usuario debe
+ *   autenticarse (el hub corre detrás de auth; en Mastra Studio local no
+ *   hay IdP, así que este camino es el esperado ahí).
+ * - CON usuario: el agente sabe quién es (oid/upn/nombre, roles, grupos) y
+ *   — si el `UserProfileResolver` pudo enriquecerlo — su perfil (cargo,
+ *   departamento, oficina). Sin config de Graph el resolver es Noop y el
+ *   perfil llega `null`: el agente trabaja solo con la identidad del token.
+ */
+export function buildUserContextInstructions(
+    authenticatedUser: AuthenticatedUserContextValue | undefined,
+    userProfile: EnrichedUserProfile | null,
+): string {
+    if (!authenticatedUser) {
+        return [
+            `Eres un agente de ejemplo que demuestra el uso del contexto de usuario autenticado del hub.`,
+            `# Estado actual
+
+NO hay un usuario autenticado en el requestContext de este request (p. ej. estás corriendo en Mastra Studio local, donde no pasa por el middleware de auth del hub).
+
+# Qué demuestras
+
+- Cuando el request llega autenticado a través del hub, tu requestContext trae \`authenticatedUser\` (oid, upn, nombre, grupos del IdP y roles de aplicación resueltos) y estas instrucciones cambian para incluir esa identidad.
+- Sin usuario autenticado no tienes tools disponibles (las tools se declaran condicionales por contexto). Explica esto si te piden acciones.`,
+            responseStyle,
+            limits,
+        ].join('\n\n');
+    }
+
+    const rolesLine = authenticatedUser.roles?.length
+        ? `- Roles de aplicación: ${authenticatedUser.roles.join(', ')}`
+        : '- Roles de aplicación: (ninguno resuelto)';
+
+    const profileSection = userProfile
+        ? `# Perfil enriquecido (UserProfileResolver)
+
+${[
+    userProfile.displayName
+        ? `- Nombre para mostrar: ${userProfile.displayName}`
+        : null,
+    userProfile.jobTitle ? `- Cargo: ${userProfile.jobTitle}` : null,
+    userProfile.department ? `- Departamento: ${userProfile.department}` : null,
+    userProfile.businessUnit
+        ? `- Gerencia/Unidad: ${userProfile.businessUnit}`
+        : null,
+    userProfile.officeLocation
+        ? `- Oficina: ${userProfile.officeLocation}`
+        : null,
+]
+    .filter(Boolean)
+    .join('\n')}`
+        : `# Perfil enriquecido
+
+No disponible en este despliegue (sin config de Microsoft Graph el resolver es Noop → perfil null). Trabaja solo con la identidad del token.`;
+
+    return [
+        `Eres un agente de ejemplo que demuestra el uso del contexto de usuario autenticado del hub.`,
+        `# Usuario autenticado en este request
+
+- oid: ${authenticatedUser.oid}
+- UPN: ${authenticatedUser.upn}
+${authenticatedUser.name ? `- Nombre: ${authenticatedUser.name}` : ''}
+${rolesLine}
+- Grupos del IdP: ${authenticatedUser.groups.length ? authenticatedUser.groups.join(', ') : '(ninguno)'}`,
+        profileSection,
+        `# Qué demuestras
+
+- Sabes quién es el usuario sin preguntar: la identidad llegó en el requestContext vía el middleware de auth del hub.
+- Tienes la tool \`get-my-profile\` disponible SOLO porque hay usuario autenticado (tools condicionales por contexto). Úsala cuando el usuario pregunte por sus datos, roles o grupos.
+- Si el usuario pide algo fuera de su identidad/perfil, explica que eres un agente de ejemplo acotado a demostrar el contexto.`,
+        responseStyle,
+        limits,
+    ].join('\n\n');
+}

package/templates/default/src/mastra/agents/user-context-agent/tools/get-my-profile-tool.ts

@@ -0,0 +1,62 @@
+import { createTool } from '@mastra/core/tools';
+import { z } from 'zod';
+import {
+    getAuthenticatedUserOrThrow,
+    getOptionalUserProfileFromRequestContext,
+} from '@envisiongroup/alakazam';
+
+/**
+ * Tool de ejemplo self-contained (sin llamadas externas): devuelve el
+ * usuario autenticado y su perfil enriquecido tal como quedaron en el
+ * `requestContext` del request.
+ *
+ * Demuestra el patrón de leer contexto dentro de `execute` via
+ * `context.requestContext` — el mismo que usan las tools de Microsoft
+ * Graph del hub real, pero sin necesitar credenciales de Graph.
+ */
+export const getMyProfileTool = createTool({
+    id: 'get-my-profile',
+    description:
+        'Devuelve la identidad del usuario autenticado (oid, upn, nombre, grupos, roles de aplicación) y, si está resuelto, su perfil enriquecido (cargo, departamento, oficina).',
+    inputSchema: z.object({}),
+    outputSchema: z.object({
+        oid: z.string(),
+        upn: z.string(),
+        name: z.string().optional(),
+        groups: z.array(z.string()),
+        roles: z.array(z.string()).optional(),
+        provider: z.string().optional(),
+        profile: z
+            .object({
+                displayName: z.string().optional(),
+                jobTitle: z.string().optional(),
+                department: z.string().optional(),
+                businessUnit: z.string().optional(),
+                officeLocation: z.string().optional(),
+            })
+            .nullable(),
+    }),
+    execute: async (_input, context) => {
+        const requestContext = context?.requestContext;
+        // `OrThrow` es seguro acá: el agente solo expone esta tool cuando
+        // YA verificó que hay usuario autenticado en el requestContext
+        // (ver `getUserContextTools` en user-context-agent.ts).
+        const authenticatedUser = getAuthenticatedUserOrThrow(requestContext);
+        const profile =
+            getOptionalUserProfileFromRequestContext(requestContext) ?? null;
+
+        return {
+            oid: authenticatedUser.oid,
+            upn: authenticatedUser.upn,
+            ...(authenticatedUser.name ? { name: authenticatedUser.name } : {}),
+            groups: authenticatedUser.groups,
+            ...(authenticatedUser.roles
+                ? { roles: authenticatedUser.roles }
+                : {}),
+            ...(authenticatedUser.provider
+                ? { provider: authenticatedUser.provider }
+                : {}),
+            profile,
+        };
+    },
+});

package/templates/default/src/mastra/agents/user-context-agent/user-context-agent.ts

@@ -0,0 +1,87 @@
+import { Agent } from '@mastra/core/agent';
+import type { ToolsInput } from '@mastra/core/agent';
+import type { RequestContext } from '@mastra/core/request-context';
+import { Memory } from '@mastra/memory';
+import { getAzureClient } from '@envisiongroup/alakazam/services/azure-model';
+import {
+    ensureUserProfileInRequestContext,
+    getAuthenticatedUserFromRequestContext,
+    getUserProfileResolver,
+    hubAgent,
+    optionalAuthenticatedUserRequestContextSchema,
+} from '@envisiongroup/alakazam';
+import { buildUserContextInstructions } from './prompts';
+import { getMyProfileTool } from './tools/get-my-profile-tool';
+
+// Crea el cliente de Azure y selecciona el modelo LLM que se usara.
+const azureClient = getAzureClient();
+
+// Asegurate que el modelo especificado exista en tu proyecto de Azure Foundry
+const llmModel = azureClient('gpt-5.4');
+
+// Obtiene el resolvedor encargado de cargar el perfil del usuario.
+const userProfileResolver = getUserProfileResolver();
+
+type RequestContextReader = Pick<RequestContext<any>, 'get'> | undefined;
+
+/**
+ * Tools condicionales por contexto: sin usuario autenticado en el
+ * requestContext, el agente no expone ninguna tool. Es la demo del patrón
+ * `tools: ({ requestContext }) => ...` de Mastra.
+ */
+function getUserContextTools(requestContext: RequestContextReader): ToolsInput {
+    if (!getAuthenticatedUserFromRequestContext(requestContext)) {
+        return {};
+    }
+
+    return { getMyProfileTool };
+}
+
+/**
+ * Agente de ejemplo: contexto del usuario autenticado.
+ *
+ * Versión self-contained del patrón que usa `personal-profile-agent` en el
+ * hub real, SIN dependencia de Microsoft Graph (funciona out-of-the-box en
+ * un proyecto recién scaffolded):
+ *
+ *  - `requestContextSchema`: declara el shape del contexto que el agente
+ *    espera (usuario opcional → corre también anónimo en Studio).
+ *  - `instructions` dinámicas: con usuario, resuelve el perfil via
+ *    `ensureUserProfileInRequestContext` (cachea el resultado en el propio
+ *    requestContext) y compone instrucciones con la identidad.
+ *  - `tools` condicionales: `get-my-profile` solo existe si hay usuario.
+ *
+ * Sin env vars de Graph, `getUserProfileResolver()` devuelve un resolver
+ * Noop → el perfil enriquecido llega `null` y el agente trabaja solo con
+ * la identidad del token (oid/upn/nombre/grupos/roles).
+ */
+export const userContextAgent = new Agent({
+    id: 'user-context-agent',
+    name: 'Contexto de Usuario',
+    description:
+        'Agente de ejemplo que demuestra el contexto del usuario autenticado: requestContextSchema, instrucciones dinámicas con la identidad del usuario y tools condicionales según haya (o no) usuario en el requestContext.',
+    requestContextSchema: optionalAuthenticatedUserRequestContextSchema,
+    instructions: async ({ requestContext }) => {
+        if (!getAuthenticatedUserFromRequestContext(requestContext)) {
+            return buildUserContextInstructions(undefined, null);
+        }
+
+        const userProfile = await ensureUserProfileInRequestContext(
+            requestContext,
+            userProfileResolver,
+        );
+        return buildUserContextInstructions(
+            getAuthenticatedUserFromRequestContext(requestContext),
+            userProfile,
+        );
+    },
+    model: llmModel,
+    tools: ({ requestContext }) => getUserContextTools(requestContext),
+    metadata: {
+        ...hubAgent({
+            catalog: { tags: ['ejemplo', 'usuario', 'contexto'] },
+            access: { public: true },
+        }),
+    },
+    memory: new Memory(),
+}) as Agent;