Cloudflare Agents WorkPaper Spreadsheet Tool

Cloudflare Agents can keep state per customer, workspace, or planning session. That fits workbook-backed workflows: store the WorkPaper document with the agent, expose a small read tool, and expose one validated write tool.

Use @bilig/workpaper for the spreadsheet part: read a computed range, write one input cell, verify the dependent formulas, serialize the document, and restore it.

Run the checked adapter

git clone https://github.com/proompteng/bilig.git
cd bilig
pnpm --dir examples/headless-workpaper install --ignore-workspace
pnpm --dir examples/headless-workpaper run agent:framework-adapters

The Cloudflare Agents lane exposes AI SDK-style tools and a verified write:

{
  "toolNames": ["readWorkPaperSummary", "setWorkPaperInputCell"],
  "writeResult": {
    "editedCell": "Inputs!B3",
    "checks": {
      "formulasPersisted": true,
      "restoredMatchesAfter": true,
      "expectedArrChanged": true
    }
  }
}

Cloudflare Agents shape

Cloudflare’s Agents docs describe AIChatAgent, server-side tools, and the agentTool helper for retained sub-agent calls. This WorkPaper example keeps the integration simpler: expose ordinary AI SDK-style tools from the agent runtime and keep the mutation behind one small function.

const tools = {
  setWorkPaperInputCell: {
    description: 'Set one WorkPaper input cell and return formula readback.',
    inputSchema: setInputCellInputSchema,
    execute: setWorkPaperInputCell,
  },
}

If the WorkPaper document is stored in the Agent instance, save only after the tool returns a valid readback. That makes reconnects and later tool calls start from a verified workbook state.

What to copy

• Use Agent state for the current WorkPaper document when each user or team has an isolated workbook.
• Keep tool arguments narrow: sheet, address, value.
• Return before/after computed values and restored readback equality.
• Use the same WorkPaper functions locally before deploying the Agent.

Official Cloudflare references: https://developers.cloudflare.com/agents/api-reference/agents-api/ and https://developers.cloudflare.com/agents/api-reference/agent-tools/.

Runnable source: examples/headless-workpaper/agent-framework-adapters.ts.