Python Agent

ツールを使用してエージェントを構築するためのPython AIエージェントを生成し、オプションでAmazon Bedrock AgentCore Runtimeにデプロイします。frameworkオプションでエージェントフレームワークを選択できます：Strands（デフォルト）またはLangChain（LangGraph上に構築）。

ジェネレーターはサーバーprotocolを介してエージェントを公開します。両方のフレームワークはHTTP（デフォルト）、他のA2A互換エージェントとの相互運用性のためのAgent-to-Agent (A2A)プロトコル、およびCopilotKitを介した直接的なフロントエンド統合のためのAG-UIプロトコルをサポートしています。

使用方法

エージェントの生成

2つの方法でPython Agentを生成できます：

VSCode
CLI

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

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

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

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

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

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

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

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

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

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

オプション

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

ジェネレーターの出力

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

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

Directoryyour-project/
- Directoryyour_module/
  - Directoryagent/（指定した場合はカスタム名）
    __init__.py Pythonパッケージ初期化ファイル
    init.py CORSとエラーハンドリングミドルウェアを備えたFastAPIアプリケーション設定
    agent.py サンプルツール付きメインエージェント定義
    main.py Bedrock AgentCore Runtime用FastAPIエントリーポイント
    Dockerfile エージェントホスティング用Dockerfile（infraがNoneの場合は生成されない）
- pyproject.toml Strands依存関係が追加された設定ファイル
- project.json エージェントサーブターゲットが追加された設定ファイル

A2Aプロトコル

エントリーポイントはA2Aプロトコル経由でエージェントを公開します（StrandsはStrands A2A Serverを使用し、LangChainはグラフをa2a-sdkエグゼキューターでラップします）。FastAPIアプリにマウントされます：

Directoryyour-project/
- Directoryyour_module/
  - Directoryagent/（指定した場合はカスタム名）
    __init__.py Pythonパッケージ初期化ファイル
    agent.py サンプルツール付きメインエージェント定義
    main.py A2Aサーバーエントリーポイント
    Dockerfile エージェントホスティング用Dockerfile（infraがNoneの場合は生成されない）
- pyproject.toml フレームワークとA2A依存関係が追加された設定ファイル
- project.json エージェントサーブターゲットが追加された設定ファイル

AG-UIプロトコル

エントリーポイントはCopilotKitとの直接的なフロントエンド統合のためにAG-UIプロトコル経由でエージェントを公開します。Strandsエージェントはag-ui-strands統合を使用し、LangChainエージェントはag-ui-langgraphを使用します：

Directoryyour-project/
- Directoryyour_module/
  - Directoryagent/（指定した場合はカスタム名）
    __init__.py Pythonパッケージ初期化ファイル
    agent.py サンプルツール付きメインエージェント定義
    main.py AG-UIサーバーエントリーポイント
    Dockerfile エージェントホスティング用Dockerfile（infraがNoneの場合は生成されない）
- pyproject.toml フレームワークとAG-UI依存関係が追加された設定ファイル
- project.json エージェントサーブターゲットが追加された設定ファイル

インフラストラクチャ

このジェネレータは選択した 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.pyを編集してツールの追加、モデルの設定、システムプロンプトのカスタマイズができます。APIは選択したフレームワークによって異なります。

ツールの追加

ツールはAIエージェントがアクションを実行するために呼び出す関数です。両方のフレームワークはツールを定義するためにデコレータベースのアプローチを使用し、関数名とdocstringからツール名と説明を導出し、型ヒントから入力スキーマを生成します。

Strands
LangChain

from strands import Agent, tool

@tool
def calculate_sum(numbers: list[int]) -> int:
    """数値リストの合計を計算"""
    return sum(numbers)

@tool
def get_weather(city: str) -> str:
    """都市の天気情報を取得"""
    # 天気API連携をここに実装
    return f"{city}の天気：晴れ、25°C"

# エージェントにツールを追加
agent = Agent(
    system_prompt="様々なツールにアクセスできる便利なアシスタントです。",
    tools=[calculate_sum, get_weather],
)

from langchain.agents import create_agent
from langchain_aws import ChatBedrockConverse
from langchain_core.tools import tool

@tool
def calculate_sum(numbers: list[int]) -> int:
    """数値リストの合計を計算"""
    return sum(numbers)

@tool
def get_weather(city: str) -> str:
    """都市の天気情報を取得"""
    # 天気API連携をここに実装
    return f"{city}の天気：晴れ、25°C"

# エージェントにツールを追加
agent = create_agent(
    model=ChatBedrockConverse(model=MODEL_ID, region_name=REGION),
    tools=[calculate_sum, get_weather],
    system_prompt="様々なツールにアクセスできる便利なアシスタントです。",
)

プリビルドツールの使用

Strands
LangChain

Strandsはstrands-toolsパッケージを通じてプリビルドツールのコレクションを提供します：

from strands_tools import current_time, http_request, file_read

agent = Agent(
    system_prompt="便利なアシスタントです。",
    tools=[current_time, http_request, file_read],
)

LangChainはツールと統合の大規模なエコシステムを提供します。関連する統合パッケージをインストールし、ツールをcreate_agentに渡します：

from langchain_community.tools import DuckDuckGoSearchRun

agent = create_agent(
    model=ChatBedrockConverse(model=MODEL_ID, region_name=REGION),
    tools=[DuckDuckGoSearchRun()],
    system_prompt="便利なアシスタントです。",
)

モデル設定

Strands
LangChain

デフォルトではStrandsエージェントはClaude 4 Sonnetを使用しますが、モデルプロバイダーをカスタマイズできます。設定オプションについてはStrandsドキュメントのモデルプロバイダーを参照してください：

from strands import Agent
from strands.models import BedrockModel

# BedrockModelの作成
bedrock_model = BedrockModel(
    model_id="anthropic.claude-sonnet-4-20250514-v1:0",
    region_name="us-west-2",
    temperature=0.3,
)

agent = Agent(model=bedrock_model)

LangChainエージェントはChatBedrockConverseモデルを使用します。生成されたエージェントはMODEL_IDとAWS_REGION環境変数からモデルIDとリージョンを読み取りますが、agent.pyで直接モデルを設定することもできます：

from langchain_aws import ChatBedrockConverse

model = ChatBedrockConverse(
    model="anthropic.claude-sonnet-4-20250514-v1:0",
    region_name="us-west-2",
    temperature=0.3,
)

MCPサーバーの利用

py#mcp-serverやts#mcp-serverジェネレーターで作成したMCPサーバーを利用する場合、connectionジェネレーターを使用できます。これにより、両方のフレームワークでMCPサーバーのツールがエージェントに接続されます。

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またはLangChainのMCPドキュメントを参照してください。

詳細

エージェントの詳細な作成方法については、StrandsまたはLangChainのドキュメントを参照してください。

プロトコル

エージェントのサーバープロトコルは通信方法を決定します。すべてのオプションはFastAPIで提供されますが、エントリーポイントが異なります：

HTTP（デフォルト）：カスタム/invocationsエンドポイント、CORS、ストリーミングを備えた標準的なFastAPIサーバー。カスタムクライアント統合に最適です。
A2A：FastAPIアプリにマウントされたAgent-to-Agentサーバー（StrandsはStrands A2A Serverを使用し、LangChainはフレームワーク非依存のa2a-sdkを使用します）。エージェントが他のA2A互換エージェントから検出・呼び出し可能である必要がある場合に最適です。
AG-UI：SSE経由のAG-UIプロトコル（Strandsはag-ui-strandsを使用し、LangChainはag-ui-langgraphを使用します）。ReactウェブサイトでのCopilotKitとの直接的なフロントエンド統合に最適です。

サーバーエントリーポイントはフレームワークによって異なります（Strandsはコンテキスト管理されたAgentを生成し、LangChainはコンパイルされたcreate_agentグラフを駆動します）が、各プロトコルの外部契約は同じです。

すべてのプロトコルは、AgentCoreランタイムのヘルスチェック契約用に/pingを公開します。A2Aエージェントはポート9000でリッスンします。HTTPとAG-UIエージェントはポート8080でリッスンします。生成されるDockerfileとインフラストラクチャは自動的に設定されます。

FastAPIサーバー（HTTPプロトコル）

生成されるHTTPサーバーには以下が含まれます：

CORSミドルウェア付きFastAPIアプリケーション設定
エラーハンドリングミドルウェア
OpenAPIスキーマ生成
ヘルスチェックエンドポイント（/ping）
エージェント呼び出しエンドポイント（/invocations）

Pydanticによる呼び出し入出力のカスタマイズ

エージェントの呼び出しエンドポイントはPydanticモデルを使用してリクエストとレスポンスのスキーマを定義・検証します。main.pyでこれらのモデルをカスタマイズしてエージェントの要件に合わせることができます。

入力モデルの定義

デフォルトのInvokeInputモデルはプロンプトを受け取ります。

from pydantic import BaseModel

class InvokeInput(BaseModel):
    prompt: str

このモデルを拡張して、エージェントに必要な追加フィールドを含めることができます。

セッションIDはx-amzn-bedrock-agentcore-runtime-session-id HTTPヘッダーから抽出されます。これはBedrock AgentCore Runtimeセッション契約に準拠しています。ヘッダーが提供されない場合は、フォールバックとしてランダムなUUIDが生成されます。

出力モデルの定義

ストリーミングレスポンスの場合、ジェネレーターはJsonStreamingResponseを提供し、PydanticモデルをJSON Lines形式（application/jsonl）に自動的にシリアライズします。この形式はOpenAPI 3.2のストリーミング仕様と互換性があり、生成されたTypeScriptクライアントとシームレスに連携します。

デフォルトでは、エージェントはエージェントのレスポンステキストを含むStreamChunkオブジェクトを生成します：

class StreamChunk(BaseModel):
    content: str

ニーズに合わせてStreamChunkモデルをカスタマイズできます：

from pydantic import BaseModel

class StreamChunk(BaseModel):
    content: str
    timestamp: str
    token_count: int

FastAPIは現在ストリーミングレスポンスのOpenAPI仕様生成をサポートしていないため、各ストリーミング操作のレスポンスモデルを明示的に設定する必要があります：

@app.post(
    "/invocations",
    response_class=JsonStreamingResponse,
    responses={200: JsonStreamingResponse.openapi_response(StreamChunk)},
)
async def invoke(input: InvokeInput) -> JsonStreamingResponse:
    return JsonStreamingResponse(handle_invoke(input))

FastAPIでのネイティブサポートのための機能リクエストが公開されています。

Bedrock AgentCore Python SDK

ジェネレーターにはPingStatus定数用にBedrock AgentCore Python SDKへの依存関係が含まれています。必要に応じて、FastAPIの代わりにBedrockAgentCoreAppを使用することも簡単ですが、型安全性が失われることに注意してください。

SDKの詳細はドキュメントを参照してください。

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

生成されるmain.pyは、FastAPIアプリにA2Aサーバーをマウントし、/pingも公開します。StrandsエージェントはA2AServerを使用し、LangChainエージェントはコンパイルされたグラフをa2a-sdkのAgentExecutorでラップします。AgentCoreにデプロイされると、エントリーポイントはAppConfigからランタイムのパブリックARNを解決し、エージェントカードで通知します。

ほとんどのユーザーはこのファイルを変更する必要はありません。ツールやシステムプロンプトを変更するにはagent.pyを編集してください。A2Aサーバーは、エージェントのnameとdescriptionからエージェントカード（/.well-known/agent-card.json）を生成します。

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

生成されるmain.pyは、Server-Sent Events（SSE）経由でAG-UIイベントをストリーミングする単一のPOSTエンドポイント、およびAgentCoreランタイムのヘルスチェック用の/pingを公開します。配線はフレームワークによって異なります：

Strands：Agentをag_ui_strands.StrandsAgentでラップし、create_strands_app()を介してFastAPIアプリを作成します。
LangChain：コンパイルされたグラフをag_ui_langgraph.LangGraphAgentでラップし、手作りのFastAPI /invocationsループから提供します。

ほとんどのユーザーはこのファイルを変更する必要はありません。ツールやシステムプロンプトを変更するにはagent.pyを編集してください。

エージェントの実行

ローカル開発

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

これはuv runを使用してBedrock AgentCore Python SDKでAgentを実行します。

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

ジェネレーターは、エージェントとのインタラクティブなターミナルチャットに入る<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が設定されている場合はデプロイされたエージェントに接続します（以下のデプロイされたエージェントとのチャットを参照）。

HTTPエージェントの場合、チャットスクリプトはエージェントのOpenAPI仕様から生成された型安全なTypeScriptクライアントを使用します。ジェネレーターは以下も生成します：

scripts/<your-agent-name>_openapi.py — エージェントのOpenAPI仕様をエクスポートする小さなスクリプト
<your-agent-name>-openapi Nxターゲット（これを実行）
<your-agent-name>-generate-client Nxターゲット（scripts/<your-agent-name>/generated/に型安全なTypeScriptクライアントを生成）

エージェントの入力形状をカスタマイズする場合（例：InvokeInputに新しいフィールドを追加）、エージェント呼び出し時に新しいフィールドを渡すようにchat.tsを更新すると、残りは自動的に機能します。

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

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

エージェント用の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]
}

バンドルとDockerターゲット

Bedrock AgentCore Runtime向けにAgentをビルドするため、プロジェクトにbundleターゲットが追加されます：

uv exportでPython依存関係をrequirements.txtファイルにエクスポート
uv pip installでターゲットプラットフォーム（aarch64-manylinux_2_28）向け依存関係をインストール

Strandsエージェント固有のdockerターゲットも追加され、DockerfileとバンドルされたアーティファクトをDockerコンテキストディレクトリにコピーします。これによりDockerfileがビルド出力と同じ場所に配置され、CDKがAgentRuntimeArtifact.fromAssetを使用してDockerイメージを直接ビルドできるようになります。

Image Scanning

このプロジェクト用にビルドされた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オブザーバビリティドキュメントを参照してください。

エージェントの呼び出し

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

<your-agent-name>-serveターゲット経由でローカル実行中のエージェントを呼び出すには、ローカルエージェントが実行されているポートの/invocationsに単純なPOSTリクエストを送信できます。例えば、curlを使用：

curl -N -X POST http://localhost:8081/invocations \
  -d '{"prompt": "what is 3 + 5?"}' \
  -H "Content-Type: application/json"

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

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を呼び出す正確な方法は、使用する認証方法によって異なります。

IAM
Cognito

IAM認証

IAM認証の場合、リクエストはAWS Signature Version 4（SigV4）を使用して署名する必要があります。

acurl <region> bedrock-agentcore -N -X POST \
'https://bedrock-agentcore.<region>.amazonaws.com/runtimes/<url-encoded-arn>/invocations' \
-d '{"prompt": "what is 3 + 5?"}' \
-H 'Content-Type: application/json'

上記のacurlコマンドの設定詳細についてはこちらをクリック

JWT / Cognito認証

Cognito認証の場合、AuthorizationヘッダーにCognitoアクセストークンを渡します：

curl -N -X POST 'https://bedrock-agentcore.<region>.amazonaws.com/runtimes/<url-encoded-arn>/invocations' \
  -d '{"prompt": "what is 3 + 5?"}' \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <access-token>"

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> \
  --region <region> \
  --query 'AuthenticationResult.AccessToken' \
  --output text

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

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

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.pyをAST変換してリモートA2Aエージェントを@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）フィルターを提供します。生成されたエージェントが使用するモデルにガードレールをアタッチできます：

Strands
LangChain

import os

from strands import Agent
from strands.models import BedrockModel

model = BedrockModel(
    model_id=os.environ.get("MODEL_ID"),
    guardrail_id=os.environ["GUARDRAIL_ID"],
    guardrail_version=os.environ.get("GUARDRAIL_VERSION", "DRAFT"),
)

agent = Agent(model=model)

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

import os

from langchain_aws import ChatBedrockConverse

model = ChatBedrockConverse(
    model=os.environ.get("MODEL_ID"),
    guardrail_config={
        "guardrailIdentifier": os.environ["GUARDRAIL_ID"],
        "guardrailVersion": os.environ.get("GUARDRAIL_VERSION", "DRAFT"),
    },
)