Definire gli esiti

Un esito indica alla sessione come dovrebbe apparire il risultato finale e come misurarne la qualità. L'agente lavora verso quell'obiettivo, autovalutandosi e iterando finché l'esito non viene raggiunto.

Quando definisci un esito, l'harness fornisce automaticamente un grader per valutare l'artefatto rispetto a una rubrica. Il grader utilizza una finestra di contesto separata per evitare di essere influenzato dalle scelte di implementazione dell'agente principale.

Il grader restituisce una spiegazione che riassume quali criteri sono stati superati o falliti, oppure conferma che l'artefatto soddisfa la rubrica. Quel 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 Creare una sessione con un esito), oppure caricala tramite la Files API per riutilizzarla tra le sessioni.

import time
from pathlib import Path

from anthropic import Anthropic

client = Anthropic()

RUBRIC = """# DCF Model Rubric

## Revenue Projections
- Uses historical revenue data from the last 5 fiscal years
- Projects revenue for at least 5 years forward

## Output Quality
- All figures are in a single .xlsx file with clearly labeled sheets
"""
Path("/tmp/rubric.md").write_text(RUBRIC)

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

Creare una sessione con un esito

I seguenti esempi creano una sessione per un agente e un ambiente esistenti (entrambi creati separatamente), poi inviano un evento user.define_outcome. L'agente inizia a lavorare immediatamente. Non è richiesto alcun evento di messaggio utente aggiuntivo.

# 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
        }
    ],
)

Eventi di esito

Il progresso su una sessione orientata agli esiti viene mostrato sullo stream degli eventi.

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

Evento utente di definizione dell'esito

Questo è l'evento che invii per avviare un esito. Viene restituito 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'esito

Emesso una volta che il grader avvia una valutazione su un ciclo di iterazione. Il campo iteration è un contatore di revisioni 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'esito 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...",
  "iteration": 0,
  "processed_at": "2026-03-25T14:02:10Z"
}

Fine della valutazione dell'esito

Emesso quando un ciclo di valutazione dell'esito termina: dopo che il grader ha finito di valutare un'iterazione, o quando la sessione viene interrotta mentre un esito è attivo. 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'esito

Puoi ascoltare sullo stream degli eventi per span.outcome_evaluation_end, oppure effettuare il polling di GET /v1/sessions/{session_id} e leggere outcome_evaluations[].result. Finché una valutazione non è completata, result riporta pending, running o evaluating:

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

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

Recuperare i deliverable

L'agente scrive i file di output in /mnt/session/outputs/ all'interno della sandbox. Per recuperarli, elenca i file tramite la Files API con l'ID della sessione come scope_id, poi scaricali per ID. Il filtraggio per scope_id richiede l'header beta managed-agents-2026-04-01 sulla richiesta di elenco, quindi gli esempi SDK e CLI effettuano quella chiamata tramite il namespace beta e passano l'header esplicitamente. I file appaiono nell'elenco poco dopo che l'agente ha finito di scriverli, a volte alcuni secondi dopo che la sessione diventa inattiva. Se un file che ti aspetti non è ancora elencato, elenca di nuovo dopo un breve ritardo; una volta che appare nell'elenco, il suo caricamento è terminato.

# List files produced by this session
# scope_id filtering requires the managed-agents beta on the files request
files = client.beta.files.list(scope_id=session.id, betas=["managed-agents-2026-04-01"])
for file in files:
    print(file.id, file.filename)

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

Passaggi successivi