Get started with the AgentCore CLI in TypeScript

This tutorial shows you how to use the AgentCore CLI (agentcore-cli) to deploy a TypeScript agent to an Amazon Bedrock AgentCore Runtime.

The AgentCore CLI is a command-line tool that you can use to create, develop, and 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: Install the AgentCore CLI and create a project

Install the AgentCore CLI globally:

npm install -g @aws/agentcore

Verify installation:

agentcore --help

To deploy a TypeScript agent, use container-based deployment. Create a project without a default agent. You will add a TypeScript container agent in the next step.

This command creates a project directory with the following structure:

MyTsAgent/
  agentcore/
    agentcore.json
    aws-targets.json

Change into the project directory:

cd MyTsAgent

Step 2: Create your TypeScript agent

This tutorial uses the Strands Agents framework, which is currently the supported framework for TypeScript agents deployed to AgentCore Runtime.

Add a TypeScript agent to your project using the bring-your-own-code (BYO) workflow with container-based deployment:

This command registers a TypeScript agent in agentcore/agentcore.json and creates a code directory for your agent at app/TsAgent/.

Initialize the TypeScript project inside the agent code directory:

cd app/TsAgent
npm init -y

Install the required packages:

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

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": "ts-agent",
  "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();

Create a Dockerfile in the app/TsAgent/ directory. Container-based deployment uses a multi-stage Docker build: the builder stage compiles TypeScript to JavaScript, and the production stage runs only the compiled output. The image runs as a non-root user for security, and exposes port 8080 (HTTP), port 8000 (MCP), and port 9000 (A2A). OpenTelemetry instrumentation is included automatically at startup.

FROM node:20-slim AS builder

WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

FROM node:20-slim
WORKDIR /app
COPY --from=builder /app/dist ./dist
COPY --from=builder /app/node_modules ./node_modules
COPY --from=builder /app/package*.json ./

RUN useradd -m -u 1000 bedrock_agentcore
USER bedrock_agentcore

EXPOSE 8080 8000 9000
CMD ["node", "--require", "@opentelemetry/auto-instrumentations-node/register", "dist/agent.js"]

Create a .dockerignore file to exclude unnecessary files from the Docker build context:

node_modules
dist
.git
*.log

Build locally to verify that your TypeScript code compiles. The container build will also run this step during deployment.

npm run build

Return to the project root directory:

cd ../..

Step 3: Review your project configuration

The agentcore create and agentcore add agent commands generated the configuration files for your project. Open agentcore/agentcore.json to review the configuration:

{
  "name": "MyTsAgent",
  "version": 1,
  "agents": [
    {
      "type": "AgentCoreRuntime",
      "name": "TsAgent",
      "build": "Container",
      "entrypoint": "main.py",
      "codeLocation": "app/TsAgent/",
      "runtimeVersion": "PYTHON_3_12",
      "protocol": "HTTP",
      "networkMode": "PUBLIC"
    }
  ]
}

You can also review your deployment target in agentcore/aws-targets.json:

[]

Before deploying, you must configure at least one deployment target. Open agentcore/aws-targets.json and add your AWS account and Region:

[
  {
    "name": "default",
    "account": "123456789012",
    "region": "us-west-2"
  }
]

Replace 123456789012 with your AWS account ID and update the Region as needed.

To validate that your configuration is correct, run:

agentcore validate

Step 4: Test your agent locally

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

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.

After deploying your agent, you can stream logs and view traces using the AgentCore CLI:

agentcore logs --runtime TsAgent --since 1h

agentcore traces list --runtime TsAgent

Step 6: Deploy to Amazon Bedrock AgentCore Runtime

Deploy your agent to AgentCore Runtime:

You can preview the deployment before confirming by using the --plan flag:

agentcore deploy --plan

The agentcore deploy command:

In the output from agentcore deploy note the following:

To check the status of your deployed resources, run:

If the deployment fails check for common issues.

Step 7: Test your deployed agent

Test your deployed agent:

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 find the ARN by running agentcore status.

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: Stop session or clean up

To stop the running session before the configurable IdleRuntimeSessionTimeout (defaulted at 15 minutes) and save on any potential runaway costs, execute: StopRuntimeSession

Create a file named stop-runtime-session.ts with the following content:

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

const client = new BedrockAgentCoreClient({ region: 'us-west-2' });
const agentArn = 'Agent ARN';
const command = new StopRuntimeSessionCommand({
  agentRuntimeArn: agentArn,
  runtimeSessionId: randomUUID(),
  qualifier: 'DEFAULT',
});

const response = await client.send(command);
console.log('Session stopped:', response);
            

Run the code with the following command:

npx tsx stop-runtime-session.ts

If you no longer want to host the agent in the AgentCore Runtime, remove all resources from your project configuration and then deploy to tear down the AWS resources:

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 AgentCore CLI 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).