Skip to content
@aws/nx-plugin
Blog

TypeScript Agent

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

Strands とは？

Section titled “Strands とは？”

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

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

使用方法

Section titled “使用方法”

エージェントの生成

Section titled “エージェントの生成”

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

このジェネレーターを実行@aws/nx-plugin:ts#agent

pnpm nx g @aws/nx-plugin:ts#agent
コマンドを組み立てる9

必須

infra = agentcore | agentcore-ecr

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

オプション

Section titled “オプション”
ジェネレーターオプション9 オプション
project必須string

Agentを追加するプロジェクト

frameworkenumデフォルト: strands

使用するエージェントSDK。

strands
authenuminfra = agentcore | agentcore-ecrデフォルト: iam

エージェントとの認証に使用する方法。infraが設定されている場合にのみ適用されます（infraがnoneの場合は無視されます）。

iamcognito
protocolenumデフォルト: http

Agentのサーバープロトコル。HTTPはtRPC/WebSocketサーバーを公開します。A2AはAgent-to-Agentプロトコルサーバーを公開します。AG-UIはCopilotKitとのフロントエンド直接統合のためのAG-UIプロトコルサーバーを公開します。

httpa2aag-ui
iacenumデフォルト: inherit

優先するIaCプロバイダー。デフォルトでは、初期選択から継承されます。

inheritcdkterraform
infraenumデフォルト: agentcore

Agentをホストするインフラストラクチャのタイプ。agentcoreは、最速のビルドとデプロイサイクルのために、コードをzipとしてAgentCore管理ランタイムにデプロイします。agentcore-ecrは、OS レベルの制御や確立されたコンテナパイプラインのために、代わりにコンテナイメージをビルドしてホストします。

agentcoreagentcore-ecrnone
sessionenumデフォルト: s3

エージェントのセッションを永続化するために使用されるストレージ。

s3in-memory
namestring

Agentの名前（デフォルト: agent）

preferInstallDependenciesbooleanデフォルト: true

ジェネレーター実行後に依存関係のインストールを優先するかどうか。複数のジェネレーターをバッチ処理する際にインストールを延期する場合はfalseに設定します（後続のジェネレーターがNxプロジェクトグラフを計算できるよう、必要に応じてインストールは実行されます）。最後に一度だけインストールします。

ジェネレーターの出力

Section titled “ジェネレーターの出力”

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

protocol = http

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

Section titled “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
        • Directoryschema/
          • z-async-iterable.ts Zod schema for the router’s streamed responses
        • client.ts Vended client for invoking your agent
        • agent-core-trpc-client.ts Client factory for connecting to agents on AgentCore Runtime
        • Dockerfile Container image definition (only when infra is agentcore-ecr)
    • package.json Updated with Strands dependencies
    • project.json Updated with agent serve targets
protocol = a2a

A2A プロトコル

Section titled “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
        • Directorymiddleware/
          • session-id-middleware.ts Binds the inbound AgentCore session ID for the request
        • Dockerfile Container image definition (only when infra is agentcore-ecr)
    • package.json Updated with Strands and Express dependencies
    • project.json Updated with agent serve targets
protocol = ag-ui

AG-UI プロトコル

Section titled “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
        • Directorymiddleware/
          • session-id-middleware.ts Binds the inbound AgentCore session ID for the request
        • Dockerfile Container image definition (only when infra is agentcore-ecr)
    • package.json Updated with Strands and AG-UI dependencies
    • project.json Updated with agent serve targets

インフラストラクチャ

Section titled “インフラストラクチャ”

infra オプションは、Amazon Bedrock AgentCore Runtime 上でコードをパッケージ化してホストする方法を選択します：

  • agentcore (デフォルト) は 直接コードデプロイ を使用します：ビルドされたコードは .zip としてパッケージ化され、S3 にアップロードされ、AgentCore が管理する言語ランタイム上で実行されます。コンテナイメージのビルド、ECR リポジトリの管理、イメージのプッシュが不要なため、ビルドとデプロイのサイクルが大幅に高速化されます。
  • agentcore-ecr は、提供される Dockerfile から arm64 コンテナイメージをビルドし、ワークスペース内の他のすべてのコンテナと並んで、共有 core/asset-ecr レジストリからホストします。オペレーティングシステムイメージを制御する必要がある場合（例えば、ネイティブシステムライブラリをインストールする場合）や、確立されたコンテナパイプラインがある場合に選択してください。このオプションは、Trivy イメージスキャンターゲットも提供します（下記の Image Scanning を参照）。
  • none はインフラストラクチャを一切生成しないため、プロジェクトはローカルでのみ実行できます。
infra = agentcore | agentcore-ecr

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

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

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

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

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

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

アーキテクチャ

Section titled “アーキテクチャ”

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

Loading the diagram…

エージェントの操作

Section titled “エージェントの操作”

プロトコル

Section titled “プロトコル”

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

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

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

protocol = http

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

Section titled “WebSocket 上の tRPC（HTTP プロトコル）”

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

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

ツールの追加

Section titled “ツールの追加”

ツールは、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 スキーマ生成
  • エラー処理とレスポンスのフォーマット

モデル設定

Section titled “モデル設定”

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

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 サーバーの利用

Section titled “MCP サーバーの利用”

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

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

このジェネレーターを実行@aws/nx-plugin:connection

pnpm nx g @aws/nx-plugin:connection
コマンドを組み立てる5

必須

必須

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

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

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

その他

Section titled “その他”

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

protocol = a2a

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

Section titled “A2A サーバー（A2A プロトコル）”

生成された index.ts は、Strands A2A Express Server を Express アプリにマウントするため、生成されたエージェントは A2A プロトコルエンドポイントと /ping ヘルスチェックを公開します。エージェントカードでアドバタイズされる URL は AGENTCORE_RUNTIME_URL 環境変数から取得され、ローカル開発の場合は http://localhost:<port>/ にフォールバックします。

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

protocol = ag-ui

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

Section titled “AG-UI サーバー（AG-UI プロトコル）”

生成された index.ts は、Strands Agent を @ag-ui/aws-strands の StrandsAgent でラップし、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 と同じ）。生成されたインフラストラクチャはすでにこれに対応して設定されています。

エージェントの実行

Section titled “エージェントの実行”

ローカル開発

Section titled “ローカル開発”

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

Terminal window
pnpm nx dev your-project

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

Terminal window
pnpm nx agent-dev your-project

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

<your-agent-name>-serve ターゲットも生成されます。これはデプロイされたインフラストラクチャに対してエージェントを実行するため、RUNTIME_CONFIG_APP_ID を設定する必要があります。dev と serve の違いについては、Local Development ガイドを参照してください。

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

Section titled “エージェントとのチャット”

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

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

Terminal window
pnpm nx agent-dev your-project

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

Terminal window
pnpm nx run your-project:agent-chat

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

infra = agentcore | agentcore-ecr

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

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

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

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

Terminal window
RUNTIME_CONFIG_APP_ID=<app-id> pnpm nx run your-project:agent-chat
infra = agentcore | agentcore-ecr

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

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

Infrastructure as Code

Section titled “Infrastructure as Code”

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

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');
  }
}

認証

Section titled “認証”

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

IAM

Section titled “IAM”

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

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);
  }
}

Cognito 認証

Section titled “Cognito 認証”

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

生成されたコンストラクトは、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 を作成できます。

バンドルターゲット

Section titled “バンドルターゲット”

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

Terminal window
pnpm nx bundle <project-name>

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

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

infra = agentcore

パッケージターゲット

Section titled “パッケージターゲット”

ジェネレーターは、デプロイ可能なコードパッケージを組み立てる <your-agent-name>-package ターゲットを設定します。バンドルされた index.js と、AgentCore がパッケージに存在することを要求する AWS Distro for OpenTelemetry のベンダーインストールが含まれます。生成されたインフラストラクチャは、このディレクトリを .zip としてアップロードします。CDK では AgentRuntimeArtifact.fromCodeAsset を介して、Terraform では共有アセットバケットにアーカイブされます。

infra = agentcore-ecr

Docker ターゲット

Section titled “Docker ターゲット”

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

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

イメージスキャン

Section titled “イメージスキャン”

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

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

スキャンはイメージビルドと同じコンテナエンジン（docker または finch）を使用するため、追加のツールは必要ありません。スキャンはキャッシュされません。これは、読み取るイメージがディスク上ではなくコンテナエンジン内に存在するためです — そのため、常に実際のイメージをスキャンし、もはや存在しないイメージに対してキャッシュされた合格を報告するのではなく、明確に失敗します。したがって、各実行はイメージごとに数十秒かかり、Trivy の脆弱性データベースを更新するため、ネットワークアクセスが必要です。提供される trivy ルートスクリプトは、ワークスペース内のすべてのイメージをスキャンします：

Terminal window
pnpm trivy

Trivy の検出結果の抑制

Section titled “Trivy の検出結果の抑制”

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

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

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

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

可観測性

Section titled “可観測性”

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

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

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

セッション管理

Section titled “セッション管理”

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 クライアントも含まれるため、呼び出しチェーン全体が一貫したセッションを共有します。

セッションを所有者に制限する

Section titled “セッションを所有者に制限する”

セッション ID は呼び出し元から送信されるため、それ自体では会話を識別しますが、会話が誰に属しているかは識別しません。AgentCore Runtime は、個々のセッションに対してではなく、エージェントランタイムリソース ARN に対して呼び出しを承認するため、エージェントはアプリケーションにとってセッションが何を意味するかを自由に決定できます。

各ユーザーを自分の会話に制限するには：

  1. tRPC、FastAPI、または Smithy を使用して、セッションを作成する API を追加します。不透明なセッション ID（少なくとも33文字）を生成し、呼び出し元のユーザー ID と一緒に保存します。たとえば、ts#dynamodb ジェネレーターで作成されたテーブルに保存します。各 API ガイドには、呼び出し元のユーザー ID を取得する方法が示されています。
  2. エージェントで、与えられたセッション ID に対して保存されたユーザー ID を検索し、呼び出し元と一致しない場合はリクエストを拒否します。auth=cognito の場合、呼び出し元の JWT がエージェントコードに到達するため、その sub クレームが呼び出し元を識別します。

会話名などのユーザー提供値からセッション ID を導出するのではなく、セッション ID を生成してください。呼び出し元が予測できるものは、呼び出し元が送信できます。

エージェントの呼び出し

Section titled “エージェントの呼び出し”
protocol = http

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

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

Section titled “ローカルサーバーの呼び出し”

<your-agent-name>-dev ターゲットでエージェントを起動します：

Terminal window
pnpm nx agent-dev your-project

次に、クライアントファクトリの .local ファクトリメソッドを使用して呼び出します。

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

クライアントクラスはエージェントにちなんで名付けられるため、my-agent という名前のエージェントは MyAgentClient をエクスポートします。

scripts/test.ts
import { MyAgentClient } from '../packages/<project>/src/agent/client.js';


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


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

エージェントに割り当てられたポートに置き換えてください — プロジェクトの project.json の metadata.ports から読み取ります。

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

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

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

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

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,
    });
  }
}

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

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

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

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

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

NodeJS

Section titled “NodeJS”

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

IAM 認証
Section titled “IAM 認証”

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

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


const client = MyAgentClient.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'),
});

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

Section titled “ブラウザ / React ウェブサイト”

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

このジェネレーターを実行@aws/nx-plugin:connection

pnpm nx g @aws/nx-plugin:connection
コマンドを組み立てる5

必須

必須

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

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

protocol = a2a

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

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

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

このジェネレーターを実行@aws/nx-plugin:connection

pnpm nx g @aws/nx-plugin:connection
コマンドを組み立てる5

必須

必須

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

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

protocol = ag-ui

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

Section titled “AG-UI エージェントの呼び出し”

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

このジェネレーターを実行@aws/nx-plugin:connection

pnpm nx g @aws/nx-plugin:connection
コマンドを組み立てる5

必須

必須

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

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

エージェントの保護

Section titled “エージェントの保護”

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

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

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

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

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

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

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

Section titled “ツールの権限を厳密にスコープする”

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

キルスイッチを提供する

Section titled “キルスイッチを提供する”

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

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

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

機密データを保護する

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

Amazon Bedrock Guardrails

Section titled “Amazon Bedrock Guardrails”

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

agent.ts
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 ガイドを参照してください。

接続

Section titled “接続”

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

Strands AgentsTypeScript
React to TypeScript AgentCall a TypeScript Agent from a React website
CopilotKit
React to AG-UI AgentCall an Agent exposing the AG-UI protocol from a React website via CopilotKit
Strands AgentsTypeScriptModel Context Protocol
TypeScript Agent to MCPConnect a TypeScript Agent to an MCP server
Strands AgentsTypeScriptAgent2Agent
TypeScript Agent to A2A AgentConnect a TypeScript Agent to a remote A2A agent
Strands AgentsPythonAgent2Agent
Python Agent to A2A AgentConnect a Python Agent to a remote A2A agent
Strands AgentsTypeScriptAmazon Aurora
TypeScript Agent to Relational DatabaseConnect a TypeScript Agent to an Aurora relational database
Strands AgentsTypeScriptAmazon DynamoDB
TypeScript Agent to TypeScript DynamoDBConnect a TypeScript Agent to a DynamoDB table
Strands AgentsTypeScriptAmazon Bedrock AgentCore Gateway
TypeScript Agent to AgentCore GatewayConnect a TypeScript Agent to an AgentCore Gateway
Amazon Bedrock AgentCore GatewayStrands Agents
AgentCore Gateway to AgentFront an agent with an AgentCore Gateway as a runtime target