Scratchpad tools

Introduced 0.12.0

The scratchpad tools give an agent a per-conversation notepad. An agent saves short notes with the WriteToScratchPadTool and reads them back later with the ReadFromScratchPadTool, so a multi-step agent can keep a plan and interim findings across tool calls instead of losing them between steps.

Notes persist within a single conversation — they are threaded by the conversational runner from one step to the next — and inherit that conversation's organization and user scoping. There are two tools:

• WriteToScratchPadTool — appends a note to the scratchpad.
• ReadFromScratchPadTool — reads back every note saved so far.

Because they are most useful when an agent reasons over several steps, pair them with a conversational agent.

Step 1: Register an agent with both scratchpad tools

The following request registers a conversational agent that can write to and read from its scratchpad:

POST /_plugins/_ml/agents/_register
{
  "name": "Test_Agent_With_ScratchPad",
  "type": "conversational",
  "description": "an agent that keeps notes while it works",
  "llm": {
    "model_id": "kLj9Bo0Bpc3sThaJdY9x",
    "parameters": {
      "max_iteration": 5
    }
  },
  "memory": {
    "type": "conversation_index"
  },
  "tools": [
    {
      "type": "WriteToScratchPadTool",
      "name": "WriteNote"
    },
    {
      "type": "ReadFromScratchPadTool",
      "name": "ReadNotes"
    }
  ]
}

Lucenia responds with an agent ID:

{
  "agent_id": "9X7xWI0Bpc3sThaJdY9i"
}

Step 2: Run the agent

As the agent works through a task, it calls WriteToScratchPadTool to save a note and ReadFromScratchPadTool to recall everything it has saved so far. Writing a note returns a short confirmation:

Saved. You now have 2 note(s).

Reading the scratchpad returns the numbered list of notes:

Your scratchpad notes:
1. User wants orders over $100 from the last week.
2. The order_date field is a date; total is the amount field.

If nothing has been saved yet, the read tool returns a hint to start taking notes.

WriteToScratchPadTool parameters

The following table lists the parameters for the WriteToScratchPadTool.

Parameter	Type	Required/Optional	Description
notes	String	Required	The note to append to the scratchpad. If omitted, the tool falls back to the raw input parameter.

ReadFromScratchPadTool parameters

The ReadFromScratchPadTool takes no parameters. It returns every note saved to the scratchpad during the current conversation.