Pythonストランドエージェント

AIエージェントをツール付きで構築するためのPython Strands Agentを生成し、オプションでAmazon Bedrock AgentCore Runtimeにデプロイします。

Strandsとは

Strandsは、AIエージェントを構築するための軽量で本番環境対応のPythonフレームワークです。主な特徴：

• 軽量でカスタマイズ可能：シンプルなエージェントループで邪魔になりません
• 本番環境対応：フルオブザーバビリティ、トレーシング、スケール対応のデプロイオプション
• モデル/プロバイダー非依存：様々なプロバイダーのモデルをサポート
• コミュニティ提供ツール：強力なコミュニティ製ツールセット
• マルチエージェント対応：エージェントチームや自律エージェントなどの高度な手法
• 柔軟なインタラクションモード：会話型、ストリーミング、非ストリーミング対応

使用方法

Strandsエージェントの生成

2つの方法でPython Strandsエージェントを生成できます：

VSCode

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

CLI

pnpm

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

yarn

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

npm

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

bun

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

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

pnpm

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

yarn

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

npm

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

bun

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

プロジェクトの前提条件

最初にpy#projectジェネレーターを使用してプロジェクトを作成し、その中にStrandsエージェントを追加してください。

オプション

パラメータ	型	デフォルト	説明
project 必須	string	-	Strands Agentを追加するプロジェクト
computeType	string	BedrockAgentCoreRuntime	Strands Agentをホストするコンピュートのタイプ
name	string	-	Strands Agentの名前（デフォルト: agent）
auth	string	IAM	Strands Agentとの認証に使用する方法。IAM（デフォルト）またはCognitoから選択します。
iacProvider	string	Inherit	優先するIaCプロバイダー。デフォルトでは初期選択から継承されます。

ジェネレーターの出力

既存のPythonプロジェクトに以下のファイルが追加されます：

• Directoryyour-project/

  • Directoryyour_module/

    • Directoryagent/（指定した場合はカスタム名）

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

インフラストラクチャ

サーバーレスデプロイ

computeTypeにNoneを選択した場合、インフラストラクチャコードは生成されません。

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

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

CDK

• Directorypackages/common/constructs

  • Directorysrc

    • Directoryapp/ プロジェクト/ジェネレータ固有のインフラストラクチャ用コンストラクト

      • …
    • Directorycore/ app 内のコンストラクトで再利用される汎用コンストラクト

      • …
    • index.ts app からコンストラクトをエクスポートするエントリーポイント
  • project.json プロジェクトのビルドターゲットと設定

生成されたプロジェクト

このプロジェクトは ts#project ジェネレータを使用して生成されているため、同じビルドターゲットを設定します。

Terraform

• Directorypackages/common/terraform

  • Directorysrc

    • Directoryapp/ プロジェクト/ジェネレータ固有のインフラストラクチャ用Terraformモジュール

      • …
    • Directorycore/ app 内のモジュールで再利用される汎用モジュール

      • …
  • project.json プロジェクトのビルドターゲットと設定

生成されたプロジェクト

このプロジェクトは terraform#project ジェネレータを使用して生成されているため、同じビルドターゲットを設定します。

Strandsエージェントのデプロイ用に以下のファイルが生成されます：

CDK

• Directorypackages/common/constructs/src

  • Directoryapp

    • Directoryagents

      • Directory<project-name>

        • <project-name>.ts エージェントデプロイ用CDKコンストラクト
        • Dockerfile CDKコンストラクトで使用されるDockerfile

Terraform

• Directorypackages/common/terraform/src

  • Directoryapp

    • Directoryagents

      • Directory<project-name>

        • <project-name>.tf エージェントデプロイ用Terraformモジュール
  • Directorycore

    • Directoryagent-core

      • runtime.tf Bedrock AgentCore Runtimeデプロイ用汎用モジュール

Strandsエージェントの操作

ツールの追加

ツールはAIエージェントがアクションを実行するために呼び出す関数です。Strandsフレームワークはデコレータベースのシンプルなアプローチを採用しています。

agent.pyファイルに新しいツールを追加できます：

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],
)

Strandsフレームワークが自動的に処理する機能：

• 関数の型ヒントに基づく型検証
• ツール呼び出し用JSONスキーマ生成
• エラーハンドリングとレスポンスフォーマット

プリビルドツールの使用

strands-toolsパッケージで提供されるプリビルドツール：

from strands_tools import current_time, http_request, file_read

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

モデル設定

デフォルトでは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)

MCPサーバーの利用

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

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

VSCode

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

CLI

pnpm

pnpm nx g @aws/nx-plugin:connection

yarn

yarn nx g @aws/nx-plugin:connection

npm

npx nx g @aws/nx-plugin:connection

bun

bunx nx g @aws/nx-plugin:connection

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

pnpm

pnpm nx g @aws/nx-plugin:connection --dry-run

yarn

yarn nx g @aws/nx-plugin:connection --dry-run

npm

npx nx g @aws/nx-plugin:connection --dry-run

bun

bunx nx g @aws/nx-plugin:connection --dry-run

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

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

詳細

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

FastAPIサーバー

ジェネレーターはFastAPIを使用してStrandsエージェント用のHTTPサーバーを作成します。FastAPIは、自動APIドキュメント生成と型検証を備えた、PythonでAPIを構築するためのモダンで高速なWebフレームワークを提供します。

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

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

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

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

入力モデルの定義

デフォルトのInvokeInputモデルはプロンプトとセッションIDを受け取ります。

from pydantic import BaseModel

class InvokeInput(BaseModel):
    prompt: str
    session_id: str

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

コード整理

ユーザーがエージェントを直接呼び出す場合、呼び出し元からセッションIDの一部または全部を抽象化することをお勧めします。例えば、認証されたユーザーIDをセッションIDの一部として使用できます。

また、ユースケースによってはセッションの認可を実装する必要がある場合があります。例えば、ユーザーが自分のセッションのみにアクセスでき、他のユーザーのセッションにはアクセスできないようにするなどです。

出力モデルの定義

ストリーミングレスポンスの場合、ジェネレーターは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ストリーミングの制限

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

Infrastructure as Code

ジェネレーターがエージェントデプロイを管理するCDK/Terraformインフラストラクチャを生成するため、エージェントデプロイ用にドキュメントで言及されているbedrock-agentcore-starter-toolkitを使用する必要はありません。

Strandsエージェントの実行

ローカル開発

ジェネレーターは<your-agent-name>-serveという名前のターゲットを設定し、開発とテストのためにStrandsエージェントをローカルで起動します。

pnpm

pnpm nx agent-serve your-project

yarn

yarn nx agent-serve your-project

npm

npx nx agent-serve your-project

bun

bunx nx agent-serve your-project

このコマンドはuv runを使用してBedrock AgentCore Python SDKでStrandsエージェントを実行します。

Bedrock AgentCore Runtimeへのデプロイ

Infrastructure as Code

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

CDK

エージェント用のCDKコンストラクトが生成されます。名前はジェネレーター実行時に選択したnameに基づくか、デフォルトでは<ProjectName>Agentになります。

このCDKコンストラクトをCDKアプリケーションで使用できます:

import { MyProjectAgent } from ':my-scope/common-constructs';

export class ExampleStack extends Stack {
  constructor(scope: Construct, id: string) {
    // Add the agent to your stack
    const agent = new MyProjectAgent(this, 'MyProjectAgent');

    // Grant permissions to invoke the relevant models in bedrock
    agent.agentCoreRuntime.addToRolePolicy(
      new PolicyStatement({
        actions: [
          'bedrock:InvokeModel',
          'bedrock:InvokeModelWithResponseStream',
        ],
        // You can scope the below down to the specific models you use
        resources: [
          'arn:aws:bedrock:*:*:foundation-model/*',
          'arn:aws:bedrock:*:*:inference-profile/*',
        ],
      }),
    );
  }
}

Alpha CDKコンストラクト

このコンストラクトは@aws-cdk/aws-bedrock-agentcore-alphaモジュールを使用します。

Terraform

Terraformモジュールが生成されます。名前はジェネレーター実行時に選択したnameに基づくか、デフォルトでは<ProjectName>-agentになります。

このTerraformモジュールをTerraformプロジェクトで使用できます:

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

  # Grant permissions to invoke the relevant models in bedrock
  additional_iam_policy_statements = [
    {
      Effect = "Allow"
      Action = [
        "bedrock:InvokeModel",
        "bedrock:InvokeModelWithResponseStream"
      ]
      # You can scope the below down to the specific models you use
      Resource = [
        "arn:aws:bedrock:*:*:foundation-model/*",
        "arn:aws:bedrock:*:*:inference-profile/*"
      ]
    }
  ]
}

Dockerが必要

Strands AgentをビルドおよびデプロイするにはDockerが必要です。次のようなエラーを回避するために、Dockerがインストールされ起動していることを確認してください:

ERROR: Cannot connect to the Docker daemon at unix://path/to/docker.sock.

認証

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

IAM

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

CDK

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

Terraform

# 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"
}

エージェントを呼び出すアクセス権を付与するには、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

生成されたコンストラクトは、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#react-website#authジェネレーターを使用して生成するか、独自のCDK UserPoolとUserPoolClientを作成できます。

Terraform

生成されたモジュールは、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"

  user_pool_id         = module.user_identity.user_pool_id
  user_pool_client_ids = [module.user_identity.user_pool_client_id]
}

カスタムOIDCプロバイダー

Cognito以外のOIDCプロバイダーを使用したカスタムJWT認証が必要な場合は、エージェント用に生成されたCDKコンストラクトまたはTerraformモジュールを直接変更できます。なお、接続ジェネレーターはIAMまたはCognito認証のみをサポートします。

バンドルとDockerターゲット

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

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

Strandsエージェント固有のdockerターゲットも追加されます：

• AgentCore runtime契約に従ってエージェントを実行するDockerfileからDockerイメージをビルド

Dockerイメージタグ

Dockerイメージはタグ（例：my-scope-my-project-agent:latest）を使用してビルドされ、CDK/Terraformインフラストラクチャで参照されるため、DockerfileをStrandsエージェントプロジェクトと同じ場所に配置できます。

オブザーバビリティ

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

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

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

Strandsエージェントの呼び出し

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

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

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

Curlストリーミングフラグ

curlに与えられる-N引数は出力ストリームのバッファリングを無効にするため、ストリーミングレスポンスをリアルタイムで確認できます。

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

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

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

CDK

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

Terraform

# 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"
}

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

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

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?", "session_id": "abcdefghijklmnopqrstuvwxyz0123456789"}' \
-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?", "session_id": "abcdefghijklmnopqrstuvwxyz0123456789"}' \
  -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