aws-cdk-lib/aws-bedrockagentcore/lib/evaluation/custom-evaluator.d.ts

Version 2 of the AWS Cloud Development Kit library

/**
 *  Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
 *
 *  Licensed under the Apache License, Version 2.0 (the "License"). You may not use this file except in compliance
 *  with the License. A copy of the License is located at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 *  or in the 'license' file accompanying this file. This file is distributed on an 'AS IS' BASIS, WITHOUT WARRANTIES
 *  OR CONDITIONS OF ANY KIND, express or implied. See the License for the specific language governing permissions
 *  and limitations under the License.
 */
import type { Construct } from 'constructs';
import { type IEvaluator, EvaluatorBase } from './evaluator-base';
import type { EvaluatorConfig } from './evaluator-config';
import type { EvaluationLevel, EvaluatorAttributes } from './types';
/**
 * Properties for creating an Evaluator.
 */
export interface EvaluatorProps {
    /**
     * The name of the evaluator.
     *
     * Must be unique within your account. Valid characters are a-z, A-Z, 0-9, _ (underscore).
     * Must start with a letter and can be up to 48 characters long.
     *
     * @pattern ^[a-zA-Z][a-zA-Z0-9_]{0,47}$
     */
    readonly evaluatorName: string;
    /**
     * The configuration that defines how the evaluator assesses agent performance.
     *
     * Use `EvaluatorConfig.llmAsAJudge()` for model-based evaluation or
     * `EvaluatorConfig.codeBased()` for Lambda-based evaluation.
     */
    readonly evaluatorConfig: EvaluatorConfig;
    /**
     * The level at which the evaluator assesses agent performance.
     *
     * Determines what granularity of data the evaluator operates on:
     * tool call, trace (single request-response), or session (full conversation).
     */
    readonly level: EvaluationLevel;
    /**
     * The description of the evaluator.
     *
     * @default - No description
     * @maxLength 200
     */
    readonly description?: string;
    /**
     * Tags for the evaluator.
     * A list of key:value pairs of tags to apply to this Evaluator resource.
     *
     * @default - No tags
     */
    readonly tags?: {
        [key: string]: string;
    };
}
/**
 * A custom evaluator for Amazon Bedrock AgentCore.
 *
 * Custom evaluators enable you to define evaluation logic tailored to your specific
 * use cases. Supports two evaluation strategies:
 * - **LLM-as-a-Judge**: Uses a foundation model with custom instructions and a rating scale.
 * - **Code-based**: Uses a Lambda function for custom evaluation logic.
 *
 * Custom evaluators are used with `OnlineEvaluationConfig` via `EvaluatorSelector.custom()`.
 *
 * @resource AWS::BedrockAgentCore::Evaluator
 *
 * @example
 * // Create a custom LLM-as-a-Judge evaluator
 * const evaluator = new agentcore.Evaluator(this, 'MyEvaluator', {
 *   evaluatorName: 'my_custom_evaluator',
 *   level: agentcore.EvaluationLevel.SESSION,
 *   evaluatorConfig: agentcore.EvaluatorConfig.llmAsAJudge({
 *     instructions: 'Evaluate whether the agent response is helpful and accurate.',
 *     modelId: 'us.anthropic.claude-sonnet-4-6',
 *     ratingScale: agentcore.EvaluatorRatingScale.categorical([
 *       { label: 'Good', definition: 'The response is helpful and accurate.' },
 *       { label: 'Bad', definition: 'The response is not helpful or contains errors.' },
 *     ]),
 *   }),
 * });
 *
 * // Use the custom evaluator in an online evaluation configuration
 * new agentcore.OnlineEvaluationConfig(this, 'MyEvaluation', {
 *   onlineEvaluationConfigName: 'my_evaluation',
 *   evaluators: [
 *     agentcore.EvaluatorSelector.builtin(agentcore.BuiltinEvaluator.HELPFULNESS),
 *     agentcore.EvaluatorSelector.custom(evaluator),
 *   ],
 *   dataSource: agentcore.DataSourceConfig.fromCloudWatchLogs({
 *     logGroupNames: ['/aws/bedrock-agentcore/my-agent'],
 *     serviceNames: ['my-agent.default'],
 *   }),
 * });
 */
export declare class Evaluator extends EvaluatorBase {
    /** Uniquely identifies this class. */
    static readonly PROPERTY_INJECTION_ID: string;
    /**
     * Import an existing Evaluator by its ID.
     *
     * @param scope - The construct scope
     * @param id - Construct identifier
     * @param evaluatorId - The evaluator ID to import
     * @returns An IEvaluator reference
     */
    static fromEvaluatorId(scope: Construct, id: string, evaluatorId: string): IEvaluator;
    /**
     * Import an existing Evaluator by its ARN.
     *
     * @param scope - The construct scope
     * @param id - Construct identifier
     * @param evaluatorArn - The evaluator ARN to import
     * @returns An IEvaluator reference
     */
    static fromEvaluatorArn(scope: Construct, id: string, evaluatorArn: string): IEvaluator;
    /**
     * Import an existing Evaluator from its attributes.
     *
     * @param scope - The construct scope
     * @param id - Construct identifier
     * @param attrs - The evaluator attributes
     * @returns An IEvaluator reference
     */
    static fromEvaluatorAttributes(scope: Construct, id: string, attrs: EvaluatorAttributes): IEvaluator;
    /**
     * The ARN of the evaluator.
     * @attribute
     */
    readonly evaluatorArn: string;
    /**
     * The unique identifier of the evaluator.
     * @attribute
     */
    readonly evaluatorId: string;
    /**
     * The name of the evaluator.
     * @attribute
     */
    readonly evaluatorName: string;
    /**
     * The lifecycle status of the evaluator.
     * @attribute
     */
    readonly status?: string;
    /**
     * The timestamp when the evaluator was created.
     * @attribute
     */
    readonly createdAt?: string;
    /**
     * The timestamp when the evaluator was last updated.
     * @attribute
     */
    readonly updatedAt?: string;
    constructor(scope: Construct, id: string, props: EvaluatorProps);
}