Définir des résultats attendus

Un « outcome » (résultat attendu) indique à la session à quoi doit ressembler le résultat final et comment en mesurer la qualité. L'agent travaille en direction de cet objectif, en s'auto-évaluant et en itérant jusqu'à ce que le résultat attendu soit atteint.

Lorsque vous définissez un résultat attendu, le harnais provisionne automatiquement un grader (évaluateur) chargé d'é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 « rubric » (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

Transmettez la grille d'évaluation sous forme de texte en ligne dans user.define_outcome (voir Créer une session avec un résultat attendu), ou téléversez-la via l'API Files pour la réutiliser d'une session à l'autre.

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

Créer une session avec un résultat attendu

Les exemples suivants créent une session pour un agent et un environnement existants (tous deux créés séparément), puis envoient 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 liés aux résultats attendus

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 attendu.
• Les événements span.outcome_evaluation_* ne sont émis que pour les sessions orientées résultat et indiquent 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 de lui-même vers le résultat attendu, en itérant jusqu'à ce qu'il réussisse ou qu'il épuise ses itérations.
• Un événement user.interrupt met en pause le travail sur le résultat attendu en cours et marque span.outcome_evaluation_end.result comme interrupted, ce qui vous permet de lancer un nouveau résultat attendu.
• Après l'évaluation finale du résultat attendu, la session peut être poursuivie en tant que session conversationnelle, ou un nouveau résultat attendu peut être lancé. La session conserve l'historique du résultat attendu précédent.

Événement utilisateur de définition du résultat attendu

Il s'agit de l'événement que vous envoyez pour initier un résultat attendu. Il est renvoyé en écho à sa réception, avec 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 attendu

Émis lorsque l'évaluateur commence une évaluation sur une boucle d'itération. Le champ iteration est un compteur de révisions indexé à partir de 0 : 0 correspond à la première évaluation, 1 à 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 attendu en cours

Signal de vie (heartbeat) é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...",
  "iteration": 0,
  "processed_at": "2026-03-25T14:02:10Z"
}

Fin de l'évaluation du résultat attendu

Émis lorsqu'un cycle d'évaluation du résultat attendu se termine : après que l'évaluateur a fini d'évaluer une itération, ou lorsque la session est interrompue alors qu'un résultat attendu est actif. 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 l'état du résultat attendu

Vous pouvez soit écouter le flux d'événements pour détecter span.outcome_evaluation_end, soit interroger GET /v1/sessions/{session_id} et lire outcome_evaluations[].result. Tant qu'une évaluation n'est pas terminée, result indique pending, running ou evaluating :

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 sandbox. Pour les récupérer, listez les fichiers via l'API Files en utilisant l'ID de session comme scope_id, puis téléchargez-les par ID. Le filtrage par scope_id nécessite l'en-tête bêta managed-agents-2026-04-01 sur la requête de liste ; c'est pourquoi les exemples SDK et CLI effectuent cet appel via l'espace de noms beta et transmettent l'en-tête explicitement. Les fichiers apparaissent dans la liste peu après que l'agent a fini de les écrire, parfois quelques secondes après que la session est passée à l'état inactif. Si un fichier que vous attendez n'est pas encore listé, relancez la liste après un court délai ; une fois qu'il apparaît dans la liste, son téléversement est terminé.

# Lister les fichiers produits par cette session
# Le filtrage par scope_id requiert la bêta managed-agents sur la requête files
files = client.beta.files.list(scope_id=session.id, betas=["managed-agents-2026-04-01"])
for file in files:
    print(file.id, file.filename)

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

Étapes suivantes