Definire i risultati

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

Quando definisci un outcome, l'harness predispone automaticamente un grader (valutatore) per valutare l'artefatto rispetto a una rubrica. Il grader utilizza una "context window" (finestra di contesto) separata per evitare di essere influenzato dalle scelte implementative dell'agente principale.

Il grader restituisce una spiegazione che riassume quali criteri sono stati soddisfatti o meno, oppure conferma che l'artefatto soddisfa la rubrica. Tale feedback viene restituito all'agente per l'iterazione successiva.



Creare una rubrica

Una rubrica è un documento markdown che descrive il punteggio per ciascun 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 (vedi la sezione successiva), oppure caricala tramite la Files API per riutilizzarla in più sessioni.

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



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.

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

# Definisci il risultato — l'agente inizia a lavorare alla ricezione
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},
            # oppure: "rubric": {"type": "file", "file_id": rubric.id},
            "max_iterations": 5,  # optional; default 3, max 20
        }
    ],
)



Eventi dell'outcome

I progressi su una sessione orientata all'outcome vengono mostrati nello stream degli eventi.

• Gli eventi agent.* (come messaggi e uso degli strumenti) mostrano i progressi verso l'outcome.
• Gli eventi span.outcome_evaluation_* vengono emessi solo per le sessioni orientate all'outcome 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 all'outcome per indirizzare il lavoro dell'agente mentre procede, ma non è obbligatorio: l'agente lavora verso l'outcome autonomamente, iterando finché non ha successo o esaurisce le iterazioni.
• Un evento user.interrupt mette in pausa il lavoro sull'outcome corrente e contrassegna span.outcome_evaluation_end.result come interrupted, permettendoti di avviare un nuovo outcome.
• Dopo la valutazione finale dell'outcome, la sessione può continuare come sessione conversazionale, oppure può essere avviato un nuovo outcome. La sessione conserva la cronologia dell'outcome precedente.



Evento utente di definizione dell'outcome

Questo è l'evento che invii per avviare un outcome. Viene restituito in eco alla ricezione, includendo 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 della valutazione dell'outcome

Emesso quando il grader avvia una valutazione su un ciclo di iterazione. Il campo iteration è un contatore di revisione con indice a partire da 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 dell'outcome 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 della valutazione dell'outcome

Emesso dopo che il grader ha terminato 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 lo stream degli eventi per span.outcome_evaluation_end, oppure eseguire il polling di GET /v1/sessions/:id e leggere 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...: soddisfatto



Recuperare i deliverable

L'agente scrive i file di output in /mnt/session/outputs/ all'interno della sandbox. Una volta che la sessione è in stato idle, recuperali tramite la Files API con ambito limitato alla sessione:

# Elenca i file prodotti da questa sessione
files = client.beta.files.list(scope_id=session.id)
for f in files:
    print(f.id, f.filename)

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