翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。
# CLI または SDK AWS を使用してインスタンスの使用を開始する
このチュートリアルでは、 AWS コマンドラインインターフェイス (AWS CLI) と SDKs **を使用して、インスタンス**コンピューティングタイプでエージェントをホストする方法について説明します。まず、Amazon Elastic Compute Cloud (Amazon EC2) インフラストラクチャを定義する[キャパシティープロバイダー](runtime-instances-how-it-works.md#runtime-instances-capacity-provider)を作成し、それを使用するエージェントランタイムを作成して、最後にエージェントを呼び出します。
前提条件については、[「インスタンスの使用を開始する](runtime-instances-getting-started.md)」を参照してください。
**注記**
これらの例のパラメータ名は、AgentCore コントロールプレーンモデルに従います。信頼できるリクエストとレスポンスの形状については、[「Amazon Bedrock AgentCore Control API リファレンス](https://docs.aws.amazon.com/bedrock-agentcore-control/latest/APIReference/Welcome.html)」を参照してください。
## ステップ 1: キャパシティープロバイダーを作成する
`CreateCapacityProvider` オペレーションを使用して EC2 インフラストラクチャを定義します。リクエストは、 `permissionsConfiguration` (AgentCore がキャパシティープロバイダーの運用に使用する IAM ロール) と、起動テンプレートを介して EC2 インスタンスを記述`computeConfiguration`する を受け取ります。次の例では、単一の許可されたインスタンスタイプと永続的な EBS ボリュームを持つ Linux キャパシティープロバイダーを作成します。
**Example**
1.
```
aws bedrock-agentcore-control create-capacity-provider \
--name "my_capacity_provider" \
--permissions-configuration '{
"capacityProviderOperatorRoleArn": "arn:aws:iam::111122223333:role/AgentCoreCapacityProviderOperatorRole"
}' \
--compute-configuration '{
"ec2Configuration": {
"launchTemplateSource": {
"launchParameters": {
"operatingSystem": "LINUX_X86_64",
"instanceRequirements": {
"allowedInstanceTypes": ["m5.large"]
}
}
},
"vpcConfiguration": {
"subnets": ["subnet-0123456789abcdef0"],
"securityGroups": ["sg-0123456789abcdef0"]
},
"lifecycleConfiguration": {
"maxLifetime": 3600
},
"volumes": [
{ "ebsConfiguration": { "name": "scratch", "sizeGiB": 50, "volumeType": "gp3" } }
]
}
}'
```
1. boto3 を使用してキャパシティープロバイダーを作成する Python の例。
```
import boto3
client = boto3.client("bedrock-agentcore-control", region_name="us-west-2")
response = client.create_capacity_provider(
name="my_capacity_provider",
permissionsConfiguration={
"capacityProviderOperatorRoleArn": "arn:aws:iam::111122223333:role/AgentCoreCapacityProviderOperatorRole"
},
computeConfiguration={
"ec2Configuration": {
"launchTemplateSource": {
"launchParameters": {
"operatingSystem": "LINUX_X86_64",
"instanceRequirements": {
"allowedInstanceTypes": ["m5.large"],
},
}
},
"vpcConfiguration": {
"subnets": ["subnet-0123456789abcdef0"],
"securityGroups": ["sg-0123456789abcdef0"],
},
"lifecycleConfiguration": {
"maxLifetime": 3600,
},
"volumes": [
{"ebsConfiguration": {"name": "scratch", "sizeGiB": 50, "volumeType": "gp3"}}
],
}
},
)
print(f"Capacity provider ARN: {response['capacityProviderArn']}")
```
GPU ワークロードを実行するには、サポートされている GPU インスタンスタイプを に含めます`allowedInstanceTypes`。AgentCore はインスタンスに GPU ドライバーをプロビジョニングするため、標準のコンテナイメージはドライバーをバンドルせずに動作します。サポートされているファミリーは、`g4dn`、、`g5`、`g6`、`g6e`、`gr6`、`g6f``gr6f``g7e`、、および です`inf2`。サポートされていないファミリーのアクセラレーターインスタンスタイプを含めると、リクエストは で失敗します`ValidationException`。詳細については、[「GPU インスタンスタイプ](runtime-instances-how-it-works.md#runtime-instances-gpu)を使用する」を参照してください。
キャパシティープロバイダーをランタイムに関連付ける`READY`前に、ステータスが `GetCapacityProvider`になるまでポーリングします。ステータスが になった場合は`CREATE_FAILED`、 `statusCode`と を調べ`statusReason`て原因を特定します。
## ステップ 2: キャパシティープロバイダーでエージェントランタイムを作成する
キャパシティープロバイダーを参照`capacityProviderConfiguration`する を使用してエージェントランタイムを作成します。キャパシティープロバイダーで定義されたボリュームをエージェントのファイルシステムにマウントするには、ボリュームを名前で参照`filesystemConfigurations`する`capacityProviderVolume`エントリを に追加します。マウントパスは、単一のサブディレクトリ ( など) `/mnt`を持つ の下にある必要があります`/mnt/scratch`。
エージェントランタイムには独自の があり`lifecycleConfiguration.maxLifetime`、デフォルトは 28800 秒 (8 時間) です。この値は、キャパシティープロバイダーが で設定`maxLifetime`する 以下である必要があります`ec2Configuration.lifecycleConfiguration`。ステップ 1 のキャパシティープロバイダーは、その値を 3600 秒 (1 時間) に設定するため、ランタイムのデフォルトである 8 時間はそれを超え、 で失敗`CreateAgentRuntime`します`ValidationException`。したがって、次の例では、キャパシティープロバイダーの制限内にあるランタイムを `maxLifetime` 1800 秒に設定します。
**注記**
どちらのリソースも`lifecycleConfiguration`メンバーを使用しますが、構造は異なります。キャパシティープロバイダーのバージョンは `idleInstanceTimeout` `maxLifetime`および を受け取り、インスタンスに適用されます。エージェントランタイムのバージョンは `idleRuntimeSessionTimeout` を受け取り`maxLifetime`、セッションに適用されます。詳細については、[「Amazon Bedrock AgentCore ライフサイクル設定の構成](runtime-lifecycle-settings.md)」を参照してください。
を指定する`networkConfiguration`ときは、 を渡さないでください`capacityProviderConfiguration`。インスタンスランタイムは、キャパシティープロバイダーの からネットワークを継承するため`ec2Configuration.vpcConfiguration`、両方の指定は で失敗します`ValidationException`。
**Example**
1.
```
aws bedrock-agentcore-control create-agent-runtime \
--agent-runtime-name "my_instances_agent" \
--role-arn "arn:aws:iam::111122223333:role/AgentRuntimeRole" \
--agent-runtime-artifact '{
"containerConfiguration": {
"containerUri": "111122223333.dkr.ecr.us-west-2.amazonaws.com/my-agent:latest"
}
}' \
--capacity-provider-configuration '{
"capacityProviderArn": "arn:aws:bedrock-agentcore:us-west-2:111122223333:capacity-provider/my_capacity_provider-a1b2c3d4e5"
}' \
--lifecycle-configuration '{
"idleRuntimeSessionTimeout": 300,
"maxLifetime": 1800
}' \
--filesystem-configurations '[
{
"capacityProviderVolume": { "volumeName": "scratch", "mountPath": "/mnt/scratch" }
}
]'
```
1. boto3 を使用してインスタンスにエージェントランタイムを作成する Python の例。
```
import boto3
client = boto3.client("bedrock-agentcore-control", region_name="us-west-2")
response = client.create_agent_runtime(
agentRuntimeName="my_instances_agent",
roleArn="arn:aws:iam::111122223333:role/AgentRuntimeRole",
agentRuntimeArtifact={
"containerConfiguration": {
"containerUri": "111122223333.dkr.ecr.us-west-2.amazonaws.com/my-agent:latest"
}
},
capacityProviderConfiguration={
"capacityProviderArn": "arn:aws:bedrock-agentcore:us-west-2:111122223333:capacity-provider/my_capacity_provider-a1b2c3d4e5",
},
lifecycleConfiguration={
"idleRuntimeSessionTimeout": 300,
"maxLifetime": 1800,
},
filesystemConfigurations=[
{
"capacityProviderVolume": {"volumeName": "scratch", "mountPath": "/mnt/scratch"}
}
],
)
print(f"Agent runtime ARN: {response['agentRuntimeArn']}")
```
## ステップ 3: エージェントを呼び出す
microVM-backed ランタイムと同じ方法でランタイムを呼び出します。呼び出し`runtimeSessionId`間で同じ を再利用して、セッションを同じインスタンスに保持します。これにより、エージェントは以前の呼び出しのデータにアクセスできます。コラボレーションエージェントを共同配置するには、キャパシティープロバイダーを共有する複数のランタイム`runtimeSessionId`で同じ を使用します。
**Example**
1.
```
echo '{"prompt": "Analyze the sales data and summarize the key trends."}' > payload.json
aws bedrock-agentcore invoke-agent-runtime \
--agent-runtime-arn "arn:aws:bedrock-agentcore:us-west-2:111122223333:runtime/my_instances_agent-suffix" \
--runtime-session-id "project-xyz-0000000000000000000000000000" \
--qualifier "DEFAULT" \
--payload fileb://payload.json \
response.json
```
`payload` パラメータはバイナリ BLOB であり、CLI AWS は BLOB がデフォルトで base64 でエンコードされることを想定しています。などの raw JSON をインラインで渡すと`--payload '{"prompt": "…"}'`、リクエストがサービスに到達する前にクライアント側で`Invalid base64`エラーが発生して失敗します。ここで使用する`fileb://`フォームは、`cli_binary_format`設定に関係なくファイルをバイナリとして読み取るため、エンコードステップを回避します。
エージェントのレスポンスは、最後の引数として名前を付けた出力ファイルに CLI AWS が書き込むストリーミング BLOB です。この例では です`response.json`。標準出力には `runtimeSessionId`、`contentType`、および `statusCode`フィールドのみが含まれるため、出力ファイルを読んでエージェントが返した内容を確認してください。
AWS SDK
1. boto3 を使用してインスタンスでエージェントランタイムを呼び出す Python の例。
```
import boto3
import json
client = boto3.client("bedrock-agentcore", region_name="us-west-2")
response = client.invoke_agent_runtime(
agentRuntimeArn="arn:aws:bedrock-agentcore:us-west-2:111122223333:runtime/my_instances_agent-suffix",
runtimeSessionId="project-xyz-0000000000000000000000000000", # 33+ chars; reuse to keep the session
payload=json.dumps({"prompt": "Analyze the sales data and summarize the key trends."}).encode(),
qualifier="DEFAULT",
)
print("Agent response:", json.loads(response["response"].read()))
```
は 33 文字以上に`runtimeSessionId`する必要があります。
新しいセッションの最初の呼び出しは、アカウントに EC2 インスタンスをプロビジョニングしてエージェントを起動するため、通常、それ以降の呼び出しよりも時間がかかります。同じセッションへのそれ以降の呼び出しでは、実行中のインスタンスが再利用され、はるかに高速に返されます。
AgentCore は、これらのインスタンスを [Amazon EC2 マネージドインスタンスとしてプロビジョニングします。Amazon EC2 マネージドインスタンス](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/amazon-ec2-managed-instances.html)は、デフォルトで `DescribeInstances`および EC2 コンソールビューに表示されません。プレーン`aws ec2 describe-instances`コールではリストされません。これらを表示するには、 マネージドリソースを含めます。
```
aws ec2 describe-instances --include-managed-resources \
--filters "Name=tag-key,Values=bedrock-agentcore:capacity-provider-id"
```
インスタンスの可視性の管理の詳細については、[「マネージドリソースの可視性設定](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/amazon-ec2-managed-instances.html#managed-resource-visibility-settings)」を参照してください。
## 1 つのインスタンスで複数のエージェントを共同配置する
2 つのエージェントランタイム**が同じ**キャパシティープロバイダーを参照し、**同じ** でそれらを呼び出すと`runtimeSessionId`、両方のエージェントは同じ EC2 インスタンスで実行されます。そこで、ファイルシステム設定で設定されたボリュームを共有できます。エージェントは、その共有ボリュームでファイルを読み書きすることで共同作業を行います。各エージェントは個別に呼び出され、それ以外の場合は 状態を共有しません。たとえば、テストランナーはボリュームに結果を書き込むことができ、同じセッションで呼び出されたコードアナライザーは結果を読み取ることができます。共有インスタンス上のエージェント間の境界については、[「ランタイムインスタンスのセキュリティモデルとアクセス許可](runtime-instances-security.md)」を参照してください。
```
import boto3
import json
client = boto3.client("bedrock-agentcore", region_name="us-west-2")
session_id = "collab-session-000000000000000000000"
# Agent A — created on capacity provider "my_capacity_provider"
client.invoke_agent_runtime(
agentRuntimeArn="arn:aws:bedrock-agentcore:us-west-2:111122223333:runtime/test-runner-suffix",
runtimeSessionId=session_id,
payload=json.dumps({"prompt": "Run the test suite for project ABC"}).encode(),
qualifier="DEFAULT",
)
# Agent B — a different runtime that shares the SAME capacity provider and session ID,
# so it runs on the same instance as Agent A and can read the files Agent A wrote to the shared volume.
client.invoke_agent_runtime(
agentRuntimeArn="arn:aws:bedrock-agentcore:us-west-2:111122223333:runtime/code-analyzer-suffix",
runtimeSessionId=session_id,
payload=json.dumps({"prompt": "Analyze the code for project ABC"}).encode(),
qualifier="DEFAULT",
)
```
各エージェントは、ランタイムの実行ロールから派生した独自の IAM 認証情報を使用して実行されるため、同じインスタンスを共有していても、コラボレーションエージェントに異なるアクセス許可を付与できます。ただし、同じインスタンス上のエージェントは互いに分離されていないため、どのエージェントも別のエージェントの認証情報を読み取ることができます。相互に信頼されているエージェントのみを共同配置します。詳細については、[「ランタイムインスタンスのセキュリティモデルとアクセス許可](runtime-instances-security.md)」を参照してください。
## クリーンアップ: セッションの停止と削除
**警告**
アカウントでプロビジョニングされた Amazon EC2 インスタンスと Amazon EBS ボリュームの継続的な料金を回避するには、このチュートリアルを完了するときに不要になったセッションとキャパシティープロバイダーを削除します。
セッションは同じインスタンスで複数のエージェントランタイムをホストできるため、AgentCore は 2 つの異なるオペレーションを提供します。
+ **セッション内のエージェントランタイムを停止する – **ランタイム ARN とセッション ID によって識別される、セッション内の単一のエージェントランタイムを`StopRuntimeSession`停止します。同じセッションとインスタンスを共有する他のエージェントランタイムは影響を受けません。
+ **セッションの削除** – はセッション全体`DeleteCapacityProviderSession`を削除し、アカウントで作成された EC2 リソース (インスタンス、ネットワークインターフェイス、永続的な EBS ボリューム) のプロビジョニングを解除するため、インフラストラクチャとストレージのコストの発生を停止します。
セッションで特定のエージェントランタイムを停止するには、ランタイム ARN とセッション ID を使用して [StopRuntimeSession](https://docs.aws.amazon.com/bedrock-agentcore/latest/APIReference/API_StopRuntimeSession.html) オペレーションを呼び出します。
**Example**
1.
```
aws bedrock-agentcore stop-runtime-session \
--agent-runtime-arn "arn:aws:bedrock-agentcore:us-west-2:111122223333:runtime/my_instances_agent-suffix" \
--runtime-session-id "project-xyz-0000000000000000000000000000"
```
1. boto3 を使用してランタイムセッションを停止する Python の例。
```
import boto3
client = boto3.client("bedrock-agentcore", region_name="us-west-2")
client.stop_runtime_session(
agentRuntimeArn="arn:aws:bedrock-agentcore:us-west-2:111122223333:runtime/my_instances_agent-suffix",
runtimeSessionId="project-xyz-0000000000000000000000000000",
)
```
セッションを削除し、永続 EBS ボリュームを含むすべてのリソースのプロビジョニングを解除するには、キャパシティープロバイダー ID とセッション ID `DeleteCapacityProviderSession` を使用して を呼び出します。オペレーションはべき等で非同期です。AgentCore がインスタンスを終了し、ボリュームをバックグラウンドで削除している間、すぐに が返されます。
セッション IDsは呼び出し時に指定する値であり、キャパシティープロバイダーのセッションを一覧表示するオペレーションはありません。後で各セッションを削除できるように、使用した`runtimeSessionId`値を記録します。それらがなくなった場合は、まだ実行中のインスタンスを見つけ、キャパシティープロバイダーを削除してすべてのセッションのプロビジョニングを解除できます。
```
aws ec2 describe-instances --include-managed-resources \
--filters "Name=tag-key,Values=bedrock-agentcore:capacity-provider-id" \
--query 'Reservations[].Instances[?State.Name!=`terminated`].[InstanceId,State.Name]'
```
**Example**
1.
```
aws bedrock-agentcore delete-capacity-provider-session \
--capacity-provider-id "my_capacity_provider-a1b2c3d4e5" \
--session-id "project-xyz-0000000000000000000000000000"
```
1. boto3 を使用してキャパシティープロバイダーセッションを削除する Python の例。
```
import boto3
client = boto3.client("bedrock-agentcore", region_name="us-west-2")
response = client.delete_capacity_provider_session(
capacityProviderId="my_capacity_provider-a1b2c3d4e5",
sessionId="project-xyz-0000000000000000000000000000",
)
print("Session status:", response["status"])
```
## キャパシティープロバイダーを削除する
キャパシティープロバイダーが不要になった場合は、 `DeleteCapacityProvider`オペレーションで削除します。キャパシティープロバイダーを削除すると、関連付けられたすべてのセッションとその永続的ストレージが停止および削除されるため、IDsします。最初にセッションを削除する必要はありません。ただし、キャパシティープロバイダーを参照するランタイムを削除する必要があります。関連するバージョン、エンドポイント、またはランタイムを最初に削除すると、削除リクエストが で失敗します`ValidationException`。オペレーションは非同期です。キャパシティープロバイダーを ID で識別します。
**Example**
1.
```
aws bedrock-agentcore-control delete-capacity-provider \
--capacity-provider-id "my_capacity_provider-a1b2c3d4e5"
```
1. boto3 を使用してキャパシティープロバイダーを削除する Python の例。
```
import boto3
client = boto3.client("bedrock-agentcore-control", region_name="us-west-2")
client.delete_capacity_provider(
capacityProviderId="my_capacity_provider-a1b2c3d4e5",
)
```