Oxagen Docs

How Oxagen agents author Google Sheets through a vendor-neutral SheetSpec — typed headers, formatted cell ranges, charts from a typed ChartSpec, and PDF export.

The spreadsheet surface is the agent's tabular output channel. An agent composes a typed SheetSpec — header row, initial body matrix, column formats — and the active provider materialises it as a Google Sheet. The provider contract lives in packages/oxagen/oxagen/documents/; the agent never imports a vendor SDK and never sees raw OAuth credentials.

The `SheetSpec` shape

A SheetSpec is a Pydantic model in oxagen.documents.specs. Every spec defines exactly one starter sheet — additional sheets are added through sheets.write_range calls with a different A1 prefix.

Field	Meaning
`title`	Spreadsheet title (also the file name in Drive).
`header_row`	List of column labels. Bolded and frozen by the provider.
`body_rows`	Optional starter rows — a 2-D matrix of cell values.
`column_formats`	Per-column type hint (`number`, `currency`, `date`, `percent`, `text`) — drives Google Sheets number format strings.
`frozen_rows` / `frozen_columns`	How many rows / columns to freeze for scrolling. Defaults to 1 / 0 when `header_row` is set.

Capability surface

Capability	Credits	What it does
`sheets.create_from_spec`	5	Materialise a `SheetSpec` as a new Google Sheet. Returns `(external_id, external_url, kind='sheet')`.
`sheets.append_rows`	2	Append a 2-D matrix of cell values to the bottom of the first sheet. Idempotent against an `Idempotency-Key` header.
`sheets.write_range`	2	Write a 2-D matrix into an explicit A1 range (e.g. `Sheet1!A1:C3`). Used by the agent when it needs precise placement instead of "append to bottom".
`sheets.insert_chart`	2	Insert a chart from a typed `ChartSpec` — line, bar, scatter, pie, or column. References a data range plus the series / category columns.
`sheets.export_pdf`	3	Render the spreadsheet to PDF. Lands as a sibling row in `app.documents`.
`sheets.share`	1	Grant access at the chosen role.

The `ChartSpec` shape

{
  "type": "line",
  "data_range": "Sheet1!A1:D52",
  "category_column": 0,
  "series": [
    { "column": 1, "label": "Active workspaces" },
    { "column": 2, "label": "New signups" }
  ],
  "title": "Weekly signups vs active",
  "anchor_cell": "F2"
}

type is one of line / bar / column / scatter / pie. category_column and series[].column are zero-indexed positions inside data_range. anchor_cell is where the chart's top-left lands.

Calling it

curl -X POST https://api.oxagen.ai/v1/cap/sheets.create_from_spec \
  -H "Authorization: Bearer $OXAGEN_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
        "spec": {
          "title": "Q2 pipeline",
          "header_row": ["Account", "Stage", "ARR (USD)", "Close date"],
          "column_formats": ["text", "text", "currency", "date"],
          "body_rows": [
            ["Acme",      "Negotiate", 120000, "2026-06-15"],
            ["Globex",    "Close-won",  84000, "2026-05-22"]
          ]
        }
      }'

sheets.append_rows and sheets.write_range take the returned external id (or the canonical app.documents.id) and follow up with cell-level edits.

Branding

When the workspace has a default BrandKit, the provider maps its palette to the header row's fill and font colour, and its typography to the default font for the sheet. Charts inserted via sheets.insert_chart pick up the kit's accent palette in series order. See Brand kits.

Storage and provenance

Column	Value
`kind`	`uploaded`
`extension`	`.gsheet`
`mime_type`	`application/vnd.google-apps.spreadsheet`
`source`	`agent_generated`
`provider`	`google`
`external_id`	Google Drive file id
`external_url`	Sheets viewer URL
`generated_by_run_id`	The agent run that produced the sheet

PDF exports land in app.documents as a sibling with parent_document_id pointing at the source spreadsheet. See Artifact storage.

Permissions

The provider uses the workspace's Google Workspace connection. Tokens are short-lived and never surface in agent context. A workspace without a connected Google account that calls sheets.* receives a structured 409 missing_connection.

Audit

Each generation writes an audit.event row with action='sheet.created' (or 'sheet.row.appended' / 'sheet.range.written' / 'sheet.chart.inserted'), chained to the workspace's audit stream. See Events, triggers, and audits.

Artifacts overview · Document generation · Slides · PDF generation

Spreadsheets