View a markdown version of this page

创建在线评估 - 亚马逊基岩 AgentCore

本文属于机器翻译版本。若本译文内容与英语原文存在差异,则一律以英文原文为准。

创建在线评估

该 CreateOnlineEvaluationConfig API 创建了新的在线评估配置,使用实时流量持续监控代理的绩效。此异步操作告诉服务在正常运行期间生成的代理跟踪时对其进行评估。

要创建在线评估,请提供唯一的配置名称,选择要监控的内容,选择最多 10 个评估者,并提供 IAM 服务角色 ARN 以供执行。数据源可以是 CloudWatch 日志,按确切的日志组名称或日志组名称前缀选择,也可以是代理端点。必需的enableOnCreate参数控制初始值executionStatus:在中true启动配置ENABLED,然后在中false启动配置DISABLED。

执行状态控制

该executionStatus参数决定评估作业是否主动处理跟踪:

  • 启用 — 评估作业持续运行,处理传入的跟踪并生成评估结果。

  • 已禁用 -评估配置存在,但作业已暂停。未处理或评估任何痕迹。

您可以使用 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 日志,请使用以下方式之一进行配置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"] } }

有关结果和分数指标的写入位置(包括专用、自定义和源日志组)的更多信息,请参阅结果和输出。

评估员保护

当您创建executionStatus设置为的评估配置时ENABLED,系统会自动锁定您选择的所有自定义评估器。锁定后:

  • 不允许修改 -您无法更新评估者的配置、提示或设置。如果您需要进行更改,请克隆一个新的评估器。

  • 不允许删除 -当任何评估作业正在使用该评估器(正在运行)时,您都不能将其删除。

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

控制台

您可以使用亚马逊 Bedrock AgentCore 控制台的可视化界面创建在线评估配置。此方法提供指导性表单和验证,以帮助您配置评估设置。

创建 AgentCore 在线评估

  1. 打开亚马逊 Bedrock AgentCore 控制台。

  2. 在左侧导航窗格中,选择评估。

  3. 选择 “创建评估配置” 。

    1. (可选)对于评估名称,输入在线评估配置的名称。

    2. (可选)要在创建评估配置后将其启用,请选中评估名称下方的复选框。

    3. (可选)在评估配置描述中,输入 AgentCore 评估配置的描述。

    4. (可选)对于会话空闲超时,输入介于 1 到 60 分钟之间的持续时间。默认为 15 分钟。

  4. 对于数据源,选择以下选项之一:

    1. 使用代理端点进行定义 -选择先前在 AgentCore Runtime 上创建的代理,或通过选择 “代理” 来创建新的代理。然后,从代理中选择一个端点。

    2. 选择 CloudWatch 日志组 -最多选择 5 个日志组。输入您的代理为实现可观察性而使用的服务名称。对于在 AgentCore Runtime 上托管的代理,服务名称遵循格式<agent-runtime-name>。<agent-runtime-endpoint-name>。对于在运行 AgentCore 时之外运行的代理,服务名称在 OTEL_RESOURCE_ATTRIBUTES 环境变量中配置。

  5. 对于评估器,每个评估配置最多选择 10 个评估器,包括内置和自定义评估器。

  6. (可选)对于筛选器,最多添加 5 个筛选条件以确定要评估哪些会话。

  7. (可选)对于采样,选择介于 0.01% 和 100% 之间的百分比以控制评估的会话百分比。默认值为 10%。

  8. 对于亚马逊 Bedrock IAM 角色,请选择以下任一选项:

    注意

    如果您的账户中启用了角色管理器,则会为您 AgentCore 附加角色,此处描述的角色选择步骤将替换为 “自定义” 选项。要使用其它角色,请选择自定义。有关更多信息,请参阅《IAM 用户指南》中的 IAM 角色创建。

    1. 使用现有角色 -选择已经具有所需权限的 IAM 服务角色。

    2. 创建新角色 — 创建新的 IAM 服务角色。

  9. 选择创建评估配置以创建 AgentCore 在线评估配置。