Skip to main content
Get Workshop Cloud Chat running on your local machine and send your first message to a Bedrock agent in just a few minutes.

​
Prerequisites

Before you begin, make sure you have:
  • Node.js 18+ installed on your machine
  • An AWS account with access to Amazon Bedrock
  • AWS CLI configured (optional, but recommended)
  • A Bedrock Agent already created in your AWS account
  • An S3 bucket for document storage (optional, for knowledge base features)
If you don’t have a Bedrock Agent yet, you’ll need to create one in the AWS Console before proceeding. Visit the AWS Bedrock documentation to learn how to create an agent.

​
Installation

1

Clone the repository

Clone the Workshop Cloud Chat repository to your local machine:
git clone <your-repository-url>
cd workshop-cloud-chat
2

Install dependencies

Install the required npm packages using your preferred package manager:
npm install
The application uses the following key dependencies:
  • astro - Web framework for building the UI
  • @aws-sdk/client-bedrock-agent-runtime - For interacting with Bedrock agents
  • @aws-sdk/client-bedrock-agent - For managing knowledge base sync
  • @aws-sdk/client-s3 - For document uploads
3

Start the development server

Launch the application in development mode:
npm run dev
You should see output similar to:
🚀 astro v5.2.0 started in 245ms

  ┃ Local    http://localhost:4321/
  ┃ Network  use --host to expose
The application runs on port 4321 by default. If this port is already in use, Astro will automatically select a different port.

​
AWS Configuration

Before you can chat with your Bedrock agent, you need to configure your AWS credentials and agent settings.
1

Open the application

Navigate to http://localhost:4321 in your web browser. You’ll see the Workshop Cloud Chat interface with configuration options.
2

Configure AWS credentials and Bedrock agent

Click the ⚙ settings icon next to “Asistente Bedrock · Chat con Agente” to open the configuration dialog.Fill in the following required fields:AWS Credentials:
  • AWS Access Key ID - Your AWS access key (required)
  • AWS Secret Access Key - Your AWS secret key (required)
  • AWS Session Token - Only needed if using temporary credentials (optional)
Bedrock Agent Settings:
  • Region - The AWS region where your agent is deployed (e.g., us-east-1)
  • Agent ID - Your Bedrock agent’s unique identifier (e.g., XXXXXXXXXX)
  • Agent Alias ID - The agent alias ID (e.g., TSTALIASID)
  • Session ID - Leave empty to auto-generate (optional)
Never commit your AWS credentials to version control. The application stores credentials in browser localStorage for convenience during development.
Example configuration:
{
  "region": "us-east-1",
  "agentId": "ABC123XYZ456",
  "agentAliasId": "TSTALIASID",
  "accessKeyId": "AKIAIOSFODNN7EXAMPLE",
  "secretAccessKey": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
}
Click Guardar (Save) to apply your configuration.
3

Verify configuration

After saving, check the “Resumen de configuración” panel on the right side:
  • AWS: Should show “credenciales configuradas (YOUR_ACCESS_KEY_ID)”
  • Agente: Should display your region, agent ID, and alias
  • S3: “sin configurar” (unless you’ve configured S3)
  • KB Sync: “sin configurar” (unless you’ve configured knowledge base sync)

​
Your First Chat Interaction

Now that everything is configured, let’s send your first message to the Bedrock agent.
1

Enter your message

In the chat input field at the bottom of the main panel, type a message such as:
Hello! Can you help me understand what you can do?
2

Send the message

Click the Enviar (Send) button or press Enter to send your message.The application will:
  1. Display your message in the chat window with a 👤 user icon
  2. Send an InvokeAgentCommand to AWS Bedrock with your message:
const command = new InvokeAgentCommand({
  agentId: body.agentId,
  agentAliasId: body.agentAliasId,
  sessionId,
  inputText: latestUserMessage.content
});
  1. Stream the response back from the agent
  2. Display the agent’s reply with a 🤖 assistant icon
3

View the response

The agent’s response will appear in the chat window. Each message shows:
  • The role (Tú for user, Agente for assistant)
  • An emoji indicator (👤 or 🤖)
  • The message content
4

Enable debug mode (optional)

To see technical details about the API calls, check the “Mostrar diagnóstico técnico” checkbox below the message input.This displays the raw response payload, including:
  • The agent’s reply text
  • Session ID for conversation tracking
  • Any errors that occurred
{
  "reply": "I'd be happy to help! I can assist you with...",
  "sessionId": "550e8400-e29b-41d4-a716-446655440000"
}

​
Understanding Sessions

Workshop Cloud Chat uses session IDs to maintain conversation context with your Bedrock agent:
  • Auto-generated sessions: By default, a new session ID is created each time you reload the page
  • Session persistence: Within a session, the agent remembers previous messages
  • Custom sessions: You can specify a session ID in the configuration to resume a previous conversation
From the API implementation in src/pages/api/chat.ts:51: 
const sessionId = body.sessionId?.trim() || crypto.randomUUID();
Sessions are managed by AWS Bedrock. Once you close the application, session history is maintained by AWS but not in the local application state.

​
Next Steps

Congratulations! You’ve successfully set up Workshop Cloud Chat and sent your first message. Here’s what to explore next:

Upload Documents

Learn how to upload PDF documents to S3 for your knowledge base

Knowledge Base Sync

Configure and run knowledge base synchronization jobs

Environment Variables

Set up environment variables for production deployments

Deploy to AWS

Deploy your application to AWS Amplify

​
Troubleshooting

​
Chat section is disabled

If the chat section shows “Configura chat y credenciales para habilitar esta sección,” make sure:
  • All required fields in the configuration dialog are filled
  • Your AWS credentials are valid
  • Your Bedrock agent exists in the specified region

​
Authentication errors

Error: The security token included in the request is invalid
This usually means:
  • Your AWS credentials are incorrect or expired
  • You need to include a session token if using temporary credentials
  • The IAM user/role doesn’t have permission to invoke Bedrock agents
Required IAM permissions: 
{
  "Version": "2012-10-17",
  "Statement": [{
    "Effect": "Allow",
    "Action": [
      "bedrock:InvokeAgent",
      "bedrock:InvokeAgentWithResponseStream"
    ],
    "Resource": "*"
  }]
}

​
Agent not responding

If messages send but you receive no response:
  • Check that your Agent ID and Alias ID are correct
  • Verify the agent is deployed and active in the AWS Console
  • Enable debug mode to see the raw API response
  • Check your agent’s CloudWatch logs for errors
For more detailed troubleshooting, visit the AWS Bedrock console and check your agent’s execution logs.

Build docs developers (and LLMs) love

Get started for freeTalk to us