Saltearse al contenido

Juego de Mazmorra de IA Agéntica

Comenzaremos creando un nuevo monorepo. Desde el directorio deseado, ejecuta el siguiente comando:

Terminal window
npx create-nx-workspace@21.6.4 dungeon-adventure --pm=pnpm --preset=@aws/nx-plugin --iacProvider=CDK --ci=skip --aiAgents

Esto configurará un monorepo NX dentro del directorio dungeon-adventure que podrás abrir en VSCode. Debería verse así:

  • Directory.nx/
  • Directory.vscode/
  • Directorynode_modules/
  • Directorypackages/ aquí residirán tus subproyectos
  • .gitignore
  • .npmrc
  • .prettierignore
  • .prettierrc
  • nx.json configura el CLI de NX y los valores por defecto del monorepo
  • package.json todas las dependencias de node se definen aquí
  • pnpm-lock.yaml o bun.lock, yarn.lock, package-lock.json según el gestor de paquetes
  • pnpm-workspace.yaml si usas pnpm
  • README.md
  • tsconfig.base.json todos los subproyectos basados en node extienden este
  • tsconfig.json
  • aws-nx-plugin.config.mts configuración para el Nx Plugin para AWS

Ahora estamos listos para comenzar a crear nuestros diferentes subproyectos usando el @aws/nx-plugin.

Primero creemos nuestra Game API. Para esto, crearemos una API tRPC llamada GameApi siguiendo estos pasos:

  1. Instale el Nx Console VSCode Plugin si aún no lo ha hecho
  2. Abra la consola Nx en VSCode
  3. Haga clic en Generate (UI) en la sección "Common Nx Commands"
  4. Busque @aws/nx-plugin - ts#trpc-api
  5. Complete los parámetros requeridos
    • name: GameApi
  6. Haga clic en Generate

Deberías ver que han aparecido algunos archivos nuevos en tu árbol de directorios.

Haz clic aquí para examinar estos archivos en detalle.

Ahora creemos nuestro Story Agent. Para esto, primero creemos un proyecto Python:

  1. Instale el Nx Console VSCode Plugin si aún no lo ha hecho
  2. Abra la consola Nx en VSCode
  3. Haga clic en Generate (UI) en la sección "Common Nx Commands"
  4. Busque @aws/nx-plugin - py#project
  5. Complete los parámetros requeridos
    • name: story
  6. Haga clic en Generate

Deberías ver que han aparecido algunos archivos nuevos en tu árbol de directorios.

Haz clic aquí para examinar estos archivos en detalle.

Luego, agreguemos un agente Strands al proyecto con el generador py#strands-agent:

  1. Instale el Nx Console VSCode Plugin si aún no lo ha hecho
  2. Abra la consola Nx en VSCode
  3. Haga clic en Generate (UI) en la sección "Common Nx Commands"
  4. Busque @aws/nx-plugin - py#strands-agent
  5. Complete los parámetros requeridos
    • project: story
  6. Haga clic en Generate

Deberías ver que han aparecido algunos archivos nuevos en tu árbol de directorios.

Haz clic aquí para examinar estos archivos en detalle.

Ahora creemos un servidor MCP que proveerá herramientas para que nuestro Story Agent gestione el inventario de un jugador.

Primero, creamos un proyecto TypeScript:

  1. Instale el Nx Console VSCode Plugin si aún no lo ha hecho
  2. Abra la consola Nx en VSCode
  3. Haga clic en Generate (UI) en la sección "Common Nx Commands"
  4. Busque @aws/nx-plugin - ts#project
  5. Complete los parámetros requeridos
    • name: inventory
  6. Haga clic en Generate

Esto creará un proyecto TypeScript vacío.

Haz clic aquí para examinar estos archivos en detalle.

Luego agregaremos un servidor MCP a nuestro proyecto TypeScript:

  1. Instale el Nx Console VSCode Plugin si aún no lo ha hecho
  2. Abra la consola Nx en VSCode
  3. Haga clic en Generate (UI) en la sección "Common Nx Commands"
  4. Busque @aws/nx-plugin - ts#mcp-server
  5. Complete los parámetros requeridos
    • project: inventory
  6. Haga clic en Generate

Esto agregará

Haz clic aquí para examinar estos archivos en detalle.

Ahora creemos la UI que permitirá interactuar con el juego. Para esto, creemos un sitio web llamado GameUI siguiendo estos pasos:

  1. Instale el Nx Console VSCode Plugin si aún no lo ha hecho
  2. Abra la consola Nx en VSCode
  3. Haga clic en Generate (UI) en la sección "Common Nx Commands"
  4. Busque @aws/nx-plugin - ts#react-website
  5. Complete los parámetros requeridos
    • name: GameUI
  6. Haga clic en Generate

Deberías ver que han aparecido algunos archivos nuevos en tu árbol de directorios.

Haz clic aquí para examinar estos archivos en detalle.

Ahora configuremos nuestra Game UI para requerir acceso autenticado mediante Amazon Cognito siguiendo estos pasos:

  1. Instale el Nx Console VSCode Plugin si aún no lo ha hecho
  2. Abra la consola Nx en VSCode
  3. Haga clic en Generate (UI) en la sección "Common Nx Commands"
  4. Busque @aws/nx-plugin - ts#react-website#auth
  5. Complete los parámetros requeridos
    • cognitoDomain: game-ui
    • project: @dungeon-adventure/game-ui
    • allowSignup: true
  6. Haga clic en Generate

Deberías ver que han aparecido/cambiado algunos archivos nuevos en tu árbol de directorios.

Haz clic aquí para examinar estos archivos en detalle.

Ahora configuremos nuestra Game UI para conectarse a nuestra Game API creada previamente:

  1. Instale el Nx Console VSCode Plugin si aún no lo ha hecho
  2. Abra la consola Nx en VSCode
  3. Haga clic en Generate (UI) en la sección "Common Nx Commands"
  4. Busque @aws/nx-plugin - api-connection
  5. Complete los parámetros requeridos
    • sourceProject: @dungeon-adventure/game-ui
    • targetProject: @dungeon-adventure/game-api
  6. Haga clic en Generate

Deberías ver que han aparecido/cambiado algunos archivos nuevos en tu árbol de directorios.

Haz clic aquí para examinar estos archivos en detalle.

Ahora el último subproyecto que necesitamos crear es para la infraestructura CDK. Para crearlo, sigue estos pasos:

  1. Instale el Nx Console VSCode Plugin si aún no lo ha hecho
  2. Abra la consola Nx en VSCode
  3. Haga clic en Generate (UI) en la sección "Common Nx Commands"
  4. Busque @aws/nx-plugin - ts#infra
  5. Complete los parámetros requeridos
    • name: infra
  6. Haga clic en Generate

Deberías ver que han aparecido/cambiado algunos archivos nuevos en tu árbol de directorios.

Haz clic aquí para examinar estos archivos en detalle.

Hagamos una actualización en nuestro packages/infra/src/stacks/application-stack.ts para instanciar algunos de nuestros constructs ya generados:

import {
GameApi,
GameUI,
InventoryMcpServer,
RuntimeConfig,
StoryAgent,
UserIdentity,
} from ':dungeon-adventure/common-constructs';
import { Stack, StackProps, CfnOutput } from 'aws-cdk-lib';
import { Construct } from 'constructs';
export class ApplicationStack extends Stack {
constructor(scope: Construct, id: string, props?: StackProps) {
super(scope, id, props);
const userIdentity = new UserIdentity(this, 'UserIdentity');
const gameApi = new GameApi(this, 'GameApi', {
integrations: GameApi.defaultIntegrations(this).build(),
});
const { userPool, userPoolClient } = userIdentity;
const mcpServer = new InventoryMcpServer(this, 'InventoryMcpServer');
// Use Cognito for user authentication with the agent
const storyAgent = new StoryAgent(this, 'StoryAgent', {
authorizerConfiguration: {
customJwtAuthorizer: {
discoveryUrl: `https://cognito-idp.${Stack.of(userPool).region}.amazonaws.com/${userPool.userPoolId}/.well-known/openid-configuration`,
allowedAudience: [userPoolClient.userPoolClientId],
},
},
environment: {
INVENTORY_MCP_ARN: mcpServer.agentCoreRuntime.arn,
},
});
// Add the Story Agent ARN to runtime-config.json so it can be referenced by the website
RuntimeConfig.ensure(this).config.agentArn =
storyAgent.agentCoreRuntime.arn;
new CfnOutput(this, 'StoryAgentArn', {
value: storyAgent.agentCoreRuntime.arn,
});
new CfnOutput(this, 'InventoryMcpArn', {
value: mcpServer.agentCoreRuntime.arn,
});
// Grant the agent permissions to invoke our mcp server
mcpServer.agentCoreRuntime.grantInvoke(storyAgent.agentCoreRuntime);
// Grant the authenticated role access to invoke the api
gameApi.grantInvokeAccess(userIdentity.identityPool.authenticatedRole);
// Ensure this is instantiated last so our runtime-config.json can be automatically configured
new GameUI(this, 'GameUI');
}
}

Nota que aquí proveemos integraciones predeterminadas para nuestra Game API. Por defecto, cada operación en nuestra API se mapea a una función lambda individual para manejar esa operación.

Ahora es momento de construir nuestro código por primera vez
Terminal window
pnpm nx run-many --target build --all

Deberías ver el siguiente mensaje:

Ventana de terminal
NX The workspace is out of sync
[@nx/js:typescript-sync]: Some TypeScript configuration files are missing project references to the projects they depend on or contain outdated project references.
This will result in an error in CI.
? Would you like to sync the identified changes to get your workspace up to date?
Yes, sync the changes and run the tasks
No, run the tasks without syncing the changes

Este mensaje indica que NX ha detectado algunos archivos que pueden actualizarse automáticamente. En este caso, se refiere a los archivos tsconfig.json que no tienen referencias de proyecto configuradas en proyectos dependientes. Selecciona la opción Yes, sync the changes and run the tasks para continuar. Deberías notar que todos los errores de importación en tu IDE se resuelven automáticamente, ya que el generador de sync agregará las referencias TypeScript faltantes.

Todos los artefactos construidos están ahora disponibles dentro de la carpeta dist/ ubicada en la raíz del monorepo. Esta es una práctica estándar cuando se usan proyectos generados por el @aws/nx-plugin ya que no contamina tu árbol de archivos con archivos generados. En caso de que quieras limpiar tus archivos, simplemente puedes eliminar la carpeta dist/ sin preocuparte por archivos generados esparcidos por el árbol de directorios.

¡Felicidades! Has creado todos los subproyectos requeridos para comenzar a implementar el núcleo de nuestro juego Dungeon Adventure. 🎉🎉🎉