TypeScript Strands エージェント

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

Strands とは?

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

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

使用方法

Agent の生成

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

VSCode
CLI

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

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

オプション

パラメータ	型	デフォルト	説明
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	エージェントをホストするインフラストラクチャのタイプ。
preferInstallDependencies	boolean	true	ジェネレーター実行後に依存関係のインストールを優先するかどうか。複数のジェネレーターをバッチ処理する際にインストールを延期する場合はfalseに設定します（後続のジェネレーターがNxプロジェクトグラフを計算できるよう、必要に応じてインストールは実行されます）。最後に一度だけインストールします。

ジェネレーター出力

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

HTTP プロトコル (デフォルト)

Directoryyour-project/
- Directorysrc/
  - Directoryagent/ (指定した場合はカスタム名)
    index.ts Bedrock AgentCore Runtime のエントリーポイント (tRPC/WebSocket サーバー)
    init.ts tRPC の初期化
    router.ts エージェントプロシージャを含む tRPC ルーター
    agent.ts サンプルツールを含むメインエージェント定義
    client.ts エージェントを呼び出すための提供されたクライアント
    agent-core-trpc-client.ts AgentCore Runtime 上のエージェントに接続するためのクライアントファクトリー
    Dockerfile エージェントをホストするためのエントリーポイント (infra が None に設定されている場合は除外)
- package.json Strands 依存関係で更新
- project.json エージェント serve ターゲットで更新

A2A プロトコル

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

Directoryyour-project/
- Directorysrc/
  - Directoryagent/ (指定した場合はカスタム名)
    index.ts A2A Express サーバーのエントリーポイント
    agent.ts サンプルツールを含むメインエージェント定義
    Dockerfile エージェントをホストするためのエントリーポイント (infra が None に設定されている場合は除外)
- package.json Strands と Express 依存関係で更新
- project.json エージェント serve ターゲットで更新

AG-UI プロトコル

エントリーポイントは @ag-ui/aws-strands を使用して、AG-UI プロトコル (SSE over POST) を介してエージェントを公開します。CopilotKit と互換性があります:

Directoryyour-project/
- Directorysrc/
  - Directoryagent/ (指定した場合はカスタム名)
    index.ts AG-UI サーバーのエントリーポイント (Express + SSE)
    agent.ts サンプルツールを含むメインエージェント定義
    Dockerfile エージェントをホストするためのエントリーポイント (infra が None に設定されている場合は除外)
- package.json Strands と AG-UI 依存関係で更新
- project.json エージェント serve ターゲットで更新

インフラストラクチャ

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

共通のInfrastructure as Codeプロジェクトは以下の構造を持ちます：

CDK
Terraform

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

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

Agent をデプロイするために、次のファイルが生成されます:

CDK
Terraform

Directorypackages/common/constructs/src
- Directoryapp
  - Directoryagents
    Directory<project-name>
    <project-name>.ts エージェントをデプロイするための CDK コンストラクト

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

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

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

Agent の操作

プロトコル

エージェントのサーバープロトコルは、通信方法を決定します。次のいずれかを選択できます:

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

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

tRPC over WebSocket (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}'`;
  },
});

// エージェントにツールを追加
export const getAgent = async (sessionId: string) => {
  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';

// 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?');

// または、モデルプロバイダーを切り替えるだけで OpenAI を使用
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 ジェネレーターを利用できます。

VSCode
CLI

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

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

接続の設定方法の詳細については、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 とインフラストラクチャはすでにこれに対応しています。

Agent の実行

ローカル開発

Agent (およびそれに接続されているすべてのもの) をローカルで実行するには、プロジェクトの 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

Agent を Bedrock AgentCore Runtime にデプロイ

Infrastructure as Code

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

CDK
Terraform

エージェント用の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モジュールの出力をエージェントモジュールに渡します:

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]
}

Bundle ターゲット

ジェネレーターは自動的に 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は定義された複数のバンドルを並行して作成する処理を管理します。

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

Docker ターゲット

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

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

イメージスキャン

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

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

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

pnpm trivy

yarn trivy

npm run trivy

bun trivy

Trivy検出結果の抑制

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

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

# 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 ドキュメントを参照してください。

Agent の呼び出し

エージェント通信は、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({ message: '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({ message: '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 ウェブサイトから Agent を呼び出す場合は、connection ジェネレーターを利用できます。これにより、正しい認証 (IAM または Cognito) を使用した tRPC WebSocket クライアントが自動的にセットアップされます。

VSCode
CLI

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

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

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

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

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

VSCode
CLI

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

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

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

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

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

VSCode
CLI

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

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

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

エージェントの保護

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

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

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

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

Strandsのプロンプトエンジニアリングと責任ある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, /* ... */ });