Mendefinisikan hasil

outcome meningkatkan sebuah sesi dari sekadar percakapan menjadi pekerjaan. Anda mendefinisikan seperti apa hasil akhir yang diharapkan dan bagaimana mengukur kualitasnya. Agen bekerja menuju target tersebut, melakukan evaluasi mandiri dan iterasi hingga hasil tercapai.

Ketika Anda mendefinisikan sebuah outcome, harness secara otomatis menyediakan grader (penilai) untuk mengevaluasi artefak terhadap sebuah rubrik. Grader menggunakan jendela konteks terpisah agar tidak terpengaruh oleh pilihan implementasi agen utama.

Grader mengembalikan penjelasan yang merangkum kriteria mana yang lulus atau gagal, atau mengonfirmasi bahwa artefak memenuhi rubrik. Umpan balik tersebut diserahkan kembali ke agen untuk iterasi berikutnya.



Membuat rubrik

Rubrik adalah dokumen markdown yang menjelaskan penilaian per kriteria. Rubrik bersifat wajib.

Contoh 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

Kirimkan rubrik sebagai teks inline pada user.define_outcome (lihat bagian berikutnya), atau unggah melalui Files API untuk digunakan kembali di berbagai sesi.

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



Membuat sesi dengan outcome

Setelah membuat sesi, kirim event user.define_outcome. Agen segera mulai bekerja; tidak diperlukan event pesan pengguna tambahan.

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

# Definisikan hasil — agen mulai bekerja saat menerimanya
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},
            # atau: "rubric": {"type": "file", "file_id": rubric.id},
            "max_iterations": 5,  # optional; default 3, max 20
        }
    ],
)



Event outcome

Progres pada sesi berorientasi outcome ditampilkan pada stream event.

• Event agent.* (seperti pesan dan penggunaan alat) menunjukkan progres menuju outcome.
• Event span.outcome_evaluation_* hanya dipancarkan untuk sesi berorientasi outcome dan menunjukkan jumlah loop iterasi serta proses umpan balik grader.
• Anda juga dapat mengirim event user.message ke sesi berorientasi outcome untuk mengarahkan pekerjaan agen selama berlangsung, tetapi ini tidak wajib: agen bekerja menuju outcome secara mandiri, melakukan iterasi hingga berhasil atau kehabisan iterasi.
• Event user.interrupt menjeda pekerjaan pada outcome saat ini dan menandai span.outcome_evaluation_end.result sebagai interrupted, memungkinkan Anda memulai outcome baru.
• Setelah evaluasi outcome terakhir, sesi dapat dilanjutkan sebagai sesi percakapan, atau outcome baru dapat dimulai. Sesi mempertahankan riwayat dari outcome sebelumnya.



Event pengguna define outcome

Ini adalah event yang Anda kirim untuk memulai sebuah outcome. Event ini dipantulkan kembali saat diterima, termasuk timestamp processed_at dan 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

Dipancarkan begitu grader memulai evaluasi pada satu loop iterasi. Field iteration adalah penghitung revisi berbasis indeks 0: 0 adalah evaluasi pertama, 1 adalah evaluasi ulang setelah revisi pertama, dan seterusnya.

{
  "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 yang dipancarkan selama grader berjalan. Penalaran internal grader bersifat tertutup: Anda melihat bahwa grader sedang bekerja, bukan apa yang sedang dipikirkannya.

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



Outcome evaluation end

Dipancarkan setelah grader selesai mengevaluasi satu iterasi. Field result menunjukkan apa yang terjadi selanjutnya.

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



Memeriksa status outcome

Anda dapat mendengarkan pada event stream untuk span.outcome_evaluation_end, atau melakukan polling GET /v1/sessions/:id dan membaca 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



Mengambil deliverable

Agen menulis file output ke /mnt/session/outputs/ di dalam sandbox. Setelah sesi berada dalam status idle, ambil file tersebut melalui Files API yang dicakupkan ke sesi:

# Daftar file yang dihasilkan oleh sesi ini
files = client.beta.files.list(scope_id=session.id)
for f in files:
    print(f.id, f.filename)

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