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

# Agent tools

> Use Google Workspace agent tools in Ravenna rules to create and manage users, handle group membership, reset MFA and passwords, manage email aliases, and transfer files during offboarding.

Google Workspace provides agent tools for identity, group, and mailbox operations. Reference them in <Tooltip headline="Agent rules" tip="Natural language instructions defining agent behavior" cta="Learn about agent rules" href="/documentation/automate/agents/configure#rules">agent rules</Tooltip> using @ mentions so your agent can create accounts, adjust access, reset credentials, and hand off data without a handoff.

Every tool listed here mirrors the [Google Workspace workflow action](/integrations/google-workspace/workflows) of the same name, so the behavior and permissions match what your workflows already do.

***

## Manage users

<AccordionGroup>
  <Accordion title="Create Google User" defaultOpen>
    Creates a new Google Workspace user with a randomly generated password. The password is not returned. Give the user access by running `@Reset Google MFA/Password` with the password scope and `generatePassword: true` once they can receive the credential over Slack DM, or send them through Google's own recovery flow.

    **Tool name:** `@Create Google User`

    **Inputs:**

    * `emailUsername` (required) - username portion of the new primary email, or the full address
    * `firstName`, `lastName` (required)
    * `domain` - domain for the primary email. Defaults to the primary domain on your Google Workspace integration; set it to provision on a secondary verified domain
    * `secondaryEmail`, `recoveryEmail`, `recoveryPhone`
    * `orgUnitPath` - for example `/Engineering`. Defaults to `/`
    * `department`, `jobTitle`, `managerEmail`

    Call `@Check Google Email Availability` first so the agent does not attempt to create an account on an address already in use.
  </Accordion>

  <Accordion title="Suspend Google User">
    Suspends a Google Workspace user so they can no longer sign in to any Google service. Use it for offboarding, security incident response, or extended-leave lockouts.

    **Tool name:** `@Suspend Google User`
  </Accordion>

  <Accordion title="Restore Google User">
    Unsuspends a previously suspended user, restoring access to every Google service. Use it when someone returns from leave or after a security review clears the account.

    **Tool name:** `@Restore Google User`
  </Accordion>

  <Accordion title="Reset Google MFA/Password">
    Resets multi-factor authentication, the password, or both, in one call. A password reset always requires the user to choose a new password at next sign-in. By default the tool also generates a temporary password and delivers it to the user in a private Slack DM, so it never appears in the ticket.

    **Tool name:** `@Reset Google MFA/Password`

    **Inputs:**

    * `userEmail` - the target user
    * `scope` - `mfa`, `password`, or `both`
    * `generatePassword` - defaults to `true` for password resets. Set it to `false` when the user cannot receive a Slack DM, so Google's own recovery flow takes over instead
    * `signUserOut` - optional. Signs the user out of every active session

    If the temporary password cannot be delivered privately, the tool tells the agent to rerun with `generatePassword` set to `false`.
  </Accordion>
</AccordionGroup>

<Note>
  Any signed-in member can trigger these tools, including for another person. To limit who can reset someone else, set **Requires approval** on the tool in the rule, or scope the rule to the people who should use it.
</Note>

***

## Manage email addresses

<AccordionGroup>
  <Accordion title="Check Google Email Availability">
    Checks whether an email address is already in use as a primary email or alias in Google Workspace. Have the agent call this before `@Create Google User` or `@Create Email Alias` so it can offer a different address instead of failing on a conflict.

    **Tool name:** `@Check Google Email Availability`

    **Output:**

    * `isAvailable` - `true` when the address is free
    * `reason` - explains the conflict when unavailable
  </Accordion>

  <Accordion title="Create Email Alias">
    Adds an email alias to an existing user so mail sent to the alias delivers to the same inbox. Use it for role-based addresses (support@, sales@) or brand-specific addresses that route to one person.

    **Tool name:** `@Create Email Alias`

    Pair it with `@Check Google Email Availability` so the agent does not try to add an alias that is already claimed as a primary email or alias somewhere else.
  </Accordion>
</AccordionGroup>

***

## Manage groups

<AccordionGroup>
  <Accordion title="Delete Google Group">
    Deletes a Google Group. Every member loses the membership immediately, so this is a destructive change the agent confirms before running.

    **Tool name:** `@Delete Google Group`

    Identify the group by its `name` or `email`.
  </Accordion>
</AccordionGroup>

<Callout icon="info" color="#6B7280">
  Group creation, listing, membership checks, and member add/remove are also available as agent tools (`@Create Google Group`, `@List Google Groups`, `@Get Google Group Info`, `@Check Google Group Membership`, `@Add Google Group Member`, `@Remove Google Group Member`, `@Update Google Group`). They share the behavior of the matching [workflow actions](/integrations/google-workspace/workflows).
</Callout>

***

## Offboard users

<AccordionGroup>
  <Accordion title="Transfer Google User Files">
    Kicks off an asynchronous transfer of a user's Google Drive and Calendar data to another user. Google processes the transfer in the background and Ravenna returns a transfer ID for tracking. Use it before suspending or deleting an account so nothing is lost.

    **Tool name:** `@Transfer Google User Files`

    **Inputs:**

    * `sourceUserEmail`, `destinationUserEmail` (required)
    * `driveTransferScope` - `ALL` (default), `PRIVATE`, `SHARED`, or `NONE`
    * `transferCalendarEvents` - default `true`
    * `releaseCalendarResources` - release rooms and equipment on future events. Only applies when calendar transfer is enabled.

    At least one of Drive or Calendar must be transferred.

    <Note>
      This tool needs the **Enable User Data Transfer** setting on your Google Workspace integration, plus the `admin.datatransfer` scope on domain-wide delegation. See the [setup guide](/integrations/google-workspace/setup#enable-data-transfer-optional).
    </Note>
  </Accordion>
</AccordionGroup>

<Callout icon="shield" color="#6B7280">
  A tool with no execution policy set runs without asking. When Copilot drafts a rule, it suggests **Requires confirmation** for write tools and **Requires approval** for delete tools, and you can change either per rule. See [tool execution policies](/documentation/automate/agents/configure#tool-execution-policies).
</Callout>

***

## Setup

<Steps>
  <Step title="Connect Google Workspace">
    Follow the [Google Workspace setup guide](/integrations/google-workspace/setup) and confirm the integration is active.
  </Step>

  <Step title="Enable data transfer (optional)">
    Turn on **Enable User Data Transfer** and grant the `admin.datatransfer` scope on domain-wide delegation before writing rules that use `@Transfer Google User Files`.
  </Step>

  <Step title="Attach the tools to an agent">
    Open the agent's settings and add the Google Workspace tools you want it to use under **Tools**. An admin has to attach each tool before an agent or rule can call it.
  </Step>

  <Step title="Write a rule">
    Reference the tools with @ mentions in a <Tooltip headline="Agent rules" tip="Natural language instructions defining agent behavior" cta="Learn about agent rules" href="/documentation/automate/agents/configure#rules">rule</Tooltip>, then test it on a real request.
  </Step>
</Steps>

***

## Example rules

<Prompt description="When someone locks themselves out of Google, use @Check Google Email Availability to confirm the address exists, then offer @Reset Google MFA/Password. Reset MFA only when they mention a new device, password only when they forgot it, and both after a suspected compromise. In generatePassword mode, deliver the temporary password through a Slack DM.">
  When someone locks themselves out of Google, use @Check Google Email
  Availability to confirm the address exists, then offer @Reset Google
  MFA/Password. Reset MFA only when they mention a new device, password
  only when they forgot it, and both after a suspected compromise. In
  generatePassword mode, deliver the temporary password through a Slack
  DM.
</Prompt>

<Prompt description="When a manager reports someone is leaving, ask for the source and destination user, then run @Transfer Google User Files with driveTransferScope ALL and transferCalendarEvents true. After the transfer ID comes back, run @Suspend Google User on the source account and confirm both steps in the reply.">
  When a manager reports someone is leaving, ask for the source and
  destination user, then run @Transfer Google User Files with
  driveTransferScope ALL and transferCalendarEvents true. After the
  transfer ID comes back, run @Suspend Google User on the source
  account and confirm both steps in the reply.
</Prompt>

***

## Best practices

* **Check before you create.** Pair `@Check Google Email Availability` with `@Create Google User` and `@Create Email Alias` so the agent picks up conflicts before it tries to write.
* **Transfer, then suspend.** Run `@Transfer Google User Files` before `@Suspend Google User` during offboarding. Suspended users cannot start a transfer.
* **Deliver temporary passwords privately.** When you use `@Reset Google MFA/Password` in `generatePassword` mode, have the rule send the password through a private Slack DM instead of putting it in the ticket.
* **Gate the destructive tools.** Put `@Delete Google Group`, `@Suspend Google User`, and any write in `generatePassword` mode behind **Requires approval** in rules an agent can reach on its own.

<Callout icon="link" color="#6B7280">
  Learn more about [configuring agents](/documentation/automate/agents/configure) and [Google Workspace workflow actions](/integrations/google-workspace/workflows).
</Callout>


## Related topics

- [Agent tools](/integrations/iru/agent-tools.md)