How to Design an Agent Scratchpad for Reliable Reasoning

Concrete Example

Scratchpad Class

from dataclasses import dataclass

@dataclass
class Turn:
    thought: str
    action: str
    action_input: str
    observation: str

class Scratchpad:
    DELIMITER = "---"
    MAX_TOKENS = 4000
    SUMMARY_TRIGGER = 3200

    def __init__(self, system_prompt: str):
        self.system_prompt = system_prompt
        self.turns: list[Turn] = []
        self.summary: str | None = None

    def add_turn(self, turn: Turn) -> None:
        self.turns.append(turn)

    def should_trim(self) -> bool:
        return len(self.render()) // 4 > self.SUMMARY_TRIGGER

    def trim_oldest(self, keep: int = 5) -> None:
        if len(self.turns) <= keep:
            return
        removed = self.turns[:-keep]
        actions = ", ".join(f"{t.action}({t.action_input[:30]})" for t in removed)
        self.summary = f"[Earlier context: {len(removed)} turns. Actions: {actions}]"
        self.turns = self.turns[-keep:]

    def render(self) -> str:
        parts = [self.system_prompt]
        if self.summary:
            parts.append(f"\n{self.DELIMITER}\n{self.summary}")
        for i, turn in enumerate(self.turns, 1):
            parts.append(f"\n{self.DELIMITER}\nTurn {i}:\nThought: {turn.thought}\nAction: {turn.action}\nAction Input: {turn.action_input}\nObservation: {turn.observation}\n{self.DELIMITER}")
        return "".join(parts)

Enforces consistent formatting with delimiters and labeled sections. should_trim() checks token count, and trim_oldest() removes early turns while preserving a summary of what actions were performed.

Key Ideas