> For the complete documentation index, see [llms.txt](https://docs.kognitos.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.kognitos.com/legacy/legacy-experience/books/reference/googledocs.md).

# Google Docs

{% hint style="info" %}
The following documentation is for **Google Docs v2.10.1** *(BDK)*.
{% endhint %}

## Overview

Google Docs provides collaborative document creation and editing with real-time synchronization across teams. This integration enables automated document generation, content management, and collaborative writing workflows. Enhance documentation processes and improve team collaboration on shared documents.

## Prerequisites

### 1. Required Books

The following Book(s) need to be added to your agent so it can learn and understand the automation procedures defined within them:

* **Google Docs**

#### How to Add the Book(s)

1. Go to **Books** → **All Books**.
2. Search for the name of the book and click on it.
3. Click on <kbd>**Install**</kbd> or <kbd>**Add Connection**</kbd> to add the book to your agent.
4. If adding a connection, you'll be prompted for [**connectivity**](#connectivity) details.

## Connectivity

This section outlines the available methods for connecting to the Book, along with the required configuration details for each.

### Connect using Client Email, Token URI and Private Key

Gets the credentials from the service account keys.

| Label        | Description                                                                     | Type        |
| ------------ | ------------------------------------------------------------------------------- | ----------- |
| Client Email | The client email of the service account registered in the Google Cloud Console. | `text`      |
| Token URI    | The token URI of the Google Cloud Console.                                      | `text`      |
| Private Key  | The private key of the service account registered in the Google Cloud Console.  | `sensitive` |

## Procedures

### to add a paragraph to a (document)

Add a new paragraph to the end of a document.

**Input Concepts**

| Concept                                    | Description                          | Type                                                                  | Required | Default Value |
| ------------------------------------------ | ------------------------------------ | --------------------------------------------------------------------- | -------- | ------------- |
| [`document`](#google-drive-file-reference) | The file to add the paragraph to.    | `google drive file reference`                                         | Yes      | (no default)  |
| `text`                                     | The new paragraph text.              | `text`                                                                | Yes      | (no default)  |
| `style`                                    | Optional. The new paragraph's style. | `enum[HEADING_1, HEADING_2, HEADING_3, NORMAL_TEXT, SUBTITLE, TITLE]` | No       | (no default)  |

**Output Concepts**

| Concept                                    | Description                    | Type                          |
| ------------------------------------------ | ------------------------------ | ----------------------------- |
| [`document`](#google-drive-file-reference) | The document's file reference. | `google drive file reference` |

**Examples**

Add a heading to a document

```generic
add a paragraph to the document where
    the text is "New paragraph"
    the style is "HEADING_1"
```

### to batch update document

Apply raw Google Docs batch update requests to a document.

**Input Concepts**

| Concept                                    | Description                                                     | Type                          | Required | Default Value |
| ------------------------------------------ | --------------------------------------------------------------- | ----------------------------- | -------- | ------------- |
| [`document`](#google-drive-file-reference) | The Google Docs document to update.                             | `google drive file reference` | Yes      | (no default)  |
| `requests json`                            | A JSON array of Google Docs batchUpdate requests.               | `text`                        | Yes      | (no default)  |
| `write control json`                       | Optional. A JSON object with Google Docs writeControl settings. | `text`                        | No       | (no default)  |

**Output Concepts**

| Concept                                  | Description                     | Type                          |
| ---------------------------------------- | ------------------------------- | ----------------------------- |
| [`answer`](#google-drive-file-reference) | The updated document reference. | `google drive file reference` |

**Examples**

Apply a raw batch update request

```generic
batch update the document where
    the requests json is "[{"replaceAllText": {"containsText": {"text": "old", "matchCase": true}, "replaceText": "new"}}]"
```

### to create a google document in a (folder)

Creates a new Google Docs document.

**Input Concepts**

| Concept                                    | Description                                       | Type                            | Required | Default Value |
| ------------------------------------------ | ------------------------------------------------- | ------------------------------- | -------- | ------------- |
| `name`                                     | The name for the new Google Docs document.        | `text`                          | Yes      | (no default)  |
| [`folder`](#google-drive-folder-reference) | The folder to create the Google Docs document in. | `google drive folder reference` | No       | (no default)  |

**Output Concepts**

| Concept                                  | Description                        | Type                          |
| ---------------------------------------- | ---------------------------------- | ----------------------------- |
| [`folder`](#google-drive-file-reference) | the new document's file reference. | `google drive file reference` |

**Examples**

Create a Google Docs document called "Hello World" in a folder

```generic
create a google document in the folder where
    the name is "Hello World"
```

### to find a (document text range) in a document

Find the index range of exact text in a document.

**Input Concepts**

| Concept                                    | Description                                                                         | Type                          | Required | Default Value |
| ------------------------------------------ | ----------------------------------------------------------------------------------- | ----------------------------- | -------- | ------------- |
| [`document`](#google-drive-file-reference) | The Google Docs document to inspect.                                                | `google drive file reference` | Yes      | (no default)  |
| `text`                                     | The exact text to find.                                                             | `text`                        | Yes      | (no default)  |
| `occurrence index`                         | Optional. The zero-based occurrence to return when the text appears multiple times. | `number`                      | No       | 0             |
| `match case`                               | Optional. Whether the match should be case sensitive.                               | `boolean`                     | No       | True          |

**Output Concepts**

| Concept                                     | Description                               | Type                |
| ------------------------------------------- | ----------------------------------------- | ------------------- |
| [`document text range`](#google-docs-range) | The index range where the text was found. | `google docs range` |

**Examples**

Find text in a document

```generic
find a document text range in the document where
    the text is "Customer Name"
```

### to get a (document paragraph) from a document

Resolve the paragraph containing a document index.

**Input Concepts**

| Concept                                    | Description                                    | Type                          | Required | Default Value |
| ------------------------------------------ | ---------------------------------------------- | ----------------------------- | -------- | ------------- |
| [`document`](#google-drive-file-reference) | The Google Docs document to inspect.           | `google drive file reference` | Yes      | (no default)  |
| `index`                                    | The document index contained in the paragraph. | `number`                      | Yes      | (no default)  |

**Output Concepts**

| Concept                                        | Description                          | Type                    |
| ---------------------------------------------- | ------------------------------------ | ----------------------- |
| [`document paragraph`](#google-docs-paragraph) | The paragraph containing that index. | `google docs paragraph` |

**Examples**

Get the paragraph containing an index

```generic
get a document paragraph from the document where
    the index is 10
```

### to get a (document) from *docs*

Get the full Google Docs document.

**Input Concepts**

| Concept                                    | Description                           | Type                          | Required | Default Value |
| ------------------------------------------ | ------------------------------------- | ----------------------------- | -------- | ------------- |
| [`document`](#google-drive-file-reference) | The Google Docs document to retrieve. | `google drive file reference` | Yes      | (no default)  |

**Output Concepts**

| Concept                             | Description                   | Type                   |
| ----------------------------------- | ----------------------------- | ---------------------- |
| [`document`](#google-docs-document) | The full normalized document. | `google docs document` |

**Examples**

Get the full document

```generic
get a document from docs where
    the document is the document
```

### to get some (document comments) from a document

Get comments and replies for a Google Docs document.

**Input Concepts**

| Concept                                    | Description                                                  | Type                          | Required | Default Value |
| ------------------------------------------ | ------------------------------------------------------------ | ----------------------------- | -------- | ------------- |
| [`document`](#google-drive-file-reference) | The Google Docs document whose comments should be retrieved. | `google drive file reference` | Yes      | (no default)  |

**Output Concepts**

| Concept                                     | Description            | Type                  |
| ------------------------------------------- | ---------------------- | --------------------- |
| [`document comments`](#google-docs-comment) | The document comments. | `google docs comment` |

**Examples**

Get the document comments

```generic
get some document comments from the document
```

### to get some (document tables) from a document

Extract the table structures and cell text from a document.

**Input Concepts**

| Concept                                    | Description                          | Type                          | Required | Default Value |
| ------------------------------------------ | ------------------------------------ | ----------------------------- | -------- | ------------- |
| [`document`](#google-drive-file-reference) | The Google Docs document to inspect. | `google drive file reference` | Yes      | (no default)  |

**Output Concepts**

| Concept                                 | Description                       | Type                |
| --------------------------------------- | --------------------------------- | ------------------- |
| [`document tables`](#google-docs-table) | The tables found in the document. | `google docs table` |

**Examples**

Get the document tables

```generic
get some document tables from the document
```

### to get some (document text blocks) from a document

Get the document paragraph text with document indexes.

**Input Concepts**

| Concept                                    | Description                          | Type                          | Required | Default Value |
| ------------------------------------------ | ------------------------------------ | ----------------------------- | -------- | ------------- |
| [`document`](#google-drive-file-reference) | The Google Docs document to inspect. | `google drive file reference` | Yes      | (no default)  |

**Output Concepts**

| Concept                                           | Description                                          | Type                     |
| ------------------------------------------------- | ---------------------------------------------------- | ------------------------ |
| [`document text blocks`](#google-docs-text-block) | The document text blocks with start and end indexes. | `google docs text block` |

**Examples**

Get the document text blocks

```generic
get some document text blocks from the document
```

### to insert a heading in a document

Insert a heading at the end of a document.

**Input Concepts**

| Concept                                    | Description                           | Type                                                                  | Required | Default Value                                                                  |
| ------------------------------------------ | ------------------------------------- | --------------------------------------------------------------------- | -------- | ------------------------------------------------------------------------------ |
| [`document`](#google-drive-file-reference) | The Google Docs document to update.   | `google drive file reference`                                         | Yes      | (no default)                                                                   |
| `text`                                     | The heading text.                     | `text`                                                                | Yes      | (no default)                                                                   |
| `style`                                    | Optional. The heading style to apply. | `enum[HEADING_1, HEADING_2, HEADING_3, NORMAL_TEXT, SUBTITLE, TITLE]` | No       | {'class\_name': 'ParagraphStyle', 'name': 'HEADING\_1', 'value': 'HEADING\_1'} |

**Output Concepts**

| Concept                                  | Description                     | Type                          |
| ---------------------------------------- | ------------------------------- | ----------------------------- |
| [`answer`](#google-drive-file-reference) | The updated document reference. | `google drive file reference` |

**Examples**

Insert a heading in a document

```generic
insert a heading in the document where
    the text is "Executive Summary"
    the style is "HEADING_1"
```

### to overwrite a document

Replace the main body content of a document.

**Input Concepts**

| Concept                                    | Description                            | Type                          | Required | Default Value |
| ------------------------------------------ | -------------------------------------- | ----------------------------- | -------- | ------------- |
| [`document`](#google-drive-file-reference) | The Google Docs document to overwrite. | `google drive file reference` | Yes      | (no default)  |
| `content`                                  | The new document body text.            | `text`                        | Yes      | (no default)  |

**Output Concepts**

| Concept                                  | Description                     | Type                          |
| ---------------------------------------- | ------------------------------- | ----------------------------- |
| [`answer`](#google-drive-file-reference) | The updated document reference. | `google drive file reference` |

**Examples**

Overwrite a document

```generic
overwrite the document where
    the content is "Hello world"
```

### to replace text in a document

Replace exact text everywhere it appears in a document.

**Input Concepts**

| Concept                                    | Description                                | Type                          | Required | Default Value |
| ------------------------------------------ | ------------------------------------------ | ----------------------------- | -------- | ------------- |
| [`document`](#google-drive-file-reference) | The Google Docs document to update.        | `google drive file reference` | Yes      | (no default)  |
| `old text`                                 | The exact text to replace.                 | `text`                        | Yes      | (no default)  |
| `replacement text`                         | The text that should replace the old text. | `text`                        | Yes      | (no default)  |

**Output Concepts**

| Concept                                  | Description                     | Type                          |
| ---------------------------------------- | ------------------------------- | ----------------------------- |
| [`answer`](#google-drive-file-reference) | The updated document reference. | `google drive file reference` |

**Examples**

Replace placeholder text in a document

```generic
replace text in the document where
    the old text is "{{customer_name}}"
    the replacement text is "Acme"
```

## Concepts

### Google drive file reference

Contains all information required to identify a file in Google Drive.

| Field Name                 | Description                   | Type           |
| -------------------------- | ----------------------------- | -------------- |
| `id`                       | The id of the file            | `text`         |
| `file_name`                | The name of the file          | `text`         |
| [`parents`](#list-of-text) | The ids of the parent folders | `list of text` |

### Google drive folder reference

Contains all information required to identify a folder in Google Drive.

| Field Name                 | Description                   | Type           |
| -------------------------- | ----------------------------- | -------------- |
| `id`                       | The id of the folder          | `text`         |
| `folder_name`              | The name of the folder        | `text`         |
| [`parents`](#list-of-text) | The ids of the parent folders | `list of text` |

### Google docs range

A range inside a Google document.

| Field Name    | Description                                | Type             |
| ------------- | ------------------------------------------ | ---------------- |
| `start_index` | The inclusive start index in the document. | `number`         |
| `end_index`   | The exclusive end index in the document.   | `number`         |
| `text`        | Optional text contained in the range.      | `optional[text]` |

### Google docs document

A normalized Google document.

| Field Name                             | Description                            | Type                                      |
| -------------------------------------- | -------------------------------------- | ----------------------------------------- |
| `id`                                   | The document identifier.               | `text`                                    |
| `title`                                | The document title.                    | `text`                                    |
| `revision_id`                          | Optional document revision identifier. | `optional[text]`                          |
| `text`                                 | The flattened document text.           | `optional[text]`                          |
| [`paragraphs`](#google-docs-paragraph) | The document paragraphs.               | `optional[list of google docs paragraph]` |
| [`tables`](#google-docs-table)         | The document tables.                   | `optional[list of google docs table]`     |

### Google docs paragraph

A paragraph extracted from a Google document.

| Field Name        | Description                                | Type             |
| ----------------- | ------------------------------------------ | ---------------- |
| `text`            | The paragraph text.                        | `text`           |
| `start_index`     | The inclusive start index in the document. | `number`         |
| `end_index`       | The exclusive end index in the document.   | `number`         |
| `paragraph_style` | Optional paragraph style name.             | `optional[text]` |

### Google docs table

A table extracted from a Google document.

| Field Name                       | Description            | Type                                      |
| -------------------------------- | ---------------------- | ----------------------------------------- |
| `start_index`                    | The table start index. | `number`                                  |
| `end_index`                      | The table end index.   | `number`                                  |
| [`rows`](#google-docs-table-row) | The table rows.        | `optional[list of google docs table row]` |

### Google docs comment

A Google document comment.

| Field Name                              | Description                             | Type                                          |
| --------------------------------------- | --------------------------------------- | --------------------------------------------- |
| `id`                                    | The comment identifier.                 | `text`                                        |
| `author`                                | The display name of the comment author. | `optional[text]`                              |
| `content`                               | The comment content.                    | `optional[text]`                              |
| `created_time`                          | When the comment was created.           | `optional[text]`                              |
| `modified_time`                         | When the comment was last modified.     | `optional[text]`                              |
| `resolved`                              | Whether the comment is resolved.        | `optional[boolean]`                           |
| [`replies`](#google-docs-comment-reply) | The replies to the comment.             | `optional[list of google docs comment reply]` |

### Google docs comment reply

A reply to a Google document comment.

| Field Name      | Description                           | Type             |
| --------------- | ------------------------------------- | ---------------- |
| `id`            | The reply identifier.                 | `text`           |
| `author`        | The display name of the reply author. | `optional[text]` |
| `content`       | The reply content.                    | `optional[text]` |
| `created_time`  | When the reply was created.           | `optional[text]` |
| `modified_time` | When the reply was last modified.     | `optional[text]` |

### Google docs text block

A text block extracted from a Google document.

| Field Name        | Description                                | Type             |
| ----------------- | ------------------------------------------ | ---------------- |
| `text`            | The text content.                          | `text`           |
| `start_index`     | The inclusive start index in the document. | `number`         |
| `end_index`       | The exclusive end index in the document.   | `number`         |
| `paragraph_style` | Optional paragraph style name.             | `optional[text]` |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.kognitos.com/legacy/legacy-experience/books/reference/googledocs.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.