> ## Documentation Index
> Fetch the complete documentation index at: https://docs.frogbot.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Pieces

> Add integration actions to FrogBot agents as tools.

Pieces package related actions as FrogBot tools. Create a piece instance, then select its actions as tools on the agents that need them.

For fetch-based search, see [Web search via pieces](https://docs.frogbot.ai/pieces/web-search.md).

## Install a piece

Install the package for the integration you need. Every shipped piece is native and includes its runtime dependencies.

```bash theme={"theme":"tokyo-night"}
pnpm add @frogbotai/piece-google-sheets
```

## Create an instance and select tools

```ts theme={"theme":"tokyo-night"}
import { createGoogleSheets } from '@frogbotai/piece-google-sheets'
import type { FrogBotConfig } from 'frogbot'

export const googleSheets = createGoogleSheets({
  auth: { accessToken: process.env.GOOGLE_SHEETS_ACCESS_TOKEN! }
})

export const pieceConfig = {
  agents: [
    {
      slug: 'assistant',
      model: 'openai/gpt-4o-mini',
      instructions: 'Read QA evidence from spreadsheets without changing it.',
      tools: [googleSheets.findRows, googleSheets.getRows]
    }
  ]
} satisfies Pick<FrogBotConfig, 'agents'>
```

Merge `pieceConfig` into your root config alongside your database, collections, secret, and AI provider configuration. This example uses a developer access token. For user-owned credentials, reuse the factory instances from the [OAuth connection example](https://docs.frogbot.ai/connections/overview.md#configure-linking).

Pieces expose actions directly. Pass only the actions your agent needs in `tools`, or pass the piece to expose all of its actions. Each action can also be called on the server with `{ input, req }` to use the caller's credentials.

Tool slugs combine the instance slug and action name, such as `google-sheets_getRows`, so tools from different pieces do not collide. See [Google actions](https://docs.frogbot.ai/pieces/index.md#google-actions) for the action inventory and key input details.

## Factory options

Every piece factory accepts these options. Each piece page lists the full set for its factory, including the piece's own options.

| Option | Type | Default | Description |
| - | - | - | - |
| `slug` | `string` | The piece slug, such as `google-sheets` | Instance slug. It prefixes tool slugs and names webhook routes. Must be URL-safe. Give each instance of the same piece its own slug. |
| `auth` | The piece's auth input | — | Developer credential, validated against the piece's auth schema when the factory runs. Used when the caller has no [connection](https://docs.frogbot.ai/connections/overview.md) for the piece. Only pieces with an auth schema accept it. |
| `oauth` | `OAuthApp` | — | Your OAuth app. Only pieces with an OAuth recipe accept it. It enables `oauth: true` connection entries and is exposed as `instance.oauth` for reuse. |
| `scopes` | Scope names, or `({ defaultScopes }) => names` | The piece's default scopes | OAuth scopes for this instance, as names from the piece's catalog. A function receives the defaults, `({ defaultScopes }) => [...defaultScopes, 'gmail.labels']`; an array replaces them. The piece's required scopes are always added. Only pieces with an OAuth recipe accept it. See [Connections](https://docs.frogbot.ai/connections/overview.md#choose-oauth-scopes). |

`OAuthApp` takes:

| Option | Type | Default | Description |
| - | - | - | - |
| `clientId` | `string` | Required | OAuth client ID. Must be non-empty. |
| `clientSecret` | `string` | Required | OAuth client secret. Must be non-empty. |

## Keep tool sets focused

Configure only the tools an agent needs. About 20 to 40 tools per agent is a practical ceiling for reliable selection by the model. Prefer explicit action subsets when combining several pieces.

## Network access

The HTTP and GraphQL pieces can request arbitrary URLs without an allowlist. Only assign them to trusted agents and treat access to private network addresses and cloud metadata endpoints as an intentional SSRF risk.

## File output

Pieces that create files buffer the complete result in memory and write it to the collection marked [`file: true`](https://docs.frogbot.ai/upload/files). Set upload size limits appropriate for your deployment. Without a marked collection, those actions fail when they run:

```text theme={"theme":"tokyo-night"}
[frogbot] QR Code requires a files collection. Add an upload collection with `file: true`.
```

A custom piece gets the same check from `filesCollectionSlug`, which returns the marked collection's slug or throws that error:

```ts theme={"theme":"tokyo-night"}
import { filesCollectionSlug } from 'frogbot/pieces'

const collection = filesCollectionSlug(req, 'QR Code')
```

| Argument | Type | Required | Description |
| - | - | - | - |
| `req` | `FrogBotRequest` | Required | The request passed to the action. |
| `piece` | `string` | Required | The piece label shown in the error, such as `'QR Code'`. |

Pass `collection` to `req.frogbot.create` with the file to store it.

## Credentials and linked accounts

Pass developer credentials as factory `auth`. To let users link accounts, configure root `connections` entries with `oauth: true`, `secret: true`, or both supported methods. Factory `oauth` holds your app credentials; it does not enable linking by itself. See [Connections](https://docs.frogbot.ai/connections/overview.md).

Use the identity-only `createGoogle` factory for [Google sign-in](https://docs.frogbot.ai/authentication/sign-in.md). Pass `google.oauth` to `createGoogleSheets`, `createGoogleDrive`, `createGoogleCalendar`, or `createGmail` to share the app credentials. Each product has its own scopes, connection entry, and callback. A Google login or identity connection does not authorize product actions.

## Gmail verification

Gmail uses restricted Google OAuth scopes. Production apps may require Google verification and a security assessment before users outside the test project can connect. Treat Gmail as an optional integration and complete Google's current approval requirements before enabling it.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.