Definire i risultati

L'outcome eleva una sessione da conversazione a lavoro. Definisci come dovrebbe apparire il risultato finale e come misurare la qualità. L'agente lavora verso quell'obiettivo, autovalutandosi e iterando finché il risultato non viene raggiunto.

Quando definisci un risultato, il sistema provvede automaticamente a un grader per valutare l'artefatto rispetto a una rubrica. Sfrutta una finestra di contesto separata per evitare di essere influenzato dalle scelte implementative dell'agente principale.

Il grader restituisce una suddivisione per criterio: o la conferma che l'artefatto soddisfa la rubrica, oppure le lacune specifiche tra il lavoro attuale e i requisiti. Quel feedback viene restituito all'agente per l'iterazione successiva.

Creare una rubrica

Una rubrica è un documento markdown che descrive la valutazione per criterio. La rubrica è obbligatoria.

Esempio di rubrica:

# 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

Passa la rubrica come testo inline su user.define_outcome (mostrato nella sezione successiva), oppure caricala tramite la Files API per il riutilizzo tra sessioni:

Richiede l'intestazione beta files-api-2025-04-14.

Creare una sessione con un risultato

Dopo aver creato una sessione, invia un evento user.define_outcome. L'agente inizia a lavorare immediatamente; non è richiesto alcun evento di messaggio utente aggiuntivo.

Eventi del risultato

Il progresso su una sessione orientata ai risultati viene mostrato nello stream degli eventi.

• Gli eventi agent.* (messaggi, uso degli strumenti, ecc.) mostrano il progresso verso il risultato.
• Gli eventi span.outcome_evaluation_* vengono emessi solo per sessioni orientate ai risultati e mostrano il numero di cicli di iterazione e il processo di feedback del grader.
• Puoi anche inviare eventi user.message a una sessione orientata ai risultati, per guidare il lavoro dell'agente mentre procede, ma questi non sono così necessari; l'agente sa di dover lavorare finché non ha esaurito le iterazioni o raggiunto il risultato.
• Un evento user.interrupt metterà in pausa il lavoro sul risultato corrente e contrassegnerà span.outcome_evaluation_end.result come interrupted, consentendoti di avviare un nuovo risultato.
• Dopo la valutazione finale del risultato, la sessione può essere continuata come sessione conversazionale, oppure può essere avviato un nuovo risultato. La sessione conserverà la cronologia del risultato precedente.

Evento utente define outcome

Questo è l'evento che invii per avviare un risultato. Viene restituito alla ricezione, incluso un timestamp processed_at e 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
}

Inizio valutazione del risultato

Emesso una volta che il grader avvia una valutazione su un ciclo di iterazione. Il campo iteration è un contatore di revisioni con indice 0: 0 è la prima valutazione, 1 è la rivalutazione dopo la prima revisione, e così via.

{
  "type": "span.outcome_evaluation_start",
  "id": "sevt_01def...",
  "outcome_id": "outc_01a...",
  "iteration": 0,
  "processed_at": "2026-03-25T14:01:45Z"
}

Valutazione del risultato in corso

Heartbeat emesso mentre il grader è in esecuzione. Il ragionamento interno del grader è opaco: vedi che sta lavorando, non cosa sta pensando.

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

Fine valutazione del risultato

Emesso dopo che il grader ha terminato la valutazione di un'iterazione. Il campo result indica cosa succede dopo.

{
  "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"
}

Verifica dello stato del risultato

Puoi ascoltare lo stream degli eventi per span.outcome_evaluation_end, oppure eseguire il polling di GET /v1/sessions/:id e leggere outcome_evaluations[].result:

Recupero dei deliverable

L'agente scrive i file di output in /mnt/session/outputs/ all'interno del container. Una volta che la sessione è inattiva, recuperali tramite la Files API con scope alla sessione: