Skip to main content

Docs

View as Markdown

Exposes the Google Docs API v1 as agent tools: read a document's text; create documents; append and replace text; insert inline images and tables; and run arbitrary batchUpdate requests (styling, named ranges, positioned inserts, deletes).

What it does​

An agent-invocable tool node — no data flows through lanes. Each operation is a @tool_function an agent calls on demand. Operational targets (documentId) are always tool-call parameters, never node config. Outputs are cleaned shapes (documentId, title, revisionId, body_text, replies_count, occurrencesChanged), not raw API JSON.

Configuration​

FieldNotes
google.authTypeservice (service account) or user (OAuth).
google.serviceKey / google.adminEmailService account JSON key; adminEmail enables domain-wide delegation (impersonate that user).
google.oAuthButton / google.userTokenUser OAuth: sign in to populate the access token.
docs.accessreadonly or write (default). Resolved by the shared DOCS spec in core/google_access.py; scopes are never hand-entered.

Access tiers → scopes​

TierScopeCapability
readonlydocuments.readonlyread document text + metadata only
writedocumentsfull read/write (default)

There are no destructive gate flags. Permanent document deletion is a Drive operation and lives in tool_drive.

Tools​

  • Read: document_get — returns {documentId, title, revisionId, body_text}, where body_text is the concatenated plain text of the paragraph text runs. Long documents are capped at 50,000 characters and flagged with truncated: true. Works at the readonly tier.
  • Write: document_create (create a document, optionally seeding initial body text via a follow-up insertText), batch_update (the catch-all: pass the full Docs batchUpdate request list).
  • Convenience wrappers (write) over batch_update, so an agent needn't do index math:
    • text_append — append text at the end of the body (insertText at endOfSegmentLocation).
    • text_replace — replace all occurrences of a string (replaceAllText); matchCase defaults to false. Returns occurrencesChanged.
    • image_insert — insert an inline image at the end of the body (insertInlineImage); the uri must be a public https:// URL. Optional width/height in points (PT).
    • table_insert — insert an empty rows×columns table at the end of the body (insertTable); rows is clamped to 1..1000 and columns to 1..25.
  • Diagnostics: check_connection probes the Docs API with a live call; for user OAuth it also verifies that granted scopes cover the configured access tier (service-account auth has no per-user scope grant to check).

The entire Docs v1 surface is documents().get / create / batchUpdate; the wrappers are conveniences over batch_update.

Setup​

Authenticate with either a Google service account (google.serviceKey JSON, optionally google.adminEmail for domain-wide delegation) or user OAuth (click sign-in to populate google.userToken). The Google Docs API must be enabled on the Google Cloud project backing the credential.

Limits​

  • Export is not a Docs operation. Exporting a document to PDF or .docx is a Drive export, not a Docs API call — use tool_drive's file_export (issue #1056), not this node.
  • document_get's body_text is capped at 50,000 characters (truncated: true when the document is longer) and covers paragraph text runs only — table cells, headers/footers, and footnotes are not concatenated. For full structure use batch_update reads or the raw document.
  • batch_update request bodies follow Google's Docs batchUpdate limits.
  • Rate limits are per Google project; the node retries 429/5xx with exponential backoff.

Examples​

An agent creates a document, appends text, then inserts a table:

document_create { "title": "Weekly Report", "text": "Summary\n" }
text_append     { "documentId": "1AbC...", "text": "\nMetrics below:\n" }
table_insert    { "documentId": "1AbC...", "rows": 3, "columns": 2 }

Replace a placeholder throughout a template:

text_replace    { "documentId": "1AbC...", "containsText": "{{name}}",
                  "text": "Ada Lovelace", "matchCase": true }

Upstream docs​

Troubleshooting​

  • Scope / 403 errors: call check_connection; if scopes are missing, disconnect and reconnect the Google account at the required access tier.
  • access is read-only: write operations raise GoogleAccessError; raise docs.access to write.
  • image_insert rejects the URL: the uri must be a public https:// URL Google can fetch (not http://, a data URL, or a private/authenticated link).
Last updated on