AgentCore ランタイムエージェントを呼び出す

InvokeAgentRuntime オペレーションを使用すると、Amazon リソースネーム (ARN) で識別される特定の AgentCore ランタイムエンドポイントにリクエストを送信し、エージェントの出力を含むストリーミングレスポンスを受信できます。API は、セッション識別子によるセッション管理をサポートしているため、複数のインタラクションにわたって会話コンテキストを維持できます。オプションの修飾子を使用して、特定のエージェントエンドポイントをターゲットにできます。

InvokeAgentRuntime を呼び出すには、 アクセスbedrock-agentcore:InvokeAgentRuntime許可が必要です。呼び出しでは、エージェントがユーザー認証に使用できるベアラートークンを渡すこともできます。

InvokeAgentRuntime オペレーションは、リクエストペイロードを最大 100 MB のサイズのバイナリデータとして受け入れ、エージェントがリクエストを処理するときに大量のデータをリアルタイムで配信するストリーミングレスポンスを返します。このストリーミングアプローチにより、完全な応答を待つのではなく、部分的な結果をすぐに受け取ることができるため、インタラクティブなアプリケーションに最適です。

同じセッションでシェルコマンド (テストの実行、git オペレーション、環境設定など) を実行するには、AgentCore ランタイムセッションオペレーションでシェルコマンドの実行を使用します。どちらのオペレーションも、同じエージェントのランタイムとセッションで動作します。

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

ストリーミングエージェントを呼び出す

次の例は、boto3 を使用してエージェントランタイムを呼び出す方法を示しています。

import boto3
import json

# Initialize the 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=session_id,
    payload=payload
)


# Process and print the response
if "text/event-stream" in response.get("contentType", ""):

    # Handle streaming response
    content = []
    for line in response["response"].iter_lines(chunk_size=10):
        if line:
            line = line.decode("utf-8")
            if line.startswith("data: "):
                line = line[6:]
                print(line)
                content.append(line)
    print("\nComplete response:", "\n".join(content))

elif response.get("contentType") == "application/json":
    # Handle standard JSON response
    content = []
    for chunk in response.get("response", []):
        content.append(chunk.decode('utf-8'))
    print(json.loads(''.join(content)))

else:
    # Print raw response for other content types
    print(response)

マルチモーダルエージェントを呼び出す

InvokeAgentRuntime オペレーションを使用して、テキストとイメージの両方を含むマルチモーダルリクエストを送信できます。次の例は、マルチモーダルエージェントを呼び出す方法を示しています。

import boto3
import json
import base64

# Read and encode image
with open("image.jpg", "rb") as image_file:
    image_data = base64.b64encode(image_file.read()).decode('utf-8')

# Prepare multi-modal payload
payload = json.dumps({
    "prompt": "Describe what you see in this image",
    "media": {
        "type": "image",
        "format": "jpeg",
        "data": image_data
 }
}).encode()

# Invoke the agent
response = agent_core_client.invoke_agent_runtime(
    agentRuntimeArn=agent_arn,
    runtimeSessionId=session_id,
    payload=payload
)

セッション管理

InvokeAgentRuntime オペレーションは、 runtimeSessionIdパラメータによるセッション管理をサポートします。複数のリクエストに同じセッション識別子を提供することで、会話コンテキストを維持し、エージェントが以前のインタラクションを参照できるようにします。

新しい会話を開始するには、一意のセッション識別子を生成します。既存の会話を続行するには、以前のリクエストと同じセッション識別子を使用します。このアプローチにより、時間の経過とともにコンテキストを維持するインタラクティブなアプリケーションを構築できます。

エラー処理

InvokeAgentRuntime オペレーションを使用すると、さまざまなエラーが発生する可能性があります。一般的なエラーとその処理方法は次のとおりです。

アプリケーションに適切なエラー処理を実装して、ユーザーエクスペリエンスを向上させ、問題を効果的にトラブルシューティングします。

ベストプラクティス

InvokeAgentRuntime オペレーションを使用する場合は、次のベストプラクティスに従ってください。