Scratchpad Tools

Scratchpad tools give agents a shared workspace for collecting notes, drafting content, and coordinating findings before taking action. Instead of writing a comment or review immediately, agents can accumulate results in a scratchpad and publish only when ready.

Available tools

Tool	Parameters	Description
`write_scratchpad`	`name`, `content`	Create or overwrite a scratchpad.
`append_scratchpad`	`name`, `content`	Append to a scratchpad. Creates it if it doesn’t exist.
`read_scratchpad`	`name`	Read the full content of a scratchpad.
`list_scratchpads`	(none)	List all scratchpad names in the current workspace.

Naming rules

Names support letters, numbers, hyphens, and underscores only. No slashes or spaces. Examples: findings, review-summary, security_notes, chunk-1

Collecting results before publishing

Agents often need to gather information across multiple files, tests, or analysis steps before producing a final output. Scratchpads act as a staging area: agents write findings as they go, then read the scratchpad to compose a polished comment, review, or ticket update.

steps:
  - id: "code-review"
    name: "Code Review"
    action: "agent.run"
    params:
      agentId: "code-reviewer"
      instruction: |
        Review the PR changes. As you analyze each file, append your findings
        to the scratchpad "review-notes" using append_scratchpad.
        When done, read the scratchpad and post a single, organized review comment on the PR.

This pattern avoids scattered, incremental comments. The agent builds up a complete picture first, then publishes once.

Multi-agent collaboration

In an agent.session, multiple agents share the same scratchpads. Each agent can append its findings independently, and the coordinator can read everything to produce a consolidated result. Use append_scratchpad when multiple agents contribute: it prevents agents from overwriting each other’s work.

steps:
  - id: "review-session"
    name: "Review Session"
    action: "agent.session"
    params:
      goal: "Review the PR for security, performance, and correctness"
      agentIds: ["security-expert", "performance-expert", "code-reviewer"]
      instruction: |
        Each agent: append your findings to the scratchpad "review-findings".
        When all reviews are done, read the scratchpad and post a combined review comment.

Passing context between workflow steps

Scratchpads persist across steps within a workflow run. An agent in one step can write a scratchpad that agents in later steps read, without relying on {{outputs}} templates. This is useful when:

The data is too large or structured for step output templates
Multiple steps need to build up a shared document incrementally
You want a later step to consume structured content directly

steps:
  - id: "analyze"
    name: "Analyze Codebase"
    action: "agent.run"
    params:
      agentId: "senior-developer"
      instruction: |
        Analyze the repository structure and write a summary to the scratchpad "analysis".
        Include key components, dependencies, and areas of concern.

  - id: "review"
    name: "Review Session"
    action: "agent.session"
    params:
      goal: "Review the code based on the analysis"
      agentIds: ["code-reviewer", "security-expert"]
      instruction: |
        Read the scratchpad "analysis" to understand the codebase context.
        Append your findings to "review-findings".
        When done, read "review-findings" and post a summary comment on the PR.

Content format

Scratchpads store plain text, but you control the format by instructing the agent what to write. You can use Markdown, JSON, JSONL, or any other text format that fits your workflow. For example, instruct an agent to append one JSON line per finding to make it easy for a later step to parse, or use Markdown for a human-readable draft.

When to use scratchpads vs step outputs

	Scratchpads	Step outputs (`{{outputs}}`)
Best for	Drafting content, multi-agent collaboration, large or structured data	Simple values passed to the next step
Format	Any text (Markdown, JSON, JSONL, plain text)	String from agent response
Multiple writers	Yes, via `append_scratchpad`	No: one step, one output
Readable by	Any agent in any step	Template expressions in step params

Get Started

Concepts

Quick Starts

Security & Compliance

Workflows and Actions

Reference

Integrations

Repositories

Available tools

Naming rules

Collecting results before publishing

Multi-agent collaboration

Passing context between workflow steps

Content format

When to use scratchpads vs step outputs

​Available tools

​Naming rules

​Collecting results before publishing

​Multi-agent collaboration

​Passing context between workflow steps

​Content format

​When to use scratchpads vs step outputs

Available tools

Naming rules

Collecting results before publishing

Multi-agent collaboration

Passing context between workflow steps

Content format

When to use scratchpads vs step outputs