Pythonからの呼び出し

コンソールのプレイグラウンドから料理レシピアシスタントとして応答できることを確認しましたが、実運用ではアプリケーションから SDK 経由でハーネスを呼び出すことになります。ここでは、詳細画面の呼び出しコードを表示パネルにあるサンプルコードをそのまま使い、ローカルの Python から独自スキル付きのハーネスを叩いてプレイグラウンドと同じ SKILL.md フォーマットで応答が返ることを確認します。

1. invoke_harness.pyの作成

MyHarness の詳細画面に戻り、呼び出しコードを表示 パネルの Python タブでコード全体をコピーします。任意の場所に invoke_harness.py ファイルを作成し、コピーしたコードを貼り付けます。以下の3箇所を実際の値に書き換えます。

  • harnessArn の値: サンプルの ARN を、MyHarness の実際の ARN(arn:aws:bedrock-agentcore:ap-northeast-1:<アカウントID>:harness/MyHarness-XXXXXX)に置き換える
  • runtimeSessionId の値: <Enter your SessionId> を、任意の33文字以上の文字列(例: harness-python-cooking-session-00001)に置き換える
  • 質問文(messages 内の text): プレイグラウンドで試したのと同じ「オムライスの作り方を教えてください」に置き換える

書き換え後のコード例は以下のとおりです。

import boto3

client = boto3.client('bedrock-agentcore', region_name='ap-northeast-1')

response = client.invoke_harness(
    harnessArn='arn:aws:bedrock-agentcore:ap-northeast-1:<アカウントID>:harness/MyHarness-XXXXXX',
    runtimeSessionId='harness-python-cooking-session-00001',
    messages=[
        {
            'role': 'user',
            'content': [{'text': 'オムライスの作り方を教えてください'}]
        }
    ]
)

for event in response['stream']:
    if 'contentBlockDelta' in event:
        delta = event['contentBlockDelta'].get('delta', {})
        if 'text' in delta:
            print(delta['text'], end='')
print()

コードを解説します。

import boto3

client = boto3.client('bedrock-agentcore', region_name='ap-northeast-1')

boto3 は AWS の Python SDK です。boto3.client('bedrock-agentcore', ...) で、AgentCore サービスに接続するクライアントを作成します。region_name にはハーネスを作成したリージョンと同じ ap-northeast-1(東京)を指定します。ハーネスやランタイムへの呼び出しは、このクライアント経由で行います。

response = client.invoke_harness(
    harnessArn='arn:aws:bedrock-agentcore:ap-northeast-1:<アカウントID>:harness/MyHarness-XXXXXX',
    runtimeSessionId='harness-python-cooking-session-00001',
    messages=[
        {
            'role': 'user',
            'content': [{'text': 'オムライスの作り方を教えてください'}]
        }
    ]
)

invoke_harness は、AgentCoreハーネスに問い合わせを送るAPIです。3つの引数を指定しています。

  • harnessArn: 呼び出す対象のハーネスの ARN。前のステップで詳細画面から控えた値を渡す
  • runtimeSessionId: 会話セッションを識別する任意の文字列(33文字以上)。同じセッションIDで呼び続けると、ハーネス側で会話の文脈が保持される。今回は毎回新しいセッションでよいので固定値を入れている
  • messages: モデルへの入力。Bedrock Converse API と同じ形式で、role(user / assistant)と content(テキストや画像などのブロックの配列)を持つ。ここでは オムライスの作り方を教えてください をユーザメッセージとして1件だけ送っている
for event in response['stream']:
    if 'contentBlockDelta' in event:
        delta = event['contentBlockDelta'].get('delta', {})
        if 'text' in delta:
            print(delta['text'], end='')
print()

invoke_harness の応答は、モデルが生成したテキストを少しずつ返すストリーム形式です。response['stream'] を for で回し、イベントごとに中身を確認します。contentBlockDelta イベントには、応答テキストの断片(delta.text)が入っているため、それを順に取り出して print で標準出力に書き出します。end='' を指定して改行を抑えることで、細切れの断片が繋がった1つの応答として画面に表示されます。ループを抜けたあとの print() は、末尾に改行を1つだけ追加するためのものです。

2. スクリプトの実行

以下のコマンドで、Python がインストールされていることを確認します。

Windowsの場合:

python --version

Macの場合:

python3 --version

以下のように Python のバージョンが表示されれば、インストールは確認できています。

Python 3.x.x

バージョンが表示されない場合は、Pythonのインストール を先に実施してください。

インストールが確認できたら、ターミナルから以下のコマンドで invoke_harness.py を実行します。

Windowsの場合:

python invoke_harness.py

Macの場合:

python3 invoke_harness.py

推定時間 / 難易度 / 必要な材料 / 手順 / コツ の5セクション形式でオムライスのレシピが流れてくれば、独自スキルを追加したハーネスを Python からも叩けている状態です。プレイグラウンドで見たのと同じ SKILL.md フォーマットで返ることから、マネジメントコンソール経由でも Python 経由でも、同じスキル付きハーネスを呼び出せていることが確認できます。

⚠️ ModuleNotFoundError: No module named 'boto3' が出る場合
ローカルに boto3 がインストールされていません。Python 側で boto3 をインストールしてから再実行してください。詳細な手順は Pythonのインストール の「boto3のインストール」に記載があります。
⚠️ Unable to locate credentials が出る場合
ローカルの AWS CLI 認証情報が未設定です。aws configure を実行してアクセスキーID・シークレットアクセスキー・リージョン(ap-northeast-1)を設定してください。詳細は AWS CLIのインストール に記載があります。
💡 ポイント
ここではローカルの Python から直接呼び出しましたが、実運用では AWS Lambda・ECS・EKS 上のバックエンドから同じ invoke_harness を叩く形になります。Lambda から呼び出す場合、Lambda の実行ロールに bedrock-agentcore:InvokeHarness を許可する IAM ポリシーが追加で必要になります。Resource を対象ハーネスの ARN に絞っておけば、意図しないハーネスを呼び出してしまうリスクを抑えられます。詳細な API 仕様は InvokeHarness API リファレンス(AWS公式ドキュメント) に記載があります。