Définir les résultats

Le outcome élève une session de conversation à travail. Vous définissez à quoi devrait ressembler le résultat final et comment mesurer la 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 évaluateur pour évaluer l'artefact par rapport à une rubrique. Il exploite une fenêtre de contexte séparée pour éviter d'être influencé par les choix d'implémentation de l'agent principal.

L'évaluateur retourne une ventilation par critère : soit une confirmation que l'artefact satisfait la rubrique, soit les lacunes spécifiques entre le travail actuel et les exigences. Ces commentaires sont renvoyés à l'agent pour l'itération suivante.

Créer une rubrique

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

Exemple de rubrique :

# Rubrique du modèle DCF

## Projections de revenus
- Utilise les données de revenus historiques des 5 derniers exercices fiscaux
- Projette les revenus pour au moins 5 ans à l'avance
- Les hypothèses de taux de croissance sont explicitement énoncées et raisonnables

## Structure des coûts
- Le COGS et les dépenses d'exploitation sont modélisés séparément
- Les marges sont cohérentes avec les tendances historiques ou les écarts sont justifiés

## Taux d'actualisation
- Le WACC est calculé avec des hypothèses énoncées pour le coût des capitaux propres et le coût de la dette
- Le bêta, le taux sans risque et la prime de risque sur actions sont sourcés ou justifiés

## Valeur terminale
- Utilise soit la méthode de croissance perpétuelle soit la méthode du multiple de sortie (indiquez laquelle)
- Le taux de croissance terminal ne dépasse pas la croissance du PIB à long terme

## Qualité de la sortie
- Tous les chiffres sont dans un seul fichier .xlsx avec des feuilles clairement étiquetées
- Les hypothèses clés se trouvent sur une feuille « Assumptions » séparée
- L'analyse de sensibilité sur le WACC et le taux de croissance terminal est incluse

Passez la rubrique en tant que texte en ligne sur user.define_outcome (montré dans la section suivante), ou téléchargez-la via l'API Files pour la réutiliser dans les sessions :

Nécessite l'en-tête bêta files-api-2025-04-14.

from pathlib import Path

rubric = client.beta.files.upload(file=Path("/path/to/pr_review_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.

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

Événements de résultat

La progression d'une session orientée vers les résultats est affichée sur le flux d'événements.

• Les événements agent.* (messages, utilisation d'outils, etc.) montrent la progression vers le résultat.
• Les événements span.outcome_evaluation_* ne sont émis que pour les sessions orientées vers les résultats et montrent le nombre de boucles d'itération et le processus de rétroaction de l'évaluateur.
• Vous pouvez également envoyer des événements user.message events à une session orientée vers les résultats, pour diriger le travail de l'agent au fur et à mesure de sa progression, mais ce n'est pas aussi nécessaire ; l'agent sait qu'il doit travailler jusqu'à ce qu'il ait épuisé ses itérations ou atteint le résultat.
• Un événement user.interrupt mettra en pause le travail sur le résultat actuel et marquera le span.outcome_evaluation_end.result comme interrupted, ce qui vous permettra 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 conservera l'historique du résultat précédent.

Définir l'événement utilisateur de résultat

C'est l'événement que vous envoyez pour initier un résultat. Il est renvoyé à la réception, y compris un horodatage processed_at et 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 commence 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

Battement de cœur émis pendant que l'évaluateur s'exécute. Le raisonnement interne de l'évaluateur est opaque : vous voyez qu'il fonctionne, 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 ait 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...: satisfied

Récupérer les livrables

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

files = client.beta.files.list(scope_id=session.id)
for f in files.data:
    print(f"{f.id}: {f.filename} ({f.size_bytes} bytes)")

content = client.beta.files.download(files.data[0].id)
content.write_to_file("costco_dcf.xlsx")