執行狀態控制選取輸入日誌群組評估器保護 AgentCore CLI、AgentCore SDK 和 AWS SDK 的程式碼範例主控台

建立線上評估

CreateOnlineEvaluationConfig API 會建立新的線上評估組態，以使用即時流量持續監控代理程式的效能。此非同步操作會通知服務在正常操作期間產生代理程式追蹤時評估追蹤。

若要建立線上評估，請提供唯一的組態名稱、選擇要監控的內容、最多選取 10 個評估者，並提供執行的 IAM 服務角色 ARN。資料來源可以是 CloudWatch Logs，由確切的日誌群組名稱或日誌群組名稱字首或客服人員端點選取。所需的enableOnCreate參數會控制初始 executionStatus：在中true啟動組態ENABLED，並在中false啟動組態DISABLED。

主題

執行狀態控制
選取輸入日誌群組
評估器保護
AgentCore CLI、AgentCore SDK 和 AWS SDK 的程式碼範例
主控台

執行狀態控制

executionStatus 參數會判斷評估任務是否主動處理追蹤：

ENABLED – 評估任務會持續執行，處理傳入的追蹤並產生評估結果。
DISABLED – 評估組態存在，但任務已暫停。不會處理或評估任何追蹤。

您可以使用 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"]
    }
}

如需寫入結果和分數指標的詳細資訊，包括專用、自訂和來源日誌群組，請參閱結果和輸出。

評估器保護

當您建立將 executionStatus 設為 ENABLED 的評估組態時，系統會自動鎖定您選取的任何自訂評估器。鎖定後：

不允許修改 – 您無法更新評估者的組態、提示或設定。如果您需要進行變更，請複製新的評估器。
不允許刪除 – 您無法在任何評估任務使用時刪除評估器（執行中）。

AgentCore CLI、AgentCore SDK 和 AWS SDK 的程式碼範例

下列程式碼範例示範如何使用不同的開發方法建立線上評估組態。選擇最適合您的開發環境和偏好設定的方法。

範例

AgentCore CLI


# 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

輸入線上評估組態的名稱。
選取要包含的評估者。您可以從內建評估者和您建立的任何自訂評估者中進行選擇。
設定取樣率 — 將評估的客服人員請求百分比。
選擇是否要在部署後自動啟用評估。
檢閱組態，然後按 Enter 鍵確認。

AgentCore SDK


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


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


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 線上評估

開啟 Amazon Bedrock AgentCore 主控台。
在左側導覽窗格中，選擇評估。
選擇建立評估組態。
1. （選用）針對評估名稱 ，輸入線上評估組態的名稱。
2. （選用）若要在建立評估組態後啟用評估組態，請選取評估名稱下的核取方塊。
3. （選用）針對評估組態描述 ，輸入 AgentCore 評估組態的描述。
4. （選用）針對工作階段閒置逾時 ，輸入介於 1 到 60 分鐘之間的持續時間。預設值為 15 分鐘。
針對資料來源 ，選擇下列其中一項：
1. 使用代理程式端點定義 - 選擇您先前在 AgentCore 執行期建立的代理程式，或選擇代理程式來建立新的代理程式。然後，從代理程式中選擇端點。
2. 選取 CloudWatch 日誌群組 – 選取最多 5 個日誌群組。輸入代理程式用於觀察的服務名稱。對於在 AgentCore 執行期上託管的代理程式，服務名稱遵循格式 <agent-runtime-name>.<agent-runtime-endpoint-name>。對於在 AgentCore 執行期外執行的代理程式，服務名稱是在 OTEL_RESOURCE_ATTRIBUTES 環境變數中設定。
針對評估者 ，每個評估組態最多選取 10 個評估者，包括內建和自訂評估者。
（選用）針對篩選條件 ，新增最多 5 個篩選條件，以識別要評估的工作階段。
（選用）對於取樣，選擇介於 0.01% 到 100% 之間的百分比，以控制評估的工作階段百分比。預設值為 10%。
針對 Amazon Bedrock IAM 角色 ，選擇下列其中一項：

注意
如果您的帳戶已啟用角色管理員，AgentCore 會為您連接角色，此處所述的角色選擇步驟會取代為自訂選項。若要使用不同的角色，請選擇自訂。如需詳細資訊，請參閱《IAM 使用者指南》中的建立 IAM 角色。
1. 使用現有角色 – 選取已具有必要許可的 IAM 服務角色。
2. 建立新的角色 – 建立新的 IAM 服務角色。
選擇建立評估組態以建立 AgentCore 線上評估組態。

您的瀏覽器已停用或無法使用 Javascript。

您必須啟用 Javascript，才能使用 AWS 文件。請參閱您的瀏覽器說明頁以取得說明。

文件慣用形式

建立和部署您的代理程式

取得線上評估