Python エージェント

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

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

使用方法

エージェントの生成

Python エージェントは2つの方法で生成できます:

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

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

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

コマンドを組み立てる9

project必須

framework

authinfra = agentcore | agentcore-ecr

protocol

iac

infra

session

name

preferInstallDependencies

true

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

オプション

ジェネレーターオプション9 オプション

project必須string: Agentを追加するプロジェクト
frameworkenumデフォルト: strands: 使用するエージェントSDK。
strandslangchain
authenuminfra = agentcore | agentcore-ecrデフォルト: iam: エージェントとの認証に使用する方法。infraが設定されている場合にのみ適用されます（infraがnoneの場合は無視されます）。
iamcognito
protocolenumデフォルト: http: Agentのサーバープロトコル。HTTPはFastAPI HTTPサーバーを公開します。A2AはAgent-to-Agentプロトコルサーバーを公開します。AG-UIは直接フロントエンド統合のためのAgent-User Interactionプロトコルサーバーを公開します。
httpa2aag-ui
iacenumデフォルト: inherit: 優先するIaCプロバイダー。デフォルトでは、初期選択から継承されます。
inheritcdkterraform
infraenumデフォルト: agentcore: Agentをホストするインフラストラクチャのタイプ。agentcoreは、最速のビルドとデプロイサイクルのために、コードをzipとしてAgentCore管理ランタイムにデプロイします。agentcore-ecrは、OS レベルの制御や確立されたコンテナパイプラインのために、代わりにコンテナイメージをビルドしてホストします。
agentcoreagentcore-ecrnone
sessionenumデフォルト: s3: Agentのセッションを永続化するために使用されるストレージ。LangChainは's3'または'dynamodb-s3'をサポートし、Strandsは's3'をサポートします。'in-memory'は両方で有効です。
s3dynamodb-s3in-memory
namestring: Agentの名前（デフォルト: agent）
preferInstallDependenciesbooleanデフォルト: 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
    Directorymiddleware/
    __init__.py Python package initialization
    session_id_middleware.py Binds the inbound AgentCore session ID for the request
    main.py FastAPI entry point for Bedrock AgentCore Runtime
    Dockerfile Container image definition (only when infra is agentcore-ecr)
- 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
    Directorymiddleware/
    __init__.py Python package initialization
    session_id_middleware.py Binds the inbound AgentCore session ID for the request
    main.py A2A server entry point
    Dockerfile Container image definition (only when infra is agentcore-ecr)
- pyproject.toml Updated with framework and A2A dependencies
- project.json Updated with agent serve targets

AG-UI プロトコル

エントリーポイントは AG-UI プロトコルを介して CopilotKit とのフロントエンド直接統合のためにエージェントを公開します。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
    Directorymiddleware/
    __init__.py Python package initialization
    session_id_middleware.py Binds the inbound AgentCore session ID for the request
    main.py AG-UI server entry point
    Dockerfile Container image definition (only when infra is agentcore-ecr)
- pyproject.toml Updated with framework and AG-UI dependencies
- project.json Updated with agent serve targets

インフラストラクチャ

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

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

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

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

CDK
Terraform

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

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

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

CDK
Terraform

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

Directorypackages/common/terraform/src
- Directoryapp
  - Directoryagents
    Directory<agent-name>
    <agent-name>.tf Module for deploying your agent
- Directorycore
  - Directoryagent-core
    runtime.tf Generic module for deploying to Bedrock AgentCore Runtime
  - Directoryagent-core-code (when infra is agentcore)
    runtime.tf Packages your agent’s code and delegates to agent-core
  - Directoryagent-core-container (when infra is agentcore-ecr)
    runtime.tf Builds and publishes your agent’s image and delegates to agent-core

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

アーキテクチャ

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

Loading the diagram…

infra: agentcore-ecrの場合、エージェントはコンテナイメージにビルドされ、Amazon ECRにプッシュされ、AgentCore Runtimeで実行されます。これにより、上記のzipパッケージングよりもビルドとデプロイサイクルが長くなる代わりに、ランタイム環境をOSレベルで制御できます。

Loading the diagram…

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

Loading the diagram…

エージェントの操作

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

ツールの追加

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

ツールを定義してから、get_agent() 内の tools リストに追加します:

Strands
LangChain

from contextlib import contextmanager

from strands import Agent, tool
from strands.hooks import HookCallback, HookProvider
from strands_tools import current_time
from my_scope_agent_connection import log_model_errors, log_tool_errors

from .session import get_session_manager


@tool
def subtract(a: int, b: int) -> int:
    return a - b


@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"


AGENT_HOOKS: list[HookProvider | HookCallback] = [log_model_errors, log_tool_errors]


@contextmanager
def get_agent():
    yield Agent(
        name="MyAgent",
        description="MyAgent Strands Agent",
        system_prompt="You are a helpful assistant with access to various tools.",
        tools=[subtract, current_time, get_weather],
        hooks=AGENT_HOOKS,
        session_manager=get_session_manager(),
    )

import os

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

from .session import get_checkpointer

REGION = os.environ.get("AWS_REGION", "us-east-1")
MODEL_ID = os.environ.get("MODEL_ID", "global.anthropic.claude-haiku-4-5-20251001-v1:0")


@tool
def subtract(a: int, b: int) -> int:
    """Subtract b from a."""
    return a - b


@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"


def get_agent():
    model = ChatBedrockConverse(model=MODEL_ID, region_name=REGION)
    return create_agent(
        model=model,
        tools=[subtract, get_weather],
        system_prompt="You are a helpful assistant with access to various tools.",
        checkpointer=get_checkpointer(),
    )

Strandsは strands-agents-tools パッケージを通じて事前構築済みツールのコレクションを提供しています。ジェネレーターはすでにこれをプロジェクトの pyproject.toml に追加しています。必要なツールをインポートして get_agent() に追加します:

from strands_tools import current_time, file_read, http_request

# ...

@contextmanager
def get_agent():
    yield Agent(
        name="MyAgent",
        description="MyAgent Strands Agent",
        system_prompt="You are a helpful assistant.",
        tools=[current_time, file_read, http_request],
        hooks=AGENT_HOOKS,
        session_manager=get_session_manager(),
    )

LangChainは大規模なツールと統合のエコシステムを提供しており、それぞれが独自のパッケージで配布されています。ジェネレーターはこれらを追加しないため、まず必要なものをインストールしてください — 例えば、以下の検索ツールが含まれる langchain-community:

pnpm nx run <project-name>:add langchain-community

yarn nx run <project-name>:add langchain-community

npx nx run <project-name>:add langchain-community

bunx nx run <project-name>:add langchain-community

次にツールをインポートして get_agent() に追加します:

from langchain_community.tools import DuckDuckGoSearchRun

# ...

def get_agent():
    model = ChatBedrockConverse(model=MODEL_ID, region_name=REGION)
    return create_agent(
        model=model,
        tools=[DuckDuckGoSearchRun()],
        system_prompt="You are a helpful assistant.",
        checkpointer=get_checkpointer(),
    )

モデルの設定

Strands
LangChain

生成されたエージェントはAmazon Bedrock上のデフォルトのStrandsモデルを使用します。設定するには、Agent に model を渡します。利用可能なプロバイダーとそのオプションについては、Strandsのモデルプロバイダーに関するドキュメントを参照してください:

from strands.models import BedrockModel

# ...

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

@contextmanager
def get_agent():
    yield Agent(
        model=MODEL,
        name="MyAgent",
        description="MyAgent Strands Agent",
        system_prompt="You are a helpful assistant.",
        tools=[subtract, current_time],
        hooks=AGENT_HOOKS,
        session_manager=get_session_manager(),
    )

LangChainエージェントは ChatBedrockConverse モデルを使用します。生成されたエージェントは MODEL_ID および AWS_REGION 環境変数からモデルIDとリージョンを読み取ります。これらはインフラストラクチャがデプロイされたエージェント用に設定します。モデルをさらに設定するには、get_agent() 内で構築される場所に引数を追加します:

# ...

def get_agent():
    model = ChatBedrockConverse(
        model=MODEL_ID,
        region_name=REGION,
        temperature=0.3,
    )
    return create_agent(
        model=model,
        tools=[subtract],
        system_prompt="You are a helpful assistant.",
        checkpointer=get_checkpointer(),
    )

MCPサーバーの利用

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

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

CLI
VSCode

$ pnpm nx g @aws/nx-plugin:connection

$ yarn nx g @aws/nx-plugin:connection

$ npx nx g @aws/nx-plugin:connection

$ bunx nx g @aws/nx-plugin:connection

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

コマンドを組み立てる5

sourceProject必須

targetProject必須

sourceComponent

targetComponent

preferInstallDependencies

true

--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 でリッスンします。生成されたインフラストラクチャは自動的に設定されます。

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

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

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

Pydanticを使った呼び出し入出力のカスタマイズ

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

入力モデルの定義

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

from pydantic import BaseModel, Field

class InvokeInput(BaseModel):
    prompt: str = Field(max_length=100000)

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

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

出力モデルの定義

ストリーミングレスポンスの場合、ジェネレーターはPydanticモデルをJSON Lines形式（application/jsonl）に自動シリアライズする JsonStreamingResponse を提供します。この形式は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 は、/ping も公開する親FastAPIアプリにA2Aサーバーをマウントします。StrandsエージェントはStrands A2AServer を使用し、LangChainエージェントはコンパイルされたグラフを a2a-sdk AgentExecutor でラップします。エージェントカードにアドバタイズされるURLは AGENTCORE_RUNTIME_URL 環境変数から取得され、ローカル開発では http://localhost:<port>/ にフォールバックします。

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

エージェントの実行

ローカル開発

エージェント（およびそれに接続されているすべてのもの）をローカルで実行するには、プロジェクトの 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 でエージェントを実行します。

エージェントは生成時にワークスペースプールから割り当てられたポートでリッスンします。プロジェクトの project.json の metadata.ports から、または <your-agent-name>-dev ターゲットのコマンドの --port フラグから読み取ることができます。以下の例では、新しいワークスペースで最初のHTTPエージェントに割り当てられるポート 8081 を使用しています。

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

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

ジェネレーターはエージェントとのインタラクティブなターミナルチャットに入るための <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仕様をエクスポートする小さなスクリプト（エージェント名を snake_case で命名）
それを実行する <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へのエージェントのデプロイ

Infrastructure as Code

infra に agentcore または agentcore-ecr を選択した場合、関連する 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 モジュールに渡します。デフォルトの agentcore パッケージングでは、エージェントのコードは共有アセットバケットにステージングされるため、Lambda および API モジュールがすでに行っているように、デプロイメントごとに core/asset-bucket モジュールを一度インスタンス化します:

module "asset_bucket" {
  source = "../../common/terraform/src/core/asset-bucket"
}

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

  asset_bucket_name = module.asset_bucket.bucket_name
  asset_bucket_arn  = module.asset_bucket.bucket_arn
}

agentcore-ecr では、エージェントのイメージが代わりに共有アセットレジストリに公開されるため、バケットではなく core/asset-ecr の出力を渡します。1つのレジストリがワークスペース内のすべてのコンテナにサービスを提供するため、エージェントは独自のリポジトリを必要としません:

module "asset_ecr" {
  source = "../../common/terraform/src/core/asset-ecr"
}

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

  asset_ecr_repository_url = module.asset_ecr.repository_url
  asset_ecr_repository_arn = module.asset_ecr.repository_arn
}

認証

ジェネレーターは 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);
  }
}

module "asset_bucket" {
  source = "../../common/terraform/src/core/asset-bucket"
}

# 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

  # Under `agentcore-ecr`, pass `core/asset-ecr`'s outputs instead.
  asset_bucket_name = module.asset_bucket.bucket_name
  asset_bucket_arn  = module.asset_bucket.bucket_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向けにエージェントをビルドするために、プロジェクトに bundle ターゲットが追加されます。これは以下を行います:

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

<your-agent-name>-package ターゲットも追加されます。これはデプロイ可能なコードパッケージを組み立てます: aarch64 依存関係バンドル、Pythonモジュールツリー、およびルート main.py エントリーポイント。生成されたインフラストラクチャはこのディレクトリを .zip としてアップロードします — CDKでは AgentRuntimeArtifact.fromCodeAsset を介して、Terraformでは共有アセットバケットにアーカイブされます。

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

イメージスキャン

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

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

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

オブザーバビリティ

エージェントは AWS Distro for Open Telemetry（ADOT）を使用したオブザーバビリティが自動的に設定されます。

CloudWatch AWSコンソールでトレースを確認できます。メニューで「GenAI Observability」を選択してください。トレースを表示するには Transaction Search を有効にする必要があります。

詳細については、オブザーバビリティに関するAgentCoreドキュメントを参照してください。

セッション管理

session オプションは、選択したフレームワークによって異なる基盤となる永続化概念にマッピングされます: strands フレームワークの場合はStrandsのセッション管理概念、langchain フレームワークの場合はLangGraphのチェックポインター概念です。

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

s3（デフォルト）: CDK/Terraformインフラストラクチャはセッションデータ用の専用S3バケットをプロビジョニングします。専用KMSキーで暗号化され、すべてのパブリックアクセスがブロックされます。サーバーアクセスログは同じキーを介してCloudWatch Logsロググループに配信されます。エージェントのIAMロールにはバケットへの読み取り/書き込み/一覧/削除アクセスとキーへの復号/データキー生成アクセスが付与され、バケット名はエージェントのARNとともにAppConfigランタイム設定に登録されます。
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クライアントを含め、コール全体で一貫したセッションが共有されます。

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

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

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

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

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

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ロールにはテーブルとバケットへの読み取り/書き込みアクセスが付与され、テーブル/バケット名はエージェントのARNとともにAppConfigランタイム設定に登録されます。
in-memory: テーブルもバケットもプロビジョニングされません。会話状態は実行中のプロセスの存続期間中のみメモリに保持され、再起動やスケールインでは保持されません。

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

エージェントの呼び出し

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

<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

次に、ローカルエージェントが実行されているポートの /invocations にPOSTリクエストを送信します。エージェントに割り当てられたポートを置き換えてください — プロジェクトの project.json の metadata.ports から、または <your-agent-name>-dev ターゲットのコマンドの --port フラグから読み取ることができます。新しいワークスペースの最初のHTTPエージェントには 8081 が割り当てられます:

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'

Click here for more details on configuring the above acurl command

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

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

CLI
VSCode

$ pnpm nx g @aws/nx-plugin:connection

$ yarn nx g @aws/nx-plugin:connection

$ npx nx g @aws/nx-plugin:connection

$ bunx nx g @aws/nx-plugin:connection

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

コマンドを組み立てる5

sourceProject必須

targetProject必須

sourceComponent

targetComponent

preferInstallDependencies

true

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

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

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

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

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

CLI
VSCode

$ pnpm nx g @aws/nx-plugin:connection

$ yarn nx g @aws/nx-plugin:connection

$ npx nx g @aws/nx-plugin:connection

$ bunx nx g @aws/nx-plugin:connection

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

コマンドを組み立てる5

sourceProject必須

targetProject必須

sourceComponent

targetComponent

preferInstallDependencies

true

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

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

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

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

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

CLI
VSCode

$ pnpm nx g @aws/nx-plugin:connection

$ yarn nx g @aws/nx-plugin:connection

$ npx nx g @aws/nx-plugin:connection

$ bunx nx g @aws/nx-plugin:connection

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

コマンドを組み立てる5

sourceProject必須

targetProject必須

sourceComponent

targetComponent

preferInstallDependencies

true

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

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

エージェントのセキュリティ保護

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

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

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

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

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

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

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

キルスイッチを提供する

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

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

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

機密データを保護する

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

Amazon Bedrock Guardrails

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

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

guardrail_config フィールドについては ChatBedrockConverse ドキュメントを参照してください。

接続

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

React to Python AgentCall a Python Agent from a React website

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

Python Agent to MCPConnect a Python Agent to an MCP server

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

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

Python Agent to Python DynamoDBConnect a Python Agent to a DynamoDB table

Python Agent to AgentCore GatewayConnect a Python Agent to an AgentCore Gateway

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