Definire i risultati

L'outcome eleva una sessione da conversazione a lavoro. Definisci come dovrebbe essere il risultato finale e come misurare la qualità. L'agente lavora verso quel target, auto-valutandosi e iterando finché l'outcome non viene raggiunto.

Quando definisci un outcome, il sistema provisiona automaticamente un grader per valutare l'artefatto rispetto a una rubrica. Utilizza una finestra di contesto separata per evitare di essere influenzato dalle scelte di implementazione dell'agente principale.

Il grader restituisce una suddivisione per criterio: sia la conferma che l'artefatto soddisfa la rubrica, sia i gap specifici tra il lavoro attuale e i requisiti. Questo feedback viene restituito all'agente per l'iterazione successiva.

Creare una rubrica

Una rubrica è un documento markdown che descrive il punteggio per criterio. La rubrica è obbligatoria.

Rubrica di esempio:

# Rubrica del Modello DCF

## Proiezioni dei Ricavi
- Utilizza i dati storici dei ricavi degli ultimi 5 anni fiscali
- Proietta i ricavi per almeno 5 anni in avanti
- Le ipotesi del tasso di crescita sono esplicitamente indicate e ragionevoli

## Struttura dei Costi
- COGS e le spese operative sono modellate separatamente
- I margini sono coerenti con i trend storici o le deviazioni sono giustificate

## Tasso di Sconto
- WACC è calcolato con ipotesi dichiarate per il costo del capitale proprio e il costo del debito
- Beta, tasso privo di rischio e premio per il rischio azionario sono forniti o giustificati

## Valore Terminale
- Utilizza il metodo della crescita perpetua o il metodo del multiplo di uscita (indicare quale)
- Il tasso di crescita terminale non supera la crescita del PIL a lungo termine

## Qualità dell'Output
- Tutte le cifre sono in un singolo file .xlsx con fogli chiaramente etichettati
- Le ipotesi chiave sono su un foglio "Assumptions" separato
- L'analisi di sensibilità su WACC e tasso di crescita terminale è inclusa

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

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

Creare una sessione con un outcome

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 di outcome

Il progresso su una sessione orientata agli outcome viene visualizzato sul flusso degli eventi.

• Gli eventi agent.* (messaggi, utilizzo di strumenti, ecc.) mostrano il progresso verso l'outcome.
• Gli eventi span.outcome_evaluation_* vengono emessi solo per le sessioni orientate agli outcome e mostrano il numero di cicli di iterazione e il processo di feedback del grader.
• Puoi anche inviare eventi user.message events a una sessione orientata agli outcome, per dirigere il lavoro dell'agente mentre progredisce, ma non sono così necessari; l'agente sa di lavorare finché non ha esaurito le sue iterazioni o raggiunto l'outcome.
• Un evento user.interrupt metterà in pausa il lavoro sull'outcome attuale e contrassegnerà span.outcome_evaluation_end.result come interrupted, permettendoti di avviare un nuovo outcome.
• Dopo la valutazione finale dell'outcome, la sessione può essere continuata come sessione conversazionale, oppure può essere avviato un nuovo outcome. La sessione manterrà la cronologia dell'outcome precedente.

Definire l'evento utente outcome

Questo è l'evento che invii per avviare un outcome. Viene echeggiato al ricevimento, incluso un timestamp 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
}

Inizio della valutazione dell'outcome

Emesso una volta che il grader avvia una valutazione su un ciclo di iterazione. Il campo iteration è un contatore di revisione a indice zero: 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 dell'outcome in corso

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

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

Fine della valutazione dell'outcome

Emesso dopo che il grader finisce di valutare 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"
}

Verificare lo stato dell'outcome

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

Recuperare i deliverable

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