Definir resultados

O outcome eleva uma sessão de conversa para trabalho. Você define como o resultado final deve parecer e como medir a qualidade. O agente trabalha em direção a esse alvo, auto-avaliando e iterando até que o resultado seja alcançado.

Quando você define um resultado, o harness provisiona automaticamente um avaliador para avaliar o artefato em relação a uma rubrica. Ele aproveita uma janela de contexto separada para evitar ser influenciado pelas escolhas de implementação do agente principal.

O avaliador retorna um detalhamento por critério: confirmação de que o artefato satisfaz a rubrica, ou as lacunas específicas entre o trabalho atual e os requisitos. Esse feedback é devolvido ao agente para a próxima iteração.

Criar uma rubrica

Uma rubrica é um documento markdown descrevendo pontuação por critério. A rubrica é obrigatória.

Exemplo de rubrica:

# Rubrica do Modelo DCF

## Projeções de Receita
- Usa dados de receita históricos dos últimos 5 anos fiscais
- Projeta receita para pelo menos 5 anos à frente
- As suposições de taxa de crescimento são explicitamente declaradas e razoáveis

## Estrutura de Custos
- COGS e despesas operacionais são modelados separadamente
- As margens são consistentes com tendências históricas ou desvios são justificados

## Taxa de Desconto
- WACC é calculado com suposições declaradas para custo de capital próprio e custo de dívida
- Beta, taxa livre de risco e prêmio de risco de capital são obtidos ou justificados

## Valor Terminal
- Usa método de perpetuidade de crescimento ou método de múltiplo de saída (declara qual)
- A taxa de crescimento terminal não excede o crescimento do PIB de longo prazo

## Qualidade de Saída
- Todos os valores estão em um único arquivo .xlsx com planilhas claramente rotuladas
- As suposições principais estão em uma planilha separada "Assumptions"
- A análise de sensibilidade em WACC e taxa de crescimento terminal está incluída

Passe a rubrica como texto inline em user.define_outcome (mostrado na próxima seção), ou carregue-a via Files API para reutilização em sessões:

Requer cabeçalho beta 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}")

Criar uma sessão com um resultado

Após criar uma sessão, envie um evento user.define_outcome. O agente começa a trabalhar imediatamente; nenhum evento de mensagem de usuário adicional é necessário.

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

Eventos de resultado

O progresso em uma sessão orientada por resultado é exibido no stream de eventos.

• Os eventos agent.* (mensagens, uso de ferramentas, etc.) mostram progresso em direção ao resultado.
• Os eventos span.outcome_evaluation_* são emitidos apenas para sessões orientadas por resultado e mostram o número de loops de iteração e o processo de feedback do avaliador.
• Você também pode enviar eventos user.message events para uma sessão orientada por resultado, para direcionar o trabalho do agente conforme ele progride, mas esses não são tão necessários; o agente sabe trabalhar até ter esgotado suas iterações ou alcançado o resultado.
• Um evento user.interrupt pausará o trabalho no resultado atual e marcará o span.outcome_evaluation_end.result como interrupted, permitindo que você inicie um novo resultado.
• Após a avaliação final do resultado, a sessão pode ser continuada como uma sessão conversacional, ou um novo resultado pode ser iniciado. A sessão reterá o histórico do resultado anterior.

Definir evento de usuário de resultado

Este é o evento que você envia para iniciar um resultado. Ele é ecoado de volta no recebimento, incluindo um timestamp processed_at e 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
}

Início da avaliação de resultado

Emitido uma vez que o avaliador inicia uma avaliação sobre um loop de iteração. O campo iteration é um contador de revisão indexado em 0: 0 é a primeira avaliação, 1 é a reavaliação após a primeira revisão, e assim por diante.

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

Avaliação de resultado em andamento

Heartbeat emitido enquanto o avaliador é executado. O raciocínio interno do avaliador é opaco: você vê que está funcionando, não o que está pensando.

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

Fim da avaliação de resultado

Emitido após o avaliador terminar de avaliar uma iteração. O campo result indica o que acontece a seguir.

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

Verificando o status do resultado

Você pode escutar no event stream por span.outcome_evaluation_end, ou fazer polling em GET /v1/sessions/:id e ler 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

Recuperando entregáveis

O agente escreve arquivos de saída em /mnt/session/outputs/ dentro do contêiner. Após a sessão estar ociosa, busque-os via Files API com escopo para a sessão:

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