Definir resultados

El outcome eleva una sesión de conversación a trabajo. Defines cuál debe ser 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 sistema automáticamente provisiona un evaluador para evaluar el artefacto contra una rúbrica. Aprovecha una ventana de contexto separada para evitar ser influenciado por las opciones de implementación del agente principal.

El evaluador devuelve un desglose por criterio: ya sea confirmación de que el artefacto satisface la rúbrica, o las brechas específicas entre el trabajo actual y los requisitos. 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.

Ejemplo de rúbrica:

# Rúbrica del Modelo DCF

## Proyecciones de Ingresos
- Utiliza datos de ingresos históricos de los últimos 5 años fiscales
- Proyecta ingresos para al menos 5 años hacia adelante
- Los supuestos de tasa de crecimiento se establecen explícitamente y son razonables

## Estructura de Costos
- COGS y gastos operativos se modelan por separado
- Los márgenes son consistentes con tendencias históricas o las desviaciones están justificadas

## Tasa de Descuento
- WACC se calcula con supuestos establecidos para costo de capital y costo de deuda
- Beta, tasa libre de riesgo y prima de riesgo de capital se obtienen o justifican

## Valor Terminal
- Utiliza método de perpetuidad o múltiplo de salida (especifica cuál)
- La tasa de crecimiento terminal no excede el crecimiento del PIB a largo plazo

## Calidad de Salida
- Todas las cifras están en un único archivo .xlsx con hojas claramente etiquetadas
- Los supuestos clave están en una hoja "Assumptions" separada
- Se incluye análisis de sensibilidad en WACC y tasa de crecimiento terminal

Pasa la rúbrica como texto en línea en user.define_outcome (mostrado en la siguiente sección), o cárgala a través de la API de Archivos para reutilizarla en sesiones:

Requiere encabezado beta files-api-2025-04-14.

from pathlib import Path

rubric = client.beta.files.upload(file=Path("/path/to/pr_review_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 inmediatamente; no se requiere un evento de mensaje de usuario adicional.

# Create a session
session = client.beta.sessions.create(
    agent=agent.id,
    environment_id=environment.id,
    title="Financial analysis on Costco",
)

# Define the outcome — agent starts working on receipt
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},
            # or: "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.* (mensajes, uso de herramientas, etc.) 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.message events a una sesión orientada a resultados, para dirigir el trabajo del agente mientras progresa, pero no son tan necesarios; el agente sabe que debe trabajar hasta que agote sus iteraciones o logre el resultado.
• Un evento user.interrupt pausará el trabajo en el resultado actual y marcará span.outcome_evaluation_end.result como interrupted, permitiéndote iniciar un nuevo resultado.
• Después de la evaluación final del resultado, la sesión puede continuarse como una sesión conversacional, o se puede iniciar un nuevo resultado. La sesión retendrá el historial del resultado anterior.

Evento de usuario de definir resultado

Este es el evento que envías para iniciar un resultado. Se devuelve en la recepción, incluida una marca de tiempo processed_at e 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 revisión 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

Latido emitido mientras se ejecuta el evaluador. El razonamiento interno del evaluador es opaco: ves que está funcionando, no en qué 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 flujo de eventos para 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 archivos de salida en /mnt/session/outputs/ dentro del contenedor. Una vez que la sesión está inactiva, obtén los archivos a través de la API de Archivos limitada a la sesión:

files = client.beta.files.list(scope_id=session.id)
for f in files.data:
    print(f"{f.id}: {f.filename} ({f.size_bytes} bytes)")

content = client.beta.files.download(files.data[0].id)
content.write_to_file("costco_dcf.xlsx")