CrewAI WorkPaper Spreadsheet Tool

CrewAI workflows can call a WorkPaper-backed TypeScript service when an agent needs spreadsheet math, formula readback, or workbook persistence. Keep the CrewAI side as the orchestration layer; keep workbook construction, validation, formula calculation, and serialization in @bilig/workpaper.

This is an interop recipe, not an official CrewAI adapter. The useful boundary is a small JSON contract:

• input payload: sheetName, address, and value
• formula readback: before/after computed Summary values
• error shape: { ok: false, error: string }

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 CrewAI lane returns plain JSON tool metadata plus a verified WorkPaper write result:

{
  "toolNames": ["read_workpaper_summary", "set_workpaper_input_cell"],
  "contract": {
    "inputPayload": "validated JSON args",
    "formulaReadback": "before/after computed Summary values",
    "errorShape": "{ ok: false, error: string }"
  },
  "writeResult": {
    "editedCell": "Inputs!B3",
    "checks": {
      "formulasPersisted": true,
      "restoredMatchesAfter": true,
      "expectedArrChanged": true
    }
  }
}

TypeScript service shape

Expose narrow WorkPaper functions from a Node service and let CrewAI call them over HTTP, a queue, or any other app-owned transport:

import { z } from 'zod'

const setInputCellInputSchema = z.object({
  sheetName: z.literal('Inputs'),
  address: z.string().regex(/^[A-Z]+[1-9][0-9]*$/),
  value: z.union([z.string(), z.number(), z.boolean(), z.null()]),
})

export function runCrewAiWorkPaperTool(payload: unknown) {
  const args = setInputCellInputSchema.safeParse(payload)
  if (!args.success) {
    return {
      ok: false,
      error: args.error.issues.map((issue) => issue.message).join('; '),
    }
  }

  const result = setWorkPaperInputCell(args.data)
  return {
    ok: true,
    result,
  }
}

The WorkPaper function behind setWorkPaperInputCell should build or load the workbook, write one validated input, read dependent formulas before and after the edit, and return a plain JSON result. The agent should receive evidence, not just an “updated” string.

What to copy

• Validate agent-generated JSON before writing to the workbook.
• Return the edited cell, before/after formula values, and persistence checks.
• Keep the tool contract small enough for a CrewAI task to reason about.
• Do not require CrewAI for normal bilig usage; the same WorkPaper functions also work from Node services, queues, tests, and other agent frameworks.

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