View a markdown version of this page

環境とファイルシステム - Amazon Bedrock AgentCore
環境でコマンドを実行するカスタム環境 (コンテナイメージ)環境変数ファイルシステム

環境とファイルシステム

すべてのハーネスセッションは、独自のファイルシステムとシェルを持つ分離されたmicroVM で実行されます。このページでは、実行環境 (デフォルトまたはカスタムコンテナ) の設定、VM でのコマンドの直接実行、環境変数の設定、永続ファイルシステムのマウントについて説明します。

環境でコマンドを実行する

すべてがエージェントループを通過する必要はありません。 InvokeAgentRuntimeCommandでは、モデル推論、トークンコスト、あいまいさなしで、決定論的なコマンド実行をハーネスmicroVM に直接シェルアクセスすることができます。

これを使用して、次の操作を行います。

  • 決定論的な呼び出し前または呼び出し後のスクリプトを実行します。

  • 呼び出しの前に環境を準備します。リポジトリのクローン作成、依存関係のインストール、入力ファイルのコピーを行います。

  • エージェントが生成したものに基づいて行動します。テストの実行、コミットとプッシュ、ビルドアーティファクトの抽出です。

  • 開発中に VM を検査します: ls、env、cat。モデルを往復python --versionする必要はありません。

例
AWS CLI/boto3
response = client.invoke_agent_runtime_command(
    agentRuntimeArn=HARNESS_ARN,
    runtimeSessionId=SESSION_ID,
    body={"command": "ls -la /workspace"},
)

for event in response["stream"]:
    chunk = event.get("chunk", {})
    if "contentDelta" in chunk:
        delta = chunk["contentDelta"]
        if "stdout" in delta:
            print(delta["stdout"], end="", flush=True)
        if "stderr" in delta:
            print(delta["stderr"], end="", flush=True)
    elif "contentStop" in chunk:
        print(f"\n[exit code: {chunk['contentStop']['exitCode']}]")
AgentCore CLI
# Install dependencies before the agent starts
agentcore invoke --exec --harness my-agent --session-id "$(uuidgen)" \
  "pip install pandas matplotlib"

# After the agent finishes, inspect what it created
agentcore invoke --exec --harness my-agent --session-id "$(uuidgen)" \
  "ls -la /tmp && cat /tmp/results.csv"
注記

基本環境には Python と bash が含まれています。git、node、またはその他のランタイムなどのツールの場合は、セッションの開始時にインストールするか (例: apt-get install -y git)、カスタム環境を使用します。

TUI で、 !を押して exec モードに入り、コマンドをインラインで実行します。

詳細については、InvokeAgentRuntimeCommand API」を参照してください。

注記

コマンドは、microVM 内で root (uid 0) として実行されます。これは独自の EC2 インスタンスのルートに似ています。IAM アクセス許可はアクセスゲートであり、VM 内権限レベルではありません。Dockerfile に USERディレクティブが含まれている場合、そのディレクティブはエージェントプロセス (コンテナのメインエントリポイント) にのみ適用されます。 InvokeAgentRuntimeCommand は、コンテナが非ルートユーザーとして実行されている場合でも、 docker exec がデフォルトでルートになるのと同様に、運用上の目的でより高い特権レベルで実行されます。セキュリティ、エラー処理、ベストプラクティスの詳細については、AgentCore ランタイムセッションでシェルコマンドを実行する」を参照してください。

カスタム環境 (コンテナイメージ)

基本環境には Python と bash が含まれており、ほとんどのタスクに十分です。さらに必要な場合は、ソースコード、依存関係、ランタイム、ツールをコンテナイメージにパッケージ化し、ECR にプッシュして、ハーネスで参照します。エージェントはその正確な環境で実行されます。カスタムイメージを とペアリングInvokeAgentRuntimeCommandして、呼び出しごとに異なるセッション固有のセットアップを行います。

コンテナイメージはプラットフォーム用に構築する必要がありますlinux/arm64。

ハーネスはコンテナの ENTRYPOINTと を上書きCMDして、環境として実行し続けます。インストールされたソフトウェア、ファイルシステム、および環境変数はエージェントで使用できます。コンテナのスタートアップコマンドは実行されません。バックグラウンドプロセス (開発サーバーなど) が必要な場合は、セッションの開始InvokeAgentRuntimeCommand後に を介して開始します。

例
AWS CLI/boto3
aws bedrock-agentcore-control create-harness \
  --harness-name "CodingAgent" \
  --execution-role-arn "arn:aws:iam::123456789012:role/MyHarnessRole" \
  --environment-artifact '{"containerConfiguration": {"containerUri": "123456789012.dkr.ecr.us-west-2.amazonaws.com/my-dev-env:latest"}}' \
  --system-prompt '[{"text": "You are an expert TypeScript developer."}]'

実行ロールには ECR プルアクセス許可が必要です。詳細については、実行ロールポリシーを参照してください。

AgentCore CLI

Dockerfile を使用してハーネスをスキャフォールドします。

agentcore create --name coding-agent --container ./Dockerfile
agentcore deploy

デプロイ時に、CLI はイメージを構築し、ECR にプッシュしてハーネスにアタッチします。

または、構築済みのイメージを参照します。

agentcore create --name node-agent \
  --container public.ecr.aws/docker/library/node:slim
agentcore deploy

環境変数

ランタイムコンテナに渡される環境変数を設定します。環境変数は、エージェントとセッションで実行されているカスタムコンテナで使用できます。

例
AWS CLI/boto3
aws bedrock-agentcore-control create-harness \
  --harness-name "MyHarness" \
  --execution-role-arn "arn:aws:iam::123456789012:role/MyHarnessRole" \
  --environment-variables '{"MY_API_URL": "https://api.example.com", "LOG_LEVEL": "debug"}'
AgentCore CLI

で環境変数を設定しますharness.json。

{
  "environmentVariables": {
    "MY_API_URL": "https://api.example.com",
    "LOG_LEVEL": "debug"
  }
}

を実行して適用agentcore deployします。

ファイルシステム

ハーネスは、指定したパスに永続的ストレージをマウントします。これらのマウントに書き込まれたファイルはセッション終了後も存続し、後の呼び出しに表示されます。

ハーネスは 3 つのファイルシステムタイプをサポートしています。

  • セッションストレージ - 同じ の停止/再開サイクルにわたって保持される、セッションごとのサービスマネージドストレージruntimeSessionId。VPC は必要ありません。

  • Amazon EFS アクセスポイント - bring-your-own EFS ファイルシステム。セッションとエージェント間で共有されます。VPC が必要です。

  • Amazon S3 Files アクセスポイント bring-your-own S3 バケットと双方向に同期する独自の S3 Files ファイルシステム。VPC が必要です。

前提条件 (VPC ネットワーク、IAM アクセス許可、セキュリティグループ）、タイプ比較、制限、ライフサイクル動作については、AgentCore ランタイムのファイルシステム設定」を参照してください。ハーネスにも同じ要件が適用されます。

AgentCore CLI で環境とファイルシステムを設定する

例
Interactive

プロジェクトディレクトリagentcoreで を実行して TUI を開き、 の追加 を選択し、ハーネス を選択します。このウィザードでは、実行環境と、詳細設定 の永続ファイルシステムを順を追って説明します。

  1. カスタム環境ステップで、デフォルトの環境を維持するか、構築済みのコンテナイメージ (ECR URI) または Dockerfile を選択します。

    ハーネスの追加ウィザード: カスタム環境

  2. ファイルシステムのマウントには VPC モードが必要なため、アドバンスト設定でネットワークとファイルシステムストレージの両方をスペース で有効にし、Enter キーを押します。

    Network and Filesystem Storage を有効にした詳細設定

  3. VPC ネットワークモードを選択し、ハーネスのサブネットとセキュリティグループを指定します。

    VPC ネットワークモードを選択する

  4. セッションストレージのマウントパス ( の下) を設定します/mnt。

    セッションストレージのマウントパスを入力する

  5. Amazon EFS ファイルシステムをアタッチするには、EFS アクセスポイント ARN (および次のステップのマウントパス) を入力します。

    EFS アクセスポイント ARN を入力する

  6. Amazon S3 Files をアタッチするには、S3 Files アクセスポイント ARN (およびそのマウントパス) を入力します。

    S3 Files アクセスポイント ARN を入力する

ウィザードを確認し、 agentcore deployを実行して適用します。

セッションストレージ

マウントパスに書き込まれたファイルは、同じ で を呼び出すと、停止/再開サイクルにわたって保持されますruntimeSessionId。

例
AWS CLI/boto3
aws bedrock-agentcore-control update-harness \
  --harness-id "MyHarness-UuFdkQoXSL" \
  --environment '{"agentCoreRuntimeEnvironment": {"filesystemConfigurations": [{"sessionStorage": {"mountPath": "/mnt/data/"}}]}}'
AgentCore CLI
# At create time
agentcore create --name myagent --session-storage-mount-path /mnt/data/

# Or add to an existing harness
agentcore add harness --name my-agent --session-storage /mnt/data/
agentcore deploy

Amazon EFS アクセスポイント

EFS アクセスポイント ARN を のマウントパスにアタッチします/mnt。データはアカウント内に保持され、同じアクセスポイントをマウントする他のハーネスやエージェントのランタイムと共有できます。

例
AWS CLI/boto3
aws bedrock-agentcore-control create-harness \
  --harness-name "SharedToolsAgent" \
  --execution-role-arn "arn:aws:iam::123456789012:role/MyHarnessRole" \
  --environment '{
    "agentCoreRuntimeEnvironment": {
      "networkConfiguration": {
        "networkMode": "VPC",
        "networkModeConfig": {
          "subnets": ["subnet-abc123", "subnet-def456"],
          "securityGroups": ["sg-abc123"]
        }
      },
      "filesystemConfigurations": [
        {
          "efsAccessPoint": {
            "accessPointArn": "arn:aws:elasticfilesystem:us-west-2:123456789012:access-point/fsap-0123456789abcdef0",
            "mountPath": "/mnt/efs"
          }
        }
      ]
    }
  }'
AgentCore CLI

EFS アクセスポイントを --efs-access-pointとしてアタッチします<accessPointArn>:<mountPath>。EFS には VPC ネットワークモードが必要です。

agentcore add harness --name shared-tools-agent \
  --network-mode VPC \
  --subnets subnet-abc123,subnet-def456 \
  --security-groups sg-abc123 \
  --efs-access-point arn:aws:elasticfilesystem:us-west-2:123456789012:access-point/fsap-0123456789abcdef0:/mnt/efs
agentcore deploy
注記

マウントパスは の下にある必要があります/mnt。フラグは繰り返し可能です (EFS マウントは最大 2 つ）。EFS --network-mode VPC--subnetsおよび S3 ファイルマウントには と --security-groupsが必要です。

Amazon S3 Files アクセスポイント

のマウントパスに S3 Files アクセスポイント ARN をアタッチします/mnt。マウントパスのファイルは、バッキング S3 バケットと双方向に同期します。

例
AWS CLI/boto3
aws bedrock-agentcore-control create-harness \
  --harness-name "DataAgent" \
  --execution-role-arn "arn:aws:iam::123456789012:role/MyHarnessRole" \
  --environment '{
    "agentCoreRuntimeEnvironment": {
      "networkConfiguration": {
        "networkMode": "VPC",
        "networkModeConfig": {
          "subnets": ["subnet-abc123", "subnet-def456"],
          "securityGroups": ["sg-abc123"]
        }
      },
      "filesystemConfigurations": [
        {
          "s3FilesAccessPoint": {
            "accessPointArn": "arn:aws:s3files:us-west-2:123456789012:file-system/fs-0123456789abcdef0/access-point/fsap-0123456789abcdef0",
            "mountPath": "/mnt/s3data"
          }
        }
      ]
    }
  }'
AgentCore CLI

S3 Files アクセスポイントを --s3-access-pointとしてアタッチします<accessPointArn>:<mountPath>。S3 ファイルには VPC ネットワークモードが必要です。

agentcore add harness --name data-agent \
  --network-mode VPC \
  --subnets subnet-abc123,subnet-def456 \
  --security-groups sg-abc123 \
  --s3-access-point arn:aws:s3files:us-west-2:123456789012:file-system/fs-0123456789abcdef0/access-point/fsap-0123456789abcdef0:/mnt/s3data
agentcore deploy
注記

アクセスポイント ARN 自体にはコロンが含まれています。マウントパスは、最後のコロンの後にセグメントから取得されます。フラグは繰り返し可能です (最大 2 つの S3 ファイルマウント）。

重要

UpdateHarness はfilesystemConfigurationsリスト全体を置き換えます。既にファイルシステムが設定されているハーネスに新しいマウントを追加するには、GetHarnessまず を呼び出し、 で必要なリスト全体 (既存のエントリと新しいエントリ) を送信しますUpdateHarness。

詳細: AgentCore ランタイムのファイルシステム設定。

関連トピック