> Nível 12 de Agent Harness Patterns, uma trilha de padrões sobre como funcionam os agentes de IA. Versão web: https://harnesspatterns.dev/pt/patterns/sessions · Todos os padrões (em inglês): https://harnesspatterns.dev/llms.txt

# Sessões

O histórico de um agente vive na memória, e a memória acaba com o programa. Uma sessão vai anotando tudo, então a conversa sobrevive ao processo: você pode retomá-la amanhã, ou bifurcá-la.

## O problema

O histórico do nível 2 é uma lista na memória. Quando o programa para (um deploy, uma queda, alguém que fecha a aba e volta amanhã), a lista some e o agente começa do zero, perguntando de novo tudo o que já sabia.

Salvar só no final também não basta: uma execução que falha no meio é justamente a que você ia querer olhar, ou retomar de onde parou.

## A solução

Dê a cada conversa um id e um lugar no disco, e trate o histórico como esse arquivo, não como uma variável. Três movimentos dão conta:

- **Salvar no caminho**
   Escreva cada mensagem no arquivo da sessão assim que ela existe, uma linha por mensagem. Se algo cair no meio, nada se perde.
- **Retomar**
   Um agente novo com o mesmo id de sessão lê o arquivo de volta para o histórico antes da próxima requisição.
- **Bifurcar**
   Copie o histórico para uma sessão nova para testar outra coisa. A original fica como estava.

JSONL, uma mensagem JSON por linha, é o formato de costume: acrescentar uma mensagem é acrescentar uma linha, e uma última linha escrita pela metade é fácil de detectar. O Claude Code e o Codex guardam as próprias sessões do mesmo jeito, e é assim que as retomam.

## O elenco

O mesmo elenco de sempre, numa aventura.

- **O diário de aventura** (o arquivo de sessão): Um slot por id de sessão, uma marca por mensagem, escrita assim que ela existe.
- **O bandoneón** (o histórico): O que o agente tem na memória. Esvazia quando o jogo é desligado; o diário, não.
- **CONTINUE** (retomar): Um agente novo com o mesmo id, com o diário lido de volta para o histórico.
- **COPY A QUEST** (bifurcar): Um segundo slot que começa como cópia do primeiro. Depois, cada um cresce por conta própria.
- **Astor** (o loop): Roda o loop como sempre, e cada mensagem vai para o diário.
- **A vila** (as ferramentas): O ancião, o guarda e a loja: `talk_to` e `buy`.

## O código

**Com astorlm:** passe um `sessionId` e um `FileSessionManager`. O agente carrega a sessão quando é criado e a salva depois de cada mensagem; um id novo começa uma vazia. `fork()` devolve um agente novo sobre uma cópia da sessão.

**Do zero:** o loop do nível 2, com o histórico lido primeiro de um arquivo JSONL e cada mensagem nova acrescentada no final. Bifurcar é copiar o arquivo.

**Com astorlm**

```ts
import { FileSessionManager, OpenAIProvider, createLocalAgent, tool } from 'astorlm'
import { z } from 'zod'

const talkTo = tool({
  name: 'talk_to',
  description: 'Talk to someone in town. Returns what they say.',
  schema: z.object({ npc: z.string() }),
  execute: async ({ npc }) => town.talk(npc), // your code
})

const buy = tool({
  name: 'buy',
  description: 'Buy an item at the shop. Returns the price and the gold left.',
  schema: z.object({ item: z.string() }),
  execute: async ({ item }) => shop.buy(item), // your code
})

// The adventure log: quest-1.jsonl (one message per line) and quest-1.meta.json, in this folder.
const sessionManager = new FileSessionManager({ dir: './sessions' })

const quest = (sessionId: string) =>
  createLocalAgent({
    // Any OpenAI-compatible endpoint: OpenAI, Ollama, LM Studio, vLLM, a proxy…
    provider: new OpenAIProvider({
      baseURL: 'http://localhost:11434/v1', // e.g. Ollama's default address
      model: 'your-model', // e.g. 'llama3.1', 'gpt-4o-mini'
      apiKey: 'YOUR_API_KEY', // local servers usually ignore it
    }),
    tools: [talkTo, buy],
    sessionId, // a new id starts an empty log; a known one loads it
    sessionManager,
  })

// Day 1. Every message is saved as soon as it's added, so a crash loses nothing.
const day1 = await quest('quest-1')
await day1.run('I need to get into the Cave of Echoes. Find out what it takes, and get what you can.')

// …the process ends. Day 2: a new agent on the same id reads the log back before answering.
const day2 = await quest('quest-1')
console.log(day2.getMessages().length) // 6: yesterday is in the history
await day2.run('I got the Silver Key from the mayor’s daughter. What now?')

// A fork: a new session with a copy of every message. quest-1 stays as it was.
const west = await day2.fork({ newSessionId: 'quest-2' })
await west.run('Suppose the key doesn’t fit. Is there another way in?')
```

**TypeScript**

```ts
// Sessions from scratch: a JSONL file per conversation. Node's standard library only.
import { appendFileSync, copyFileSync, existsSync, mkdirSync, readFileSync } from 'node:fs'

type Message = { role: string; content: unknown; [key: string]: unknown }
const DIR = './sessions'
const pathOf = (id: string) => `${DIR}/${id}.jsonl`

// 1. Load: one JSON message per line. No file yet means a new, empty session.
export function load(id: string): Message[] {
  if (!existsSync(pathOf(id))) return []
  return readFileSync(pathOf(id), 'utf8')
    .split('\n')
    .filter(Boolean)
    .map((line) => JSON.parse(line))
}

// 2. Save as you go: append each message the moment it exists. A crash mid-run loses nothing.
function append(id: string, message: Message): void {
  mkdirSync(DIR, { recursive: true })
  appendFileSync(pathOf(id), JSON.stringify(message) + '\n')
}

// 3. Fork: copy the file. From here on, each session only appends to its own.
export function fork(from: string, to: string): void {
  copyFileSync(pathOf(from), pathOf(to))
}

// 4. The loop from level 2, with its history loaded first and every new message written down.
export async function runSession(id: string, prompt: string, maxTurns = 10): Promise<string> {
  const messages = load(id)
  const add = (message: Message) => {
    messages.push(message)
    append(id, message)
  }

  add({ role: 'user', content: prompt })
  for (let turn = 1; turn <= maxTurns; turn++) {
    const choice = await chat(messages) // one model call, as in level 2
    add(choice.message)
    if (choice.finish_reason !== 'tool_calls') return choice.message.content ?? ''
    for (const call of choice.message.tool_calls ?? []) {
      add({ role: 'tool', tool_call_id: call.id, content: await runTool(call) })
    }
  }
  throw new Error(`No answer after ${maxTurns} turns`)
}

// Day 1, then day 2 on the same id, then a fork to try another way.
await runSession('quest-1', 'I need to get into the Cave of Echoes. Find out what it takes, and get what you can.')
await runSession('quest-1', 'I got the Silver Key from the mayor’s daughter. What now?')
fork('quest-1', 'quest-2')
await runSession('quest-2', 'Suppose the key doesn’t fit. Is there another way in?')
```

**Python**

```python
# Sessions from scratch: a JSONL file per conversation. Standard library only.
import json
import shutil
from pathlib import Path

DIR = Path("sessions")

def path_of(session_id):
    return DIR / f"{session_id}.jsonl"

# 1. Load: one JSON message per line. No file yet means a new, empty session.
def load(session_id):
    path = path_of(session_id)
    if not path.exists():
        return []
    return [json.loads(line) for line in path.read_text(encoding="utf-8").splitlines() if line]

# 2. Save as you go: append each message the moment it exists. A crash mid-run loses nothing.
def append(session_id, message):
    DIR.mkdir(exist_ok=True)
    with path_of(session_id).open("a", encoding="utf-8") as log:
        log.write(json.dumps(message) + "\n")

# 3. Fork: copy the file. From here on, each session only appends to its own.
def fork(source, target):
    shutil.copyfile(path_of(source), path_of(target))

# 4. The loop from level 2, with its history loaded first and every new message written down.
def run_session(session_id, prompt, max_turns=10):
    messages = load(session_id)

    def add(message):
        messages.append(message)
        append(session_id, message)

    add({"role": "user", "content": prompt})
    for _ in range(max_turns):
        choice = chat(messages)  # one model call, as in level 2
        add(choice["message"])
        if choice["finish_reason"] != "tool_calls":
            return choice["message"].get("content") or ""
        for call in choice["message"].get("tool_calls", []):
            add({"role": "tool", "tool_call_id": call["id"], "content": run_tool(call)})

    raise RuntimeError(f"No answer after {max_turns} turns")

# Day 1, then day 2 on the same id, then a fork to try another way.
run_session("quest-1", "I need to get into the Cave of Echoes. Find out what it takes, and get what you can.")
run_session("quest-1", "I got the Silver Key from the mayor's daughter. What now?")
fork("quest-1", "quest-2")
run_session("quest-2", "Suppose the key doesn't fit. Is there another way in?")
```

## O que observar

- **Uma sessão retomada manda tudo de novo.** O dia 30 de uma conversa longa carrega os 29 anteriores. Sessões guardam o histórico; compactá-lo (nível 9) é o que evita que ele ultrapasse a janela de contexto.
- **Bifurcar copia o histórico, não o mundo.** A tocha foi comprada uma vez, e está nos dois slots. E-mails enviados, pedidos feitos e arquivos escritos pelas ferramentas aconteceram de verdade, em todos os ramos.
- **Confira a última linha ao retomar.** Se o programa morreu entre uma chamada de ferramenta e o seu resultado, o diário termina com uma chamada que ninguém respondeu, e a maioria dos provedores a rejeita. Descarte-a, ou acrescente um resultado de erro para ela.
- **Um só escritor por sessão.** Dois processos acrescentando linhas ao mesmo arquivo ao mesmo tempo as misturam. Dê a cada execução a sua sessão, ou uma trava.
- **Arquivos de sessão são dados pessoais.** Guardam tudo o que o usuário disse e cada resultado de ferramenta. Decida onde ficam, quem pode lê-los e quando são apagados.

## Padrões relacionados

- [2 · O loop do agente](https://harnesspatterns.dev/pt/patterns/agent-loop.md)
- [9 · A mochila enche](https://harnesspatterns.dev/pt/patterns/compaction.md)
- [13 · Memória](https://harnesspatterns.dev/pt/patterns/memory.md)
- [14 · Voltas limpas](https://harnesspatterns.dev/pt/patterns/fresh-laps.md)