Memanggil agen AgentCore Runtime

InvokeAgentRuntimeOperasi ini memungkinkan Anda mengirim permintaan ke titik akhir AgentCore Runtime tertentu yang diidentifikasi oleh Amazon Resource Name (ARN) mereka dan menerima tanggapan streaming yang berisi output agen. API mendukung manajemen sesi melalui pengenal sesi, memungkinkan Anda mempertahankan konteks percakapan di berbagai interaksi. Anda dapat menargetkan titik akhir agen tertentu menggunakan kualifikasi opsional.

Untuk meneleponInvokeAgentRuntime, Anda memerlukan bedrock-agentcore:InvokeAgentRuntime izin. Dalam panggilan Anda juga dapat memberikan token pembawa yang dapat digunakan agen untuk otentikasi pengguna.

InvokeAgentRuntimeOperasi menerima payload permintaan Anda sebagai data biner hingga ukuran 100 MB dan mengembalikan respons streaming yang mengirimkan potongan data secara real-time saat agen memproses permintaan Anda. Pendekatan streaming ini memungkinkan Anda untuk menerima sebagian hasil segera daripada menunggu respons lengkap, menjadikannya ideal untuk aplikasi interaktif.

Untuk menjalankan perintah shell (seperti menjalankan tes, operasi git, atau pengaturan lingkungan) dalam sesi yang sama, gunakan perintah Execute shell dalam operasi sesi AgentCore Runtime. Kedua operasi bekerja pada runtime dan sesi agen yang sama.

Jika Anda berencana mengintegrasikan agen Anda dengan OAuth, Anda tidak dapat menggunakan AWS SDK untuk menelepon. InvokeAgentRuntime Sebagai gantinya, buat permintaan HTTPS ke InvokeAgentRuntime. Untuk informasi selengkapnya, lihat Mengautentikasi dan mengotorisasi dengan Auth Masuk dan Auth Keluar.

Memanggil agen streaming

Contoh berikut menunjukkan cara menggunakan boto3 untuk memanggil runtime agen:

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)

Memanggil agen multi-modal

Anda dapat menggunakan InvokeAgentRuntime operasi untuk mengirim permintaan multi-modal yang mencakup teks dan gambar. Contoh berikut menunjukkan cara memanggil agen multi-modal:

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
)

Manajemen sesi

InvokeAgentRuntimeOperasi mendukung manajemen sesi melalui runtimeSessionId parameter. Dengan menyediakan pengenal sesi yang sama di beberapa permintaan, Anda dapat mempertahankan konteks percakapan, memungkinkan agen untuk mereferensikan interaksi sebelumnya.

Untuk memulai percakapan baru, buat pengenal sesi unik. Untuk melanjutkan percakapan yang ada, gunakan pengenal sesi yang sama dari permintaan sebelumnya. Pendekatan ini memungkinkan Anda untuk membangun aplikasi interaktif yang mempertahankan konteks dari waktu ke waktu.

Tip

Untuk hasil terbaik, gunakan UUID atau pengenal unik lainnya untuk ID sesi Anda untuk menghindari tabrakan antara pengguna atau percakapan yang berbeda.

Penanganan kesalahan

Saat menggunakan InvokeAgentRuntime operasi, Anda mungkin mengalami berbagai kesalahan. Berikut adalah beberapa kesalahan umum dan cara menanganinya:

ValidationException

Terjadi ketika parameter permintaan tidak valid. Periksa apakah ARN agen Anda, ID sesi, dan payload diformat dengan benar.

ResourceNotFoundException

Terjadi ketika runtime agen yang ditentukan tidak dapat ditemukan. Verifikasi bahwa agen ARN benar dan agen ada di akun Anda AWS .

AccessDeniedException

Terjadi ketika Anda tidak memiliki izin yang diperlukan. Pastikan bahwa kebijakan IAM Anda mencakup bedrock-agentcore:InvokeAgentRuntime izin.

ThrottlingException

Terjadi ketika Anda melebihi batas tingkat permintaan. Terapkan backoff eksponensial dan coba lagi logika dalam aplikasi Anda.

Terapkan penanganan kesalahan yang tepat dalam aplikasi Anda untuk memberikan pengalaman pengguna yang lebih baik dan untuk memecahkan masalah secara efektif.

Praktik terbaik

Ikuti praktik terbaik ini saat menggunakan InvokeAgentRuntime operasi:

• Gunakan manajemen sesi untuk mempertahankan konteks percakapan untuk pengalaman pengguna yang lebih baik.

• Memproses respons streaming secara bertahap untuk memberikan umpan balik waktu nyata kepada pengguna.

• Menerapkan penanganan kesalahan yang tepat dan coba kembali logika untuk aplikasi yang kuat.

• Pertimbangkan batasan ukuran muatan (100 MB) saat mengirim permintaan, terutama untuk konten multi-modal.

• Gunakan kualifikasi yang sesuai untuk menargetkan versi agen atau titik akhir tertentu.

• Menerapkan mekanisme otentikasi bila perlu menggunakan token pembawa.

• Gunakan InvokeAgentRuntimeCommand untuk operasi deterministik (tes, git, build) alih-alih merutekan mereka melalui LLM agen. Lihat Menjalankan perintah shell dalam sesi AgentCore Runtime.