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

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

Strandsとは

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

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

使用方法

Strandsエージェントの生成

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

VSCode
CLI

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

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

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

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

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

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

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

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

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

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

オプション

パラメータ	型	デフォルト	説明
project 必須	string	-	The project to add the Strands Agent to
computeType	string	BedrockAgentCoreRuntime	The type of compute to host your Strands Agent.
name	string	-	The name of your Strands Agent (default: agent)
iacProvider	string	Inherit	The preferred IaC provider. By default this is inherited from your initial selection.

ジェネレーターの出力

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

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

インフラストラクチャ

このジェネレータは選択した iacProvider に基づいて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 プロジェクトのビルドターゲットと設定

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

CDK
Terraform

Directorypackages/common/constructs/src
- Directoryapp
  - Directoryagents
    Directory<project-name>
    <project-name>.ts エージェントデプロイ用CDKコンストラクト
    Dockerfile CDKコンストラクトで使用されるDockerfile
- Directorycore
  - Directoryagent-core
    runtime.ts Bedrock AgentCore Runtimeデプロイ用汎用CDKコンストラクト

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ジェネレーター（またはBedrock AgentCore Runtime上でホストされた他サーバー）で作成したMCPサーバーを利用する場合、agentcore_mcp_client.pyにクライアントファクトリが生成されます。

agent.pyのget_agentメソッドを更新してMCPクライアントを作成しツールを追加できます。IAM（SigV4）認証の例：

import os
from contextlib import contextmanager

import boto3
from strands import Agent

from .agentcore_mcp_client import AgentCoreMCPClient

# リージョンと認証情報の取得
region = os.environ["AWS_REGION"]
boto_session = boto3.Session(region_name=region)
credentials = boto_session.get_credentials()

@contextmanager
def get_agent(session_id: str):
    mcp_client = AgentCoreMCPClient.with_iam_auth(
        agent_runtime_arn=os.environ["MCP_AGENTCORE_RUNTIME_ARN"],
        credentials=credentials,
        region=region,
        session_id=session_id,
    )

    with mcp_client:
        mcp_tools = mcp_client.list_tools_sync()

        yield Agent(
            system_prompt="..."
            tools=[*mcp_tools],
        )

上記のIAM認証例では、インフラストラクチャで2つの設定が必要です。まず、MCPサーバーのAgentCore Runtime ARN用環境変数の追加、次にエージェントにMCPサーバー呼び出し権限の付与が必要です。以下のように実現できます：

CDK
Terraform

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

export class ExampleStack extends Stack {
  constructor(scope: Construct, id: string) {
    const mcpServer = new MyProjectMcpServer(this, 'MyProjectMcpServer');

    const agent = new MyProjectAgent(this, 'MyProjectAgent', {
      environment: {
        MCP_AGENTCORE_RUNTIME_ARN: mcpServer.agentCoreRuntime.arn,
      },
    });

    mcpServer.agentCoreRuntime.grantInvoke(agent.agentCoreRuntime);
  }
}

# MCPサーバー
module "my_project_mcp_server" {
  source = "../../common/terraform/src/app/mcp-servers/my-project-mcp-server"
}

# エージェント
module "my_project_agent" {
  source = "../../common/terraform/src/app/agents/my-project-agent"

  env = {
    MCP_AGENTCORE_RUNTIME_ARN = module.my_project_mcp_server.agent_core_runtime_arn
  }

  additional_iam_policy_statements = [
    {
      Effect = "Allow"
      Action = [
        "bedrock-agentcore:InvokeAgentRuntime"
      ]
      Resource = [
        module.my_project_mcp_server.agent_core_runtime_arn,
        "${module.my_project_mcp_server.agent_core_runtime_arn}/*"
      ]
    }
  ]
}

詳細

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

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

出力モデルの定義

ストリーミングレスポンスの場合、エンドポイントの戻り値の型アノテーションは、ジェネレーター関数が生成する各値の型に対応します。デフォルトでは、エージェントはStrandsからストリーミングバックされるエージェントのレスポンステキストを含む文字列を生成します：

@app.post("/invocations", openapi_extra={"x-streaming": True})
async def invoke(input: InvokeInput) -> str:
    """Entry point for agent invocation"""
    return StreamingResponse(handle_invoke(input), media_type="text/event-stream")

代わりに構造化データを生成するPydanticモデルを定義できます：

from pydantic import BaseModel

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

@app.post("/invocations", openapi_extra={"x-streaming": True})
async def invoke(input: InvokeInput) -> StreamChunk:
    return StreamingResponse(handle_invoke(input), media_type="application/json")

Bedrock AgentCore Python SDK

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

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

Strandsエージェントの実行

ローカル開発

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

pnpm nx run your-project:agent-serve

yarn nx run your-project:agent-serve

npx nx run your-project:agent-serve

bunx nx run your-project:agent-serve

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

Bedrock AgentCore Runtimeへのデプロイ

インフラストラクチャ即コード

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

CDK
Terraform

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

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

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

export class ExampleStack extends Stack {
  constructor(scope: Construct, id: string) {
    // スタックにエージェントを追加
    const agent = new MyProjectAgent(this, 'MyProjectAgent');

    // Bedrockモデル呼び出し権限の付与
    agent.agentCoreRuntime.role.addToPolicy(
      new PolicyStatement({
        actions: [
          'bedrock:InvokeModel',
          'bedrock:InvokeModelWithResponseStream',
        ],
        // 使用する特定のモデルに絞り込むことができます
        resources: ['arn:aws:bedrock:*::foundation-model/*'],
      }),
    );
  }
}

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

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

# エージェント
module "my_project_agent" {
  # common/terraformプロジェクト内の生成されたモジュールへの相対パス
  source = "../../common/terraform/src/app/agents/my-project-agent"

  # Bedrockモデル呼び出し権限の付与
  additional_iam_policy_statements = [
    {
      Effect = "Allow"
      Action = [
        "bedrock:InvokeModel",
        "bedrock:InvokeModelWithResponseStream"
      ]
      Resource = [
        "arn:aws:bedrock:*::foundation-model/*"
      ]
    }
  ]
}

StrandsエージェントのビルドとデプロイにはDockerが必要です。以下のようなエラーを防ぐため、Dockerのインストールと起動を確認してください：

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

バンドルとDockerターゲット

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

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

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

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

認証

IAM

デフォルトでは、StrandsエージェントはIAM認証で保護されます。引数なしでデプロイするだけです：

CDK
Terraform

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

export class ExampleStack extends Stack {
  constructor(scope: Construct, id: string) {
    new MyProjectAgent(this, 'MyProjectAgent');
  }
}

grantInvokeメソッドを使用して、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.agentCoreRuntime.grantInvoke(lambdaFunction);
  }
}

# エージェント
module "my_project_agent" {
  # common/terraformプロジェクト内の生成されたモジュールへの相対パス
  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 JWT認証

以下はエージェントのCognito認証設定方法の例です。

CDK
Terraform

JWT認証を設定するには、エージェントコンストラクトにauthorizerConfigurationプロパティを渡します。以下はエージェントを保護するためにCognitoユーザープールとクライアントを設定する例です：

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

export class ExampleStack extends Stack {
  constructor(scope: Construct, id: string) {
    const userPool = new UserPool(this, 'UserPool');
    const client = userPool.addClient('Client', {
      authFlows: {
        userPassword: true,
      },
    });

    new MyProjectAgent(this, 'MyProjectAgent', {
      authorizerConfiguration: {
        customJwtAuthorizer: {
          discoveryUrl: `https://cognito-idp.${Stack.of(userPool).region}.amazonaws.com/${userPool.userPoolId}/.well-known/openid-configuration`,
          allowedClients: [client.userPoolClientId],
        },
      },
    });
  }
}

JWT認証を設定するには、エージェントモジュールを編集して以下のようにcustomJWTAuthorizer変数を設定します：

data "aws_region" "current" {}

locals {
  aws_region = data.aws_region.current.name

  # ユーザープールとクライアントIDに置き換えるか、変数として公開してください
  user_pool_id = "xxx"
  user_pool_client_ids = ["yyy"]
}

module "agent_core_runtime" {
  source = "../../../core/agent-core"
  agent_runtime_name = "MyProjectAgent"
  docker_image_tag = "my-scope-my-project-agent:latest"
  server_protocol = "HTTP"
  customJWTAuthorizer = {
    discoveryUrl = "https://cognito-idp.${local.aws_region}.amazonaws.com/${local.user_pool_id}/.well-known/openid-configuration",
    allowedClients = local.user_pool_client_ids
  }
  env = var.env
  additional_iam_policy_statements = var.additional_iam_policy_statements
  tags = var.tags
}

オブザーバビリティ

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

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

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