Définir des résultats

Le outcome élève une session du statut de conversation à celui de travail. Vous définissez à quoi doit ressembler le résultat final et comment mesurer sa qualité. L'agent travaille vers cet objectif, s'auto-évaluant et itérant jusqu'à ce que le résultat soit atteint.

Lorsque vous définissez un résultat, le harnais provisionne automatiquement un grader (évaluateur) pour évaluer l'artefact par rapport à une grille d'évaluation. L'évaluateur utilise une « context window » (fenêtre de contexte) distincte afin de ne pas être influencé par les choix d'implémentation de l'agent principal.

L'évaluateur renvoie une explication résumant quels critères ont été satisfaits ou non, ou confirmant que l'artefact satisfait la grille d'évaluation. Ce retour est transmis à l'agent pour l'itération suivante.



Créer une grille d'évaluation

Une grille d'évaluation est un document markdown décrivant la notation critère par critère. La grille d'évaluation est obligatoire.

Exemple de grille d'évaluation :

# 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

Passez la grille d'évaluation sous forme de texte inline sur user.define_outcome (voir la section suivante), ou téléversez-la via l'API Files pour la réutiliser dans plusieurs sessions.

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



Créer une session avec un résultat

Après avoir créé une session, envoyez un événement user.define_outcome. L'agent commence à travailler immédiatement ; aucun événement de message utilisateur supplémentaire n'est requis.

# Créer une session
session = client.beta.sessions.create(
    agent=agent.id,
    environment_id=environment.id,
    title="Financial analysis on Costco",
)

# Définir le résultat — l'agent commence à travailler dès réception
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},
            # ou : "rubric": {"type": "file", "file_id": rubric.id},
            "max_iterations": 5,  # optional; default 3, max 20
        }
    ],
)



Événements de résultat

La progression d'une session orientée résultat est exposée sur le flux d'événements.

• Les événements agent.* (tels que les messages et l'utilisation d'outils) montrent la progression vers le résultat.
• Les événements span.outcome_evaluation_* ne sont émis que pour les sessions orientées résultat et montrent le nombre de boucles d'itération ainsi que le processus de retour de l'évaluateur.
• Vous pouvez également envoyer des événements user.message à une session orientée résultat pour orienter le travail de l'agent au fur et à mesure de sa progression, mais ce n'est pas obligatoire : l'agent travaille vers le résultat de manière autonome, itérant jusqu'à ce qu'il réussisse ou épuise ses itérations.
• Un événement user.interrupt met en pause le travail sur le résultat en cours et marque le span.outcome_evaluation_end.result comme interrupted, vous permettant de lancer un nouveau résultat.
• Après l'évaluation finale du résultat, la session peut être poursuivie en tant que session conversationnelle, ou un nouveau résultat peut être lancé. La session conserve l'historique du résultat précédent.



Événement utilisateur de définition de résultat

Il s'agit de l'événement que vous envoyez pour initier un résultat. Il est renvoyé en écho à la réception, incluant un horodatage processed_at et 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
}



Début de l'évaluation du résultat

Émis une fois que l'évaluateur démarre une évaluation sur une boucle d'itération. Le champ iteration est un compteur de révision indexé à partir de 0 : 0 est la première évaluation, 1 est la réévaluation après la première révision, et ainsi de suite.

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



Évaluation du résultat en cours

Signal de présence émis pendant que l'évaluateur s'exécute. Le raisonnement interne de l'évaluateur est opaque : vous voyez qu'il travaille, pas ce qu'il pense.

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



Fin de l'évaluation du résultat

Émis après que l'évaluateur a terminé l'évaluation d'une itération. Le champ result indique ce qui se passe ensuite.

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



Vérifier le statut du résultat

Vous pouvez soit écouter le flux d'événements pour span.outcome_evaluation_end, soit interroger GET /v1/sessions/:id et lire 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... : satisfait



Récupérer les livrables

L'agent écrit les fichiers de sortie dans /mnt/session/outputs/ à l'intérieur du bac à sable. Une fois la session à l'état idle, récupérez-les via l'API Files limitée à la session :

# Lister les fichiers produits par cette session
files = client.beta.files.list(scope_id=session.id)
for f in files:
    print(f.id, f.filename)

# Télécharger un fichier
if files.data:
    content = client.beta.files.download(files.data[0].id)
    content.write_to_file("/tmp/output.txt")