View a markdown version of this page

Rekomendasi - Batuan Dasar Amazon AgentCore
Mode masukan konfigurasiSumber jejak agen

Rekomendasi

Rekomendasi menggunakan AI untuk menghasilkan konfigurasi agen yang dioptimalkan dari jejak sesi nyata. Alih-alih menulis ulang prompt atau deskripsi alat secara manual, Anda mengarahkan layanan ke jejak agen Anda, menentukan evaluator target sebagai sinyal hadiah, dan menerima konfigurasi yang dioptimalkan.

catatan

Rekomendasi dihasilkan oleh LLM. Tinjau dan uji sebelum menerapkannya.

Amazon Bedrock AgentCore mendukung dua jenis rekomendasi:

  • Rekomendasi prompt sistem: Menganalisis jejak agen dan menghasilkan prompt sistem yang dioptimalkan yang meningkatkan kinerja pada evaluator target. Layanan mengidentifikasi pola kegagalan dan menambahkan instruksi perilaku tertentu.

  • Rekomendasi deskripsi alat: Menganalisis jejak agen dan menghasilkan deskripsi alat yang diasah yang mengurangi kebingungan pemilihan alat. Ini berguna ketika agen memilih alat yang salah untuk permintaan ambigu.

Setiap rekomendasi memerlukan dua masukan: konfigurasi agen saat ini untuk dioptimalkan, dan jejak agen untuk dianalisis.

Topik

Mode masukan konfigurasi

Anda menyediakan konfigurasi saat ini dalam salah satu dari dua cara:

  • Teks sebaris: Berikan konfigurasi secara langsung sebagai string dalam permintaan API. Untuk rekomendasi prompt sistem, teruskan teks prompt di systemPrompt.text bidang. Untuk rekomendasi deskripsi alat, berikan nama dan deskripsi masing-masing alat dalam toolDescription.toolDescriptionText.tools daftar. Mode ini berguna untuk eksperimen cepat, ketika Anda ingin menguji prompt Anda secara aktif mengulangi, atau ketika konfigurasi Anda tidak disimpan dalam bundel.

    Jenis rekomendasi Bendera CLI Bidang API

    Prompt sistem

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

    systemPrompt.text

    Deskripsi alat

    --tools "name:description, name:description"

    toolDescription.toolDescriptionText.tools: daftar objek dengan toolName dan toolDescription

  • Bundel konfigurasi: Referensi versi bundel konfigurasi yang ada. Layanan membaca konfigurasi saat ini dari bundel menggunakan jalur JSON yang Anda tentukan, menghasilkan versi yang dioptimalkan, dan menulis hasilnya kembali ke versi bundel baru. Ini membuat riwayat pengoptimalan Anda tetap berversi di samping bundel Anda. Mode ini berguna ketika Anda mengelola konfigurasi secara terpusat dengan bundel konfigurasi dan ingin output yang dioptimalkan ditulis kembali ke bundel secara otomatis.

    Jenis rekomendasi Bendera CLI Bidang API

    Prompt sistem

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

    systemPrompt.configurationBundledengan bundleArnversionId, systemPromptJsonPath

    Deskripsi alat

    --bundle-name <bundle-name>+ --bundle-version <bundle-version> + --tool-desc-json-path "name:jsonpath" (ulangi untuk setiap alat)

    toolDescription.configurationBundledenganbundleArn,versionId, dan tools daftar yang berisi toolName dan toolDescriptionJsonPath

    Saat menggunakan bundel konfigurasi, hasil rekomendasi menyertakan configurationBundle bidang dengan bundleArn dan yang baru versionId menunjuk ke versi bundel yang berisi konfigurasi yang dioptimalkan.

Sumber jejak agen

agentTracesParameter menerima salah satu dari dua sumber:

  • CloudWatch Log: Gunakan saat runtime agen Anda menulis telemetri. CloudWatch Layanan membaca jejak langsung dari grup log yang ditentukan dalam rentang waktu yang diperlukan. Anda harus menyediakanlogGroupArns,serviceNames,startTime, danendTime. ruleBidang opsional memungkinkan Anda memfilter jejak (misalnya, hanya memilih sesi yang goal_success_rate berada di bawah ambang batas).

    catatan

    API rekomendasi menggunakan ARN grup log (logGroupArns), bukan nama grup log. Ini berbeda dari evaluasi batch, yang menggunakanlogGroupNames.

    Bidang Tipe Diperlukan Deskripsi

    cloudwatchLogs.logGroupArns

    Daftar string

    Ya

    CloudWatch Log log grup ARN tempat telemetri agen disimpan. Format: arn:aws:logs:{region}:{account}:log-group:{log-group-name}.

    cloudwatchLogs.serviceNames

    Daftar string

    Ya

    Nama layanan yang mengidentifikasi jejak agen Anda CloudWatch. Konvensi:{RuntimeName}.DEFAULT.

    cloudwatchLogs.startTime

    Tanggal waktu ISO 8601

    Ya

    Mulai dari jendela pengumpulan jejak. Hanya jejak setelah waktu ini yang disertakan.

    cloudwatchLogs.endTime

    Tanggal waktu ISO 8601

    Ya

    Akhir dari jendela pengumpulan jejak. Hanya jejak sebelum waktu ini yang disertakan.

    cloudwatchLogs.rule

    Objek

    Tidak

    Aturan filter opsional untuk mempersempit pemilihan jejak. Berisi filters daftar di mana setiap filter menentukankey, operator (sepertiLESS_THAN), dan value (seperti{"doubleValue": 0.5}).
    contoh
    AgentCore CLI
    agentcore run recommendation \
  --type system-prompt \
  --run my-prompt-rec \
  --runtime MyAgent \
  --evaluator Builtin.GoalSuccessRate \
  --inline "You are a helpful assistant..." \
  --lookback 7 \
  --wait
    AWS SDK (boto3)
    from datetime import datetime, timedelta, timezone

now = datetime.now(timezone.utc)

agent_traces = {
    "cloudwatchLogs": {
        "logGroupArns": [
            "<log-group-arn>"
        ],
        "serviceNames": ["<service-name>"],
        "startTime": now - timedelta(days=7),
        "endTime": now,
    }
}

    Dengan filter aturan opsional untuk memilih hanya sesi berkinerja rendah:

    agent_traces = {
    "cloudwatchLogs": {
        "logGroupArns": [
            "<log-group-arn>"
        ],
        "serviceNames": ["<service-name>"],
        "startTime": now - timedelta(days=7),
        "endTime": now,
        "rule": {
            "filters": [
                {
                    "key": "goal_success_rate",
                    "operator": "LESS_THAN",
                    "value": {"doubleValue": 0.5}
                }
            ]
        },
    }
}

  • Rentang sesi sebaris: Gunakan saat Anda memiliki jejak yang tersedia secara lokal (misalnya, dari uji coba lokal, CI/CD pipeline, atau sesi tertentu yang ingin Anda optimalkan). Anda memberikan bentang secara langsung di badan permintaan API sebagai daftar objek OpenTelemetry-compatible rentang.

    Bidang Tipe Diperlukan Deskripsi

    sessionSpans

    Daftar objek

    Ya

    Jejak agen membentang dalam OpenTelemetry-compatible format. Setiap rentang mencakup ID jejak, ID rentang, nama, stempel waktu, dan atribut.
    contoh
    AgentCore CLI

    Merentang file (membaca bentang dari file JSON lokal 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 assistant..." \
  --spans-file agent-traces.json

    ID sesi tertentu (CLI mengumpulkan rentang sisi klien 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 assistant..." \
  --session-id <session-id-1> <session-id-2>
    AWS SDK (boto3)
    import json

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

agent_traces = {
    "sessionSpans": spans
}
catatan

agentcore run recommendationadalah asinkron. Tanpa--wait, perintah mengirimkan pekerjaan rekomendasi dan segera kembali; pekerjaan dimulai dalam keadaan non-terminal (seperti PENDING atauIN_PROGRESS), dan Anda mengambil hasilnya nanti. Lulus --wait ke blokir hingga rekomendasi mencapai status terminal. Untuk melakukan polling atau mengambil hasil pekerjaan yang dikirimkan, jalankanagentcore view recommendation <id>, di id mana ID pekerjaan rekomendasi.

AgentCore CLI menyediakan flag kenyamanan yang dipetakan ke tipe sumber jejak API yang mendasarinya:

Bendera CLI Pemetaan API Deskripsi

--lookback <days>

cloudwatchLogsdengan dihitung startTime dan endTime

Mengumpulkan jejak dari N hari terakhir melalui CloudWatch Log. CLI menyelesaikan ARN grup log dan nama layanan dari konfigurasi runtime.

--session-id <id>

sessionSpans(sebaris)

Mengumpulkan rentang untuk sisi klien sesi yang ditentukan dan meneruskannya sebagai rentang sesi inline. API rekomendasi itu sendiri tidak mendukung pemfilteran ID sesi pada CloudWatch sumber.

--spans-file <path>

sessionSpans(sebaris)

Membaca rentang dari file JSON lokal dan meneruskannya sebagai rentang sesi inline.

--wait

n/a (polling sisi klien)

Blokir hingga rekomendasi mencapai status terminal.