Outcomes definieren

Das outcome hebt eine Session von einer Konversation zu Arbeit an. Du definierst, wie das Endergebnis aussehen soll und wie die Qualität gemessen wird. Der Agent arbeitet auf dieses Ziel hin, bewertet sich selbst und iteriert, bis das Outcome erfüllt ist.

Wenn du ein Outcome definierst, stellt das Harness automatisch einen Grader bereit, der das Artefakt anhand einer Rubrik bewertet. Der Grader verwendet ein separates Kontextfenster, um nicht von den Implementierungsentscheidungen des Hauptagenten beeinflusst zu werden.

Der Grader gibt eine Erklärung zurück, die zusammenfasst, welche Kriterien bestanden oder nicht bestanden wurden, oder bestätigt, dass das Artefakt die Rubrik erfüllt. Dieses Feedback wird für die nächste Iteration an den Agenten zurückgegeben.



Eine Rubrik erstellen

Eine Rubrik ist ein Markdown-Dokument, das die Bewertung pro Kriterium beschreibt. Die Rubrik ist erforderlich.

Beispiel-Rubrik:

# 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

Übergib die Rubrik als Inline-Text bei user.define_outcome (siehe nächster Abschnitt), oder lade sie über die Files API hoch, um sie sessionübergreifend wiederzuverwenden.

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



Eine Session mit einem Outcome erstellen

Nachdem du eine Session erstellt hast, sende ein user.define_outcome-Event. Der Agent beginnt sofort mit der Arbeit; es ist kein zusätzliches User-Message-Event erforderlich.

# Erstelle eine Session
session = client.beta.sessions.create(
    agent=agent.id,
    environment_id=environment.id,
    title="Financial analysis on Costco",
)

# Definiere das Ergebnis — Agent beginnt bei Empfang mit der Arbeit
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},
            # oder: "rubric": {"type": "file", "file_id": rubric.id},
            "max_iterations": 5,  # optional; default 3, max 20
        }
    ],
)



Outcome-Events

Der Fortschritt einer outcome-orientierten Session wird über den Event-Stream sichtbar gemacht.

• agent.*-Events (wie Nachrichten und Tool-Nutzung) zeigen den Fortschritt in Richtung des Outcomes.
• span.outcome_evaluation_*-Events werden nur für outcome-orientierte Sessions ausgegeben und zeigen die Anzahl der Iterationsschleifen und den Feedback-Prozess des Graders.
• Du kannst auch user.message-Events an eine outcome-orientierte Session senden, um die Arbeit des Agenten während des Fortschritts zu lenken, aber das ist nicht erforderlich: Der Agent arbeitet eigenständig auf das Outcome hin und iteriert, bis er erfolgreich ist oder keine Iterationen mehr übrig sind.
• Ein user.interrupt-Event pausiert die Arbeit am aktuellen Outcome und markiert das span.outcome_evaluation_end.result als interrupted, sodass du ein neues Outcome starten kannst.
• Nach der finalen Outcome-Bewertung kann die Session als konversationelle Session fortgesetzt oder ein neues Outcome gestartet werden. Die Session behält den Verlauf des vorherigen Outcomes bei.



Define-Outcome-User-Event

Dies ist das Event, das du sendest, um ein Outcome zu initiieren. Es wird bei Empfang zurückgespiegelt, einschließlich eines processed_at-Zeitstempels und einer 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
}



Outcome-Evaluation-Start

Wird ausgegeben, sobald der Grader eine Bewertung über eine Iterationsschleife startet. Das Feld iteration ist ein 0-indizierter Revisionszähler: 0 ist die erste Bewertung, 1 ist die Neubewertung nach der ersten Revision und so weiter.

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



Outcome-Evaluation-Ongoing

Heartbeat, der ausgegeben wird, während der Grader läuft. Die interne Argumentation des Graders ist nicht einsehbar: Du siehst, dass er arbeitet, nicht was er denkt.

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



Outcome-Evaluation-End

Wird ausgegeben, nachdem der Grader die Bewertung einer Iteration abgeschlossen hat. Das Feld result gibt an, was als Nächstes passiert.

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



Outcome-Status überprüfen

Du kannst entweder im Event-Stream auf span.outcome_evaluation_end lauschen oder GET /v1/sessions/:id abfragen und outcome_evaluations[].result auslesen:

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

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



Deliverables abrufen

Der Agent schreibt Ausgabedateien nach /mnt/session/outputs/ innerhalb der Sandbox. Sobald die Session im Zustand idle ist, rufe sie über die Files API ab, die auf die Session beschränkt ist:

# Liste die von dieser Session erzeugten Dateien auf
files = client.beta.files.list(scope_id=session.id)
for f in files:
    print(f.id, f.filename)

# Lade eine Datei herunter
if files.data:
    content = client.beta.files.download(files.data[0].id)
    content.write_to_file("/tmp/output.txt")