Gmail
On this page
Purpose
Gmail runs actions from a Composio-connected Google account. Agent Core can use the enabled Gmail tools, or a normal flow can run one selected action.
When to use it
- Search or fetch messages.
- Draft or send an email.
- Organize messages with labels or work with attachments when the selected action supports them.
Required setup
- Create a Composio project API key in Composio Settings > Project Settings > API Keys. Add it in the component or select a saved Arkus Credential. Never put it in prompts, examples, or images.
- Use the component authorization flow to connect the Gmail account. This provider grant is separate from the Composio key. The auth config chooses OAuth or API-key authentication and requested scopes. A workspace or organization administrator may need to approve permissions.
- When the connected account is active, Arkus loads available actions. Selected actions become separate Agent tools. The Gmail toolkit page shows the catalog beyond this guide. Actions can vary by connected account and the toolkit version pinned by Arkus. The examples below are not exhaustive.
- Missing actions? Check the Composio key, connected-account status, requested scopes, and administrator approval. Then reconnect or refresh.
How to use it
Tool Mode
- Add Gmail, select the saved Composio Credential, and complete the account connection.
- Enable Tool Mode, keep only the Actions the Agent needs, and connect the tool output to Agent Core.
- Test a read-only action before enabling actions that send or change mail.
Normal mode
- Select one Action and provide its inputs.
- Connect the DataFrame output to the next step.
Configuration
| Setting | What it controls | Recommended starting point |
|---|---|---|
| Composio API Key | Connects Arkus to Composio and loads the action schema. | Select a saved Credential, not an inline key. |
| Action | Chooses one available Gmail action in normal mode. | Start with search or fetch. |
| Auth Mode | Appears when the connected toolkit requires an authentication choice. | Use the mode required by the authorized account. |
| Actions | Selects loaded actions that become separate Agent tools in Tool Mode. Builder can curate any relevant subset. Without a selection or component default, Arkus starts with the first five fetched actions. | Review the initial set and keep only the actions the Agent needs. |
| Entity ID | Identifies the editor-side Composio user. Deployed flows use the authorized owner instead. | Leave the default default value in normal Builder use. |
Expected result
Tool Mode gives Agent Core the enabled Gmail tools. Normal mode returns a DataFrame. Send results include message and thread identifiers when the provider returns them. A deployed flow requires a saved owner Composio Credential and exactly one active owner account. If the account is missing, disabled, or ambiguous, Arkus asks the owner to reconnect before execution. Authorization failures during an action return a provider error.
Reference details
The available actions are not a fixed catalog. Keep destructive or mailbox-changing actions out of an Agent unless the workflow needs them and you have tested them with the intended account.
Works well with
Connect Gmail in Tool Mode to Agent Core's tools input. Send the normal-mode DataFrame to Parser or Type Convert when the next step needs a structured value.