View a markdown version of this page

온라인 평가 생성 - Amazon Bedrock AgentCore

기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.

온라인 평가 생성

CreateOnlineEvaluationConfig API는 라이브 트래픽을 사용하여 에이전트의 성능을 지속적으로 모니터링하는 새로운 온라인 평가 구성을 생성합니다. 이 비동기 작업은 서비스에 에이전트 추적이 정상 작업 중에 생성될 때 에이전트 추적을 평가하도록 지시합니다.

온라인 평가를 생성하려면 고유한 구성 이름을 제공하고, 모니터링할 대상을 선택하고, 최대 10명의 평가자를 선택하고, 실행을 위한 IAM 서비스 역할 ARN을 제공합니다. 데이터 소스는 정확한 로그 그룹 이름 또는 로그 그룹 이름 접두사 또는 에이전트 엔드포인트로 선택한 CloudWatch Logs일 수 있습니다. 필수 enableOnCreate 파라미터는 초기를 제어ENABLED합니다executionStatus. true는에서 구성을 false 시작하고에서 시작합니다DISABLED.

실행 상태 제어

executionStatus 파라미터는 평가 작업이 트레이스를 능동적으로 처리하는지 여부를 결정합니다.

  • ENABLED - 평가 작업이 지속적으로 실행되어 수신 추적을 처리하고 평가 결과를 생성합니다.

  • 비활성화됨 - 평가 구성이 존재하지만 작업이 일시 중지되었습니다. 트레이스는 처리되거나 평가되지 않습니다.

CLI를 사용하여 실행 상태를 제어할 수 있습니다.

# Pause a running online evaluation agentcore pause online-eval "your_config_name" # Resume a paused online evaluation agentcore resume online-eval "your_config_name"

입력 로그 그룹 선택

데이터 소스가 CloudWatch Logs인 경우 다음 방법 중 정확히 하나로 dataSourceConfig.cloudWatchLogs를 구성합니다.

  • logGroupNames - 로그 그룹 이름의 명시적 목록을 제공합니다.

  • logGroupNamePrefixes - 1~5개의 로그 그룹 이름 접두사를 제공합니다. 서비스는 나중에 생성되는 일치하는 로그 그룹을 포함하여 이름이 접두사 중 하나로 시작하는 모든 로그 그룹의 추적을 평가합니다.

어느 경우든 서비스가 선택한 로그 그룹에서 에이전트의 트레이스를 식별할 수 serviceNames 있도록를 설정합니다.

logGroupNamePrefixes를 사용하여 Amazon Bedrock AgentCore 런타임 로그 그룹과 일치하는 경우 런타임이 에이전트의 자체 로그 그룹으로 범위를 전송하는지 확인합니다. 여전히 공유 aws/spans 로그 그룹을 사용하는 에이전트의 경우 런타임UNIFIED_TRACES_DESTINATION_ENABLED=true에를 설정합니다. 자세한 내용은 Amazon Bedrock AgentCore 런타임에서 호스팅되는 에이전트의 범위 대상을 참조하세요.

# Match input log groups by prefix instead of exact names dataSourceConfig={ "cloudWatchLogs": { "logGroupNamePrefixes": ["/aws/agentcore/my-agent-"], "serviceNames": ["my_agent.DEFAULT"] } }

전용, 사용자 지정 및 소스 로그 그룹을 포함하여 결과 및 점수 지표가 기록되는 위치에 대한 자세한 내용은 결과 및 출력을 참조하세요.

평가자 보호

를 ENABLED 로 executionStatus 설정하여 평가 구성을 생성하면 선택한 사용자 지정 평가자가 자동으로 잠깁니다. 잠긴 후:

  • 수정 불가 - 평가자의 구성, 프롬프트 또는 설정을 업데이트할 수 없습니다. 변경해야 하는 경우 새 평가자를 복제합니다.

  • 삭제 불가 - 평가 작업이 평가자를 사용하는(실행 중인) 동안에는 평가자를 삭제할 수 없습니다.

AgentCore CLI, AgentCore SDK 및 AWS SDK용 코드 샘플

다음 코드 샘플은 다양한 개발 접근 방식을 사용하여 온라인 평가 구성을 생성하는 방법을 보여줍니다. 개발 환경 및 기본 설정에 가장 적합한 방법을 선택합니다.

예
AgentCore CLI
  1. # Create online evaluation configuration agentcore add online-eval \ --name "your_config_name" \ --runtime "your_runtime_name" \ --evaluator "Builtin.GoalSuccessRate" "Builtin.Helpfulness" \ --sampling-rate 1.0 \ --enable-on-create

    이 명령은 온라인 평가 구성을 로컬 agentcore.json에 추가합니다. agentcore deploy를 실행하여 AWS 계정에서 생성합니다.

    참고

    AgentCore 프로젝트 디렉터리(로 생성됨) 내에서이 작업을 실행합니다agentcore create.

Interactive
  1. 온라인 평가 구성의 이름을 입력합니다.

    온라인 평가 구성 이름 입력
  2. 포함할 평가자를 선택합니다. 기본 제공 평가자와 생성한 사용자 지정 평가자 중에서 선택할 수 있습니다.

    평가자 다중 선택 목록
  3. 샘플링 속도 설정 - 평가할 에이전트 요청의 백분율입니다.

    샘플링 속도 입력
  4. 배포 후 평가를 자동으로 활성화할지 여부를 선택합니다.

    배포 선택 시 활성화
  5. 구성을 검토하고 Enter 키를 눌러 확인합니다.

    온라인 평가 구성 검토
AgentCore SDK
  1. from bedrock_agentcore_starter_toolkit import Evaluation # Initialize the evaluation client eval_client = Evaluation() # Replace these with your actual values config_name = "YOUR_CONFIG_NAME" agent_id = "YOUR_AGENT_ID" # e.g., agent_myagent-ABC123xyz # Create online evaluation configuration config = eval_client.create_online_config( config_name=config_name, # Must use underscores, not hyphens agent_id=agent_id, # Agent ID (e.g., agent_myagent-ABC123xyz) sampling_rate=1.0, # Percentage to evaluate (0-100). 1.0 = evaluate 1% of interactions evaluator_list=["Builtin.GoalSuccessRate", "Builtin.Helpfulness"], # List of evaluator IDs config_description="Online Evaluation Config", # Optional description auto_create_execution_role=True, # Automatically creates IAM role (default: True) enable_on_create=True # Enable immediately after creation (default: True) ) print("✅ Online evaluation configuration created!") print(f"Config ID: {config['onlineEvaluationConfigId']}") print(f"Status: {config['status']}") # Save the config ID for later operations config_id = config['onlineEvaluationConfigId'] print(f"\nSaved config_id: {config_id}")
AWS SDK
  1. import boto3 # Your input log group that contains agent traces LOG_GROUP_NAME = "/aws/agentcore/test-agent-traces" # The service.name attribute from Otel SERVICE_NAME = "strands_healthcare_single_agent.DEFAULT" # The role created earlier with the required permissions for eval role_arn = f"arn:aws:iam::{ACCOUNT_ID}:role/AgentCoreEvaluationRole" client = boto3.client('bedrock-agentcore-control') create_config_response = client.create_online_evaluation_config( onlineEvaluationConfigName="strands_healthcare_agent_1", description="Continuous evaluation of a healthcare agent", rule={ "samplingConfig": {"samplingPercentage": 80.0} }, dataSourceConfig={ "cloudWatchLogs": { "logGroupNames": [LOG_GROUP_NAME], "serviceNames": [SERVICE_NAME] } }, evaluators=[{"evaluatorId":"Builtin.Helpfulness"}], evaluationExecutionRoleArn=role_arn, enableOnCreate=True )
AWS CLI
  1. aws bedrock-agentcore-control create-online-evaluation-config \ --online-evaluation-config-name "strands_healthcare_agent_1" \ --description "Continuous evaluation of a healthcare agent" \ --rule '{"samplingConfig": {"samplingPercentage": 80.0}}' \ --data-source-config '{"cloudWatchLogs": {"logGroupNames": ["/aws/agentcore/test-agent-traces"], "serviceNames": ["strands_healthcare_single_agent.DEFAULT"]}}' \ --evaluators '[{"evaluatorId": "Builtin.Helpfulness"}]' \ --evaluation-execution-role-arn "arn:aws:iam::{YOUR_ACCOUNT_ID}:role/AgentCoreEvaluationRole" \ --enable-on-create

콘솔

Amazon Bedrock AgentCore 콘솔의 시각적 인터페이스를 사용하여 온라인 평가 구성을 생성할 수 있습니다. 이 방법은 평가 설정을 구성하는 데 도움이 되는 안내 양식 및 검증을 제공합니다.

AgentCore 온라인 평가를 생성하려면

  1. Amazon Bedrock AgentCore 콘솔을 엽니다.

  2. 왼쪽 탐색 창에서 평가를 선택합니다.

  3. 평가 구성 생성을 선택합니다.

    1. (선택 사항) 평가 이름에 온라인 평가 구성의 이름을 입력합니다.

    2. (선택 사항) 평가 구성을 생성한 후 활성화하려면 평가 이름 아래의 확인란을 선택합니다.

    3. (선택 사항) 평가 구성 설명에 AgentCore 평가 구성에 대한 설명을 입력합니다.

    4. (선택 사항) 세션 유휴 제한 시간에 1~60분의 기간을 입력합니다. 기본값은 15분입니다.

  4. 데이터 소스에서 다음 중 하나를 선택합니다.

    1. 에이전트 엔드포인트로 정의 - AgentCore 런타임에서 이전에 생성한 에이전트를 선택하거나 에이전트를 선택하여 새 에이전트를 생성합니다. 그런 다음 에이전트에서 엔드포인트를 선택합니다.

    2. CloudWatch 로그 그룹 선택 - 최대 5개의 로그 그룹을 선택합니다. 관찰성을 위해 에이전트가 사용하는 서비스 이름을 입력합니다. AgentCore 런타임에서 호스팅되는 에이전트의 경우 서비스 이름은 <agent-runtime-name>.<agent-runtime-endpoint-name> 형식을 따릅니다. AgentCore 런타임 외부에서 실행되는 에이전트의 경우 서비스 이름은 OTEL_RESOURCE_ATTRIBUTES 환경 변수에 구성됩니다.

  5. 평가자에서 기본 제공 평가자와 사용자 지정 평가자를 포함하여 평가 구성당 최대 10명의 평가자를 선택합니다.

  6. (선택 사항) 필터의 경우 평가할 세션을 식별하기 위해 최대 5개의 필터를 추가합니다.

  7. (선택 사항) 샘플링에서 0.01%에서 100% 사이의 백분율을 선택하여 평가되는 세션의 백분율을 제어합니다. 기본값은 10%입니다.

  8. Amazon Bedrock IAM 역할에서 다음 중 하나를 선택합니다.

    참고

    계정에서 역할 관리자가 활성화된 경우 AgentCore는 역할을 자동으로 연결하며 여기에 설명된 역할 선택 단계는 사용자 지정 옵션으로 대체됩니다. 다른 역할을 사용하려면 사용자 지정을 선택합니다. 자세한 내용은 IAM 사용 설명서의 IAM 역할 생성을 참조하세요.

    1. 기존 역할 사용 - 이미 필요한 권한이 있는 IAM 서비스 역할을 선택합니다.

    2. 새 역할 생성 - 새 IAM 서비스 역할을 생성합니다.

  9. 평가 구성 생성을 선택하여 AgentCore 온라인 평가 구성을 생성합니다.