Pieces

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.

Install a piece

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

pnpm add @frogbotai/piece-google-sheets

Create an instance and select tools

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. 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 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 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.

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. Set upload size limits appropriate for your deployment. Without a marked collection, those actions fail when they run:

[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:

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. Use the identity-only createGoogle factory for Google sign-in. 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.

Start here

Basics

Managing Data

Features

Ecosystem

Deployment

Install a piece

Create an instance and select tools

Factory options

Keep tool sets focused

Network access

File output

Credentials and linked accounts

Gmail verification

​Install a piece

​Create an instance and select tools

​Factory options

​Keep tool sets focused

​Network access

​File output

​Credentials and linked accounts

​Gmail verification

Install a piece

Create an instance and select tools

Factory options

Keep tool sets focused

Network access

File output

Credentials and linked accounts

Gmail verification