Определение результатов

Параметр outcome превращает сессию из разговора в работу. Вы определяете, как должен выглядеть конечный результат и как измерять его качество. Агент работает над достижением этой цели, самостоятельно оценивая и итерируя, пока результат не будет достигнут.

Когда вы определяете результат, оболочка автоматически создаёт оценщик (grader) для проверки артефакта по рубрике. Оценщик использует отдельное контекстное окно, чтобы на него не влияли решения по реализации, принятые основным агентом.

Оценщик возвращает объяснение, в котором резюмируется, какие критерии выполнены, а какие нет, либо подтверждается, что артефакт удовлетворяет рубрике. Эта обратная связь передаётся агенту для следующей итерации.



Создание рубрики

Рубрика — это документ в формате markdown, описывающий оценку по каждому критерию. Рубрика обязательна.

Пример рубрики:

# 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

Передайте рубрику как встроенный текст в user.define_outcome (см. следующий раздел) или загрузите её через Files API для повторного использования в разных сессиях.

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



Создание сессии с результатом

После создания сессии отправьте событие user.define_outcome. Агент немедленно приступает к работе; дополнительное событие пользовательского сообщения не требуется.

# Создаём сессию
session = client.beta.sessions.create(
    agent=agent.id,
    environment_id=environment.id,
    title="Financial analysis on Costco",
)

# Определяем результат — агент начинает работу при получении
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},
            # или: "rubric": {"type": "file", "file_id": rubric.id},
            "max_iterations": 5,  # optional; default 3, max 20
        }
    ],
)



События результата

Прогресс в сессии, ориентированной на результат, отображается в потоке событий.

• События agent.* (такие как сообщения и использование инструментов) показывают прогресс в достижении результата.
• События span.outcome_evaluation_* генерируются только для сессий, ориентированных на результат, и показывают количество циклов итерации и процесс обратной связи от оценщика.
• Вы также можете отправлять события user.message в сессию, ориентированную на результат, чтобы направлять работу агента по мере её выполнения, но это не обязательно: агент самостоятельно работает над достижением результата, итерируя до тех пор, пока не добьётся успеха или не исчерпает лимит итераций.
• Событие user.interrupt приостанавливает работу над текущим результатом и помечает span.outcome_evaluation_end.result как interrupted, позволяя вам запустить новый результат.
• После финальной оценки результата сессию можно продолжить как разговорную сессию или запустить новый результат. Сессия сохраняет историю предыдущего результата.



Пользовательское событие определения результата

Это событие, которое вы отправляете для инициирования результата. Оно возвращается эхом при получении, включая временную метку processed_at и 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
}



Начало оценки результата

Генерируется, когда оценщик начинает оценку в рамках одного цикла итерации. Поле iteration — это счётчик ревизий с индексацией от 0: 0 — первая оценка, 1 — повторная оценка после первой ревизии и так далее.

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



Оценка результата в процессе

Сигнал активности (heartbeat), генерируемый во время работы оценщика. Внутренние рассуждения оценщика непрозрачны: вы видите, что он работает, но не то, о чём он думает.

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



Завершение оценки результата

Генерируется после того, как оценщик завершает оценку одной итерации. Поле result указывает, что произойдёт дальше.

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



Проверка статуса результата

Вы можете либо прослушивать поток событий на предмет span.outcome_evaluation_end, либо опрашивать GET /v1/sessions/:id и читать 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



Получение результатов работы

Агент записывает выходные файлы в /mnt/session/outputs/ внутри песочницы. Как только сессия перейдёт в состояние idle, получите их через Files API с областью действия, ограниченной сессией:

# Перечисляем файлы, созданные этой сессией
files = client.beta.files.list(scope_id=session.id)
for f in files:
    print(f.id, f.filename)

# Скачиваем файл
if files.data:
    content = client.beta.files.download(files.data[0].id)
    content.write_to_file("/tmp/output.txt")