View a markdown version of this page

Mulai rekomendasi prompt sistem - Batuan Dasar Amazon AgentCore
Sampel KodePermintaan parameterMemilih evaluatorMode input prompt sistemResponsHasil rekomendasiKesalahan

Mulai rekomendasi prompt sistem

Mulai rekomendasi untuk menghasilkan prompt sistem yang dioptimalkan untuk agen Anda. Layanan menganalisis jejak agen, mengidentifikasi pola kegagalan, dan menghasilkan prompt sistem yang direvisi yang meningkatkan kinerja pada evaluator target.

catatan

Rekomendasi dihasilkan oleh LLM. Tinjau dan uji sebelum menerapkannya.

Sampel Kode

contoh
AgentCore CLI

CLI menerima beberapa sumber jejak dan tiga mode input prompt sistem. Gabungkan mereka sesuai kebutuhan:

  • Sumber jejak: CloudWatch Log (--lookback), bentang sebaris (--spans-file), dijalankan wawasan lokal (--from-insights <id>— menggunakan wawasan lokal yang dijalankan sebagai sumber jejak; menyelesaikan ARN eval batch), atau ARN evaluasi batch secara langsung --batch-evaluation-arn <arn> (— menggunakan ARN evaluasi batch secara langsung sebagai sumber jejak)

  • Input prompt sistem: teks sebaris (--inline), file prompt (--prompt-file), atau bundel konfigurasi (--bundle-name)

  • Filter opsional: ID sesi tertentu (--session-id) untuk mempersempit jejak mana yang dianalisis

  • Enkripsi opsional: kunci KMS (--kms-key <arn>— ARN kunci KMS untuk mengenkripsi hasil rekomendasi)

    Prompt sistem sebaris dengan CloudWatch jejak: 

    agentcore run recommendation \
  --type system-prompt \
  --run my-prompt-rec \
  --runtime MyAgent \
  --evaluator Builtin.GoalSuccessRate \
  --inline "You are a helpful customer support assistant. Help users with their orders and returns." \
  --lookback 7 \
  --wait

    run recommendationmemulai pekerjaan asinkron dan mengembalikan hanya a recommendationId dan awal PENDING atau status. IN_PROGRESS Tambahkan --wait ke blok sampai rekomendasi mencapai status terminal. Untuk mengambil hasil yang sudah selesai nanti, lihat Mengambil hasilnya.

    Prompt sistem sebaris dari file dengan CloudWatch jejak: 

    agentcore run recommendation \
  --type system-prompt \
  --run my-prompt-rec \
  --runtime MyAgent \
  --evaluator Builtin.GoalSuccessRate \
  --prompt-file ./system-prompt.txt \
  --lookback 7

    Prompt sistem sebaris dengan file bentang: 

    agentcore run recommendation \
  --type system-prompt \
  --run my-prompt-rec \
  --runtime MyAgent \
  --evaluator Builtin.GoalSuccessRate \
  --inline "You are a helpful customer support assistant." \
  --spans-file agent-traces.json

    Prompt sistem sebaris dengan ID sesi tertentu:

    CLI mengumpulkan rentang untuk sisi klien sesi yang ditentukan dan meneruskannya sebagai bentang sebaris.

    agentcore run recommendation \
  --type system-prompt \
  --run my-prompt-rec \
  --runtime MyAgent \
  --evaluator Builtin.GoalSuccessRate \
  --inline "You are a helpful customer support assistant." \
  --session-id <session-id-1> <session-id-2>

    Bundel konfigurasi dengan CloudWatch jejak:

    CLI secara otomatis menyelesaikan jalur JSON lengkap dari objek induk ARN runtime agen. configuration Anda hanya perlu memberikan nama kunci yang berisi prompt sistem.

    agentcore run recommendation \
  --type system-prompt \
  --run my-prompt-rec \
  --runtime MyAgent \
  --evaluator Builtin.GoalSuccessRate \
  --bundle-name <bundle-name> \
  --bundle-version <bundle-version> \
  --system-prompt-json-path "system_prompt" \
  --lookback 7

    Ambil hasilnya:

    Gunakan view recommendation dengan ID pekerjaan rekomendasi untuk mengambil hasil yang sudah selesai. Tambahkan --json untuk output yang dapat dibaca mesin yang berisi dan. recommendedSystemPrompt explanation

    agentcore view recommendation <recommendation-id> --json
AWS SDK (boto3)

Teks sebaris dengan CloudWatch jejak:

import boto3
import json
import uuid
from datetime import datetime, timedelta, timezone

client = boto3.client("bedrock-agentcore", region_name="us-west-2")

now = datetime.now(timezone.utc)

response = client.start_recommendation(
    name="my-prompt-rec",
    type="SYSTEM_PROMPT_RECOMMENDATION",
    recommendationConfig={
        "systemPromptRecommendationConfig": {
            "systemPrompt": {
                "text": "You are a helpful customer support assistant. Help users with their orders and returns."
            },
            "agentTraces": {
                "cloudwatchLogs": {
                    "logGroupArns": [
                        "<log-group-arn>"
                    ],
                    "serviceNames": ["<service-name>"],
                    "startTime": now - timedelta(days=7),
                    "endTime": now,
                }
            },
            "evaluationConfig": {
                "evaluators": [
                    {"evaluatorArn": "arn:aws:bedrock-agentcore:::evaluator/Builtin.GoalSuccessRate"}
                ]
            },
        }
    },
    clientToken=str(uuid.uuid4()),
)

recommendation_id = response["recommendationId"]
print(f"Started recommendation: {recommendation_id}")
print(f"Status: {response['status']}")

Teks sebaris dengan bentang sebaris:

with open("agent-traces.json") as f:
    spans = json.load(f)

response = client.start_recommendation(
    name="my-prompt-rec-spans",
    type="SYSTEM_PROMPT_RECOMMENDATION",
    recommendationConfig={
        "systemPromptRecommendationConfig": {
            "systemPrompt": {
                "text": "You are a helpful customer support assistant."
            },
            "agentTraces": {
                "sessionSpans": spans
            },
            "evaluationConfig": {
                "evaluators": [
                    {"evaluatorArn": "arn:aws:bedrock-agentcore:::evaluator/Builtin.GoalSuccessRate"}
                ]
            },
        }
    },
    clientToken=str(uuid.uuid4()),
)

Bundel konfigurasi dengan CloudWatch jejak:

response = client.start_recommendation(
    name="my-bundle-prompt-rec",
    type="SYSTEM_PROMPT_RECOMMENDATION",
    recommendationConfig={
        "systemPromptRecommendationConfig": {
            "systemPrompt": {
                "configurationBundle": {
                    "bundleArn": "<bundle-arn>",
                    "versionId": "<bundle-version>",
                    "systemPromptJsonPath": "$.configuration.system_prompt",
                }
            },
            "agentTraces": {
                "cloudwatchLogs": {
                    "logGroupArns": [
                        "<log-group-arn>"
                    ],
                    "serviceNames": ["<service-name>"],
                    "startTime": now - timedelta(days=7),
                    "endTime": now,
                }
            },
            "evaluationConfig": {
                "evaluators": [
                    {"evaluatorArn": "arn:aws:bedrock-agentcore:::evaluator/Builtin.GoalSuccessRate"}
                ]
            },
        }
    },
    clientToken=str(uuid.uuid4()),
)

Bundel konfigurasi dengan bentang sebaris:

response = client.start_recommendation(
    name="my-bundle-prompt-rec-spans",
    type="SYSTEM_PROMPT_RECOMMENDATION",
    recommendationConfig={
        "systemPromptRecommendationConfig": {
            "systemPrompt": {
                "configurationBundle": {
                    "bundleArn": "<bundle-arn>",
                    "versionId": "<bundle-version>",
                    "systemPromptJsonPath": "$.configuration.system_prompt",
                }
            },
            "agentTraces": {
                "sessionSpans": spans
            },
            "evaluationConfig": {
                "evaluators": [
                    {"evaluatorArn": "arn:aws:bedrock-agentcore:::evaluator/Builtin.GoalSuccessRate"}
                ]
            },
        }
    },
    clientToken=str(uuid.uuid4()),
)

Permintaan parameter

Parameter Tipe Diperlukan Deskripsi

name

Tali

Ya

Sebuah nama untuk rekomendasi. Maksimal 48 karakter. Pola:[a-zA-Z][a-zA-Z0-9_-]{0,47}.

type

Tali

Ya

Harus berupa SYSTEM_PROMPT_RECOMMENDATION.

recommendationConfig

Objek

Ya

Berisi systemPromptRecommendationConfig dengan konfigurasi untuk rekomendasi.

description

String

Tidak

Deskripsi opsional. Maksimal 4096 karakter.

clientToken

String

Tidak

Token idempotensi. Jika Anda mencoba lagi permintaan dengan token klien yang sama, layanan mengembalikan rekomendasi yang ada alih-alih membuat yang baru.

PromptRecommendationConfig bidang sistem

Bidang Tipe Diperlukan Deskripsi

systemPrompt

Union

Ya

Sistem saat ini meminta untuk mengoptimalkan. Berikan text (string sebaris, maksimum 20.000 karakter) atau configurationBundle (referensi bundel).

agentTraces

Union

Ya

Sumber jejak untuk analisis. Lihat Melacak sumber untuk rekomendasi.

evaluationConfig

Objek

Ya

Konfigurasi evaluasi yang menentukan evaluator target. Berisi evaluators daftar dengan tepat satu referensi evaluator.

Memilih evaluator

Pilih evaluator yang selaras dengan arah yang ingin Anda tingkatkan. Evaluator yang Anda pilih menentukan apa yang dioptimalkan oleh rekomendasi; apa pun skor evaluator yang tinggi adalah apa yang didorong oleh pengoptimal.

Anda dapat menggunakan evaluator bawaan atau menyediakan ARN evaluator kustom. Gunakan panduan berikut untuk memilih:

  • Jika agen Anda memiliki tugas yang jelas untuk diselesaikan (pemesanan, pengambilan, alur kerja multi-langkah), Builtin.GoalSuccessRate adalah sinyal yang tepat.

  • Jika agen Anda lebih terbuka dan Anda peduli dengan kualitas interaksi itu sendiri, Builtin.Helpfulness lebih cocok.

  • Jika kualitas yang Anda pedulikan khusus domain atau tidak ditangkap oleh evaluator bawaan, gunakan evaluator khusus untuk mewakili pengukuran dengan sebaik-baiknya.

catatan

Rekomendasi mendukung evaluator bawaan LLM-as-judge, kustom, dan berbasis kode, tetapi mengharuskan evaluator untuk mengembalikan nilai numerik sebagai sinyal pengoptimalan. Untuk LLM-as-judge evaluator kustom, konfigurasikan ratingScale dengan numerical skala (bukancategorical). Untuk evaluator berbasis kode, sertakan value bidang dalam skema respons.

Di API, tentukan evaluator dalam evaluationConfig.evaluators daftar dengan tepat satu referensi evaluator:

"evaluationConfig": {
    "evaluators": [
        {"evaluatorArn": "arn:aws:bedrock-agentcore:::evaluator/Builtin.GoalSuccessRate"}
    ]
}

Di CLI, gunakan bendera: --evaluator

--evaluator Builtin.GoalSuccessRate

Mode input prompt sistem

Modus Bendera CLI Bidang API

Teks sebaris

--inline "prompt text" atau --prompt-file ./path.txt

systemPrompt.text

Bundel konfigurasi

--bundle-name <bundle-name> + --bundle-version <bundle-version> + --system-prompt-json-path <path>

systemPrompt.configurationBundledengan bundleArnversionId, systemPromptJsonPath

Saat menggunakan bundel konfigurasi, hasilnya menyertakan versi bundel baru dengan prompt sistem yang dioptimalkan diterapkan.

Respons

Bidang Tipe Deskripsi

recommendationId

String

Pengidentifikasi unik untuk rekomendasi.

recommendationArn

String

ARN dari rekomendasi.

name

String

Nama yang Anda tentukan.

type

String

SYSTEM_PROMPT_RECOMMENDATION.

status

String

Status awal: PENDING atauIN_PROGRESS.

createdAt

Stempel waktu

Ketika rekomendasi dibuat.

updatedAt

Stempel waktu

Ketika rekomendasi terakhir diperbarui.

Hasil rekomendasi

Ketika rekomendasi mencapai COMPLETED status (diambil melalui Dapatkan rekomendasi), hasilnya berisi:

Bidang Tipe Deskripsi

recommendedSystemPrompt

String

Teks prompt sistem yang dioptimalkan.

configurationBundle

Objek

Hadir ketika input adalah bundel konfigurasi. Berisi bundleArn dan versionId menunjuk ke versi bundel baru dengan prompt yang dioptimalkan diterapkan.

explanation

String

Penjelasan mengapa rekomendasi dihasilkan dan alasan di balik perubahan yang disarankan.

errorCode

String

Hadir jika rekomendasi gagal. Kode kesalahan yang menggambarkan kegagalan.

errorMessage

String

Hadir jika rekomendasi gagal. Human-readable deskripsi kesalahan.

Kesalahan

Kesalahan Status HTTP Deskripsi

ValidationException

400

Parameter permintaan tidak valid. Periksa batasan bidang dan bidang wajib.

AccessDeniedException

403

Izin tidak mencukupi. Verifikasi kebijakan IAM.

ConflictException

409

Rekomendasi dengan token klien yang sama sudah ada dengan parameter yang berbeda.

ServiceQuotaExceededException

402

Anda telah melampaui jumlah maksimum rekomendasi bersamaan.

ThrottlingException

429

Tingkat permintaan terlampaui. Coba lagi dengan backoff eksponensial.

InternalServerException

500

Service-side kesalahan. Coba lagi permintaannya.