# Execute um A/B teste para agentes hospedados fora do AgentCore
Você pode A/B testar um agente executado fora do AgentCore Runtime com um agente hospedado em qualquer lugar, por exemplo, no AWS Lambda, no Amazon EKS ou no Amazon ECS. Para agentes A/B de teste, o AgentCore gateway direciona o tráfego entre variantes, a avaliação on-line pontua cada sessão e o serviço calcula a significância estatística por variante. Quando seu agente não está em um AgentCore Runtime, você precisa instrumentá-lo para fins de observabilidade, registrá-lo como um destino de AgentCore gateway e habilitar o rastreamento do gateway para que as sessões possam ser atribuídas a uma variante.
A/B tests oferece suporte a [pacotes de configuração com um único tempo de execução de agente](ab-testing-config-bundle.md), bem como [roteamento baseado em destinos com dois endpoints de agente](ab-testing-target-based.md). Esta página mostra como configurar um endpoint de agente HTTP acessível como um destino no AgentCore gateway com o rastreamento ativado. Em seguida, o rastreamento do AgentCore gateway fornece a atribuição de variantes, e a observabilidade no endpoint do agente fornece o conteúdo da mensagem para pontuação.
Esta página é um adendo para [Executar um A/B teste com roteamento baseado em metas](ab-testing-target-based.md). Ela abrange apenas a configuração extra de que um agente que não está em tempo de execução precisa — usando um Lambda-hosted agente (por trás de uma URL de função) como exemplo; a mesma abordagem se aplica a qualquer endpoint de HTTP-reachable agente que você registra como destino do AgentCore gateway — e depois o envia de volta à página para criar e executar o teste.
## Pré-requisitos
Além dos [pré-requisitos gerais A/B de teste](ab-testing-prereqs.md), você precisa:
1. AgentCore rastreamento de gateway ativado no gateway para que as sessões possam ser atribuídas a uma variante.
1. Seu agente foi adicionado como destino de passagem em um AgentCore gateway usando um protocolo compatível.
## Etapa 1: instrumentar seu agente para fins de AgentCore observabilidade
**nota**
Siga [Habilitando a observabilidade para agentes hospedados fora do AgentCore](observability-configure.md#observability-configure-3p) para ver a configuração completa.
Para um Lambda-hosted agente, anexe a [camada AWS Lambda OpenTelemetry](https://aws-otel.github.io/docs/getting-started/lambda#adot-lambda-layer-arns) e defina as seguintes variáveis de ambiente:
```
aws lambda update-function-configuration \
--function-name \
--region \
--layers \
--environment "Variables={
AGENT_OBSERVABILITY_ENABLED=true,
OTEL_PROPAGATORS='baggage,xray-lambda,tracecontext',
OTEL_PYTHON_DISTRO=aws_distro,
OTEL_PYTHON_CONFIGURATOR=aws_configurator,
OTEL_LOGS_EXPORTER=otlp,
OTEL_TRACES_EXPORTER=otlp,
OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf,
OTEL_PYTHON_LOGGING_AUTO_INSTRUMENTATION_ENABLED=true,
OTEL_AWS_APPLICATION_SIGNALS_ENABLED=false,
OTEL_EXPORTER_OTLP_LOGS_HEADERS='x-aws-log-group=/aws/bedrock-agentcore/agents//runtime-logs,x-aws-log-stream=runtime-logs,x-aws-metric-namespace=agentcore',
OTEL_RESOURCE_ATTRIBUTES='service.name=',
AWS_LAMBDA_EXEC_WRAPPER=/opt/otel-instrument
}"
```
Um manipulador Lambda mínimo que analisa a solicitação de URL da função e define a bagagem da sessão:
```
import base64, json
from strands import Agent
from strands.models.bedrock import BedrockModel
from opentelemetry import baggage, context
_model = BedrockModel(model_id="global.anthropic.claude-sonnet-4-5-20250929-v1:0")
def lambda_handler(event, _context):
# Lambda function URL payload format 2.0: JSON body is in event["body"], no httpMethod.
raw = event.get("body")
if raw is not None and event.get("isBase64Encoded"):
raw = base64.b64decode(raw).decode()
body = json.loads(raw) if isinstance(raw, str) else (raw or event)
session_id = _session_id(event)
token = context.attach(baggage.set_baggage("session.id", session_id))
try:
agent = Agent(model=_model, system_prompt="You are a helpful assistant. Be concise.")
result = agent(body.get("prompt", "Hello"))
finally:
context.detach(token)
return {"response": str(result), "sessionId": session_id}
def _session_id(event):
return (event.get("headers") or {}).get("x-session-id") or "default"
```
Para roteamento baseado em metas, implante isso duas vezes (controle e tratamento) com a alteração que você está testando — por exemplo, um prompt diferente `model_id` ou do sistema.
## Etapa 2: exponha seu agente via HTTP
O agente deve estar acessível em um endpoint HTTP que o AgentCore gateway possa chamar. Para o exemplo do Lambda, crie uma URL de função com autenticação IAM para cada função:
```
aws lambda create-function-url-config \
--function-name cs-agent-control \
--auth-type AWS_IAM \
--region us-west-2
```
Repita o procedimento para a função de tratamento. (Para um contêiner ou agente auto-hospedado, exponha um endpoint HTTPS em vez disso e vá para a Etapa 3.)
## Etapa 3: registrar seu agente como um destino de AgentCore gateway
Registre cada endpoint como um destino de **passagem** HTTP em um AgentCore gateway. Para obter detalhes sobre os destinos de passagem`protocolType`, incluindo as opções de fidelidade e credencial, consulte Destinos de passagem [HTTP](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/gateway-target-http-passthrough.html).
Para registrar uma URL da função Lambda como destino, `protocolType` defina `CUSTOM` e forneça uma. `iamCredentialProvider` O provedor de credenciais autoriza o gateway a assinar cada solicitação de saída no URL da função como serviço: `lambda`
**nota**
Isso `stickinessConfiguration` diz ao gateway que use o `x-session-id` cabeçalho para reconhecer quais solicitações pertencem à mesma sessão. A aderência da sessão mantém as sessões em andamento inalteradas quando você inicia ou interrompe um A/B teste: o gateway continua direcionando as sessões em andamento para o mesmo alvo ao qual elas já foram atribuídas e encaminha somente novas sessões de acordo com os pesos do tratamento do A/B teste enquanto o teste está sendo executado.
Para fins de observação, seu agente também deve definir esse mesmo ID de sessão em seu contexto de rastreamento (por exemplo, como `session.id` bagagem). Isso permite que a avaliação on-line pontue sessões e rastreamentos do agente e os atribua ao tratamento A/B de teste correto.
**Example**
```
agentcore add gateway-target \
--name customer-support-control \
--gateway cs-3p-abtest-gw \
--type passthrough \
--passthrough-endpoint https://.lambda-url.us-west-2.on.aws/ \
--passthrough-protocol CUSTOM \
--stickiness-identifier '$context.header.x-session-id' \
--stickiness-timeout 28800 \
--signing-service lambda \
--signing-region us-west-2
```
```
aws bedrock-agentcore-control create-gateway-target \
--gateway-identifier cs-3p-abtest-gw-abc123 \
--name customer-support-control \
--region us-west-2 \
--target-configuration '{
"http": {
"passthrough": {
"endpoint": "https://.lambda-url.us-west-2.on.aws/",
"protocolType": "CUSTOM",
"stickinessConfiguration": {
"identifier": "$context.header.x-session-id",
"timeout": 28800
}
}
}
}' \
--credential-provider-configurations '[
{
"credentialProviderType": "GATEWAY_IAM_ROLE",
"credentialProvider": {
"iamCredentialProvider": { "service": "lambda", "region": "us-west-2" }
}
}
]'
```
Para roteamento baseado em metas, repita para o ponto final do tratamento (nomeie-o). `customer-support-treatment` Pesquise cada alvo com `get-gateway-target` até que `status` seja`READY`.
**nota**
`iamCredentialProvider`é necessário para um alvo de IAM-authenticated passagem. Para um URL da função Lambda definido como`service`. `lambda` A função do IAM do gateway deve ter ambos `lambda:InvokeFunctionUrl` e `lambda:InvokeFunction` no ARN de cada função.
## Etapa 4: Ativar o rastreamento do AgentCore gateway
Ative o rastreamento da entrega no AgentCore gateway para que ele emita extensões de atribuição de variantes para. `aws/spans` ****Para ativar o rastreamento a partir do console, abra a página de detalhes do gateway e escolha **Registrar entregas e rastreamento → Rastreamento** → Ativar.**** Para obter mais informações, consulte [Configurar a entrega de rastreamento para CloudWatch](observability-configure.md#observability-configure-tracing).
Quando o tráfego começa a fluir, cada extensão do gateway carrega os atributos `aws.agentcore.gateway.routing_experiment_arn` e `aws.agentcore.gateway.routing_experiment_variant_name` (por exemplo, `C` ou`T1`), junto com o `traceId` da solicitação. O pipeline de avaliação on-line une a extensão do gateway aos períodos do seu agente`traceId`, e é assim que cada sessão pontuada é atribuída à sua variante. Sem o rastreamento do gateway, as sessões ainda são pontuadas, mas não podem ser atribuídas a uma variante, e o A/B teste não produz resultados por variante.
## Etapa 5: criar e executar o A/B teste
Seu agente agora é um alvo de gateway que emite telemetria. Restam duas etapas:
1. **Crie uma configuração de avaliação on-line por endpoint de variante.** Consulte [Criar avaliação on-line](create-online-evaluations.md). Para cada configuração, use o grupo de log `service.name` de eventos em [Etapa 1: instrumentar seu agente para fins de AgentCore observabilidade](#ab-testing-3p-step1-observability) que você configurou.
1. **Crie e execute o A/B teste.** Siga [Execute um A/B teste com roteamento baseado em metas](ab-testing-target-based.md), começando pela etapa **Criar o A/B teste** — crie o teste com`perVariantOnlineEvaluationConfig`, envie tráfego, resultados de enquetes, pare e implante o vencedor.
Ao enviar tráfego pelo gateway, direcione-o para o destino da variante de controle. O gateway divide todo o tráfego que chega ao alvo de controle entre os alvos de controle (`C`) e tratamento (`T1`) de acordo com sua configuração de A/B teste.
**Example**
Adicione uma configuração de avaliação on-line por variante, usando o grupo de registros de eventos `service.name` e [Etapa 1: instrumentar seu agente para fins de AgentCore observabilidade](#ab-testing-3p-step1-observability) como fonte de dados, e inicie o teste no `target-based` modo:
```
agentcore add online-eval \
--name cs-control-eval \
--evaluator Builtin.Correctness \
--service-name customer-support-control \
--log-group-name /aws/bedrock-agentcore/agents/cs-agent-control/runtime-logs \
--enable-on-create
agentcore add online-eval \
--name cs-treatment-eval \
--evaluator Builtin.Correctness \
--service-name customer-support-treatment \
--log-group-name /aws/bedrock-agentcore/agents/cs-agent-treatment/runtime-logs \
--enable-on-create
agentcore deploy
agentcore run ab-test \
--name cs-3p-abtest \
--gateway cs-3p-abtest-gw \
--mode target-based \
--control-target customer-support-control \
--treatment-target customer-support-treatment \
--control-online-eval cs-control-eval \
--treatment-online-eval cs-treatment-eval \
--control-weight 50 \
--treatment-weight 50 \
--wait
```
Use `agentcore status` para visualizar os resultados por variante enquanto o teste é executado e `agentcore stop` para finalizá-lo.
Crie uma configuração de avaliação on-line por variante com`create_online_evaluation_config`. `serviceNames`Defina para o endpoint `service.name` e `logGroupNames` para seu grupo de registros de eventos. Em seguida, crie o teste com`create_ab_test`, usando`perVariantOnlineEvaluationConfig`. **Para ver o exemplo completo do boto3, incluindo envio de tráfego, resultados de pesquisas e interrupção do teste, consulte [Executar um A/B teste com roteamento baseado em metas](ab-testing-target-based.md), a partir da etapa Criar o teste. A/B **
## Solução de problemas
### A/B o teste não mostra resultados após o envio do tráfego
+ Confirme se o rastreamento do gateway está ativado ([Etapa 4: Ativar o rastreamento do AgentCore gateway](#ab-testing-3p-step4-gateway-tracing)) — sem ele, o pipeline de agregação não pode atribuir sessões a variantes.
+ Confirme se cada configuração de avaliação on-line `serviceNames` corresponde à do endpoint `service.name` e `logGroupNames` inclui o grupo de log de eventos do endpoint. A avaliação on-line é lida `aws/spans` automaticamente, então você não a lista, mas o grupo do registro de eventos (conteúdo da mensagem) deve estar listado.
+ Os resultados aparecem depois que uma sessão fica ociosa para o configurado e`sessionTimeoutMinutes`, em seguida, dentro de aproximadamente 15 minutos do próximo ciclo de pontuação.