Definir resultados

El outcome eleva una sesión de conversación a trabajo. Tú defines cómo debe verse el resultado final y cómo medir la 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 grader (evaluador) para evaluar el artefacto según una rúbrica. El evaluador usa una "context window" (ventana de contexto) separada para evitar verse influenciado por las decisiones de implementación del agente principal.

El evaluador devuelve una explicación que resume qué criterios se cumplieron o no, 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 en markdown que describe la puntuación por criterio. La rúbrica es obligatoria.

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 included

Pasa la rúbrica como texto en línea en user.define_outcome (consulta la siguiente sección), o súbela a través de la Files API para reutilizarla en varias sesiones.

rubric = client.beta.files.upload(file=Path("/tmp/rubric.md"))
print(f"Uploaded rubric: {rubric.id}")



Crear una sesión con un resultado

Después de crear una sesión, envía un evento user.define_outcome. El agente comienza a trabajar de inmediato; no se requiere ningún evento adicional de mensaje de usuario.

# 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 stream 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 ciclos de iteración y el proceso de retroalimentación del evaluador.
• También puedes enviar eventos user.message a 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 su cuenta, iterando hasta que tiene éxito o se queda sin iteraciones.
• Un evento user.interrupt pausa el trabajo en el resultado actual y marca span.outcome_evaluation_end.result como interrupted, 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 inicia una evaluación sobre un ciclo de iteración. El campo iteration es un contador de revisiones con índice base 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 emitido mientras el evaluador se ejecuta. El razonamiento interno del evaluador es opaco: ves que está trabajando, no lo que está pensando.

{
  "type": "span.outcome_evaluation_ongoing",
  "id": "sevt_01ghi...",
  "outcome_id": "outc_01a...",
  "processed_at": "2026-03-25T14:02:10Z"
}



Fin de evaluación de resultado

Se emite después de que el evaluador termina de evaluar una iteración. El campo result indica qué sucede a continuación.

{
  "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 el evento span.outcome_evaluation_end, o hacer polling a GET /v1/sessions/:id y leer outcome_evaluations[].result:

session = client.beta.sessions.retrieve(session.id)

for outcome in session.outcome_evaluations:
    print(f"{outcome.outcome_id}: {outcome.result}")
    # outc_01a...: satisfied



Recuperar entregables

El agente escribe los archivos de salida en /mnt/session/outputs/ dentro del sandbox. Una vez que la sesión está en estado idle, recupéralos a través de la Files API con alcance a la sesión:

# Lista los archivos producidos por esta sesión
files = client.beta.files.list(scope_id=session.id)
for f in files:
    print(f.id, f.filename)

# Descarga un archivo
if files.data:
    content = client.beta.files.download(files.data[0].id)
    content.write_to_file("/tmp/output.txt")