Python Agent

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

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

使用方法

Agentの生成

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

CLI
VSCode

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

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

オプション

パラメータ	型	デフォルト	説明
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	エージェントをホストするインフラストラクチャのタイプ。
session	s3 \| dynamodb-s3 \| in-memory	s3	Agentのセッションを永続化するために使用されるストレージ。LangChainは's3'または'dynamodb-s3'をサポートし、Strandsは's3'をサポートします。'in-memory'は両方で有効です。
preferInstallDependencies	boolean	true	ジェネレーター実行後に依存関係のインストールを優先するかどうか。複数のジェネレーターをバッチ処理する際にインストールを延期する場合はfalseに設定します（後続のジェネレーターがNxプロジェクトグラフを計算できるよう、必要に応じてインストールは実行されます）。最後に一度だけインストールします。

ジェネレーターの出力

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

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

Directoryyour-project/
- Directoryyour_module/
  - Directoryagent/ (or custom name if specified)
    __init__.py Python package initialization
    init.py FastAPI application setup with CORS and error handling middleware
    agent.py Main agent definition with sample tools
    session.py Resolves the framework-specific session persistence implementation
    main.py FastAPI entry point for Bedrock AgentCore Runtime
    Dockerfile Entry point for hosting your agent (excluded when infra is set to None)
- pyproject.toml Updated with Strands dependencies
- project.json Updated with agent serve targets

A2Aプロトコル

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

Directoryyour-project/
- Directoryyour_module/
  - Directoryagent/ (or custom name if specified)
    __init__.py Python package initialization
    agent.py Main agent definition with sample tools
    session.py Resolves the framework-specific session persistence implementation
    main.py A2A server entry point
    Dockerfile Entry point for hosting your agent (excluded when infra is set to None)
- pyproject.toml Updated with framework and A2A dependencies
- project.json Updated with agent serve targets

AG-UIプロトコル

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

Directoryyour-project/
- Directoryyour_module/
  - Directoryagent/ (or custom name if specified)
    __init__.py Python package initialization
    agent.py Main agent definition with sample tools
    session.py Resolves the framework-specific session persistence implementation
    main.py AG-UI server entry point
    Dockerfile Entry point for hosting your agent (excluded when infra is set to None)
- pyproject.toml Updated with framework 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 プロジェクトのビルドターゲットと設定

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

CDK
Terraform

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

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の操作

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

ツールの追加

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

Strands
LangChain

from strands import Agent, tool

@tool
def calculate_sum(numbers: list[int]) -> int:
    """Calculate the sum of a list of numbers"""
    return sum(numbers)

@tool
def get_weather(city: str) -> str:
    """Get weather information for a city"""
    # Your weather API integration here
    return f"Weather in {city}: Sunny, 25°C"

# Add tools to your agent
agent = Agent(
    system_prompt="You are a helpful assistant with access to various tools.",
    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:
    """Calculate the sum of a list of numbers"""
    return sum(numbers)

@tool
def get_weather(city: str) -> str:
    """Get weather information for a city"""
    # Your weather API integration here
    return f"Weather in {city}: Sunny, 25°C"

# Add tools to your agent
agent = create_agent(
    model=ChatBedrockConverse(model=MODEL_ID, region_name=REGION),
    tools=[calculate_sum, get_weather],
    system_prompt="You are a helpful assistant with access to various tools.",
)

事前構築されたツールの使用

Strands
LangChain

Strandsは、strands-toolsパッケージを通じて事前構築されたツールのコレクションを提供します：

from strands_tools import current_time, http_request, file_read

agent = Agent(
    system_prompt="You are a helpful assistant.",
    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="You are a helpful assistant.",
)

モデルの設定

Strands
LangChain

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

from strands import Agent
from strands.models import BedrockModel

# Create a 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サーバーのツールがエージェントに組み込まれます。

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または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は、Bedrock AgentCore Runtimeセッション契約と一致するx-amzn-bedrock-agentcore-runtime-session-id HTTPヘッダーから抽出されます。ヘッダーが提供されない場合、フォールバックとしてランダムな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は、A2Aサーバーを親FastAPIアプリにマウントし、/pingも公開します。Strandsエージェントは、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でラップし、FastAPIのlifespanハンドラー内で構築され（インポート時ではなく、コンテナ/セッション起動時に構築が行われます）、手作りのFastAPI /invocationsループから提供されます。
LangChain：コンパイルされたグラフをag_ui_langgraph.LangGraphAgentでラップし、同じようにlifespan内で構築され、手作りのFastAPI /invocationsループから提供されます。

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

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

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

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ターゲット
scripts/<your-agent-name>/generated/の下に型安全なTypeScriptクライアントを生成する<your-agent-name>-generate-client Nxターゲット

エージェントの入力形状をカスタマイズする場合（例：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へのAgentのデプロイ

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

BundleとDockerターゲット

Bedrock AgentCore Runtime用にAgentをビルドするために、プロジェクトにbundleターゲットが追加されます。これは以下を行います：

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

Agentに固有のdockerターゲットも追加され、Dockerfileとバンドルされたアーティファクトをdockerコンテキストディレクトリにコピーします。これにより、Dockerfileがビルド出力と同じ場所に配置され、CDKがAgentRuntimeArtifact.fromAssetを使用して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フレームワークの場合はStrandsのセッション管理概念、langchainフレームワークの場合はLangGraphのcheckpointer概念です。

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

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

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

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

sessionオプションは、エージェントのLangGraphチェックポインターが会話状態を永続化する方法を制御します：

s3（デフォルト）：デプロイされたエージェントは、プロビジョニングされたセッションバケットでS3CheckpointSaverを使用し、checkpoints/プレフィックスの下にチェックポイントと保留中の書き込みを保存します。このクラスは、共有エージェント接続プロジェクトのs3_checkpoint_saver_langchain.pyにあります。
dynamodb-s3：CDK/Terraformインフラストラクチャは、チェックポイント用のDynamoDBテーブルをプロビジョニングし、LangGraphエージェントのチェックポイントストアとしてDynamoDBを使用することに関するAWSドキュメントで推奨されているように設定されます（統一されたPK/SKスキーマ、PAY_PER_REQUEST課金、ポイントインタイムリカバリ、およびttl属性）、さらに350KBを超えるチェックポイントをオフロードするためのS3バケット。両方とも専用のKMSキーで暗号化されます。バケットのサーバーアクセスログは、同じキーを介してCloudWatch Logsロググループに配信されます。エージェントのIAMロールには、テーブルとバケットへの読み取り/書き込みアクセスが付与され、テーブル/バケット名はAppConfigランタイム設定でエージェントのARNと一緒に登録されます。
in-memory：テーブルまたはバケットはプロビジョニングされません。会話状態は、実行中のプロセスの存続期間中のみメモリに保持され、再起動やスケールインには耐えられません。

これは、生成されたsession.pyに実装されており、agent.pyのcreate_agent(..., checkpointer=get_checkpointer())から呼び出されるget_checkpointer()関数をエクスポートします。

Agentの呼び出し

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

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

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

デプロイされたAgentの呼び出し

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ウェブサイトからエージェントを呼び出すには、connectionジェネレーターを使用できます。これにより、正しい認証（IAMまたはCognito）を持つクライアントが自動的にセットアップされます。

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 Agentをツールとして呼び出す

このエージェントからリモートA2Aエージェント（TypeScriptまたはPython）に作業を委任するには、connectionジェネレーターを使用します。これにより、ターゲットエージェント用のSigV4認証クライアントが提供され、このエージェントのagent.pyがAST変換されて、リモートA2Aエージェントが@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 Agentの呼び出し

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ジェネレーターガイドを参照してください。

Agentの保護

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

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

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

生成されたサンプルツールのように、ツールに対して厳密な入力スキーマを定義します。自由形式の文字列を受け入れるのではなく、ツールが実際に必要とするもの（列挙型、長さ制限、数値範囲）に値を制約します。
モデルの出力を検証やエンコーディングなしに、シェルコマンド、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）フィルターを提供します。生成されたエージェントが使用するモデルにガードレールをアタッチできます：

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