TypeScript Agent

ツールを使用してAIエージェントを構築するための TypeScript Strands Agent を生成し、オプションで Amazon Bedrock AgentCore Runtime にデプロイします。デフォルトでは、ジェネレーターは WebSocket 上の tRPC を使用して、リアルタイムで型安全な通信のために AgentCore の双方向ストリーミングサポートを活用します。または、他の A2A 互換エージェントとの相互運用性のために Agent-to-Agent (A2A) プロトコルを選択するか、CopilotKit を介した直接的なフロントエンド統合のために AG-UI プロトコルを選択できます。

Strands とは？

Strands は、AIエージェントを構築するための軽量フレームワークです。主な機能は以下の通りです：

軽量でカスタマイズ可能: 邪魔にならないシンプルなエージェントループ
本番環境対応: 完全な可観測性、トレーシング、スケールのためのデプロイオプション
モデルとプロバイダーに依存しない: さまざまなプロバイダーの多くの異なるモデルをサポート
コミュニティ駆動のツール: コミュニティが貢献する強力なツールセット
マルチエージェントサポート: エージェントチームや自律エージェントなどの高度な技術
柔軟な対話モード: 会話型、ストリーミング、非ストリーミングのサポート

使用方法

エージェントの生成

TypeScript Agent は2つの方法で生成できます：

CLI
VSCode

pnpm nx g @aws/nx-plugin:ts#agent

yarn nx g @aws/nx-plugin:ts#agent

npx nx g @aws/nx-plugin:ts#agent

bunx nx g @aws/nx-plugin:ts#agent

変更されるファイルを確認するためにドライランを実行することもできます

pnpm nx g @aws/nx-plugin:ts#agent --dry-run

yarn nx g @aws/nx-plugin:ts#agent --dry-run

npx nx g @aws/nx-plugin:ts#agent --dry-run

bunx nx g @aws/nx-plugin:ts#agent --dry-run

インストール Nx Console VSCode Plugin まだインストールしていない場合
VSCodeでNxコンソールを開く
クリック Generate (UI) "Common Nx Commands"セクションで
検索 @aws/nx-plugin - ts#agent
必須パラメータを入力
クリック Generate

オプション

パラメータ	型	デフォルト	説明
project 必須	string	-	Agentを追加するプロジェクト
framework	strands	strands	使用するエージェントSDK。
name	string	-	Agentの名前（デフォルト: agent）
auth	iam \| cognito	iam	エージェントとの認証に使用する方法。infraが設定されている場合にのみ適用されます（infraがnoneの場合は無視されます）。
protocol	http \| a2a \| ag-ui	http	Agentのサーバープロトコル。HTTPはtRPC/WebSocketサーバーを公開します。A2AはAgent-to-Agentプロトコルサーバーを公開します。AG-UIはCopilotKitとのフロントエンド直接統合のためのAG-UIプロトコルサーバーを公開します。
iac	inherit \| cdk \| terraform	inherit	優先するIaCプロバイダー。デフォルトでは、初期選択から継承されます。
infra	agentcore \| none	agentcore	エージェントをホストするインフラストラクチャのタイプ。
session	s3 \| in-memory	s3	エージェントのセッションを永続化するために使用されるストレージ。
preferInstallDependencies	boolean	true	ジェネレーター実行後に依存関係のインストールを優先するかどうか。複数のジェネレーターをバッチ処理する際にインストールを延期する場合はfalseに設定します（後続のジェネレーターがNxプロジェクトグラフを計算できるよう、必要に応じてインストールは実行されます）。最後に一度だけインストールします。

ジェネレーターの出力

ジェネレーターは、既存の TypeScript プロジェクトに以下のファイルを追加します。生成されるファイルは、選択した protocol によって異なります：

HTTP プロトコル（デフォルト）

Directoryyour-project/
- Directorysrc/
  - Directoryagent/ (or custom name if specified)
    index.ts Entry point for Bedrock AgentCore Runtime (tRPC/WebSocket server)
    init.ts tRPC initialization
    router.ts tRPC router with agent procedures
    agent.ts Main agent definition with sample tools
    session.ts Resolves the SessionManager used to persist conversation state
    client.ts Vended client for invoking your agent
    agent-core-trpc-client.ts Client factory for connecting to agents on AgentCore Runtime
    Dockerfile Entry point for hosting your agent (excluded when infra is set to None)
- package.json Updated with Strands dependencies
- project.json Updated with agent serve targets

A2A プロトコル

エントリーポイントは tRPC の代わりに Strands A2A Express Server を使用します：

Directoryyour-project/
- Directorysrc/
  - Directoryagent/ (or custom name if specified)
    index.ts A2A Express server entry point
    agent.ts Main agent definition with sample tools
    session.ts Resolves the SessionManager used to persist conversation state
    Dockerfile Entry point for hosting your agent (excluded when infra is set to None)
- package.json Updated with Strands and Express dependencies
- project.json Updated with agent serve targets

AG-UI プロトコル

エントリーポイントは @ag-ui/aws-strands を使用して、CopilotKit と互換性のある AG-UI プロトコル（POST 上の SSE）を介してエージェントを公開します：

Directoryyour-project/
- Directorysrc/
  - Directoryagent/ (or custom name if specified)
    index.ts AG-UI server entry point (Express + SSE)
    agent.ts Main agent definition with sample tools
    session.ts Resolves the SessionManager used to persist conversation state
    Dockerfile Entry point for hosting your agent (excluded when infra is set to None)
- package.json Updated with Strands and AG-UI dependencies
- project.json Updated with agent serve targets

インフラストラクチャ

このジェネレーターは、選択した iac に基づいてインフラストラクチャをコードとして提供するため、関連する CDK コンストラクトまたは Terraform モジュールを含む packages/common にプロジェクトを作成します。

共通のインフラストラクチャコードプロジェクトは、次のように構成されています：

CDK
Terraform

Directorypackages/common/constructs
- Directorysrc
  - Directoryapp/ プロジェクト/ジェネレーター固有のインフラストラクチャ用のコンストラクト
    …
  - Directorycore/ app 内のコンストラクトによって再利用される汎用コンストラクト
    …
  - index.ts app からコンストラクトをエクスポートするエントリーポイント
- project.json プロジェクトのビルドターゲットと設定

Directorypackages/common/terraform
- Directorysrc
  - Directoryapp/ プロジェクト/ジェネレーター固有のインフラストラクチャ用の Terraform モジュール
    …
  - Directorycore/ app 内のモジュールによって再利用される汎用モジュール
    …
- project.json プロジェクトのビルドターゲットと設定

エージェントをデプロイするために、以下のファイルが生成されます：

CDK
Terraform

Directorypackages/common/constructs/src
- Directoryapp
  - Directoryagents
    Directory<project-name>
    <project-name>.ts CDK construct for deploying your agent

infra に none を選択した場合、CDK コンストラクトや Terraform モジュールは生成されません。エージェントはローカルでのみ実行できます。このモードでは、認証するホストされたエンドポイントがないため、auth オプションは無視されます。

Bedrock AgentCore Runtimeにデプロイされると、エージェントはコンテナイメージにビルドされ、Amazon ECRにプッシュされ、AgentCore Runtimeで実行されます。クライアントはAgentCore Runtimeデータプレーンエンドポイントを呼び出し、リクエストをエージェントに転送します。エージェントはモデル推論のためにAmazon Bedrockを呼び出し、ツール、MCPサーバー、またはダウンストリームAPIを呼び出すことができます。

infra: noneの場合、AWSインフラストラクチャは生成されません。エージェントはローカルプロセスとして実行され、モデル推論のためにAmazon Bedrockを呼び出します。

エージェントの操作

プロトコル

エージェントのサーバープロトコルは、通信方法を決定します。以下から選択できます：

HTTP（デフォルト）: リアルタイムで型安全な通信のために WebSocket 上の tRPC を使用します。カスタムクライアント統合とエージェントの API のきめ細かい制御に最適です。
A2A: 標準化されたエージェント間通信のために Agent-to-Agent (A2A) プロトコルを使用します。エージェントが他の A2A 互換エージェントによって検出可能で呼び出し可能である必要がある場合に最適です。
AG-UI: @ag-ui/aws-strands を介した AG-UI プロトコル（POST 上の SSE）を使用して、CopilotKit との直接的なフロントエンド統合を行います。ストリーミング、ツール呼び出しの可視化、状態管理を備えたリッチなチャット UI が必要な場合に最適です。

プロトコルは CDK/Terraform インフラストラクチャで設定され、アプリケーションコードはそれに応じて生成されます。

WebSocket 上の tRPC（HTTP プロトコル）

TypeScript Agent は WebSocket 上の tRPC を使用し、AgentCore の双方向ストリーミングサポートを活用して、クライアントとエージェント間のリアルタイムで型安全な通信を可能にします。

tRPC は WebSocket 上で Query、Mutation、Subscription プロシージャをサポートしているため、任意の数のプロシージャを定義できます。デフォルトでは、router.ts に invoke という名前の単一のサブスクリプションプロシージャが定義されています。

ツールの追加

ツールは、AIエージェントがアクションを実行するために呼び出すことができる関数です。agent.ts ファイルに新しいツールを追加できます：

import { Agent, tool } from '@strands-agents/sdk';
import { z } from 'zod';

const letterCounter = tool({
  name: 'letter_counter',
  description: 'Count occurrences of a specific letter in a word',
  inputSchema: z.object({
    word: z.string().describe('The input word to search in'),
    letter: z.string().length(1).describe('The specific letter to count'),
  }),
  callback: (input) => {
    const { word, letter } = input;
    const count = word.toLowerCase().split(letter.toLowerCase()).length - 1;
    return `The letter '${letter}' appears ${count} time(s) in '${word}'`;
  },
});

// Add tools to your agent
export const getAgent = async () => {
  return new Agent({
    systemPrompt: 'You are a helpful assistant with access to various tools.',
    tools: [letterCounter],
  });
};

Strands フレームワークは以下を自動的に処理します：

Zod スキーマを使用した入力検証
ツール呼び出しのための JSON スキーマ生成
エラー処理とレスポンスのフォーマット

モデル設定

デフォルトでは、Strands エージェントは Claude 4 Sonnet を使用しますが、モデルプロバイダー間で簡単に切り替えることができます：

import { Agent } from '@strands-agents/sdk';
import { BedrockModel } from '@strands-agents/sdk/models/bedrock';
import { OpenAIModel } from '@strands-agents/sdk/models/openai';

// Use Bedrock
const bedrockModel = new BedrockModel({
  modelId: 'anthropic.claude-sonnet-4-20250514-v1:0',
});
let agent = new Agent({ model: bedrockModel });
let response = await agent.invoke('What can you help me with?');

// Alternatively, use OpenAI by just switching model provider
const openaiModel = new OpenAIModel({
  apiKey: process.env.OPENAI_API_KEY,
  modelId: 'gpt-4o',
});
agent = new Agent({ model: openaiModel });
response = await agent.invoke('What can you help me with?');

詳細な設定オプションについては、Strands のモデルプロバイダーに関するドキュメントを参照してください。

MCP サーバーの利用

Strands エージェントに MCP サーバーからツールを追加できます。

py#mcp-server または ts#mcp-server ジェネレーターを使用して作成した MCP サーバーを利用する場合は、connection ジェネレーターを使用できます。

CLI
VSCode

pnpm nx g @aws/nx-plugin:connection

yarn nx g @aws/nx-plugin:connection

npx nx g @aws/nx-plugin:connection

bunx nx g @aws/nx-plugin:connection

変更されるファイルを確認するためにドライランを実行することもできます

pnpm nx g @aws/nx-plugin:connection --dry-run

yarn nx g @aws/nx-plugin:connection --dry-run

npx nx g @aws/nx-plugin:connection --dry-run

bunx nx g @aws/nx-plugin:connection --dry-run

インストール Nx Console VSCode Plugin まだインストールしていない場合
VSCodeでNxコンソールを開く
クリック Generate (UI) "Common Nx Commands"セクションで
検索 @aws/nx-plugin - connection
必須パラメータを入力
クリック Generate

接続の設定方法の詳細については、connection ジェネレーターガイドを参照してください。

他の MCP サーバーについては、Strands ドキュメントを参照してください。

その他

Strands エージェントの作成に関するより詳細なガイドについては、Strands ドキュメントを参照してください。

A2A サーバー（A2A プロトコル）

生成された index.ts は、Strands A2A Express Server を Express アプリにマウントするため、生成されたエージェントは A2A プロトコルエンドポイントと /ping ヘルスチェックを公開します。AgentCore にデプロイされると、エントリーポイントは AppConfig からランタイムのパブリック ARN を解決し、エージェントカードでアドバタイズします。

ほとんどのユーザーはこのファイルを変更する必要はありません。ツールやシステムプロンプトを変更するには agent.ts を編集してください。A2A エージェントはポート 9000 でリッスンします（HTTP の 8080 に対して）。生成された Dockerfile とインフラストラクチャはすでにこれに対応して設定されています。

AG-UI サーバー（AG-UI プロトコル）

生成された index.ts は、Strands Agent を @ag-ui/aws-strands の StrandsAgent でラップし、createStrandsApp() を介して Express アプリを作成します。結果のアプリは、Server-Sent Events（SSE）上で AG-UI イベントをストリーミングする単一の POST エンドポイントと、AgentCore ランタイムヘルスチェック用の /ping を公開します。

AG-UI エージェントは、フロントエンドから直接利用されるように設計されています。connection ジェネレーターを使用して、CopilotKit プロバイダーと AG-UI HttpAgent クライアントを使用して React ウェブサイトをエージェントに接続します。

ほとんどのユーザーは index.ts を変更する必要はありません。ツールやシステムプロンプトを変更するには agent.ts を編集してください。AG-UI エージェントはポート 8080 でリッスンします（HTTP と同じ）。生成された Dockerfile とインフラストラクチャはすでにこれに対応して設定されています。

エージェントの実行

ローカル開発

エージェント（およびそれに接続されているすべて）をローカルで実行するには、プロジェクトの dev ターゲットを使用します：

pnpm nx dev your-project

yarn nx dev your-project

npx nx dev your-project

bunx nx dev your-project

プロジェクトに複数のコンポーネント（エージェント、MCP サーバーなど）を追加している場合、これによりすべてが起動します。このエージェントのみを実行するには、その <your-agent-name>-dev ターゲットを指定します：

pnpm nx agent-dev your-project

yarn nx agent-dev your-project

npx nx agent-dev your-project

bunx nx agent-dev your-project

これは tsx --watch を使用して、ファイルが変更されたときにサーバーを自動的に再起動します。エージェントは http://localhost:8081（または複数のエージェントがある場合は割り当てられたポート）で利用可能になります。

エージェントとのチャット

ジェネレーターは、エージェントとの対話型ターミナルチャットに入る <your-agent-name>-chat Nx ターゲットを設定します。

チャットターゲットはスタンドアロンで実行されます。デフォルトではローカルで実行中のエージェントに接続するため、まずエージェントの <your-agent-name>-dev ターゲットを（別のターミナルで）起動してください：

pnpm nx agent-dev your-project

yarn nx agent-dev your-project

npx nx agent-dev your-project

bunx nx agent-dev your-project

次に、別のターミナルでチャットを開始します：

pnpm nx run your-project:agent-chat

yarn nx run your-project:agent-chat

npx nx run your-project:agent-chat

bunx nx run your-project:agent-chat

ジェネレーターは、すべてのプロトコルに対して scripts/<your-agent-name>/chat.ts を出力します。エージェントの入力形状が進化するにつれて、これをカスタマイズできます。デフォルトではローカルエージェントに接続しますが、RUNTIME_CONFIG_APP_ID が設定されている場合はデプロイされたエージェントに接続します（以下のデプロイされたエージェントとのチャットを参照）。

デプロイされたエージェントとのチャット

Bedrock AgentCore にデプロイされたエージェントとチャットするには、RUNTIME_CONFIG_APP_ID 環境変数をデプロイの AppConfig アプリケーション ID（デプロイされたスタックによって RuntimeConfigApplicationId として出力される）に設定します。チャットスクリプトは、ランタイム設定からエージェントのランタイム ARN を解決し、デプロイされたエンドポイントに接続します：

IAM
Cognito

IAM 認証されたエージェントの場合、リクエストはデフォルトの AWS 認証情報を使用して SigV4 で署名されます。環境にランタイムを呼び出す権限を持つ AWS 認証情報があることを確認してください：

RUNTIME_CONFIG_APP_ID=<app-id> pnpm nx run your-project:agent-chat

RUNTIME_CONFIG_APP_ID=<app-id> yarn nx run your-project:agent-chat

RUNTIME_CONFIG_APP_ID=<app-id> npx nx run your-project:agent-chat

RUNTIME_CONFIG_APP_ID=<app-id> bunx nx run your-project:agent-chat

Cognito 認証されたエージェントの場合、AGENT_ACCESS_TOKEN 環境変数を介して Cognito アクセストークンを提供します。これはベアラートークンとして送信されます：

RUNTIME_CONFIG_APP_ID=<app-id> AGENT_ACCESS_TOKEN=<access-token> pnpm nx run your-project:agent-chat

RUNTIME_CONFIG_APP_ID=<app-id> AGENT_ACCESS_TOKEN=<access-token> yarn nx run your-project:agent-chat

RUNTIME_CONFIG_APP_ID=<app-id> AGENT_ACCESS_TOKEN=<access-token> npx nx run your-project:agent-chat

RUNTIME_CONFIG_APP_ID=<app-id> AGENT_ACCESS_TOKEN=<access-token> bunx nx run your-project:agent-chat

AWS CLI の cognito-idp admin-initiate-auth コマンドを使用してアクセストークンを取得できます。例：

aws cognito-idp admin-initiate-auth \
  --user-pool-id <user-pool-id> \
  --client-id <user-pool-client-id> \
  --auth-flow ADMIN_NO_SRP_AUTH \
  --auth-parameters USERNAME=<username>,PASSWORD=<password> \
  --query 'AuthenticationResult.AccessToken' \
  --output text

エージェントを Bedrock AgentCore Runtime にデプロイする

Infrastructure as Code

infra に agentcore を選択した場合、関連する CDK または Terraform インフラストラクチャが生成され、これを使用して Agent を Amazon Bedrock AgentCore Runtime にデプロイできます。

CDK
Terraform

Agent 用の CDK コンストラクトが生成されます。名前はジェネレーター実行時に選択した name に基づくか、デフォルトでは <ProjectName>Agent となります。

この CDK コンストラクトを CDK アプリケーションで使用できます:

import { MyProjectAgent } from '@my-scope/common-constructs';

export class ExampleStack extends Stack {
  constructor(scope: Construct, id: string) {
    new MyProjectAgent(this, 'MyProjectAgent');
  }
}

Terraform モジュールが生成されます。名前はジェネレーター実行時に選択した name に基づくか、デフォルトでは <ProjectName>-agent となります。

共有の runtime_config_appconfig モジュールの出力を agent モジュールに渡します:

module "my_project_agent" {
  source = "../../common/terraform/src/app/agents/my-project-agent"

  appconfig_application_id  = module.runtime_config_appconfig.application_id
  appconfig_application_arn = module.runtime_config_appconfig.application_arn
}

Agent をビルドおよびデプロイするには Docker が必要です。次のようなエラーを回避するために、Docker がインストールされ起動していることを確認してください:

ERROR: Cannot connect to the Docker daemon at unix://path/to/docker.sock.

認証

ジェネレーターは Agent の認証を設定するための auth オプションを提供します。エージェント生成時に IAM（デフォルト）または Cognito 認証を選択できます。

IAM

デフォルトでは、Agent は IAM 認証を使用して保護されます。引数なしでデプロイするだけです:

CDK
Terraform

import { MyProjectAgent } from '@my-scope/common-constructs';

export class ExampleStack extends Stack {
  constructor(scope: Construct, id: string) {
    new MyProjectAgent(this, 'MyProjectAgent');
  }
}

grantInvokeAccess メソッドを使用して、Bedrock AgentCore Runtime 上のエージェントを呼び出すアクセス権を付与できます。例:

import { MyProjectAgent } from '@my-scope/common-constructs';

export class ExampleStack extends Stack {
  constructor(scope: Construct, id: string) {
    const agent = new MyProjectAgent(this, 'MyProjectAgent');
    const lambdaFunction = new Function(this, ...);

    agent.grantInvokeAccess(lambdaFunction);
  }
}

# Agent
module "my_project_agent" {
  # Relative path to the generated module in the common/terraform project
  source = "../../common/terraform/src/app/agents/my-project-agent"

  appconfig_application_id  = module.runtime_config_appconfig.application_id
  appconfig_application_arn = module.runtime_config_appconfig.application_arn
}

エージェントを呼び出すアクセス権を付与するには、module.my_project_agent.agent_core_runtime_arn 出力を参照する次のようなポリシーを追加する必要があります:

{
  Effect = "Allow"
  Action = [
    "bedrock-agentcore:InvokeAgentRuntime"
  ]
  Resource = [
    module.my_project_agent.agent_core_runtime_arn,
    "${module.my_project_agent.agent_core_runtime_arn}/*"
  ]
}

Cognito 認証

Cognito 認証を選択すると、ジェネレーターは Cognito を使用するようにエージェントを設定します。

CDK
Terraform

生成されたコンストラクトは、Cognito 認証を設定する identity プロパティを受け入れます:

import { MyProjectAgent, UserIdentity } from '@my-scope/common-constructs';

export class ExampleStack extends Stack {
  constructor(scope: Construct, id: string) {
    const identity = new UserIdentity(this, 'Identity');

    new MyProjectAgent(this, 'MyProjectAgent', {
      identity,
    });
  }
}

UserIdentity コンストラクトは ts#website#auth ジェネレーターを使用して生成するか、独自の CDK UserPool と UserPoolClient を作成できます。

生成されたモジュールは、Cognito 認証用の user_pool_id と user_pool_client_ids 変数を受け入れます:

module "user_identity" {
  source = "../../common/terraform/src/core/user-identity"
}

module "my_project_agent" {
  source = "../../common/terraform/src/app/agents/my-project-agent"

  appconfig_application_id  = module.runtime_config_appconfig.application_id
  appconfig_application_arn = module.runtime_config_appconfig.application_arn

  user_pool_id         = module.user_identity.user_pool_id
  user_pool_client_ids = [module.user_identity.user_pool_client_id]
}

バンドルターゲット

ジェネレーターは、Rolldown を使用してデプロイメントパッケージを作成する bundle ターゲットを自動的に設定します：

pnpm nx bundle <project-name>

yarn nx bundle <project-name>

npx nx bundle <project-name>

bunx nx bundle <project-name>

Rolldown の設定は rolldown.config.ts にあり、生成するバンドルごとにエントリーがあります。Rolldown は、定義されている場合、複数のバンドルを並列で作成することを管理します。

バンドルターゲットは、Bedrock AgentCore Runtime でホストする WebSocket サーバーのエントリーポイントとして index.ts を使用します。

Docker ターゲット

ジェネレーターは、エージェントのソースディレクトリから Dockerfile をバンドル出力ディレクトリにコピーする <your-agent-name>-docker ターゲットを設定します。これにより、Dockerfile がバンドルされたアーティファクトと同じ場所に配置され、CDK が AgentRuntimeArtifact.fromAsset を使用して Docker イメージを直接ビルドできるようになります。

複数のエージェントが定義されている場合、すべてのエージェントの Docker コンテキストを準備する docker ターゲットも生成されます。

イメージスキャン

このプロジェクト用にビルドされた Docker イメージは、ECR ホスト版 Trivy イメージから実行される Trivy を使用して脆弱性をスキャンできます。

プロジェクトに trivy ターゲットが追加され、ビルドされたイメージをスキャンし、HIGH または CRITICAL の深刻度の脆弱性が見つかった場合は非ゼロで終了します。生成された Dockerfile は、生成時点でこれらの深刻度の既知の修正可能な脆弱性がないベースイメージを使用し、バンドルされたツール（npm など）をアップグレードしてその状態を維持します。

スキャンはイメージビルドと同じコンテナエンジン（docker または finch）を使用するため、追加のツールは必要ありません。スキャンはイメージが変更された場合にのみ再実行されるため、変更されていないイメージは再スキャンされません。提供される trivy ルートスクリプトは、ワークスペース内のすべてのイメージをスキャンします：

pnpm trivy

yarn trivy

npm run trivy

bun trivy

スキャンは --ignore-unfixed で実行されるため、利用可能な修正がない脆弱性はビルドを失敗させません。これは、Dockerfile 内のツールをアップグレードすることでアクションできないためです — これらはビルドのスキャン出力に報告されません。新しい脆弱性が開示されると、スキャンの結果は時間の経過とともに変わる可能性があるため、フラグなしで trivy image <your-image> を実行してイメージを定期的に確認し、修正が公開されたら新しいベースイメージに対して再ビルドする（または利用可能なパッチを適用するコンテナステップを追加する）ことをお勧めします。

Trivy の検出結果の抑制

特定の脆弱性を抑制したい場合があります。たとえば、まだ修正が利用できず、リスクを許容可能と評価した場合などです。

脆弱性 ID（1 行に 1 つ）をプロジェクトのルート（つまり project.json の隣）にある .trivyignore ファイルに追加します：

# node-tar arbitrary file write - not exploitable in our usage
CVE-2024-XXXXX

検出結果のフィルタリングの詳細については、Trivy フィルタリングドキュメントを参照してください。

可観測性

エージェントは、Dockerfile で自動計装を設定することにより、AWS Distro for Open Telemetry（ADOT）を使用した可観測性で自動的に設定されます。

CloudWatch AWS コンソールでメニューから「GenAI Observability」を選択することで、トレースを見つけることができます。トレースが入力されるためには、Transaction Search を有効にする必要があることに注意してください。

詳細については、AgentCore の可観測性に関するドキュメントを参照してください。

セッション管理

session オプションは、Strands SDK の SessionManager を使用して、エージェントが呼び出し間で会話状態（メッセージ履歴、ツール状態など）を永続化する方法を制御します：

s3（デフォルト）: CDK/Terraform インフラストラクチャは、セッションデータ用の専用 S3 バケットをプロビジョニングします。専用 KMS キーで暗号化され、すべてのパブリックアクセスがブロックされます。サーバーアクセスログは、同じキーを介して CloudWatch Logs ロググループに配信されます。エージェントの IAM ロールには、バケットへの読み取り/書き込み/リスト/削除アクセスと、キーへの復号化/データキー生成アクセスが付与され、バケット名は AppConfig ランタイム設定でエージェントの ARN と一緒に登録されます。
in-memory: バケットはプロビジョニングされません。会話状態は、実行中のプロセスの存続期間中のみメモリに保持され、再起動やスケールインでは存続しません。

これは生成された session.ts に実装されており、現在のセッションの SessionManager を解決する getSessionManager() 関数をエクスポートします。

セッション ID 自体は AgentCore Runtime セッションから取得され（A2A/AG-UI の場合は x-amzn-bedrock-agentcore-runtime-session-id ヘッダーを介して、HTTP/tRPC の場合は WebSocket 接続コンテキストを介して伝播されます）、AsyncLocalStorage ベースのコンテキストにバインドされるため、getCurrentSessionId() はリクエスト内のどこでもそれを解決できます。これには、connection ジェネレーターを介して接続された下流の MCP または A2A クライアントも含まれるため、呼び出しチェーン全体が一貫したセッションを共有します。

エージェントの呼び出し

エージェント通信は WebSocket 上の tRPC を介して送信されます。そのため、client.ts で生成された型安全なクライアントファクトリを使用することをお勧めします。

ローカルサーバーの呼び出し

クライアントファクトリの .local ファクトリメソッドを使用して、ローカルで実行中のエージェントを呼び出すことができます。

たとえば、ワークスペースに scripts/test.ts という名前のファイルを作成し、クライアントをインポートできます：

import { AgentClient } from '../packages/<project>/src/agent/client.js';

const client = AgentClient.local({ url: 'http://localhost:8081/ws' });

client.invoke.subscribe({ prompt: 'what is 1 plus 1?' }, { onData: console.log });

エージェントをすばやくテストする方法として、tsx で実行します。

pnpm tsx scripts/test.ts

yarn tsx scripts/test.ts

npx tsx scripts/test.ts

bunx tsx scripts/test.ts

デプロイされたエージェントの呼び出し

Bedrock AgentCore Runtimeにデプロイされたエージェントを呼び出すには、URLエンコードされたランタイムARNを使用してBedrock AgentCore RuntimeデータプレーンエンドポイントにPOSTリクエストを送信します。

ランタイムARNは、以下のようにインフラストラクチャから取得できます：

CDK
Terraform

import { CfnOutput } from 'aws-cdk-lib';
import { MyProjectAgent } from '@my-scope/common-constructs';

export class ExampleStack extends Stack {
  constructor(scope: Construct, id: string) {
    const agent = new MyProjectAgent(this, 'MyProjectAgent');

    new CfnOutput(this, 'AgentArn', {
      value: agent.agentCoreRuntime.agentRuntimeArn,
    });
  }
}

# Agent
module "my_project_agent" {
  # Relative path to the generated module in the common/terraform project
  source = "../../common/terraform/src/app/agents/my-project-agent"

  appconfig_application_id  = module.runtime_config_appconfig.application_id
  appconfig_application_arn = module.runtime_config_appconfig.application_arn
}

output "agent_arn" {
  value = module.my_project_agent.agent_core_runtime_arn
}

ARNは次の形式になります：arn:aws:bedrock-agentcore:<region>:<account>:runtime/<agent-runtime-id>。

その後、:を%3Aに、/を%2Fに置き換えることでARNをURLエンコードできます。

ブラウザコンソールまたはNode REPLでは、組み込みのencodeURIComponentメソッドを使用して簡単に実行できます：

encodeURIComponent('arn:aws:bedrock-agentcore:<region>:<account>:runtime/<agent-runtime-id>')

エージェントを呼び出すためのBedrock AgentCore RuntimeデータプレーンのURLは次のとおりです：

https://bedrock-agentcore.<region>.amazonaws.com/runtimes/<url-encoded-arn>/invocations

インフラストラクチャは、ARNエンコーディングを処理した完全な呼び出しURLを直接出力することもできます：

CDK
Terraform

new CfnOutput(this, 'AgentUrl', {
  value: agent.invocationUrl,
});

output "agent_url" {
  value = module.my_project_agent.invocation_url
}

このURLを呼び出す正確な方法は、使用される認証方法によって異なります。

NodeJS

生成された client.ts ファイルには、デプロイされたエージェントを呼び出すために使用できる型安全なクライアントファクトリが含まれています。

IAM
Cognito

IAM 認証

withIamAuth ファクトリメソッドにエージェントの ARN を渡すことで、デプロイされたエージェントを呼び出すことができます：

import { AgentClient } from './agent/client.js';

const client = AgentClient.withIamAuth({
  agentRuntimeArn: 'arn:aws:bedrock-agentcore:us-west-2:123456789012:runtime/my-agent',
});

client.invoke.subscribe({ prompt: 'what is 1 plus 1?' }, {
  onData: (message) => console.log(message),
  onError: (error) => console.error(error),
  onComplete: () => console.log('Done'),
});

JWT / Cognito 認証

JWT / Cognito アクセストークンで認証するには、withJwtAuth ファクトリメソッドを使用します。

const client = AgentClient.withJwtAuth({
  agentRuntimeArn: 'arn:aws:bedrock-agentcore:us-west-2:123456789012:runtime/my-agent',
  accessTokenProvider: async () => `<access-token>`,
});

client.invoke.subscribe({ prompt: 'what is 1 plus 1?' }, {
  onData: console.log,
});

accessTokenProvider は、リクエストの認証に使用されるトークンを返す必要があります。たとえば、このメソッド内でトークンを取得して、tRPC が WebSocket 接続を再起動したときに新しい認証情報が再利用されるようにすることができます。以下は、AWS SDK を使用して Cognito からトークンを取得する方法を示しています：

import { CognitoIdentityProvider } from "@aws-sdk/client-cognito-identity-provider";

const cognito = new CognitoIdentityProvider();

const jwtClient = AgentClient.withJwtAuth({
  agentRuntimeArn: 'arn:aws:bedrock-agentcore:us-west-2:123456789012:runtime/my-agent',
  accessTokenProvider: async () => {
    const response = await cognito.adminInitiateAuth({
      UserPoolId: '<user-pool-id>',
      ClientId: '<user-pool-client-id>',
      AuthFlow: 'ADMIN_NO_SRP_AUTH',
      AuthParameters: {
        USERNAME: '<username>',
        PASSWORD: '<password>',
      },
    });
    return response.AuthenticationResult!.AccessToken!;
  },
});

ブラウザ / React ウェブサイト

React ウェブサイトからエージェントを呼び出すには、connection ジェネレーターを使用できます。これにより、正しい認証（IAM または Cognito）を使用した tRPC WebSocket クライアントが自動的に設定されます。

CLI
VSCode

pnpm nx g @aws/nx-plugin:connection

yarn nx g @aws/nx-plugin:connection

npx nx g @aws/nx-plugin:connection

bunx nx g @aws/nx-plugin:connection

変更されるファイルを確認するためにドライランを実行することもできます

pnpm nx g @aws/nx-plugin:connection --dry-run

yarn nx g @aws/nx-plugin:connection --dry-run

npx nx g @aws/nx-plugin:connection --dry-run

bunx nx g @aws/nx-plugin:connection --dry-run

インストール Nx Console VSCode Plugin まだインストールしていない場合
VSCodeでNxコンソールを開く
クリック Generate (UI) "Common Nx Commands"セクションで
検索 @aws/nx-plugin - connection
必須パラメータを入力
クリック Generate

接続の設定方法の詳細については、connection ジェネレーターガイドを参照してください。

A2A エージェントをツールとして呼び出す

このエージェントからリモート A2A エージェント（TypeScript または Python）に作業を委任するには、connection ジェネレーターを使用します。これにより、ターゲットエージェント用の SigV4 認証クライアントが提供され、このエージェントの agent.ts が AST 変換されて、リモート A2A エージェントが Strands tool として登録されます。

CLI
VSCode

pnpm nx g @aws/nx-plugin:connection

yarn nx g @aws/nx-plugin:connection

npx nx g @aws/nx-plugin:connection

bunx nx g @aws/nx-plugin:connection

変更されるファイルを確認するためにドライランを実行することもできます

pnpm nx g @aws/nx-plugin:connection --dry-run

yarn nx g @aws/nx-plugin:connection --dry-run

npx nx g @aws/nx-plugin:connection --dry-run

bunx nx g @aws/nx-plugin:connection --dry-run

インストール Nx Console VSCode Plugin まだインストールしていない場合
VSCodeでNxコンソールを開く
クリック Generate (UI) "Common Nx Commands"セクションで
検索 @aws/nx-plugin - connection
必須パラメータを入力
クリック Generate

接続の設定方法の詳細については、connection ジェネレーターガイドを参照してください。

AG-UI エージェントの呼び出し

React ウェブサイトから AG-UI エージェントを呼び出すには、connection ジェネレーターを使用します。これにより、正しい認証（IAM または Cognito）を使用してデプロイされたエージェント用に設定された CopilotKit クライアントが接続されます。

CLI
VSCode

pnpm nx g @aws/nx-plugin:connection

yarn nx g @aws/nx-plugin:connection

npx nx g @aws/nx-plugin:connection

bunx nx g @aws/nx-plugin:connection

変更されるファイルを確認するためにドライランを実行することもできます

pnpm nx g @aws/nx-plugin:connection --dry-run

yarn nx g @aws/nx-plugin:connection --dry-run

npx nx g @aws/nx-plugin:connection --dry-run

bunx nx g @aws/nx-plugin:connection --dry-run

インストール Nx Console VSCode Plugin まだインストールしていない場合
VSCodeでNxコンソールを開く
クリック Generate (UI) "Common Nx Commands"セクションで
検索 @aws/nx-plugin - connection
必須パラメータを入力
クリック Generate

接続の設定方法の詳細については、connection ジェネレーターガイドを参照してください。

エージェントの保護

エージェントは信頼できない入力に対して動作し、ツールを通じて実際のアクションを実行できるため、最初からセキュリティを考慮する価値があります。以下のプラクティスは、生成されたエージェントに適用されます。

モデルの入力と出力を信頼できないものとして扱う

プロンプトには敵対的な指示（プロンプトインジェクション）が含まれる可能性があり、モデルの出力は非決定的です。どちらもセキュリティに敏感なロジックで信頼すべきではありません：

生成されたサンプルツールのように、ツールに対して厳密な入力スキーマを定義します。自由形式の文字列を受け入れるのではなく、ツールが実際に必要とするもの（列挙型、長さ制限、数値範囲）に値を制約します。
モデルの出力を検証やエンコーディングなしに、シェルコマンド、SQLクエリ、コード評価、またはレンダリングされたHTMLに直接渡さないでください。
ツールおよび下流のサービスで認可チェックを適用します。モデルがアクセス権を持つツールの誤用を防ぐためにシステムプロンプトに依存しないでください。

StrandsのPrompt EngineeringおよびResponsible AIガイドでは、堅牢で安全性を意識したシステムプロンプトの作成について説明しています。

ツールの権限を厳密にスコープする

エージェントのIAMロールには、そのツールが必要とする権限のみを付与します。提供されるCDKコンストラクトとTerraformモジュールは、この目的のためにgrant*メソッドとスコープされたポリシーを公開しています。たとえば、広範な管理ポリシーをアタッチするのではなく、特定のAPIを呼び出すアクセス権をエージェントに付与します。ツールがユーザーの代わりに動作する場合は、エージェント自身の環境権限よりも、呼び出し元ユーザーのアイデンティティ（リクエストコンテキストを通じて渡される）を使用してアクションを認可することを優先します。

キルスイッチを提供する

モデルの動作は予期しない方法で変化する可能性があるため、コード変更なしでモデルを迅速に無効化または交換できるように計画します：

モデルIDを設定から読み取ります（たとえばMODEL_ID環境変数）。これにより、オペレーターは設定を更新することで別のモデルに切り替えたりロールバックしたりできます。
エージェントをフィーチャーフラグの背後に配置して、AI機能を完全に無効化できるようにします。無効化された場合は、エラーではなく一般的なメッセージを返し、アプリケーションの残りの部分が適切に劣化することを確認します。

これらのコントロールを切り替える方法を運用ランブックに文書化します。

機密データを保護する

プロンプトと補完のログ記録を避けます。これらにはユーザーデータが含まれる可能性があります。生成されたエージェントのモデルエラーログフックは、会話の内容ではなくエラーメタデータのみをログに記録します。独自のログを追加する際は、このプロパティを維持してください。
ユーザーには一般的なエラーメッセージを返します。詳細なエラーはサーバー側でログに記録します。
ユーザーとセッション間で会話状態を分離し、永続化されたセッションデータへのアクセスを認可します。
プロンプトと出力から個人を特定できる情報（PII）を編集します。Bedrock Guardrailの機密情報フィルター（以下）を使用するか、Strandsエージェントの場合はPII Redactionガイドのアプローチを使用します。

Amazon Bedrock Guardrails

Amazon Bedrock Guardrailsは、モデルの入力と出力で評価される、設定可能なコンテンツフィルター、拒否されたトピック、および機密情報（PII）フィルターを提供します。生成されたエージェントが使用するモデルにガードレールをアタッチできます：

import { Agent } from '@strands-agents/sdk';
import { BedrockModel } from '@strands-agents/sdk/models/bedrock';

const model = new BedrockModel({
  modelId: process.env.MODEL_ID,
  guardrailConfig: {
    guardrailIdentifier: process.env.GUARDRAIL_ID!,
    guardrailVersion: process.env.GUARDRAIL_VERSION ?? 'DRAFT',
  },
});

const agent = new Agent({ model, /* ... */ });

詳細については、Strands の Guardrails ガイドを参照してください。

接続

connection ジェネレーターを使用して、このプロジェクトをワークスペース内の他のプロジェクトと統合します。このプロジェクトに関連する接続は以下の通りです：

React to TypeScript AgentCall a TypeScript Agent from a React website

React to AG-UI AgentCall an Agent exposing the AG-UI protocol from a React website via CopilotKit

TypeScript Agent to MCPConnect a TypeScript Agent to an MCP server

TypeScript Agent to A2A AgentConnect a TypeScript Agent to a remote A2A agent

Python Agent to A2A AgentConnect a Python Agent to a remote A2A agent

TypeScript Agent to Relational DatabaseConnect a TypeScript Agent to an Aurora relational database

TypeScript Agent to TypeScript DynamoDBConnect a TypeScript Agent to a DynamoDB table

TypeScript Agent to AgentCore GatewayConnect a TypeScript Agent to an AgentCore Gateway

AgentCore Gateway to AgentFront an agent with an AgentCore Gateway as a runtime target