View a markdown version of this page

Crie uma avaliação on-line - Amazon Bedrock AgentCore

Crie uma avaliação on-line

A CreateOnlineEvaluationConfig API cria uma nova configuração de avaliação on-line que monitora continuamente o desempenho do seu agente usando tráfego ao vivo. Essa operação assíncrona configura o serviço para avaliar os rastreamentos do agente à medida que eles são gerados durante a operação normal.

Ao criar uma avaliação on-line, você especifica um nome de configuração exclusivo, a fonte de dados a ser monitorada (uma lista de grupos de CloudWatch registros ou um endpoint do agente) e uma lista de avaliadores a serem aplicados (até 10, combinando avaliadores integrados e personalizados). Você também fornece um ARN da função de serviço do IAM para execução. O enableOnCreate parâmetro é obrigatório e determina se a avaliação começa a ser executada imediatamente após a criação (executionStatus= true) ou permanece desativada até ser explicitamente ativada (executionStatus= false).

Controle do status de execução

O executionStatus parâmetro determina se o trabalho de avaliação processa ativamente os rastreamentos:

  • HABILITADO — O trabalho de avaliação é executado continuamente, processando rastreamentos recebidos e gerando resultados de avaliação.

  • DESATIVADO — A configuração de avaliação existe, mas o trabalho está pausado. Nenhum traço é processado ou avaliado.

Você pode controlar o status da execução usando a 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"

Proteção do avaliador

Quando você cria uma configuração de avaliação com executionStatus definido comoENABLED, o sistema bloqueia automaticamente todos os avaliadores personalizados que você selecionou. Uma vez bloqueado:

  • Nenhuma modificação permitida — Você não pode atualizar a configuração, as solicitações ou as configurações do avaliador. Clone um novo avaliador se precisar fazer alterações.

  • Nenhuma exclusão permitida — Você não pode excluir o avaliador enquanto qualquer trabalho de avaliação o estiver usando (em execução).

Exemplos de código para AgentCore CLI, AgentCore SDK e AWS SDK

Os exemplos de código a seguir demonstram como criar configurações de avaliação on-line usando diferentes abordagens de desenvolvimento. Escolha o método mais adequado ao seu ambiente de desenvolvimento e às suas preferências.

exemplo
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

    Esse comando adiciona a configuração de avaliação on-line ao seu localagentcore.json. Corra agentcore deploy para criá-lo em sua AWS conta.

    nota

    Execute isso de dentro de um diretório de AgentCore projeto (criado comagentcore create).

Interactive
  1. Insira um nome para sua configuração de avaliação on-line.

    Entrada online do nome da configuração de avaliação
  2. Selecione os avaliadores a serem incluídos. Você pode escolher entre avaliadores integrados e quaisquer avaliadores personalizados que você tenha criado.

    Lista de seleção múltipla do avaliador
  3. Defina a taxa de amostragem — a porcentagem de solicitações de agentes que serão avaliadas.

    Entrada da taxa de amostragem
  4. Escolha se deseja ativar a avaliação automaticamente após a implantação.

    Ativar na seleção de implantação
  5. Revise a configuração e pressione Enter para confirmar.

    Revise a configuração de avaliação on-line
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

Console

Você pode criar configurações de avaliação on-line usando a interface visual do AgentCore console Amazon Bedrock. Esse método fornece formulários guiados e validação para ajudá-lo a definir suas configurações de avaliação.

Para criar uma avaliação AgentCore on-line

  1. Abra o AgentCore console Amazon Bedrock.

  2. No painel de navegação esquerdo, escolha Avaliação.

  3. Escolha Criar configuração de avaliação.

    1. (Opcional) Em Nome da avaliação, insira um nome para a configuração da avaliação on-line.

    2. (Opcional) Para ativar a configuração da avaliação após sua criação, marque a caixa de seleção abaixo do nome da avaliação.

    3. (Opcional) Em Descrição da configuração de avaliação, insira uma descrição para a configuração de AgentCore avaliação.

    4. (Opcional) Em Tempo limite de inatividade da sessão, insira uma duração entre 1 e 60 minutos. O padrão é 15 minutos.

  4. Em Fonte de dados, escolha uma das seguintes opções:

    1. Defina com um endpoint de agente — Escolha um agente que você criou anteriormente no AgentCore Runtime ou crie um novo agente escolhendo Agentes. Em seguida, escolha um endpoint do agente.

    2. Selecione um grupo de CloudWatch registros — Selecione até 5 grupos de registros. Insira o nome do serviço usado pelo seu agente para fins de observabilidade. Para agentes hospedados no AgentCore Runtime, o nome do serviço segue o formato<agent-runtime-name>. <agent-runtime-endpoint-name>. Para agentes executados fora do AgentCore Runtime, o nome do serviço é configurado na variável de ambiente OTEL_RESOURCE_ATTRIBUTES.

  5. Para avaliadores, selecione até 10 avaliadores por configuração de avaliação, incluindo avaliadores integrados e personalizados.

  6. (Opcional) Para Filtros, adicione até 5 filtros para identificar quais sessões avaliar.

  7. (Opcional) Para Amostragem, escolha uma porcentagem entre 0,01% e 100% para controlar a porcentagem de sessões que são avaliadas. O padrão é 10%.

  8. Para a função Amazon Bedrock IAM, escolha uma das seguintes opções:

    1. Use uma função existente — Selecione uma função de serviço do IAM que já tenha as permissões necessárias.

    2. Crie uma nova função — Crie uma nova função de serviço do IAM.

  9. Escolha Criar configuração de avaliação para criar a configuração de avaliação AgentCore on-line.