前提条件ステップ 1: AgentCore CLI をインストールするステップ 2: エージェントプロジェクトを作成するステップ 3: エージェントをローカルでテストするステップ 4: エージェントのオブザーバビリティを有効にするステップ 5: Amazon Bedrock AgentCore ランタイムにデプロイするステップ 6: デプロイされたエージェントをテストするステップ 7: デプロイされたエージェントを呼び出すステップ 8: クリーンアップするリソースの検索一般的なの問題と解決策詳細オプション (オプション)

AgentCore CLI の使用を開始する

このチュートリアルでは、AgentCore CLI を使用して Amazon Bedrock AgentCore ランタイムで Python エージェントを作成、デプロイ、および呼び出す方法を示します。

AgentCore CLI は、エージェントプロジェクトをスキャフォールドし、Amazon Bedrock AgentCore ランタイムにデプロイして呼び出すコマンドラインツールです。CLI は、Strands Agents、LangChain/LangGraph、Google ADK、OpenAI Agents などの一般的な Python エージェントフレームワークで使用できます。このチュートリアルでは、ストランドエージェントを使用します。

エージェントが使用する HTTP プロトコルの詳細については、「HTTP プロトコル契約」を参照してください。

トピック

前提条件
ステップ 1: AgentCore CLI をインストールする
ステップ 2: エージェントプロジェクトを作成する
ステップ 3: エージェントをローカルでテストする
ステップ 4: エージェントのオブザーバビリティを有効にする
ステップ 5: Amazon Bedrock AgentCore ランタイムにデプロイする
ステップ 6: デプロイされたエージェントをテストする
ステップ 7: デプロイされたエージェントを呼び出す
ステップ 8: クリーンアップする
リソースの検索
一般的なの問題と解決策
詳細オプション (オプション)

前提条件

開始する前に、以下を確認してください。

AWS 認証情報が設定されたアカウント。 AWS 認証情報を設定するには、AWS CLI の設定と認証情報ファイルの設定を参照してください。
Node.js 20 以上がインストールされている。AgentCore CLI は npm パッケージとして配布されます。
Python 3.10 以降がインストールされている。生成されたエージェントコードは Python です。
AWS CDK がインストールされました。CLI は AWS CDK を使用してリソースをデプロイします。詳細については、AWS 「CDK の開始方法」を参照してください。
アクセス AWS 許可: AgentCore CLI を使用してエージェントを作成してデプロイするには、適切なアクセス許可が必要です。詳細については、AgentCore CLI を使用する」を参照してください。
モデルアクセス: Amazon Bedrock コンソールで Anthropic Claude Sonnet 4.0 が有効になっています (モデルプロバイダーとして Bedrock を使用している場合）。Strands Agents で別のモデルを使用する方法については、「Strands Agents SDK ドキュメント」の「Model Providershttps://strandsagents.com/latest/documentation/docs/」セクションを参照してください。

ステップ 1: AgentCore CLI をインストールする

AgentCore CLI をグローバルにインストールします。


npm install -g @aws/agentcore

インストールを確認します。


agentcore --help

次のような出力が表示されます:


Usage: agentcore [options] [command]

Build and deploy Agentic AI applications on AgentCore

Options:
  -V, --version                output the version number
  -h, --help                   Display help

Commands:
  add [subcommand]             Add resources (agent, evaluator, online-eval,
                               memory, identity, target)
  dev|d [options]              Launch local development server with hot-reload.
  deploy|p [options]           Deploy project infrastructure to AWS via CDK.
  create [options]             Create a new AgentCore project
  evals                        View past eval run results.
  fetch                        Fetch access info for deployed resources.
  help                         Display help topics
  invoke|i [options] [prompt]  Invoke a deployed agent endpoint.
  logs|l [options]             Stream or search agent runtime logs.
  package|pkg [options]        Package agent artifacts without deploying.
  pause                        Pause an online eval config.
  remove [subcommand]          Remove resources from project config.
  resume                       Resume a paused online eval config.
  run                          Run on-demand evaluation.
  status|s [options]           Show deployed resource details and status.
  traces|t                     View and download agent traces.
  update [options]             Check for and install CLI updates
  validate [options]           Validate agentcore/ config files.

ステップ 2: エージェントプロジェクトを作成する

agentcore create コマンドを使用して、新しいエージェントプロジェクトをスキャフォールドします。

例

agentcore create コマンドは、次のフラグを受け入れます。

--name – プロジェクト名 (英数字、先頭は文字、最大 36 文字）。
--framework – エージェントフレームワーク。サポートされている値: Strands 、LangChain_LangGraph、GoogleADK、OpenAIAgents。
--protocol – プロトコルモード。サポートされている値: HTTP (デフォルト)MCP、、A2A。
--build – ビルドタイプ。サポートされている値: CodeZip (デフォルト)Container、。
--model-provider – モデルプロバイダー。サポートされている値: Bedrock 、Anthropic、OpenAI、Gemini。
--memory – メモリ設定。サポートされている値: none 、shortTerm、longAndShortTerm。

コマンドは、次の構造を持つプロジェクトディレクトリを生成します。


MyAgent/
  agentcore/
    agentcore.json        # Project and agent configuration
    aws-targets.json      # AWS account and region targets
    .env.local            # Local environment variables (gitignored)
  app/
    MyAgent/
      main.py             # Agent entrypoint
      pyproject.toml      # Python dependencies
  README.md

agentcore/agentcore.json ファイルには、プロジェクトとエージェントの設定が含まれています。app/MyAgent/main.py ファイルには、選択したフレームワークを使用するスターターエージェントコードが含まれています。

支払い機能をプロジェクトに追加するには、以下を実行します。


agentcore add payment-manager --name MyPayments --auto-payment --default-spend-limit 5.00
agentcore add payment-connector --manager MyPayments --name MyConnector --provider CoinbaseCDP \
  --api-key-id <KEY_ID> --api-key-secret <KEY_SECRET> --wallet-secret <WALLET_SECRET>

これにより、エージェントAgentCorePaymentsPluginでが設定され、デプロイ時に支払いインフラストラクチャがプロビジョニングされます。ワークフロー全体については、「支払いのクイックスタート」を参照してください。

ステップ 3: エージェントをローカルでテストする

にデプロイする前に AWS、開発サーバーを使用してエージェントをローカルでテストします。まず、プロジェクトディレクトリに変更します。


cd MyAgent

API キー (OpenAI、Anthropic、または Gemini) を必要とするモデルプロバイダーを選択した場合は、キーがで設定されていることを確認しますagentcore/.env.local。

ローカル開発サーバーを起動します。

例

agentcore dev コマンド:

ウェブブラウザでエージェントインスペクターを開きます
Python 仮想環境を自動的に作成し、依存関係をインストールする
AgentCore ランタイム環境を模倣するローカルサーバーを起動します
http://localhost:8080 デフォルトではで実行されます (ポートを変更するには -p を使用します)

サーバーログをリアルタイムで表示するには (非インタラクティブモード）、 --logsフラグを使用します。


agentcore dev --logs

別のターミナルで、ローカルエージェントを呼び出します。


agentcore dev "Hello, tell me a joke"

プロンプトを渡すと、実行中のローカル開発サーバーに送信されます。を使用して--stream、リアルタイムでストリーミングされたレスポンスを表示します。

ステップ 4: エージェントのオブザーバビリティを有効にする

Amazon Bedrock AgentCore オブザーバビリティは、Amazon Bedrock AgentCore ランタイムでホストするエージェントをトレース、デバッグ、モニタリングするのに役立ちます。まず、「Amazon Bedrock AgentCore ランタイムオブザーバビリティを有効にする」の手順に従って CloudWatch トランザクション検索を有効にします。エージェントを監視するには、「Amazon Bedrock AgentCore エージェントのオブザーバビリティデータを表示する」を参照してください。

エージェントをデプロイしたら、AgentCore CLI を使用してログをストリーミングし、トレースを表示できます。


# Stream agent logs
agentcore logs

# List recent traces
agentcore traces list

ステップ 5: Amazon Bedrock AgentCore ランタイムにデプロイする

Amazon Bedrock AgentCore ランタイムにエージェントをデプロイします。

例

変更を加えずにデプロイをプレビューするには、 --dry-runフラグを使用します。


agentcore deploy --dry-run

agentcore deploy コマンド:

agentcore/agentcore.json と agentcore/aws-targets.jsonの設定を読み取ります。
エージェントコードをパッケージ化します (ビルドタイプに応じて CodeZip アーカイブまたは Docker コンテナとして)
AWS CDK を使用して CloudFormation リソースを合成およびデプロイします
必要な AWS リソース (IAM ロール、Amazon Bedrock AgentCore ランタイムなど) を作成します。

リソースレベルのデプロイイベントを示す詳細な出力-vにを使用します。を使用して-y、プロンプトなしでデプロイを自動確認します。

デプロイが失敗した場合は、一般的な問題を確認します。

ステップ 6: デプロイされたエージェントをテストする

デプロイが完了したら、デプロイされたエージェントを呼び出します。

例

レスポンスに joke が表示された場合、エージェントは Amazon Bedrock AgentCore ランタイムで実行されており、呼び出すことができます。そうでない場合は、一般的な問題を確認します。

ステップ 7: デプロイされたエージェントを呼び出す

例

AgentCore CLI

デプロイされたエージェントをプロンプトで呼び出します。
```
agentcore invoke --runtime MyAgent "Hello, what can you do?"
```
レスポンスをリアルタイムでストリーミングします。
```
agentcore invoke --runtime MyAgent "Tell me a joke" --stream
```
プロンプトagentcore invokeなしでを実行してインタラクティブチャット TUI を開きます。これにより、デフォルトでレスポンスがストリーミングされ、セッションが自動的に維持されます。

AWS Python SDK (Boto3)

AWS SDK InvokeAgentRuntime オペレーションを使用してエージェントを呼び出すこともできます。デプロイされたエージェントの ARN を取得するには、 agentcore status コマンドを使用します。
```
agentcore status
```
次の boto3 (AWS SDK for Python) コードを使用してエージェントを呼び出します。エージェント ARN をエージェントの ARN に置き換えます。アクセスbedrock-agentcore:InvokeAgentRuntime許可があることを確認します。という名前のファイルを作成しinvoke_agent.py、次のコードを追加します。
```
import json
import uuid
import boto3

agent_arn = "Agent ARN"
prompt = "Tell me a joke"

# Initialize the Amazon Bedrock AgentCore client
agent_core_client = boto3.client('bedrock-agentcore')

# Prepare the payload
payload = json.dumps({"prompt": prompt}).encode()

# Invoke the agent
response = agent_core_client.invoke_agent_runtime(
    agentRuntimeArn=agent_arn,
    runtimeSessionId=str(uuid.uuid4()),
    payload=payload,
    qualifier="DEFAULT"
)

content = []
for chunk in response.get("response", []):
    content.append(chunk.decode('utf-8'))
print(json.loads(''.join(content)))
```
ターミナルウィンドウを開き、次のコマンドを使用してコードを実行します。
```
python invoke_agent.py
```
成功すると、レスポンスに joke が表示されます。呼び出しが失敗した場合は、を使用してログを確認するagentcore logsか、Amazon CloudWatch でログを表示します。

注記
エージェントを OAuth と統合する場合は、 AWS SDK を使用して InvokeAgentRuntime を呼び出すことはできません。代わりに、に HTTPS InvokeAgentRuntime リクエストを行います。詳細については、「インバウンド認証とアウトバウンド認証による認証と認可」を参照してください。

ステップ 8: クリーンアップする

Amazon Bedrock AgentCore ランタイムでエージェントをホストする必要がなくなった場合は、デプロイされた AWS リソースを削除します。まず、ローカル設定からすべてのリソースを削除します。

例

次に、再度デプロイして AWS リソースを削除します。

例

remove all コマンドは、 agentcore/aws-targets.jsonおよびデプロイ状態を維持しながらagentcore/agentcore.json設定ファイルをリセットします。後続は、削除されたリソースdeployを検出し、対応する AWS リソースを破棄します。

リソースの検索

デプロイ後、AgentCore CLI を使用してリソースのステータスを確認できます。

例

AWS コンソールでリソースを表示することもできます。

[リソース]	ロケーション
エージェントログ	CloudWatch → ロググループ → `/aws/bedrock-agentcore/runtimes/{agent-id}-DEFAULT`
CloudFormation スタック	CloudFormation → スタック → プロジェクト名を検索する
IAM ロール	IAM → ロール → BedrockAgentCore」を検索する
S3 アセット (CodeZip)	S3 → バケット → CDK ステージングバケット

一般的なの問題と解決策

AgentCore CLI の使用を開始する際の一般的な問題と解決策。トラブルシューティングの詳細については、「Amazon Bedrock AgentCore ランタイムのトラブルシューティング」を参照してください。

アクセス許可拒否エラー

AWS 認証情報とアクセス許可を確認します。

AWS 認証情報の検証: aws sts get-caller-identity
必要なポリシーがアタッチされていることを確認します。
詳細な要件について発信者のアクセス許可ポリシーを確認する

モデルアクセスが拒否されました

Bedrock コンソールでモデルアクセスを有効にします。

Bedrock コンソールで Anthropic Claude 4.0 を有効にする
正しい AWS リージョン (デフォルトではus-west-2) にあることを確認します。

CDK デプロイエラー

CDK の設定とアクセス許可を確認します。

CDK の AWS アカウントがブートストラップされていることを確認します。 cdk bootstrap
発信者のアクセス許可に CloudFormation と CDK アクセスが含まれていることを確認する
agentcore deploy -v 詳細な出力にを使用して、障害が発生したリソースを特定する

使用中のポート 8080 (ローカルのみ)

ポート 8080 を使用しているプロセスを見つけて停止します。

lsof -ti:8080 を使用して、ポート 8080 を使用するプロセスのリストを取得します。

プロセスを停止kill -9 PIDするには、を使用します。PID をプロセス ID に置き換えます。

または、別のポートで dev サーバーを起動します。 agentcore dev -p 3000

リージョンの不一致

で AWS リージョンを確認しaws configure get region、のリージョンがリソースをデプロイするリージョンagentcore/aws-targets.jsonと一致することを確認します。

設定検証エラー

設定ファイルを検証します。

を使用してagentcore validate、 agentcore/agentcore.json および関連する設定ファイルの構文またはスキーマエラーをチェックします。

詳細オプション (オプション)

でエージェントプロジェクトを作成したらagentcore create、 agentcore add コマンドを使用して拡張できます。CLI の完全なリファレンスについては、AgentCore CLI ドキュメントを参照してください。

ビルドタイプ

プロジェクトを作成するときは、ニーズに合ったビルドタイプを選択します。

CodeZip (デフォルト)

エージェントコードは zip アーカイブとしてパッケージ化され、S3 にアップロードされます。これは最も簡単なオプションであり、Docker は必要ありません。


agentcore create --name MyAgent --framework Strands --model-provider Bedrock --memory none --build CodeZip

コンテナ

エージェントコードは Docker コンテナイメージとしてパッケージ化されています。このオプションは、カスタムシステムレベルの依存関係または特定のベースイメージが必要な場合に使用します。


agentcore create --name MyAgent --framework Strands --model-provider Bedrock --memory none --build Container

プロジェクトにリソースを追加する

作成後にプロジェクトに追加のリソースを追加できます。


# Add another agent to the same project
agentcore add agent --name SecondAgent --language Python --framework Strands --model-provider Bedrock

# Add a memory store for conversational context
agentcore add memory --name MyMemory --strategies SEMANTIC

# Add an API key credential for external services
agentcore add credential --name MyApiKey --type api-key --api-key your-api-key

# Add a payment manager for x402 microtransactions
agentcore add payment-manager --name MyPayments --auto-payment --default-spend-limit 5.00

リソースを追加したら、 agentcore deploy を実行して新しいリソースをプロビジョニングします AWS。

ARM64 を使用する理由

Amazon Bedrock AgentCore ランタイムは ARM64 (AWS Graviton) で実行されます。AgentCore CLI は、CodeZip ビルドタイプと Container ビルドタイプの両方でアーキテクチャの互換性を自動的に処理します。コンテナビルドの場合、Amazon Bedrock AgentCore ランタイムにデプロイすると、ARM64 用に構築されたイメージのみが機能します。

ブラウザで JavaScript が無効になっているか、使用できません。

AWS ドキュメントを使用するには、JavaScript を有効にする必要があります。手順については、使用するブラウザのヘルプページを参照してください。

ドキュメントの表記規則

AgentCore ランタイムの使用を開始する

AgentCore CLI の使用を開始する (TypeScript)