先决条件 IAM 权限 Lambda 函数合约创建基于代码的评估器使用基于代码的评估器进行按需评估使用基于代码的评估器进行在线评估

基于代码的自定义评估器

基于自定义代码的评估器允许您使用自己的 Lamb AWS da 函数以编程方式评估代理性能，而不必使用 LLM 作为评判。这使您可以完全控制评估逻辑——您可以实现确定性检查、调用外部 API、运行正则表达式匹配、计算自定义指标或应用任何特定于业务的规则。

先决条件

要使用基于代码的自定义赋值器，您需要：

与您的 AgentCore 评估资源部署在同一区域的 AWS Lambda 函数。
一个 IAM 执行角色，用于向 AgentCore 评估服务授予调用您的 Lambda 函数的权限。
Lambda 函数必须返回符合响应架构中描述的响应架构的 JSON 响应。

IAM 权限

您的服务执行角色需要以下额外权限才能调用 Lambda 函数进行基于代码的评估：


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

Lambda 函数合约

注意

Lambda 函数的最大运行时超时时间为 5 分钟（300 秒）。发送到 Lambda 函数的最大输入负载大小为 6 MB。

输入架构

您的 Lambda 函数会收到具有以下结构的 JSON 有效负载：


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

字段	Type	说明
`schemaVersion`	字符串	有效载荷的架构版本。目前`"1.0"`。
`evaluatorId`	字符串	基于代码的评估者的 ID。
`evaluatorName`	字符串	基于代码的评估器的名称。
`evaluationLevel`	字符串	评估级别：`TRACETOOL_CALL`、或`SESSION`。
`evaluationInput`	对象	包含用于评估的会话跨度。
`evaluationInput.sessionSpans`	列表	会话跨度进行评估。如果原始有效载荷超过 6 MB，则可能会被截断。
`evaluationReferenceInputs`	列表	提供给评估者的参考输入，根据评估级别进行过滤。请参阅在基于代码的赋值器中使用基本真相。
`evaluationTarget`	对象	标识要评估的特定轨迹或跨度。对于会话级别的评估者，此值为。`None`
`evaluationTarget.traceIds`	列表	评估目标的跟踪 ID。用于跟踪级和工具级评估。
`evaluationTarget.spanIds`	列表	评估目标的跨度 ID。用于工具级评估。

响应 schema

您的 Lambda 函数必须返回与以下两种格式之一匹配的 JSON 对象：

成功响应


{
    "label": "PASS",
    "value": 1.0,
    "explanation": "All validation checks passed."
}

字段	必填	Type	Description
`label`	是	字符串	评估结果的分类标签（例如，“通过”、“失败”、“良好”、“差”）。
`value`	否	数字	数字分数（例如，0.0 到 1.0）。
`explanation`	否	字符串	对评估结果的易于理解的解释。

错误响应


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

字段	必填	Type	Description
`errorCode`	是	字符串	识别错误的代码。
`errorMessage`	是	字符串	人类可读的错误描述。

创建基于代码的评估器

CreateEvaluatorAPI 通过指定 Lambda 函数 ARN 和可选的超时时间来创建基于代码的评估器。

必需参数：唯一的评估者姓名、评估级别（TRACETOOL_CALL、或SESSION）以及包含 Lambda ARN 的基于代码的评估器配置。

Code-based 评估器配置：


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

字段	必填	默认值	Description
`lambdaArn`	是	—	要调用的 Lambda 函数的 ARN。
`lambdaTimeoutInSeconds`	否	60	Lambda 调用的超时时间（以秒为单位）(1—300)。

以下代码示例演示了如何使用不同的开发方法创建基于代码的赋值器。

例

AgentCore CLI


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


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


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


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
            }
        }
    }'

使用基于代码的评估器进行按需评估

创建完成后，将基于代码的自定义评估器与 Evaluate API 一起使用，就像使用任何其他评估器一样。该服务会自动处理 Lambda 调用、并行扇出和结果映射。

例

使用评估目标

你可以瞄准特定的轨迹或跨度，就像使用 LLM-based 赋值器一样：


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

在基于代码的赋值器中使用基本真相

配置基本真相参考输入后，您的 Lambda 函数会在字段中evaluationReferenceInputs接收它们。包括的参考输入取决于评估级别：

评估级别	Lambda 收到
`SESSION`	所有参考输入。
`TRACE`	Session-level 参考输入加上与目标 traceID 匹配的参考输入。
`TOOL_CALL`	Session-level 参考输入加上与目标 spanID 匹配的参考输入。

注意

有关使用地面实况评估的更多信息，请参阅地面实况评估。

使用基于代码的评估器进行在线评估

您可以在在线评估配置中使用基于代码的自定义评估器来持续监控代理的实时流量。致CreateOnlineEvaluationConfig电时在evaluators列表中传递评估者 ID。

例

AgentCore CLI

```
agentcore add online-eval \
  --name "your_config_name" \
  --runtime "your_runtime_name" \
  --evaluator "code-based-evaluator-id" \
  --sampling-rate 1.0 \
  --enable-on-create
```
此命令将在线评估配置添加到您的本地agentcore.json。运行agentcore deploy以在您的 AWS 帐户中创建它。

注意
在 AgentCore 项目目录（使用创建agentcore create）中运行它。

AgentCore SDK


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


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


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

注意

启用引用基于代码的评估器的在线评估配置时，评估器会自动锁定，并且在禁用或删除该配置之前无法修改或删除。要对评估器进行更改，请先禁用在线评估配置，或者克隆评估器并创建新配置。

Javascript 在您的浏览器中被禁用或不可用。

要使用 Amazon Web Services 文档，必须启用 Javascript。请参阅浏览器的帮助页面以了解相关说明。

文档惯例

删除赋值器

在线评估