Definir resultados

Um "outcome" (resultado) informa à sessão como o resultado final deve ser e como medir sua qualidade. O agente trabalha em direção a esse objetivo, autoavaliando-se e iterando até que o resultado seja alcançado.

Quando você define um resultado, o harness provisiona automaticamente um grader (avaliador) para avaliar o artefato com base em uma "rubric" (rubrica). O avaliador usa uma "context window" (janela de contexto) separada para evitar ser influenciado pelas escolhas de implementação do agente principal.

O avaliador retorna uma explicação que resume quais critérios foram aprovados ou reprovados, ou que confirma que o artefato satisfaz a rubrica. Esse feedback é repassado ao agente para a próxima iteração.

Criar uma rubrica

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

Exemplo de rubrica:

# 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

Passe a rubrica como texto inline em user.define_outcome (consulte Criar uma sessão com um resultado) ou faça o upload dela por meio da Files API para reutilizá-la entre sessões.

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

Criar uma sessão com um resultado

Os exemplos a seguir criam uma sessão para um agente e um ambiente existentes (ambos criados separadamente) e, em seguida, enviam um evento user.define_outcome. O agente começa a trabalhar imediatamente. Nenhum evento adicional de mensagem do usuário é 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 a resultados é exibido no stream de eventos.

• Eventos agent.* (como mensagens e uso de ferramentas) mostram o progresso em direção ao resultado.
• Eventos span.outcome_evaluation_* são emitidos apenas para sessões orientadas a resultados e mostram o número de ciclos de iteração e o processo de feedback do avaliador.
• Você também pode enviar eventos user.message para uma sessão orientada a resultados para direcionar o trabalho do agente à medida que ele avança, mas isso não é obrigatório: o agente trabalha em direção ao resultado por conta própria, iterando até ter sucesso ou esgotar as iterações.
• Um evento user.interrupt pausa o trabalho no resultado atual e marca 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 continuar como uma sessão conversacional, ou um novo resultado pode ser iniciado. A sessão mantém o histórico do resultado anterior.

Evento de usuário de definição de resultado

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

Emitido quando o avaliador inicia uma avaliação sobre um ciclo de iteração. O campo iteration é um contador de revisões indexado a partir de 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 do resultado em andamento

"Heartbeat" (sinal de atividade) emitido enquanto o avaliador é executado. O raciocínio interno do avaliador é opaco: você vê que ele está trabalhando, não o que ele está pensando.

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

Fim da avaliação do resultado

Emitido quando um ciclo de avaliação do resultado termina: depois que o avaliador conclui a avaliação de uma iteração, ou quando a sessão é interrompida enquanto um resultado está ativo. O campo result indica o que acontece em seguida.

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

Verificar o status do resultado

Você pode escutar o stream de eventos aguardando span.outcome_evaluation_end, ou consultar periodicamente GET /v1/sessions/{session_id} e ler outcome_evaluations[].result. Até que uma avaliação seja concluída, result informa 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

Recuperar entregáveis

O agente grava os arquivos de saída em /mnt/session/outputs/ dentro do sandbox. Para recuperá-los, liste os arquivos por meio da Files API usando o ID da sessão como scope_id e, em seguida, faça o download deles pelo ID. Filtrar por scope_id requer o cabeçalho beta managed-agents-2026-04-01 na requisição de listagem, por isso os exemplos de SDK e CLI fazem essa chamada por meio do namespace beta e passam o cabeçalho explicitamente. Os arquivos aparecem na lista pouco depois de o agente terminar de gravá-los, às vezes alguns segundos depois de a sessão ficar ociosa. Se um arquivo esperado ainda não estiver listado, liste novamente após um breve intervalo; assim que ele aparecer na lista, seu upload terá sido concluído.

# List files produced by this session
# scope_id filtering requires the managed-agents beta on the files request
files = client.beta.files.list(scope_id=session.id, betas=["managed-agents-2026-04-01"])
for file in files:
    print(file.id, file.filename)

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

Próximos passos