awslabs · nx-plugin-for-aws · Mar 31, 2026 · Mar 31, 2026 · Mar 31, 2026 · Apr 1, 2026
diff --git a/docs/src/content/docs/en/get_started/tutorials/dungeon-game/3.mdx b/docs/src/content/docs/en/get_started/tutorials/dungeon-game/3.mdx
@@ -49,6 +49,16 @@ Since the connection generator already wired up the MCP client in <Link path="ge
 - Adding the `player_name` and `genre` parameters to the `get_agent` function, and
 - Customizing the system prompt for our dungeon adventure game.
 
+### Customize the CLI
+
+Since our agent accepts a custom input schema (`playerName`, `genre`, `actions`) instead of the default (`prompt`, `session_id`), we need to update the generated CLI script to pass these parameters.
+
+Update `packages/story/scripts/story-agent/cli.ts`:
+
+<E2EDiff lang="typescript" before="dungeon-adventure/3/cli.ts.old.template" after="dungeon-adventure/3/cli.ts.template" />
+
+This updated CLI accepts `--playerName` and `--genre` arguments and sends each message as an action in the conversation history.
+
 ## Task 2: Deployment and testing
 
 ### Build the code
@@ -93,11 +103,7 @@ dungeon-adventure-infra-sandbox-Application.UserIdentityUserIdentityUserPoolIdXX
 
 ### Test your Agent
 
-You can test your Agent by either:
-<ul>
-<li>Starting a local instance of the Agent server and invoking it using `curl`, or</li>
-<li>Calling the deployed API using curl with a JWT token.</li>
-</ul>
+You can test your Agent using the generated CLI invoke target. This provides an interactive chat interface to your agent directly in the terminal.
 
 <Tabs>
   <TabItem label="Local">
@@ -108,94 +114,21 @@ You can test your Agent by either:
     Use the CDK deploy output value of `RuntimeConfigApplicationId` for the `RUNTIME_CONFIG_APP_ID` environment variable, and your deployed AWS region for `AWS_REGION`.
     </Aside>
 
-    :::caution
-    Use the CDK deploy `InventoryMcpArn` output in the above, and specify your target `AWS_REGION`.
-    :::
-
-    Once the Agent server is up and running (you won't see any output), call it by running the following command:
+    Once the Agent server is up and running, invoke it using the CLI in a separate terminal. Pass `--playerName` and `--genre` to configure your adventure, and `--accessToken` if using Cognito authentication:
 
-    ```bash
-    curl -N -X POST http://127.0.0.1:8081/invocations \
-      -d '{"genre":"superhero", "actions":[], "playerName":"UnnamedHero"}' \
-      -H "Content-Type: application/json"
-    ```
+    <NxCommands commands={['run dungeon_adventure.story:agent-invoke -- --playerName UnnamedHero --genre superhero']} />
   </TabItem>
   <TabItem label="Deployed">
-    To test the deployed agent, you'll need to authenticate with Cognito and obtain a JWT token. First, set up your environment variables:
-
-    ```bash
-    # Set your Cognito User Pool ID and Client ID from the CDK outputs
-    export POOL_ID="<UserPoolId from CDK outputs>"
-    export CLIENT_ID="<UserPoolClientId from CDK outputs>"
-    export REGION="<your-region>"
-    ```
-
-    Create a test user and obtain an authentication token:
-
-    ```bash
-    # Disable MFA to simplify user creation
-    aws cognito-idp set-user-pool-mfa-config \
-      --mfa-configuration OFF \
-      --user-pool-id $POOL_ID
-
-    # Create User
-    aws cognito-idp admin-create-user \
-      --user-pool-id $POOL_ID \
-      --username "test" \
-      --temporary-password "TempPass123-" \
-      --region $REGION \
-      --message-action SUPPRESS > /dev/null
-
-    # Set Permanent Password (replace with something more secure!)
-    aws cognito-idp admin-set-user-password \
-      --user-pool-id $POOL_ID \
-      --username "test" \
-      --password "PermanentPass123-" \
-      --region $REGION \
-      --permanent > /dev/null
-
-    # Authenticate User and capture ID Token
-    export BEARER_TOKEN=$(aws cognito-idp initiate-auth \
-      --client-id "$CLIENT_ID" \
-      --auth-flow USER_PASSWORD_AUTH \
-      --auth-parameters USERNAME='test',PASSWORD='PermanentPass123-' \
-      --region $REGION \
-      --query "AuthenticationResult.AccessToken" \
-      --output text)
-    ```
-
-    Invoke the deployed agent using the Bedrock AgentCore runtime URL:
-
-    ```bash
-    # Set the Story Agent ARN from CDK outputs
-    export AGENT_ARN="<StoryAgentArn from CDK outputs>"
-
-    # URL-encode the ARN
-    export ENCODED_ARN=$(echo $AGENT_ARN | sed 's/:/%3A/g' | sed 's/\//%2F/g')
-
-    # Construct the invocation URL
-    export AGENT_URL="https://bedrock-agentcore.$REGION.amazonaws.com/runtimes/$ENCODED_ARN/invocations?qualifier=DEFAULT"
-
-    # Invoke the agent
-    curl -N -X POST "$AGENT_URL" \
-      -H "authorization: Bearer $BEARER_TOKEN" \
-      -H "Content-Type: application/json" \
-      -H "X-Amzn-Bedrock-AgentCore-Runtime-Session-Id: abcdefghijklmnopqrstuvwxyz-123456789" \
-      -d '{"genre":"superhero", "actions":[], "playerName":"UnnamedHero"}'
-    ```
-
-    :::note
-    The URL encoding is necessary to properly format the ARN for the Bedrock AgentCore API endpoint.
-    :::
+    To invoke the deployed agent, set the `RUNTIME_CONFIG_APP_ID` environment variable and provide an `--accessToken` for Cognito authentication:
+
+    <NxCommands highlights={['xxxx', 'your-access-token']} env={{RUNTIME_CONFIG_APP_ID:"xxxx"}} commands={['run dungeon_adventure.story:agent-invoke -- --accessToken your-access-token --playerName UnnamedHero --genre superhero']} />
+
+    <Aside type="caution">
+    Use the CDK deploy output value of `RuntimeConfigApplicationId` for the `RUNTIME_CONFIG_APP_ID` environment variable. Obtain an access token by authenticating with your Cognito User Pool.
+    </Aside>
   </TabItem>
 </Tabs>
 
-If the command runs successfully, you should start to see the initial story text being streamed as JSON Lines:
-
-```
-{"content":"You are "}
-{"content":"a new superhero "}
-{"content":"in the bustling metropolis of Metro City..."}
-```
+If the command runs successfully, you should see a chat prompt. Type a message and the agent will stream its response back to you in real time.
 
 Congratulations. You have built and deployed your first Strands Agent on Bedrock AgentCore Runtime!  🎉🎉🎉
diff --git a/docs/src/content/docs/en/guides/py-strands-agent.mdx b/docs/src/content/docs/en/guides/py-strands-agent.mdx
@@ -267,6 +267,20 @@ The generator configures a target named `<your-agent-name>-serve`, which starts
 
 This command uses `uv run` to execute your Strands Agent using the [Bedrock AgentCore Python SDK](https://github.com/aws/bedrock-agentcore-sdk-python).
 
+### Invoke Target
+
+The generator also creates a `<your-agent-name>-invoke` target which provides an interactive CLI for chatting with your agent in the terminal.
+
+To chat with a **locally running** agent (start the agent with `serve` or `serve-local` first):
+
+<NxCommands commands={['run your-project:agent-invoke']} />
+
+To invoke a **deployed** agent on Bedrock AgentCore Runtime, set the `RUNTIME_CONFIG_APP_ID` environment variable. If using Cognito authentication, pass `--accessToken`:
+
+<NxCommands highlights={['xxxx', 'your-access-token']} env={{RUNTIME_CONFIG_APP_ID:"xxxx"}} commands={['run your-project:agent-invoke -- --accessToken your-access-token']} />
+
+The CLI is a TypeScript script at `scripts/<your-agent-name>/cli.ts` that uses an OpenAPI-generated type-safe client from the shared `agent-connection` project. The generator sets up an `openapi` target to extract the OpenAPI spec from your FastAPI app, and generates the TypeScript client into the `agent-connection` project. The CLI connects locally via HTTP or remotely via authenticated AgentCore transport (IAM or Cognito).
+
 ## Deploying Your Strands Agent to Bedrock AgentCore Runtime
 
 <Snippet name="agent/bedrock-deployment" parentHeading="Deploying Your Strands Agent to Bedrock AgentCore Runtime" />

diff --git a/docs/src/content/docs/en/guides/ts-strands-agent.mdx b/docs/src/content/docs/en/guides/ts-strands-agent.mdx
@@ -192,6 +192,20 @@ The generator configures a target named `<your-agent-name>-serve`, which starts
 
 This command uses `tsx --watch` to automatically restart the server when files change. The agent will be available at `http://localhost:8081` (or the assigned port if you have multiple agents).
 
+### Invoke Target
+
+The generator also creates a `<your-agent-name>-invoke` target which provides an interactive CLI for chatting with your agent in the terminal.
+
+To chat with a **locally running** agent (start the agent with `serve` or `serve-local` first):
+
+<NxCommands commands={['run your-project:agent-invoke']} />
+
+To invoke a **deployed** agent on Bedrock AgentCore Runtime, set the `RUNTIME_CONFIG_APP_ID` environment variable. If using Cognito authentication, pass `--accessToken`:
+
+<NxCommands highlights={['xxxx', 'your-access-token']} env={{RUNTIME_CONFIG_APP_ID:"xxxx"}} commands={['run your-project:agent-invoke -- --accessToken your-access-token']} />
+
+The CLI script is generated at `scripts/<your-agent-name>/cli.ts` and uses the type-safe tRPC client from the shared `agent-connection` project. It connects locally via WebSocket or remotely via authenticated AgentCore transport (IAM or Cognito).
+
 ## Deploying Your Strands Agent to Bedrock AgentCore Runtime
 
 <Snippet name="agent/bedrock-deployment" parentHeading="Deploying Your Strands Agent to Bedrock AgentCore Runtime" />

diff --git a/docs/src/content/docs/es/get_started/tutorials/dungeon-game/3.mdx b/docs/src/content/docs/es/get_started/tutorials/dungeon-game/3.mdx
@@ -49,6 +49,16 @@ Dado que el generador de conexiones ya configuró el cliente MCP en el <Link pat
 - Agregar los parámetros `player_name` y `genre` a la función `get_agent`, y
 - Personalizar el prompt del sistema para nuestro juego de aventuras en mazmorras.
 
+### Personalizar el CLI
+
+Dado que nuestro agente acepta un esquema de entrada personalizado (`playerName`, `genre`, `actions`) en lugar del predeterminado (`prompt`, `session_id`), necesitamos actualizar el script CLI generado para pasar estos parámetros.
+
+Actualiza `packages/story/scripts/story-agent/cli.ts`:
+
+<E2EDiff lang="typescript" before="dungeon-adventure/3/cli.ts.old.template" after="dungeon-adventure/3/cli.ts.template" />
+
+Este CLI actualizado acepta los argumentos `--playerName` y `--genre` y envía cada mensaje como una acción en el historial de conversación.
+
 ## Tarea 2: Despliegue y pruebas
 
 ### Compilar el código
@@ -93,11 +103,7 @@ dungeon-adventure-infra-sandbox-Application.UserIdentityUserIdentityUserPoolIdXX
 
 ### Probar tu Agente
 
-Puedes probar tu Agente de dos formas:
-<ul>
-<li>Iniciando una instancia local del servidor del Agente e invocándola con `curl`, o</li>
-<li>Llamando a la API desplegada usando curl con un token JWT.</li>
-</ul>
+Puedes probar tu Agente usando el objetivo de invocación CLI generado. Esto proporciona una interfaz de chat interactiva con tu agente directamente en la terminal.
 
 <Tabs>
   <TabItem label="Local">
@@ -108,94 +114,21 @@ Puedes probar tu Agente de dos formas:
     Usa el valor de salida del despliegue CDK de `RuntimeConfigApplicationId` para la variable de entorno `RUNTIME_CONFIG_APP_ID`, y tu región de AWS desplegada para `AWS_REGION`.
     </Aside>
 
-    :::caution
-    Usa el output `InventoryMcpArn` del despliegue CDK arriba, y especifica tu `AWS_REGION` objetivo.
-    :::
-
-    Una vez que el servidor del Agente esté en ejecución (no verás ninguna salida), invócalo ejecutando el siguiente comando:
+    Una vez que el servidor del Agente esté en ejecución, invócalo usando el CLI en una terminal separada. Pasa `--playerName` y `--genre` para configurar tu aventura, y `--accessToken` si usas autenticación de Cognito:
 
-    ```bash
-    curl -N -X POST http://127.0.0.1:8081/invocations \
-      -d '{"genre":"superhero", "actions":[], "playerName":"UnnamedHero"}' \
-      -H "Content-Type: application/json"
-    ```
+    <NxCommands commands={['run dungeon_adventure.story:agent-invoke -- --playerName UnnamedHero --genre superhero']} />
   </TabItem>
   <TabItem label="Desplegado">
-    Para probar el agente desplegado, necesitarás autenticarte con Cognito y obtener un token JWT. Primero, configura tus variables de entorno:
-
-    ```bash
-    # Establece tu User Pool ID y Client ID de Cognito desde los outputs de CDK
-    export POOL_ID="<UserPoolId from CDK outputs>"
-    export CLIENT_ID="<UserPoolClientId from CDK outputs>"
-    export REGION="<your-region>"
-    ```
-
-    Crea un usuario de prueba y obtén un token de autenticación:
-
-    ```bash
-    # Disable MFA to simplify user creation
-    aws cognito-idp set-user-pool-mfa-config \
-      --mfa-configuration OFF \
-      --user-pool-id $POOL_ID
-
-    # Create User
-    aws cognito-idp admin-create-user \
-      --user-pool-id $POOL_ID \
-      --username "test" \
-      --temporary-password "TempPass123-" \
-      --region $REGION \
-      --message-action SUPPRESS > /dev/null
-
-    # Set Permanent Password (replace with something more secure!)
-    aws cognito-idp admin-set-user-password \
-      --user-pool-id $POOL_ID \
-      --username "test" \
-      --password "PermanentPass123-" \
-      --region $REGION \
-      --permanent > /dev/null
-
-    # Authenticate User and capture ID Token
-    export BEARER_TOKEN=$(aws cognito-idp initiate-auth \
-      --client-id "$CLIENT_ID" \
-      --auth-flow USER_PASSWORD_AUTH \
-      --auth-parameters USERNAME='test',PASSWORD='PermanentPass123-' \
-      --region $REGION \
-      --query "AuthenticationResult.AccessToken" \
-      --output text)
-    ```
-
-    Invoca el agente desplegado usando la URL de Bedrock AgentCore Runtime:
-
-    ```bash
-    # Set the Story Agent ARN from CDK outputs
-    export AGENT_ARN="<StoryAgentArn from CDK outputs>"
-
-    # URL-encode the ARN
-    export ENCODED_ARN=$(echo $AGENT_ARN | sed 's/:/%3A/g' | sed 's/\//%2F/g')
-
-    # Construct the invocation URL
-    export AGENT_URL="https://bedrock-agentcore.$REGION.amazonaws.com/runtimes/$ENCODED_ARN/invocations?qualifier=DEFAULT"
-
-    # Invoke the agent
-    curl -N -X POST "$AGENT_URL" \
-      -H "authorization: Bearer $BEARER_TOKEN" \
-      -H "Content-Type: application/json" \
-      -H "X-Amzn-Bedrock-AgentCore-Runtime-Session-Id: abcdefghijklmnopqrstuvwxyz-123456789" \
-      -d '{"genre":"superhero", "actions":[], "playerName":"UnnamedHero"}'
-    ```
-
-    :::note
-    La codificación URL es necesaria para formatear correctamente el ARN en el endpoint de API de Bedrock AgentCore.
-    :::
+    Para invocar el agente desplegado, establece la variable de entorno `RUNTIME_CONFIG_APP_ID` y proporciona un `--accessToken` para la autenticación de Cognito:
+
+    <NxCommands highlights={['xxxx', 'your-access-token']} env={{RUNTIME_CONFIG_APP_ID:"xxxx"}} commands={['run dungeon_adventure.story:agent-invoke -- --accessToken your-access-token --playerName UnnamedHero --genre superhero']} />
+
+    <Aside type="caution">
+    Usa el valor de salida del despliegue CDK de `RuntimeConfigApplicationId` para la variable de entorno `RUNTIME_CONFIG_APP_ID`. Obtén un token de acceso autenticándote con tu Cognito User Pool.
+    </Aside>
   </TabItem>
 </Tabs>
 
-Si el comando se ejecuta correctamente, deberías comenzar a ver el texto inicial de la historia siendo transmitido como JSON Lines:
-
-```
-{"content":"You are "}
-{"content":"a new superhero "}
-{"content":"in the bustling metropolis of Metro City..."}
-```
+Si el comando se ejecuta correctamente, deberías ver un prompt de chat. Escribe un mensaje y el agente transmitirá su respuesta en tiempo real.
 
 ¡Felicidades! Has construido y desplegado tu primer Agente de Strands en Bedrock AgentCore Runtime. 🎉🎉🎉
diff --git a/docs/src/content/docs/es/guides/py-strands-agent.mdx b/docs/src/content/docs/es/guides/py-strands-agent.mdx
@@ -267,6 +267,20 @@ El generador configura un target llamado `<your-agent-name>-serve` para iniciar
 
 Este comando usa `uv run` para ejecutar tu agente con el [SDK Python de Bedrock AgentCore](https://github.com/aws/bedrock-agentcore-sdk-python).
 
+### Target de Invocación
+
+El generador también crea un target `<your-agent-name>-invoke` que proporciona una CLI interactiva para chatear con tu agente en la terminal.
+
+Para chatear con un agente **ejecutándose localmente** (inicia el agente con `serve` o `serve-local` primero):
+
+<NxCommands commands={['run your-project:agent-invoke']} />
+
+Para invocar un agente **desplegado** en Bedrock AgentCore Runtime, establece la variable de entorno `RUNTIME_CONFIG_APP_ID`. Si usas autenticación Cognito, pasa `--accessToken`:
+
+<NxCommands highlights={['xxxx', 'your-access-token']} env={{RUNTIME_CONFIG_APP_ID:"xxxx"}} commands={['run your-project:agent-invoke -- --accessToken your-access-token']} />
+
+La CLI es un script TypeScript en `scripts/<your-agent-name>/cli.ts` que usa un cliente type-safe generado desde OpenAPI del proyecto compartido `agent-connection`. El generador configura un target `openapi` para extraer la especificación OpenAPI de tu aplicación FastAPI, y genera el cliente TypeScript en el proyecto `agent-connection`. La CLI se conecta localmente vía HTTP o remotamente vía transporte AgentCore autenticado (IAM o Cognito).
+
 ## Desplegando tu Agente Strands a Bedrock AgentCore Runtime
 
 <Snippet name="agent/bedrock-deployment" parentHeading="Desplegando tu Agente Strands a Bedrock AgentCore Runtime" />

diff --git a/docs/src/content/docs/es/guides/ts-strands-agent.mdx b/docs/src/content/docs/es/guides/ts-strands-agent.mdx
@@ -192,6 +192,20 @@ El generador configura un target llamado `<your-agent-name>-serve`, que inicia t
 
 Este comando usa `tsx --watch` para reiniciar automáticamente el servidor cuando cambian los archivos. El agente estará disponible en `http://localhost:8081` (o el puerto asignado si tienes múltiples agentes).
 
+### Target Invoke
+
+El generador también crea un target `<your-agent-name>-invoke` que proporciona una CLI interactiva para chatear con tu agente en la terminal.
+
+Para chatear con un agente **ejecutándose localmente** (inicia el agente con `serve` o `serve-local` primero):
+
+<NxCommands commands={['run your-project:agent-invoke']} />
+
+Para invocar un agente **desplegado** en Bedrock AgentCore Runtime, establece la variable de entorno `RUNTIME_CONFIG_APP_ID`. Si usas autenticación Cognito, pasa `--accessToken`:
+
+<NxCommands highlights={['xxxx', 'your-access-token']} env={{RUNTIME_CONFIG_APP_ID:"xxxx"}} commands={['run your-project:agent-invoke -- --accessToken your-access-token']} />
+
+El script CLI se genera en `scripts/<your-agent-name>/cli.ts` y utiliza el cliente tRPC con seguridad de tipos del proyecto compartido `agent-connection`. Se conecta localmente vía WebSocket o remotamente vía transporte AgentCore autenticado (IAM o Cognito).
+
 ## Desplegar tu Strands Agent en Bedrock AgentCore Runtime
 
 <Snippet name="agent/bedrock-deployment" parentHeading="Desplegar tu Strands Agent en Bedrock AgentCore Runtime" />