Definir resultados
Indícale al agente cómo se ve ‘terminado’ y déjalo iterar hasta lograrlo.
Un resultado le indica a la sesión cómo debe verse el resultado final y cómo medir su calidad. El agente trabaja hacia ese objetivo, autoevaluándose e iterando hasta que se cumple el resultado.
Cuando defines un resultado, el harness aprovisiona automáticamente un evaluador (grader) para evaluar el artefacto contra una rúbrica. El evaluador usa una ventana de contexto separada para evitar ser influenciado por las decisiones de implementación del agente principal.
El evaluador devuelve una explicación que resume qué criterios se aprobaron o fallaron, o confirma que el artefacto satisface la rúbrica. Esa retroalimentación se devuelve al agente para la siguiente iteración.
Crear una rúbrica
Una rúbrica es un documento markdown que describe la puntuación por criterio. La rúbrica es obligatoria.
Estructura la rúbrica como criterios explícitos y evaluables, como “El CSV contiene una columna de precio con valores numéricos” en lugar de “Los datos se ven bien.” El evaluador puntúa cada criterio de forma independiente, por lo que los criterios vagos producen evaluaciones ruidosas.
Si no tienes una rúbrica, intenta darle a Claude un ejemplo de un artefacto que sepas que es bueno y pídele que analice qué hace bueno ese contenido; luego convierte ese análisis en una rúbrica. Este enfoque intermedio a menudo produce mejores resultados que escribir criterios sin ningún ejemplo del cual partir.
Ejemplo de rúbrica:
# DCF Model Rubric
## Revenue Projections
- Uses historical revenue data from the last 5 fiscal years
- Projects revenue for at least 5 years forward
- Growth rate assumptions are explicitly stated and reasonable
## Cost Structure
- COGS and operating expenses are modeled separately
- Margins are consistent with historical trends or deviations are justified
## Discount Rate
- WACC is calculated with stated assumptions for cost of equity and cost of debt
- Beta, risk-free rate, and equity risk premium are sourced or justified
## Terminal Value
- Uses either perpetuity growth or exit multiple method (stated which)
- Terminal growth rate does not exceed long-term GDP growth
## Output Quality
- All figures are in a single .xlsx file with clearly labeled sheets
- Key assumptions are on a separate "Assumptions" sheet
- Sensitivity analysis on WACC and terminal growth rate is includedPasa la rúbrica como texto en línea en user.define_outcome (consulta Crear una sesión con un resultado), o súbela a través de la Files API para reutilizarla en varias sesiones.
import time
from pathlib import Path
from anthropic import Anthropic
client = Anthropic()
RUBRIC = """# DCF Model Rubric
## Revenue Projections
- Uses historical revenue data from the last 5 fiscal years
- Projects revenue for at least 5 years forward
## Output Quality
- All figures are in a single .xlsx file with clearly labeled sheets
"""
Path("/tmp/rubric.md").write_text(RUBRIC)
rubric = client.files.upload(file=Path("/tmp/rubric.md"))
print(f"Uploaded rubric: {rubric.id}")Crear una sesión con un resultado
Los siguientes ejemplos crean una sesión para un agente y un entorno existentes (ambos creados por separado), y luego envían un evento user.define_outcome. El agente comienza a trabajar de inmediato. No se requiere ningún evento de mensaje de usuario adicional.
# Crea una sesión
session = client.beta.sessions.create(
agent=agent.id,
environment_id=environment.id,
title="Financial analysis on Costco",
)
# Define el resultado. El agente empieza a trabajar al recibirlo.
client.beta.sessions.events.send(
session_id=session.id,
events=[
{
"type": "user.define_outcome",
"description": "Build a DCF model for Costco in .xlsx",
"rubric": {"type": "text", "content": RUBRIC},
# o: "rubric": {"type": "file", "file_id": rubric.id},
"max_iterations": 5, # optional; default 3, max 20
}
],
)Eventos de resultado
El progreso en una sesión orientada a resultados se muestra en el flujo de eventos.
- Los eventos
agent.*(como mensajes y uso de herramientas) muestran el progreso hacia el resultado. - Los eventos
span.outcome_evaluation_*solo se emiten para sesiones orientadas a resultados y muestran el número de bucles de iteración y el proceso de retroalimentación del evaluador. - También puedes enviar eventos
user.messagea una sesión orientada a resultados para dirigir el trabajo del agente a medida que avanza, pero no es obligatorio: el agente trabaja hacia el resultado por sí mismo, iterando hasta que tiene éxito o se queda sin iteraciones. - Un evento
user.interruptpausa el trabajo en el resultado actual y marca elresultdel eventospan.outcome_evaluation_endcomointerrupted, lo que te permite iniciar un nuevo resultado. - Después de la evaluación final del resultado, la sesión puede continuar como una sesión conversacional, o se puede iniciar un nuevo resultado. La sesión conserva el historial del resultado anterior.
Evento de usuario para definir resultado
Este es el evento que envías para iniciar un resultado. Se devuelve como eco al recibirse, incluyendo una marca de tiempo processed_at y un outcome_id.
{
"type": "user.define_outcome",
"description": "Build a DCF model for Costco in .xlsx",
"rubric": { "type": "file", "file_id": "file_01..." },
"max_iterations": 5
}Inicio de evaluación de resultado
Se emite una vez que el evaluador comienza una evaluación sobre un bucle de iteración. El campo iteration es un contador de revisiones indexado desde 0: 0 es la primera evaluación, 1 es la reevaluación después de la primera revisión, y así sucesivamente.
{
"type": "span.outcome_evaluation_start",
"id": "sevt_01def...",
"outcome_id": "outc_01a...",
"iteration": 0,
"processed_at": "2026-03-25T14:01:45Z"
}Evaluación de resultado en curso
“Heartbeat” (señal de actividad) que se emite mientras el evaluador se ejecuta. El razonamiento interno del evaluador es opaco: el evento solo muestra que el evaluador está trabajando.
{
"type": "span.outcome_evaluation_ongoing",
"id": "sevt_01ghi...",
"outcome_id": "outc_01a...",
"iteration": 0,
"processed_at": "2026-03-25T14:02:10Z"
}Fin de evaluación de resultado
Se emite cuando termina un ciclo de evaluación del resultado: después de que el evaluador termina de evaluar una iteración, o cuando la sesión se interrumpe mientras hay un resultado activo. El campo result indica lo que ocurre a continuación.
| Resultado | Siguiente |
|---|---|
satisfied | La sesión pasa a idle. |
needs_revision | El agente inicia un nuevo ciclo de iteración. |
max_iterations_reached | Sigue un turno final de reconocimiento antes de que la sesión pase a idle. No se ejecutan más evaluaciones. |
failed | La sesión pasa a idle. Se devuelve cuando la rúbrica no se aplica a los entregables, por ejemplo si la descripción y la rúbrica se contradicen entre sí. |
interrupted | Se emite cuando la sesión se interrumpe mientras un resultado está activo, incluso si la evaluación aún no había comenzado. Si no se disparó ningún outcome_evaluation_start antes de la interrupción, outcome_evaluation_start_id es una cadena vacía. |
{
"type": "span.outcome_evaluation_end",
"id": "sevt_01jkl...",
"outcome_evaluation_start_id": "sevt_01def...",
"outcome_id": "outc_01a...",
"result": "satisfied",
"explanation": "All 12 criteria met: revenue projections use 5 years of historical data, WACC assumptions are stated, sensitivity table is included...",
"iteration": 0,
"usage": {
"input_tokens": 2400,
"output_tokens": 350,
"cache_creation_input_tokens": 0,
"cache_read_input_tokens": 1800
},
"processed_at": "2026-03-25T14:03:00Z"
}Verificar el estado del resultado
Puedes escuchar en el stream de eventos para span.outcome_evaluation_end, o hacer polling a GET /v1/sessions/{session_id} y leer outcome_evaluations[].result. Hasta que se complete una evaluación, result reporta pending, running o evaluating:
session = client.beta.sessions.retrieve(session.id)
for outcome in session.outcome_evaluations:
print(f"{outcome.outcome_id}: {outcome.result}")
# outc_01a...: satisfiedRecuperar entregables
El agente escribe los archivos de salida en /mnt/session/outputs/ dentro del sandbox. Para recuperarlos, lista los archivos a través de la Files API con el ID de la sesión como scope_id, y luego descárgalos por ID. Filtrar por scope_id requiere el encabezado beta managed-agents-2026-04-01 en la solicitud de listado, por lo que los ejemplos de SDK y CLI hacen esa llamada a través del espacio de nombres beta y pasan el encabezado explícitamente. Los archivos aparecen en la lista poco después de que el agente termina de escribirlos, a veces unos segundos después de que la sesión pasa a inactiva. Si un archivo que esperas aún no aparece en la lista, vuelve a listar después de un breve intervalo; una vez que aparece en la lista, su carga está completa.
# Lista los archivos producidos por esta sesión
# El filtrado por scope_id requiere la beta managed-agents en la solicitud de archivos
files = client.beta.files.list(scope_id=session.id, betas=["managed-agents-2026-04-01"])
for file in files:
print(file.id, file.filename)
# Descarga un archivo
if files.data:
content = client.files.download(files.data[0].id)
content.write_to_file("/tmp/output.txt")Próximos pasos
Registra credenciales por usuario al crear sesiones.
Envía eventos, transmite respuestas en streaming e interrumpe o redirige tu sesión mientras se ejecuta.
Sube archivos y móntalos en tu sandbox para leerlos y procesarlos.
Disponibilidad
Claude API
- Estado
- Beta
- API
- Managed Agents
- Encabezado beta
- Requiere
- Modelos
- Todos los modelos
Claude Platform on AWS
- Estado
- Beta
- API
- Managed Agents
- Encabezado beta
- Requiere
- Modelos
- Todos los modelos
Claude Models on Google Cloud (Anthropic managed)
- Estado
- Beta
- API
- Managed Agents
- Encabezado beta
- Requiere
- Modelos
- Todos los modelos
Manejo de datos
Descripción general del manejo de datosEndpoints aplicables
/v1/agents/v1/sessions/v1/environments
No es elegible para ZDR, excepto Managed Agents autoalojado. Las sesiones son recursos con estado; las transcripciones persisten hasta que las eliminas. Más información
No es elegible para HIPAA. Se aplica a todas las subfunciones de Managed Agents.
¿Te resultó útil esta página?