View a markdown version of this page

Crie uma avaliação on-line - Base da Amazônia AgentCore

As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.

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 instrui o serviço a avaliar os rastreamentos do agente à medida que são gerados durante a operação normal.

Para criar uma avaliação on-line, forneça um nome de configuração exclusivo, escolha o que monitorar, selecione até 10 avaliadores e forneça um ARN da função de serviço IAM para execução. A fonte de dados pode ser CloudWatch Logs, selecionados por nomes exatos de grupos de logs ou prefixos de nomes de grupos de logs, ou um endpoint de agente. O enableOnCreate parâmetro necessário controla a inicialexecutionStatus: true inicia a configuração em ENABLED e false a inicia emDISABLED.

Controle do status de execução

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

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

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

Você pode controlar o status de 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"

Selecionar grupos de registros de entrada

Se sua fonte de dados for CloudWatch Logs, configure dataSourceConfig.cloudWatchLogs exatamente de uma das seguintes formas:

  • logGroupNames— Forneça uma lista explícita de nomes de grupos de registros.

  • logGroupNamePrefixes— Forneça de 1 a 5 prefixos de nomes de grupos de registros. O serviço avalia rastreamentos de qualquer grupo de registros cujo nome comece com um desses prefixos, incluindo grupos de registros correspondentes criados posteriormente.

Em ambos os casos, defina serviceNames para que o serviço possa identificar os rastros do seu agente nos grupos de registros selecionados.

Se você usa logGroupNamePrefixes para combinar grupos de logs do Amazon Bedrock AgentCore Runtime, certifique-se de que seu tempo de execução envie períodos para o próprio grupo de logs do agente. Para agentes que ainda usam o grupo de aws/spans log compartilhado, UNIFIED_TRACES_DESTINATION_ENABLED=true defina o tempo de execução. Para obter mais informações, consulte Destino de Span para agentes hospedados no tempo de AgentCore execução do Amazon Bedrock.

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

Para obter mais informações sobre onde os resultados e as métricas de pontuação são gravados, incluindo grupos de registros dedicados, personalizados e de origem, consulte Resultados e saída.

Proteção do avaliador

Quando você cria uma configuração de avaliação com executionStatus set toENABLED, 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, os prompts 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).

Amostras 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 que melhor se adapta 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 de nome de configuração de avaliação online
  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 de 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 de 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. Selecionar um grupo de CloudWatch registros — Selecione até 5 grupos de registros. Insira o nome do serviço usado pelo seu agente para fins de observação. 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) Em 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:

    nota

    Se o gerente de funções estiver habilitado em sua conta, AgentCore anexará a função para você e a etapa de seleção de função descrita aqui será substituída por uma opção Personalizar. Para usar um perfil diferente, escolha Personalizar. Para saber mais informações, consulte Criação do perfil do IAM no Guia do usuário do IAM.

    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.