# Evaluator berbasis kode khusus
<a name="code-based-evaluators"></a>

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
<a name="code-based-evaluators-prerequisites"></a>

Untuk menggunakan evaluator berbasis kode khusus, Anda memerlukan:
+ Fungsi AWS Lambda yang digunakan di Wilayah yang sama dengan sumber daya Evaluasi Anda AgentCore .
+ Peran eksekusi IAM yang memberikan izin layanan AgentCore Evaluasi untuk menjalankan fungsi Lambda Anda.
+ [Fungsi Lambda harus mengembalikan respons JSON yang sesuai dengan skema respons yang dijelaskan dalam skema Respons.](#code-based-response-schema)

## Izin IAM
<a name="code-based-evaluators-iam"></a>

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
<a name="code-based-lambda-contract"></a>

**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
<a name="code-based-input-schema"></a>

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`, atau`SESSION`. | 
|  `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](#code-based-ground-truth). | 
|  `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
<a name="code-based-response-schema"></a>

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
<a name="create-code-based-evaluator"></a>

`CreateEvaluator`API membuat evaluator berbasis kode dengan menentukan ARN fungsi Lambda dan batas waktu opsional.

 **Parameter yang diperlukan:** Nama evaluator unik, tingkat evaluasi (`TRACE`,, atau`SESSION`)`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.

**Example**  

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
   ```

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"
       )
   ```

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']}")
   ```

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
<a name="run-on-demand-code-based"></a>

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.

**Example**  

1. 

   ```
   agentcore run eval \
     --runtime "your_runtime_name" \
     --session-id "your_session_id" \
     --evaluator "code-based-evaluator-id"
   ```

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",
   )
   ```

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', '')}")
   ```

1. 

   ```
   aws bedrock-agentcore evaluate \
       --cli-input-json file://session_span_logs.json
   ```

### Menggunakan target evaluasi
<a name="code-based-evaluation-targets"></a>

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
<a name="code-based-ground-truth"></a>

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](ground-truth-evaluations.md).

## Jalankan evaluasi online dengan evaluator berbasis kode
<a name="run-online-code-based"></a>

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 menelepon`CreateOnlineEvaluationConfig`.

**Example**  

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 Anda`agentcore.json`. Jalankan `agentcore deploy` untuk membuatnya di AWS akun Anda.
**catatan**  
Jalankan ini dari dalam direktori AgentCore proyek (dibuat dengan`agentcore create`).

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']}")
   ```

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']}")
   ```

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.