View a markdown version of this page

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

Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris.

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 Logs (--lookback), spans sebaris (--spans-file), menjalankan wawasan lokal (--from-insights <id>— menggunakan wawasan lokal yang dijalankan sebagai sumber pelacakan; menyelesaikan batch eval ARN), atau ARN evaluasi batch secara langsung (--batch-evaluation-arn <arn>— menggunakan ARN evaluasi batch secara langsung sebagai sumber jejak)

  • Masukan 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>— kunci KMS ARN 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 IN_PROGRESS status. Tambahkan --wait ke blok hingga 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 spans: 

    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 tertentu dan meneruskannya sebagai rentang 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 telah selesai. Tambahkan --json untuk output yang dapat dibaca mesin yang berisi recommendedSystemPrompt dan. 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 rentang 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 rentang 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

Ber systemPromptRecommendationConfig isi 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 salah text satu (string sebaris, maksimum 20.000 karakter) atau configurationBundle (referensi bundel).

agentTraces

Union

Ya

Sumber jejak untuk analisis. Lihat Sumber jejak 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 rekomendasi; apa pun skor evaluator yang tinggi adalah apa yang didorong oleh pengoptimal.

Anda dapat menggunakan evaluator bawaan atau menyediakan evaluator khusus ARN. 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 spesifik 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 mengembalikan nilai numerik sebagai sinyal pengoptimalan. Untuk LLM-as-judge evaluator khusus, konfigurasikan ratingScale dengan numerical skala (tidakcategorical). Untuk evaluator berbasis kode, sertakan value bidang dalam skema respons. 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 --evaluator bendera:

--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.configurationBundledenganbundleArn,versionId, 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 tersebut.

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

Kapan 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. Ber bundleArn isi 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 mundur eksponensial.

InternalServerException

500

Service-side kesalahan. Coba lagi permintaannya.