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á.
# Começando com a avaliação em lote
Este passo a passo leva você de um agente implantado aos resultados da avaliação em lote usando um agente de suporte ao cliente da Acme Store. Você criará o agente, o implantará, gerará sessões de amostra, executará uma avaliação em lote e lerá os resultados.
**Topics**
+ [Antes de começar](#batch-gs-before-you-begin)
+ [Etapa 1: criar e implantar o agente de amostra](#batch-gs-step1)
+ [Etapa 2: gerar sessões de amostra](#batch-gs-step2)
+ [Etapa 3: Executar a avaliação em lote](#batch-gs-step3)
+ [Etapa 4: Leia os detalhes por sessão](#batch-gs-step4)
+ [Próximas etapas](#batch-gs-next-steps)
## Antes de começar
Verifique se você:
+ A AgentCore CLI instalada () `agentcore --version`
+ AWS credenciais com permissões para `bedrock-agentcore` e `logs`
+ Pesquisa de transações ativada em CloudWatch
+ Python 3.10\+ (para exemplos de boto3)
Para obter detalhes completos, consulte [ Pré-requisitos](batch-evaluations-prereqs.md).
As constantes a seguir são usadas nos exemplos do boto3. Substitua-os por seus próprios valores depois de implantar o agente:
```
REGION = "us-west-2"
AGENT_ARN = "arn:aws:bedrock-agentcore:us-west-2:123456789012:runtime/AcmeSupport-abc123"
SERVICE_NAME = "AcmeSupport-abc123.DEFAULT"
LOG_GROUP = "/aws/bedrock-agentcore/runtimes/AcmeSupport-abc123-DEFAULT"
```
## Etapa 1: criar e implantar o agente de amostra
Crie um AgentCore projeto e substitua o código padrão do agente pelo agente de suporte ao cliente da Acme Store. Esse agente tem cinco ferramentas para lidar com pedidos, devoluções, remessas, descontos e escalações.
### Criar o projeto
```
agentcore create --name AcmeSupport --framework Strands --model-provider Bedrock --memory none
cd AcmeSupport
```
### Substitua o código do agente
Abra `app/AcmeSupport/main.py` e substitua seu conteúdo pelo seguinte:
```
"""Acme Store customer support agent."""
from strands import Agent, tool
from strands.models.bedrock import BedrockModel
from bedrock_agentcore.runtime import BedrockAgentCoreApp
app = BedrockAgentCoreApp()
MODEL_ID = "global.anthropic.claude-sonnet-4-6"
SYSTEM_PROMPT = (
"You are a helpful customer support assistant for Acme Store. "
"Help customers with their orders, returns, and shipping questions."
)
@tool
def lookup_order(order_id: str) -> str:
"""Look up an order by ID and return its status, item, and delivery details."""
orders = {
"ORD-1001": {
"status": "delivered",
"item": "Blue T-Shirt (L)",
"delivered": "2026-03-28",
"total": "$29.99",
},
"ORD-1002": {
"status": "in_transit",
"item": "Running Shoes (10)",
"shipped": "2026-03-30",
"est_delivery": "2026-04-05",
"total": "$89.99",
},
"ORD-1003": {
"status": "delayed",
"item": "Wireless Headphones",
"shipped": "2026-03-25",
"est_delivery": "2026-03-29",
"days_late": 5,
"total": "$59.99",
},
"ORD-1004": {
"status": "processing",
"item": "Yoga Mat",
"ordered": "2026-04-02",
"total": "$34.99",
},
"ORD-1005": {
"status": "delivered",
"item": "Coffee Maker",
"delivered": "2026-03-20",
"total": "$149.99",
},
}
return str(orders.get(order_id, {"error": f"Order {order_id} not found"}))
@tool
def initiate_return(order_id: str, reason: str) -> str:
"""Initiate a return for an order. Sends a return label to the customer."""
return (
f"Return initiated for {order_id}. Reason: {reason}. "
"Return label sent to customer email. Please ship within 14 days."
)
@tool
def check_shipping_status(order_id: str) -> str:
"""Check detailed shipping status including carrier location and delays."""
statuses = {
"ORD-1002": (
"Package is with carrier, currently in Portland OR. "
"On schedule for April 5."
),
"ORD-1003": (
"Package delayed at distribution center in Memphis TN. "
"Original delivery was March 29. Now 5 days late. "
"Acme Store policy: orders delayed 3+ days qualify for 15% discount."
),
}
return statuses.get(order_id, f"No active shipment found for {order_id}.")
@tool
def apply_discount(order_id: str, discount_percent: int, reason: str) -> str:
"""Apply a percentage discount to an order and issue a refund."""
return (
f"Applied {discount_percent}% discount to {order_id}. "
f"Reason: {reason}. Refund will appear in 3-5 business days."
)
@tool
def escalate_to_human(reason: str) -> str:
"""Escalate the conversation to a human support agent."""
return (
f"Escalated to human agent. Reason: {reason}. "
"Estimated wait time: 3 minutes."
)
agent = Agent(
model=BedrockModel(model_id=MODEL_ID),
tools=[lookup_order, initiate_return, check_shipping_status,
apply_discount, escalate_to_human],
system_prompt=SYSTEM_PROMPT,
)
@app.entrypoint
def invoke(payload, context):
result = agent(str(payload.get("prompt", "Hello")))
return {"response": str(result)}
if __name__ == "__main__":
app.run()
```
### Implemente e verifique
```
agentcore deploy
```
Após a implantação, verifique se o agente está em execução:
```
agentcore invoke --prompt "What's the status of order ORD-1001?"
```
Você deve ver uma resposta com os detalhes do pedido. Observe o ARN de tempo de execução, o nome do serviço e o grupo de registros de `agentcore status --json` — você precisará deles para os exemplos do boto3.
**nota**
Se você já tem um agente implantado no AgentCore Runtime com a observabilidade ativada, ignore esta etapa e use seu próprio agente no restante do passo a passo.
## Etapa 2: gerar sessões de amostra
Invoque o agente com solicitações variadas para criar sessões para avaliação. Essas solicitações abrangem diferentes cenários: consultas de pedidos, devoluções, atrasos no envio, solicitações de descontos e interações com várias ferramentas.
**Example**
```
agentcore invoke --runtime AcmeSupport --prompt "What's the status of my order ORD-1001?"
agentcore invoke --runtime AcmeSupport --prompt "I need to return order ORD-1001, the shirt doesn't fit."
agentcore invoke --runtime AcmeSupport --prompt "What's the shipping status on ORD-1002?"
agentcore invoke --runtime AcmeSupport --prompt "My order ORD-1003 is delayed, can you help?"
agentcore invoke --runtime AcmeSupport --prompt "I'd like to check on order ORD-1004 please."
agentcore invoke --runtime AcmeSupport --prompt "Can you look up order ORD-1005 for me?"
agentcore invoke --runtime AcmeSupport --prompt "I want to return the coffee maker from order ORD-1005, it's defective."
agentcore invoke --runtime AcmeSupport --prompt "Where is my order ORD-1002? It should have arrived by now."
agentcore invoke --runtime AcmeSupport --prompt "ORD-1003 is really late, I want a discount."
agentcore invoke --runtime AcmeSupport --prompt "Can you check order ORD-1001 and tell me when it was delivered?"
```
```
import boto3
import json
import uuid
client = boto3.client("bedrock-agentcore", region_name=REGION)
prompts = [
"What's the status of my order ORD-1001?",
"I need to return order ORD-1001, the shirt doesn't fit.",
"What's the shipping status on ORD-1002?",
"My order ORD-1003 is delayed, can you help?",
"I'd like to check on order ORD-1004 please.",
"Can you look up order ORD-1005 for me?",
"I want to return the coffee maker from order ORD-1005, it's defective.",
"Where is my order ORD-1002? It should have arrived by now.",
"ORD-1003 is really late, I want a discount.",
"Can you check order ORD-1001 and tell me when it was delivered?",
]
for i, prompt in enumerate(prompts):
session_id = f"acme-eval-{uuid.uuid4().hex[:12]}"
print(f"[{i+1}/10] {prompt[:60]}...")
response = client.invoke_agent_runtime(
agentRuntimeArn=AGENT_ARN,
runtimeSessionId=session_id,
payload=json.dumps({"prompt": prompt}).encode(),
)
response_body = response["response"].read()
print(f" Done (session: {session_id})")
print("\nAll sessions created.")
```
Aguarde de 2 a 3 minutos após a última invocação para ingerir a CloudWatch telemetria antes de continuar.
## Etapa 3: Executar a avaliação em lote
Inicie uma avaliação em lote para pontuar todas as sessões recentes. O serviço descobre sessões a partir do CloudWatch Logs, compara cada avaliador a cada sessão e retorna resultados agregados.
**Example**
```
agentcore run batch-evaluation \
--runtime AcmeSupport \
--evaluator Builtin.GoalSuccessRate Builtin.Helpfulness Builtin.Faithfulness \
--wait
```
Por padrão, `agentcore run batch-evaluation` inicia o trabalho e retorna imediatamente (sem bloqueio). Passe `--wait` para bloquear até que o trabalho atinja um estado terminal. Com`--wait`, a CLI resolve o grupo de CloudWatch logs e o nome do serviço da configuração do seu projeto, inicia o trabalho, bloqueia até atingir um estado terminal e, em seguida, imprime as pontuações médias por avaliador:
```
Batch evaluation completed: acme-eval-a1b2c3d4
Sessions: 10 completed, 0 failed, 10 total
Evaluator Avg Score
─────────────────────────────────────────────
Builtin.GoalSuccessRate 0.7200
Builtin.Helpfulness 0.8100
Builtin.Faithfulness 0.8500
Results saved to .cli/jobs/batch-eval-results/
```
Adicione `--json` para emitir resultados legíveis por máquina (incluindo `batchEvaluationId` e por avaliador`averageScore`) para criação de scripts e para rotular a execução para que você possa comparar `-n ` os resultados entre as execuções. Por exemplo:
```
agentcore run batch-evaluation \
--runtime AcmeSupport \
--evaluator Builtin.GoalSuccessRate Builtin.Helpfulness Builtin.Faithfulness \
-n acme_baseline \
--wait
```
```
import boto3
import uuid
import time
import json
eval_client = boto3.client("bedrock-agentcore", region_name=REGION)
# Start the batch evaluation
response = eval_client.start_batch_evaluation(
batchEvaluationName=f"acme_baseline_{uuid.uuid4().hex[:8]}",
evaluators=[
{"evaluatorId": "Builtin.GoalSuccessRate"},
{"evaluatorId": "Builtin.Helpfulness"},
{"evaluatorId": "Builtin.Faithfulness"},
],
dataSourceConfig={
"cloudWatchLogs": {
"serviceNames": [SERVICE_NAME],
"logGroupNames": [LOG_GROUP],
}
},
clientToken=str(uuid.uuid4()),
)
batch_eval_id = response["batchEvaluationId"]
print(f"Started: {batch_eval_id}")
# Poll until complete
while True:
result = eval_client.get_batch_evaluation(batchEvaluationId=batch_eval_id)
status = result["status"]
print(f"Status: {status}")
if status in ("COMPLETED", "COMPLETED_WITH_ERRORS", "FAILED", "STOPPED"):
break
time.sleep(30)
print(json.dumps(result, indent=4, default=str))
```
## Etapa 4: Leia os detalhes por sessão
As pontuações agregadas mostram o panorama geral. Para ver as pontuações por turno e por avaliador em sessões individuais, use os comandos de visualização da CLI integrados ou leia os eventos de avaliação diretamente do Logs. CloudWatch
**Example**
A CLI fornece comandos de primeira classe para visualizar trabalhos de avaliação em lote concluídos e seus resultados. Visualize um trabalho específico pelo ID do trabalho de avaliação em lote ou liste os trabalhos anteriores:
```
# View a batch evaluation job and its results
agentcore view batch-evaluation acme-eval-a1b2c3d4
# List batch evaluation jobs
agentcore batch-evaluations history
```
Esses comandos são executados interativamente quando nenhum sinalizador é fornecido. Adicione `--json` para obter uma saída não interativa e legível por máquina, por exemplo. `agentcore view batch-evaluation acme-eval-a1b2c3d4 --json`
```
# Get the output location from the batch evaluation result
output = result["outputConfig"]["cloudWatchConfig"]
log_group = output["logGroupName"]
log_stream = output["logStreamName"]
# Read the events
logs_client = boto3.client("logs", region_name=REGION)
response = logs_client.get_log_events(
logGroupName=log_group,
logStreamName=log_stream,
)
for event in response["events"]:
event_attrs = json.loads(event["message"]).get("attributes", {})
print(f"Score: {event_attrs.get('gen_ai.evaluation.score.value')}")
print(f"Label: {event_attrs.get('gen_ai.evaluation.score.label')}")
print(f"Explanation: {event_attrs.get('gen_ai.evaluation.explanation', '')[:200]}")
print()
```
## Próximas etapas
+ **Filtrar sessões ** — Avalie sessões específicas por ID ou intervalo de tempo. Consulte [ Iniciar uma avaliação em lote](batch-evaluations-start.md).
+ **Execute com base em um conjunto de dados ** — Invoque seu agente em cenários predefinidos e avalie os resultados automaticamente. Consulte Avaliação [Avaliação do conjunto de dados](dataset-evaluations.md) do conjunto de dados.
+ **Compare execuções ** — Execute uma avaliação em lote antes e depois de uma alteração e compare as pontuações. Consulte [ Entendendo os resultados e a saída](batch-evaluations-results.md).