View a markdown version of this page

Evaluator berbasis kode khusus - Batu Dasar Amazon AgentCore

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

Evaluator berbasis kode khusus

Evaluator berbasis kode khusus memungkinkan Anda menggunakan fungsi AWS Lambda Anda sendiri untuk mengevaluasi kinerja agen secara terprogram, alih-alih menggunakan LLM sebagai juri. Ini memberi Anda kontrol penuh atas logika evaluasi — Anda dapat menerapkan pemeriksaan deterministik, memanggil API eksternal, menjalankan pencocokan regex, menghitung metrik khusus, atau menerapkan aturan khusus bisnis apa pun.

Prasyarat

Untuk menggunakan evaluator berbasis kode khusus, Anda memerlukan:

  • Fungsi AWS Lambda yang digunakan di Wilayah yang sama dengan sumber daya AgentCore Evaluasi Anda.

  • Peran eksekusi IAM yang memberikan izin layanan AgentCore Evaluasi untuk memanggil fungsi Lambda Anda.

  • Fungsi Lambda harus mengembalikan respons JSON yang sesuai dengan skema respons yang dijelaskan dalam skema respons.

Izin IAM

Peran eksekusi layanan Anda memerlukan izin tambahan berikut untuk memanggil fungsi Lambda untuk evaluasi berbasis kode:

{ "Sid": "LambdaInvokeStatement", "Effect": "Allow", "Action": [ "lambda:InvokeFunction", "lambda:GetFunction" ], "Resource": "arn:aws:lambda:region:account-id:function:function-name" }

Kontrak fungsi lambda

catatan

Waktu tunggu waktu maksimum untuk fungsi Lambda adalah 5 menit (300 detik). Ukuran muatan input maksimum yang dikirim ke fungsi Lambda adalah 6 MB.

Skema masukan

Fungsi Lambda Anda menerima muatan JSON dengan struktur berikut:

{ "schemaVersion": "1.0", "evaluatorId": "my-evaluator-abc1234567", "evaluatorName": "MyCodeEvaluator", "evaluationLevel": "TRACE", "evaluationInput": { "sessionSpans": [...] }, "evaluationReferenceInputs": [], "evaluationTarget": { "traceIds": ["trace123"], "spanIds": ["span123"] } }
Bidang Tipe Deskripsi

schemaVersion

String

Versi skema dari payload. Saat ini"1.0".

evaluatorId

String

ID evaluator berbasis kode.

evaluatorName

String

Nama evaluator berbasis kode.

evaluationLevel

String

Tingkat evaluasi:TRACE,TOOL_CALL, atauSESSION.

evaluationInput

Objek

Berisi rentang sesi untuk evaluasi.

evaluationInput.sessionSpans

Daftar

Sesi berlangsung untuk mengevaluasi. Dapat dipotong jika muatan asli melebihi 6 MB.

evaluationReferenceInputs

Daftar

Input referensi diberikan kepada evaluator, disaring berdasarkan tingkat evaluasi. Lihat Menggunakan kebenaran dasar dalam evaluator berbasis kode.

evaluationTarget

Objek

Mengidentifikasi jejak atau rentang spesifik untuk dievaluasi. Untuk evaluator tingkat sesi, nilai ini adalah. None

evaluationTarget.traceIds

Daftar

ID jejak target evaluasi. Hadir untuk evaluasi tingkat jejak dan tingkat alat.

evaluationTarget.spanIds

Daftar

ID rentang target evaluasi. Hadir untuk evaluasi tingkat alat.

Skema respons

Fungsi Lambda Anda harus mengembalikan objek JSON yang cocok dengan salah satu dari dua format:

Respon sukses

{ "label": "PASS", "value": 1.0, "explanation": "All validation checks passed." }
Bidang Diperlukan Tipe Deskripsi

label

Ya

String

Label kategoris untuk hasil evaluasi (misalnya, “LULUS”, “GAGAL”, “Baik”, “Miskin”).

value

Tidak

Bilangan

Skor numerik (misalnya, 0,0 hingga 1,0).

explanation

Tidak

String

Penjelasan hasil evaluasi yang dapat dibaca manusia.

Respon kesalahan

{ "errorCode": "VALIDATION_FAILED", "errorMessage": "Input spans missing required tool call attributes." }
Bidang Diperlukan Tipe Deskripsi

errorCode

Ya

String

Kode yang mengidentifikasi kesalahan.

errorMessage

Ya

String

Deskripsi kesalahan yang dapat dibaca manusia.

Buat evaluator berbasis kode

CreateEvaluatorAPI membuat evaluator berbasis kode dengan menentukan fungsi Lambda ARN dan batas waktu opsional.

Parameter yang diperlukan: Nama evaluator unik, tingkat evaluasi (TRACE,, atauSESSION)TOOL_CALL, dan konfigurasi evaluator berbasis kode yang berisi Lambda ARN.

Code-based konfigurasi evaluator:

{ "codeBased": { "lambdaConfig": { "lambdaArn": "arn:aws:lambda:region:account-id:function:function-name", "lambdaTimeoutInSeconds": 60 } } }
Bidang Diperlukan Default Deskripsi

lambdaArn

Ya

—

ARN dari fungsi Lambda untuk dipanggil.

lambdaTimeoutInSeconds

Tidak

60

Batas waktu dalam detik untuk pemanggilan Lambda (1—300).

Contoh kode berikut menunjukkan cara membuat evaluator berbasis kode menggunakan pendekatan pengembangan yang berbeda.

contoh
AgentCore CLI
  1. agentcore add evaluator \ --name "MyCodeEvaluator" \ --level TRACE \ --type code-based \ --lambda-arn "arn:aws:lambda:us-east-1:123456789012:function:my-eval-function" \ --timeout 120
AgentCore SDK
  1. from bedrock_agentcore.evaluation.code_based_evaluators import ( EvaluatorInput, EvaluatorOutput, code_based_evaluator, ) import json as _json @code_based_evaluator() def json_response_evaluator(input: EvaluatorInput) -> EvaluatorOutput: """Check if the agent response in the target trace contains valid JSON.""" for span in input.session_spans: if span.get("traceId") != input.target_trace_id: continue if span.get("name", "").startswith("Model:") or span.get("name") == "Agent.invoke": output = span.get("attributes", {}).get("gen_ai.completion", "") try: _json.loads(output) return EvaluatorOutput( value=1.0, label="Pass", explanation="Response contains valid JSON" ) except (ValueError, TypeError): pass return EvaluatorOutput( value=0.0, label="Fail", explanation="No valid JSON found in agent response" )
AWS SDK
  1. import boto3 client = boto3.client('bedrock-agentcore-control') response = client.create_evaluator( evaluatorName="MyCodeEvaluator", level="TRACE", evaluatorConfig={ "codeBased": { "lambdaConfig": { "lambdaArn": "arn:aws:lambda:us-east-1:123456789012:function:my-eval-function", "lambdaTimeoutInSeconds": 120 } } } ) print(f"Evaluator ID: {response['evaluatorId']}") print(f"Evaluator ARN: {response['evaluatorArn']}")
AWS CLI
  1. aws bedrock-agentcore-control create-evaluator \ --evaluator-name 'MyCodeEvaluator' \ --level TRACE \ --evaluator-config '{ "codeBased": { "lambdaConfig": { "lambdaArn": "arn:aws:lambda:us-east-1:123456789012:function:my-eval-function", "lambdaTimeoutInSeconds": 120 } } }'

Jalankan evaluasi sesuai permintaan dengan evaluator berbasis kode

Setelah dibuat, gunakan evaluator berbasis kode khusus dengan Evaluate API dengan cara yang sama seperti Anda menggunakan evaluator lainnya. Layanan ini menangani pemanggilan Lambda, fan-out paralel, dan pemetaan hasil secara otomatis.

contoh
AgentCore CLI
  1. agentcore run eval \ --runtime "your_runtime_name" \ --session-id "your_session_id" \ --evaluator "code-based-evaluator-id"
AgentCore SDK
  1. from bedrock_agentcore.evaluation.client import EvaluationClient client = EvaluationClient( region_name="region" ) results = client.run( evaluator_ids=[ "code-based-evaluator-id", ], session_id="session-id", log_group_name="log-group-name", )
AWS SDK
  1. import boto3 client = boto3.client('bedrock-agentcore') response = client.evaluate( evaluatorId="code-based-evaluator-id", evaluationInput={"sessionSpans": session_span_logs} ) for result in response["evaluationResults"]: if "errorCode" in result: print(f"Error: {result['errorCode']} - {result['errorMessage']}") else: print(f"Label: {result['label']}, Value: {result.get('value')}") print(f"Explanation: {result.get('explanation', '')}")
AWS CLI
  1. aws bedrock-agentcore evaluate \ --cli-input-json file://session_span_logs.json

Menggunakan target evaluasi

Anda dapat menargetkan jejak atau rentang tertentu, seperti dengan LLM-based evaluator:

# Trace-level evaluation response = client.evaluate( evaluatorId="code-based-evaluator-id", evaluationInput={"sessionSpans": session_span_logs}, evaluationTarget={"traceIds": ["trace-id-1", "trace-id-2"]} ) # Tool-level evaluation response = client.evaluate( evaluatorId="code-based-evaluator-id", evaluationInput={"sessionSpans": session_span_logs}, evaluationTarget={"spanIds": ["span-id-1", "span-id-2"]} )

Menggunakan kebenaran dasar dalam evaluator berbasis kode

Ketika input referensi kebenaran ground dikonfigurasi, fungsi Lambda Anda menerimanya di evaluationReferenceInputs lapangan. Input referensi yang disertakan tergantung pada tingkat evaluasi:

Tingkat evaluasi Lambda menerima

SESSION

Semua input referensi.

TRACE

Session-level input referensi ditambah input referensi yang cocok dengan target TraceID.

TOOL_CALL

Session-level input referensi ditambah input referensi yang cocok dengan spanID target.

catatan

Untuk informasi selengkapnya tentang menggunakan evaluasi kebenaran dasar, lihat Evaluasi kebenaran dasar.

Jalankan evaluasi online dengan evaluator berbasis kode

Anda dapat menggunakan evaluator berbasis kode khusus dalam konfigurasi evaluasi online untuk terus memantau lalu lintas langsung agen Anda. Berikan ID evaluator dalam evaluators daftar saat menelep CreateOnlineEvaluationConfig on.

contoh
AgentCore CLI
  1. agentcore add online-eval \ --name "your_config_name" \ --runtime "your_runtime_name" \ --evaluator "code-based-evaluator-id" \ --sampling-rate 1.0 \ --enable-on-create

    Perintah ini menambahkan konfigurasi evaluasi online ke lokal Andaagentcore.json. J agentcore deploy alankan untuk membuatnya di AWS akun Anda.

    catatan

    Jalankan ini dari dalam direktori AgentCore proyek (dibuat denganagentcore create).

AgentCore SDK
  1. from bedrock_agentcore_starter_toolkit import Evaluation eval_client = Evaluation() config = eval_client.create_online_config( config_name="my_online_eval_config", agent_id="agent-id", sampling_rate=1.0, evaluator_list=["code-based-evaluator-id"], enable_on_create=True ) print(f"Config ID: {config['onlineEvaluationConfigId']}")
AWS SDK
  1. import boto3 client = boto3.client('bedrock-agentcore-control') response = client.create_online_evaluation_config( onlineEvaluationConfigName="my_online_eval_config", rule={"samplingConfig": {"samplingPercentage": 100.0}}, dataSourceConfig={ "cloudWatchLogs": { "logGroupNames": ["/aws/agentcore/my-agent-traces"], "serviceNames": ["my-agent.DEFAULT"] } }, evaluators=[{"evaluatorId": "code-based-evaluator-id"}], evaluationExecutionRoleArn="arn:aws:iam::account-id:role/AgentCoreEvaluationRole", enableOnCreate=True ) print(f"Config ID: {response['onlineEvaluationConfigId']}")
AWS CLI
  1. aws bedrock-agentcore-control create-online-evaluation-config \ --online-evaluation-config-name "my_online_eval_config" \ --rule '{"samplingConfig": {"samplingPercentage": 100.0}}' \ --data-source-config '{"cloudWatchLogs": {"logGroupNames": ["/aws/agentcore/my-agent-traces"], "serviceNames": ["my-agent.DEFAULT"]}}' \ --evaluators '[{"evaluatorId": "code-based-evaluator-id"}]' \ --evaluation-execution-role-arn "arn:aws:iam::account-id:role/AgentCoreEvaluationRole" \ --enable-on-create
catatan

Ketika konfigurasi evaluasi online yang mereferensikan evaluator berbasis kode diaktifkan, evaluator secara otomatis dikunci dan tidak dapat dimodifikasi atau dihapus sampai konfigurasi dinonaktifkan atau dihapus. Untuk membuat perubahan pada evaluator, nonaktifkan konfigurasi evaluasi online terlebih dahulu, atau kloning evaluator dan buat konfigurasi baru.