View a markdown version of this page

Evaluator berbasis kode khusus - Batuan Dasar Amazon AgentCore

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 kustom, atau menerapkan aturan khusus bisnis apa pun.

Prasyarat

Untuk menggunakan evaluator berbasis kode khusus, Anda memerlukan:

Izin IAM

Peran eksekusi layanan Anda memerlukan izin tambahan berikut untuk menjalankan 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

Batas waktu runtime maksimum untuk fungsi Lambda adalah 5 menit (300 detik). Ukuran payload 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 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 ini mencakup untuk mengevaluasi. Dapat terpotong 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 bentang tertentu 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”, “Buruk”).

value

Tidak

Bilangan

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

explanation

Tidak

String

Penjelasan yang dapat dibaca manusia tentang hasil evaluasi.

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 ARN fungsi Lambda 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 memanggil.

lambdaTimeoutInSeconds

Tidak

60

Batas waktu dalam hitungan 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 eval evaluator create \ --name "MyCodeEvaluator" \ --level TRACE \ --lambda-arn "arn:aws:lambda:us-east-1:123456789012:function:my-eval-function" \ --lambda-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 halnya 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 dasar dikonfigurasi, fungsi Lambda Anda menerimanya di evaluationReferenceInputs lapangan. Masukan 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 traceID target.

TOOL_CALL

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

catatan

Untuk informasi lebih lanjut 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. Lulus ID evaluator dalam evaluators daftar saat meneleponCreateOnlineEvaluationConfig.

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. Jalankan agentcore deploy 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 merujuk evaluator berbasis kode diaktifkan, evaluator secara otomatis terkunci 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.