Get started with the Amazon Bedrock AgentCore starter toolkit in TypeScript

This tutorial shows you how to use the Amazon Bedrock AgentCore starter toolkit to deploy a TypeScript agent to an Amazon Bedrock AgentCore Runtime.

The starter toolkit is a Command Line Interface (CLI) toolkit that you can use to deploy AI agents to an Amazon Bedrock AgentCore Runtime. This tutorial shows you how to create and deploy a TypeScript agent using the bedrock-agentcore SDK.

For information about the HTTP protocol that the agent uses, see HTTP protocol contract.

Prerequisites

Before you start, make sure you have:

Step 1: Set up project and install dependencies

Create a project folder and initialize your TypeScript project:

mkdir agentcore-typescript-quickstart
cd agentcore-typescript-quickstart
npm init -y

Install the required packages:

npm install bedrock-agentcore @strands-agents/sdk @opentelemetry/auto-instrumentations-node
npm install --save-dev typescript @types/node tsx

Install the starter toolkit CLI (requires Python):

pip install --upgrade bedrock-agentcore-starter-toolkit

Verify installation:

agentcore --help

Step 2: Create your agent project

Create a tsconfig.json file with the following content:

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "outDir": "./dist",
    "rootDir": ".",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "declaration": true
  },
  "include": ["*.ts"],
  "exclude": ["node_modules", "dist"]
}

Update your package.json to add the required configuration:

{
  "name": "agentcore-typescript-quickstart",
  "version": "1.0.0",
  "type": "module",
  "main": "dist/agent.js",
  "scripts": {
    "build": "tsc",
    "start": "node dist/agent.js",
    "dev": "npx tsx --watch agent.ts"
  },
  "engines": {
    "node": ">=20.0.0"
  },
  "dependencies": {
    "bedrock-agentcore": "^0.2.0",
    "@strands-agents/sdk": "^0.1.5",
    "@opentelemetry/auto-instrumentations-node": "^0.56.0"
  },
  "devDependencies": {
    "@types/node": "^22.0.0",
    "typescript": "^5.5.0",
    "tsx": "^4.0.0"
  }
}

Create an agent.ts file with your agent code:

import { BedrockAgentCoreApp } from 'bedrock-agentcore/runtime';
import { Agent } from '@strands-agents/sdk';

// Create a Strands agent
const agent = new Agent();

// Create and start the server
const app = new BedrockAgentCoreApp({
  invocationHandler: {
    process: async (payload, context) => {
      const prompt = (payload as { prompt?: string }).prompt ?? 'Hello!';
      console.log(`Session ${context.sessionId} - Received prompt:`, prompt);
      
      const result = await agent.invoke(prompt);
      return result;
    }
  }
});

app.run();

Build your TypeScript project:

npm run build

Step 3: Configure your agent

Run the agentcore configure command to set up your agent for deployment:

agentcore configure --entrypoint agent.ts

The command will:

Step 4: Test your agent locally

Before deploying to AWS, test your agent locally using the development server:

agentcore dev

In a separate terminal, test your agent:

agentcore invoke --dev '{"prompt": "Hello!"}'

Step 5: Enable observability for your agent

Amazon Bedrock AgentCore Observability helps you trace, debug, and monitor agents that you host in Amazon Bedrock AgentCore Runtime. First enable CloudWatch Transaction Search by following the instructions at Enabling Amazon Bedrock AgentCore runtime observability. To observe your agent, see View observability data for your Amazon Bedrock AgentCore agents.

Step 6: Deploy to Amazon Bedrock AgentCore Runtime

Deploy your agent to AgentCore Runtime:

agentcore deploy

This command:

In the output from agentcore deploy note the following:

If the deployment fails check for common issues.

Step 7: Test your deployed agent

Test your deployed agent:

agentcore invoke '{"prompt": "tell me a joke"}'

If you see a response, your agent is now running in an Amazon Bedrock AgentCore Runtime and can be invoked. If not, check for common issues.

Step 8: Invoke your agent programmatically

You can invoke the agent using the AWS SDK InvokeAgentRuntime operation. To call InvokeAgentRuntime, you need the ARN of the agent that you noted in Step 6. You can also get the ARN from the bedrock_agentcore: section of the .bedrock_agentcore.yaml (hidden) file that the toolkit creates.

Create a file named invoke-agent.ts and add the following code:

import { 
  BedrockAgentCoreClient, 
  InvokeAgentRuntimeCommand 
} from '@aws-sdk/client-bedrock-agentcore';
import { randomUUID } from 'crypto';

const agentArn = 'Agent ARN';
const prompt = 'Tell me a joke';

// Initialize the Amazon Bedrock AgentCore client
const client = new BedrockAgentCoreClient({ region: 'us-west-2' });

// Invoke the agent
const command = new InvokeAgentRuntimeCommand({
  agentRuntimeArn: agentArn,
  runtimeSessionId: randomUUID(),
  payload: JSON.stringify({ prompt }),
  contentType: 'application/json',
  qualifier: 'DEFAULT',
});

const response = await client.send(command);
const textResponse = await response.response?.transformToString();

console.log('Response:', textResponse);

Run the code with the following command:

npx tsx invoke-agent.ts

If successful, you should see a response from your agent. If the call fails, check the logs that you noted in Step 6: Deploy to Amazon Bedrock AgentCore Runtime.

Step 9: Clean up

If you no longer want to host the agent in the AgentCore Runtime, use the destroy command to delete the AWS resources that the starter toolkit created for you.

agentcore destroy

Find your resources

After deployment, view your resources in the AWS Console:

Common issues and solutions

Common issues and solutions when getting started with the Amazon Bedrock AgentCore starter toolkit for TypeScript. For more troubleshooting information, see Troubleshoot Amazon Bedrock AgentCore Runtime.

Advanced: Streaming responses

Your TypeScript agent can return streaming responses using async generators. This is useful for long-running operations or when you want to provide incremental updates to the client:

import { BedrockAgentCoreApp } from 'bedrock-agentcore/runtime';

// Streaming handler using async generator
const streamingHandler = async function* (request: unknown, context: { sessionId: string }) {
  yield { event: 'start', sessionId: context.sessionId };

  // Simulate processing steps
  for (let i = 0; i < 5; i++) {
    yield {
      event: 'progress',
      step: i + 1,
      data: `Processing step ${i + 1}`,
    };
  }

  yield { event: 'complete', result: 'done' };
};

const app = new BedrockAgentCoreApp({
  invocationHandler: { process: streamingHandler },
});

app.run();

The server automatically handles streaming responses using Server-Sent Events (SSE).