View a markdown version of this page

Rekomendasi - Batu Dasar Amazon AgentCore
Mode input konfigurasiSumber jejak agen

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

Rekomendasi

Rekomendasi menggunakan AI untuk menghasilkan konfigurasi agen yang dioptimalkan dari jejak sesi nyata. Alih-alih menulis ulang perintah 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 tajam yang mengurangi kebingungan pemilihan alat. Ini berguna ketika agen memilih alat yang salah untuk permintaan ambigu.

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

Topik

Mode input konfigurasi

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

  • Teks sebaris: Men yediakan konfigurasi secara langsung sebagai string dalam permintaan API. Untuk rekomendasi prompt sistem, berikan 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 yang Anda iterasi secara aktif, 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: Referensikan 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 bersama 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 empat sumber:

  • CloudWatch Log: Gunakan saat runtime agen Anda menulis telemetri ke 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, memilih hanya sesi yang goal_success_rate berada di bawah ambang batas).

    catatan

    API rekomendasi menggunakan log group ARNs (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 di 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 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 pelacakan yang tersedia secara lokal (misalnya, dari uji coba lokal, CI/CD pipeline, atau sesi tertentu yang ingin Anda optimalkan). Anda memberikan rentang langsung di badan permintaan API sebagai daftar objek OpenTelemetry-compatible rentang.

    Bidang Tipe Diperlukan Deskripsi

    sessionSpans

    Daftar objek

    Ya

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

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

    ID sesi tertentu (CLI mengumpulkan rentang sisi klien 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 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

Evaluasi batch dan sumber jejak evaluasi online hanya tersedia untuk rekomendasi prompt sistem.

  • Evaluasi batch: Gunakan saat Anda telah menyelesaikan pekerjaan evaluasi batch yang sesinya ingin Anda gunakan kembali untuk pengoptimalan. Alih-alih mengumpulkan kembali jejak dari CloudWatch atau memberikan rentang sebaris, Anda mereferensikan evaluasi batch secara langsung oleh ARN-nya. Sumber ini hanya tersedia untuk rekomendasi prompt sistem.

    • Jika evaluator yang digunakan dalam pekerjaan evaluasi batch cocok dengan evaluator yang ditentukan dalam permintaan rekomendasi, layanan menggunakan kembali skor yang ada.

    • Jika evaluator tidak cocok, layanan menjalankan evaluasi baru untuk evaluator yang diminta terhadap sesi evaluasi batch.

      Bidang Tipe Diperlukan Deskripsi

      batchEvaluation.batchEvaluationArn

      Tali

      Ya

      ARN dari pekerjaan evaluasi batch yang telah selesai. Layanan menggunakan kembali sesi dari pekerjaan ini sebagai input pelacakan. Format: arn:aws:bedrock-agentcore:{region}:{account}:batch-evaluation/{id}.
      contoh
      AWS SDK (boto3)
      agent_traces = {
    "batchEvaluation": {
        "batchEvaluationArn": "<batch-evaluation-arn>"
    }
}

  • Evaluasi online: Gunakan ketika Anda memiliki konfigurasi evaluasi online yang terus mengevaluasi sesi agen langsung. Karena evaluasi online adalah aliran berkelanjutan, Anda harus menentukan jendela waktu (startTimedanendTime) untuk mengikat sesi evaluasi mana yang diambil rekomendasi. Layanan menggunakan kembali skor evaluasi dari sesi evaluasi online dalam jendela yang ditentukan. Sumber ini hanya tersedia untuk rekomendasi prompt sistem.

    Bidang Tipe Diperlukan Deskripsi

    onlineEvaluation.onlineEvaluationConfigArn

    Tali

    Ya

    ARN dari konfigurasi evaluasi online. Layanan menggunakan sesi yang dievaluasi dari konfigurasi ini sebagai input jejak. Format: arn:aws:bedrock-agentcore:{region}:{account}:online-evaluation-config/{id}.

    onlineEvaluation.startTime

    Tanggal waktu ISO 8601

    Ya

    Mulai dari jendela evaluasi. Hanya sesi yang dievaluasi setelah waktu ini yang disertakan.

    onlineEvaluation.endTime

    Tanggal waktu ISO 8601

    Ya

    Akhir jendela evaluasi. Hanya sesi yang dievaluasi sebelum waktu ini yang disertakan.
    contoh
    AWS SDK (boto3)
    from datetime import datetime, timedelta, timezone

now = datetime.now(timezone.utc)

agent_traces = {
    "onlineEvaluation": {
        "onlineEvaluationConfigArn": "<online-evaluation-config-arn>",
        "startTime": now - timedelta(days=7),
        "endTime": now,
    }
}
catatan

agentcore run recommendationbersifat 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. L --wait ulus untuk memblokir sampai 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 jenis sumber pelacakan API yang mendasarinya:

Bendera CLI Pemetaan API Deskripsi

--lookback <days>

cloudwatchLogsdengan komputasi 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 tertentu dan meneruskannya sebagai rentang sesi sebaris. 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 sebaris.

--wait

n/a (polling sisi klien)

Blokir sampai rekomendasi mencapai status terminal.