# Attach or update an agent MCP server
Source: https://docs.gumloop.com/api-reference/agents/attach-agent-mcp-server
put /agents/{agent_id}/mcp-servers/{server_id}
Attach an MCP server (connector) to an agent, or update its configuration if it's already attached (upsert).
The `server_id` is validated against the caller's MCP catalog. Catalog identity fields (`type`, `server_id`, `secret_id`, `mcp_server_url`) always come from the catalog and cannot be spoofed via the request body — the body carries only free-form connector configuration (e.g. approval mode, tool restrictions); any identity keys in it are ignored.
Attach may succeed before OAuth is completed; `auth_status` reflects the catalog's authentication state.
# Create agent
Source: https://docs.gumloop.com/api-reference/agents/create-agent
post /agents
Create a new agent. The authenticated caller must have permission to create agents on the target team.
# Detach an agent MCP server
Source: https://docs.gumloop.com/api-reference/agents/detach-agent-mcp-server
delete /agents/{agent_id}/mcp-servers/{server_id}
Detach an MCP server (connector) from an agent. This is idempotent — detaching a server that isn't attached returns `detached: false` rather than an error.
# List agent MCP servers
Source: https://docs.gumloop.com/api-reference/agents/list-agent-mcp-servers
get /agents/{agent_id}/mcp-servers
List the MCP servers (connectors) attached to an agent. Sensitive fields such as `secret_id` and `mcp_server_url` are scrubbed from the response.
# List agent versions
Source: https://docs.gumloop.com/api-reference/agents/list-agent-versions
get /agents/{agent_id}/versions
List the immutable versions of an agent, newest first. Each entry is a point-in-time snapshot of the agent's configuration.
Requires configuration access on the agent — callers limited to using the agent (no configuration access) get a `403`.
# List agents
Source: https://docs.gumloop.com/api-reference/agents/list-agents
get /agents
List agents the caller has access to. Filter by team, search by name, or narrow to agents that use a specific tool or trigger. Results can be sorted with `sort_order` and paginated by sending `page_size` and/or `cursor`.
# Retrieve agent
Source: https://docs.gumloop.com/api-reference/agents/retrieve-agent
get /agents/{agent_id}
Retrieve a single agent by ID.
In addition to regular agent IDs, `agent_id` accepts the reserved aliases `gumball` (your personal Gumball agent) and `analytics` (your analytics agent) on all agent-scoped endpoints. The alias resolves to your own copy of the platform agent, creating it on first use, and responses report the alias back as the agent's `id`.
# Retrieve agent version
Source: https://docs.gumloop.com/api-reference/agents/retrieve-agent-version
get /agents/{agent_id}/versions/{version_id}
Retrieve one immutable agent version: its full configuration (`composition`) plus the structured `changes` relative to the version before it. Use it to export an agent's configuration or to audit what changed between versions.
`changes` is `null` for the first version of an agent, since there is no predecessor to diff against. Versions created before attachment snapshots were recorded report `composition.complete: false` (and `changes.attachment_changes_complete: false`); their `skill_ids` and `knowledge_sources` are `null` rather than empty. Skill file contents are never included, and this endpoint is read-only — it cannot restore or deploy a version.
Requires configuration access on the agent — callers limited to using the agent (no configuration access) get a `403`.
# Update agent
Source: https://docs.gumloop.com/api-reference/agents/update-agent
patch /agents/{agent_id}
Update an existing agent. Only fields included in the request body are changed; omitted fields are left untouched.
This endpoint edits document fields only. To attach or detach skills, use [`PATCH /agents/{agent_id}/skills`](/api-reference/agents/update-agent-skills); to manage MCP servers, use the [agent MCP server endpoints](/api-reference/agents/attach-agent-mcp-server).
**`is_active: false` is not a pause switch.** It retires the agent: the agent disappears from `GET /agents`, and both `GET` and `PATCH /agents/{agent_id}` return `404` afterwards, so you cannot set it back to `true` through the API. To stop an agent from running on its own while keeping it fully reachable, disable its [triggers](/core-concepts/agent_triggers#managing-active-triggers) instead.
# Attach or detach agent skills
Source: https://docs.gumloop.com/api-reference/agents/update-agent-skills
patch /agents/{agent_id}/skills
Attach and/or detach skills on an agent using deltas. This is **not** a replace-list: skills you don't mention are left untouched.
- The operation is idempotent. Re-attaching a skill that's already attached (or detaching one that isn't) is reported under `already_attached` / `already_detached` rather than failing.
- A skill ID may not appear in both `attach` and `detach`.
- Up to 100 unique skill IDs total (`attach` + `detach`) per request.
- Attaching requires `INVOKE` permission on the skill. Detaching is permissive so stale attachments can always be removed.
# Download artifact
Source: https://docs.gumloop.com/api-reference/artifacts/download-artifact
get /artifacts/{artifact_id}/download
Returns a signed download URL for an artifact, plus its filename, media type, and size. Follow `download_url` to fetch the file bytes.
# List artifacts
Source: https://docs.gumloop.com/api-reference/artifacts/list-artifacts
get /agents/{agent_id}/artifacts
List artifacts (files) produced by an agent. Optionally scope to a specific session, search by filename, sort, and paginate. Deleted files are excluded from the results.
# Authentication
Source: https://docs.gumloop.com/api-reference/authentication
The Gumloop API supports two authentication methods. Both grant the same permissions and work on every endpoint — pick whichever matches how your app gets the credential.
## API key
For scripts and integrations you control end to end. Generate one from the [Connectors page](https://www.gumloop.com/settings/profile/connectors?view=connected\&search=Gumloop+API+Key), then pass it as a bearer token.
```bash theme={"dark"}
curl https://api.gumloop.com/api/v1/start_agent \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"user_id": "xxxxxxxxxxxx", "gummie_id": "xxxxxxxxxxxx", "message": "Hello"}'
```
API keys require the [Pro plan or above](https://www.gumloop.com/pricing).
### Personal vs Team keys
Gumloop offers two flavors of API key, selectable when you generate one.
| | Personal key | Team key |
| - | - | - |
| Acts as | The owning user only | Any team member (set `user_id` per request) |
| Default credentials | The user's personal credentials | The credentials configured per workflow step (`Personal Default` or `Team Default`) |
| Use when | Solo use, local development | Team automations, server-to-server, CI/CD |
When a request includes `project_id`, each workflow step's *Credentials to use* setting decides whether the run uses the calling user's personal credentials or the team's credentials.
The API parameter is still named `project_id` for backwards compatibility — it's the same thing the UI now calls your **team** ID.
You can find your `user_id` on the [Profile Settings page](https://www.gumloop.com/settings/profile/general). See [Finding Your User ID](/api-reference/getting-started#finding-your-user-id) for details.
## OAuth 2.0
If you're building an app that other Gumloop users sign in to, use [OAuth 2.0](/api-reference/oauth). Once you've completed the flow and have an access token, pass it the same way:
```bash theme={"dark"}
curl https://api.gumloop.com/api/v1/agents \
-H "Authorization: Bearer ACCESS_TOKEN"
```
# Approve source
Source: https://docs.gumloop.com/api-reference/brain/approve-source
post /brain/sources/{source_id}/approve
Approve a `draft` source. It becomes `active`, the paused estimate run resumes as a real indexing run, and credits are charged. Later uploads index without another approval.
# Create source
Source: https://docs.gumloop.com/api-reference/brain/create-source
post /brain/sources
Create a file-upload source. Only `direct_file_uploads` sources can be created through the API; connected sources such as Notion or Google Drive are set up in the Gumloop app because they need an account connection.
By default the source is `active` and indexes (and bills) each file as soon as it is uploaded. Set `require_approval` to `true` to create it as a `draft` instead: uploads then run a credit estimate, the source owner is notified, and nothing is indexed until [Approve source](/api-reference/brain/approve-source) is called.
# Delete file
Source: https://docs.gumloop.com/api-reference/brain/delete-file
delete /brain/sources/{source_id}/files/{file_id}
Remove a file from the source and from search.
# Delete source
Source: https://docs.gumloop.com/api-reference/brain/delete-source
delete /brain/sources/{source_id}
Delete a source, every file in it, and everything it contributed to search. This cannot be undone.
# Retrieve estimate
Source: https://docs.gumloop.com/api-reference/brain/get-estimate
get /brain/sources/{source_id}/estimate
The latest credit estimate for a source created with `require_approval`. `estimate` is `null` until the first upload has produced a run; poll until `estimate.status` is `paused_for_approval`, then call [Approve source](/api-reference/brain/approve-source). `estimated_credits` is rounded up to the nearest 5 and is an estimate, not a quote.
# Retrieve source
Source: https://docs.gumloop.com/api-reference/brain/get-source
get /brain/sources/{source_id}
Fetch one source the authenticated user can see.
# List files
Source: https://docs.gumloop.com/api-reference/brain/list-files
get /brain/sources/{source_id}/files
List the files in a file-upload source with their indexing status. Each file carries the `sha256` of its bytes, so a client can compare a local folder against the source and upload only what changed.
# List sources
Source: https://docs.gumloop.com/api-reference/brain/list-sources
get /brain/sources
List the [Company Brain](/core-concepts/brain) sources the authenticated user can see: personal sources, plus team and organization sources shared with them. Every source type is listed, including ones connected in the app such as Notion or Google Drive.
# Search Company Brain
Source: https://docs.gumloop.com/api-reference/brain/search
post /brain/search
Run a hybrid (semantic + keyword) search across the knowledge sources indexed in your [Company Brain](/core-concepts/brain) and return the most relevant, ranked snippets with citations.
Results are scoped to what the authenticated user can see: personal sources, plus any team and organization sources shared with them. Requires the Brain feature, which is available on the Pro and Enterprise plans. Each search consumes Gumloop credits.
# Upload files
Source: https://docs.gumloop.com/api-reference/brain/upload-files
post /brain/sources/{source_id}/files
Upload up to 25 files as `multipart/form-data` parts named `files`. Accepted types are PDF, Word, PowerPoint, Excel, and text formats (`.txt`, `.md`, `.html`, `.csv`, `.rtf`), each up to 25 MB.
Indexing starts on its own after the upload: an `active` source indexes and bills immediately, a `draft` source runs a credit estimate instead (see [Retrieve estimate](/api-reference/brain/get-estimate)). Poll [List files](/api-reference/brain/list-files) until each file's `status` is `indexed`.
Files the upload policy refuses (unsupported type, too large, empty) are returned in `rejected` with a `201`; the request is a `400 no_files_accepted` only when every file was refused.
# Import cookies into a browser profile
Source: https://docs.gumloop.com/api-reference/browser-profiles/import-cookies
post /browser-profiles/{profile_id}/cookies
Add sign-in cookies to a browser profile. This is what `gumloop browser import-logins` calls. Send the cookies in Chrome extension (`chrome.cookies.Cookie`) or Chrome DevTools Protocol `Cookie` shape. With `url`, only that site's cookies are kept and the import replaces that site; without it, every site in the payload is imported. Cookies are encrypted with the profile's key before storage and are never returned by any endpoint.
Use `default` as the `profile_id` to import into the owner's default profile, creating it if needed.
# List browser profiles
Source: https://docs.gumloop.com/api-reference/browser-profiles/list-browser-profiles
get /browser-profiles
List the browser profiles you own, or a team's profiles with `team_id`. A browser profile holds the sign-ins an agent's Browser ability uses. Cookie values are never returned; each profile lists its sites and cookie counts.
# Create chat completion
Source: https://docs.gumloop.com/api-reference/chat-completions/create-completion
post /chat/completions
Run one chat completion on any model Gumloop supports (Anthropic, OpenAI, Google Gemini, OpenRouter
routes). The request and response use the OpenRouter chat completions schema, which extends
OpenAI's. An OpenAI-style client works unchanged. OpenRouter's `reasoning`, `plugins`, `provider`,
`modalities` and `image_config` fields are accepted too.
Image-generation models (`gpt-image-*`, `gemini-*-image-preview`) run when `modalities` includes
`"image"` and return image attachments on `choices[0].message.images`. Decision models
(`typesafe/jev-*`) are not chat models. Send those to `POST /decisions`.
### Host
Chat completions are served from the streaming host, `POST https://ws.gumloop.com/api/v1/chat/completions`,
for both `stream: true` and `stream: false`. `api.gumloop.com` does not serve this endpoint. The Python SDK
routes there automatically.
With `stream: true` the response is `text/event-stream` (Server-Sent Events). Each event carries one
`chat.completion.chunk` and the stream ends with `data: [DONE]`. `client.chat.completions.create(..., stream=True)`
yields parsed `ChatStreamChunk` objects.
### Tool calls, images, and `tool_choice`
Send messages in the OpenAI shape and Gumloop translates them for the model's provider (Anthropic, OpenAI, and Google Gemini). Models served through OpenRouter and other OpenAI-compatible providers receive the messages as sent.
- **Tool-result turns**: after the model replies with `finish_reason: "tool_calls"`, append its assistant message (with `tool_calls`) and one `{"role": "tool", "tool_call_id": ..., "content": ...}` message per call, then send the conversation again. Every tool call needs a matching tool message, and every tool message must match a tool call in an earlier assistant message.
- **Images**: user messages accept `image_url` content parts alongside `text` parts. The URL can be an `http(s)` URL or a base64 data URL (`data:image/png;base64,...`). Images must be JPEG, PNG, GIF, or WebP and at most 20 MB. Redirects are not followed when downloading an image.
- **`tool_choice`**: `"auto"` (the default when `tools` are sent), `"none"`, `"required"`, or `{"type": "function", "function": {"name": "..."}}` to force one tool.
- **`developer` messages** are treated like `system` messages.
```json
{
"model": "claude-sonnet-4-5",
"tools": [{"type": "function", "function": {"name": "get_weather", "parameters": {"type": "object", "properties": {"city": {"type": "string"}}}}}],
"messages": [
{"role": "user", "content": [
{"type": "text", "text": "What's the weather where this photo was taken?"},
{"type": "image_url", "image_url": {"url": "https://example.com/photo.jpg"}}
]},
{"role": "assistant", "content": null, "tool_calls": [
{"id": "call_1", "type": "function", "function": {"name": "get_weather", "arguments": "{\"city\": \"Ottawa\"}"}}
]},
{"role": "tool", "tool_call_id": "call_1", "content": "12°C and sunny"}
]
}
```
A request that can't be translated returns `400 invalid_request` with `param` set to the field at fault (for example `messages[3].tool_call_id`). When the provider itself rejects the request (HTTP 400, 404, 413, or 422), the error message relays the provider's reason, prefixed with `The provider rejected the request:`.
### Billing
Each completion charges the caller's credit balance based on token usage (with cache-token semantics per provider) plus a flat 30-credit fee for image-gen calls. Users who configure their own provider API key get a 50% discount.
# Get evaluation config
Source: https://docs.gumloop.com/api-reference/evaluations/get-config
get /agents/{agent_id}/evaluation-config
Retrieve the current evaluation configuration for an agent, including criteria, tags, data points, and sentiment settings.
# Get evaluation metrics
Source: https://docs.gumloop.com/api-reference/evaluations/get-metrics
get /agents/{agent_id}/evaluations/metrics
Returns aggregated grade and tag counts for an agent's evaluations over a time window.
Useful for dashboards and reporting on agent quality trends.
# List evaluations
Source: https://docs.gumloop.com/api-reference/evaluations/list-evaluations
get /agents/{agent_id}/evaluations
Returns a cursor-paginated list of evaluation results for a specific agent, newest first.
Only completed and failed evaluations are returned unless `status` selects another state.
Each evaluation includes the grade, criteria pass/fail results, extracted data points, applied tags, and sentiment analysis.
# Retrieve evaluation
Source: https://docs.gumloop.com/api-reference/evaluations/retrieve-evaluation
get /agents/{agent_id}/evaluations/{evaluation_id}
Retrieve a single evaluation result by ID. The evaluation must belong to the specified agent.
# Run evaluations
Source: https://docs.gumloop.com/api-reference/evaluations/run-evaluations
post /agents/{agent_id}/evaluations/run
Grades up to 200 of the agent's finished sessions with its own evaluation configuration. Grading is asynchronous: each accepted session gets a result with `status: queued`; poll it with `GET /agents/{agent_id}/evaluations/{evaluation_id}` until it is `completed` or `failed`. A new result replaces the previous result for that session.
Sessions are skipped, not rejected, when they are unfinished, incognito, or not owned by this agent (`ineligible`), or already have a queued or running result (`in_flight`, with the existing `result_id`). The caller is charged one credit per queued session. Set `dry_run: true` to see the cost and skips without queuing anything.
Requires edit access on the agent and a plan with evaluations enabled.
# Update evaluation config
Source: https://docs.gumloop.com/api-reference/evaluations/update-config
patch /agents/{agent_id}/evaluation-config
Partially update the evaluation configuration for an agent.
Omitted fields keep their current value. Provided list fields (criteria, tags, data_points) replace that list entirely.
Requires Pro tier or above.
# Download file
Source: https://docs.gumloop.com/api-reference/file-operations/download-file
post /download_file
# Download multiple files
Source: https://docs.gumloop.com/api-reference/file-operations/download-files
post /download_files
# Upload file
Source: https://docs.gumloop.com/api-reference/file-operations/upload-file
post /upload_file
# Upload multiple files
Source: https://docs.gumloop.com/api-reference/file-operations/upload-files
post /upload_files
# Getting started
Source: https://docs.gumloop.com/api-reference/getting-started
Use the Gumloop API to create agents, start chat sessions, and trigger automations programmatically.
The Gumloop API is agent-first: you can create and update [agents](/api-reference/agents/create-agent), start [sessions](/api-reference/sessions/create-session) to chat with them, and use [chat completions](/api-reference/chat-completions/create-completion) from any OpenAI-compatible client. The [Python](/api-reference/sdk/python) and [JavaScript](/api-reference/sdk/javascript) SDKs wrap all of it.
Webhooks, covered next, let an outside service run an agent by calling a URL — no API key, SDK, or polling loop needed.
## Agent webhooks
A [webhook trigger](/core-concepts/agent_triggers#webhook-triggers) gives an agent its own URL. Anything that can send an HTTP `POST` — Stripe, GitHub, a cron job, an internal script — runs the agent by calling it.
On the agent's configuration page, open the **Triggers** section, click **+ Add**, and choose **Webhook**. Give it a name and either a prompt (drop the **Raw JSON** badge where the payload should land) or turn on **Send raw JSON instead of a prompt**.
Gumloop shows the URL as soon as the trigger is created, along with a `curl` example. You can copy it again any time from the trigger's detail panel.
![Trigger created screen showing the webhook URL and a Try it yourself curl example]()
```bash theme={"dark"}
curl -X POST \
'https://api.gumloop.com/trigger_incoming_webhook//' \
-H 'Content-Type: application/json' \
-d '{"customer": {"email": "ada@example.com"}}'
```
### Request & response
| | Behavior |
| - | - |
| **Method** | `POST` only |
| **Auth** | None — the secret is part of the URL, so no API key or header is required |
| **Body** | JSON (parsed even without a `Content-Type: application/json` header), form-encoded data, or raw text |
| **Success** | `200` with `{"success": true}`, returned as soon as the request is accepted |
| **Rejected** | `404` with `{"error": "not_found"}` for an unknown trigger, a deactivated trigger, or a wrong secret — deliberately identical, so a bad URL reveals nothing |
The agent runs in the background, so the response never carries its output. Have the agent report results through a tool (Slack, email, a database write) or check the run in the agent's history.
The webhook URL *is* the credential: anyone holding it can run your agent. Store it like a password, and delete the trigger to retire a URL — a new trigger always gets a fresh one.
## Finding your user ID
Many API endpoints require a `user_id` parameter. You can find your User ID on the [Profile Settings page](https://www.gumloop.com/settings/profile/general), under your email address.
![User ID displayed on the Profile Settings page under your email address]()
Click the copy icon next to your User ID to copy it to your clipboard.
## Authorization
Agent webhooks need no credentials, but the rest of the API does. You can authenticate using one of two methods:
The default method is to include your API key as a query parameter in the URL. This method is simpler and works well for most integrations:
```bash theme={"dark"}
curl -X POST \
https://api.gumloop.com/api/v1/start_agent?api_key=xxxxxxxxxxxx \
-H "Content-Type: application/json" \
-d '{"user_id": "xxxxxxxxxxxxxx", "agent_id": "xxxxxxxxxxxxxx", "message": "Hello"}'
```
Alternatively, you can use the Authorization header with a Bearer token. This method is preferred when you want to keep credentials out of URLs:
```bash theme={"dark"}
curl -X POST \
https://api.gumloop.com/api/v1/start_agent \
-H "Content-Type: application/json" \
-H "Authorization: Bearer xxxxxxxxxxxx" \
-d '{"user_id": "xxxxxxxxxxxxxx", "agent_id": "xxxxxxxxxxxxxx", "message": "Hello"}'
```
All examples in the API reference use the Authorization header method, but you can substitute the API key method in any of them.
# Call MCP tools
Source: https://docs.gumloop.com/api-reference/mcp/call-tool
post /mcp/tools/call
Execute a batch of 1–5 MCP tool calls. Calls run concurrently and each result reports its own `status`. When Gumloop accepts the request, MCP execution failures such as target server authentication, policy blocks, invalid tools, upstream HTTP errors, and connection failures are returned in `results[*].status` and `results[*].error`. Top-level `4xx` responses are reserved for Gumloop request, authentication, and permission failures. `200` covers homogeneous execution outcomes (all calls succeeded or all calls failed); mixed success/failure batches return `207`. If you previously treated non-2xx HTTP statuses as MCP execution failures, update your integration to inspect each result's `status` and `error`.
# Get MCP server prompt
Source: https://docs.gumloop.com/api-reference/mcp/get-prompt
post /mcp/servers/{server_id}/prompts/get
Render one prompt template with arguments and return its messages.
# List MCP server prompts
Source: https://docs.gumloop.com/api-reference/mcp/list-prompts
get /mcp/servers/{server_id}/prompts
Return the prompt templates an MCP server exposes, fetched live from the server. When the server is not `connected`, `prompts` is empty and `gumloop_auth_url` is returned.
# List MCP server resources
Source: https://docs.gumloop.com/api-reference/mcp/list-resources
get /mcp/servers/{server_id}/resources
Return the resources an MCP server exposes, fetched live from the server. When the server is not `connected`, `resources` is empty and `gumloop_auth_url` is returned so the caller can prompt the user to authenticate.
# List MCP servers
Source: https://docs.gumloop.com/api-reference/mcp/list-servers
get /mcp/servers
Return the catalog of MCP servers visible to the caller — Gumloop-hosted (`gumcp_server`), user-deployed Gumstack (`gumstack_server`), and custom (`mcp_server`) — along with each server's connection state.
# List MCP server tools
Source: https://docs.gumloop.com/api-reference/mcp/list-tools
get /mcp/servers/{server_id}/tools
Return the tools exposed by an MCP server. When the server is not in `connected` state, `tools` is empty and `gumloop_auth_url` is returned so the caller can prompt the user to authenticate.
# Read MCP server resource
Source: https://docs.gumloop.com/api-reference/mcp/read-resource
get /mcp/servers/{server_id}/resources/read
Read one resource by `uri`. Each content item is either `text` or a base64 `blob`, never both.
# Retrieve an MCP server
Source: https://docs.gumloop.com/api-reference/mcp/retrieve-server
get /mcp/servers/{server_id}
Return a single MCP server. The response populates `allowed_tool_call_ids` with the tool call IDs the caller is permitted to invoke on this server.
# Create decision
Source: https://docs.gumloop.com/api-reference/models/create-decision
post /decisions
Ask a decision model one or more typed questions about a piece of `state`. The model returns a
probability for each question instead of text. The request and response use the OpenRouter Decisions
schema. Jev (`typesafe/jev-1.13`) is the first decision model. Any model with `is_classifier_model: true`
in `GET /models` works here. Chat models are refused with `model_unavailable`. Send those to
`POST /chat/completions`.
You choose the question ids. The answers come back under the same ids. There are three question types:
- `noul` is a yes/no question. The answer is `noul`, the probability of yes. `criteria.true` and
`criteria.false` are optional descriptions of each side.
- `choice` picks one option from `criteria`, a map of option id to description. A description may be
`null`. The answer is `choice`, `probabilities` over every option, and `confidence`.
- `score` places the state on the ordered rubric in `criteria`, a list with the lowest level first. The
answer is `score` (the weighted position), `probabilities` per level, `legend`, and `confidence`.
`state`, `instructions` and criteria accept a string, a JSON object, or an array. The response `model`
is the exact version the provider served, for example `typesafe/jev-1.13-20260917`. Billing uses the
model you requested. There is no streaming form. The server applies its zero-data-retention provider
policy after any `provider` preferences you send.
### Billing
Each call charges the caller's credit balance from the provider-reported cost, or from the model's token
rate when the provider reports none. A call costs at least one credit, so put every independent question
about one piece of state in a single request.
# List models
Source: https://docs.gumloop.com/api-reference/models/list-models
get /models
List the LLMs and preset model chains available to the caller, grouped for display in a model picker.
# Route a message to a model
Source: https://docs.gumloop.com/api-reference/models/route-model
post /models/route
Ask Gumloop Chew — the model router behind **Auto** — which model it would use for a given
message, and why. Chew is a router, not a model: `router` is always `gumloop-chew`, and the
concrete model it selected is `route.model`.
This endpoint returns a decision only. It does not run the selected model or its fallbacks.
The routing judgement consumes credits and is bounded by the caller's model access.
Omit `models` to use the deduplicated union of Chew's lane chains, not every model the
caller may use. Restricted candidates can appear with `status: "restricted"`; they are never
selected or included in `fallback_models`.
Team scope requires actual team membership, even within the same organization. Personal API
keys and OAuth are supported; this is not team-key-only.
# OAuth 2.0
Source: https://docs.gumloop.com/api-reference/oauth
Gumloop supports OAuth 2.0, which is recommended if you're building an application that other Gumloop users sign in to. The flow follows the standard **authorization code grant with PKCE (S256)** and issues refresh tokens.
## Register an OAuth application
OAuth client registration is currently invite-only.
Email **[support@gumloop.com](mailto:support@gumloop.com)** with your app name, use case, redirect URI(s), and logo. We'll review and reach out with a `client_id`.
## Redirect the user to Gumloop
When authorizing a user, redirect to the authorization endpoint with the correct parameters and scopes.
```http theme={"dark"}
GET https://api.gumloop.com/oauth/authorize
```
| Parameter | Description |
| - | - |
| `client_id` | (required) Client ID from your registered OAuth app |
| `redirect_uri` | (required) One of your app's registered redirect URIs |
| `response_type=code` | (required) Only `code` is supported |
| `scope` | (required) Space-separated list of [scopes](#scopes) |
| `code_challenge` | (required) Your PKCE code challenge |
| `code_challenge_method=S256` | (required) Only `S256` is supported |
| `state` | (optional, recommended) Opaque value echoed back on redirect to prevent CSRF |
### Example
```http theme={"dark"}
GET https://api.gumloop.com/oauth/authorize
?response_type=code
&client_id=YOUR_CLIENT_ID
&redirect_uri=https%3A%2F%2Fyourapp.com%2Foauth%2Fcallback
&scope=gumloop_api
&code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM
&code_challenge_method=S256
&state=SECURE_RANDOM
```
## Handle the redirect
After the user approves your app, Gumloop redirects them back to your `redirect_uri` with the authorization `code` and your `state` in the query string. Always validate that `state` matches the value you sent.
```http theme={"dark"}
GET https://yourapp.com/oauth/callback?code=9a5190f637d8...&state=SECURE_RANDOM
```
## Exchange the code for tokens
Exchange the `code` (plus your PKCE `code_verifier`) for an access token.
```http theme={"dark"}
POST https://api.gumloop.com/oauth/token
Content-Type: application/x-www-form-urlencoded
```
| Parameter | Description |
| - | - |
| `grant_type=authorization_code` | (required) |
| `code` | (required) Authorization code from the previous step |
| `redirect_uri` | (required) Same value sent in the authorize request |
| `client_id` | (required) Your client ID |
| `code_verifier` | (required) The PKCE verifier matching the challenge sent in the authorize request |
### Example
```bash theme={"dark"}
curl -X POST https://api.gumloop.com/oauth/token \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=authorization_code" \
-d "code=9a5190f637d8..." \
-d "redirect_uri=https://yourapp.com/oauth/callback" \
-d "client_id=YOUR_CLIENT_ID" \
-d "code_verifier=YOUR_CODE_VERIFIER"
```
### Response
```json theme={"dark"}
{
"access_token": "...",
"token_type": "Bearer",
"expires_in": 3600,
"scope": "gumloop_api",
"refresh_token": "..."
}
```
## Make API requests
Pass the access token as a bearer header on every request, exactly like an API key:
```bash theme={"dark"}
curl https://api.gumloop.com/api/v1/agents \
-H "Authorization: Bearer ACCESS_TOKEN"
```
## Refresh an access token
When `expires_in` elapses, exchange the refresh token for a new access token.
```http theme={"dark"}
POST https://api.gumloop.com/oauth/token
Content-Type: application/x-www-form-urlencoded
```
| Parameter | Description |
| - | - |
| `grant_type=refresh_token` | (required) |
| `refresh_token` | (required) Refresh token from the previous response |
| `client_id` | (required) Your client ID |
## Revoke a token
```http theme={"dark"}
POST https://api.gumloop.com/oauth/revoke
Content-Type: application/x-www-form-urlencoded
```
| Parameter | Description |
| - | - |
| `token` | (required) The access or refresh token to revoke |
| `client_id` | (required) Your client ID |
## Scopes
| Scope | Grants |
| - | - |
| `gumloop_api` | Call the Gumloop developer API on behalf of the user |
| `userinfo` | Read the user's basic profile (email, name) |
The `gumloop_api` scope requires the authorizing user to be on the [Pro plan or above](https://www.gumloop.com/pricing). Token exchange will fail if the user's account does not meet this requirement.
# Create evaluation
Source: https://docs.gumloop.com/api-reference/organization-evaluations/create-evaluation
post /evaluations
Creates an organization evaluation. A new evaluation has no targets, so it cannot start enabled: set targets with `PUT /evaluations/{evaluation_id}/targets`, then enable it with `PATCH /evaluations/{evaluation_id}`.
Rubric values are validated strictly: an unknown `frequency`, criterion `priority`, `type`, data point `data_type`, or session type, a criterion without `name` and `prompt`, or a duplicate tag name returns `400 invalid_request` with the offending paths in `error.details.fields`.
# Delete evaluation
Source: https://docs.gumloop.com/api-reference/organization-evaluations/delete-evaluation
delete /evaluations/{evaluation_id}
Deletes the evaluation. It stops running and disappears from lists; results it already produced stay attached to their sessions.
# Get evaluation metrics
Source: https://docs.gumloop.com/api-reference/organization-evaluations/get-metrics
get /evaluations/{evaluation_id}/metrics
Grade counts for one evaluation over a trailing window (default 30 days, 1–365).
# Get evaluation options
Source: https://docs.gumloop.com/api-reference/organization-evaluations/get-options
get /evaluation-options
Allowed values for evaluation fields and filters — session types, criterion types and priorities, data point types, frequencies, grades, statuses, target types, skip reasons — plus size limits. Use these instead of hardcoding enums.
# List evaluations
Source: https://docs.gumloop.com/api-reference/organization-evaluations/list-evaluations
get /evaluations
Cursor-paginated list of an organization's evaluations with their targets, coverage, and result rollups. Requires the `organization:manage_evaluations` permission (Enterprise plan).
# List evaluation results
Source: https://docs.gumloop.com/api-reference/organization-evaluations/list-results
get /evaluations/{evaluation_id}/results
Cursor-paginated results for one evaluation across every agent it grades, newest first. Each session appears once with its latest result; queued and in-progress results are included so a run can be followed to completion.
# Retrieve evaluation
Source: https://docs.gumloop.com/api-reference/organization-evaluations/retrieve-evaluation
get /evaluations/{evaluation_id}
Returns one evaluation with its rubric, targets, current coverage, and result rollup.
# Retrieve evaluation result
Source: https://docs.gumloop.com/api-reference/organization-evaluations/retrieve-result
get /evaluations/{evaluation_id}/results/{result_id}
One result, including per-criterion outcomes, extracted data points, and applied tags. Poll this after `POST /evaluations/{evaluation_id}/run` until `status` is `completed` or `failed`.
# Run evaluation on sessions
Source: https://docs.gumloop.com/api-reference/organization-evaluations/run-evaluation
post /evaluations/{evaluation_id}/run
Grades up to 200 existing sessions with this evaluation. Grading is asynchronous: each accepted session gets a result with `status: queued`; poll it with `GET /evaluations/{evaluation_id}/results/{result_id}` until it is `completed` or `failed`.
Sessions are skipped, not rejected, when they are not completed sessions of an agent the evaluation covers (`ineligible`) or already have a queued or running result for this evaluation (`in_flight`, with the existing `result_id`). The caller is charged one credit per queued session. Set `dry_run: true` to see the cost and skips without queuing anything.
# Set evaluation targets
Source: https://docs.gumloop.com/api-reference/organization-evaluations/set-targets
put /evaluations/{evaluation_id}/targets
Replaces the full set of targets — who the evaluation grades. Targets expand to agents live: `organization` covers every agent in the organization, `team` every agent a team owns, `user` a member's personal agents, `agent` one agent. Removing the last target pauses an enabled evaluation; `enabled` in the response reflects that.
# Update evaluation
Source: https://docs.gumloop.com/api-reference/organization-evaluations/update-evaluation
patch /evaluations/{evaluation_id}
Partial update. Only the fields you send change. `config` is merged field by field; a list you send (`criteria`, `tags`, `data_points`) replaces that list wholesale. `description: null` clears the description.
Setting `enabled: true` requires at least one criterion, tag, or data point (`400 organization_evaluation_empty_rubric`) and at least one covered agent (`400 organization_evaluation_no_targets`). Emptying the rubric of an enabled evaluation pauses it.
# Export data
Source: https://docs.gumloop.com/api-reference/organization/export-data
post /export_data
This endpoint allows enterprise organization administrators to create and initiate a comprehensive data export for their organization or specific workspaces.
The export supports six data types:
- **Workflow data** (`data_type: "workflows"`): Includes workflow runs, workbook details, user information, and other organizational data.
- **Agent data** (`data_type: "agents"`): Includes agent configurations, metadata, tools, and creator information.
- **Agent interaction data** (`data_type: "agent_interactions"`): Includes agent interaction data with timestamps, credit costs, trigger types, and message counts.
- **Credit log data** (`data_type: "credit_logs"`): Includes credit transaction history with charges, balances, categories, and user attribution.
- **Interaction evaluation data** (`data_type: "interaction_evaluations"`): Includes one row per completed [evaluation](/core-concepts/evaluations) of a chat, with its grade, call outcome, sentiment, and the model that graded it.
- **Gumstack data** (`data_type: "gumstack"`): Includes Gumstack MCP tool call activity with timestamps, statuses, and latency.
The available `export_fields` depend on the selected `data_type`. See the field descriptions below for details.
**Scoping requirement:** For non-credit-log exports, at least one scoping parameter must be provided: `workspace_ids`, `include_all_workspaces`, `include_personal_workspaces`, or `entity_ids`. Requests that omit all scoping parameters will receive a `400` error.
**Note:** Credit log exports work differently from workflow and agent exports. When `data_type` is `"credit_logs"`, the following parameters are **not applicable** and will be ignored: `export_level`, `workspace_ids`, `include_all_workspaces`, `include_personal_workspaces`, and `entity_ids`. Credit log exports are always scoped to the entire organization. Use `category_filter` to filter by credit log category.
# Get data export status
Source: https://docs.gumloop.com/api-reference/organization/export-status
get /export_status
This endpoint retrieves the status of a data export job and optionally downloads the export file (as CSV) if the export has completed successfully.
Use the `data_export_id` returned by the [Export data](/api-reference/organization/export-data) endpoint to check progress.
# Retrieve audit logs
Source: https://docs.gumloop.com/api-reference/organization/get-audit-logs
get /get_audit_logs
This endpoint retrieves audit logs for all users in an organization for a specified time period.
# Get custom role credit limit
Source: https://docs.gumloop.com/api-reference/organization/get-role-credit-limit
get /organizations/{organization_id}/roles/{role_id}/credit-limit
This endpoint returns the monthly credit limit of one custom role. A `monthly_credit_limit` of `null` means the role sets no limit of its own.
# List organizations
Source: https://docs.gumloop.com/api-reference/organization/list-organizations
get /organizations
Returns the organization the authenticated user belongs to. Use its `id` as `organization_id` on the evaluation endpoints.
# List custom role credit limits
Source: https://docs.gumloop.com/api-reference/organization/list-role-credit-limits
get /organizations/{organization_id}/roles/credit-limits
This endpoint lists every active custom role in an organization together with its monthly credit limit, so external systems can manage credit limits programmatically. A `monthly_credit_limit` of `null` means the role sets no limit of its own. The limit applies to each member of the role individually; when a user belongs to multiple roles, the highest limit across their roles wins.
# Manage custom role users
Source: https://docs.gumloop.com/api-reference/organization/manage-permission-group-users
post /manage_permission_group_users
This endpoint allows organization administrators to add or remove users from a custom role (formerly "permission group"). Adding a user to a role does not remove them from any other role they belong to.
# Manage workspace users
Source: https://docs.gumloop.com/api-reference/organization/manage-workspace-users
post /manage_workspace_users
This endpoint allows organization administrators to add or remove users from a workspace.
# Set custom role credit limit
Source: https://docs.gumloop.com/api-reference/organization/set-role-credit-limit
put /organizations/{organization_id}/roles/{role_id}/credit-limit
This endpoint sets or clears the monthly credit limit of a custom role. The limit applies to each member of the role individually and takes effect immediately: member allowances are recalculated while preserving credits already used in the current billing cycle. Send `"monthly_credit_limit": null` to clear the role-level limit so members revert to the organization default. When a user belongs to multiple roles, the highest limit across their roles wins. Requests that do not change the stored value are no-ops. Changes are recorded in the organization audit trail.
# JavaScript SDK
Source: https://docs.gumloop.com/api-reference/sdk/javascript
For convenience, we have created a Gumloop JavaScript SDK to more easily perform operations like starting an automation and retrieving outputs.
## Installation
```bash theme={"dark"}
npm install gumloop
```
## Usage
```typescript theme={"dark"}
import { GumloopClient } from "gumloop";
// Initialize the client
const client = new GumloopClient({
apiKey: "your_api_key",
userId: "your_user_id",
});
// Run a flow and wait for outputs
async function runFlow() {
try {
const output = await client.runFlow("your_flow_id", {
recipient: "example@email.com",
subject: "Hello",
body: "World",
});
console.log(output);
} catch (error) {
console.error("Flow execution failed:", error);
}
}
runFlow();
```
Optionally add a `project_id` when creating the client if running automations in a workspace:
```typescript theme={"dark"}
const client = new GumloopClient({
apiKey: "your_api_key",
userId: "your_user_id",
projectId: "your_project_id"
});
```
# Python SDK
Source: https://docs.gumloop.com/api-reference/sdk/python
The Gumloop Python SDK ships two clients:
* **`Gumloop`** — the modern resource client used for chat completions, agents, sessions, MCP, skills, artifacts, and teams.
* **`GumloopClient`** — the legacy flows client used to start saved automations and poll for outputs. Emits a `DeprecationWarning` at construction.
Pick `Gumloop` for new code. Use `GumloopClient` only if you need `run_flow` against an existing saved automation.
## Installation
```bash theme={"dark"}
uv add gumloop
```
## Chat completions
`client.chat.completions.create(...)` is an OpenAI-compatible chat surface that routes to every model Gumloop supports (Anthropic, OpenAI, Google Gemini, OpenRouter routes). The streaming variant returns an iterator of `ChatStreamChunk`; the unary variant returns a `ChatResult`.
`model` must be a concrete model. `gumloop-chew` — the [**Auto** router](/core-concepts/ai_models#auto-faq) — picks a model instead of being one. Use `client.models.route(...)` (or `POST /models/route`) to get the model it would choose, then pass that here. Requires a current `gumloop` package that includes the models resource.
```python theme={"dark"}
from gumloop import Gumloop
client = Gumloop(access_token="your_access_token")
result = client.chat.completions.create(
model="claude-sonnet-4-5",
messages=[{"role": "user", "content": "Capital of Canada?"}],
)
print(result.choices[0].message.content)
```
### Streaming
```python theme={"dark"}
for chunk in client.chat.completions.create(
model="claude-sonnet-4-5",
messages=[{"role": "user", "content": "Write a haiku about Toronto."}],
stream=True,
):
delta = chunk.choices[0].delta
if delta.content:
print(delta.content, end="", flush=True)
```
### Structured output
Pass `response_format={"type": "json_schema", "json_schema": {...}}` to constrain the response to a JSON Schema. The SDK accepts the same shape the OpenAI API documents.
```python theme={"dark"}
result = client.chat.completions.create(
model="claude-sonnet-4-5",
messages=[{"role": "user", "content": "Return JSON with the capital of Canada."}],
response_format={
"type": "json_schema",
"json_schema": {
"name": "answer",
"strict": True,
"schema": {
"type": "object",
"properties": {"capital": {"type": "string"}},
"required": ["capital"],
"additionalProperties": False,
},
},
},
)
print(result.choices[0].message.content) # '{"capital":"Ottawa"}'
```
### Image generation
Request an image-generation model such as `gpt-image-2.5-flare` or `gemini-*-image-preview` with `modalities=["image", "text"]`. The response carries image attachments on `choices[0].message.images` as data URLs. Streaming variants emit partial frames natively for OpenAI gpt-image models.
```python theme={"dark"}
result = client.chat.completions.create(
model="gpt-image-2.5-flare",
messages=[{"role": "user", "content": "A red maple leaf on white"}],
modalities=["image", "text"],
image_config={"size": "1024x1024"},
)
for image in result.choices[0].message.images:
print(image.image_url.url[:64], "...")
```
### Tool calling
Pass OpenAI-shape tool definitions; the SDK forwards them unchanged so any LLM that supports function calling can invoke them.
```python theme={"dark"}
result = client.chat.completions.create(
model="claude-sonnet-4-5",
messages=[{"role": "user", "content": "What's the weather in Toronto?"}],
tools=[{
"type": "function",
"function": {
"name": "get_weather",
"description": "Get current weather for a city",
"parameters": {
"type": "object",
"properties": {"city": {"type": "string"}},
"required": ["city"],
},
},
}],
)
for tc in result.choices[0].message.tool_calls or []:
print(tc.function.name, tc.function.arguments)
```
### Bring your own provider key
When the calling user has configured their own provider API key (OpenAI, Anthropic, etc.) in Gumloop, billing follows that account's pricing policy. Usage pricing can waive inference for BYOK; some legacy organizations use a partial discount. See [Credits](/core-concepts/credits). No SDK change is required.
## MCP tools
`client.mcp.execute(...)` returns an `McpExecuteResponse` with one result per tool call. MCP execution failures, such as target server authentication errors or upstream connection failures, are reported on each result instead of being raised as `APIStatusError`. Gumloop request errors, such as missing credentials, invalid request bodies, or endpoint permission failures, can still raise `APIStatusError`.
```python theme={"dark"}
from gumloop import APIStatusError, Gumloop
client = Gumloop(access_token="your_access_token")
try:
response = client.mcp.execute(
server_id="gumloop_slack",
tool_name="slack_send_message",
arguments={"channel": "#general", "text": "Hello from Gumloop"},
)
except APIStatusError as error:
print(f"Gumloop API request failed: {error}")
raise
result = response.results[0]
if result.status != "success":
print(result.error)
else:
print(result.decoded_content)
```
`decoded_content` is a Python SDK convenience property. Raw REST responses include the underlying `content` array.
## Agent versions
Every agent keeps an immutable history of its configuration. `client.agents.list_versions(...)` pages through those snapshots newest-first, and `client.agents.get_version(...)` returns one version's full configuration plus the structured diff against the version before it.
```python theme={"dark"}
from gumloop import Gumloop
client = Gumloop(access_token="your_access_token")
response = client.agents.list_versions("abc123DEFghiJKL", page_size=20)
for version in response.versions:
print(version.id, version.major_version, version.is_deployed, version.created_at)
detail = client.agents.get_version("abc123DEFghiJKL", response.versions[0].id)
print(detail.version.composition.model_name)
print(detail.version.composition.system_prompt)
print(detail.changes) # None for the agent's first version
```
Both calls require configuration access on the agent, and they are read-only — deploying or restoring a version has to happen in the app.
## Evaluations
`client.agents.list_evaluations(...)` pages through an agent's graded chats newest-first, `client.agents.get_evaluation_metrics(...)` returns grade and tag counts over a window, and `client.agents.run_evaluations(...)` queues evaluations for finished sessions. `client.agents.get_evaluation_options()` lists the criterion types, priorities, and limits the config accepts.
```python theme={"dark"}
from datetime import datetime, timedelta, timezone
from gumloop import Gumloop
client = Gumloop(access_token="your_access_token")
since = datetime.now(timezone.utc) - timedelta(days=7)
failed = client.agents.list_evaluations("abc123DEFghiJKL", grade="needs_attention", created_after=since)
for evaluation in failed.evaluations:
print(evaluation.interaction_id, evaluation.summary)
metrics = client.agents.get_evaluation_metrics("abc123DEFghiJKL", days=30)
print(metrics.grades)
run = client.agents.run_evaluations("abc123DEFghiJKL", session_ids=[e.interaction_id for e in failed.evaluations])
for queued in run.results:
print(queued.session_id, queued.id)
for skipped in run.skipped:
print(skipped.session_id, skipped.reason)
```
Listing and metrics need read access on the agent and cover the chats you can see. Running evaluations needs edit access and consumes one credit per session; pass `dry_run=True` to see the cost and the sessions that would be skipped (unfinished, or already queued) without queuing anything. Results from an organization evaluation enforced on the agent are listed with `list_evaluations(agent_id, organization_evaluation_id=...)`.
## Organization evaluations
`client.evaluations` manages rubrics an organization admin defines once and applies to teams, people, or individual agents (Enterprise plan, **Manage evaluations** permission). A new evaluation starts disabled: set its targets, then enable it. Run it over past sessions with `run(...)`; grading is asynchronous, so poll each returned result id.
```python theme={"dark"}
import time
from gumloop import Gumloop
client = Gumloop(access_token="your_access_token")
organization_id = client.organizations.list().organizations[0].id
created = client.evaluations.create(
organization_id=organization_id,
name="Support tone",
config={
"criteria": [
{"name": "Greets the customer", "prompt": "Did the agent greet the customer by name?", "priority": "needs_review"}
]
},
)
evaluation_id = created.evaluation.id
client.evaluations.set_targets(evaluation_id, [{"type": "team", "id": "team_abc"}])
client.evaluations.update(evaluation_id, enabled=True)
queued = client.evaluations.run(evaluation_id, ["session_1", "session_2"])
for result in queued.results:
polled = client.evaluations.get_result(evaluation_id, result.id).result
while polled.status in ("queued", "in_progress"):
time.sleep(5)
polled = client.evaluations.get_result(evaluation_id, result.id).result
print(result.session_id, polled.status, polled.grade)
for result in client.evaluations.list_results(evaluation_id, grade="needs_attention").results:
print(result.agent_id, result.session_id, result.summary)
```
`client.evaluations.options()` returns the allowed values for every enum field (grades, statuses, target types, session types, criterion priorities) and the size limits.
## Company Brain
`client.brain.search(...)` runs a hybrid (semantic + keyword) search across the knowledge sources indexed in your [Company Brain](/core-concepts/brain) and returns ranked results scoped to what you can access. Brain is available on the Pro and Enterprise plans, and each search consumes credits.
```python theme={"dark"}
from gumloop import Gumloop
client = Gumloop(access_token="your_access_token")
response = client.brain.search(
"what is our refund policy?",
limit=8, # optional, 1–50 (default 8)
source_type=["notion", "google_drive"], # optional filter
)
for result in response.results:
print(result.score, result.source, result.title, result.url)
```
Each result carries `document_id`, `source`, `title`, `content`, `url`, `score`, `updated_at`, `owner_name`, `owner_email`, `parent_title`, and `metadata`. Omit `source_type` to search every source you can access; valid values are `notion`, `google_drive`, `slack`, `github`, `confluence`, `direct_file_uploads`, and `gumloop_artifacts`.
### Sources and files
Create file-upload sources and put files into them. Only `direct_file_uploads` sources can be created through the SDK; connected sources are set up in the app.
```python theme={"dark"}
source = client.brain.create_source("Engineering docs").source # personal, active
# client.brain.create_source("Runbooks", scope="team", team_id="...")
# client.brain.create_source("Policies", scope="organization", require_approval=True)
upload = client.brain.upload_files(source.id, {"handbook.pdf": open("handbook.pdf", "rb").read()})
print([f.status for f in upload.files], upload.rejected) # indexing starts on its own
for f in client.brain.list_files(source.id).files:
print(f.file_name, f.status, f.sha256) # uploaded → indexing → indexed
client.brain.delete_file(source.id, upload.files[0].id)
client.brain.delete_source(source.id)
```
`list_sources(scope=..., source_type=..., team_id=..., page_size=..., cursor=...)` and `get_source(id)` read sources of every type. A source created with `require_approval=True` is a draft: `get_estimate(id).estimate.estimated_credits` shows the cost once `estimate.status` is `paused_for_approval`, and `approve_source(id)` starts indexing. Every file's `sha256` lets you diff a local folder against a source; the CLI's [`gumloop brain sync`](/cli/brain) does exactly that.
## Flows (legacy client)
```python theme={"dark"}
from gumloop import GumloopClient
# Initialize the client
client = GumloopClient(
api_key="your_api_key",
user_id="your_user_id"
)
# Run a flow and wait for outputs
output = client.run_flow(
flow_id="your_flow_id",
inputs={
"recipient": "example@email.com",
"subject": "Hello",
"body": "World"
}
)
print(output)
```
Optionally add a `project_id` when creating the client if running automations in a workspace:
```python theme={"dark"}
from gumloop import GumloopClient
# Initialize the client
client = GumloopClient(
api_key="your_api_key",
user_id="your_user_id",
project_id="your_project_id"
)
```
# Cancel session
Source: https://docs.gumloop.com/api-reference/sessions/cancel-session
post /sessions/{session_id}/cancel
Cancel an in-progress session. If the session is currently `processing` or `queued`, any running stream is aborted and the session is transitioned to `failed`. If the session is already `completed` or `failed`, its current state is returned unchanged.
The response carries a `session` envelope but only `id`, `agent_id`, and `state` are populated.
# Create session
Source: https://docs.gumloop.com/api-reference/sessions/create-session
post /agents/{agent_id}/sessions
Create a new session for an agent. When `input` is provided, the message is enqueued and the agent begins processing — the response returns `202` with the session in `processing` or `queued` state. When `input` is omitted, an idle session stub is created and the response returns `201`.
`agent_id` also accepts the reserved aliases `gumball` and `analytics`, which resolve to your personal Gumball and analytics agents (created on first use).
### Streaming the response
`api.gumloop.com` only serves the non-streaming response above. To stream agent output as it's produced, send the same request body (with `stream: true`) to the streaming host instead:
`POST https://ws.gumloop.com/api/v1/agents/{agent_id}/sessions`
The response is `text/event-stream` (Server-Sent Events). With the Python SDK, `client.sessions.stream(agent_id, input="...")` routes to `ws.gumloop.com` automatically and yields parsed `StreamEvent` objects.
If you send `stream: true` to `api.gumloop.com` by mistake, the response is a `400` whose body contains the correct streaming host so you can retry against it.
# Delete queued message
Source: https://docs.gumloop.com/api-reference/sessions/delete-queued-message
delete /sessions/{session_id}/queue/{queued_message_id}
Remove a message from the session's queue before it is sent.
# List queued messages
Source: https://docs.gumloop.com/api-reference/sessions/list-queued-messages
get /sessions/{session_id}/queue
List the messages waiting in a session's queue, in the order they will be sent. Queued messages are drained automatically when the agent finishes its current turn.
# List sessions
Source: https://docs.gumloop.com/api-reference/sessions/list-sessions
get /agents/{agent_id}/sessions
List sessions for an agent with cursor-based pagination, optional filtering, and search.
# Queue message
Source: https://docs.gumloop.com/api-reference/sessions/queue-message
post /sessions/{session_id}/queue
Add a message to a session's queue instead of interrupting the agent. Queued messages are sent automatically, in order, when the agent finishes its current turn. A session's queue holds at most 20 messages.
To interrupt the current turn and send a queued message immediately, use [Send queued message now](/api-reference/sessions/send-queued-message).
# Rename session
Source: https://docs.gumloop.com/api-reference/sessions/rename-session
patch /sessions/{session_id}
Rename a session. `name` is the only mutable field; it is trimmed and must be between 1 and 256 characters after trimming.
Returns the full session, in the same shape as Retrieve session.
# Resolve approvals
Source: https://docs.gumloop.com/api-reference/sessions/resolve-approvals
post /sessions/{session_id}/approvals
Answer pending asks on a session that is paused in the `approval_required` state — tool approvals, human input requests, and checkpoints.
List the pending asks with Retrieve session: each entry in `pending_approvals` carries the `action_request_id` to answer, and `human_input` asks include the `questions` to fill in via `response.values`. Resolutions are processed in order; the agent resumes once the pending asks are answered.
# Retrieve session
Source: https://docs.gumloop.com/api-reference/sessions/retrieve-session
get /sessions/{session_id}
Retrieve a session by ID, including its messages, current state, agent metadata, and participants.
# Send message
Source: https://docs.gumloop.com/api-reference/sessions/send-message
post /sessions/{session_id}/messages
Append a user message to an existing session and resume the agent. The session must be `idle`, `completed`, `failed`, or `approval_required`; sending to a session that is `processing` or `queued` returns `409 interaction_not_in_terminal_state`. To hand the agent a message while it is still busy, use the [message queue](/api-reference/sessions/queue-message) instead.
Files uploaded via [Upload session file](/api-reference/sessions/upload-session-file) can be attached to the message with `attachments`.
### Sessions waiting on an approval
A session that stopped to ask you something is `approval_required`, and you have two ways to move it forward:
- **Answer the ask.** Send the pending asks' responses to [Resolve approvals](/api-reference/sessions/resolve-approvals). Use this to approve or reject a tool call, or to answer an Ask Question the agent raised. This endpoint rejects `approval_responses` with a `400`.
- **Send a follow-up instead.** Post a normal message here. It is appended to the session transcript and starts a new turn, leaving the pending ask unanswered. Use this when the answer no longer matters — for example to redirect the agent or drop the request it was asking about.
See [Human in the Loop](/core-concepts/human_in_the_loop) for how agents pause for approvals and questions.
### Streaming the response
`api.gumloop.com` only serves the non-streaming response above. To stream agent output as it's produced, send the same request body (with `stream: true`) to the streaming host instead:
`POST https://ws.gumloop.com/api/v1/sessions/{session_id}/messages`
The response is `text/event-stream` (Server-Sent Events). With the Python SDK, `client.sessions.stream_message(session_id, input="...")` routes to `ws.gumloop.com` automatically and yields parsed `StreamEvent` objects.
If you send `stream: true` to `api.gumloop.com` by mistake, the response is a `400` whose body contains the correct streaming host so you can retry against it.
# Send queued message now
Source: https://docs.gumloop.com/api-reference/sessions/send-queued-message
post /sessions/{session_id}/queue/{queued_message_id}/send
Send a queued message immediately instead of waiting for the agent to finish its current turn. Any in-progress run is aborted, the queued message is appended to the transcript, and the agent starts processing it.
The response is the same envelope as Send message. Queued messages cannot be sent this way on incognito sessions, and a message that is currently being edited must have its edit finished or cancelled first.
# Update queued message
Source: https://docs.gumloop.com/api-reference/sessions/update-queued-message
patch /sessions/{session_id}/queue/{queued_message_id}
Replace the content of a message that is still waiting in the session's queue.
# Upload session file
Source: https://docs.gumloop.com/api-reference/sessions/upload-session-file
post /sessions/{session_id}/files
Upload a file into a session's input namespace so it can be attached to a message. The response returns the stored path — pass it as `file_name` in the `attachments` array when sending a message on the same session.
Files are base64 encoded in the request body and limited to 200MB (decoded). Uploaded files are scoped to the session they were uploaded to and cannot be attached to messages on other sessions.
# Create skill
Source: https://docs.gumloop.com/api-reference/skills/create-skill
post /skills
Upload a skill package and create a new skill. The package must include a `SKILL.md` with `name` and `description` frontmatter; uploads may be a single `.md` file (stored as `SKILL.md`), or a `.zip` / `.skill` archive containing `SKILL.md` at its root. The initial version is created automatically. Maximum upload size is 10 MB.
# Delete skill
Source: https://docs.gumloop.com/api-reference/skills/delete-skill
delete /skills/{skill_id}
Permanently delete a skill. This is a soft-delete — the skill will no longer appear in listings or be usable by agents.
# Download skill
Source: https://docs.gumloop.com/api-reference/skills/download-skill
get /skills/{skill_id}/download
Generate a signed URL to download a skill's contents as a `.skill` archive (ZIP). When `version_id` is provided, returns that exact version; otherwise returns the current draft.
# List skills
Source: https://docs.gumloop.com/api-reference/skills/list-skills
get /skills
List skills the caller has access to. Filter by team, search by name, or narrow to a specific creator, related MCP server, or agent.
# Update skill
Source: https://docs.gumloop.com/api-reference/skills/update-skill
patch /skills/{skill_id}
Replace a skill's files with a new upload. Reparses `SKILL.md` to update the skill's `name`, `description`, and `metadata`, and creates a new version. Maximum upload size is 10 MB.
# List teams
Source: https://docs.gumloop.com/api-reference/teams/list-teams
get /teams
List teams the authenticated caller belongs to.
# Agents
Source: https://docs.gumloop.com/cli/agents
List, inspect, create, and update agents from the terminal.
`gumloop agents` lets you list, inspect, create, and update your [agents](/core-concepts/agents) without leaving the terminal. Every command accepts `--json` to print the raw response payload.
## List agents
```bash theme={"dark"}
gumloop agents list
gumloop agents list --search support --limit 50
```
Returns a tab-separated table with `ID`, `NAME`, `MODEL`, `TEAM`, and `ACTIVE`. If the response is paginated, the next cursor is printed at the bottom — pass it back with `--cursor`.
| Flag | Description |
| - | - |
| `--search` | Filter agents by name or description. |
| `--limit` | Maximum number of agents to return. |
| `--cursor` | Pagination cursor from a previous list call. |
| `--json` | Print the raw response payload. |
The `--team-id` global flag scopes the listing to a single team.
## Get an agent
```bash theme={"dark"}
gumloop agents get agent_abc
```
Prints the agent's name as a header followed by `id`, `model_name`, `team_id`, `is_active`, `folder_id`, `description`, `created_at`, and the system prompt (if set).
Grab the agent ID from the first column of `gumloop agents list`.
## List agent versions
```bash theme={"dark"}
gumloop agents versions agent_abc
gumloop agents versions agent_abc --limit 50 --json
```
Returns a tab-separated table with `ID`, `VERSION`, `NAME`, `DEPLOYED`, and `CREATED`, newest first. If the response is paginated, the next cursor is printed at the bottom — pass it back with `--cursor`.
| Flag | Description |
| - | - |
| `--limit` | Maximum number of versions to return. |
| `--cursor` | Pagination cursor from a previous versions call. |
| `--json` | Print the raw response payload. |
Versions are read-only snapshots of the agent's configuration; the CLI cannot deploy or restore one.
## Export an agent version
```bash theme={"dark"}
gumloop agents export agent_abc gv_a1b2c3d4
gumloop agents export agent_abc gv_a1b2c3d4 --output agent-version.json
```
Writes one version as JSON: the version's full configuration (`composition`) plus the structured `changes` against the version before it. `changes` is `null` for an agent's first version.
| Flag | Description |
| - | - |
| `-o`, `--output` | File to write. Omit or pass `-` to print to stdout. |
Grab the version ID from the first column of `gumloop agents versions `.
## Create an agent
```bash theme={"dark"}
gumloop agents create --name "Support bot" --model gumloop-chew
```
| Flag | Required | Description |
| - | - | - |
| `--name` | yes | Display name for the new agent. |
| `--model` | | Model name (for example `gumloop-chew`, `anthropic/claude-sonnet-4`). Omit to use the server default for the account, which is not always Auto. |
| `--description` | | Short description. |
| `--system-prompt` | | Inline system prompt text. |
| `--system-prompt-file` | | Path to a file containing the system prompt. Mutually exclusive with `--system-prompt`. |
| `--tools-json` | | Inline JSON array of tool config objects. |
| `--tools-file` | | Path to a JSON file containing the tools array. Mutually exclusive with `--tools-json`. |
| `--json` | | Print the raw response payload. |
`gumloop-chew` is [Gumloop Chew](/core-concepts/ai_models#auto-faq), the router that picks a model per message rather than a model of its own. The CLI does not treat `auto` as an alias.
Pass the system prompt from a file:
```bash theme={"dark"}
gumloop agents create --name "Sales research" --model gumloop-chew \
--system-prompt-file ./prompts/sales.md
```
Attach tools (each entry in the array is one tool config; the shape varies by type):
```bash theme={"dark"}
gumloop agents create --name "Email reader" --model gumloop-chew \
--tools-json '[{"type":"gumcp_server","server":"gmail"}]'
```
To see the exact tool config shape an agent uses, run `gumloop agents get --json` on an existing agent and copy the `tools` array out of the response.
## Update an agent
```bash theme={"dark"}
gumloop agents update agent_abc --name "Better bot"
gumloop agents update agent_abc --system-prompt-file new-prompt.md
```
Only the flags you pass are changed; everything else is left untouched. The flag surface matches `agents create` and adds:
| Flag | Description |
| - | - |
| `--is-active` / `--inactive` | Set the agent's active state. `--inactive` retires the agent — see the warning below. |
`--inactive` (and `is_active: false` on the API) is **not** a pause switch. It retires the agent: it stops appearing in `gumloop agents list`, and `gumloop agents get`/`update` return a `404` afterwards, so you cannot turn it back on yourself. Contact [support@gumloop.com](mailto:support@gumloop.com) if you need a retired agent restored.
To stop an agent from running on its own while keeping it fully reachable, deactivate its triggers instead — open the agent's **Triggers** section in the app and use the three-dot menu on each trigger, or ask the agent to pause the schedule in chat. See [Managing active triggers](/core-concepts/agent_triggers#managing-active-triggers).
## Evaluations
```bash theme={"dark"}
gumloop agents eval-options
gumloop agents eval-metrics agent_abc --days 30
gumloop agents eval-run agent_abc --session-id session_1 --session-id session_2
gumloop agents eval-run agent_abc --session-id session_1 --dry-run
```
`eval-options` prints the criterion types, priorities, data point types, frequencies, and limits the evaluation config accepts. `eval-metrics` prints grade and tag counts for the last `--days` days (default 30). `eval-run` queues an evaluation for each `--session-id` and prints the result id to poll for each queued session, plus the sessions skipped as ineligible or already running.
| Flag | Description |
| - | - |
| `--days` | Look-back window for `eval-metrics`, 1 to 365. |
| `--session-id` | Session to evaluate with `eval-run`. Repeat for multiple sessions, up to 200. |
| `--dry-run` | Print the credit cost and skipped sessions without queuing anything. |
| `--json` | Print the raw response payload. |
`eval-run` needs edit access on the agent and consumes one credit per queued session.
# Artifacts
Source: https://docs.gumloop.com/cli/artifacts
List and download files produced by agents.
`gumloop artifacts` exposes the [files](/core-concepts/agent_artifacts) an agent has produced — reports, generated docs, exported data, etc. Artifacts are always scoped to an agent.
## List artifacts
```bash theme={"dark"}
gumloop artifacts list agent_abc
gumloop artifacts list agent_abc --session session_xyz --limit 50
```
Prints `ID`, `FILENAME`, `VERSION`, `SESSION`, and `CREATED`. If the response is paginated, the next cursor is printed at the bottom.
Grab the agent ID from `gumloop agents list` and the session ID from `gumloop sessions get ` or the URL of the session in the Gumloop hub.
| Flag | Description |
| - | - |
| `--session` | Filter to artifacts produced inside a specific session. |
| `--limit` | Maximum number of artifacts to return. |
| `--cursor` | Pagination cursor from a previous list call. |
| `--json` | Print the raw response payload. |
## Download an artifact
```bash theme={"dark"}
gumloop artifacts download artifact_abc
```
By default the artifact is written to the current directory under its original filename. Use `-o` to change the destination:
| Flag | Description |
| - | - |
| `-o`, `--output` | File or directory to write to. Use `-` to write to stdout. |
| `--version-id` | Download a specific artifact version. |
| `--json` | Print download metadata as JSON (path + bytes). |
```bash theme={"dark"}
gumloop artifacts download artifact_abc -o ./downloads/
gumloop artifacts download artifact_abc -o - # stream to stdout
gumloop artifacts download artifact_abc --version-id av_xyz
```
# Authentication
Source: https://docs.gumloop.com/cli/authentication
Sign in with OAuth or an API key. The CLI stores credentials in your OS keychain.
The Gumloop CLI authenticates with either an [OAuth 2.0](/api-reference/oauth) access token or a personal [API key](/api-reference/authentication#api-key). Both grant the same permissions; OAuth is recommended because it can refresh on its own.
Credentials are stored in your OS keychain (macOS Keychain, GNOME Keyring, or KWallet) — never in a plaintext file. On headless machines, skip `gumloop login` and use [environment variables](#environment-variables) instead.
The CLI runs on **macOS** and **Linux** only — not native Windows. On Windows, run it inside [WSL](https://learn.microsoft.com/windows/wsl/install) or use the [Python SDK](/api-reference/sdk/python) instead. See [System requirements](/cli/overview#install).
## Login
```bash theme={"dark"}
gumloop login
```
Pick **OAuth (browser)** or **API key** when prompted:
![gumloop login prompt asking the user to choose between OAuth (browser) and API key]()
### OAuth (recommended)
```bash theme={"dark"}
gumloop login --method oauth
```
Here's what happens:
1. The CLI starts a tiny one-shot web server on `localhost:8765` to receive the OAuth redirect.
2. Your browser opens to the Gumloop consent screen — click **Allow**.
3. Gumloop redirects back to `localhost:8765`, the CLI captures the auth code, exchanges it for tokens, and shuts the server down.
4. Both the access token and refresh token are saved to your OS keychain. Expired access tokens are refreshed automatically — you should not need to re-run `gumloop login` until you explicitly `logout`.
**On a remote box** where the CLI can't open a browser:
```bash theme={"dark"}
gumloop login --method oauth --no-browser
```
The CLI prints the authorization URL — open it on any machine, complete the flow, and the redirect will still land back on `localhost:8765` on the remote box (use SSH port-forwarding if needed: `ssh -L 8765:localhost:8765 user@host`).
Other options:
| Flag | Default | Description |
| - | - | - |
| `--callback-port` | `8765` | Local port for the OAuth redirect handler. Change it if 8765 is in use. |
| `--no-browser` | off | Print the authorization URL instead of opening a browser. |
### API key
```bash theme={"dark"}
gumloop login --method api-key
```
You'll be prompted for two values:
1. **API key** — generate one on the [Connectors page](https://www.gumloop.com/settings/profile/connectors?view=connected). Requires the Pro plan or above.
2. **User ID** — your Gumloop user ID, also visible on the [Profile Settings page](https://www.gumloop.com/settings/profile/general).
Pass them inline to skip the prompt:
```bash theme={"dark"}
gumloop login --api-key gum_xxx --user-id user_abc
```
To keep the key out of your shell history (and `/proc//cmdline` on Linux), pipe it in via stdin with `-`:
```bash theme={"dark"}
echo "$GUMLOOP_API_KEY" | gumloop login --api-key - --user-id user_abc
```
The same `-` trick works for `--access-token`.
### Verification
`gumloop login` calls a lightweight read endpoint (`models.list`) before saving anything. If the credential is invalid, nothing is written to the keychain.
## Logout
```bash theme={"dark"}
gumloop logout
```
This clears every entry the CLI wrote to your keychain. If you signed in with OAuth, the CLI also revokes your refresh token server-side. Revoke failures don't block the local clear — a warning is printed if the server was unreachable.
## Environment variables
These override stored credentials for a single invocation, which makes them ideal for CI, containers, and headless servers.
| Variable | Purpose |
| - | - |
| `GUMLOOP_ACCESS_TOKEN` | OAuth access token. Wins over any stored credential. |
| `GUMLOOP_API_KEY` | Personal API key. Used only if `GUMLOOP_ACCESS_TOKEN` is not set. |
| `GUMLOOP_USER_ID` | User ID for API key auth (sent as the `x-auth-key` header). Required with `GUMLOOP_API_KEY`. |
| `GUMLOOP_TEAM_ID` | Default team to scope commands to (same as `--team-id`). |
| `GUMLOOP_BASE_URL` | Override the Gumloop API base URL (same as `--base-url`). |
**Example: GitHub Actions step**
```yaml theme={"dark"}
- name: Trigger nightly report
env:
GUMLOOP_API_KEY: ${{ secrets.GUMLOOP_API_KEY }}
GUMLOOP_USER_ID: user_abc
run: |
curl -fsSL https://gumloop.com/cli/install.sh | sh
gumloop sessions create agent_abc --input "Run the nightly report."
```
## Where credentials are stored
The CLI writes the following entries under the `gumloop-cli` keyring service:
| Entry | Set when |
| - | - |
| `access_token` | OAuth login |
| `refresh_token` | OAuth login (if the server issued one) |
| `api_key` | API-key login |
| `user_id` | API-key login |
| `base_url` | Always — the API base URL the credentials were issued against |
Inspect them with your OS tooling (Keychain Access on macOS, `secret-tool` / `kwallet-query` on Linux) or wipe them with `gumloop logout`.
If no keychain backend is available, `gumloop login` refuses to run rather than fall back to a plaintext file. On a headless box, use the [environment variables](#environment-variables) above.
# Brain
Source: https://docs.gumloop.com/cli/brain
Search your Company Brain and keep a folder of files synced into it from the terminal.
[Company Brain](/core-concepts/brain) is your organization's knowledge base — the documents, messages, and files you've connected and indexed. `gumloop brain` searches it with the same hybrid (semantic + keyword) search your agents use, and syncs local folders into file-upload sources.
Brain is available on the **Pro** and **Enterprise** plans. Searches and indexing consume Gumloop credits.
## Sync a folder
```bash theme={"dark"}
gumloop brain sync ./docs --create "Engineering docs"
```
The first run creates a file-upload source and uploads every file in the folder (subfolders included, dotfiles skipped). Re-running compares each file's name and sha256 against the source and uploads only what is new or changed; indexing starts on its own after each upload.
```text theme={"dark"}
Source PFqdAMir8PA2Xc6qcszSN9 (active)
1 uploaded, 1 replaced, 0 pruned, 3 unchanged
Skipped notes.exe: unsupported file type ".exe"
```
```bash theme={"dark"}
gumloop brain sync ./docs --source --prune # existing source; remove remote files that are gone locally
gumloop brain sync ./runbooks --create "Runbooks" --team-id
gumloop brain sync ./policies --create "Policies" --scope organization --require-approval --approve
gumloop brain sync ./docs --source --dry-run
```
| Flag | Description |
| - | - |
| `--source` | Id of an existing source to sync into. Exactly one of `--source` or `--create` is required. |
| `--create` | Create a new source with this name. Personal by default; add `--team-id` (or `--scope team --team-id`) for a team source, `--scope organization` for an organization source. |
| `--require-approval` | With `--create`: start as a draft that estimates credits before indexing (see below). |
| `--prune` | Delete files from the source that no longer exist locally. Off by default. |
| `--approve` | Approve a draft source once its estimate is ready. |
| `--dry-run` | Print the plan without uploading or deleting. |
| `--json` | Print the result as JSON (`uploaded`, `replaced`, `pruned`, `unchanged`, `rejected`, `estimate`). |
Accepted file types are PDF, Word, PowerPoint, Excel, and text (`.txt`, `.md`, `.html`, `.csv`, `.rtf`), up to 25 MB each. Anything else is reported as skipped and left alone.
### Drafts and credit estimates
Without `--require-approval` a source is active and each upload is indexed and billed right away. With it, the source is a draft: uploads run a credit estimate, the source owner is notified in Gumloop, and nothing is indexed until it is approved.
```bash theme={"dark"}
gumloop brain sources estimate
# Estimate (paused_for_approval): 5 credits for 2 files (75 tokens).
gumloop brain sources approve
```
## Sources and files
```bash theme={"dark"}
gumloop brain sources list [--scope personal|team|organization] [--source-type direct_file_uploads]
gumloop brain sources create "Engineering docs" [--scope team --team-id ] [--require-approval]
gumloop brain sources get
gumloop brain sources delete
gumloop brain files list
gumloop brain files upload ./handbook.pdf ./release.md
gumloop brain files delete
```
`sources list` shows every source you can see, including ones connected in the app such as Notion or Google Drive. Only file-upload sources can be created from the CLI. `files list` shows each file's indexing status (`uploaded`, `indexing`, `indexed`, `failed`) and sha256. Every command takes `--json`.
## Search
```bash theme={"dark"}
gumloop brain search "onboarding process"
```
The query returns the most relevant snippets across every source you can access — your Personal sources plus any Team and Organization sources shared with you.
```text theme={"dark"}
SCORE SOURCE TITLE URL
0.871 notion Onboarding Checklist https://www.notion.so/Onboarding-Checklist-2f1a9c7e
0.804 google_drive New Hire Handbook https://docs.google.com/document/d/1a2b3c
```
### Options
| Flag | Description |
| - | - |
| `--limit` | Maximum number of results to return (1–50). Defaults to 8. |
| `--source` | Filter by source type. Repeat the flag to allow several, e.g. `--source notion --source slack`. Valid values: `notion`, `google_drive`, `slack`, `github`, `confluence`, `direct_file_uploads`, `gumloop_artifacts`. |
| `--json` | Print the raw response payload instead of the table. |
```bash theme={"dark"}
gumloop brain search "pricing" --limit 5 --source notion --json
```
The `--json` output includes the full result objects — `document_id`, `source`, `title`, `content`, `url`, `score`, `updated_at`, `owner_name`, `owner_email`, `parent_title`, and `metadata` — which is handy for piping into `jq` or another tool.
## Related
How Brain indexes your knowledge and how agents use it.
Search, sources, and file uploads over the REST API.
# Chat
Source: https://docs.gumloop.com/cli/chat
Send chat completions to any Gumloop-supported model from the terminal.
`gumloop chat completions create` is the terminal counterpart of the Python SDK call `client.chat.completions.create(...)`. Every flag maps 1:1 to the matching SDK kwarg.
## Create a completion
```bash theme={"dark"}
gumloop chat completions create "Capital of Canada?" -m claude-sonnet-4-5
```
By default, output streams to your terminal when stdout is a TTY and is buffered into a single response when it isn't (e.g. piped to a file or another command). Pass `--stream` or `--no-stream` to be explicit.
| Flag | Description |
| - | - |
| `-m`, `--model` | **Required.** Model slug (for example `claude-sonnet-4-5`, `gpt-4o-mini`, `gemini-2.5-pro`). Chat needs a concrete model, so `gumloop-chew` (the **Auto** [router](/core-concepts/ai_models#auto-faq)) is not valid here. Preview a choice with `POST /models/route` first, then complete. |
| `-s`, `--system` | System message prepended to the conversation. Repeatable. |
| `--message-stdin -` | Read the user message from stdin instead of the positional argument. |
| `--max-completion-tokens` | Cap on completion tokens. |
| `--temperature` | Sampling temperature. |
| `--modality` | Output modality. Repeatable — e.g. `--modality image --modality text` for image-generation models. |
| `--schema-file` | Path to a JSON Schema file. Sent as `response_format={"type": "json_schema", ...}` for structured output. |
| `--schema-name` | Name to attach to the schema (defaults to `schema`). |
| `--stream` / `--no-stream` | Force or suppress streaming. When omitted, streams only if stdout is a TTY. `--json` implies `--no-stream` unless `--stream` is also passed. |
| `--json` | Print the response as JSON. With `--stream`, emits newline-delimited JSON (one chunk per line). |
## Pipe from stdin
```bash theme={"dark"}
cat draft.md | gumloop chat completions create -m claude-sonnet-4-5 \
--message-stdin - \
--system "Summarize the input in three bullets."
```
## Structured output
```bash theme={"dark"}
gumloop chat completions create "Return JSON with the capital of Canada." \
-m claude-sonnet-4-5 \
--schema-file ./capital.schema.json \
--schema-name capital \
--json
```
`capital.schema.json`:
```json theme={"dark"}
{
"type": "object",
"properties": { "capital": { "type": "string" } },
"required": ["capital"],
"additionalProperties": false
}
```
## Image generation
```bash theme={"dark"}
gumloop chat completions create "A red maple leaf on white" \
-m gpt-image-2.5-flare \
--modality image --modality text \
--json
```
The response carries one or more image attachments on `choices[0].message.images`. Each entry is a data URL the caller can decode or render directly.
## Streaming with machine output
`--stream --json` emits ndjson — one full `chat.completion.chunk` per line — so consumers can stitch deltas without re-parsing the full SSE wire format.
```bash theme={"dark"}
gumloop chat completions create "stream me" -m claude-sonnet-4-5 --stream --json
```
The CLI streams to TTYs by default. When redirecting stdout (`> out.txt`, `| jq`, CI pipes) it switches to unary so output is byte-stable.
# Evaluations
Source: https://docs.gumloop.com/cli/evaluations
Create organization evaluations, choose which agents they grade, and run them over past sessions.
`gumloop evaluations` manages [organization evaluations](/core-concepts/evaluations): rubrics an organization admin defines once and applies to teams, people, or individual agents. Every command accepts `--json` to print the raw response payload.
These commands require the Enterprise plan and the **Manage evaluations** organization permission. Commands that need an organization default to the one you belong to; pass `--organization org_abc` to be explicit.
## List evaluations
```bash theme={"dark"}
gumloop evaluations list
```
Returns a tab-separated table with `ID`, `NAME`, `ENABLED`, `AGENTS` (how many agents the targets currently cover), `GRADED`, and `SUCCESS`.
| Flag | Description |
| - | - |
| `--organization` | Organization id. Defaults to yours. |
| `--limit` | Maximum number of evaluations to return. |
| `--cursor` | Pagination cursor from a previous list call. |
## Get an evaluation
```bash theme={"dark"}
gumloop evaluations get eval_abc
```
Prints the name, whether it is enabled, its targets, how many agents it covers, how many criteria it has, and its graded count and success rate so far.
## Create an evaluation
```bash theme={"dark"}
gumloop evaluations create --name "Support tone"
gumloop evaluations create --name "Refund policy" --config-file rubric.json
```
`rubric.json` holds the rubric fields — `criteria`, `tags`, `data_points`, `model_name`, `frequency`, `language`, `session_types`:
```json theme={"dark"}
{
"criteria": [
{
"name": "Greets the customer",
"prompt": "Did the agent greet the customer by name?",
"priority": "needs_review"
}
],
"tags": [{ "name": "refund request", "description": "The customer asked for a refund." }]
}
```
| Flag | Description |
| - | - |
| `--name` | Evaluation name, unique within the organization. |
| `--description` | Optional description. |
| `--organization` | Organization id. Defaults to yours. |
| `--config-json` | Inline JSON rubric. |
| `--config-file` | Path to a JSON file containing the rubric. Mutually exclusive with `--config-json`. |
A new evaluation starts disabled and grades nothing until you give it targets and turn it on:
```bash theme={"dark"}
gumloop evaluations targets eval_abc --team-ids team_1
gumloop evaluations update eval_abc --enable
```
Unknown values — a `priority` that isn't `needs_review` or `needs_attention`, a `frequency` that isn't `debounced`, `per_turn`, or `manual`, a criterion missing `name` or `prompt` — are rejected with the offending field path rather than silently changed. `gumloop evaluations options` lists every allowed value.
## Update an evaluation
```bash theme={"dark"}
gumloop evaluations update eval_abc --enable
gumloop evaluations update eval_abc --disable
gumloop evaluations update eval_abc --name "Support tone v2" --config-file rubric.json
```
Only the flags you pass change. A rubric list you send (`criteria`, `tags`, `data_points`) replaces that list wholesale, so send the full list you want to keep. Pass `--description ""` to clear the description.
Turning an evaluation on requires at least one criterion, tag, or data point and at least one covered agent.
## Choose which agents it grades
```bash theme={"dark"}
gumloop evaluations targets eval_abc --whole-organization
gumloop evaluations targets eval_abc --team-ids team_1,team_2 --agent-ids agent_9
gumloop evaluations targets eval_abc --user-ids user_5
```
Each call replaces the whole target set. Targets expand to agents live: a team target grades every agent that team owns, including ones created later; `--user-ids` grades members' personal agents. The output lists the saved targets and how many agents they currently cover. Removing the last target pauses an enabled evaluation.
| Flag | Description |
| - | - |
| `--whole-organization` | Grade every agent in the organization. |
| `--team-ids` | Comma-separated team ids. |
| `--user-ids` | Comma-separated member user ids. |
| `--agent-ids` | Comma-separated agent ids. |
## Run it on past sessions
```bash theme={"dark"}
gumloop evaluations run eval_abc session_1 session_2
gumloop evaluations run eval_abc session_1 --dry-run
```
Queues up to 200 sessions for grading and prints one line per session: queued ones with their result id, skipped ones with the reason (`ineligible` when the session's agent isn't covered, `in_flight` when it is already being graded). Each queued session costs one credit. `--dry-run` prints the same breakdown without queuing or charging.
Grading is asynchronous — check back with `gumloop evaluations results`.
## See results
```bash theme={"dark"}
gumloop evaluations results eval_abc
gumloop evaluations results eval_abc --grade needs_attention
gumloop evaluations results eval_abc --agent agent_9 --since 2026-09-01T00:00:00Z --json
```
Returns a tab-separated table with `ID`, `SESSION`, `AGENT`, `STATUS`, `GRADE`, and `CREATED`. Failed results show their error code in the grade column.
| Flag | Description |
| - | - |
| `--agent` | Only results for this agent. |
| `--session` | Only results for this session. |
| `--grade` | `pass`, `needs_review`, or `needs_attention`. |
| `--status` | `queued`, `in_progress`, `completed`, or `failed`. |
| `--since` / `--until` | Created-at bounds, RFC 3339 with an offset (for example `2026-09-01T00:00:00Z`). |
| `--limit` | Maximum number of results to return. |
| `--cursor` | Pagination cursor from a previous call. |
## Metrics
```bash theme={"dark"}
gumloop evaluations metrics eval_abc --days 7
```
Prints how many sessions received each grade in the window (default 30 days).
## Delete an evaluation
```bash theme={"dark"}
gumloop evaluations delete eval_abc
```
The evaluation stops running and disappears from lists. Results it already produced stay attached to their sessions.
# MCP servers
Source: https://docs.gumloop.com/cli/mcp
Explore the MCP servers available to your account and execute their tools.
An [MCP server](/nodes/mcp/custom_mcp_servers) is an integration — Gmail, Slack, Linear, Notion, your own custom one — that exposes a set of tools your agents (or you, directly) can call. `gumloop mcp` lets you list the servers connected to your account, browse their tools, and invoke them on demand.
## List servers
```bash theme={"dark"}
gumloop mcp list
```
Prints `SERVER_ID`, `NAME`, `TYPE`, `STATUS`, `TOOLS` (tool count), and `AUTH_URL`. If a server's `STATUS` is anything other than `connected`, the `AUTH_URL` column has a one-click link to finish connecting it — open it in your browser, approve, and you're done.
## Inspect a server
```bash theme={"dark"}
gumloop mcp get gmail
```
Shows the server's full configuration — `server_id`, `type`, `status`, `tool_count`, `description`, the Gumloop auth URL, and the underlying MCP endpoint.
## List the tools a server exposes
```bash theme={"dark"}
gumloop mcp tools gmail
```
Returns a table of `NAME`, `TOOL_CALL_ID`, and `DESCRIPTION`. If the server isn't connected yet, the CLI prints the auth URL you need to open instead.
You pass the tool's `NAME` (not `TOOL_CALL_ID`) to `gumloop mcp call`. `TOOL_CALL_ID` is the internal identifier used when an agent invokes the tool.
## Call a tool
```bash theme={"dark"}
gumloop mcp call gmail list_emails --args-json '{"max_results": 5}'
```
The arguments can come from three places (pick one):
| Flag | Description |
| - | - |
| `--args-json` | Inline JSON object. |
| `--args-file` | Path to a JSON file. |
| `--args -` | Read JSON from stdin (use the literal `-`). |
| `--ref` | Optional client-side ref string. The server echoes it back on each result so you can match responses to requests. |
| `--json` | Print the raw response payload. |
Examples:
```bash theme={"dark"}
gumloop mcp call gmail send_email --args-file ./email.json
```
```bash theme={"dark"}
cat email.json | gumloop mcp call gmail send_email --args -
```
The default text output groups results by tool, prints the status and any error, then the content of each result. MCP execution failures are reported per result, so check each printed `status` or use `--json` to pipe the structured response into another tool.
# Gumloop for terminal
Source: https://docs.gumloop.com/cli/overview
Drive Gumloop agents, sessions, chat completions, MCP servers, Company Brain, skills, and artifacts from your shell.
`gumloop` is the command line for Gumloop. Sign in once, then drive your agents, sessions, chat completions, MCP integrations, Company Brain, skills, and artifacts from the terminal. Every command has a `--json` mode so you can pipe results into scripts, cron jobs, or any other tool you already use.
## Install
```bash theme={"dark"}
curl -fsSL https://gumloop.com/cli/install.sh | sh
```
The prompt is self-contained — the agent installs the CLI, sorts out authentication with you, and installs the [Gumloop CLI skill](#use-with-coding-agents) on its own.
````markdown theme={"dark"}
# Set up the Gumloop CLI
Set up the Gumloop CLI in this environment so you can operate Gumloop (run agents,
call MCP integration tools, search Company Brain). Follow these steps in order.
## Step 1: Install the CLI
Skip this step if `gumloop --version` already works. Otherwise install it
(macOS, Linux, or WSL only — it does not run on native Windows):
```bash
curl -fsSL https://gumloop.com/cli/install.sh | sh
```
On an interactive machine the installer ends by offering `gumloop login` — tell me
to accept it. On a headless machine or CI, ask me for a Gumloop API key
(from https://www.gumloop.com/settings/profile/connectors?view=connected) and my user ID
(from https://www.gumloop.com/settings/profile/general), then export both as
`GUMLOOP_API_KEY` and `GUMLOOP_USER_ID`. Never print or log the API key.
## Step 2: Verify authentication
```bash
gumloop agents list
```
If this fails with an authentication error, fix the credentials from Step 1
before continuing.
## Step 3: Install the Gumloop CLI skill
```bash
gumloop plugin install gumloop
```
This installs a `gumloop-cli` skill with the full command reference into your
skill directories. Read it before using unfamiliar commands.
## Step 4: Learn the surface
- List what is available: `gumloop agents list`, `gumloop mcp list`.
- Always pass `--json` when you parse output.
- Use `gumloop --help` before using a command; do not invent flags.
- Discover MCP tools with `gumloop mcp tools --json` instead of guessing
tool names.
When all steps pass, tell me what agents and MCP servers you found and ask what
I want to run first.
````
The installer is fully self-contained under `~/.gumloop` — it ships its own Python, never touches your system Python, and needs no sudo. Verify the install:
```bash theme={"dark"}
gumloop --version
```
Update any time with:
```bash theme={"dark"}
gumloop update
```
Using Gumloop as a library instead? See the [Python SDK](/api-reference/sdk/python).
**Windows is not supported.** The Gumloop CLI runs on **macOS** and **Linux** only. This applies to every command — including `gumloop login` and syncing skills or artifacts — because credential storage and the OAuth callback server rely on POSIX-only paths.
Windows users have two options:
* **Use [WSL](https://learn.microsoft.com/windows/wsl/install)** (Windows Subsystem for Linux) and install the CLI inside your Linux distribution. This is the recommended path.
* **Use the Python SDK instead** — it works natively on Windows. Import `from gumloop import Gumloop` directly. See the [Python SDK reference](/api-reference/sdk/python).
### Linux prerequisites
The CLI stores credentials in your OS keychain. macOS Keychain is always available, but on Linux you need one of:
```bash theme={"dark"}
sudo apt install gnome-keyring libsecret-1-0
sudo apt install kwalletmanager
```
On a headless box without a keychain, skip `gumloop login` entirely and pass credentials per invocation via [environment variables](/cli/authentication#environment-variables).
## Sign in
```bash theme={"dark"}
gumloop login
```
Pick **OAuth (browser)** at the prompt. The CLI opens your browser, you click "Allow" on the Gumloop consent screen, and you're signed in. Tokens are stored in your OS keychain and the CLI refreshes them for you when they expire.
Prefer an API key, or running on a headless box? See [Authentication](/cli/authentication).
## Your first command
List the agents you can see:
```bash theme={"dark"}
gumloop agents list
```
```text theme={"dark"}
ID NAME MODEL TEAM ACTIVE
agent_g6f1a2b3 Sales research anthropic/claude-sonnet-4 team_4f8c92ab yes
agent_h7e9c1d4 Support triage openai/gpt-5 team_4f8c92ab yes
```
Grab an ID from that table and start a chat:
```bash theme={"dark"}
gumloop sessions create agent_g6f1a2b3 --input "Summarize this week's pipeline."
```
That's it. From here, every command works the same way — `gumloop `, with `--help` on anything to see all the flags.
## Use with coding agents
Now that you're set up, your coding agent (Claude Code, Cursor, Codex, ...) can drive Gumloop for you. One command installs the `gumloop-cli` skill — setup, every command, and the sharp edges — into each coding agent detected on your machine:
```bash theme={"dark"}
gumloop plugin install gumloop
```
Restart your agent (or start a new session) and it picks the skill up whenever a task involves Gumloop. Haven't installed the CLI yet? The [setup prompt in Install](#install) has your agent do all of this for you.
The skill ships inside the CLI as an [Agent Plugin](https://agent-plugins.org). To write the raw plugin package (`plugin.json` + `skills/`) somewhere explicit — for a plugin-aware client or a project checkout — use `gumloop plugin install gumloop --dir `.
## Commands
| Command | What it does |
| - | - |
| [`gumloop login`](/cli/authentication#login) / [`logout`](/cli/authentication#logout) | Manage stored credentials |
| [`gumloop agents`](/cli/agents) | List, inspect, create, and update agents, and export agent versions |
| [`gumloop sessions`](/cli/sessions) | Create, inspect, send messages to, and cancel agent sessions |
| [`gumloop evaluations`](/cli/evaluations) | Create organization evaluations, choose which agents they grade, and run them over past sessions |
| [`gumloop chat`](/cli/chat) | Send chat completions to any supported model (unary, streaming, structured, image) |
| [`gumloop mcp`](/cli/mcp) | Explore connected MCP servers and execute their tools |
| [`gumloop brain`](/cli/brain) | Search your Company Brain's indexed knowledge sources |
| [`gumloop skills`](/cli/skills) | List, upload, update, and download skill files |
| [`gumloop artifacts`](/cli/artifacts) | List and download artifacts produced by agents |
## Global flags
These work on every command:
| Flag | Env var | Description |
| - | - | - |
| `--team-id` | `GUMLOOP_TEAM_ID` | Scope the command to a single team. |
| `--base-url` | `GUMLOOP_BASE_URL` | Override the Gumloop API base URL (useful for self-hosted/staging). |
| `--version`, `-V` | — | Print the CLI version and exit. |
| `--help`, `-h` | — | Show contextual help for any command or subcommand. |
Most subcommands additionally accept `--json` to print the raw response payload instead of the human-friendly table, which is handy for piping into `jq`, scripts, or other tools.
# Sessions
Source: https://docs.gumloop.com/cli/sessions
Start agent conversations, send follow-ups, and cancel running sessions.
A **session** is a single conversation thread with one agent — start it, send messages back and forth, then cancel or let it finish. `gumloop sessions` is how you do all of that from the terminal.
## Create a session
Start a new conversation with an agent, optionally with the first user message:
```bash theme={"dark"}
gumloop sessions create agent_abc --input "Hello!"
```
Read the message from a file or stdin to avoid escaping:
```bash theme={"dark"}
echo "Summarize this thread:" | gumloop sessions create agent_abc --input-stdin -
```
```bash theme={"dark"}
gumloop sessions create agent_abc --input-stdin - < ./prompt.md
```
| Flag | Description |
| - | - |
| `--input` | Initial user message text. |
| `--input-stdin -` | Read the initial message from stdin. Mutually exclusive with `--input`. |
| `--session-id` | Pre-assign a client-side session ID (otherwise the server assigns one). |
| `--json` | Print the raw response payload. |
The output shows the new session ID, the agent it's running against, its state, the creation timestamp, and the last few messages. Hang on to the session ID — you'll need it to send follow-ups.
Don't have an agent ID yet? Run `gumloop agents list` to see all the agents you can talk to.
## Get a session
```bash theme={"dark"}
gumloop sessions get session_abc
```
Prints the session metadata and the last five messages. Add `--json` for the full transcript.
## Send a follow-up
```bash theme={"dark"}
gumloop sessions send session_abc --input "follow-up question"
```
Same input options as `sessions create`:
```bash theme={"dark"}
cat next-turn.txt | gumloop sessions send session_abc --input-stdin -
```
## Cancel a session
```bash theme={"dark"}
gumloop sessions cancel session_abc
```
Stops a session that's currently running.
The CLI returns the agent's final response after each `create` / `send` call but does not stream tokens as they're generated. If you need token-by-token streaming, use [`client.sessions.stream()`](/api-reference/sdk/python) from the Python SDK directly.
# Skills
Source: https://docs.gumloop.com/cli/skills
Upload, update, and download agent skills as files.
`gumloop skills` lets you manage agent [skills](/core-concepts/skills) as files on disk. Each skill is one or more files (markdown, JSON, anything) that an agent can read at runtime.
## List skills
```bash theme={"dark"}
gumloop skills list
gumloop skills list --search retrieval --limit 50
```
Prints `ID`, `NAME`, `TEAM`, `USAGE` (usage count), and `UPDATED`. If the response is paginated, the next cursor is printed at the bottom.
| Flag | Description |
| - | - |
| `--search` | Filter skills by query string. |
| `--server` | Filter to skills related to a specific MCP server ID. |
| `--limit` | Maximum number of skills to return. |
| `--cursor` | Pagination cursor from a previous list call. |
| `--json` | Print the raw response payload. |
## Create a skill
Upload one or more files as a new skill:
```bash theme={"dark"}
gumloop skills create ./my-skill.md
gumloop skills create skills/*.md
```
The skill is created with all of the provided files atomically. The new skill ID is printed on success.
## Update a skill
Replace the files attached to an existing skill:
```bash theme={"dark"}
gumloop skills update skill_abc ./new-version.md
```
`update` is a **full replace**, not a merge. Any file that was attached to the skill but isn't in the new upload is removed. To add a file without losing the existing ones, pass all of them: `gumloop skills update skill_abc existing.md new.md`.
Grab the skill ID from `gumloop skills list`.
## Download a skill
```bash theme={"dark"}
gumloop skills download skill_abc
```
By default the file is written to the current directory under its original filename. Override the destination with `-o`:
| Flag | Description |
| - | - |
| `-o`, `--output` | File or directory to write to. Use `-` to write to stdout. |
| `--version-id` | Download a specific skill version. |
| `--json` | Print download metadata as JSON (path + bytes). |
```bash theme={"dark"}
gumloop skills download skill_abc -o ./local-name.md
gumloop skills download skill_abc -o - # write to stdout
gumloop skills download skill_abc --version-id skv_xyz
```
# Agent access
Source: https://docs.gumloop.com/core-concepts/agent_access
Agents have exactly **two roles**: **Owners** manage the agent, **Users** run it. Everything on this page is configured from the **Access** tab of the agent.
## Owner vs. User at a glance
| | Owner | User |
| - | :-: | :-: |
| Run the agent and start tasks | | |
| See instructions, model, connectors, skills, knowledge, subagents, secret names | | Only what Owners choose to show |
| Edit any of the above | | |
| Create their own triggers | | Only if Owners allow it |
| Manage every trigger on the agent, including other people's | | |
| Add/remove Owners and Users, change General Access | | |
| Set User Permissions and Task Visibility | | |
| See every task on the agent | | Depends on Task Visibility |
| Delete the agent | | |
As an **Owner** you tune exactly what Users can see and what they can create on the agent — and you can add as many Owners as you like to share that control.
![Access tab showing Owners, Users, General Access, File Sharing, Task Visibility, and User Permissions]()
***
## Give someone access
Everyone below is added from the **Share** button at the top of the agent, which opens the **Share This Agent** modal. The same controls also live in the **Access** tab of the agent configuration.
**Share** → type their email in **Add people** → pick the role next to the **Share** button → **Share**.
* *Can manage this agent* = Owner
* *Can use this agent* = User
A direct email grant sticks: it keeps working even if General Access is lowered later.
Instead of adding people one by one, set **General Access** in the Share modal. Everyone who comes in this way is a **User** — there is no role picker.
![Share This Agent modal with the General Access dropdown open, showing Restricted, Organization, and Anyone]()
| Setting | Who can use the agent |
| - | - |
| **Restricted** | Only Owners and people added by email (personal agents only). |
| **Team** | Everyone in the team the agent lives in. |
| **Organization** | Everyone in your organization. |
| **Anyone** | Anyone with the link, including people without a Gumloop account. |
Agents that live in a team cannot be **Restricted** — Team is the floor.
Click the role dropdown next to a person in the Share modal (or the Access tab):
* **Promote to Owner** on a User
* **Demote to User** on an Owner
The last Owner cannot be demoted or removed. Add a second Owner first.
***
## User permissions
Per-agent switches that control what **Users** see and what they can do with the agent. Owners always see everything.
![User Permissions section listing the per-agent User settings, each set to Show or Hide]()
| Setting | Show means the User can |
| - | - |
| **Show Instructions** | Read the instructions the agent follows (read-only). |
| **Show Model** | See which model the agent runs on. |
| **Show Connectors** | See the connected apps the agent can use. |
| **Show Skills** | See the skills the agent can use. |
| **Show Knowledge Sources** | See the knowledge sources the agent can search. |
| **Show Subagents** | See the other agents this agent can call. |
| **Show Secrets** | See the **names** of the secrets the agent can use. |
| **Create triggers** | Create and edit their own triggers (**Allow** / **Don't allow**). |
| **Make a copy** | Duplicate the agent for themselves (**Allow** / **Don't allow**). |
Three rules worth remembering:
* **Visible is not editable.** Showing the instructions lets a User read the prompt, never change it.
* **Hiding something does not disable it.** Hide Connectors and the agent still uses Gmail — the User just doesn't see it listed.
* **Permissions are per agent, not per person.** Everyone with User access gets the same view.
Out of the box every visibility setting is **Show**, and **Create triggers** and **Make a copy** are **Allow**. Organization admins can ship different defaults with [Agent Default Settings](/enterprise-features/agent_default_settings).
If you switch **Create triggers** to **Don't allow** while Users already have triggers, Gumloop asks what to do:
* **Keep running** — they keep firing. Users cannot create, edit, or activate triggers, but can still view, deactivate, and delete their own.
* **Disable them** — they are switched off.
Owners can still manage those triggers from the **Triggers** tab. Allowing creation again does **not** reactivate disabled triggers.
When **Make a copy** is allowed, a User can duplicate the agent and becomes the Owner of their copy. The copy carries the **whole configuration** — instructions, model, connectors, skills, knowledge, subagents — even the parts your visibility settings hide from them, so treat copying as a separate decision from what a User can see. Turn it off if the agent's setup should not leave your control.
Copying applies to the custom agents you build. [Gumball](/core-concepts/gumball) and Gumloop's built-in agents cannot be copied, and an organization custom role that restricts agent modification blocks copying too.
**Example setup — an internal support agent everyone talks to:** General Access **Organization**, *Show Instructions* **Hide**, *Show Connectors* **Show**, *Create triggers* **Don't allow**.
***
## Task Visibility
A **task** is one conversation with the agent.
![Task Visibility section with the dropdown open, showing Their tasks only and Team tasks]()
| Option | What Users see |
| - | - |
| **Their tasks only** | Each User sees only the tasks they created. |
| **Team tasks** | Users can **read** tasks created by team members. Continuing someone else's task still requires Owner access. |
* This setting only exists on **team agents**, and new team agents default to **Team tasks**.
* On a personal agent, Users see only their own tasks, so the setting is hidden.
* Owners always see every task on either kind of agent, and any task can also be shared separately.
Seeing a task includes its task-linked artifacts. It never grants access to another person's private persistent workspace files.
***
## File sharing
**Default behavior** sets sharing for every file the agent generates.
![File Sharing section with the Default behavior dropdown open, showing Default, Organization, and Anyone]()
| Option | Generated files are shared with |
| - | - |
| **Default** | Whoever can see the task and the agent — a file created in a team task is visible to that team. |
| **Organization** | Everyone in your organization. |
| **Anyone** | Anyone with the link. |
See [Agent Artifacts](/core-concepts/agent_artifacts).
***
## Requesting and claiming access
A User who needs to manage the agent opens the **⋮** menu in the agent header and chooses **Request Owner access**, then picks which Owner receives it. That Owner approves or denies it from their inbox. See [Request Owner Access](/help/sharing/request-owner-access).
If an agent's Owners are unavailable, an organization admin in the same organization can manage it through administrative access and claim durable ownership. Claiming does not require every existing Owner to be gone: it changes the canonical creator and adds an Owner grant, and existing Owners remain. See [Claim an ownerless agent](/help/sharing/claim-an-ownerless-agent).
Organization admins can reach any agent in the organization through their admin override, even without a grant. Admin access is **not** the same as being an Owner — that's why **Claim Ownership** exists.
***
## FAQ
They no longer apply to agents. An editor becomes an **Owner**; a viewer or use-only person becomes a **User** whose visibility you tune with User Permissions. Skills still use Editor, Viewer, and Use Only. See [Sharing a skill](/core-concepts/skills#sharing-skills).
No. Every User Permission is about seeing, not editing. Editing the agent requires Owner.
Not today. User Permissions are per agent, not per person. If one person needs more, make them an Owner, or make a copy of the agent with different settings.
An agent always needs someone who can manage it. Add a second Owner first, then demote or remove the original.
An organization admin can open it and use **Claim Ownership** to take it over.
***
## Related
The agent builder, tab by tab.
Who can create triggers, and what happens when you turn that off.
Quick answer with the eight settings.
Owner vs User, and roles on skills.
# Agent artifacts (files)
Source: https://docs.gumloop.com/core-concepts/agent_artifacts
How agent-generated files are versioned, shared, hosted, and made interactive
When your Gumloop agents generate files during a conversation, those files are saved as **artifacts**. Reports, spreadsheets, images, code files, HTML dashboards: anything your agent creates can be viewed, downloaded, shared, and version-tracked directly from the chat.
## How artifacts work
When an agent generates a file in its sandbox (using code execution, data processing, or any tool that produces a file), it exports the file using a built-in export tool. The export:
The file is written to secure cloud storage.
Gumloop records a versioned artifact for it.
Preview thumbnails and representations are built.
The file appears as a rich card in the conversation.
You don't need to configure anything. Agents automatically export files they create, and artifacts appear inline in the conversation as they're generated.
## Viewing artifacts
When an agent exports a file, it appears as a card in the chat message showing the filename, file type icon, and a thumbnail preview (for supported types). Click the card to open a side panel preview without leaving the chat.
Each artifact has its own shareable page at a unique URL. The viewer page shows:
* Full-width file preview
* Filename, file type, and size
* Who created it and which agent generated it
* Links to view the source chat and agent (if you have access)
All files from a conversation are listed in the **Files** section of the chat sidebar. Click any file to preview it, open it in a new tab, copy its link, or download it.
On mobile, tapping a file card opens the viewer page in a new tab instead of a side panel, and auto-preview of new files is disabled so it doesn't interrupt the chat.
## Supported preview types
Gumloop can render inline previews for many file types:
| File Type | Preview |
| - | - |
| **HTML** (.html) | Interactive sandboxed preview |
| **Images** (.png, .jpg, .gif, .webp, .svg) | Native image viewer |
| **PDF** (.pdf) | PDF viewer |
| **Spreadsheets** (.csv, .xlsx, .xls) | Spreadsheet viewer |
| **Presentations** (.pptx, .ppt) | Slide viewer or PDF preview |
| **Text & Code** (.txt, .md, .py, .js, .json, etc.) | Syntax-highlighted text viewer |
| **All other files** | Download prompt with file size |
There is no hard limit on the size of a file an agent can create, but files larger than 50 MB cannot be previewed inline and are shown as download-only.
## Actions
From the viewer page or the in-chat card, you can perform several actions on an artifact:
![Artifact options menu showing Share, Copy link, and Download actions]()
| Action | Description |
| - | - |
| **Download** | Download the original file to your device |
| **Share** | Open the share dialog to manage who can access the file |
| **Copy link** | Copy a shareable URL to your clipboard |
| **Open in new tab** | Open the dedicated viewer page |
| **Version history** | View all versions of the file |
| **Full screen** | Available for HTML artifacts only |
## Automatic versioning
When an agent exports a file with the **same filename** multiple times in the same conversation, Gumloop automatically creates new versions instead of overwriting. This gives you a full history of how a file evolved during the conversation.
![Version history panel showing Version 2 and Version 1 with timestamps and file sizes]()
Each version shows:
* **Version number** (v1, v2, v3, etc.)
* **Timestamp** of when it was created
* **File size**
Click any version to view it. The latest version is always shown by default.
Agents are instructed to keep the same filename and let the system handle versioning. If you see files like `report_v2.pdf` instead of version 2 of `report.pdf`, you can update your agent's instructions to tell it not to rename files for versioning.
## Sharing & access control
You can control who can view, download, and manage each file.
### Share dialog
Click **Share** from the options menu to open the share dialog:
![Share this artifact dialog with the General Access dropdown open, showing Team, Organization, Password Protected, and Anyone]()
You can:
* **Add specific users** by email
* **Set General Access** to control broader visibility
### General Access Levels
| Level | Who Can Access |
| - | - |
| **Restricted** | Only you and explicitly shared users (personal artifacts only) |
| **Team** | Everyone in the team the artifact lives in (team artifacts only) |
| **Organization** | All members of your organization |
| **Password Protected** | Anyone with the link *and* the password, including people without a Gumloop account |
| **Anyone** | Anyone with the link, including people without a Gumloop account |
### Password protected artifacts
**Password Protected** sits between **Restricted** and **Anyone**: the link alone is not enough, the viewer also has to type the password you set.
![Artifact share dialog with General Access set to Password Protected, showing the Password field and the note that users added to this artifact or its agent won't need the password]()
Open **Share**, then pick **Password Protected** under **General Access**.
Type a password in the **Password** field and click **Save**. Passwords are 6 to 256 characters. An artifact cannot be Password Protected without one.
Use **Copy share link** for the link, and pass the password along however you normally share secrets.
**Who has to type the password**
| Viewer | Needs the password? |
| - | - |
| You, and the artifact's owners | No |
| People added to the artifact by name | No |
| People added to the artifact's agent by name | No |
| Everyone else with the link, signed in or not | Yes |
People who would normally reach the file by being in the team or organization behind the agent are prompted for the password like any other link visitor.
When the password is needed, the artifact opens on an unlock screen ("This artifact is password protected") with a **Password** field and an **Unlock** button. Protected HTML artifacts render normally once unlocked.
24 hours. After that the viewer is asked for the password again.
Changing the password ends every existing unlock immediately, so anyone still viewing has to enter the new one. Switching **General Access** away from **Password Protected** deletes the stored password along with the protected link.
Repeated wrong guesses are throttled, so guessing stops once the limit is reached. Correct unlocks are unaffected.
Yes. Anyone who can change the artifact's General Access can reveal the saved password in the share dialog, so you can resend it without resetting it.
Yes. A [hosted URL](#hosting-artifacts-on-a-custom-domain) is another address for the same artifact, so the password prompt applies there too.
**External password-protected artifact sharing** is a [Custom Role](/enterprise-features/user_groups#features-tab) permission. If your role does not allow it, saving a password-protected link is blocked and you are shown who to ask; an admin can turn it on for the role.
### Default file sharing
Each agent has a **Default File Sharing** setting that controls how new artifacts are shared when created. You can configure this in **Access → File Sharing → Default behavior**:
| Setting | What Happens |
| - | - |
| **Default** | Inherits access from the task and agent. Files attached to a task are visible to people who can read that task; team membership alone does not expose files from a task they cannot read. Agent Owners can read task-linked artifacts, including those from personal agents. |
| **Organization** | Files are shared with your entire organization |
| **Anyone** | Files are publicly accessible via link |
The default sharing setting applies to **new** artifacts only. You can always change the sharing level of any individual artifact after it's created.
### Requesting access
If someone shares a file link with you but you don't have access:
* **Not signed in**: You'll see a prompt to create a Gumloop account
* **Signed in, no access**: You'll see a **Request Access** button that sends a notification to the file's owner or a team admin. If they have Slack connected, they can approve with a single click. The owner or a workspace admin can approve from their inbox, or with one click in Slack if they have Slack connected.
## Hosting artifacts on a custom domain
Every artifact is always reachable at its canonical `/artifacts/{id}` URL. On top of that, you can give an individual artifact its own subdomain on `gumloopartifacts.com`:
```text theme={"dark"}
your-artifact.gumloopartifacts.com
```
This is useful when you want to hand out a clean, memorable link — a dashboard, a report, or an interactive HTML artifact — without exposing the internal artifact ID.
The custom domain is an **alternate URL for the same artifact**, not a separate copy or a published snapshot. Access checks, version behavior, and credentials are identical on both URLs.
### Per-artifact domains
#### Enabling hosting
Hosting is configured **per artifact**, from the same **Share** dialog as General Access. Turn on **Custom Domain** and the artifact's URL appears below the toggle, with buttons to copy it or rename the alias.
![Share this artifact dialog with the Custom Domain toggle enabled and the artifact's gumloopartifacts.com URL shown]()
You need the same level of access that lets you change the artifact's General Access — **Owner** or **Editor** on that file.
When you enable hosting, Gumloop derives an alias from the artifact's filename: the extension is dropped, anything that isn't a letter or number becomes a hyphen, and the result is lowercased. If that alias is already taken, a suffix is added automatically so enabling never fails on a collision.
| Filename | Derived alias |
| - | - |
| `Q3 Pipeline Review.html` | `q3-pipeline-review` |
| `report.pdf` | `report` |
| `q3.html` | `q3-file` |
Very short names are padded to meet the three-character minimum, and long names are truncated.
#### Customizing the URL alias
You can rename the alias at any time while hosting is enabled. Aliases follow the same rules as [hosted pages](/core-concepts/hosted_pages#customizing-the-url-alias):
* 3–64 characters
* Lowercase letters, numbers, and hyphens only
* Must start and end with a letter or number
* Must be unique across Gumloop
Certain aliases like `admin`, `api`, `app`, `auth`, `beta`, `docs`, `gumstack`, `help`, `localhost`, `mcp`, `sandbox`, `staging`, `support`, `ws`, and `www` are reserved and cannot be used.
Renaming frees the old alias immediately. Anyone holding the previous link will get a dead URL, and the old alias becomes available for someone else to claim.
#### Authentication and sign-in
The custom domain is a different origin from the main Gumloop app, so visitors who aren't already signed in there go through a handoff:
A visitor opens `your-artifact.gumloopartifacts.com`.
The page resolves the alias to the artifact it serves.
If the artifact isn't public, the visitor is sent to Gumloop's sign-in.
On success, a one-time token is exchanged for a session on the artifact domain and the visitor lands back on the artifact.
The handoff validates the return URL against the artifact's own hosted URL, and credentials are never passed through the subdomain directly.
Artifacts whose General Access is set to **Anyone** open without a sign-in, exactly as they do on the canonical URL.
#### Versions and access
* **No version pin.** The custom domain always serves what `/artifacts/{id}` serves, so a new version of the artifact appears on both URLs at once.
* **No extra sharing.** Hosting does not widen access. A **Restricted** artifact stays restricted on its custom domain — the URL being public doesn't make the file public.
* **Canonical links are unchanged.** Links generated by agents and the Gumloop UI still point at `/artifacts/{id}`. The custom URL is offered alongside it for copying and sharing.
#### Disabling hosting
Disabling hosting immediately stops the subdomain from resolving. The alias stays reserved for that artifact, so you can turn hosting back on later with the same URL. Deleting the artifact also stops the subdomain from resolving.
Enabling, renaming, and disabling artifact hosting are all recorded in [audit logs](/enterprise-features/audit_logging).
### Organization domains
Organization admins can claim one organization-level domain for artifact hosting from [**Organization Settings**](https://www.gumloop.com/settings/organization/general).
In [**Organization Settings**](https://www.gumloop.com/settings/organization/general), open the **Custom artifact domain** section, select **Add domain**, and enter a domain such as `yourdomain.com`. New artifacts will be shared on this domain once its DNS records are verified. The **Add domain** button stays disabled until the domain is valid.
Add these records at your domain provider. DNS changes can take up to 48 hours.
| Type | Host | Value |
| - | - | - |
| TXT | `_gumloop-verify.` | `gumloop-verify=` |
| CNAME | `*.` | `cname.vercel-dns.com` |
Verification runs against those records; use **Re-check DNS** to check again, or **DNS records** to see the values you need.
New artifacts are automatically shared on your own domain instead of gumloopartifacts.com.
You can paste the bare domain; casing, `http://` or `https://` prefixes, paths, and a leading `*.` are cleaned up for you. Gumloop-owned and other reserved suffixes are rejected, as is a domain another organization has already claimed. Each organization can have one domain at a time, so remove the current domain before adding a different one.
#### Domain status
| Status | What it means |
| - | - |
| **Active** | DNS verification succeeded. |
| **DNS records not found** | The required DNS records were not found. |
| **Waiting for DNS to resolve** | DNS is still resolving. |
| **Verification failed** | DNS verification did not succeed. |
Select **Remove** to deregister the domain. The removal confirmation warns that artifact links on the domain will stop working.
#### Hosting on the organization domain
Once the domain is **Active**:
* Newly exported artifacts from the organization's agents are automatically given an alias at `https://.`, replacing the corresponding `.gumloopartifacts.com` URL.
* The alias is derived and collision-suffixed using the same behavior documented for [`gumloopartifacts.com` aliases](#customizing-the-url-alias).
* Auto-hosting is best effort, so a hosting failure never fails the artifact export.
* Auto-hosting is skipped when hosting was explicitly disabled for the artifact or when the artifact already has a hosted alias. An explicitly disabled artifact is not silently re-enabled.
The per-artifact **Custom Domain** toggle in the Share dialog is unchanged. When your organization has an active domain, that toggle hosts the artifact on the organization domain. Its description reads: “Give this artifact its own URL on ``. Your sharing settings still apply.”
A **Restricted** artifact stays restricted on the organization domain.
### Importing an artifact from a link
An agent can import an artifact from its link — a canonical `https://gumloop.com/artifacts/...` link, a `gumloopartifacts.com` link, or a link on your organization's own artifact domain — and pull that file into its sandbox.
When a specific version is named, it is used ahead of any version in the link. A link the agent can't resolve or doesn't have access to comes back as simply not found or not accessible, without revealing whether the artifact exists.
## HTML artifacts
HTML files get special treatment. Agents can generate fully interactive HTML pages, dashboards, and web applications that render directly in the viewer.
### Full screen mode
HTML artifacts support a **full screen mode** that hides the toolbar and gives the artifact the full browser window. This is useful for dashboards, interactive tools, and presentations. Click the full screen button in the viewer toolbar to enter full screen.
### Security
HTML artifacts run in a **strict security sandbox**. This is important because agents can generate arbitrary HTML and JavaScript. The sandbox:
* Blocks access to your Gumloop session, cookies, and storage
* Blocks direct network requests (fetch, XHR, WebSocket)
* Prevents opening new windows or popups
* Automatically strips sensitive headers from any proxied requests
**Safe requests** (GET, HEAD) from within an HTML artifact are automatically proxied. **Unsafe requests** (POST, PUT, DELETE) require your explicit approval via a confirmation dialog.
## Interactive artifacts (live data)
Interactive artifacts are HTML files that pull **live data from your connected integrations** every time you open them. Instead of showing a static snapshot from when the agent ran, the data refreshes on each view using your own credentials.
### How they work
When you ask an agent to build something that needs live data, it creates two things:
1. **An HTML file** with the layout, styling, and JavaScript for the UI
2. **One or more Python data scripts** that fetch data from your integrations at view time
You don't need to know how the two are wired together. Just ask your agent for a dashboard, report, or tool that uses your connected apps, and it handles the rest.
The HTML calls `fetch('/gumloop/data/...')` to request data. Gumloop intercepts these requests, runs the matching Python script in a secure sandbox, and returns the results as JSON. The HTML then renders the data.
### Integration consent
When you open an interactive artifact for the first time, you'll see a consent overlay that lists every integration the file can access and the specific actions it can perform.
![Integration consent overlay showing the file is requesting permission to use Slack with 1 tool, with an I acknowledge, continue button]()
**You must approve before any scripts run.** This is a deliberate security step. It means:
* You always know exactly which integrations a file will use
* No data is fetched until you explicitly approve
* If someone shares a file with you, you decide whether to grant it access to your accounts
Consent is per-session. If you refresh the page, you'll see the consent overlay again. This is intentional: it ensures you're always aware of what a file is doing.
### Your credentials, your data
Opened inside Gumloop, an interactive artifact runs on the **viewer's** connected accounts, not the creator's. This is a core design choice.
If your teammate creates a "Team Slack Dashboard" and shares it with you:
* When **they** open it, they see data from **their** Slack account
* When **you** open it, you see data from **your** Slack account
* The file creator never sees your data and you never see theirs
Each time a script runs, Gumloop mints a short-lived, scoped token that only allows the specific integrations and tools that the file declared. The token expires in 5 minutes and is invalidated as soon as the script finishes. Your credentials are never exposed to the HTML itself.
**On a [hosted page](#hosting-artifacts-on-a-custom-domain) your own connections are not used.** Opening an artifact through its hosted URL — a custom domain or `gumloopartifacts.com` — runs its scripts on the **integrations the artifact's owner pinned to the agent** instead, so everyone who visits sees the same data. A hosted artifact shared publicly gets no integrations at all.
If you build an artifact for people outside Gumloop, connect the apps it needs **on the agent** rather than expecting each viewer to bring their own. Opening the same artifact inside Gumloop still uses your own accounts.
**Password Protected** counts as shared publicly here: the password controls who can open the file, but the agent's pinned integrations are not used when its scripts run.
If you haven't connected a required integration, you'll see a setup prompt asking you to connect it before the file can load. The artifact won't execute until all required integrations are connected.
### What can you build?
Anything that combines a UI with live integration data. Here are some example prompts:
| What you want | Example prompts |
| - | - |
| **Dashboards and monitors** | "Build me a dashboard that shows my open Linear issues, today's Google Calendar events, and my unread Gmail count."
"Create a live team status page that pulls from Slack, Google Sheets, and HubSpot."
"Make a monitoring page that shows my recent GitHub pull requests and their CI status." |
| **Interactive tools** | "Create an HTML form where I can compose a message, pick a Slack channel from a dropdown, and send it."
"Build a tool that lets me search my Google Drive files and preview them."
"Make a form that creates a new Linear issue with title, description, and assignee fields." |
| **Reports with live data** | "Generate a weekly summary report that pulls my Gmail activity, calendar meetings, and Slack messages from the past 7 days."
"Create a CRM overview that shows my HubSpot deals pipeline with real-time data." |
| **Multi-integration pages** | "Build a meeting prep page that, given a calendar event, pulls the attendee list from Google Calendar, finds their LinkedIn profiles, and shows recent email threads." |
The more specific you are about which integrations and data you want, the better the result. Tell the agent exactly which tools you want it to pull from.
### How teams use interactive artifacts
Interactive artifacts are especially powerful for teams because the same file works differently for each person.
A team lead creates a "My Open Tasks" dashboard and shares it with the whole team. Each team member opens the same link but sees their own tasks, their own calendar, their own inbox. One artifact, personalized for everyone.
An ops lead creates a "Post to #announcements" tool with a form. Anyone on the team can use it to send formatted messages to the channel without needing Slack open.
Create a "New Hire Status" page that shows a new team member their onboarding checklist from Linear, upcoming meetings from Google Calendar, and key documents from Google Drive. Share the link as part of onboarding.
Build a report template that pulls live data from your CRM. Share it with stakeholders, and each person sees data scoped to their access level.
### Download buttons
An interactive artifact can also hand you a **file**, not just a screen of data. Ask for it and the agent adds a button that builds the file when you click it — an Excel export of whatever the dashboard is showing, a filtered CSV, a generated PDF — and your browser saves it like any other download.
Because the file is built at click time, it reflects the data as it is right then, and it is never stored in Gumloop: it goes straight to your machine.
| Example prompt | What you get |
| - | - |
| "Add an **Export to Excel** button to this dashboard." | A button that builds an `.xlsx` of the current numbers. |
| "Let me download the filtered rows as CSV." | A button that exports whatever your filters selected. |
A download runs a script, so it takes a few seconds and costs credits like any other data load. If the script produces nothing, the artifact shows an error instead of saving a file.
### Credits
Every time a data script runs, the **viewer** is charged credits for the sandbox execution time. The creator is not charged when someone else opens their file.
This means:
* You pay for what you use, not for what others view
* If you share a dashboard with 10 people, each person pays for their own data loads
* If you have no credits remaining, scripts won't execute and you'll see an error
### Refreshing data
Data scripts run each time you open the artifact. If the HTML includes a refresh button or auto-refresh timer, each refresh triggers a new script execution.
Keep in mind:
* Each execution costs credits
* Each execution creates a fresh sandbox (no state carried between refreshes)
* Scripts have a 5-minute timeout for long-running queries
### Error handling
If a data script fails (the integration is disconnected, the API returns an error, or the script times out), the HTML receives an error response. Well-built artifacts will show a friendly error message. If the agent didn't include error handling, the section may simply be blank.
Common causes and fixes:
| Why it failed | What to do |
| - | - |
| You haven't connected the required integration | Connect the required integration. |
| Your integration token has expired | Reconnect in Settings > Integrations. |
| The script timed out (queries that scan large amounts of data may exceed the 5-minute limit) | Reduce the data scope so the query finishes inside the 5-minute limit. |
| You've run out of credits | Top up credits. |
## Files page
All your files are accessible from a dedicated **Files** page at [gumloop.com/personal/files](https://www.gumloop.com/personal/files). This page provides a centralized view of every artifact you've created or received across all your agent conversations.
The Files page has three tabs for filtering your view:
| Tab | What It Shows |
| - | - |
| **Mine** | Files you created (from your own agent conversations) |
| **Shared with me** | Files that others have shared with you directly or via your organization |
| **Organization** | All files visible to your organization |
![Files page showing the Shared with me tab with file cards grouped by date]()
You can search files by name, filter by media type, and sort by date. Each file card shows a thumbnail preview, filename, file type, and version number.
## Workspace files (persistent across conversations)
By default, files created during an agent conversation are scoped to that conversation. However, agents can also work with **workspace files** that persist across conversations.
Files saved to the `/home/user/.workspace/` directory in the agent's sandbox are treated as **workspace-scoped artifacts**. These files are not tied to a single conversation — they persist and are available in future conversations with the same agent.
### How workspace scope works
Workspace files use two separate folders:
* **Shared agent workspace — `/home/user/.workspace/agent/`:** Available to project members with the appropriate file permissions. Members with read access can view its files; saving changes requires edit permission.
* **Personal workspace — `/home/user/.workspace/personal/`:** Private to you and persistent across your conversations with the same agent. Your personal workspace remains writable even when the shared workspace is read-only.
Non-project members do not receive the shared agent workspace; their workspace files use the personal workspace.
This is useful for agents that maintain ongoing project files, configuration, or reference data that should carry over between sessions.
Workspace files follow the same artifact system — they are versioned, previewable, and shareable just like conversation-scoped artifacts.
***
## Common questions
### Files and versions
Artifacts are stored securely in Google Cloud Storage. Files are accessible through the Gumloop viewer or via download. They persist as long as the conversation exists.
Yes. The file's **owner** (the person who ran the agent conversation that created it) or anyone with **editor** access can delete it. Deleting is a soft delete: the file is removed from your files list, search, filters, sharing, and API/SDK reads, but its stored versions are preserved behind the scenes. If the agent later regenerates a file with the same name, the file reappears with its version history intact.
### Sharing and access
Yes. You can either add them by email in the share dialog, or set General Access to "Anyone" to make the file accessible via link. Enterprise admins can restrict public sharing if needed.
These links only appear if you have access to the source agent. Artifact access does not automatically grant access to the agent that created it. Ask the agent owner to share the agent with you separately.
### Interactive artifacts
A **static** artifact is a regular file (PDF, image, CSV, or even a plain HTML page) that shows the same content every time you open it. An **interactive** artifact is an HTML file with attached data scripts that fetch live data from your integrations each time you open it. You can tell by whether you see a consent overlay when you open the file.
**Yours, inside Gumloop.** When you open an artifact in the app it runs with your own connected accounts, so you see your own data and the creator never has access to it.
On a **hosted page** (custom domain or `gumloopartifacts.com`) it is different: the scripts run on the integrations the owner pinned to the agent, never on the visitor's connections, and a publicly hosted artifact gets no integrations at all.
Both. Agents can build artifacts with forms and buttons that trigger write actions like sending a Slack message or creating a Linear issue. These actions run with your credentials and cost your credits, just like read operations.
No. HTML artifacts run in a strict sandbox that blocks access to your Gumloop session, cookies, localStorage, and all direct network requests. The only way the HTML can reach external services is through Gumloop's security proxy, which strips sensitive headers and blocks private network access.
Common fixes: (1) Check that all required integrations are connected in Settings > Integrations. (2) If a token has expired, disconnect and reconnect the integration. (3) Make sure you have credits remaining. (4) For very large queries, the script may have timed out (5-minute limit). Try asking the agent to reduce the data scope.
### Custom domains
Your artifacts keep working at their canonical URLs and their `gumloopartifacts.com` URLs. Nothing is served on the new organization domain until its status is **Active**.
No. An organization can claim one custom artifact domain at a time. Remove the current domain before adding a different one.
No. A custom domain is an alternate URL for the same artifact. A **Restricted** artifact stays restricted and uses the same access checks as its canonical URL.
Yes. Paste an artifact link into a chat and the agent can pull that file into its sandbox.
Links on that domain stop working. Canonical artifact URLs continue to work.
## Related documentation
Learn how to create and configure agents
Owners, Users, and file sharing on an agent
# Agent browser
Source: https://docs.gumloop.com/core-concepts/agent_browser
Give your agent a real Chromium browser to open sites, sign in, fill forms, and download files. Watch it live, replay every step, and hand it the keyboard when it needs you.
The agent browser is a real Chromium browser that runs inside your agent's cloud sandbox. With it, an agent can open any website, click and type like a person, sign in with saved logins, fill forms, and download files, including on sites that need JavaScript, a signed-in session, or a real browser to load.
You can watch the browser live from the chat, take over when the agent needs a human, and replay every browser step after the task finishes.
***
## What can the agent browser do?
Open pages, click, type, scroll, switch tabs, and read what is on screen, including JavaScript-heavy pages.
Type saved logins and 2FA codes into a site. The agent never sees the password. See [Browser Logins and Profiles](/core-concepts/browser_logins_and_profiles).
Sign-ins are saved to a browser profile at the end of each turn and restored on the next task.
When it hits a login, 2FA code, CAPTCHA, or purchase confirmation, the agent pauses and hands the browser to you.
Watch the browser live in the side panel, and replay a recording of every browser step afterwards.
Route traffic through a residential proxy so sites see a visitor from the country you pick.
Use the browser for sites and tasks no [connector](/core-concepts/credentials) covers. When a connector covers the app (Gmail, Salesforce, Notion, and so on), it is faster and more reliable than clicking through the site.
***
## How do I turn on the browser for an agent?
The browser is an ability you turn on per custom agent, from the **Browser** section of the agent's configuration.
Open the agent and find the **Browser** section in the configuration panel. When the browser is off, it reads **Give your agent a browser**.
![Browser section with the empty state Give your agent a browser and a Turn on button]()
The section expands to show the **Browser** toggle and its settings.
![Browser section turned on, with rows for Browser, Proxy, Browser profile, and 1Password, and a Login button]()
| Setting | What it does |
| - | - |
| **Proxy** | **Off** by default. Pick a country to browse as a visitor from that country. See [Proxy](#how-do-i-browse-from-another-country). |
| **Browser profile** | Whose saved sign-ins the browser starts with. See [Browser profiles](/core-concepts/browser_logins_and_profiles#browser-profiles). |
| **1Password** | Let the agent type logins from a 1Password vault. See [1Password](/core-concepts/browser_logins_and_profiles#1password). |
| **+ Login** | Bind a saved website login to the agent. See [Logins](/core-concepts/browser_logins_and_profiles#logins). |
Click **Save**. The browser is available from the next message.
Turning the browser off also turns off its proxy, browser profile, and 1Password settings. Logins you bound stay listed so you can still remove them.
### Which agents get the browser?
| Agent | Browser access |
| - | - |
| **New custom agents** | Turned on by default when the person who creates the agent is allowed to use the browser. |
| **Existing custom agents** | Off until someone turns it on in the **Browser** section. |
| **[Gumball](/core-concepts/gumball)** | Available whenever your role allows the browser. There is nothing to configure. |
If you do not see a **Browser** section at all, the browser is not available on your account yet.
### Why does it say "Turned off for your role"?
Your organization hasn't given your role access to the browser yet. **Reach out to your [organization admin](https://www.gumloop.com/settings/organization/members?role=admin)** and ask them to add the **Agent browser** feature to your role. Until they do, agents you run work without the browser.
#### For admins: turn on the browser for a role
On Enterprise organizations, the browser is controlled by the **Agent browser** feature in [Custom Roles](/enterprise-features/user_groups). It is off by default.
Go to [Settings > Organization > Custom Roles](https://www.gumloop.com/settings/organization/groups).
Click the role the person belongs to. To turn it on for everyone, open your default role (the one every new member joins, such as **Default Group**).
Open the **Features** tab, click **Add Features**, select **Agent browser**, and click **Add Features**.
![Custom role Features tab listing Agent browser under Agents]()
The change applies from the person's next message. No one needs to reconfigure their agents.
***
## How do I watch the agent use the browser?
As soon as the browser starts, a **Browser** panel opens on the right side of the chat. It has two modes, switched from the pill at the bottom of the panel.
**Live** streams the agent's browser as it works, with its real tab strip, **Back**, **Forward**, **Reload**, and an address bar.
![Live browser panel with a tab, back, forward, reload, the address bar, and a signed-in page]()
* While the agent is driving, the page has a blue glow.
* You can click and type directly in the page. Your clicks and typing go to the real browser.
* Type a URL or search terms in the address bar. Anything that is not a web address becomes a Google search.
* Open a new tab with **+** and switch tabs from the tab strip.
* If someone else in the chat is using the browser, you see a label with their name, such as *Max is using the browser*.
![Live browser panel with a blue glow around the page while the agent types into a login form]()
**Replay · N steps** plays back a recording of every browser step in the chat, as one timeline.
![Browser replay of a login page with the Live and Replay pill and playback controls for step back, step forward, play, scrubber, time, and speed]()
* Step back and forward between browser steps, play or pause, scrub, and change the playback speed.
* The tab strip and address bar replay with the clip, so you can see which page each step was on.
* Screenshots the agent took are marked on the timeline.
* Open the replay later from **Browser replay** under the agent's message.
Only one driver at a time. While a person is controlling the browser, the agent cannot run browser steps on the same page. During a handoff, only the person the browser was handed to can control it.
### When do recordings appear?
Every browser step is recorded. Recordings are attached when the turn finishes, so a running or paused turn never shows a half-finished clip. A very long step is cut off at the frame limit and marked **Truncated at the frame limit**.
Recordings from a [subagent](/core-concepts/agents) stay in that subagent's own chat; they are not copied into the parent chat.
***
## When does the agent ask me for help?
The agent hands the browser to you when it reaches something only you can do: a sign-in it has no login for, a 2FA or one-time code, a CAPTCHA it could not pass, an SSO button, approving on your phone, or confirming a purchase. This is a **browser handoff**. The agent pauses until you answer.
```mermaid theme={"dark"}
flowchart LR
A[Agent reaches a login or check] --> B{Can it finish alone?}
B -- Yes --> C[Agent continues]
B -- No --> D[Handoff card in chat]
D --> E[You type values in the card]
D --> F[You do it in the live browser]
D --> G[Skip]
E --> H[Agent types them in and continues]
F --> C
G --> I[Agent continues without it]
```
### What does the handoff card look like?
![Handoff card with Username and Password fields, a note that sensitive values can only be typed on the-internet.herokuapp.com, a Save login checkbox, and Skip and Continue buttons]()
| Part | What it means |
| - | - |
| **Status banner** | *Use the browser in the side panel, then continue. The agent is paused until you do.* |
| **Instructions** | What the agent needs, written by the agent. |
| **Fields** | Up to six inputs, such as a username, password, or one-time code. Password and code fields are sensitive. |
| **Sensitive values can only be typed on ``** | Sensitive values are locked to the exact host the browser was on when it asked. They cannot be typed anywhere else. |
| **Save login for ``** | Saves the username and password to your Vault so the agent can sign in next time without asking. Pick **Only me** or **My team** when both are offered. |
| **Skip** | Decline. The agent continues without your help. |
| **Open browser** / **Continue** | Open the live panel if it is closed, then continue once you have entered values or finished in the browser. |
### How do I answer a handoff?
Fill in the fields and click **Continue**. The agent receives sensitive values only as references, never as text. It types them into the page with a secure fill that checks the site first. The password field is masked in the live view, recordings, and screenshots.
![Agent steps showing the handoff resolved with Saved the login for the-internet.herokuapp.com as THE_INTERNET_HEROKUAPP_COM and sent it to the agent]()
Use the live panel to sign in, enter the code, or pass the check, then click **Continue**. The agent looks at the page and picks up from there. Use this for SSO buttons, CAPTCHAs, phone approvals, and purchase confirmations, where there is nothing to type.
When the chat runs in Slack, the handoff posts to the thread with buttons:
| Handoff | Buttons |
| - | - |
| With fields | **Enter the details** (opens a form), **I did it in the browser**, **I couldn't do it** |
| Without fields | **Open in Gumloop**, **I did it in the browser**, **I couldn't do it** |
Sensitive fields in the Slack form show the host they can be typed on. You can also open the browser in Gumloop, complete the step there, then hand it back from the thread.
The card resolves to one of: **Completed in the browser**, **Could not be completed in the browser**, or *Saved the login for `` as `` and sent it to the agent*.
Only the person whose message the agent is working on can answer its handoff. Everyone else in the chat sees the card as *waiting for* that person.
***
## How do I browse from another country?
Set **Proxy** in the **Browser** section to a country (**Browse from**). The browser then exits through a residential proxy in that country, so sites see a visitor from there. **Off** is the default.
* Each sandbox keeps one exit IP for its lifetime.
* The agent is told which country it browses from.
* Changing the proxy restarts the browser. Open tabs close, but sign-ins are kept.
* Proxy bandwidth is not billed separately.
***
## How does the agent stay signed in?
The browser remembers which websites it is signed in to with a **browser profile**. At the end of each turn, Gumloop saves any new sign-ins to the profile, and the next task starts already signed in, even in a brand-new chat.
![Chat where the agent reports it is signed in, with the browser panel showing a Secure Area page]()
When a saved session has expired, the agent signs back in with a [saved login](/core-concepts/browser_logins_and_profiles#logins) and the end-of-turn save keeps the new session. For profile ownership, importing your own browser's sign-ins, and 1Password, see [Browser Logins and Profiles](/core-concepts/browser_logins_and_profiles).
***
## Limits
| Limit | Value |
| - | - |
| **Window** | Desktop Chromium. Mobile and device emulation are not supported, so mobile-only checks cannot be tested. |
| **Handoff fields** | 6 per handoff |
| **Recording** | One clip per browser step, cut off at the frame limit |
| **Sign-in saving** | At the end of each turn, not mid-turn |
| **Incognito chats** | No browser profile is restored or saved |
The browser shares the agent's [Code Sandbox](/core-concepts/agent_sandbox_and_secrets), so the sandbox's limits apply too.
***
## How is the browser billed?
The browser has no separate charge. Browser steps aren't billed as tool calls, and the proxy, recordings, and live view are free. A browser task is billed like any other [agent chat](/core-concepts/credits):
* **Compute:** 5 credits per minute the agent spends working in the browser.
* **Chat & Reasoning:** the model reading pages and screenshots.
Time spent waiting on you during a handoff isn't billed.
***
## How are passwords kept safe?
No. Login passwords, 2FA setup keys, and sensitive handoff answers are never shown to the agent and are not stored in the sandbox environment. The agent refers to them by name, and Gumloop types them in for it. 2FA codes are generated by Gumloop at the moment of typing, so the setup key never enters the sandbox. The **username** is not secret: the agent can read it.
Every secure fill is checked against the login's site before anything is typed: the scheme, port, and host of the frame the field lives in must match. A mismatch types nothing and tells the agent to ask you instead. Handoff answers are locked to the exact host they were asked on, and the card shows you that host before you type.
No. Password and code fields are masked before and after typing, including if the site has a show-password toggle, and a screenshot is skipped if a typed field cannot be masked. Values are also kept out of chat transcripts and logs.
These protections defend against a web page steering the agent. They are not a hard boundary against an agent that sets out to extract a value from its own sandbox. Treat every login an agent can type as usable by that agent, and bind only the logins it needs. For tighter control, restrict **Agent browser** with [Custom Roles](/enterprise-features/user_groups).
***
## FAQ
Check three things: the **Browser** section is turned on and saved, your role allows **Agent browser**, and the task actually needs a browser. If a [connector](/core-concepts/credentials) can do the job, the agent may use it instead. To force the browser, ask explicitly, for example *"Use your browser to open ..."*.
If your organization uses Custom Roles, **Agent browser** is denied by default and is checked for whoever runs the agent, not whoever configured it. A teammate whose role lacks it gets an agent without the browser. See [Why does it say "Turned off for your role"?](#why-does-it-say-%E2%80%9Cturned-off-for-your-role%E2%80%9D) for what to ask your admin and how they turn it on.
Yes. Click into the **Live** view and use the page. While you hold control, the agent cannot run browser steps on that page, so it is best to take over when the agent asks with a handoff.
The browser restarts when the proxy setting changes or when it switches to a different browser profile. Tabs close; sign-ins in the profile are kept. A tab that stops responding for about a minute is also closed, and the agent is told so it does not retry the same page.
The usual causes:
* **The chat was incognito.** Incognito chats never save or restore sign-ins.
* **Someone else ran it.** With the default **User-owned** profile, each person has their own sign-ins, so a teammate's run starts from their profile, not yours.
* **The site signed the browser out.** Sessions expire. [Give the agent a login](/core-concepts/browser_logins_and_profiles#how-do-i-give-an-agent-a-login) so it can sign back in on its own.
See [Browser profiles](/core-concepts/browser_logins_and_profiles#browser-profiles) for how sign-ins are saved.
No. Mobile viewports, mobile user agents, and touch emulation are not supported. The agent reports mobile checks as not testable rather than as site failures.
Most of the time. When it cannot, it hands the browser to you with a handoff so you can solve it in the live view.
***
## Related
Saved logins, 2FA, browser profiles, importing sign-ins, and 1Password.
The sandbox the browser runs in, and the Vault.
Approvals and questions that pause an agent.
Grant or restrict Agent browser per role.
# Agent performance
Source: https://docs.gumloop.com/core-concepts/agent_performance
Insights, Evaluations, and Tasks for a single agent
**Performance** in the agent sidebar answers three questions about one agent: what is it costing, is it doing good work, and what has it actually been doing. Those are the three tabs.
This page is the map of that screen. Two of the things you switch on from it — **Evaluations** and **Reflections** — have their own guides, linked below.
![Performance page with the Insights tab showing Credits Over Time, Credits by, Usage by, overview metrics, impact report, Evaluations, and Reflections]()
Performance covers the tasks you are allowed to see. Owners see everything on the agent; a User's numbers follow the agent's [Task Visibility](/core-concepts/agent_access#task-visibility). For organization-wide reporting, see [Insights](/enterprise-features/organization_insights).
## Insights
Pick a date range, and optionally **Compare to previous period** to see the change.
The chart's **interval** is chosen for you to suit the range, and you can switch to any other interval that still makes a readable chart:
| Range you picked | Default interval | Other intervals you can pick |
| - | - | - |
| Under 2 hours | 15 minutes | — |
| 2 hours to 3 days | Hour | 15 minutes (up to 1 day) |
| Up to 31 days | Day | Hour (up to 7 days) |
| Up to about 3 months | Week | Day |
| Longer | Month | Week (up to 2 years) |
Intervals that would produce a single bar or thousands of them are not offered, so a short range cannot be charted by month and a year cannot be charted by the hour.
**Credits Over Time** charts three series together — credits, tasks, and cost per task — so you can tell a spike in spend apart from a spike in usage.
The overview on the right gives you the headline numbers for the range:
| Metric | What it counts |
| - | - |
| **Credits** | Credits the agent consumed. |
| **Tasks** | Tasks started with the agent. |
| **Avg. credits per task** | Credits divided by tasks — the number to watch when tuning cost. |
| **Members** | Distinct people who used it. |
Under the chart, two breakdown tables:
* **Credits by** — **Models**, **Sources** (where tasks came from, such as a trigger, Slack, or the app), **Members**, and **Connectors**.
* **Usage by** — tool calls and reads per **Connector**, **Skill**, **Artifact**, **Subagent**, and **Knowledge Source**.
**Reading it.** High credits with few tasks usually means long tasks on an expensive model: check *Credits by Models* and consider a cheaper model or a lower [summarization trigger](/core-concepts/agents#ai-advanced-settings). Lots of tasks with almost no connector usage often means people are asking the agent things it has no tools for.
### Task outcomes
Under the breakdowns, **Task outcomes** charts how tasks ended over time, on the same range and interval as the rest of the tab:
| Outcome | What it means |
| - | - |
| **Got done** | The agent finished what was asked. |
| **Needed a human** | The agent got there, but only after a person stepped in. |
| **Didn't get done** | The task ended without the ask being met, including tasks that errored out. |
Read it next to **Credits Over Time**. Cost falling while *Didn't get done* rises is a cheaper model doing worse work, not a saving. A steady band of *Needed a human* usually points at a missing tool or an instruction gap for one specific kind of request.
### What changed, and what it did to cost
Markers along the bottom of **Credits Over Time** show when the agent was changed, so you can line a change up against the spend and volume around it. Each marker covers one interval of the chart; select one to see the changes inside it, newest first, with who made each one:
* **Agent created**
* **Model changed** — the model it moved to, and the one it came from
* **Instructions edited**
* Connectors, [skills](/core-concepts/skills), and [knowledge sources](/core-concepts/brain) added or removed
* [Reflections](/core-concepts/reflections) the agent applied — select one to open the suggestion
When enough data exists on both sides, the card also shows how **cost per task** moved after the change, so a model swap's effect is visible without doing the arithmetic. It appears only once both the before and after windows have completed, and it stays quiet when the movement is within the agent's normal noise.
A change made before the agent ran any tasks is marked **No tasks yet**, since there is nothing yet to compare against.
### Impact report
Have Gumloop send this summary out on a schedule, by **Email** or to a **Channel**, to the people you add under **To**. Useful for keeping a team lead in the loop without giving them the builder.
### Evaluations and Reflections
Both features live in the summary panel on the right of this page, and both are switched on from here:
| Feature | What it does | Turn it on | Full guide |
| - | - | - | - |
| **Evaluations** | Grades completed tasks against criteria you write, so a regression shows up as a failed check instead of a complaint. | **Set up Evaluations** | [Evaluations](/core-concepts/evaluations) |
| **Reflections** | Has the agent review its own past tasks and suggest instruction changes you accept or dismiss. | **Enable Reflections** | [Reflections](/core-concepts/reflections) |
Everything else about them — criteria, tags, data points, schedules, reports, and the API — is in those two guides.
## Evaluations tab
Once evaluations are on, this tab shows the grades: how completed tasks scored against your criteria, which ones failed, and the trend over time. That is where you catch a regression after changing the instructions or the model.
## Tasks tab
The full task history for the agent, filterable, with who started each one, where it came from, and what it cost. Open a task to read the whole thing. This is the fastest way to answer "what did it actually do yesterday?" and to spot the pattern behind a bad evaluation score.
## Related
Define criteria and grade the agent's answers.
Let the agent propose its own improvements.
What the agent is charged for.
The same picture across every agent and team.
# Code sandbox & secrets
Source: https://docs.gumloop.com/core-concepts/agent_sandbox_and_secrets
Secure code execution and credential management for your AI agents.
The Code Sandbox gives your agent the ability to execute Python code and shell commands in a secure, isolated cloud environment. It is **natively enabled** on all agents with no configuration required.
***
## What the sandbox can do
Data analysis, visualizations, computations, file processing, API calls, and more.
File operations, package installation, running scripts, and system commands.
Create, modify, and organize files within the sandbox filesystem.
Move files between your Gumloop storage and the sandbox environment.
***
## How it works
Each conversation runs in its own **secure cloud sandbox** (an isolated VM). The files your agent creates while working stay with that conversation, so if you reopen the chat later they are restored automatically.
Anything that should outlive a single chat lives in one of two durable layers that carry over across all conversations with the same agent: the shared **package environment** and the agent's **workspace folders**.
| Scope | What Persists | Lifetime |
| - | - | - |
| **Per-conversation files** | Files the agent saves in its working directory | Saved with the conversation and restored when you reopen it |
| **Shared package environment** | Installed packages (`pip install`, `npm install`), cached dependencies | Shared across every chat on the agent. Members with edit access add packages once and they become available to everyone |
| **Team workspace** (`.workspace/agent/`) | Skills and files saved to the shared workspace | Shared across all conversations and all members of the agent |
| **Personal workspace** (`.workspace/personal/`) | Files you save to your private workspace | Private to you, persists across all your conversations with that agent |
Python variables and imports remain available while the conversation's Python kernel is running. They are not archived with files and may be lost if the kernel or sandbox is restarted. Save important intermediate results to files so the agent can reload them.
Starting a new conversation gives you a fresh working directory, but your installed packages and workspace files are already available from previous sessions.
Conversations are isolated from one another:
* Each chat runs in its own sandbox, so one conversation can never see another conversation's in-progress working files.
* Sharing across chats happens only through the workspace folders and the shared package environment described above.
* Your **personal workspace** is private to you. Other members of the same agent cannot see it.
* Subagents spawned by your agent run in their own sandboxes but mount the same workspace folders and package environment, so they can reach the same shared files and packages.
***
## Pre-installed packages
The sandbox comes with **80+ Python packages** ready to use, so your agent can start working immediately without installing anything.
pandas, numpy, scipy, scikit-learn, statsmodels
matplotlib, seaborn, plotly, bokeh
openai, anthropic, google-generativeai, mistralai, llama-index-core, gensim
requests, aiohttp, beautifulsoup4, scrapy, selenium, playwright
openpyxl, PyMuPDF, python-docx, Pillow, opencv-python, imageio
moviepy, librosa, ffmpeg-python, yt-dlp, soundfile
nltk, spacy, textblob
psycopg2-binary, pymongo, PyMySQL, pyodbc, boto3, google-cloud-storage
Need something that isn't pre-installed? Your agent can install it with `pip install package-name`. Installed packages are shared across every chat on the agent, so you only need to install once. Members with edit access to the agent can add packages for everyone; if you only have view access, your own installs are temporary and last for the current session.
***
## Execution limits
| Resource | Limit |
| - | - |
| **Command timeout** | 30 minutes per command |
| **File ingestion** | Up to 300 MB per file |
| **Network access** | Full internet access (API calls, pip installs, web requests) |
| **GUI** | Headless only. Visualizations must be saved to files (e.g., `plt.savefig()`) |
The sandbox is designed for data analysis, scripting, and automation tasks. It is not intended for training large ML models or running persistent servers.
***
## Examples
Here are some common ways to use the Code Sandbox:
Ask your agent to analyze data:
```text theme={"dark"}
Analyze this CSV file and create a summary with charts showing
monthly revenue trends and top-performing products.
```
The agent will use pandas to load the data, perform analysis, and generate visualizations with matplotlib or plotly.
Use secrets to call external APIs:
```text theme={"dark"}
Pull all open support tickets from our Pylon API and create
a spreadsheet grouped by priority level.
```
The agent accesses your configured secrets as environment variables and makes authenticated API calls.
Transform and process files:
```text theme={"dark"}
Take this PDF report, extract all tables, and convert them
into a clean Excel spreadsheet with proper formatting.
```
The agent uses libraries like PyMuPDF and openpyxl to read PDFs and generate spreadsheets.
Run complex multi-step scripts:
```text theme={"dark"}
Scrape all product listings from this website, clean the data,
remove duplicates, and export as a CSV with price comparisons.
```
The agent writes and executes Python scripts, using the shell for any system-level operations needed.
***
## Workspace files
The agent has two persistent workspace folders that carry over across conversations:
* **Team workspace** (`.workspace/agent/`) — shared by everyone with access to the agent. Files saved here by one member are visible to all other members, which makes it ideal for reference data, configuration, or ongoing project assets. Members with **edit** access can write to it; members with **view** access can read it but not change it.
* **Personal workspace** (`.workspace/personal/`) — private to you. Files you save here persist across your own conversations with the agent and are never visible to other members.
Your agent chooses the right folder automatically based on whether a file should be shared or kept private, so you can simply ask it to save something for later.
Workspace files follow the same artifact system as other agent-generated files: they are versioned, previewable, and shareable.
For more details on file management, versioning, and sharing, see [Agent Artifacts](/core-concepts/agent_artifacts).
***
## Integration with apps
The sandbox has access to your connected apps via the pre-installed `gumloop` SDK. Your agent can call any of its configured integrations directly from Python code:
```python theme={"dark"}
from gumloop import Gumloop
client = Gumloop()
result = client.mcp.execute(
server_id="slack",
tool_name="send_message",
arguments={"channel": "#general", "text": "Hello from the sandbox!"}
)
```
This means your agent can combine code execution with any integration, for example: query a database, process the results in Python, then post a summary to Slack.
***
## Agent secrets
Agent Secrets let you inject encrypted credentials into the sandbox as environment variables, so your agent can authenticate with external services (APIs, databases, etc.) without ever exposing the raw values.
A **secret** is the stored credential, either personal or owned by a team. A **binding** maps an environment-variable name on an agent to a secret. Binding scope controls who gets that mapping; it does not change who owns the secret.
Secrets live in your **Vault** — at [gumloop.com/personal/vault](https://www.gumloop.com/personal/vault) for your own credentials, and in the team's Vault for shared ones. A secret is one credential type in the Vault, alongside [website logins](/core-concepts/browser_logins_and_profiles#logins), [browser profiles](/core-concepts/browser_logins_and_profiles#browser-profiles), and [1Password connections](/core-concepts/browser_logins_and_profiles#1password) that the [agent browser](/core-concepts/agent_browser) uses.
***
### Adding a secret to your agent
Open the agent, go to the **Agent** tab, expand **Secrets**, and click **+ Add**.
![Secrets section showing No secrets yet and an Add button]()
In **Add personal secret to agent**, set **Name** to the environment-variable name the agent should use (for example `PYLON_API_KEY`). Under **Source**, choose **Existing secret** or **New secret**, then pick or create the stored credential.
![Add personal secret to agent dialog with Name, Source, and Secret fields]()
Click **Add**. The secret appears by name in the Secrets section. The agent can use it at runtime as an environment variable, but it never sees the raw value.
In the agent chat, ask it to perform a task that requires the credential. The agent accesses the secret as an environment variable (e.g. `os.environ["PYLON_API_KEY"]`) and uses it in code, but it can never read or expose the actual value.
![Agent chat showing it has access to PYLON_API_KEY and using it to query the Pylon API for tickets created today]()
If you share an agent that uses personal secrets, other users will be prompted to provide their own values. Your secrets are never exposed.
***
### Two types of secrets
Private to you. No other user can access them. Managed from your [personal Vault](https://www.gumloop.com/settings/profile/vault).
Shared across all team members. Managed from the team's Vault, and available when an agent is in a team space.
***
### Team secrets
For agents in a **team space**, you can use shared secrets that all team members can access.
Move your agent into a team (or create it there).
On the **Agent** tab, expand **Secrets** and click **+ Add**. The picker shows both personal and team secrets.
Pick from the Team Secrets section. All team members will share this value.
![Secret picker showing Personal Secrets and Team Secrets sections with Pylon API Key under Team Secrets]()
***
### Binding scopes
Bindings can be saved for **User** or **Team** scope in **Secrets** on the **Agent** tab:
| Scope | Who it applies to | Requirement |
| - | - | - |
| **User** | You only. The binding is saved to your own row. | Anyone who can read and use the agent can save their own user bindings. |
| **Team** | Everyone on the agent's home team who uses the agent. | The agent must have a home project/team, and you must have permission to manage the project's variables. Team bindings can reference only secrets owned by that home project. |
The scope toggle offers **Team** and **User**. The panel describes them as:
* **Team scope:** “Anyone in your team who uses this agent can use these secrets. A user binding with the same name overrides these.”
* **User scope:** “Only you can use these secrets. User secrets override matching team secrets.”
If you can read team bindings but cannot manage team secrets, you can see the Team list but are prompted to request the required permission instead of adding a binding. A personal agent with no home team can only have user bindings, so the Team option is not offered.
***
### Runtime resolution
Secrets resolve based on the **running user**, not the agent owner. A user who runs an agent without a binding of their own is prompted to configure one.
For each run, the authorized home-team bindings are merged with the running user's bindings. If the same environment-variable name exists in both, the **user binding wins**.
Team bindings are skipped when the running user does not have permission to read the home project, so users outside that team do not get them. Permissions are checked again when bindings are used, not only when they are saved.
When a user encounters a secret they haven't configured, the chat prompts them to configure it:
![Chat showing Configure secrets prompt with PYLON_API_KEY needed, a dropdown to select from Personal Secrets or add new, and buttons for Skip, Save for me, and Save to agent]()
When the agent asks you to bind secrets mid-chat, the prompt asks **Who should use these bindings?**
Options:
* **Skip**: proceed without the secret
* **Only me**: the binding applies to you
* **My team**: the binding applies to everyone on the agent's home team; offered only when the agent has a home team and you can manage the team's variables
If the question goes unanswered, the binding is saved for you only, so access is never widened by accident.
Users can also manage their active secrets during a conversation using the **Secrets** button in the chat composer:
![Chat composer Secrets popover showing Your secrets with Pylon API Key mapped to PYLON_API_KEY]()
***
### Comparison
#### Secret ownership
| | Personal Secrets | Team Secrets |
| - | - | - |
| **Visibility** | Only you | All team members |
| **Where managed** | [Personal Vault](https://www.gumloop.com/settings/profile/vault) | Team Vault |
| **Use case** | Private API keys, personal tokens | Shared service accounts, org-wide keys |
| **Agent location** | Personal or team space | Team space only |
| **Resolution** | Per-user (each provides their own) | Shared (one value for all) |
#### Binding scope
| | User binding | Team binding |
| - | - | - |
| **Visibility** | Only the user who saved it | Users on the agent's home team who can use the agent and read the home project |
| **Where managed** | Agent tab > Secrets, User scope | Agent tab > Secrets, Team scope |
| **Who can write** | Anyone who can read and use the agent | Users with permission to manage the home project's variables |
| **Agent location** | Personal or team space | Home project/team required |
| **Secret picker** | Personal secrets available to the user | Secrets owned by the home project only |
| **Precedence** | Overrides a team binding with the same environment-variable name | Used when no user binding with the same name exists |
***
### FAQ
No. Secrets are injected as environment variables at runtime. The agent can reference them by name (`os.environ["MY_KEY"]`) but never sees the actual value. Values are encrypted and never shown to the agent.
Yes. An agent can use personal and team secrets, and it can have both user and team bindings. Team bindings require a home team and the appropriate project access. If you run an agent with a binding you haven't configured, the chat prompts you to bind your own (see [Runtime Resolution](#runtime-resolution)).
Your user binding wins. The running user's bindings override authorized team bindings with the same environment-variable name.
Anyone on the agent's home team who can use the agent and has read access to the home project can use the binding. Permissions are checked again when the binding is used.
The agent may not have a home team, or you may not have permission to manage the project's variables. Personal agents with no home team offer user bindings only.
It can use user bindings only. Team scope is not available without a home project/team.
Yes. Secrets are bound to the agent configuration. They are available every time the agent runs code.
Go to [gumloop.com/settings/profile/vault](https://www.gumloop.com/settings/profile/vault) and add one. It will then appear in the secret picker when configuring agents.
# Agent triggers
Source: https://docs.gumloop.com/core-concepts/agent_triggers
Run your agents automatically on a schedule or in response to external events like emails, Slack messages, and more.
Agents can run autonomously without manual interaction. Set up **scheduled triggers** to run on a recurring or one-time basis, **app triggers** to fire when something happens in an external service, or a **webhook trigger** to fire when another app sends data to a unique URL.
All triggers are managed from the **Triggers** section of your agent's configuration page. Click **Add trigger** to create a new one.
![Trigger type selector showing Scheduled Trigger and App Trigger options]()
Need to monitor multiple services, apply custom logic, or watch an app without a pre-built trigger? Use [**Create With AI**](/core-concepts/ai_trigger_creation) to build custom triggers in natural language.
***
## Scheduled triggers
Schedule your agent to run automatically on a **recurring schedule** or as a **one-time trigger**. When a trigger fires, the agent receives a prompt you configure and processes it exactly as if you had typed it in the chat.
### Setting up a scheduled trigger
Go to your agent's configuration page, find the **Triggers** section, and click **Add trigger**. Choose **Scheduled Trigger** as the type, then fill in three fields:
* **Name**: A short label (e.g., "Daily Ticket Summary")
* **Schedule**: When the trigger should run (recurring cron or one-time)
* **Prompt**: The message your agent receives when the trigger fires
Click **Create** and the trigger is immediately active.
Runs on a cron schedule until you pause or delete it. You don't need to know cron syntax: describe your schedule in plain language and the AI generates the expression.
![Create a Scheduled Trigger dialog showing the Recurring tab with name, AI-powered schedule field, cron expression, and prompt]()
Minimum interval is 1 minute. Timezones default to your browser's timezone.
Runs once and is **automatically deleted** after execution.
![Create a Scheduled Trigger dialog showing the One-time tab with name, date/time picker, and prompt]()
* **Relative** ("In" mode): In 30 minutes, 2 hours, 3 days
* **Absolute** ("At" mode): Pick a specific date and time
Once created, triggers appear in the **Triggers** section. Click to edit, or use the three-dot menu to activate, deactivate, or delete.
![Triggers section showing a created Tickets Summary trigger that runs every 30 minutes]()
### Writing good trigger prompts
The prompt is what your agent receives when the trigger fires. Be specific:
| Good | Bad |
| - | - |
| "Give me a summary of all the Zendesk tickets created in the last two days." | "Do the usual thing." |
| "Check my Gmail for unread client emails, summarize them, and post to #client-updates in Slack." | "Check emails." |
If your agent has a relevant [skill](/core-concepts/skills) for the task, reference it in the prompt. The agent will load the skill and follow its instructions for consistent results.
### Self-Scheduling
Your agent can create and manage its own triggers during a conversation. Just tell it what you need:
| What you say | What happens |
| - | - |
| "Remind me to check emails every weekday at 9 AM" | Agent creates a recurring scheduled trigger |
| "In 30 minutes, check if the deployment succeeded" | Agent creates a one-time delayed trigger |
| "Show me my active schedules" | Agent lists all its triggers |
| "Pause the daily email check" | Agent deactivates the trigger without deleting it |
Agents can only manage their own schedules, not those of other agents.
***
## Webhook triggers
A webhook trigger gives your agent its own URL. Any service that can send an HTTP `POST` — Stripe, GitHub, a CI job, an internal script — runs the agent by calling it. Unlike app triggers, nothing needs a pre-built integration and Gumloop doesn't poll anything: the other system calls you.
### Setting up a webhook trigger
On your agent's configuration page, find the **Triggers** section, click **Add trigger**, and choose **Webhook**.
![Trigger menu showing Create With AI, App Trigger, Webhook, Scheduled Trigger, and One-Time Trigger options]()
Fill in the trigger and decide how the payload reaches your agent:
| Field | Description |
| - | - |
| **Trigger name** | A short label (e.g., "Incoming Event") shown in the Triggers list |
| **Prompt** | The message your agent receives when the trigger fires. Drag or click the **Raw JSON** badge to drop the request body into the prompt. |
| **Send raw JSON instead of a prompt** | Sends the payload on its own, with no prompt around it. Use it when the agent's instructions already explain what to do with the data. |
![Webhook trigger dialog with Trigger name, a prompt containing the Raw JSON badge, and the Send raw JSON instead of a prompt toggle]()
A prompt is required unless **Send raw JSON instead of a prompt** is on.
Click **Create trigger**. Gumloop generates a unique URL plus a ready-to-run `curl` example. Paste the URL into whatever app or script should start the agent.
![Trigger created screen showing the webhook URL, a copy button, and a Try it yourself curl example]()
Need the URL again later? Click the trigger in the **Triggers** section — the webhook URL is on its detail panel.
### Calling the webhook
Send a `POST` request to the URL. No API key or header is required — the URL itself is the credential.
```bash theme={"dark"}
curl -X POST \
'https://api.gumloop.com/trigger_incoming_webhook//' \
-H 'Content-Type: application/json' \
-d '{"customer": {"email": "ada@example.com"}}'
```
Gumloop replies `200` with `{"success": true}` as soon as the request is accepted, then runs the agent in the background — it does not wait for the agent to finish, and the response never contains the agent's answer. Have the agent report back through a tool (Slack, email, a database write) instead.
**Payload handling:**
* **JSON** is parsed as JSON, even if the sender omits the `Content-Type: application/json` header.
* **Form-encoded** bodies are turned into key/value pairs.
* **Anything else** is passed through as raw text.
Anyone with the URL can run your agent, so treat it like a password and don't share it publicly. To retire a URL, delete the trigger — a new trigger always gets a fresh URL.
Every rejected call returns the same `404` `not_found`, whether the trigger doesn't exist, is deactivated, or the URL's secret is wrong. That's deliberate: a caller holding a bad URL learns nothing about your agents.
**Rate limit:** each webhook trigger accepts up to **100 requests per minute**. The limit is counted per trigger, no matter who sends the request or from which IP, and every request counts toward it, including rejected ones. Requests over the limit get a `429` `rate_limited` response with a `Retry-After` header giving the seconds to wait, and the agent does not run for them. If a sender can burst past 100 events a minute, batch or space out its calls, or retry after the `Retry-After` delay.
### Letting your agent manage webhooks
You don't have to build the trigger by hand. Ask the agent in chat — "give me a webhook I can call from our deploy script" — and it creates one, then tells you to copy the URL from the trigger's detail panel (the agent never sees the URL itself).
| What you say | What happens |
| - | - |
| "Create a webhook trigger for incoming Stripe events" | Agent creates a webhook trigger, pending your approval |
| "Show me my webhook triggers" | Agent lists the webhook triggers you created on this agent |
| "Change the prompt on the Stripe webhook" | Agent updates the trigger's name, prompt, or raw-JSON setting |
| "Pause the deploy webhook" | Agent deactivates the trigger without deleting it |
Creating, editing, deleting, disabling, and enabling all require your approval before they take effect, and an agent only sees the webhook triggers **you** created — not ones your teammates added.
Agent-managed triggers require **AI Managed** to be on in the **Triggers** header. Turn it off and only you can create or change triggers.
***
## App triggers
App triggers fire your agent when something happens in an external service. Instead of checking manually, your agent reacts automatically to new emails, messages, database changes, and more.
When a trigger fires, the event data (e.g., the email body, the Slack message) is injected into a prompt template you write. The agent processes it as if you had typed it in the chat.
### Supported integrations
New email in a label
New channel message
Emoji reaction on a message
New channel message
New file in a folder
New or updated row
Upcoming event
New or updated page
New or updated record
New ticket or comment
New or updated record in any object
New or updated issue
New issue created
Item, subitem, update, or column change on a board
Web changes matching a query
Also supported: **Outlook**, **Outlook Calendar**, **Google Forms**, **Typeform**, **HubSpot**, **incident.io**, and **Jira**. Some integrations (Gmail, Slack, Slack Reaction, Teams, Drive, Forms, Typeform, Zendesk, Monday.com, Parallel Web Monitor) are **real-time** and fire within seconds. Others (Sheets, Calendar, Notion, Airtable, HubSpot, incident.io, Salesforce, Linear, Jira) use **polling** and check for changes approximately every 60 seconds.
### Setting up an app trigger
Go to your agent's configuration page, find the **Triggers** section, and click **Add trigger**. Choose **App Trigger** as the type. Then follow three steps:
Choose which integration event should fire your agent.
![App Trigger picker with a search box and integrations including Google Drive Folder, Google Sheets, Google Calendar Event, Gmail, Outlook, Slack Message, Slack Reaction, Teams Message, Notion Database, Airtable, HubSpot List, Salesforce Record, Zendesk Ticket, Linear Issue, Jira Issue, Outlook Calendar Event, Typeform Submission, Monday.com Board, Google Form Responses, incident.io Incidents, and Parallel Web Monitor]()
Connect the account your trigger should use and set its parameters. For example, with Gmail you can choose which label to monitor, whether to mark emails as read, and whether to read HTML content.
![Gmail trigger setup with credential selection, label filter, and options for Mark as Read and Read as HTML]()
Your agent uses the credentials of the person who created the trigger. Make sure you've connected the required app on your [Connectors page](https://www.gumloop.com/settings/profile/connectors?view=connected) before setting up the trigger.
Define what your agent should do when the trigger fires. Use **template variables** (shown as badges) to inject event data into your prompt.
![Prompt template editor showing trigger name and a prompt with template variables like Email Body, Attached File Name, and more]()
Template variables are specific to each integration. For Gmail, you get variables like `Email Body`, `Subject`, `Sender`, and `Attached File Name`. For Slack, you get `Message`, `Sender Name`, `Channel Name`, etc.
### Prompt templates
When an app trigger fires, the event data is injected into your prompt template before the agent receives it.
**How it works:**
1. You write a prompt template with placeholder variables (shown as badges in the UI)
2. When the trigger fires, each variable is replaced with the actual event data
3. The agent receives the fully resolved prompt and acts on it
**Example:**
Your template:
```text theme={"dark"}
New email from {Sender}: Subject: {Subject}
{Email Body}
Please categorize this email and draft a response if it's from a client.
```
When fired, your agent sees:
```text theme={"dark"}
New email from john@acme.com: Subject: Q1 Budget Review
Hi, can we schedule a meeting to discuss the Q1 budget numbers?
Please categorize this email and draft a response if it's from a client.
```
You can also toggle **Pass Raw Data** to send the entire event payload as JSON instead of using template variables. This is useful when you want the agent to decide what's relevant.
### Managing active triggers
All your triggers (scheduled, app, and webhook) appear in the **Triggers** section of your agent's configuration. Owners can edit, deactivate, or delete any trigger. Users can always view, deactivate, and delete their own triggers; they can create, edit, and activate their own only when **Create triggers** is **Allow**. See [Who Can Manage Triggers?](/help/triggers/who-can-manage-triggers).
Deactivating every trigger is the supported way to switch an agent off: the agent stops running on its own, but its configuration, connectors, and triggers stay intact and you can re-enable them at any time. Do not use `is_active: false` on the [agents API](/api-reference/agents/update-agent) or `gumloop agents update --inactive` for this — that retires the agent instead of pausing it.
![Triggers tab of an agent listing triggers with a three-dot menu open on Edit, Deactivate, and Delete]()
### Integration details
**Fires when**: A new email arrives in the specified label. *(Real-time)*
**Configuration**: Choose your Gmail credential, select a label to monitor (e.g., INBOX, a custom label), and optionally enable "Mark as Read" and "Read as HTML".
**Available variables**: Email Body, Subject, Sender, Attached File Name, Date, Message ID, Thread ID
Due to Google API limitations, only one Gmail account can be monitored per credential. For multiple accounts, create separate triggers with different credentials.
**Fires when**: A new message is posted in the specified channel. *(Real-time)*
**Configuration**: Choose your Slack credential and select the channel to monitor. "Ignore Bot Messages" is enabled by default. You can also optionally ignore thread replies.
**Available variables**: Message, Sender Name, Channel Name, Channel ID, Date, Thread ID, Attachment Names
"Ignore Bot Messages" is on by default to prevent infinite loops if your agent posts back to the same channel. We recommend keeping it enabled unless you specifically need to process bot messages.
**Fires when**: Someone reacts to a message with an emoji in the specified channel. *(Real-time)*
**Configuration**: Choose your Slack credential and select the channel to watch. Optionally filter by specific emoji (e.g., `white_check_mark`, `thumbsup`). Leave the emoji filter empty to trigger on any reaction. "Ignore Reactions From Bots" is enabled by default. You can also include or exclude reactions on thread replies, and optionally read the full thread for additional context.
**Available variables**: Message, Emoji, Reaction Count, Reacted By, Message Sender, Attachment Names, Thread ID, Thread Link, Channel Name, Channel ID, Date
"Ignore Reactions From Bots" is on by default. Reactions from Gumloop itself are always ignored regardless of this setting, preventing infinite loops if your agent reacts to messages in the same channel.
**Fires when**: A new message is posted in the specified Teams channel. *(Real-time)*
**Configuration**: Choose your Teams credential, select the team and channel. Optionally ignore bot messages and thread replies.
**Available variables**: Message, Sender Name, Channel Name, Channel ID, Date, Subject
Teams triggers only work with Microsoft 365 work or school accounts. Personal Microsoft accounts are not supported.
Want your team to chat with an agent inside a Teams channel instead? See [Using Agents in Microsoft Teams](/core-concepts/agents_teams).
**Fires when**: A new file is uploaded to the specified folder. *(Real-time)*
**Configuration**: Choose your Google Drive credential and select the folder to watch.
**Available variables**: File Name, File ID, File Type, Modified Date
**Fires when**: A new row is added or an existing row is updated, depending on your trigger mode. *(Polling, \~60s)*
**Configuration**: Choose your Google Sheets credential, select the spreadsheet and worksheet. Pick a trigger mode: "Create Row" (new rows only) or "Create or Update Row" (new and modified rows).
**Available variables**: All column values from the row that triggered the event
**Fires when**: An event is about to start, an event is about to end, or a new event is created in the future, depending on the trigger mode. *(Polling, \~60s)*
**Configuration**: Choose your Google Calendar credential, select the calendar, and set how many minutes before the event the trigger should fire (default: 15 minutes).
**Available variables**: Event Title, Start Time, End Time, Attendees, Description, Location
**Fires when**: A new email arrives in your Outlook inbox or a folder you select.
**Configuration**: Choose your Outlook credential and select the inbox or folder to monitor.
**Available variables**: Email Body, Subject, Sender, Attached File Name, Date, Message ID, Thread ID
**Fires when**: An event is about to start, an event is about to end, or a new event is created in the future, depending on the trigger mode.
**Configuration**: Choose your Outlook Calendar credential, select the calendar, and set how far ahead of the event the trigger should fire.
**Available variables**: Event Title, Start Time, End Time, Attendees, Description, Location
**Fires when**: A new page is created or an existing page is updated in the specified database. *(Polling, \~60s)*
**Configuration**: Choose your Notion credential and select the database to monitor.
**Available variables**: All database property values from the page that triggered the event
**Fires when**: A new record is created or an existing record is updated in the specified table. *(Polling, \~60s)*
**Configuration**: Choose your Airtable credential, select the base, table, and optionally a view. Requires a "Last Modified Timestamp" field in your table.
**Available variables**: All field values from the record that triggered the event
**Fires when**: Depending on your trigger mode: new ticket created, new comment added, ticket status changed, or ticket enters a view. *(Real-time)*
**Configuration**: Choose your Zendesk credential and select a trigger mode. Optionally filter by ticket type, priority, or status.
**Available variables**: Ticket ID, URL, Subject, Description, Status, Priority, Type, Requester Email, Assignee Email, Comments
**Fires when**: A new form response is submitted. *(Real-time)*
**Configuration**: Choose your Google credential and select the Google Form to monitor.
**Available variables**: All submitted form field values
**Fires when**: A new form submission is received. *(Real-time)*
**Configuration**: Choose your Typeform credential and select the form to monitor.
**Available variables**: All submitted form field values
**Fires when**: New records appear in a specified HubSpot list. *(Polling, \~60s)*
**Configuration**: Choose your HubSpot credential, select the list to monitor, and configure the object type.
**Available variables**: All property values from the records that triggered the event
**Fires when**: A new incident is detected. *(Polling, \~60s)*
**Configuration**: Choose your incident.io credential. Optionally filter by severity (Minor, Major, Critical) and mode (Standard, Retrospective, Tutorial, Test).
**Available variables**: Incident ID, Name, Status, Severity, Timestamps, Summary, Permalink, Slack Channel ID
**Fires when**: A new record is created or an existing record is updated in the selected Salesforce object, depending on the trigger mode. *(Polling, \~60s)*
**Configuration**: Choose your Salesforce credential, select the object to monitor (e.g., Lead, Contact, Opportunity, Account, Case, or any custom object), and choose a **Trigger Mode**:
* **New Record**: Fires when a new record is created
* **Updated Record**: Fires when an existing record is modified (newly created records are automatically excluded)
**Available variables**: All fields from the selected Salesforce object (e.g., First Name, Last Name, Email, Company, etc.). The exact fields depend on the object type.
The trigger uses a compound cursor based on the relevant timestamp field (`CreatedDate` or `LastModifiedDate`) and record `Id` to avoid duplicates. It fetches up to 5 records per poll. In Updated Record mode, each modification to a record triggers the agent again.
**Fires when**: A new issue is created or an existing issue is updated in the selected Linear team, depending on the trigger mode. *(Polling, \~60s)*
**Configuration**: Choose your Linear credential, select the **Team** to monitor (required), and choose a **Trigger Mode**:
* **New Issue**: Fires when a new issue is created
* **Updated Issue**: Fires when an existing issue is modified (newly created issues are automatically excluded)
Optionally add **Filters** to narrow which issues fire the trigger:
* **Status**: Filter by issue status (e.g., In Progress, Done, Backlog)
* **Project**: Filter by Linear project
* **Priority**: Filter by priority level (e.g., Urgent, High, Medium, Low)
* **Labels**: Filter by issue labels (matches issues with at least one of the selected labels)
* **Assignee**: Filter by the team member assigned to the issue
**Available variables**: Description, Identifier (e.g., "ENG-123"), Title, URL, Assignee, Status, Project, Labels
The trigger fetches up to 5 issues per poll. In Updated Issue mode, each modification to an issue triggers the agent again. A Team must be selected — it is a required parameter.
**Fires when**: A new issue is created in the selected Jira project. *(Polling, \~60s)*
**Configuration**: Choose your Jira credential, select the **Resource** (your Jira instance), the **Project** to monitor, and optionally apply filters to narrow which issues fire the trigger.
**Filter options**:
* **Standard Filters**: Filter by Status, Priority, Labels, Issue Type, Assignee, and Custom Fields
* **JQL**: Write a custom Jira Query Language expression for advanced filtering
* **Saved Filter**: Use an existing filter saved in your Jira instance
**Available variables**: Issue ID, Key, Summary, and other issue fields based on the **Information to Read** selection
The trigger fetches up to 5 new issues per poll. Uses a compound cursor based on the issue's `created` timestamp and issue key to avoid duplicates. You must connect your Jira account on the [Connectors page](https://www.gumloop.com/settings/profile/connectors?view=connected) before setting up the trigger.
**Fires when**: Something changes on a Monday.com board — an item, subitem, update, or column event, depending on the **Trigger Mode** you pick. *(Real-time via webhook)*
**Configuration**: Choose your Monday.com credential, select the **Workspace** and **Board** to watch, then pick a **Trigger Mode**. Some modes ask for one more field:
| Trigger Mode | Extra field |
| - | - |
| **Specific Column Changed** | **Column** — the column to watch |
| **Status Changed To** | **Status Column**, plus an optional **Status Value**. Leave the value empty to fire on any change to that column. |
| **Item Moved To Group** | **Group** — the destination group |
All 18 modes: Item Created, Item Name Changed, Any Column Changed, Specific Column Changed, Status Changed To, Item Moved To Group, Item Moved To Any Group, Item Deleted, Item Restored, Update Posted, Update Edited, Update Deleted, Column Created, Subitem Created, Subitem Name Changed, Any Subitem Column Changed, Subitem Deleted, and Update Posted On Subitem.
**Available variables**: One variable per column on the selected board, named after the column title, plus the board's item name column (`Item`, `Task`, or whatever your board calls its items). Values come from the item behind the event.
Modes where the item no longer exists — **Item Deleted**, **Subitem Deleted**, and **Column Created** — still fire, but the column variables come through empty. Use **Pass Raw Data** if you need the raw event payload for those.
Subitem events are watched from the parent board you select, and their column values are read from the subitems board, so the variables you get are the subitem's own columns matched by title.
Monday.com triggers create a webhook on the board, so your connected account needs permission to manage webhooks on it. If you connected Monday.com before this trigger shipped, reconnect it on the [Connectors page](https://www.gumloop.com/settings/profile/connectors?view=connected) to grant the webhook permission, otherwise the trigger fails to save.
**Fires when**: Relevant changes are detected on the web matching your natural-language query. *(Real-time via webhook)*
**Configuration**: No credentials required — works out of the box. Write a **Query** describing what you want to monitor and set the **Frequency** for how often to check (hourly, daily, or weekly).
Unlike other triggers that watch a specific service, the Parallel Web Monitor uses AI to scan the entire web for material changes matching your query. This makes it ideal for open-ended monitoring like tracking competitors, news, or market changes.
**Query examples**:
* "OpenAI product announcements and API pricing changes"
* "Acme Corp product launches, pricing changes, and new partnerships"
* "YC Startups that have raised Series A funding"
* "SEC rulings on cryptocurrency ETF applications"
* "New job postings for VP of Engineering at FAANG companies"
**Available variables**: Event Output, Event Date, Source URLs
Be specific in your query. "AI news" is too broad — "Anthropic and OpenAI model release announcements" will produce much more relevant results.
***
## Choosing the model a trigger uses
Every trigger has a **Model** field. By default it is set to **Use agent model**, so the run uses whatever model the agent is configured with. Pick a different model when a specific trigger needs something faster or stronger than the agent's day-to-day model — for example, keeping an agent on its normal model for chat while a weekly report trigger runs on the smartest one.
![Trigger editor showing the Model field open with Use agent model selected, plus Auto, Recommended, Smartest, and per-provider options]()
Open the **Model** dropdown while creating or editing a trigger and choose one of:
| Option | What it does |
| - | - |
| **Use agent model** | Inherits the agent's selected model. If you later change the agent's model, this trigger follows along. |
| **Auto**, **Recommended**, **Smartest** | The same presets the agent's own model picker offers, so the trigger tracks whichever model currently sits behind that preset. |
| A specific model | Pinned to that exact model, grouped by provider in the dropdown. |
The list shows exactly the models your agent could be set to, so anything your organization has restricted does not appear. If a model you pinned later becomes unavailable — it's retired, or an admin removes it from the allowed list — the trigger quietly falls back to the agent's model instead of failing.
The **Model** field is available on scheduled, webhook, app, and MCP triggers, and applies to every run that trigger starts, including runs you fire manually from the Triggers section.
Model choice affects cost. A trigger pinned to a heavier model spends more credits per run than the same trigger on the agent's default. See [Credits](/core-concepts/credits) for how model usage is billed.
***
## Good to know
### File and attachment handling
When a trigger passes files or attachments to your agent, the agent **automatically receives and can process them**. This includes:
* **Email attachments** from Gmail triggers (PDFs, spreadsheets, images, etc.)
* **Slack file attachments** from Slack message triggers
* **Google Drive files** from Drive triggers (the actual file content, not just the metadata)
* **Teams attachments** from Microsoft Teams message triggers
Your agent can read text-based files (PDFs, CSVs, DOCX, etc.), parse images using vision capabilities, and use file contents as context for its response. No additional configuration is needed.
### Credentials
Triggers use the credentials of the **person who created the trigger**, not whoever is chatting with the agent. Make sure you've connected the required app on your [Connectors page](https://www.gumloop.com/settings/profile/connectors?view=connected) before setting up a trigger.
For team agents, if team credentials are configured, those can be used instead of personal credentials.
### Auto-disable on failure
All triggers (scheduled, app, and webhook) automatically deactivate after **3 consecutive failed runs**. Common causes include expired credentials, deleted resources (channels, folders, databases), or permission changes.
When this happens, the trigger owner receives a notification through **email, Slack DM, and in-app**. The notification links straight to the most recent failed run so you can see what went wrong. You can dismiss it once you've handled it.
To fix: resolve the underlying issue, then re-enable the trigger from the Triggers section. Re-enabling **resets the failure count**, so a trigger won't be immediately disabled again by earlier failures — only failures that happen after you re-enable it count toward the next auto-disable.
For a walkthrough of every reason a trigger turns off and how to fix each one, see [Why Did My Trigger Turn Off?](/help/triggers/why-triggers-turn-off).
### Overlapping runs
If a previous trigger execution is still running when the next one fires, the new execution is **skipped**. This prevents duplicate work and ensures your agent finishes one task before starting the next.
### Credits
Each trigger execution costs credits based on model and tool usage, the same as a normal chat message. One-time scheduled triggers are automatically deleted after execution (whether they succeed or fail).
***
## FAQ
No. Delete the existing trigger and create a new one with the desired type.
The agent's own model, unless you set the trigger's **Model** field to something else. See [Choosing the Model a Trigger Uses](#choosing-the-model-a-trigger-uses).
Yes. They appear in the agent's run history as triggered executions.
Yes. When a trigger includes files (email attachments, Slack files, Google Drive uploads), the agent automatically receives them and can read text-based files, parse images, and use the content in its response.
Some integrations use **polling** instead of real-time webhooks. Polling-based triggers (Google Sheets, Notion, Airtable, Google Calendar, HubSpot, incident.io, Jira) check for changes approximately every 60 seconds. Real-time triggers (Gmail, Slack, Slack Reaction, Teams, Google Drive, Zendesk, Google Forms, Typeform, Monday.com, Parallel Web Monitor) fire within seconds.
Yes. You can add as many scheduled, app, and webhook triggers as you need to a single agent. Each trigger operates independently.
Yes! Agents can create and manage their own **scheduled triggers** and **custom AI triggers** during conversations. Just describe what you want to monitor and the agent builds it. See [Create Triggers With AI](/core-concepts/ai_trigger_creation) for details. Pre-built integration triggers must still be set up from the agent's configuration page.
***
## Related documentation
Build custom multi-service triggers in natural language
Learn about building and configuring agents
Teach your agent reusable processes
# Agents
Source: https://docs.gumloop.com/core-concepts/agents
Agents are AI-powered assistants that use tools to solve open-ended tasks. An agent decides which tools to use and when, adapting its approach to the task in front of it.
## What agents do
You give an agent a goal and a set of tools, and it figures out how to get there: which tools to call, in what order, and when to ask you for input.
* **Adaptive**: takes different approaches for different situations
* **Tool-driven**: uses your connected services and data as needed
* **Conversational**: works through a task in a back-and-forth conversation
* **Context-aware**: considers your instructions, skills, and past tasks
One piece of work you hand to an agent is a **task**. Each task is its own conversation with its own history, files, and credit cost.
When you give it a task, the agent analyzes the request, decides which tools to use and in what order, runs them, adapts based on the results, and asks for confirmation when your instructions call for it.
## Configure an agent in three moves
You do not need to write a long system prompt up front. The fastest way to a useful agent is to let it do real work, then have it write its own instructions.
Open the **Connectors** section and add the integrations the agent needs (Gmail, Salesforce, Slack, and so on). The connectors you add define what the agent can see and do, so start with the two or three it actually needs.
Start a task and run something end to end. Watch where it guesses, asks the wrong thing, or misses a step.
Once it completes a task the way you want, tell it: *"Update your instructions so you always do it this way"* or *"Turn this into a skill."* The agent writes its own [instructions](#self-improving-instructions) and [skills](#skills), so you can capture the approach without writing everything from scratch.
When an agent gets something wrong, give it feedback and ask it to save the correction in its instructions or a skill. Saving the change gives future tasks a reusable starting point; feedback in one conversation alone does not update every future task.
## Getting around an agent
Open an agent and the left sidebar has everything about it:
![Agent sidebar with New Task, Artifacts, Performance, Channels, and a Recents list]()
| Item | What it is |
| - | - |
| **New Task** | Start a fresh task. `Ctrl/Cmd + Shift + O`. |
| **Artifacts** | Every file, document, and chart the agent has produced. See [Agent Artifacts](/core-concepts/agent_artifacts). |
| **Performance** | Insights, Evaluations, and Tasks for this agent. See [Agent Performance](/core-concepts/agent_performance). |
| **Channels** | Where the agent is reachable: email, Slack, Microsoft Teams, a hosted page, the API, and MCP. See [Channels](#channels). |
| **Recents** | Your recent tasks, newest first, with a filter. |
When the agent is waiting on you to approve a tool call, a **pending action request** appears above Recents.
## The agent builder
Everything you configure lives in four tabs at the top of the builder. Only Owners see them; what a User sees depends on the agent's [User Permissions](/core-concepts/agent_access#user-permissions).
| Tab | What it holds |
| - | - |
| **Agent** | What the agent is made of: model, instructions, connectors, skills, knowledge sources, subagents, secrets, abilities. |
| **Triggers** | How it starts on its own: app, webhook, scheduled, and one-time triggers. |
| **Access** | Who can use it and what they can see: Owners, Users, General Access, File Sharing, Task Visibility, User Permissions. |
| **Settings** | Identity, suggested prompts, advanced AI settings, summarization, model fallback, and deletion. |
Sections open in place. Click a section header (for example **Connectors**) and it expands into a full view with an `Agent > Connectors` breadcrumb, so you can drill into a connector's tools and come back without losing your place. Nothing saves until you press **Save** (`Ctrl/Cmd + S`); the arrow next to it undoes unsaved changes.
![Agent tab showing Model, instructions, Edit Own Instructions, Connectors, Skills, Knowledge Sources, Subagents, Secrets, and Abilities]()
The model picker and the instructions box sit at the top, with **Edit Own Instructions** ([self-improving instructions](#self-improving-instructions)) right under them. Below that, one section per building block — each shows how many items it has, and **+ Add** to add one.
![Triggers tab showing AI Managed, a Mine filter, and Create With AI, App Trigger, Webhook, Scheduled Trigger, and One-Time Trigger options]()
Lists the triggers on the agent and the five ways to add one. The **Mine / Team** filter switches between the triggers you own and everyone's. **AI Managed** in the header lets the agent set up its own triggers during a task. See [Triggers](#triggers).
![Access tab showing Owners, Users, General Access, File Sharing, Task Visibility, and User Permissions]()
Owners, Users, General Access, File Sharing, Task Visibility (team agents), and the eight User Permissions. See [Agent Access](/core-concepts/agent_access).
![Settings tab showing Identity, Suggested Prompts, Advanced AI, Chat Summarization, Model Fallback, and Destructive]()
Identity (icon, name, description), Suggested Prompts, [Advanced AI](#ai-advanced-settings), [Chat Summarization](#ai-advanced-settings), [Model Fallback](#ai-advanced-settings), and **Destructive**, where you delete the agent.
### Guided setup
A brand-new agent asks what it should take care of and sets itself up from your answer, instead of dropping you into the full builder. If you would rather start in the builder every time, turn on **Skip guided agent setup** in [your profile preferences](/core-concepts/profile_settings#preferences).
The rest of this page covers each part, starting with the ones you will reach for most.
***
## Connectors
**Connectors** are the integrations your agent connects to, such as Gmail, Salesforce, Slack, Notion, and 150+ more. The connectors you add determine what the agent can access, so this is the most important part of configuration.
![Connectors section showing connected connector icons, an Add Connector row, and the AI Discovery toggle set to ON]()
Click **+ Add** on the Connectors header to open the picker. The **All** tab lists every available connector (Gumloop-managed and your own), and the **Custom** tab filters to [custom MCP servers](/nodes/mcp/custom_mcp_servers) you have added. Pick the few your agent actually needs rather than connecting everything.
![Add Connectors modal with a search box, a Connected list with checkmarks and Remove all, and a Connectors list with plus buttons]()
The **AI Discovery** toggle on the Connectors header is the same setting as [Tool Discovery](#abilities) in Abilities. It lets the agent load tool schemas on demand instead of all at once, which keeps context lean when you connect many connectors.
### Account selection
Click a connector to open its detail view. The **Account** selector controls which connected account the agent uses when calling its tools.
![Google Docs connector detail view showing Activity, Tools Enabled, and Rules tiles, with an Account selector offering Use Personal Default and Use Specific Account]()
* **Use Personal Default**: each person who runs the agent uses their own default account. This is the default.
* **Use Specific Account**: pin one account for the agent, useful when you have multiple accounts for the same service.
* **Use Team Default** (team agents only): everyone on the team uses the same shared account.
Connect personal or team accounts and choose which account the agent uses.
### Tool Management and approvals
The same detail view has a **Tool Management** panel that controls which of a connector's tools the agent can call, and which ones need your approval first. Tools are grouped into **Read-only tools** and **Write/delete tools**.
![Tool Management panel with an approval preset dropdown, read-only and write/delete tool groups, and per-tool allow, ask, and deny controls]()
Set a preset for the connector, or control each tool individually:
| Preset | Behavior |
| - | - |
| **Always allow** | Every tool runs without asking. |
| **Ask each time** | The agent pauses for approval before any tool call. |
| **Ask for writes/deletes** | Read-only tools run freely; write, delete, and unknown-risk tools pause for approval. |
| **Custom** | Set the mode per tool: allow always, ask each time, or never allow (deny). |
When a tool needs approval, the agent pauses mid-task and shows you an approval card. This is the human-in-the-loop guardrail for sensitive actions.
How approvals work, what the agent shows you, and how to tune when it pauses.
***
## Skills
**Skills** teach your agent how to do specific work *your way*: multi-step processes, templates, and domain knowledge that load only when relevant. You rarely write one by hand. The easiest path is to prompt the agent in a task: get it to do the work well, then say *"turn this into a skill."* When it gets something wrong later, give it feedback and it updates the skill. The **AI Skill Editing** toggle is what lets it create and edit skills on its own.
![Skills section with AI Skill Editing toggle and the Skill menu showing Create With AI, Upload Files, Write Skill Instructions, and Add Existing Skill]()
You can also add a skill yourself with **+ Skill**:
* **Create With AI**: describe the skill and the agent generates it.
* **Upload Files**: turn a document or `.zip` into a skill.
* **Write Skill Instructions**: enter a name and description yourself.
* **Add Existing Skill**: attach a skill you already created.
Create skills, attach them to agents, and build a library that improves over time.
***
## Knowledge sources
Give your agent a searchable memory of what your company knows. In the **Knowledge Sources** section, attach [Brain](/core-concepts/brain) sources (Google Drive, Notion, Slack, GitHub, Confluence, or uploaded files) so the agent answers from your real documents and messages, with citations, instead of guessing.
![Knowledge Sources section in agent configuration with the prompt Give your agent knowledge: Attach Company Brain sources so this agent can search them, down to the exact files or folders within]()
Click **+ Source** to attach whole sources, or drill into the exact files and folders that matter. When you ask about internal knowledge, the agent searches automatically (shown as *Searching Company Brain*) and can open a full document for more context.
Connect knowledge sources, keep them synced, and give your agents company knowledge to search.
***
## Triggers
Agents can run on their own, without anyone starting a task. The **Triggers** tab lists the triggers on the agent, and **AI Managed** in its header lets the agent create, edit, and manage its own triggers during a task.
![Triggers tab showing AI Managed, a Mine filter, and the five ways to add a trigger]()
There are five ways to add one:
| Option | What it does |
| - | - |
| **App Trigger** | Runs the agent when an event happens in another app (new email, new Slack message, a record changes). |
| **Webhook** | Runs the agent when another service sends it a request. |
| **Scheduled Trigger** | Runs the agent on a recurring schedule, for example every weekday at 9 AM. |
| **One-Time Trigger** | Runs the agent once at a specific time. |
| **Create With AI** | Describe what you want and the agent builds a custom trigger for you. |
Owners manage every trigger on the agent. Users can create and edit **their own** triggers while **Create triggers** is allowed in [User Permissions](/core-concepts/agent_access#user-permissions). The **Mine / Team** filter switches between the two views.
Set up app and scheduled triggers, write prompt templates, and manage active triggers.
***
## Subagents
Subagents let your agent delegate to other agents. Instead of doing everything in one task, it can spin up focused helpers that work in parallel, then collect the results and continue.
There are two ways an agent delegates, both through the **invoke\_agent** tool:
The agent clones itself, keeping the same tools and instructions. Useful for parallel work: spawn several clones, each handling a different subtask. The clone shows up as **"(Me)"** in the list and is enabled by default. Clones cannot clone themselves again (depth limit of 1), and you can scope a clone to a subset of apps.
The agent calls a different, specialized agent by name. Add agents to the **Subagents** list to allow this. Cross-agent chains are not depth-limited, so a coordinator can delegate to a chain of purpose-built agents.
Each subagent runs as its own task with its own context and computer, visible in your task history. A task can have at most **10 concurrent subagents**, including subagents started by other subagents. Subagents also count toward your account's concurrent-agent limit, so available capacity may be lower.
If the agent reaches the subagent limit, it receives "Subagent limit reached." Wait for running subagents to finish, or ask the agent to split the work into fewer batches before starting more.
Behind the scenes, subagents run as queued background tasks with their own time budget (about half the parent's). For batch invocations a shared progress board tracks each one, and the parent can hand specific files to a subagent before it starts. The parent reads each subagent's results when it finishes.
***
## Abilities
**Abilities** are the agent's built-in capabilities. Most are on by default, and each can be toggled from the **Abilities** section.
![Abilities section listing Web Search, Web Fetch, Image Generation, Search Past Conversations, Ask Question, Tool Discovery, and App Rules Creation]()
| Ability | Default | What it does |
| - | - | - |
| **Web Search** | On | Searches the web for current information. Choose the provider (Exa, Parallel, Firecrawl, or the model's native search). |
| **Web Fetch** | On | Reads the content of a specific URL. Choose the provider (Firecrawl, Parallel, Exa, or Gumloop). |
| **Image Generation** | On | Creates images from text prompts. See [Image Generation](#image-generation). |
| **Search Past Conversations** | On | Searches and retrieves earlier tasks for context. The backbone of an agent that learns over time. |
| **Ask Question** | On | Lets the agent pause and ask you a structured, multiple-choice question when it needs a decision. |
| **Tool Discovery** | Auto | Loads tool schemas on demand. In **Auto**, the agent loads tools directly when they are small (roughly 10% of context) and switches to on-demand discovery when they grow larger. |
| **App Rules Creation** | On where available | Lets the agent propose [App Rules](/enterprise-features/app-policies/app-rules) for your review while it works. Enabled by default on plans that include App Rules. |
***
## Image generation
The **Image Generation** ability creates images from text prompts. New agents have it on by default and use **GPT-Image 2.5 Flare** as the default image model.
On an agent, you choose the image **model**. The agent chooses the size, quality, background, format, aspect ratio, and resolution for each request based on the prompt. It is instructed to use the smallest option that satisfies the request.
### Image models
| Picker label | ID | Provider | Per-request options |
| - | - | - | - |
| **GPT-Image-2.5 Flare** | `gpt-image-2.5-flare` | OpenAI | `size`, `quality`, `background`, `output_format` |
| **GPT-Image-2.5 Sunburst** | `gpt-image-2.5-sunburst` | OpenAI | `size`, `quality`, `background`, `output_format` |
| **GPT-Image-2** | `gpt-image-2` | OpenAI | `size`, `quality`, `background`, `output_format` |
| **Gemini 3.1 Flash (Nano Banana 2)** | `gemini-3.1-flash-image-preview` | Google | `aspect_ratio`, `image_size` |
| **Gemini 3 Pro** | `gemini-3-pro-image-preview` | Google | `aspect_ratio`, `image_size` |
| **Gemini 2.5 Flash Image** | `gemini-2.5-flash-image` | Google | `aspect_ratio` |
The **Recommended** image preset tries these models in order: GPT-Image 2.5 Flare, GPT-Image 2.5 Sunburst, Gemini 3.1 Flash, Gemini 3 Pro, GPT-Image 2, and Gemini 2.5 Flash Image. It skips any model your organization restricts.
### Per-request options
The agent selects these options for each image request:
| Option | Values |
| - | - |
| **Size** (OpenAI) | `auto`, `1024x1024`, `1536x1024`, `1024x1536`, `2048x2048`, `2048x1152`, `1152x2048`, `3840x2160`, `2160x3840` |
| **Quality** (GPT-Image 2.5 Flare and Sunburst) | `auto`, `low`, `medium`, `high`, `xhigh`, `max` |
| **Quality** (GPT-Image 2) | `auto`, `low`, `medium`, `high` |
| **Background** (OpenAI) | `auto`, `transparent`, `opaque`. `transparent` requires `png` or `webp` output. |
| **Output format** (OpenAI) | `png`, `jpeg`, `webp` |
| **Aspect ratio** (Gemini 3.1 Flash) | `auto`, `1:1`, `2:3`, `3:2`, `3:4`, `4:3`, `4:5`, `5:4`, `9:16`, `16:9`, `21:9`, `1:4`, `4:1`, `1:8`, `8:1` |
| **Aspect ratio** (Gemini 3 Pro and Gemini 2.5 Flash Image) | `auto`, `1:1`, `2:3`, `3:2`, `3:4`, `4:3`, `4:5`, `5:4`, `9:16`, `16:9`, `21:9` |
| **Image size** (Gemini 3.1 Flash) | `auto`, `512`, `1K`, `2K`, `4K` |
| **Image size** (Gemini 3 Pro) | `auto`, `1K`, `2K`, `4K` |
Agents can also pass reference images to edit them or keep a subject, product, or style consistent. OpenAI image models accept up to 16 reference images. Gemini 3.1 Flash and Gemini 3 Pro accept up to 14, and Gemini 2.5 Flash Image accepts up to 3. OpenAI accepts JPEG, PNG, and WebP; all Gemini image models also accept HEIC and HEIF.
**What it costs:** Image generation is charged from the usage reported by the image model. Cost depends on the model and the options selected, so higher quality or resolution costs more credits. See [Credits](/core-concepts/credits) for how BYOK affects image generation.
Older image model IDs are no longer in the picker. Requests that use a retired ID are remapped to a current model:
| Retired ID | Now uses |
| - | - |
| `dall-e-2`, `dall-e-3`, `gpt-image-1`, `gpt-image-1.5` | `gpt-image-2.5-flare` |
| `gemini-2.5-flash-image-preview` | `gemini-2.5-flash-image` |
***
## The agent's computer
Every agent has a built-in **computer** for running Python and shell commands in a secure, isolated environment. It is always on, so the agent can analyze data, generate files, and run scripts automatically. You do not need to configure anything. It keeps installed packages and workspace files across tasks and ships with 80+ Python packages preinstalled.
What the agent's computer can do, persistence, execution limits, preinstalled packages, and Agent Secrets.
***
## The agent's browser
Agents can also get a real Chromium **browser** to open websites, sign in, fill forms, and download files on sites no connector covers. Turn it on from the **Browser** section of the agent's configuration, watch it live from the chat, and replay every step afterwards.
Turn on the browser, watch it live, answer handoffs, logins, browser profiles, and 1Password.
***
## Measuring and improving an agent
**Performance** in the agent sidebar is where you see how the agent is doing and turn on the two features that improve it: **Evaluations** grade completed tasks against your criteria, and **Reflections** have the agent review past tasks and suggest improvements you can accept or dismiss.
Insights, Evaluations, and Tasks for a single agent.
Define criteria and grade the agent's answers so you catch regressions early.
Let the agent review its own recent tasks and propose improvements.
Agents can also produce rich outputs such as documents, spreadsheets, and interactive charts. See [Agent Artifacts](/core-concepts/agent_artifacts) for how those are generated, shared, and versioned.
***
## Working in a task
### Message input menu
The **+** menu in the message bar gives you quick actions while you work:
![Chat input plus menu showing Add photos and files, Use skill, Mention integration, Mention secret, and an Incognito toggle]()
* **Add photos & files**: attach files and images to your message.
* **Use skill**: manually point the agent at a specific skill.
* **Mention integration**: reference a connected app directly in your message.
* **Mention secret**: reference a stored secret so the agent can use it without you pasting the value.
* **Incognito**: toggle a private task (covered below).
### Voice input
You can send audio instead of typing. Gumloop transcribes it on the server and sends the text to the agent, so the task flows the same whether you type or talk.
![Agent chat input showing the microphone button for voice input]()
Supported formats include mp3, mp4, m4a, wav, and webm, up to 25 MB. Transcription runs on Gumloop's servers using OpenAI transcription models (Whisper and GPT-4o Transcribe), so your agent only ever receives the text transcript, never the raw audio.
For a spoken, two-way conversation instead of a single dictated message, use [Talk mode](/core-concepts/talk_mode).
### Message queue and steering
You do not have to wait for the agent to finish before sending your next message. While the agent is working, press **Enter** to add a follow-up to the **message queue** without interrupting its current step. You can edit, reorder, or remove a queued message before it is delivered.
![Message queue showing multiple queued messages in different states]()
To redirect the current run immediately, click **Send Now** on a queued message, or press **⌘ Enter** on Mac / **Ctrl Enter** on Windows or Linux. The agent interrupts its current step and continues with your new input instead of ending the task.
Steering does not undo actions that have already completed, and it does not bypass a pending approval. Use the stop control when you want to end the run rather than redirect it.
### Context usage meter
The circular meter in the bottom-right of the message input shows how much of the agent's usable context window is in use — for models where you picked a [short context window](#context-window), that smaller window is the denominator. Hover it for a breakdown across System, AI Instructions, Abilities, Tools, Skills, Subagents, and Conversation.
![Context Usage Meter showing a token breakdown by category]()
If context fills up, reduce the tools or skills attached, switch to a model with a larger context window, or rely on auto summarization to compress older messages.
### Incognito mode
Incognito tasks are **not saved to the database**. They are held in temporary memory and auto-deleted after 24 hours. Toggle **Incognito** from the message input menu before sending.
| Behavior | Standard task | Incognito task |
| - | - | - |
| **Message storage** | Saved permanently | Not saved |
| **Visible in history and search** | Yes | No |
| **Included in data exports** | Yes | No |
| **Files and artifacts** | Stored permanently | Auto-deleted after 24 hours |
| **Used for reflections** | Yes | No, excluded |
Incognito applies to the whole task, including any subagents it spawns. Once it expires, messages and files are permanently gone.
***
## Understanding credit costs
Agents consume credits for AI model usage, tool calls, the compute time they spend working, and an orchestration fee on top of those. Cost depends on the model, message length, task history, and the number of tools available.
The task's running credit total sits next to its name in the header. Select it to open the task's details drawer, which shows the source, creation time, model, and participants, plus a row for each credit type the task was actually charged for: **Chat & Reasoning**, **Tool Calls**, **Compute**, **Orchestration Fee**, and **Evaluation & Self-Improvement**.
![Chat details drawer opened from the credit count in the chat header, showing source, created time, model, participants, and a credit breakdown by type]()
Full model pricing, integration costs, and how to track usage.
***
## Settings
The **Settings** tab covers how the agent presents itself and how the model behaves.
![Settings tab showing Identity, Suggested Prompts, Advanced AI, Chat Summarization, Model Fallback, and Destructive]()
| Section | What it controls |
| - | - |
| **Identity** | The agent's icon, name, and description. |
| **Suggested Prompts** | Prompts shown on the agent's home screen so people know what to ask. |
| **Advanced AI** | Max steps, parallel tool calls, max output tokens, and context window. See [AI advanced settings](#ai-advanced-settings). |
| **Chat Summarization** | When and how older messages are compacted as a task gets long. |
| **Model Fallback** | Which model the agent switches to if the primary one is unavailable. |
| **Destructive** | Delete the agent. |
Two things that used to live here have moved: file sharing for generated files is now **File Sharing** on the [Access](/core-concepts/agent_access#file-sharing) tab, and Slack behavior is now under **Channels → Slack**. **Secrets** is a section on the **Agent** tab.
***
## Channels
An agent is not limited to Gumloop. **Channels** in the agent sidebar is the single place you make it reachable somewhere else — every surface is set up from there, one per item in the list.
![Channels page with Email Inbox, Slack, Microsoft Teams, Hosted Page, Developer, and MCP in a sidebar]()
| Channel | What it gives you |
| - | - |
| **Email Inbox** | The agent gets its own email address. Email it, forward mail to it, or CC it on a thread. |
| **Slack** | Talk to the agent in Slack channels and DMs. |
| **Microsoft Teams** | Talk to the agent in Teams. |
| **Hosted Page** | A public or private chat page you can link or embed. |
| **Developer** | The API and SDK details for calling the agent from your own code. |
| **MCP** | Expose the agent as an MCP server so other AI tools can call it. |
Deploy agents to Slack channels for team-wide access.
Deploy agents to Microsoft Teams channels.
Give your agent an inbox it can read and reply from.
Share a public or private hosted page for your agent.
***
## Finding agents
The **Agents** page lists every agent you can access. Use the tabs to switch views:
| Tab | What it shows |
| - | - |
| **Mine** | Agents you created. |
| **Shared with me** | Agents others shared with you directly or through your organization. |
| **Organization** | All agents visible to your organization. |
![Agents page showing the Shared with me tab with agent cards]()
Each card shows the agent name, connected apps, creator, and last activity. You can search by name and switch between grid and list views.
***
## Usage stats
A line under the agent's description summarises how it has been used over the **last 31 days**: how many tasks it worked on, and on a team agent, who used it most (**Used by Ana, Ben and 4 others · 62 tasks in the last month**, with avatars for the top users). A personal agent reads **Worked on 62 tasks in the last month**.
Stats respect [Task Visibility](/core-concepts/agent_access#task-visibility). If you can only see your own tasks on an agent, the numbers cover just your usage and no users are named. Subagent runs are excluded, and [incognito](#incognito-mode) tasks never count.
For the full picture — credits over time, credits by model and member, connector and skill usage — open **Performance** in the agent sidebar. See [Agent Performance](/core-concepts/agent_performance). Organization-wide reporting lives in [Insights](/enterprise-features/organization_insights).
***
## Managing tasks
Every task appears under **Recents** in the sidebar. Right-click a task or open its three-dot menu to manage it.
![Task context menu showing Share, Rename, and Delete options]()
| Action | What it does |
| - | - |
| **Share** | Share the task as a read-only link. |
| **Rename** | Give the task a custom name so you can find it later. |
| **Delete** | Permanently remove the task. |
Rename tasks to keep your sidebar organized. "Q2 Marketing Plan" is easier to find than an auto-generated title.
***
## Guardrails
For agents that take real actions, layer on guardrails so they stay within bounds.
Make the agent pause for approval before write, delete, and other sensitive tool calls.
Set conditions that block or flag specific tool calls at the agent or organization level.
***
## Self-improving instructions
Your agent can update its own instructions while it works. Correct it once ("always check Salesforce first," "keep emails under 100 words") and it edits its instructions so the same mistake does not happen again. Changes take effect on the next step and persist across future tasks. The toggle sits below the system prompt editor and is on by default; there is no version history, so revert by editing the prompt manually.
***
## AI advanced settings
Most agents never need this. Defaults are already set for a good balance of performance, cost, and reliability. Organization admins can set the defaults that new agents inherit. See [Agent Default Settings](/enterprise-features/agent_default_settings).
Open the **Settings** tab, then expand **Advanced AI**, **Chat Summarization**, or **Model Fallback**.
![Settings tab with Advanced AI, Chat Summarization, and Model Fallback expandable sections]()
Per-provider model parameters. Switching models preserves your preferences for each provider.
| Setting | What it does |
| - | - |
| **Max Steps** | How many actions the agent can take before responding — each tool use is one step. Default 100, range 1 to 200. |
| **Verbosity** | Length and detail of the response: low, medium, or high. |
| **Parallel Tool Calls** | Whether the model can run tool calls in parallel. |
| **Max Output Tokens** | Upper bound on generated tokens, including visible output and reasoning tokens. Defaults to Auto. |
| **Max Tool Calls** | Cap on total built-in tool calls; further attempts are ignored. Defaults to Auto. |
| **Top P** | Nucleus sampling, 0 to 1. Change this *or* temperature, not both. |
| **Top Logprobs** | How many likely alternatives to return per token, 0 to 20. |
| **Context Window** | How much of the model's context the agent uses before older messages are summarized. Only shown for models that offer two windows. |
| **Thinking** | How hard the model thinks before it answers, and whether it thinks at all. Shown only for models with a thinking control — see [Thinking controls](/core-concepts/ai_models#thinking-controls). |
**Reset Model Parameters to Defaults** restores these values for the current provider.
Some models ship two context windows. When your agent is on one of those models, **Context Window** appears under Advanced AI.
| Choice | What it does |
| - | - |
| **The larger window** (default) | Uses the model's full context. Keeps the most history. |
| **The smaller window** | Summarization starts earlier, which lowers cost and latency. |
| Model | Short | Long |
| - | - | - |
| GPT-6 Astra, GPT-6.1 Sol, GPT-6 Sol, GPT-6 Luna, GPT-5.6 Sol, Terra, Luna | 272K | 1.05M |
| Claude 5.5 Opus, Claude 5 Opus, Claude 4.8 Opus, Claude 5.5 Sonnet, Claude 5 Sonnet, Claude 4.6 Sonnet, Claude Fable 5.1, Claude Fable 5 | 300K | 1M |
| Grok 4.7, Grok 4.6 | 200K | 500K |
Every other model has a single window and never shows the setting. The choice is saved per provider. It is not sent to the model provider: it changes the context budget Gumloop enforces.
GPT-5.6 and Grok 4.6/4.7 charge higher long-context rates once a request's input tokens cross the short window, and the higher rates apply to the whole request. Claude's 1M-token models bill at one flat rate.
When a task approaches the model's context limit, older messages are compacted into a structured recap while recent messages are kept in full.
Defaults: summarization starts at **80%** of the context window, roughly the most recent 40,000 tokens are protected, and summaries are capped around 30,000 tokens.
Turn on **Override Auto Summarization** to tune **Summarization Trigger (%)**, **Summary Model**, **Protected Context Tokens**, and **Max Summary Tokens**. A lower trigger summarizes sooner and costs less per turn. A higher trigger keeps more raw history.
If the primary model is unavailable or unreachable, the agent retries and then switches to a fallback from a different provider. **Enable Model Fallback** is on by default. Turn on **Override Auto Fallback** to pick fallback models yourself.
Browse the full model catalog by tier, vision models, and bring-your-own-key (BYOK).
***
## Best practices and troubleshooting
Begin with two or three apps and short instructions. Test, watch how the agent behaves, then add tools and rules based on real usage. Avoid launching with 15 tools and a 2,000-word prompt.
When the agent makes a mistake, ask it: "What could I add to your instructions to prevent this?" Then have it update its own instructions or a skill. Review past tasks for patterns.
Be explicit about what the agent should never do without approval: delete records, send emails, make purchases, or modify production data. Back this up with [Tool Management](#tool-management-and-approvals) approvals.
Make tool names more descriptive, add "when to use" guidance in the system prompt, and reduce similar tools that might confuse it.
Check the app's [account selection](#account-selection), authenticate on your [Connectors page](https://www.gumloop.com/settings/profile/connectors?view=connected), and set it as your personal default. For team agents, contact your team admin.
Tune the app's [Tool Management](#tool-management-and-approvals) preset, or list in the system prompt which actions need approval and which can proceed automatically.
Switch to a cheaper model for simple tasks, add your own provider API key (BYOK) to waive model credits entirely, start new tasks instead of long threads, reduce the tool count, and write clearer prompts to cut back-and-forth.
Check that every required app is connected and authenticated, review the task for the specific tool error, and raise **Max Steps** under **Settings → Advanced AI** if the task needs many tool calls in sequence.
***
## Next steps
Run agents automatically on a schedule or in response to events.
Build reusable knowledge packs that teach agents how to do specific work.
Give agents company knowledge to search from your connected sources.
Grade agent responses and catch regressions before they ship.
Let agents review their own work and propose improvements.
Run code securely and manage agent secrets.
Owners, Users, User Permissions, and Task Visibility.
# Agent email inbox
Source: https://docs.gumloop.com/core-concepts/agents_email
Give your agent a dedicated email address so anyone can interact with it by sending an email.
Each agent gets a unique `@gumloop.ai` email address that routes messages straight to the agent.
Email replies stay threaded. The agent maintains full conversation history across multiple email exchanges.
Send files as email attachments and the agent can process them just like it would in chat.
Update the email alias or disable the inbox whenever the agent no longer needs it.
***
## Enabling the email inbox
Open **Channels** in the agent sidebar, then select **Email Inbox**.
![Channels page with Email Inbox selected, showing the inbox address, attribution stamp, and email list]()
Click **Enable Email Inbox**. Gumloop automatically generates a unique email alias based on your agent's name. The alias follows the format:
```text theme={"dark"}
your-agent-name@gumloop.ai
```
![Email Inbox enabled showing the generated email address with copy and edit buttons]()
You can copy the address using the copy button, or click the pencil icon to customize the alias.
Send an email to your agent's address from any email client. The agent processes the message and replies directly to the sender's inbox.
![Email conversation showing a user message and the agent's response inside the Gumloop chat interface]()
All email interactions also appear in the agent's chat history inside Gumloop, so you can review conversations from either place.
***
## Customizing the email alias
You can change the email alias at any time:
1. Open the **Email Inbox** page for your agent
2. Click the **pencil icon** next to the current address
3. Type your preferred alias and press **Enter** (or click the checkmark)
**Alias rules:**
* 3 to 64 characters
* Alphanumeric characters and hyphens only
* Must start and end with a letter or number
When you change the alias, the old address stops working immediately and the new address becomes active. Any emails sent to the old alias after the change will not be delivered.
Changing the alias means anyone using the old address will need to update it. Share the new address with your team after making changes.
***
## How it works behind the scenes
When someone sends an email to your agent's address, here is what happens:
1. **Email received**: The inbound email arrives at `gumloop.ai` and is routed to Gumloop's email processing service.
2. **Agent lookup**: Gumloop looks up which agent is registered to the email alias.
3. **Sender verification**: Gumloop verifies the message's DKIM signature against the sender's domain and matches the sender's email to a Gumloop account. The sender must have a Gumloop account, and their domain must have DKIM configured. Messages without a valid DKIM signature are rejected. See [Sender Domain Authentication (DKIM)](#sender-domain-authentication-dkim) for setup details.
4. **Permission check**: Gumloop verifies that the sender has permission to use the agent (same access control as the chat interface).
5. **Thread resolution**: If the email is a reply, Gumloop matches it to an existing conversation using email headers (`References`, `In-Reply-To`). New emails start a fresh conversation.
6. **Attachment processing**: Any file attachments are decoded and stored securely, then passed to the agent as file inputs.
7. **Agent execution**: The agent processes the message using the same AI engine as the chat interface, with access to all configured tools and integrations.
8. **Reply sent**: The agent's response is formatted as an HTML email and sent back to the sender (and any CC'd recipients). File outputs from the agent are included as attachments.
9. **Conversation persisted**: The full exchange is saved to the agent's interaction history, visible in both the Gumloop UI and future email threads.
The email channel uses the same AI agent engine, tools, and credentials as the chat interface. There is no difference in agent capabilities between email and chat.
***
## Sender domain authentication (DKIM)
Gumloop verifies the **DKIM signature** of every inbound email so it can confirm that the sender's domain actually authorized the message. Without this check, anyone could spoof an email from a teammate's address and gain access to that user's agents and credentials.
If the sender's domain does not have DKIM configured, the email is rejected. The sender usually receives a generic bounce from their mail provider that looks like an "Address not found" or "domain couldn't be found" error, even though the real cause is missing DKIM on their own outbound mail.
### When this affects you
* **Personal accounts** on Gmail, Outlook, iCloud, and similar consumer providers already have DKIM enabled by default. No action is needed.
* **Workspace and corporate domains** (custom domains hosted on Google Workspace, Microsoft 365, or another provider) need DKIM enabled by an administrator before they can email a Gumloop agent.
### Setting up DKIM on your domain
Ask your IT administrator to enable DKIM signing for the sending domain. Both major providers have step-by-step guides:
Generate a DKIM key in the Admin console, add the provided TXT record to DNS, then turn on signing.
Add the two CNAME records for your custom domain in DNS, then enable DKIM in the Microsoft Defender portal.
DNS changes can take up to 48 hours to propagate. Once DKIM is active and outbound mail is signed, emails to your agent will go through.
If you administer your own mail server, configure DKIM using your provider's documentation and confirm a `DKIM-Signature` header is present on outbound messages. Gumloop accepts any valid DKIM signature where the signing domain (`d=`) matches the sender's domain.
### Confirming DKIM is the cause of a bounce
If an email to your agent bounced and you're not sure why, open the bounce message and view the original headers:
* **Gmail**: open the message, click the three-dot menu, then **Show original**.
* **Outlook**: open the message, click **File > Properties** (desktop) or the three-dot menu and **View message source** (web).
Look at the `Authentication-Results` header. A line like `dkim=none` or `dkim=fail` (or no DKIM line at all) confirms the sender's domain is not signing outbound mail.
***
## Threading and conversation history
The email inbox supports full conversation threading:
* **New emails** start a new conversation with the agent.
* **Replies** (using your email client's reply button) continue the existing conversation. The agent has access to the full thread history.
* **CC recipients** are preserved. When the agent replies, it CCs everyone who was on the original email.
* **Subject lines** are included as context for new conversations, helping the agent understand the topic.
The agent uses standard email headers (`References` and `In-Reply-To`) to track threads, so threading works correctly across Gmail, Outlook, Apple Mail, and other email clients.
***
## Connectors and accounts
Email tasks use the same connector account settings as Gumloop chat:
* **Use Personal Default** uses the sender's connected account for each service
* If the sender has not authenticated with a required service, the agent will notify them in the reply
* Team accounts, specific account selections, and [agent-owned accounts](/core-concepts/credentials#agent-owned-credentials) apply the same way as in chat
The sender's email address must match their Gumloop account email. If someone sends an email from an address not associated with a Gumloop account, they will receive an error reply asking them to sign up.
***
## Concurrency and rate limits
Email agent interactions follow the same concurrency limits as other agent channels:
* If you have too many agent interactions running simultaneously, the email will receive a reply explaining that the request was rate-limited
* **Enterprise users** benefit from automatic queuing: instead of being rejected, their messages are queued and processed in order. The sender receives a notification with their queue position.
* If a message takes too long to process (exceeds the time limit), the sender receives an error reply
***
## Disabling the email inbox
To turn off the email inbox:
1. Open the **Email Inbox** page for your agent
2. Click the red **Disable** button
Once disabled, any emails sent to the agent's address will no longer be delivered. You can re-enable the inbox at any time.
***
## Permissions
Managing the email inbox requires **Owner** access to the agent. Users cannot enable, disable, or change the email alias.
Organization admins can also restrict email inbox access using **policy controls**. If email inboxes have been restricted by your admin, you will see a message indicating this on the setup page.
***
## Troubleshooting
This almost always means the sender's domain does not have DKIM signing enabled. The bounce message from your mail provider can be misleading: `gumloop.ai` exists and is reachable, but Gumloop rejected the message because the DKIM signature could not be verified.
**Fix**: Ask your IT administrator to enable DKIM on the sender's domain. See [Sender Domain Authentication (DKIM)](#sender-domain-authentication-dkim) for the Google Workspace and Microsoft 365 setup guides.
To confirm this is the cause, open the bounce email, view the original headers, and look for `dkim=` in the `Authentication-Results` header. A `dkim=none` or missing DKIM signature confirms the issue.
The sender's email address must match an existing Gumloop account. Either invite them to your organization or have them sign up at [gumloop.com](https://gumloop.com) using the same email address they're sending from.
Check the agent's chat history in Gumloop. If the email made it through, the conversation will appear there. If not, the email was rejected before it reached the agent. Common causes:
* DKIM is not configured on the sender's domain (see above).
* The sender's email does not match a Gumloop account.
* The sender does not have permission to use the agent.
* The email inbox has been disabled or restricted by an admin policy.
***
## FAQ
Anyone with a Gumloop account and read access to the agent can send emails to it. The sender's email address must match the email on their Gumloop account, and the sender's domain must have DKIM configured.
Not currently. All agent email addresses use the `@gumloop.ai` domain. Custom domain support may be added in the future.
You will receive an error reply asking you to sign up for a Gumloop account at [gumloop.com](https://gumloop.com).
Yes. File attachments are processed and made available to the agent. The agent can also send files back as attachments in its reply.
If you CC other people on your email to the agent, the agent's reply will also CC those recipients. This makes it easy to keep team members in the loop.
No. The email inbox is inbound-only. The agent only replies to emails it receives. It cannot initiate email conversations on its own. If you need outbound email capabilities, use the Gmail or email MCP integrations as agent tools.
The agent replies in HTML format with clean formatting, including support for headings, lists, code blocks, and tables. The reply also includes a plain-text fallback for email clients that do not render HTML.
Yes. An agent can be connected to Slack, email, and the Gumloop chat interface simultaneously. Each channel maintains its own conversation threads.
Existing conversation threads are preserved in the agent's history. However, replies to those threads using the old email address will no longer be delivered. You would need to start a new email thread using the new address.
Standard email size limits apply. Very large attachments may fail to process. For best results, keep individual attachments under 25 MB.
Gumloop uses DKIM signature verification to confirm that emails really came from the sender's domain. Without it, anyone could spoof a teammate's address and access their agents and credentials. Personal Gmail and Outlook accounts already have DKIM. Custom workspace domains need an admin to enable it. See [Sender Domain Authentication (DKIM)](#sender-domain-authentication-dkim).
# Using agents in Slack
Source: https://docs.gumloop.com/core-concepts/agents_slack
Connect your Gumloop agents to Slack channels so your team can work with them in the tool they already use every day.
Connect a bot and add the agent to a channel.
@mention, forward, stop, and follow threads.
Thread replies, detailed steps, and the attribution stamp.
Who can run the agent and whose accounts it uses.
`/gummie`, `!stop`, and `!link`.
Fixes for the most common problems.
## Why use agents in Slack?
Every interaction in a channel is visible to the team, so people learn how to use the agent by watching each other.
Your team already talks in Slack. The agent joins those conversations without a new tool to learn.
Instead of one person running automations, the whole channel uses the same agent with consistent results.
If your team knows how to @mention someone in Slack, they know how to use an agent.
## Add an agent to Slack
Connecting or disconnecting Slack bots requires **Owner** access to the agent.
Open **Channels** in the agent sidebar, then select **Slack**.
![Channels page with Slack selected, showing Add Slack bot, Slack preferences, and the list of bots and channels]()
Click **Add Slack bot** to connect the default Gumloop bot or a [custom Slack app](/core-concepts/custom_slack_app). Connecting Slack the first time uses your [Connectors](https://www.gumloop.com/settings/profile/connectors?view=connected) account.
Click **Add to Channel** and pick a tab:
* **New Channel** creates a Slack channel and adds the bot. Pick a workspace, enter a name, and optionally turn on **Make Channel Private**.
* **Existing Channel** adds the bot to a channel that already exists.
* **Commands** shows the `/gummie add` command if you prefer to paste it in Slack.
![Add to a Slack channel sheet with New Channel, Existing Channel, and Commands tabs]()
Once the bot is in a channel, the **Slack bots** and **Slack channels** tables on the same page show each channel's members, task count, and when the agent was last used.
**One agent per channel** with the standard @Gumloop bot. To switch agents, run `/gummie remove` first. To run several agents in one channel, give each additional agent its own [Custom Slack App](/core-concepts/custom_slack_app).
Custom agents work in **public and private channels**, not in direct messages. DMs to the Gumloop app go to your personal [Gumball](#direct-messages-go-to-gumball).
## Talk to your agent
### Mention the agent
**@mention** the agent in any message in the channel:
```text theme={"dark"}
@Gumloop [your question or task]
```
Mention it in a **top-level message** to start a new thread, or inside an **existing thread** to continue the conversation. The agent always replies in the thread.
![Agent interaction in Slack showing an @Gumloop mention and the agent's threaded response]()
### Forward a message
Forward any Slack message to the agent and it treats the message as a task. The agent reads the forwarded text, formatted Block Kit content, and attached files, so you don't need to copy and paste.
### Follow the agent's progress
While the agent works, a progress card in the thread shows what it is doing, for example *Thinking...*, *Working on it...*, or *Waiting for results...*. When the run ends, the card shows how long it took, then the agent posts its answer.
By default the card lists each step the agent takes. To show only a short status and step count, turn off [Show Detailed Steps](#show-detailed-steps).
### Stop a response
While the agent is working, Slack can show a **Working…** indicator with a **Stop** button in the thread. Click **Stop** to end the agent's current run.
* If the agent already posted, its message reads *This response was stopped.*
* If it had not posted anything yet, it replies *Stopped this chat.*
* Other agents in the same thread keep running.
You can also type `!stop` in the thread. See [Thread commands](#thread-commands).
Slack only shows the **Stop** button for apps subscribed to Slack's `agent_session_stopped` event. For a custom Slack app, see [Stopping a response](/core-concepts/custom_slack_app#stopping-a-response).
### Continue a thread someone else started
Anyone in the channel who is allowed to run the agent can reply in a thread another person started, and the agent continues that conversation. Once you reply in the thread, you can also:
* Open the conversation in Gumloop as a viewer.
* Download files the agent shares in the thread.
Who can run the agent is set by its [sharing settings](/core-concepts/agent_access). People from another organization can't continue the thread.
### Files and images
Files the agent creates are uploaded straight into the thread. When the agent uses **Image Generation**, Slack gets both the **image file** and a **link**. Turn on **Image Generation** in the agent's **Abilities** section to enable it.
![Abilities section of an agent showing Image Generation turned on]()
Current image models include **GPT-Image 2.5 Flare**, **GPT-Image 2.5 Sunburst**, **GPT-Image 2**, **Gemini 3.1 Flash (Nano Banana 2)**, **Gemini 3 Pro**, and **Gemini 2.5 Flash Image**.
Image generation is charged like any other model call, based on the usage the image model reports. Higher quality or resolution costs more credits. See [Credits](/core-concepts/credits) for how BYOK affects image generation.
### Rich messages and buttons (Block Kit)
The standard @Gumloop bot can post [Block Kit](https://docs.slack.dev/block-kit/) messages, including sections, dividers, context lines, images, and buttons. You don't need a [Custom Slack App](/core-concepts/custom_slack_app) for this.
The agent's normal thread replies are formatted text. To send Block Kit, the agent uses the **Slack** connector:
1. Add the **Slack** connector to the agent.
2. Ask the agent to post a Block Kit message, or describe the message in its instructions, for example:
```text theme={"dark"}
@Gumloop Post a Block Kit message in #releases with a summary section, a divider,
and two link buttons: "Open release notes" and "View dashboard".
```
The Slack connector's **Send Message**, **Send Ephemeral Message**, **Update Message**, and **Schedule Message** tools all accept Block Kit `blocks`, so the agent can post to a channel or thread, show a message to one person, edit a message it sent, or schedule one for later.
* **Who it posts as**: messages go out as the Gumloop bot. If the agent has a custom Slack app, they go out as that app instead. See [Choosing Which Bot the Agent Acts As](/core-concepts/custom_slack_app#choosing-which-bot-the-agent-acts-as).
* **Attribution**: when the [Slack Attribution Stamp](#slack-attribution-stamp) is on, Gumloop adds a *Sent by* line with a **View conversation** link to the bottom of messages sent with **Send Message**.
* **Buttons**: link buttons (buttons with a `url`) open their link when clicked. Clicks on other buttons aren't sent back to your agent. To have someone approve or reject an action from Slack, use [approvals](/core-concepts/human_in_the_loop) instead.
Gumloop also posts its own interactive messages in the thread when needed:
* **Approve** and **Reject** buttons when an action needs [approval](/core-concepts/human_in_the_loop)
* **Connect** and **Add** buttons when the agent needs an account or connector. See [Whose accounts the agent uses](#whose-accounts-the-agent-uses)
* **Request Access & Setup** when someone isn't allowed to use the agent. See [Who can use the agent](#who-can-use-the-agent)
* Browser handoff buttons when the agent needs you to finish a step in its browser. See [Agent Browser](/core-concepts/agent_browser)
### Direct messages go to Gumball
You can **DM the Gumloop app** in your workspace with no channel, no @mention, and nothing to set up. Those DMs are answered by your own [Gumball](/core-concepts/gumball#gumball-in-slack), the personal agent that comes with every Gumloop account, running on your connectors and skills.
DMs never reach a custom agent. To DM a custom agent under its own name and avatar, connect a [Custom Slack App](/core-concepts/custom_slack_app#direct-messages-dms) for it.
**Need custom branding?** Connect your own Slack app so the agent appears with its own name and avatar instead of "@Gumloop". See [Custom Slack App Integration](/core-concepts/custom_slack_app).
## Slack preferences
Three preferences on **Channels → Slack** control how the agent behaves in Slack. They apply to every channel the agent is in, and changes take effect for new messages right away.
| Preference | What it controls | Default |
| - | - | - |
| [Thread Replies](#thread-replies) | When the agent answers thread replies that don't @mention it | **Auto** |
| [Slack Attribution Stamp](#slack-attribution-stamp) | The agent name and **View conversation** link under each reply | On |
| [Show Detailed Steps](#show-detailed-steps) | Whether the progress card lists each step | On |
### Thread Replies
The **Thread Replies** dropdown controls when the agent replies inside a thread it is already part of.
![Slack preferences on the Channels page with the Thread Replies dropdown open, showing Auto, Only on mentions, and On all messages]()
The agent decides whether a thread reply is meant for it, so nobody has to @mention it every time.
* **Two-party threads**: while the thread has only you and the agent, it replies to every message, the same as **On all messages**.
* **Group threads**: once a thread has three or more parties (people and other bots both count), Gumloop checks each message that doesn't @mention the agent and decides which agent in the thread, if any, it is for. The agent replies only when it is picked. If several agents share the thread, the message is judged once and at most one of them answers.
* **Messages for someone else**: a reply that @mentions anyone other than the agent, or a broadcast (`@here`, `@channel`, or a user group), is skipped without a check.
**Example**: Three people are in a thread with the agent. "Can you also break that down by team?" gets an answer from the agent. "Gonzalo, can you review the PR later today?" does not.
Auto uses the **Jev 1.13** model to make the decision. If you don't have access to Jev 1.13, **Auto** is disabled in the dropdown and a **Request access** button appears under Thread Replies. An Auto agent whose creator doesn't have access to Jev 1.13 keeps replying in two-party threads but stays quiet in group threads unless @mentioned.
The agent only responds when explicitly @mentioned. Your team can discuss in the thread without triggering it.
**Example**: After `@Gumloop analyze this customer`, your team can discuss the results freely. The agent only responds again when someone @mentions it with a follow-up.
The agent responds to every thread reply, no @mention needed, while the thread is just you and the agent.
**Example**: You start with `@Gumloop analyze this customer`. A follow-up like "What about their purchase history?" triggers the agent automatically.
Once a third person joins the thread, the agent switches to replying only when @mentioned in that thread. Use **Auto** if you want the agent to keep answering follow-ups in group threads.
### Slack attribution stamp
Each agent reply includes an **attribution stamp** with the agent's name and a **View conversation** link to the full conversation in Gumloop, including tool calls and credit usage.
![Slack message from Gumloop showing the attribution stamp with the agent name and View conversation link]()
The stamp also appears on messages the agent sends with the Slack connector's **Send Message** tool, such as [Block Kit messages](#rich-messages-and-buttons-block-kit) posted to another channel.
The stamp is on by default. Turn off **Slack Attribution Stamp** on **Channels → Slack** to hide it for this agent.
### Show Detailed Steps
**Show Detailed Steps** controls how much the [progress card](#follow-the-agents-progress) shows while the agent works.
* **On (default)**: the card lists each step the agent takes, so the channel can see what it searched, read, or ran.
* **Off**: the card shows a short status and a step count. Useful in busy channels or when the agent calls many tools per answer.
## Access and connected accounts
### Who can use the agent
Being in the Slack channel is not enough on its own. A person can run the agent only if its [sharing settings](/core-concepts/agent_access) allow it:
| General Access | Who can use the agent in Slack |
| - | - |
| **Restricted** | Owners and people added by email |
| **Team** | Everyone in the team the agent lives in |
| **Organization** | Everyone in your organization |
| **Anyone** | Anyone with a Gumloop account linked to their Slack email |
Anyone else gets an **Access Required** message in Slack with a **Request Access & Setup** button.
### Whose accounts the agent uses
When you message an agent in Slack, each connector uses its configured account setting: **Use Personal Default**, **Use Team Default** (team agents only), or **Use Specific Account**. By default, it uses **your** connected accounts, not the agent creator's. An explicitly [agent-owned account](/core-concepts/credentials#agent-owned-credentials) is shared by everyone with access to the agent. See [Choose which account to use](/core-concepts/credentials#in-agents).
If your Slack email matches your Gumloop account, the agent uses your connected accounts right away with no extra setup.
**Example**: If the agent uses Gmail and Google Calendar, it reads your Gmail and your Calendar.
The first time you message the agent, it replies with an **Account Required** prompt.
![Gumloop signup prompt in Slack with a Get Started with Gumloop button]()
1. Click **Get Started with Gumloop** and sign up with your Slack email.
2. Connect the services the agent needs.
3. Go back to Slack and @mention the agent again.
Your Slack and Gumloop email addresses must match.
**Enterprise organizations can skip this for specific agents.** An admin can register your Slack workspace and let its members message chosen agents with no Gumloop account, running on a shared organization service account. See [Organization Service Accounts for Slack Agents](/enterprise-features/slack_agent_access).
If the agent needs an account you haven't connected, it posts a message in the thread with a button to fix it, for example:
```text theme={"dark"}
🔑 You cannot use `Send Email` tool since your Gmail account is not connected.
[Connect Gmail on Gumloop]
```
If the connector isn't on the agent at all, the message reads *To continue, add Gmail to this agent.* with an **Add Gmail** button. Connect or add it, then ask the agent again.
### Share connectors with a team
To let teammates use the agent without connecting their own accounts, put the agent in a team and switch its connectors to team accounts.
Teams are available on **Pro** and **Enterprise** plans.
On the [Home page](https://www.gumloop.com/hub), find **Teams** in the sidebar and click **+** to create a team.
![Click the plus icon in the Teams sidebar section]()
To include everyone automatically, set a **default team** that all organization members join. Go to [Settings → Teams](https://www.gumloop.com/settings/organization/teams), open the three-dot menu next to a team, and select **Make Default**.
![Teams list with the three-dot menu open on Make Default, described as setting the team as the organization default]()
On the Home page, open the agent's three-dot menu (⋮), select **Move to Team**, and choose the team.
![Agent three-dot menu showing Copy Link, Share, Pin to My Sidebar, Rename, Duplicate, Move to Team, and Delete]()
Expand the team in the sidebar and open **Connectors**, then add the integrations the agent needs (for example Gmail, Google Drive, or Salesforce).
![Team Connectors page with Discover, All, and Connected tabs and a searchable list of connectors]()
In the agent, open the three-dot menu next to each connector and select **Use Team Default**.
![Account menu on an agent connector showing Use Personal Default, Use Team Default, Use Specific Account, and Remove]()
Agents that live in a team are available at least to the whole team, and team connectors only work for team members. People outside the team can't use team connectors through the agent. A **default team** avoids adding people one by one.
### Data privacy
When the agent runs on your personal accounts, only your connected accounts are used. Teammates can't reach your data through the agent.
Admin security controls and roles in Gumloop apply in Slack. You can only reach what you're already allowed to.
## Slack commands
### Channel commands
Type these in the channel's message box.
| Command | What it does |
| - | - |
| `/invite @Gumloop` | Add the Gumloop bot to the channel (required before `/gummie add`) |
| `/gummie add [agent-id]` | Add an agent to the current channel |
| `/gummie remove` | Remove the agent from the current channel |
| `/gummie active` | Show which agent is active in this channel |
| `/gummie help` | Show all available commands |
You rarely need `/gummie add`. **Channels → Slack → Add to Channel** does the same thing, and its **Commands** tab has the full command ready to copy.
### Thread commands
Type these as a reply in the agent's thread.
| Command | What it does |
| - | - |
| `!stop` | Stop the agent's current response and prevent further replies in this thread. The agent reacts with 👍 to confirm. You can also use Slack's [Stop button](#stop-a-response). |
| `!link` | Get a link only you can see to the full conversation in Gumloop, including tool calls and credit usage. |
## Best practices and troubleshooting
Agents work in **public** and **private** channels. Put each agent where its audience already works, for example:
* **#support**: ticket triage and refund checks
* **#sales**: lead research and enrichment
* **#marketing**: campaign planning and content
* **#data**: analysis and reporting
When you add an agent, post a message with what it can do, how to use it (`@Gumloop [your question]`), and one example.
Prefer "Support Ticket Assistant" or "Sales Lead Researcher" over "Agent 1". The name appears in the attribution stamp, and `/gummie active` shows it too.
* **Auto** (default): best for most channels. The agent answers follow-ups meant for it and stays quiet when people talk to each other.
* **Only on mentions**: the agent never replies unless someone @mentions it.
* **On all messages**: for one-on-one threads where the agent should answer every reply.
**Channels → Slack** shows task counts and last activity for each channel. Open the agent's **Tasks** to read the conversations, then refine instructions, connectors, and skills based on where the agent struggles.
Test with your own accounts first, list which services teammates need to connect, and share the [Connectors page](https://www.gumloop.com/settings/profile/connectors?view=connected). Or use [team connectors](#share-connectors-with-a-team) so nobody has to connect anything.
1. Did you @mention the agent?
2. Is the bot in the channel? Run `/invite @Gumloop`.
3. Is an agent active in the channel? Run `/gummie active`.
4. Is this a channel? DMs to the Gumloop app reach [Gumball](#direct-messages-go-to-gumball), not this agent.
5. Do the agent's [sharing settings](#who-can-use-the-agent) include you?
Check **Thread Replies** on **Channels → Slack**. With **Only on mentions**, you must @mention the agent in each reply. With **Auto**, the agent stays quiet in a group thread when a message looks meant for someone else. @mention the agent to make sure it answers.
Your Slack email must match your Gumloop account email. Update one to match the other, then try again.
The agent's sharing settings don't include you. Click **Request Access & Setup**, or ask an Owner to share the agent with you or your team. See [Agent Access](/core-concepts/agent_access).
Click the **Connect** button in the agent's message, or visit your [Connectors page](https://www.gumloop.com/settings/profile/connectors?view=connected). For team connectors, ask a team admin.
With the standard @Gumloop bot, only one agent can be active per channel. Run `/gummie active` to check, `/gummie remove` to clear it, then add the right agent from **Channels → Slack**. For several agents in one channel, use a [Custom Slack App](/core-concepts/custom_slack_app) for each.
* You need **Owner** access to the agent.
* Agents work in public and private channels, not DMs.
* Make sure you're allowed to add apps to the channel in Slack.
* If you use `/gummie add`, run `/invite @Gumloop` first and copy the full agent ID from the **Commands** tab.
Make sure the **Slack** connector is on the agent, then ask it explicitly to post a Block Kit message with the Slack connector, and say which channel or thread to post in. See [Rich messages and buttons](#rich-messages-and-buttons-block-kit).
Only link buttons (buttons with a `url`) do something when clicked. Gumloop doesn't send clicks on other buttons back to the agent. For approve or reject decisions, use [approvals](/core-concepts/human_in_the_loop).
Limit the agent to the connectors it needs, try a faster model, or split big requests into smaller ones.
## Example use cases
**Agent**: Support Ticket Assistant · **Channel**: #customer-support (public) · **Thread Replies**: Auto
```text theme={"dark"}
Teammate: "@Gumloop Is ticket #12345 eligible for a refund?"
Agent: [Checks the ticket, reads the policy, evaluates eligibility]
Teammate (in thread): "What about ticket #12346?"
Agent: [Auto sees the follow-up is for it and checks #12346]
Teammate (in thread): "Priya, can you approve this one?"
Agent: [Stays quiet, the message is for Priya]
```
**Why it works**: Support gets answers without leaving Slack, and follow-ups flow naturally without spamming every reply.
**Agent**: Lead Research Assistant · **Channel**: #sales-team (public) · **Thread Replies**: Only on mentions
```text theme={"dark"}
Teammate: "@Gumloop Research this company: [LinkedIn URL]"
Agent: [Enriches the lead, checks the CRM, drafts outreach]
Teammate (in thread): "Thanks! What's the best time to reach out?"
(No reply, the team discusses freely)
Teammate: "@Gumloop What's the status of opportunities over $50k?"
Agent: [Queries Salesforce, summarizes the pipeline]
```
**Why it works**: Reps get research instantly, and newer reps learn by watching experienced reps use the agent.
**Agent**: Data Analysis Assistant · **Channel**: #data-team (private) · **Thread Replies**: Only on mentions
```text theme={"dark"}
Teammate: "@Gumloop Compare Q4 revenue vs Q3 by product line"
Agent: [Runs a BigQuery query, generates the comparison]
Teammate (in thread): "@Gumloop Now break it down by region"
Agent: [Continues with a regional breakdown]
```
**Why it works**: Analysts get quick answers, and teammates learn what data is available and how to ask for it.
## Important limitations
Only one @Gumloop agent per channel. For more, use a [Custom Slack App](/core-concepts/custom_slack_app) for each.
Custom agents work in public and private channels. DMs to the Gumloop app go to your [Gumball](#direct-messages-go-to-gumball).
You must @mention the agent to start a conversation. In threads, it depends on [Thread Replies](#thread-replies).
Your Slack email must match your Gumloop account email, unless your admin set up an [organization service account](/enterprise-features/slack_agent_access).
## Next steps
Create and configure agents in Gumloop
Give an agent its own name, avatar, and DMs
Deploy the same agents to Microsoft Teams
# Using agents in Microsoft Teams
Source: https://docs.gumloop.com/core-concepts/agents_teams
Connect your Gumloop agents to Microsoft Teams channels so your team can chat with AI-powered assistants where they already work.
Connect your Gumloop agents to Microsoft Teams so anyone in a channel can interact with them using a simple @mention.
## Why use agents in Microsoft Teams?
Bringing agents to Teams transforms how your team learns and adopts AI automation:
**Visibility by default**: Every interaction in a channel becomes a learning opportunity for the team. No more siloed knowledge, everyone sees how to use agents effectively.
**Where work happens**: Teams already use Microsoft Teams for communication. Agents integrate seamlessly into existing workflows without requiring new tools.
**Team-wide access**: Instead of one person running automations, entire teams can leverage the same agent with consistent results.
**Zero learning curve**: If your team knows how to @mention someone in Teams, they know how to use an agent. No training required.
**The Learning Effect**: When someone asks an agent a question in a channel, everyone sees the interaction. This passive learning accelerates team-wide adoption faster than any training session could.
## Prerequisites
Before connecting an agent to Microsoft Teams, make sure you have:
* A **Gumloop account** with an agent you want to deploy
* A **Microsoft 365 work or school account** (personal Microsoft accounts are not supported)
* Permission to install apps in your Microsoft Teams workspace
Microsoft Teams integration requires a Microsoft 365 work or school account. Personal Microsoft accounts (e.g. outlook.com, hotmail.com) cannot be used because the Microsoft Graph API permissions are only available for enterprise tenants.
## Adding an agent to Microsoft Teams
Open **Channels** in the agent sidebar, then select **Microsoft Teams**.
![Channels page with Microsoft Teams selected, showing Microsoft account, Install, and Agent ID]()
If **Microsoft account** is not connected, connect it. This links your Microsoft identity to your Gumloop account so the agent can attribute messages to the correct user when someone @mentions it. You only need to do this once.
Click **Install** next to **Gumloop app for Teams**. Install it once per workspace, then open the channel where this agent should respond.
Agents can only be added to **public (standard) channels**. Private channels are not supported.
In the Teams compose menu, choose **Gumloop**, then **Add Agent**, and paste the **Agent ID** from this page.
Click the copy button next to the agent ID to copy it.
## Using your agent in Teams
To interact with your agent, **@mention Gumloop** in any message:
```text theme={"dark"}
@Gumloop [your question or task]
```
You can `@Gumloop` in a **top-level message** to start a new thread, or inside an **existing thread** to continue the conversation.
You must @mention **@Gumloop** in every message, including thread replies. Unlike Slack, there is no "respond to all messages in thread" mode. The agent only responds when explicitly mentioned.
**One agent per channel.** Only one Gumloop agent can be active in a channel at a time. To switch agents, remove the current one first, then add the new agent using the compose command.
## Teams commands
### Compose extension commands
Teams uses compose extension commands (accessed from the compose menu) instead of Slack-style slash commands.
| Command | What It Does |
| - | - |
| **Add Agent** | Add an agent to the current channel by pasting its agent ID |
| **Remove** | Remove the active agent from the current channel |
| **Active** | Show which agent is currently active in this channel |
| **Help** | Show available commands and usage instructions |
### Thread commands
| Command | What It Does |
| - | - |
| `!stop` | Stop the agent's current response and prevent further replies in this thread |
| `!link` | Get a link to view the full conversation in Gumloop, including tool calls and credit usage |
## Connectors and accounts
### Which account the agent uses
The agent uses the account selected for each connector, just as it does in Gumloop chat. **Use Personal Default** uses the running user's account; **Use Team Default** uses a shared team account. An explicitly [agent-owned account](/core-concepts/credentials#agent-owned-credentials) is used by everyone with access to the agent. See [Connectors](/core-concepts/credentials#in-agents) for all account-selection options.
If your Microsoft 365 email matches your Gumloop account:
1. The agent automatically uses your personal default connected accounts
2. You have immediate access to all tools you're authorized to use
3. No additional setup required
**Example**: If the agent uses Gmail and Google Calendar, it will access your personal Gmail and Calendar using your connected accounts.
If you're not yet a Gumloop user, you'll see a signup prompt the first time you try to use an agent.
**What happens**:
1. Agent responds with a message asking you to sign up
2. Click the link to create your Gumloop account using your Microsoft 365 email
3. After signing up, authenticate with the services the agent needs
4. Return to Teams and @Gumloop the agent again
You must use the same email address for Microsoft 365 and Gumloop for the integration to work properly.
If the agent needs a service you haven't connected yet:
1. The agent will notify you about the missing authentication
2. Visit your [Connectors page](https://www.gumloop.com/settings/profile/connectors?view=connected)
3. Authenticate with the required service
4. Return to Teams and retry your request
**Recommendation**: Always create agents in your personal space unless you need shared team connectors or team collaboration features.
**Personal Agents** (created in personal space):
* Channel members can use the agent when its [Access settings](/core-concepts/agent_access) allow it
* Each user's request runs on their own connected accounts
* Non-Gumloop users will be prompted to sign up
* Best for most use cases
**Team Agents** (created in a team):
* **Access control**: Team members get User access by default; Owners can also share the agent with people outside the team
* **Account selection**: If a connector is set to **Use Team Default**, the shared team account is used instead of the running user's personal account
* People without access are denied, even if they can see the channel
Learn more about the differences between personal and team spaces in the [Organizations and Teams documentation](/core-concepts/teams#personal-vs-team).
| Feature | Personal Agent | Team Agent |
| - | - | - |
| Who can use it? | People allowed by the agent's Access settings | Team members by default, plus anyone else the agent is shared with |
| Connected account | Personal default, unless a specific account is configured | Personal default or team default, depending on the connector's account setting |
| Best for | General use, maximum accessibility | Team collaboration with shared accounts |
For a full walkthrough on configuring team connectors with agents, see [Share connectors with a team](/core-concepts/agents_slack#share-connectors-with-a-team).
### Data privacy & security
When you use an agent with personal credentials, only your connected accounts are used. Other team members cannot access your personal data through the agent.
Admin security controls and user roles in Gumloop apply to agents. You can only access what you're authorized to access.
## Current limitations
The Microsoft Teams integration has a few differences compared to the [Slack integration](/core-concepts/agents_slack). These are mostly due to technical limitations in the Teams platform.
Agents can only be added to **public (standard) channels**. Private channels in Teams are not supported.
Agents cannot receive or process file attachments sent in Teams messages. Text-only interactions are supported.
Unlike Slack, there is no custom app option. All agents respond as **@Gumloop**, so you cannot customize the bot name or avatar.
You must @mention **Gumloop** in every message, including thread replies. There is no "respond to all messages in thread" mode like in Slack.
## Best practices & troubleshooting
Deploy agents strategically to appropriate channels:
**Supported channel types**:
* Public (standard) channels
* **Not supported**: Private channels, direct messages, or group chats
**Example deployments**:
* **Support**: Customer service agents with ticket triage capabilities
* **Sales**: Lead research and enrichment agents
* **Marketing**: Campaign planning and content strategy agents
* **Data**: Data analysis and reporting agents
When adding an agent to a channel, post a message explaining what the agent can do, how to use it (`@Gumloop [your question]`), and a quick example. This reduces friction and encourages proper usage.
Give agents clear names so your team knows what each one does:
* "Support Ticket Assistant", "Sales Lead Researcher"
* Not: "Agent 1", "My Bot"
Unlike Slack, Teams requires an @mention for every interaction, including thread replies. Remind your team that `@Gumloop` is needed each time they want the agent to respond.
Before deploying to a team channel: test with your own connected accounts, document which services team members need to authenticate with, and share the [Connectors page](https://www.gumloop.com/settings/profile/connectors?view=connected) link.
For maximum automation, combine agents in Teams with [event-based triggers](/core-concepts/agent_triggers). The agent handles ad-hoc questions in the channel while triggers automatically process events like new emails, tickets, or database changes.
1. Did you @Gumloop the agent in your message? (Required for every message, including thread replies)
2. Is the Gumloop app installed in the channel?
3. Has an agent been added using the Add Agent compose command?
4. Is this a **public (standard) channel**? (Private channels are not supported)
5. Have you authenticated with the required services?
Your Microsoft 365 email must match your Gumloop account email. If they're different, update one to match the other, then try again.
Visit your [Connectors page](https://www.gumloop.com/settings/profile/connectors?view=connected), authenticate with the required service, and retry. For team agents, contact your team admin.
Some organizations require admin approval for new Teams apps. Contact your Microsoft 365 admin to approve the Gumloop app, or ask them to add it to the organization's app catalog.
Limit tools to only what's necessary, use faster models, or break complex tasks into smaller interactions.
Open **Channels → Microsoft Teams** and copy the agent ID from the setup page. Make sure you've connected your Microsoft account first.
## Example use cases
**Agent**: Support Ticket Assistant
**Channel**: Customer Support (public channel)
**Common interactions**:
```text theme={"dark"}
Team member: "@Gumloop Is ticket #12345 eligible for a refund?"
Agent: [Checks ticket, reads policy, evaluates eligibility]
Team member (in thread): "@Gumloop What about ticket #12346?"
Agent: [Checks ticket #12346]
Team member: "@Gumloop Pull the last 5 interactions with customer@email.com"
Agent: [Searches CRM and email, returns history]
```
**Why it works**: Support team gets instant access to information without leaving Teams. Every interaction teaches the team how to use the agent for similar queries.
**Agent**: Lead Research Assistant
**Channel**: Sales Team (public channel)
**Common interactions**:
```text theme={"dark"}
Team member: "@Gumloop Research this company: [LinkedIn URL]"
Agent: [Enriches lead, checks CRM for activity, drafts outreach]
Team member (in thread): "@Gumloop What's the best time to reach out?"
Agent: [Analyzes contact data, suggests optimal timing]
Team member: "@Gumloop What's the status of opportunities over $50k?"
Agent: [Queries Salesforce, summarizes pipeline]
```
**Why it works**: Sales reps get instant research without switching tools. Newer reps learn by watching experienced reps use the agent.
**Agent**: Data Analysis Assistant
**Channel**: Data Team (public channel)
**Common interactions**:
```text theme={"dark"}
Team member: "@Gumloop Compare Q4 revenue vs Q3 by product line"
Agent: [Runs query, generates comparison]
Team member (in thread): "@Gumloop Now break it down by region"
Agent: [Continues analysis with regional breakdown]
Team member: "@Gumloop Flag any anomalies in yesterday's user signups"
Agent: [Analyzes data, identifies outliers, reports findings]
```
**Why it works**: Analysts get quick answers to data questions. Non-technical team members learn what data is available and how to access it.
## FAQ
Yes. Microsoft Teams integration only works with Microsoft 365 work or school accounts. Personal Microsoft accounts (outlook.com, hotmail.com, live.com) are not supported because the Microsoft Graph API permissions required are only available for enterprise tenants.
Currently, one agent can be active per channel. To switch to a different agent, remove the current one and add the new agent using the Add Agent command.
Yes. The agent matches your Microsoft 365 email to your Gumloop account. If they don't match, you'll be prompted to connect your account.
Yes. An agent can be deployed to Slack, Microsoft Teams, and other external channels simultaneously. Each channel operates independently.
No. File uploads are not currently supported in the Teams integration. The agent can only process text messages. If you need file processing, use the [Slack integration](/core-concepts/agents_slack) or the [Agent Email Inbox](/core-concepts/agents_email), both of which support attachments.
No. Unlike Slack (which supports [Custom Slack Apps](/core-concepts/custom_slack_app)), all agents in Teams respond as **@Gumloop**. Custom branding is not available for the Teams integration.
No. You must @mention **Gumloop** in every message, including thread replies. The "respond to all messages in thread" mode available in Slack is not supported in Teams.
Yes. This feature lets your team chat with a Gumloop agent **inside** Microsoft Teams channels. The [Microsoft Teams MCP server](https://www.gumloop.com/mcp/teams) is the opposite: it lets an agent **use** Teams as a tool (send messages, create channels, manage meetings) from within Gumloop.
It depends on your organization's Teams policies. Some organizations require admin approval for new apps. If you can't install the app, contact your Microsoft 365 admin.
Yes. If your agent stops responding, go to the Microsoft Teams channel page in Gumloop and click **Refresh** to re-authenticate your connection.
Open the compose menu in the channel, choose **Gumloop**, then select **Remove**. This clears the active agent from that channel. You can also check which agent is active by using the **Active** command from the same menu.
## Next steps
Learn how to create and configure agents in Gumloop
Deploy the same agents to Slack channels
Give your agent a dedicated email address
# AI models
Source: https://docs.gumloop.com/core-concepts/ai_models
Gumloop gives your agents access to the top models from every major provider. You choose the model at the top of the **Agent** tab.
AI models evolve rapidly. New models are usually available in Gumloop within a day of their public release, so you have the latest options even if this page has not caught up yet.
## Choosing a model
Open the model dropdown at the top of the **Agent** tab. The fastest way to choose is one of the options at the top:
![Agent model picker showing the Recommended and Smartest presets, a provider list, and a model detail card for Claude 4.8 Opus]()
* **[Auto](#auto-let-gumloop-choose-the-model)**: Gumloop picks a model per message instead of pinning one. New agents normally default to Auto; Enterprise organizations and accounts where Auto is restricted default to **Recommended** instead. Organization default-agent settings can select another model.
* **Recommended**: the best balance of speed, quality, and cost. Currently points to **Grok 4.7**.
* **Smartest**: maximum intelligence for complex reasoning and agentic work.
Each preset maps to a current best-in-class model that Gumloop keeps up to date, so you do not have to track model releases yourself. On **Enterprise** plans, your organization can choose which model each preset points to, so you may see different models than the defaults. See [AI Model Governance & Configuration](/enterprise-features/ai_model_control).
On **Enterprise** plans, admins can restrict which models a [Custom Role](/enterprise-features/user_groups#models-tab) may use. Restricted models can appear in the picker marked **Restricted by Admin**, but you cannot select them. Where available, you can request access.
To pick a specific model instead, search by name or browse by provider: **Anthropic**, **OpenAI**, **Google**, **DeepSeek**, **MiniMax**, **Z.ai**, and more.
**Auto** suits most agents, especially when message difficulty varies. Pin **Recommended** or **Smartest** — or a specific model — when you want every run to use the same model.
***
## Auto: let Gumloop choose the model
**Auto** is Gumloop's **model router**, not a model from a provider. Select it once, and Gumloop picks which model runs *each message*. Your initial selection depends on your organization's defaults and model restrictions.
![Model dropdown with Auto selected, described as an advanced model router powered by Gumloop Chew]()
### How Auto picks a model
Before the agent starts working, Gumloop judges what the message actually needs — how hard it is, whether anything will check the answer, which tools it implies — and picks the **cheapest tier that should still produce the same result for you**. Quality comes first: Auto does not save money by accepting a worse answer. While it decides, the chat shows *Choosing the best model*.
Each tier is a short, ordered list of models; Auto runs the first one you're allowed to use. Once the run starts, the chat names it (*Using Grok 4.7*), and that same model is what shows up in the chat's models list and its credit breakdown.
If a run turns out harder than the message looked, Auto **escalates to a stronger tier part-way through** — the chat shows *Switching to …*. That judgement is made from steps the agent has already finished, so it reacts to how a run is going rather than predicting it. Escalation then sticks for the rest of the run: a run never climbs and drops back down, and a message that already started on a top tier doesn't switch, because nothing sits above it.
**You can ask.** If your own message asks for a stronger (or cheaper) model, Auto honors that instead of optimizing for cost, as long as the model you asked for can actually do the job. It only listens to your current instruction — a model name quoted inside a pasted document or a fetched page doesn't steer the routing.
### The tiers Auto chooses from
Auto picks one of five tiers, from cheapest to most capable. Gumloop keeps the model behind each tier current, so the models below are today's choices rather than a fixed list — the chat always names the one that actually ran.
| Today's model | What Auto sends there |
| - | - |
| DeepSeek V4.1 Flash | Throwaway turns only: a greeting, repeating a literal string, one obvious calculation. |
| GPT-6 Luna | The bulk of simple useful work: summaries, explanations, extraction, classification, translation, reformatting, ordinary writing, working over material you supplied, and fully specified read-only sweeps. |
| Grok 4.7 | Ordinary coding and frontend, everyday data analysis and charts, advanced searches, anything that writes to the real world, and open-ended work where steps depend on results. Also the tier Auto falls back to whenever the choice isn't clear. |
| Claude 5.5 Opus | Ambitious frontend and web apps, high-quality visualizations, polished decks and artifacts, broad suggestions, and long-horizon work where taste and initiative matter. |
| GPT-6 Astra | Deep multi-source research, detailed evidence synthesis, formal analysis, tight constraints, and research-grade science or math. |
Some work never runs on the two cheapest tiers, however trivial the message looks:
* **Anything that writes to the real world** — send, post, reply, create, update, delete, invite — runs on Grok 4.7's tier or above, including bulk "do this to each of these" sweeps.
* **Turns that use other agents** (sub-agents, delegations) run on Grok 4.7's tier or above, because those tools aren't available on the cheaper tiers.
* **Messages carrying images or other non-text attachments** stay on Grok 4.7's tier, since routing only reads text and can't judge what it can't see.
### Where Auto can be used
| | |
| - | - |
| **Available for** | [Custom agents](/core-concepts/agents) and [Gumball](/core-concepts/gumball). Pick it in the model dropdown like any model. |
| **Not available for** | AI steps in flows, the **Recommended / Smartest** presets, and organization [fallback models](/enterprise-features/ai_model_control#fallbacks) — those always point at a specific model. |
| **Continuing a run** | Resuming a paused or continued message reuses the model decision already made for it, rather than re-deciding. |
| **Cost** | You're charged for the tokens of whichever model actually ran. The routing decision itself is **not billed**. See [Credits](/core-concepts/credits). |
### Auto and restricted models
On **Enterprise** plans, Auto stays inside your organization's model rules — it is not a way around them.
* **Both layers of restriction apply.** Organization-wide [model restrictions](/enterprise-features/ai_model_control#restrictions) and a [Custom Role's](/enterprise-features/user_groups#models-tab) model allow-list are both enforced on the routing decision, on the model Auto runs, on any mid-run escalation, and on fallbacks.
* **A blocked model is never used.** Auto skips it and takes the next permitted model in that tier.
* **A fully blocked tier steps aside.** If nothing in the chosen tier is permitted, Auto runs on the first tier that does have a permitted model, starting with Grok 4.7's tier.
* **If nothing is permitted, the run fails.** Auto stops with a model-restricted error rather than running on a model your organization disallowed.
* **Admins can restrict Auto itself.** It appears in the restriction and Custom Role model lists like any other picker entry. An allow-list that leaves it out prevents users from selecting it. Agents already saved on Auto use a permitted ordinary model, with no routing or escalation; restrictions still apply.
* **Models with 30-day data retention are never routed to.** [Claude Fable models](#models-with-30-day-data-retention) have to be chosen deliberately, so Auto never selects one.
### Auto FAQ
Auto's router is called **Gumloop Chew**, and its model ID is `gumloop-chew`. You will see both names, so it helps to know which is which: *Auto* is the label in the picker, *Chew* is the router doing the work, and `gumloop-chew` is what it is called in code.
* **Set it on an agent.** Set `model_name="gumloop-chew"` when creating or updating an agent through the [API](/api-reference/agents/create-agent) or Python SDK, or pass `--model gumloop-chew` in the CLI.
* **List it.** [`GET /models`](/api-reference/models/list-models) returns it among the picker options, marked as a Gumloop router rather than a provider model.
* **Ask it to decide.** [`POST /models/route`](/api-reference/models/route-model) returns the model Chew would pick for a message. `router` is always `gumloop-chew`; the concrete model it chose is `route.model`, with the lane it landed in, ordered `fallback_models`, and every candidate it considered.
```bash theme={"dark"}
curl -X POST 'https://api.gumloop.com/api/v1/models/route' \
-H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
-H 'Content-Type: application/json' \
-d '{"input": "Summarize this email thread", "models": ["claude-opus-5", "gpt-5.6-luna"]}'
```
An illustrative response is shown below. The decision depends on your message, candidate models, and permissions.
```json theme={"dark"}
{
"router": "gumloop-chew",
"route": {
"model": "gpt-5.6-luna",
"lane": "light",
"verdict_lane": "light",
"adjustment": null,
"fallback_models": ["claude-opus-5"],
"fail_closed": false
},
"candidates": [
{"requested_model": "claude-opus-5", "model": "claude-opus-5", "lane": "plus", "basis": "catalog", "status": "eligible"},
{"requested_model": "gpt-5.6-luna", "model": "gpt-5.6-luna", "lane": "light", "basis": "catalog", "status": "eligible"}
]
}
```
This endpoint returns a decision only. It does not run the selected model or its fallbacks. Restricted candidates may appear with `status: "restricted"`, but are never selected or included in `fallback_models`.
`gumloop-chew` is a **router**, not a model you can call directly. Chat completions need a concrete model; routing is exposed through `POST /models/route`, and the routing decision is not billed. Your organization's model restrictions apply to it just as they do in the app.
No. It's a router. Selecting Auto means "decide for me": Gumloop classifies each message and runs a real provider model — Claude, GPT, Gemini, Grok, and others — behind it.
The chat tells you. It shows *Choosing the best model* while deciding, then names the model it runs (*Using …*) and any mid-run switch (*Switching to …*). The chat's models list and credit details record the real models, never the routing guess.
Auto won't use it. Organization restrictions and Custom Role allow-lists apply to every model Auto could pick, including escalations and fallbacks, so a restricted model is skipped in favor of a permitted one. If no permitted model is left anywhere, the run fails with a model-restricted error instead of bypassing the rule.
Yes. Auto is listed in organization restrictions and Custom Role model lists, so it can be blocked or left out of an allow-list. Agents saved on Auto fall back to running on a normal model, without routing.
Exactly like the model that ran: token-based **Chat & Reasoning**, plus Compute, Tool Calls, and the orchestration fee. Choosing the model is free — the routing decision is not billed, so the chat's credit breakdown only shows the model that did the work.
The message runs on Auto's baseline model — currently **Grok 4.7** — instead of failing. Routing errors, timeouts, and content Auto can't inspect all fall back to that baseline rather than guessing a cheaper or stronger model.
Use **Auto** for agents whose messages vary a lot in difficulty — it saves money on the easy ones without capping the hard ones. Pin a specific model or preset when you need every run to be predictable and identical, such as a compliance-sensitive agent or an eval baseline.
***
## Reading the model card
Selecting or hovering a model opens a detail card so you can compare options at a glance:
* **Description**: what the model is best at.
* **Speed** and **Intelligence**: relative ratings across the catalog. Intelligence ratings are periodically rebased on a third-party benchmark, the Artificial Analysis Intelligence Index, so an existing model's rating can change as the index is updated.
* **Provider** and **Context**: who makes the model and how much it can read at once (in tokens and approximate words).
* **Tool Calling** and **Vision**: capability checks.
* **Badges**: extra labels that call out how a model is served. Models marked **US-provider hosted** are served by US providers under Zero Data Retention (ZDR) policies, and models marked **30-day data retention** are [not covered by ZDR](#models-with-30-day-data-retention).
For agents that read images or screenshots, pick one with **Vision**.
## Available models
These are the models you can choose for an agent, grouped by provider. Every one supports tool calling, so it can use your connected services and data. Models marked **Vision** can also read images and screenshots. **Served through** is the inference provider Gumloop sends the request to, which also decides which [BYOK](#bring-your-own-key-byok) key can cover the model. New models are added continually, so the in-product picker is always the most up-to-date list.
| Provider | Model | Served through | Vision |
| - | - | - | - |
| Anthropic | Claude Fable 5.1 | Anthropic | Yes |
| Anthropic | Claude Fable 5 | Anthropic | Yes |
| Anthropic | Claude 5.5 Opus | Anthropic | Yes |
| Anthropic | Claude 5 Opus | Anthropic | Yes |
| Anthropic | Claude 5.5 Sonnet | Anthropic | Yes |
| Anthropic | Claude 5 Sonnet | Anthropic | Yes |
| Anthropic | Claude 4.8 Opus | Anthropic | Yes |
| Anthropic | Claude 4.6 Sonnet | Anthropic | Yes |
| Anthropic | Claude 4.5 Haiku | Anthropic | Yes |
| OpenAI | GPT-6 Astra | OpenAI | Yes |
| OpenAI | GPT-6.1 Sol | OpenAI | Yes |
| OpenAI | GPT-6 Sol | OpenAI | Yes |
| OpenAI | GPT-6 Luna | OpenAI | Yes |
| OpenAI | GPT-5.6 Sol | OpenAI | Yes |
| OpenAI | GPT-5.6 Terra | OpenAI | Yes |
| OpenAI | GPT-5.6 Luna | OpenAI | Yes |
| OpenAI | GPT-5.5 | OpenAI | Yes |
| OpenAI | GPT-5.4 Mini | OpenAI | Yes |
| OpenAI | GPT-OSS 120B | OpenRouter (Cerebras, Groq, or Fireworks) | No |
| Google | Gemini 3.1 Pro | Google Gemini API | Yes |
| Google | Gemini 3.8 Flash | Google Gemini API | Yes |
| Google | Gemini 3.7 Flash | Google Gemini API | Yes |
| Google | Gemma 4 26B | OpenRouter (DeepInfra or Venice) | Yes |
| SpaceXAI | Grok 4.7 | OpenRouter (xAI only) | Yes |
| SpaceXAI | Grok 4.6 | OpenRouter (xAI only) | Yes |
| Moonshot | Kimi K3 | Fireworks AI (US-only) | Yes |
| Moonshot | Kimi K2.7 Code | Fireworks AI | Yes |
| DeepSeek | DeepSeek V4.1 Flash | Fireworks AI | Yes |
| DeepSeek | DeepSeek V4 Flash | Fireworks AI | No |
| DeepSeek | DeepSeek V4 Pro | Fireworks AI | No |
| MiniMax | MiniMax M3 | Fireworks AI | Yes |
| Qwen | Qwen3.8 Max | Fireworks AI | No |
| Z.ai | GLM-5.3 | Fireworks AI | No |
| Z.ai | GLM-5.2 | Fireworks AI | No |
| Z.ai | GLM-5.3-Flash | OpenRouter (Fireworks, Baseten, or Together) | Yes |
All open-source models (such as GPT-OSS 120B, LLaMA, DeepSeek, Qwen, Kimi, MiniMax, and GLM) are accessed through US-based providers under Zero Data Retention (ZDR) policies, and carry a **US-provider hosted** badge in the model picker. Your data is never used for model training and is not stored after inference.
### Where open models are served
Gumloop serves open models through two routes:
* **Fireworks AI**: DeepSeek V4.1 Flash, DeepSeek V4 Flash, DeepSeek V4 Pro, Kimi K3, Kimi K2.7 Code, GLM-5.3, GLM-5.2, MiniMax M3, and Qwen3.8 Max go straight to Fireworks.
* **OpenRouter**: GPT-OSS 120B, Gemma 4 26B, and GLM-5.3-Flash go through OpenRouter, locked to the hosts listed in the table above. Every OpenRouter request enforces Zero Data Retention and blocks data collection.
A model sent through OpenRouter can still land on Fireworks as the host (for example GLM-5.3-Flash or GPT-OSS 120B), but it runs on Gumloop's OpenRouter account, so your own Fireworks key does not cover it. If your organization only wants to use models served on its own Fireworks key, restrict your [allowed models](/enterprise-features/ai_model_control#restrictions) to the Fireworks AI list above.
### Models with 30-day data retention
Gumloop serves every model under **Zero Data Retention** with one documented exception: the **Claude Fable** family. Anthropic keeps prompts and outputs sent to Claude Fable models for **30 days** to check for misuse, then deletes them. Anthropic does not train on that data, and every other model — including every other Claude model — is unaffected.
| | Claude Fable 5.1 | Claude Fable 5 |
| - | - | - |
| **Best at** | Long-running agentic coding, knowledge work, and research | Demanding reasoning and long-horizon agentic work |
| **Context** | 1M tokens, or 300K on the [short window](/core-concepts/agents#context-window) | 1M tokens, or 300K on the short window |
| **Vision & tool calling** | Yes | Yes |
| **Badge** | 30-day data retention | 30-day data retention |
These models carry a **30-day data retention** badge in the picker, and:
* They are **off by default**. An organization admin has to explicitly allow non-zero data retention models before anyone can select one. See [AI Model Governance](/enterprise-features/ai_model_control#models-with-30-day-data-retention).
* They are **never chosen for you**. They are excluded from the **Recommended / Smartest** presets, from [Auto](#auto-let-gumloop-choose-the-model), and from fallback models — the only way one runs is if you pick it.
* If the acknowledgement is later revoked, they become unavailable immediately and agents set to them fail until you switch models.
## Thinking controls
Most modern models think before they answer. How much they think is a setting on the agent: open the **Settings** tab and expand **Advanced AI**. What you can change there depends on the model you have selected, because Gumloop only offers the controls a model actually supports — a model with no thinking control simply does not show one.
![Advanced AI section of an agent's Settings tab, showing Max Steps, Verbosity, Parallel Tool Calls, Max Output Tokens, Max Tool Calls, Top P, Top Logprobs, and Context Window]()
There are three shapes:
* **Effort levels** — pick how hard the model thinks, from **low** up to **max**. More effort usually means a better answer, more thinking tokens, and a higher cost.
* **On or off** — turn thinking off for speed and cost on models that allow it.
* **A thinking budget** — give the model a token allowance to think inside.
| Model | What you can change |
| - | - |
| GPT-6 Astra | Effort: low, medium, high, xhigh, max. Thinking is always on. |
| GPT-6.1 Sol, GPT-6 Sol, GPT-6 Luna, GPT-5.6 Sol, GPT-5.6 Terra, GPT-5.6 Luna | Effort: low, medium, high, xhigh, max — or turn thinking off. |
| GPT-5.5, GPT-5.4 Mini | Effort: low, medium, high, xhigh — or turn thinking off. |
| GPT-OSS 120B | Effort: low, medium, high — or turn thinking off. |
| Claude 5.5 Opus, Claude 5.5 Sonnet, Claude Fable 5.1 | Effort: low, medium, high, xhigh, max. Thinking is always on. |
| Claude 5 Opus, Claude 4.8 Opus, Claude 5 Sonnet, Claude Fable 5 | Effort: low, medium, high, xhigh, max — or turn thinking off. |
| Claude 4.6 Sonnet, Claude 4.5 Haiku | A thinking budget in tokens — or turn thinking off. |
| Gemini 3.1 Pro, Gemini 3.8 Flash, Gemini 3.7 Flash | Thinking: low, medium, high. Defaults to high. |
| Grok 4.7, Grok 4.6 | Effort: low, medium, high, xhigh. Thinking cannot be turned off on these models. |
| DeepSeek V4.1 Flash | Effort: high, xhigh — or turn thinking off. |
| DeepSeek V4 Flash, DeepSeek V4 Pro | Effort: low, high, max — or turn thinking off. |
| Kimi K3 | Effort: low, high, max. Kimi K3 always thinks. |
| GLM-5.3, GLM-5.2, GLM-5.3-Flash | Effort: high, max — or turn thinking off. |
| Qwen3.8 Max | Effort: low, medium, xhigh — or turn thinking off. |
| MiniMax M3 | Thinking on or off. |
Your choices are saved per provider, so switching models keeps the settings you picked for each one. If a model does not support a level you saved, Gumloop uses the closest level it does support rather than failing the run.
On **Gemini 3** models the thinking level is the only tuning control offered — temperature and the other randomness settings are not shown.
## How agents are charged
In agents, model cost is **token-based and variable**. You are charged for the tokens each message uses, which depends on the model, the length of the conversation, and the tools available. There are no fixed per-message tiers. Model calls bill at cost, converted to credits at **\$0.005 per credit**, and each run also carries **Compute** and an **Orchestration Fee**. Select the credit count in any chat's header to see its exact usage, and see [Credits](/core-concepts/credits) for the full breakdown.
## Bring your own key (BYOK)
Provide your own provider API key to cut model costs. BYOK makes AI model calls cost **0 credits**, and it also applies to image generation and voice transcription. Since the model spend leaves your credit balance entirely, agent chats on BYOK carry a **16% orchestration fee instead of 8%**, calculated on what the run would have been worth — still a large net saving. See [Credits](/core-concepts/credits#reducing-credit-costs).
**Each key only waives the models it can actually serve.** A **Fireworks AI** key covers the open models Gumloop serves through Fireworks — DeepSeek V4.1 Flash, DeepSeek V4 Flash, DeepSeek V4 Pro, Kimi K3, Kimi K2.7 Code, GLM-5.3, GLM-5.2, MiniMax M3, and Qwen3.8 Max. The other open models in the picker (GPT-OSS 120B, Gemma 4 26B, GLM-5.3-Flash) run elsewhere, so a Fireworks key does not affect them.
Requires a **Pro plan or higher** and your own OpenAI, Anthropic, Google AI, Perplexity, SpaceXAI, or Fireworks AI account.
Add a key from your personal [Connectors](https://www.gumloop.com/settings/profile/connectors?view=connected) so your own calls route through it, or add a **shared team key** so the whole team can use it without managing individual keys.
Pro users cannot set keys at the organization level.
Admins can set **organization API keys** (OpenAI, Anthropic, Google Gemini, Perplexity, xAI, and Fireworks AI) at [Organization > API keys](https://gumloop.com/settings/organization/api-keys). These override personal and team keys for everyone, and all AI requests can be routed through a **custom proxy**.
See [AI Model Governance & Configuration](/enterprise-features/ai_model_control) for model access control, proxy setup, and model name mapping.
# Create triggers with AI
Source: https://docs.gumloop.com/core-concepts/ai_trigger_creation
Let AI build custom polling triggers that monitor any combination of connected services and fire your agent when conditions are met.
The **Create With AI** option lets you describe what you want to monitor in plain language, and your agent builds a custom polling trigger for you automatically. Unlike pre-built [event-based triggers](/core-concepts/agent_triggers#app-triggers) that are limited to a single integration, AI-created triggers can combine multiple services, apply custom filtering logic, and handle scenarios that no pre-built trigger covers.
![Trigger type selector showing Create With AI, Scheduled Trigger, and Event-Based Trigger options]()
***
## When to use AI triggers
AI-created triggers (also called **custom MCP triggers**) are the right choice when:
| Scenario | Why AI trigger? |
| - | - |
| Monitor **multiple services** at once | Pre-built triggers only watch one app. AI triggers can poll Gmail *and* check Salesforce in the same trigger. |
| Apply **custom filtering logic** | "Only alert me if the email sender has an open deal in HubSpot" requires logic no pre-built trigger offers. |
| Watch a service that **has no pre-built trigger** | Any app connected via MCP can be monitored, even if Gumloop doesn't have a dedicated trigger for it. |
| Detect **computed conditions** | "Pipeline total dropped 20% since last check" or "Slack message with no reply after 30 minutes" need stateful comparison logic. |
| Combine data from **different sources** to decide when to fire | "New Jira ticket where the reporter has open GitHub PRs" cross-references two systems. |
If your use case is simple single-service monitoring (e.g., "new email from X" or "new Slack message in #channel"), a [pre-built event-based trigger](/core-concepts/agent_triggers#app-triggers) is faster to set up and fires in real-time. Use AI triggers for anything more complex.
***
## How it works
When you select **Create With AI** from the **+ Trigger** menu (or simply describe what you want in the agent chat), the agent follows a structured process:
The agent identifies which connectors your trigger needs (e.g., Gmail, Salesforce, Slack). If any are not yet connected to the agent, it prompts you to add and authenticate them before proceeding.
The agent queries each connected service to find the exact tools and parameters available. It never guesses tool names or schemas.
Based on your request, the agent writes a custom trigger class that polls the relevant services and detects when your condition is met.
The trigger code runs in a secure, isolated sandbox environment to verify it works correctly with your real data. If there are issues (wrong credentials, API errors), the agent reports them so you can fix the configuration.
On its first run, the trigger records the current state of the data (e.g., the latest email ID, the current pipeline total). Future polls compare against this baseline to detect *new* changes.
Once validated, the trigger is saved and starts polling on the schedule you specified. When the trigger condition is met, your agent receives the event data and acts on it.
***
## Creating a trigger
There are two ways to create an AI trigger:
Go to your agent's configuration page, find the **Triggers** section, click **+ Trigger**, and select **Create With AI**. This opens a chat where the agent walks you through the process.
Simply describe what you want to your agent in natural language. If the request involves monitoring or automation that needs custom logic, the agent will automatically use the AI trigger creation flow.
**Examples of what you can say:**
* "Let me know when I get a new email from @partner.com that has a matching open deal in Salesforce."
* "Watch Slack #support for messages with no reply after 30 minutes."
* "Alert me when our Salesforce pipeline total drops more than 20%."
### What you need
Before the agent can build your trigger, make sure:
1. **The required connectors are added to the agent.** In the **Agent** tab, expand **Connectors** and add the services the trigger needs. The agent will prompt you if anything is missing.
2. **You've authenticated with each service.** Visit your [Connectors page](https://www.gumloop.com/settings/profile/connectors?view=connected) to connect an account for each service.
3. **The agent has trigger creation enabled.** This is on by default for the general personal assistant. For custom agents, ensure the **Triggers** toggle is enabled under Tools.
***
## Examples
Here are real-world examples to illustrate the range of triggers you can build. Just describe any of these to your agent and it will build the trigger for you.
### Single-service triggers
**Prompt:** "Alert me when my Airtable 'Inventory' items drop below 10 in quantity."
Reads Airtable records and checks quantity fields against a threshold. Uses state to avoid re-alerting on the same item.
**Services:** Airtable
**Prompt:** "Notify me when a HubSpot deal moves to 'Closed Won'."
Polls HubSpot deals and detects *changes* in the deal stage, not just the current value. Stores the last known stage to identify transitions.
**Services:** HubSpot
**Prompt:** "Watch Slack #support for messages with no reply after 30 minutes."
Polls Slack messages, checks timestamps, and fires when a message has been sitting without a reply for the specified window.
**Services:** Slack
**Prompt:** "Alert me when a Linear issue has been stuck in 'In Progress' for over 5 days."
Polls Linear issues, performs date arithmetic, and detects stale items. Deduplicates so you only get alerted once per issue.
**Services:** Linear
**Prompt:** "Notify me when someone mentions a dollar amount over \$10k in Slack #sales."
Parses Slack messages with regex to extract dollar amounts and fires when one exceeds the threshold.
**Services:** Slack
**Prompt:** "Alert me when our Salesforce pipeline total drops more than 20% since last check."
Stores the pipeline total after each poll and compares it to the next check. Fires on significant percentage drops.
**Services:** Salesforce
### Multi-service triggers
**Prompt:** "When I get a new Gmail email, check if the sender is already in our HubSpot contacts."
Polls Gmail for new emails, then queries HubSpot to check if the sender exists as a contact. Fires with both email details and the HubSpot match result.
**Services:** Gmail + HubSpot
**Prompt:** "Watch for new Salesforce leads that don't already exist in HubSpot."
Polls Salesforce for new leads, then checks HubSpot to see if the lead email already exists. Only fires for leads that are truly net-new across both CRMs.
**Services:** Salesforce + HubSpot
**Prompt:** "Alert me when a GitHub PR is opened and the linked Jira ticket is still in 'To Do'."
Watches GitHub for new PRs, parses the Jira ticket reference from the PR title or description, then checks the ticket status in Jira. Fires when the status hasn't been updated.
**Services:** GitHub + Jira
**Prompt:** "Notify me about new emails from @partner.com if there's a matching open deal in Salesforce."
Monitors Gmail for emails from a specific domain, then queries Salesforce to find related open deals. Only fires when both conditions are true.
**Services:** Gmail + Salesforce
**Prompt:** "Watch for new Jira tickets -- check if the reporter has open GitHub PRs and find their Slack handle."
Monitors Jira for new tickets, looks up the reporter in GitHub to find their open PRs, and resolves their Slack handle. Fires with enriched context from all three systems.
**Services:** Jira + GitHub + Slack
### External MCP server triggers
AI triggers work with any MCP-compatible server, not just Gumloop's built-in integrations. If you've connected an external MCP server (like Notion's official MCP or Stripe's MCP), you can build triggers against it.
**Prompt:** "Watch for new database entries in Notion."
Uses an external Notion MCP server to poll for new pages in a database. Works even though Notion isn't a built-in trigger integration.
**Services:** Notion (external MCP)
**Prompt:** "Notify me about new Stripe subscriptions if the customer email appears in my recent Gmail."
Combines an external Stripe MCP server with Gmail to cross-reference new subscriptions against your email history.
**Services:** Stripe (external MCP) + Gmail
***
## Poll frequency and scheduling
Every AI trigger runs on a polling schedule. The agent chooses a frequency based on your intent, but you can also specify it explicitly.
| Frequency | Use case | Credit impact |
| - | - | - |
| **Every 5 minutes** (300s) | Time-sensitive monitoring ("notify me immediately") | Highest -- 288 checks/day |
| **Every 15 minutes** (900s) | Standard monitoring | 96 checks/day |
| **Every hour** (3600s) | Periodic checks | 24 checks/day |
| **Every day** (86400s) | Daily reports or digests | 1 check/day |
| **Every week** (604800s) | Weekly summaries | \~0.14 checks/day |
**Minimum frequency:** 5 minutes (300 seconds).
**Maximum frequency:** 1 week (604,800 seconds).
**Default:** 5 minutes if not specified.
Match the poll frequency to your actual need. If "check every hour" is good enough, don't poll every 5 minutes -- you'll save significant credits over time.
***
## How triggers detect changes (state management)
AI triggers use a **state checkpoint system** to track what they've already seen, ensuring they only fire on genuinely new data.
### How it works
1. **First run (baseline):** The trigger polls the API, records the current state (e.g., the latest email ID, the current pipeline total), and does *not* fire. This establishes the baseline.
2. **Subsequent runs:** Each poll compares the new data against the stored state. If something new is detected, the trigger fires with only the new items.
3. **State updates:** After each successful poll, the trigger updates its stored state so the next poll has an accurate comparison point.
### State window
State is stored as a **sliding window of up to 5,000 checkpoint entries**. Older entries are automatically trimmed. This is designed for deduplication -- storing only the minimal data needed to identify what's new (like IDs and timestamps), not full API responses.
State exists only for deduplication. The trigger stores the minimum needed to tell "new" from "already seen." If you need to retain historical data, have your agent save it elsewhere (e.g., Google Sheets, Airtable) when the trigger fires.
***
## Credit costs (polling only)
AI triggers consume a small number of credits **each time they poll** -- this is the cost of checking whether your condition is met, not the cost of the agent acting on it.
The credits listed here cover **only the polling check** (running the trigger code in the sandbox). When a trigger actually fires and your agent processes the event, the agent interaction has its own separate credit cost based on the AI model, conversation length, and any tools the agent uses. See [Understanding Credit Costs](/core-concepts/agents#understanding-credit-costs) for details on agent interaction pricing.
**Polling cost formula:**
```text theme={"dark"}
credits_per_check = execution_time_seconds x 0.018 (rounded up, minimum 1 credit)
credits_per_day = credits_per_check x (86400 / poll_frequency)
```
**Typical polling costs:**
| Trigger complexity | Execution time | Poll frequency | Credits/check | Credits/day |
| - | - | - | - | - |
| Simple (1 API call) | \~3s | Every 5 min | 1 | \~288 |
| Medium (2-3 API calls) | \~8s | Every 15 min | 1 | \~96 |
| Complex (multi-service) | \~15s | Every hour | 1 | \~24 |
| Heavy (many API calls) | \~60s | Every hour | 2 | \~48 |
These costs are charged **every poll cycle**, whether the trigger fires or not. The cost of the agent responding when the trigger fires is separate and depends on the agent's model and what actions it takes.
The agent shows you the estimated polling credit cost before activating the trigger, so there are no surprises.
To reduce polling costs: increase the poll interval (check less often), simplify the trigger logic, or use a pre-built event-based trigger where available (those don't have per-poll costs).
***
## Limits and safety
### Trigger limits
* **Maximum 10 active triggers per agent per user.** This includes all trigger types: AI-created, pre-built integration triggers, and scheduled triggers. If you hit the limit, deactivate or delete unused triggers first.
* **Maximum trigger code size:** 5,000 lines. If a trigger is this large, it probably needs to be simplified.
### Circuit breaker
If a trigger fires **more than 20 times within 10 minutes**, it is automatically deactivated. This prevents runaway triggers from draining credits or overwhelming your agent.
To re-enable: fix the underlying issue (usually a trigger that fires on every poll instead of only on new data), then re-enable from the **Triggers** section.
### Deduplication
Each trigger fire is deduplicated based on the data payload. If the exact same data would fire the trigger twice (e.g., due to a race condition), the duplicate is silently dropped.
### Credit limit protection
If your account runs out of credits, polling is paused automatically. The trigger resumes when credits are available again.
### Read-only enforcement
AI trigger code can only **read** data from your connected services. It cannot create, update, delete, or send anything. All actions happen through the agent's prompt after the trigger fires.
The trigger detects the condition; the *agent* takes the action. For example, a trigger can detect "new email from VIP client" but cannot reply to the email itself. The agent does that based on the prompt you configured.
***
## Managing AI triggers
### From the Triggers section
All active triggers (AI-created, pre-built, and scheduled) appear in the **Triggers** section of your agent's configuration page. Click any trigger to see its details, or use the three-dot menu to:
* **Edit** the trigger name, prompt, or poll frequency
* **Test Now** to run the trigger's check immediately
* **Deactivate** the trigger (pauses polling without deleting)
* **Delete** the trigger entirely
![Trigger management menu showing Edit, Test Now, Deactivate, and Delete options]()
### From the chat
You can also ask your agent to manage triggers conversationally:
| What you say | What happens |
| - | - |
| "Show me my active triggers" | Agent lists all triggers with their status |
| "Change the email trigger to check every hour instead" | Agent updates the poll frequency |
| "Pause the Salesforce pipeline monitor" | Agent deactivates the trigger |
| "Delete the Slack support trigger" | Agent removes the trigger |
| "Test the Gmail trigger now" | Agent runs the trigger's check immediately and shows the result |
### Testing a trigger
Use **Test Now** (from the UI or by asking the agent) to run the trigger's check immediately without waiting for the next poll. This is useful for:
* Verifying a newly created trigger works correctly
* Debugging triggers that aren't firing as expected
* Checking what data the trigger would return right now
The test returns one of three statuses:
* **Fired** + data: New items were detected (shows the items)
* **Empty**: No new data since the last poll
* **Error**: Something went wrong (shows the error message)
***
## Prompt templates
When an AI trigger fires, the trigger data is injected into a prompt template you configure. The agent receives this prompt and acts on it.
![Trigger prompt template editor showing field chips and the prompt text area]()
### Inserting trigger fields
The prompt editor shows all available output fields as **chips** below the text area. Click a chip (or type `@` and select a field) to insert it into your prompt. When the trigger fires, each field chip is replaced with the actual value from the trigger data.
For example, if your trigger outputs `File Name`, `File Url`, `Created Time`, and `File Id`, your prompt might look like:
> A new Google Sheet has been created in your account!
>
> **Name:** `File Name` **Link:** `File Url` **Created:** `Created Time` **File ID:** `File Id`
>
> Let me know if you'd like to do anything with this new sheet.
### Raw data mode
Toggle **Pass raw JSON event data instead of prompt** at the bottom of the editor to send the entire trigger payload as JSON instead of using the prompt template. This is useful when you want the agent to dynamically decide what's important rather than mapping specific fields.
Use raw data mode when your trigger returns many fields and you want the agent to interpret them flexibly, or when you're prototyping and don't want to set up a structured prompt yet.
***
## Supported server types
AI triggers work with three types of MCP servers:
Gumloop's built-in MCP servers (Gmail, Slack, GitHub, Salesforce, Airtable, HubSpot, Linear, Jira, Google Calendar, and 70+ more). Connect from your agent's Tools page.
Any third-party MCP-compatible server (e.g., Notion's MCP at `mcp.notion.com`, Stripe's MCP at `mcp.stripe.com`). Connect via the Custom MCP option in your agent's Tools.
Custom MCP servers deployed through Gumloop's [Hosted MCPs](/enterprise-features/hosted_mcps) infrastructure. These are organization-managed servers configured in **Settings → Organization → Hosted MCPs**.
A single trigger can combine servers of **different types**. For example, you can build a trigger that polls a built-in Gmail server *and* an external Stripe MCP server in the same check.
***
## AI triggers vs. pre-built triggers vs. scheduled triggers
| Feature | AI Triggers (Create With AI) | Pre-Built Triggers | Scheduled Triggers |
| - | - | - | - |
| **Setup** | Describe in natural language | Configure via UI form | Configure via UI form |
| **Multi-service** | Yes -- combine any MCP servers | Single service only | N/A |
| **Custom logic** | Yes -- filtering, thresholds, cross-referencing | Limited to built-in parameters | N/A (prompt-based) |
| **Latency** | Polling (minimum 5 min) | Real-time or polling (\~60s) | Cron or one-time |
| **Any MCP server** | Yes | Only supported integrations | N/A |
| **Credit cost** | Per-poll sandbox execution | Per-trigger execution | Per-run execution |
| **Best for** | Complex, multi-service, conditional monitoring | Simple single-service events | Recurring or delayed triggers |
***
## Troubleshooting
**Common causes:**
* The baseline captured the current state, and nothing has changed since. Try creating new data in the monitored service, then use **Test Now** to verify.
* The poll frequency is longer than expected (check if it was set to hourly/daily instead of every 5 minutes).
* The trigger condition is too specific and no data matches.
The trigger isn't correctly tracking state between polls. This usually means the deduplication logic isn't working -- the trigger is treating existing data as new every time. If this happens repeatedly, the circuit breaker will auto-deactivate the trigger. Delete it and ask your agent to rebuild with better deduplication.
Make sure the required integrations are connected and authenticated:
1. Go to your [Connectors page](https://www.gumloop.com/settings/profile/connectors?view=connected) and verify the service is connected
2. In the **Agent** tab, expand **Connectors** and verify the required service is added
3. Refresh the affected connector from its account menu
Two common reasons:
* **Circuit breaker:** The trigger fired more than 20 times in 10 minutes. Fix the trigger logic and re-enable.
* **Credit limit exceeded:** Your account ran out of credits. Add more credits and re-enable.
The error message from the sandbox will tell you what went wrong. Common issues:
* **Auth errors:** Authorization expired or permissions changed. Refresh the affected connector.
* **API errors:** The external service returned an error. Check if the service is operational.
* **Code errors:** The trigger logic has a bug. Ask your agent to fix it and recreate the trigger.
No. Trigger code is managed by the AI agent. To change the trigger's behavior, describe what you want differently and the agent will rebuild the trigger. You can update the name, prompt, and poll frequency without rebuilding.
***
## FAQ
No. You describe what you want in plain language, and the agent writes all the code. You never see or edit code directly.
Yes. Any agent with the **Triggers** toggle enabled under Tools can create AI triggers. [Gumball](/core-concepts/gumball), your personal agent, has this enabled by default.
The trigger data is injected into the prompt template you configured, and the agent receives it as a new message. The agent then processes the prompt and takes whatever action you specified (reply to email, post to Slack, update a spreadsheet, etc.).
Yes. This is one of the main advantages of AI triggers. A single trigger can poll Gmail, check Salesforce, and verify data in Airtable -- all in one check cycle.
The agent builds stateful deduplication logic tailored to your use case. It tracks IDs, timestamps, hashes, or whatever is appropriate to distinguish new data from previously seen data. The sliding window of 5,000 state entries ensures long-term accuracy without unbounded storage growth.
No. Triggers are strictly read-only. They can poll and read data, but cannot create, update, or delete anything. All write actions happen through the agent after the trigger fires.
10 active triggers per agent per user. This limit includes all trigger types (AI-created, pre-built integration triggers, and scheduled triggers).
Yes. Just describe what you want to monitor, and the agent will build and activate the trigger. You don't need to go through the **+ Trigger** menu.
Either go to the **Triggers** section and click **Deactivate** or **Delete**, or tell your agent "pause the \[trigger name]" or "delete the \[trigger name]" in chat.
***
## Related documentation
Pre-built event-based triggers and scheduled triggers
Teach your agent reusable processes
Connect external MCP servers to your agent
# Brain
Source: https://docs.gumloop.com/core-concepts/brain
Brain is your company knowledge base for agents. Connect your tools once, and your agents can search everything your team knows.
Your agents can already take actions through [connectors](/core-concepts/agents#connectors) and follow your processes through [skills](/core-concepts/skills#what-is-a-skill). What they cannot do out of the box is know what *your company* knows: your documents, your Slack threads, your past decisions, and where any of it lives.
**Brain** is where that knowledge lives.
You connect the tools your team already uses, Gumloop indexes them, and your agents can then search across all of it and answer from your real content, with citations, instead of guessing.
Brain is available on the **Pro** and **Enterprise** plans.
## How Brain fits with tools and skills
Brain is the third piece of what makes an agent useful. Each answers a different question:
| Piece | Gives your agent | Answers |
| - | - | - |
| [**Connectors**](/core-concepts/agents#connectors) | The ability to take live actions | "Send this Slack message" |
| [**Skills**](/core-concepts/skills#what-is-a-skill) | Reusable instructions for a task | "Draft outreach using our sequence" |
| **Brain** | Searchable knowledge from your content | "What does our refund policy say?" |
They work together. An agent might **search Brain** for your pricing policy, follow a **skill** to format a quote, then use a **connector** to email it.
The mental model for the rest of this page: **indexing a source makes knowledge available; attaching it to an agent makes that knowledge usable by that agent.**
## Where you access Brain
Open **Brain** from the left sidebar, or jump straight to a page:
Sources only you can see.
Sources shared across your company.
The **All**, **Mine**, and **Organization** tabs filter by scope, and **+ Source** adds one. To scope knowledge to a single agent, use its [Knowledge Sources](#giving-an-agent-knowledge) section.
## How access works
Brain has two layers of access control:
1. **Source scope** — who can *see and search the source* at all.
2. **[Document access](#document-access)** — for supported sources, whether individual documents are further gated by their *own permissions in the original system*.
### Source scope
Every source has a **scope** that decides who can see and search it. You choose the scope when you add a source, and can change it later.
Only you can see and search it.
Everyone on that [team](/core-concepts/teams) can see and search it.
Everyone in your organization can see and search it, or only the teams you choose. Often set up once by an admin for the whole company.
**Your data stays yours.** Indexed content is used only to answer your own team's agents. The embedding provider Gumloop uses runs under a zero-data-retention policy, so your content is not retained by it or used to train third-party models, and Brain respects [incognito](/core-concepts/agents#incognito-mode) chats.
## Document access
By default, source scope is the only gate: anyone who can see a source can search everything indexed in it. For **Google Drive**, **SharePoint**, and **Salesforce** sources, you can go further and have Brain honor each document's *own* permissions in that system. You set this when adding a source (and can change it later on the source's settings), under **Document access**:
Only people with access to a document *in the original source* can retrieve its content through Brain. Permissions are checked per document.
Anyone with access to this source in Gumloop can retrieve any document indexed in it, regardless of the original system's permissions.
**Document access** appears only for sources that support it — **Google Drive**, **SharePoint**, **Salesforce**, **Gmail**, and **Linear** today. Other source types always use **Gumloop access**.
When **Original source** is set, Gumloop snapshots each document's permissions in the original system during sync and enforces them at search time, matched by the user's email in that system.
For **Google Drive**, a user only retrieves a document if they have access to the underlying Drive file, matched by the email on their connected Google account.
Three kinds of Drive grants are honored: **direct user access**, **organization/domain access** (matching your verified email domain), and **Google Group access** — the last one needs the directory connection described below. Documents shared only through **"anyone with the link"** are treated as *no access* and won't surface: Brain fails closed rather than over-share.
With **Gumloop access**, Brain does not check the source's own per-document permissions. Anyone who can see the source can retrieve anything indexed in it — including files they could not open directly in the original system. Scope such sources to the audience you intend. See [Agent Access](/core-concepts/agent_access).
Changing a source's Document access setting queues a re-sync so permissions are re-snapshotted against the new mode.
### Google Group sharing on Drive sources
Most Drive files in a company are shared with a **Google Group** rather than person by person. Drive reports the group's address, not who belongs to it, so Brain needs a way to expand a group into its members. That is the job of the **Google Workspace directory** connection: one organization-level Google connection that reads your Workspace group memberships, read-only, so anyone in a group can retrieve the files shared with that group.
An organization admin connects it once at [Organization settings > General](https://www.gumloop.com/settings/organization/general), under **Google Workspace directory**, using an account allowed to read your Workspace directory. It then applies to every Drive source in the organization.
Because group-only files stay hidden without it, new **organization** and **team** Drive sources set to **Original source** ask for the connection before they can be added — the dialog links an admin straight to it, and switching **Document access** to **Gumloop access** removes the requirement. Personal Brain sources and existing Drive sources are unaffected.
**Brain fails closed on group membership it cannot read.** Files shared only through a group stay hidden from that group's members when the directory is not connected, when the group lives outside your organization's directory, or when the connected Drive account can no longer read the file's permissions. Disconnecting the directory stops group expansion, so group-shared files can drop out of results for those members.
### SharePoint file permissions
With **Original source**, Brain reads each SharePoint file's permissions during sync and matches users by email.
| SharePoint grant | Honored by Brain |
| - | - |
| Direct access for a user | Yes |
| **Everyone** or **Everyone except external users** | Yes, for users whose email is on one of your Microsoft tenant's verified domains |
| **Microsoft Entra group** | Yes, with the **Microsoft Entra directory** connection |
| **SharePoint site group** | Yes, with the **SharePoint site groups** connection. Entra groups nested inside a site group are expanded too. |
| Sharing links (anyone with the link, or people in your organization with the link) | No. Link-only access is treated as *no access*. |
Expired permissions are ignored. If Brain can't read a file's permissions, the file is skipped rather than indexed.
#### Connecting the Microsoft directory
SharePoint reports a group, not who belongs to it, so Brain needs two organization-level connections to expand groups into members:
* **Microsoft Entra directory**: reads Microsoft Entra group membership.
* **SharePoint site groups**: reads SharePoint site group membership. It can only be connected after **Microsoft Entra directory**.
An organization admin connects both at [Organization settings > General](https://www.gumloop.com/settings/organization/general), under **Microsoft directory**. They then apply to every SharePoint source in the organization.
New **organization** and **team** SharePoint sources set to **Original source** need both connections before they can be added. The dialog links an admin to them, and switching **Document access** to **Gumloop access** removes the requirement. Personal SharePoint sources don't need the connections, but files shared only through a group stay hidden from them.
**Brain fails closed on group membership it cannot read.** Files shared only through a group stay hidden from that group's members when the connection is missing or can't read the group. Disconnecting either connection stops that kind of group expansion, so group-shared files can drop out of results for those members.
### Salesforce record permissions
Salesforce sources can also use **Original source**. During each sync, Brain snapshots who can read every record and enforces it at search time, matching users by the email on their Salesforce user record.
* **Record ownership**, plus the owner's **role hierarchy** where the object grants access upward
* **Sharing** on the record: sharing rules, manual shares, and shares to public groups, queues, teams, and territories
* **Organization-wide defaults**, for objects whose sharing model is public read
* **"View All" and "View All Data"** granted through profiles and permission sets
* **Knowledge articles**: data category visibility, so a user matches an article only when their profile can see every category on it
* **Field-level security**: fields a user cannot read in Salesforce are kept out of what they can retrieve, so two people searching the same record can see different fields
Brain never widens access it cannot verify. A record's content stays limited to **View All Data** users when:
* **Restriction rules** are active on the object — their criteria are not mirrored
* A record is flagged **private**, in which case non-owner shares are ignored (for private activities, only the assignee and View All Data)
* The object's sharing model cannot be read, or access is **controlled by a parent** record
* A record has **no owner**, or a user who should match has **no email** on their Salesforce user record
Knowledge articles with data categories are skipped entirely if the connected Salesforce account cannot use the Metadata API, since per-user category visibility is only available there. Reconnect the source with an account that can use it to index those articles.
Salesforce permissions are re-snapshotted on each sync, so grants you change in Salesforce take effect in Brain after the next sync.
### Syncing "Shared with me"
Drive's **Shared with me** can be picked as a sync root, and Brain walks it recursively like any other folder. Google does not expose permission lists for that content, so **Original source** cannot be enforced on it: a Shared with me source has to use **Gumloop access**, and Gumloop blocks the other combination when you add it. Everyone who can see the source can then retrieve everything indexed from it, so choose the source's scope accordingly.
## Adding a source
A **knowledge source** is a connection to a place your knowledge already lives. Gumloop reads from it, indexes the content, and keeps it in sync.
![Add a source dialog listing Notion, Google Drive, Slack, GitHub, Confluence, Zendesk, and File uploads.]()
**Don't see your app?** You can also sync almost any other app in Gumloop's connector library, no native source required. See [Build your own sources](#build-your-own-sources).
**Gmail** and **Linear** are now native source types with their own setup, rather than build-your-own apps. See [Gmail sources](#gmail-sources) and [Linear sources](#linear-sources).
On the **Brain** page (or an agent's Knowledge Sources section), click **+ Source** and pick a source type.
Give the source a clear, descriptive name. This is how agents and your team will see it. Then choose the connected account Gumloop should use to read the content.
![Google Drive source setup showing a Name field and an Account selector.]()
Narrow the source to only what you want indexed: specific drives, SharePoint sites and libraries, folders, channels, spaces, repositories, or (for Salesforce) objects. Everything you include inherits the source's scope, so pick with the audience in mind. For Google Drive you can also sync [**Shared with me**](#syncing-shared-with-me).
![Google Drive source setup showing a drive selector and a checklist of folders to sync.]()
For [sources that support it](#document-access), choose how retrieval permissions work: **Original source** to honor each document's own permissions, or **Gumloop access** to let anyone with access to the source in Gumloop retrieve its content. See [Document access](#document-access) below.
When you add a source to **Organization** Brain, a final step controls who in your org gets it: everyone organization-wide, or only specific [teams](/core-concepts/teams). Personal and team sources skip this step.
Click **Add source**. Gumloop starts crawling and indexing.
### What gets indexed
Brain reads the text in your content. What that means per source:
| Source | What gets indexed |
| - | - |
| **Notion** | Full page content for the pages and databases you connect. |
| **Google Drive** | File contents from the drives and folders you pick, including Google Docs, Sheets, and Slides (converted for indexing). Folders organize results but are not documents themselves. |
| **Slack** | Messages, including thread replies, from the public channels you choose. |
| **GitHub** | Files from the repository you connect. |
| **Confluence** | Pages from the Confluence space you connect. |
| **SharePoint** | Files from the document libraries, folders, and files you pick in one SharePoint site. Supports the same file types as **File uploads**, up to 100 MB each. |
| **Zendesk** | Help Center articles from the categories and sections you pick, and support tickets, including each ticket's subject and full comment thread. |
| **Salesforce** | CRM records and Knowledge articles from the objects you pick. Each record becomes one document with its field values as text, grouped under its object. |
| **Gmail** | Email threads from the labels you pick in the connected mailbox. Each thread is indexed as one document. |
| **Linear** | Issues, documents, and projects from the teams you pick. |
| **File uploads** | The files you upload: PDFs, Office files (`.docx`, `.pptx`, `.xlsx`), rich text, Markdown, JSON, XML, YAML, and plain text, up to about 400 MB each. |
Brain does not run OCR on images, so text inside images or scanned pages is not indexed. Private Slack channels are not synced.
### Salesforce sources
**Salesforce** is a native source that syncs *CRM records and Knowledge articles*, so agents can answer from accounts, opportunities, cases, custom objects, and your Knowledge base.
Choose the connected Salesforce account Brain should read with. Everything Brain can index is limited to what that account can see, so use an account with the visibility you want indexed.
Salesforce is scoped by **object**, not by individual record. Under **Objects** you get a checklist of the objects available in your org — standard and custom — and every object starts selected. Uncheck the ones you don't want, or select only the specific objects you do want.
Objects Salesforce doesn't expose for browsing and reporting, and internal plumbing tables (share, history, and feed objects), are not offered.
Pick **Original source** to mirror Salesforce record permissions per document, or **Gumloop access** to let anyone with the source retrieve anything indexed in it. See [Salesforce record permissions](#salesforce-record-permissions).
**How records are indexed**
* One document per record, grouped under its object, titled from the record's name, title, subject, or case number
* The record's field values are indexed as text with their field labels, and rich text fields are flattened to plain text
* Structural values with nothing to search — raw IDs, system timestamps, and compound fields — are left out of the text
* Each record links back to the record in Salesforce, so search results are clickable
You must select at least one object. A Salesforce source that includes nothing would index nothing, so Gumloop won't let you save it.
### Gmail sources
**Gmail** is a native source that syncs *email threads* from a connected mailbox, so agents can answer from what your team actually said over email.
Choose the connected Gmail account Brain should read. Everything indexed is limited to what that mailbox can see.
Gmail is scoped by **label**, not by individual thread — a label is the whole unit of choice. Pick the labels whose mail you want searchable, or sync everything.
**Spam**, **Trash**, **Drafts**, and **Chats** are never offered and never indexed.
With **Original source**, only the mailbox owner can retrieve that mail through Brain, which is usually what you want for a personal mailbox. With **Gumloop access**, anyone who can see the source can retrieve anything indexed in it — scope the source accordingly. See [Document access](#document-access).
Each thread is indexed as one document, and syncs are **incremental**: after the first crawl, Brain picks up only what changed in the mailbox since the last successful sync.
A mailbox is personal by nature. Adding a Gmail source to **Team** or **Organization** Brain with **Gumloop access** makes that mail searchable by everyone who can see the source. Use **Original source**, or keep the source in Personal Brain, unless sharing the mailbox is the point (a shared support inbox, say).
### Linear sources
**Linear** is a native source that syncs *issues, documents, and projects*, so agents can answer from your roadmap, specs, and open work.
Choose the connected Linear account Brain should read with. What it can index is limited to what that account can see in the workspace.
Linear is scoped by **team**. Issues, documents, and projects aren't picked individually — you choose the teams whose content should be searchable, and everything in them is included.
With **Original source**, Brain mirrors Linear's own team privacy: content from a private team is retrievable only by that team's members, while content from a public team is open to the workspace. With **Gumloop access**, anyone who can see the source can retrieve anything indexed in it. See [Document access](#document-access).
Linear sources can be added to **Team** and **Organization** Brain, not Personal Brain. Permissions are re-snapshotted on each sync, so a team you make private in Linear tightens in Brain after the next sync.
### SharePoint sources
**SharePoint** is a native source that syncs *files from a SharePoint site's document libraries*, so agents can answer from the documents your team keeps in SharePoint.
Choose the connected SharePoint account Brain should read with. Brain can only index what that account can access.
Pick one SharePoint **site**, then choose which document libraries, folders, or files to include. Only files Brain can index are offered.
Pick **Original source** to honor each file's SharePoint permissions, or **Gumloop access** to let anyone with the source retrieve anything indexed in it. See [SharePoint file permissions](#sharepoint-file-permissions).
After the first crawl, syncs are **incremental**: Brain picks up only files that changed since the last sync. About once a day, it also runs a full re-sync of the source.
**Renaming or moving a folder.** Folder selections are saved by folder path. If you rename or move a folder that you included or excluded, the change may not be reflected in what Brain syncs until the next full re-sync. After renaming or moving folders, check the source's selection.
## Build your own sources
The source types above are purpose-built and give the best experience. For anything else, you can sync almost any app in Gumloop's [connector library](/core-concepts/agents#connectors), the same 100+ integrations your agents already use, even when there's no native source for it (Intercom, HubSpot, Jira, Asana, and more).
Instead of a fixed form, a short **AI setup chat** inspects the app for you, proposes what's worth syncing, and turns it into the same picker-and-toggle experience as a native source. Nothing is added until you approve the plan.
The screenshots below use Gmail as the example. Gmail is now a [native source](#gmail-sources) with its own setup, so it no longer appears under **Build your own** — the flow shown is the same for the apps that do.
In **Add a source**, search for the app. Apps without a native source appear under **Build your own**.
![Add a source dialog with 'Gmail' typed in the search box and a Gmail result listed under a 'Build your own' heading.]()
Choose the account Brain should read from, then optionally describe what to sync (for example, "our support emails"). Leave it empty and the setup chat suggests a sensible default.
An assistant explores the app, works out how its content is organized, and proposes what to sync. Review its summary and choose **Looks good** or **Request changes**.
![Setup chat for a Gmail source showing the assistant's plan and a 'Ready to sync' card with 'Looks good' and 'Request changes' options.]()
On the selection screen, narrow the source to only what you want indexed, using the app's own concepts (labels, folders, channels, projects). Then click **Add source**.
![Selection screen for a Gmail source with a 'Sync by Labels' dropdown, 'Sync everything' vs 'Select what to sync' options, and a checklist of labels such as INBOX, SENT, and IMPORTANT.]()
From there it behaves like any other source: it shows **Preparing** briefly, flips to **Active**, and appears in the sources list, [knowledge graph](#the-knowledge-graph), and [agent citations](#giving-an-agent-knowledge). It [stays in sync](#what-happens-after-you-add-a-source) automatically, and you can [re-sync, pause, edit, or delete it](#source-actions) like any source.
### The setup chat
The chat does the discovery so you don't have to:
* **It inspects the app** to learn how content is organized and which parts are worth making searchable.
* **It proposes a plan** as a plain-language summary of what you'll get, not a list of settings.
* **It may ask a question** when a choice is genuinely yours (which workspace, which username), always with options to pick from.
* **You approve or request changes.** **Looks good** moves you to the selection screen; **Request changes** tells it what to adjust, and it reworks the plan.
The setup chat is **read-only**. It only reads from the connected account to plan and sync the source, and never creates, edits, or deletes anything in your app.
Give it a hint on the connect step for a more tailored plan, e.g. "just our #announcements channel" or "deals closed this year". Anything specific you mention is carried onto the selection screen so you don't re-enter it.
### Choosing what to sync
The selection screen is built from the approved plan, so the exact controls depend on the app. You'll typically see:
| Control | What it does |
| - | - |
| **Sync by** | When an app can be organized more than one way, pick the dimension to sync by (for example, **Labels** vs. a search query). |
| **Sync everything** | Index the whole source, including content added later. |
| **Select what to sync** | Hand-pick only the containers you check, such as specific labels, folders, or channels. |
| **What to include** | Toggle which content streams are indexed (bodies vs. comments, say). Core content is on by default. |
| **Search box / queries** | For content reachable only by an identifier or query (a username, a channel, a search), type the values to pull in. |
Everything you include inherits the source's [scope](#source-scope), so pick with your audience in mind. The account works like any source: on **Team** Brain you can pick a team or personal account; on **Personal** and **Organization** Brain you pick a personal account.
### What you can't add this way
* **Apps with a native source** (Notion, Google Drive, Gmail, Slack, GitHub, Confluence, Zendesk, Gong, Linear, Salesforce) use their dedicated setup instead and don't appear here.
* **Action-only and scraping platforms** (web-scraping, enrichment tools) have no content library to sync, so they're hidden.
* **Raw database and warehouse apps** aren't offered, because syncing them safely would need write-capable access that Brain never uses.
* **Empty accounts or missing permissions** — the setup chat tells you rather than creating an empty source, so you can switch accounts. If setup can't finish (including running out of [credits](#credits)) the source shows **Setup failed** with a short reason; fix the cause and set it up again.
## What happens after you add a source
Once a source is added, Gumloop takes over. You do not manage any of this:
Gumloop reads the source, detects what is new or changed, and indexes the content for both semantic (meaning-based) and keyword search. The source moves to **Active** and its items show as **Indexed**.
External sources re-sync automatically (by default about hourly for connectors like Google Drive), so answers reflect the latest version. If a document is deleted or moved out of a source's scope upstream, the next successful sync removes it from Brain too. File uploads do not auto-sync because there is no remote system to poll.
**How long until it is searchable?** Indexing time depends on the source's size, from a minute or two for a small source to longer for large ones. The **Status** column shows progress and flips to Active once items are indexed and ready to search.
If your admins have already set up **Organization** sources, they appear under the Organization tab and are ready to search right away. You do not need to add anything yourself to start benefiting from Brain.
## Managing your sources
### The sources list
On the Brain page, each source shows an at-a-glance summary:
| Column | What it shows |
| - | - |
| **Name** | The source name, grouped by source type. |
| **Docs** | How many documents are indexed. |
| **Activity** | How often the source has been searched recently. |
| **Access** | Who can see and search it (its scope). |
| **Status** | The current sync status (Active, Paused, and so on). |
The **Overview** panel summarizes total sources and recent activity across everything you can see.
### A source's detail page
Click any source to open it. You get:
* The list of items it contains, each with its status and last-updated time.
* An **Overview** panel: status, document count, activity, last sync, and who added it.
* **Search this source** to preview what is indexed, and **Edit** to change what it syncs.
![Confluence source detail page listing indexed items with Access, Status, and Updated columns, and an Overview panel showing Status, Documents, Activity, Last synced, and Added by.]()
### Source actions
Open the **⋮** menu on any source for its management actions:
![Source context menu with Re-sync, Pause, Share, Rename, and Delete options.]()
Force an immediate sync to pull the latest content without waiting for the next scheduled run.
Stop syncing and stop any running indexing work. Already-indexed content stays searchable. Resume any time.
Change who can see and search the source. For organization sources this controls whether it's available org-wide or only to specific teams; you can also change a source's [Document access](#document-access) from its settings.
Change the display name your team and agents see. Renaming does not re-index anything.
Remove the source and all of its indexed chunks from Brain. This cannot be undone.
### Statuses
| Status | Meaning |
| - | - |
| **Active** | The source is connected and syncing normally. |
| **Preparing** | A newly added [build-your-own source](#build-your-own-sources) is being wired up before its first sync. Flips to Active on its own. |
| **Setup failed** | A build-your-own source couldn't be set up (for example, an empty account or out of credits). Shows a short reason; fix it and set the source up again. |
| **Paused** | Syncing is stopped until you resume it. Brain also pauses a source on its own after its last 3 syncs failed on the source's side, and emails the person who added it. See [Automatic pause after repeated failures](/help/brain/pause-resume-or-delete-a-source#automatic-pause-after-repeated-failures). |
| **Syncing** | A sync is currently running. |
| **Indexed** | An item has been processed and is searchable. |
| **Failed** | The last sync hit an error. Re-sync or check the connected account. |
| **Partial** | The last sync finished, but some items did not index. |
## The knowledge graph
Every Brain view includes a **knowledge graph**: an interactive 3D map of everything you have indexed. Each point is a piece of your knowledge, clustered by source and colored so you can see how your Slack, Drive, Confluence, and other content group and connect. Click **View knowledge graph** or **Expand** to open it full screen and drag to explore.
![A 3D knowledge graph showing thousands of points clustered around Slack, Google Drive, Confluence, and file-upload source icons.]()
## Giving an agent knowledge
Adding a source to Brain makes it available. To let a specific agent *use* it, attach it in that agent's configuration.
![An agent configuration panel titled Knowledge Sources with the prompt 'Give your agent knowledge: Attach Company Brain sources so this agent can search them, down to the exact files or folders within.']()
In the agent's configuration, find the **Knowledge Sources** section and click **+ Source**.
Pick from your Personal, Team, and Organization sources, or **Upload files** to add knowledge straight to this agent. You can drill into a source to attach only the exact files or folders that are relevant, so the agent searches a focused set.
![Add knowledge source dialog with an Upload files option and sources grouped under Personal, Team, and Organization.]()
Once a source is attached, the agent gets two built-in tools automatically:
* **Search Company Brain** runs a hybrid search across the attached sources and returns the most relevant snippets. In chat this shows as *Searching Company Brain*.
* **Read document** fetches the full text of a specific document when a snippet is not enough. In chat this shows as *Reading document*.
The agent decides when to search. When you ask about internal knowledge, it searches Brain, cites what it found, and can open a full document for more context.
## Prompting an agent to use Brain
Once knowledge is attached, you use the agent normally. It reaches for Brain when a question is about your internal content, often running several searches at once and citing the sources it used.
![An HR-Bot chat answering a password policy question by searching the Gumloop Policies source across three queries and returning a cited answer.]()
Prompts that work well:
* "According to our internal docs, what is our refund window?"
* "Find the launch retro notes and summarize the top three action items."
* "What did we decide about pricing in the Slack thread last quarter?"
* "Search our knowledge base for the onboarding checklist and turn it into an email."
Nudge the agent toward Brain when you want a grounded answer: phrases like "according to our docs," "search our knowledge base," or "what do we know about" make it clear you want a cited answer from your content, not a general one.
## Your agents' artifacts
Beyond the sources you connect, Gumloop can index the [artifacts](/core-concepts/agent_artifacts#how-artifacts-work) your agents produce, the files they generate for you in chat, so agents can search and reuse past work instead of starting from scratch.
* Artifacts are indexed at the **Personal** (your artifacts) or **Team** (a project's artifacts) level.
* Only the newest version of each artifact is indexed, and it updates in place when a new version is produced.
* Agents find them with the same **Search Company Brain** and **Read document** tools, so "pull up the deck we made last week" works like any other knowledge lookup.
## Searching Brain programmatically
Brain search isn't limited to agent chats. The same hybrid search is available anywhere you build, scoped to the sources the authenticated user can access:
`POST /brain/search` — search from any language over HTTP.
`client.brain.search("...")` returns ranked results.
`gumloop brain search "..."` from your shell.
The `search_brain` tool, callable from any MCP client.
Each of these accepts a query, an optional result `limit` (1–50), and an optional `source_type` filter, and returns ranked snippets with their title, source, URL, relevance score, and owner metadata.
## Credits
Brain usage consumes Gumloop credits:
* **Indexing** (also called **sync**) is charged as content is processed, so most of the cost lands when you first add a source and when its content changes.
* **Searching** is charged per query. This includes searches an agent runs for you: they are billed inside that agent's run, alongside the model and tool cost of the same task.
Where you see it:
| Where | How it appears |
| - | - |
| A chat's cost breakdown | A **Brain** line, separate from Chat & Reasoning and Tool Calls |
| Your credit history | **Brain Search** for queries, **Brain Indexing** for syncs |
| Organization [Insights](/enterprise-features/organization_insights#brain) | Sync credits and search credits for the whole org, and sync credits per source |
Bigger sources and heavier search usage cost more. See [Credits](/core-concepts/credits#what-you-pay-for) for how credits work across the platform.
If your credit balance is exhausted, Brain searches stop working. An agent mid-task is told the search failed and keeps going without those results, so answers can lose their grounding until credits are available again.
## FAQ
**Brain** is knowledge your agents can *search* (documents, messages, files). [**Skills**](/core-concepts/skills#what-is-a-skill) are instructions that teach an agent *how to do a task* your way. Use Brain for "what do we know about X," and skills for "here's our process for doing X."
Usually yes. Beyond the native source types, you can [build your own source](#build-your-own-sources) from almost any app in Gumloop's [connector library](/core-concepts/agents#connectors). An AI setup chat inspects the app, proposes what to sync, and you approve it, no technical configuration needed. Apps that already have a native source, and action-only or raw-database apps, are the exceptions.
No. Both the setup chat and ongoing sync are strictly **read-only**. They only read content to index it and never create, edit, or delete anything in the connected app.
A connector lets an agent take live actions and fetch specific items on demand. Brain pre-indexes your content so the agent can do fast, semantic **search across everything** at once, with citations, instead of navigating a tool call by call.
It depends on the source's size, from a minute or two for a small source to longer for large ones. The source shows **Active** and its items show **Indexed** once they are ready.
Yes. When a document is deleted or moved out of a source's scope upstream, the next successful sync removes it from Brain. To remove an entire source, use **Delete**.
No. Your indexed content is used only to answer your own team's agents, and the embedding provider Gumloop uses runs under a zero-data-retention policy, so your content is not retained by it or used to train third-party models.
It depends on the source's **scope**. Personal sources are visible only to you, Team sources to that [team](/core-concepts/teams), and Organization sources to everyone in your org (or only the teams you pick). Anyone who can see a source can search everything indexed in it, unless you set the source's [Document access](#document-access) to **Original source** (Google Drive, Salesforce, Gmail, and Linear), which additionally honors each document's own permissions.
Yes. When you add a Google Drive source, set **[Document access](#document-access)** to **Original source**. Brain then snapshots each file's Drive permissions on every sync and only lets a user retrieve a document if they have access to it in Drive. Google Group sharing is honored too, once an admin connects the [Google Workspace directory](#google-group-sharing-on-drive-sources); files shared only via "anyone with the link" stay private in Brain.
Common document formats such as PDFs, Office files (`.docx`, `.pptx`, `.xlsx`), rich text, Markdown, JSON, XML, YAML, and plain text, up to about 400 MB per file. Unsupported types are rejected, and Brain does not read text inside images.
Yes. Gumloop can index your agents' [artifacts](/core-concepts/agent_artifacts#how-artifacts-work) at the Personal or Team level, so an agent can search and reuse past outputs. Only the newest version of each artifact is indexed.
Yes. Each source has a **Search this source** box, and the Brain page has a global search so you can find and preview content directly.
Brain is available on the **Pro** and **Enterprise** plans.
## Next steps
Build and configure agents that use your knowledge.
Teach agents how to do tasks your way, on top of what they know.
# Browser logins and profiles
Source: https://docs.gumloop.com/core-concepts/browser_logins_and_profiles
Let your agent sign in to websites without seeing your password: saved logins with 2FA, browser profiles that keep sessions across tasks, imported sign-ins, and 1Password.
Your agent's [browser](/core-concepts/agent_browser) can sign in to websites in three ways: it restores a **browser profile** that is already signed in, it types a **saved login** (username, password, and optional 2FA) that Gumloop fills in for it, or it **hands the browser to you** to sign in. In every case, the agent never sees the password.
| | Browser profile | Saved login | Handoff |
| - | - | - | - |
| **What it holds** | The sites the browser is already signed in to | Username, password, optional 2FA key | Values you type once, or you sign in yourself |
| **Best for** | Staying signed in across tasks | Signing in again when a session expires | First sign-in, SSO, CAPTCHAs, phone approvals |
| **Where it lives** | Vault, **Browser Profiles** | Vault, **Logins** | The chat; can be saved as a login |
![Your Vault page with 1Password, Secrets, Logins, and Browser Profiles sections, showing one saved login and a Default browser profile]()
***
## User-owned or Agent-owned: whose accounts does the agent use?
Two settings on this page, **Browser profile** and **1Password**, ask the same question: when someone runs the agent, whose accounts does it use? You answer it with the same choice each time.
![Whose profile toggle with User-owned, Everyone uses their own profile, and Agent-owned, Everyone uses the profile you pick]()
**Everyone acts as themselves.** Each person who runs the agent uses their own accounts. If ten people use the agent, it works in ten different accounts. Shown as **User/Team-owned** on team agents.
* **Browser profile:** each person's own saved sign-ins.
* **1Password:** each person's own service account.
**Use it when** people work in their own accounts, for example a research agent your team shares where each person signs in to their own LinkedIn.
**Everyone acts as one account you pick.** The agent always uses the profile or 1Password connection you chose, no matter who runs it. People who run the agent never get access to that account directly.
* **Browser profile:** one profile you pick, for everyone.
* **1Password:** one service account you pick, for everyone.
**Use it when** the agent should always work in one shared account, for example a support agent that signs in to the team's vendor portal.
Agent-owned works the same way it does for [connectors](/core-concepts/credentials#agent-owned-credentials). On organizations it needs the **Agent-owned credentials** feature on your [custom role](/help/sharing/enable-agent-owned-credentials), and it can't be used while the agent is shared with **Anyone**. Choosing Agent-owned on an Anyone-shared agent offers to change its sharing first.
***
## Logins
A login is a website username, password, and optional 2FA authenticator key, stored encrypted in your Vault. When the agent signs in, it names the login and Gumloop types the values into the page after checking the site. The password and 2FA key never reach the agent or its sandbox environment.
### How do I add a login?
Go to [gumloop.com/personal/vault](https://www.gumloop.com/personal/vault) for your own logins, or your team's Vault for shared ones. Click **Add**.
*Username, password and optional 2FA. The agent types them into the site without seeing them.*
![What are you adding? dialog with API key or value and Login for a website options]()
![Add Login form with Name, Website, Username, Password, and an Advanced section with Authenticator key and Type the password on]()
| Field | What to enter |
| - | - |
| **Name** | How the agent refers to the login, for example `ACME`. Cannot start with a number. |
| **Website** | The site's address, for example `acme.com`. |
| **Username** | The account's username or email. |
| **Password** | The account's password. |
| **Authenticator key** (Advanced) | Optional. The setup key the site shows next to its 2FA QR code (letters and digits 2 to 7). Gumloop generates the current 6-digit code each time the agent signs in. |
| **Type the password on** (Advanced) | **Any page of this site** (default) or **This exact address only**. See [Where can a login be typed?](#where-can-a-login-be-typed) |
The login appears under **Logins** in your Vault.
### How do I give an agent a login?
In the agent's **Browser** section, click **+ Login**. In **Add login to agent**, choose a **Name** for the agent to use, then a **Source**: an **Existing login** from your Vault, or a **New login** created on the spot.
![Add login to agent dialog with Name, Source with Existing login and New login, and a Login picker]()
Gumloop also lists the agent's logins in its instructions, so the agent knows which sites it can sign in to and as which username. A binding you remove is revoked from the next turn, even in a running chat.
### Where can a login be typed?
Every fill is checked before anything is typed. The page field's scheme and port must match the login's website, and its host must match the **Type the password on** setting:
| Setting | Types on | Example for `acme.com` |
| - | - | - |
| **Any page of this site** | The site and its subdomains | `acme.com`, `app.acme.com`, `login.acme.com` |
| **This exact address only** | Only the exact host you entered | `acme.com` only |
The check uses the frame the field actually lives in, not just the top page, so a login form embedded from another site is refused. Shared hosting domains such as `github.io` or `herokuapp.com` count each subdomain as its own site, so a login for `alice.github.io` never types on `bob.github.io`.
If the check fails, nothing is typed and the agent is told to ask you with a [handoff](/core-concepts/agent_browser#when-does-the-agent-ask-me-for-help) instead.
### How do I save a login from a handoff?
When the agent asks you to sign in with a handoff card, tick **Save login for ``** before you click **Continue**. If the agent is in a team, choose who can use it: **Only me** or **My team**.
![Handoff card with Username and Password fields and a Save login checkbox]()
Gumloop saves the login to the matching Vault and names it after the site, for example `THE_INTERNET_HEROKUAPP_COM`. The card then reads *Saved the login for `` as `` and sent it to the agent*, and next time the agent signs in without asking.
***
## Browser profiles
**A browser profile is how the agent's browser remembers which websites it is signed in to.** It works like your own Chrome: sign in to a site once, and next time you open the browser you are still signed in. Without a profile, every task would start with a fresh browser that is signed out of everything.
### How does a profile keep the agent signed in?
It signs in with a [saved login](#logins), or you sign in for it with a [handoff](/core-concepts/agent_browser#when-does-the-agent-ask-me-for-help).
At the end of the agent's turn, the sign-in is saved to the browser profile.
The next time the agent opens the browser, even in a brand-new chat, it is already signed in to that site.
You do not need to set anything up. Your personal **Default** profile is created automatically the first time a task saves a sign-in.
### What's the difference between a profile and a login?
| | Browser profile | Login |
| - | - | - |
| **In plain terms** | "I'm already signed in" | "Here's how to sign in" |
| **What it stores** | The site's sign-in session (cookies and site data). No passwords. | Username, password, and optional 2FA key |
| **What the agent does with it** | Opens the site already signed in | Types it into the sign-in page |
They work best together. The profile keeps the agent signed in from task to task. When a site eventually signs it out, the agent uses the login to sign back in, and the profile saves the new session.
### Who owns a browser profile?
A profile belongs to a **person** or a **team**, never to an agent. An agent that uses a profile can use every site that profile is signed in to.
### Can everyone who runs the agent share one profile?
Yes, with **Agent-owned**. By default the profile is **User-owned**, so everyone uses their own sign-ins. Change it from the **Browser profile** row in the agent's **Browser** section. See [User-owned or Agent-owned](#user-owned-or-agent-owned-whose-accounts-does-the-agent-use) for which to pick.
![Browser profile settings with Whose profile options User-owned and Agent-owned, and a Profile section]()
* **User-owned:** *Everyone uses their own profile.* Each person's personal **Default** profile is used.
* **Agent-owned:** *Everyone uses the profile you pick.* Picking a profile in **Profile** switches the agent to Agent-owned.
The profile menu also has **Import from browser** and **Manage browser profiles** (opens the Vault). Incognito chats never restore or save a profile.
### How do I bring my own sign-ins into a profile?
Import the cookies from a browser on your computer, so agents open those sites already signed in. Open **Import logins** from the profile menu in the agent's **Browser profile** view, from **Import** in a profile's menu in the Vault, or from **Add** on the Vault's **Browser Profiles** row.
![Import logins dialog with From the terminal and From this browser sections]()
Copy the command from the dialog and run it on your computer. The dialog fills in the target profile for you.
```bash Terminal theme={"dark"}
curl -fsSL https://gumloop.com/cli/import-logins.sh | sh
```
macOS may ask for Keychain access. Windows is not supported yet.
With the [Gumloop CLI](/cli/overview) installed, you can run the import directly:
```bash Terminal theme={"dark"}
gumloop browser import-logins
gumloop browser import-logins --include-domain github.com --include-domain linear.app
gumloop browser import-logins --browser brave --exclude-domain doubleclick.net
```
| Option | What it does |
| - | - |
| `--url` | Import only this site, for example `https://github.com`. Default: every site. |
| `--include-domain` | Only these domains and their subdomains. Repeat for several. |
| `--exclude-domain` | Skip these domains and their subdomains. Repeat for several. |
| `--into` | Target profile id or name. Default: your personal default profile. |
| `--team` | Team id when the target profile belongs to a team. |
| `--browser` | `chrome`, `chromium`, `brave`, `edge`, `arc`, or `firefox`. Default: ask. |
| `--browser-profile` | Local browser profile name, for example `Default` or `Work`. |
| `--yes`, `-y` | Do not ask for confirmation. |
List your profiles and the sites they hold with `gumloop browser profiles list` (add `--team ` for a team's).
Install the Gumloop Chrome extension, then click **Preview** in the dialog. Pick the sites to import (*N of M sites*, with **Select all** and **Select none**) and click **Import**.
Import cookies programmatically with [Import cookies](/api-reference/browser-profiles/import-cookies), and list profiles with [List browser profiles](/api-reference/browser-profiles/list-browser-profiles).
* Imports bring **cookies only**, not local storage.
* An import can carry up to **20,000 cookies**. A profile holds up to **25,000 cookies** or **24 MB**.
* Importing while a task is running is safe: the import and the task's end-of-turn save are merged, not overwritten.
* Only people who manage team secrets can import into a team profile. Only a personal profile's owner can import into it.
### How do I manage profiles?
In the Vault's **Browser Profiles** section, **Add** opens **Import logins**, and each profile's menu has **Import**, **Rename**, and **Delete**.
| Action | Effect |
| - | - |
| **Remove a site** | Open a profile to see its sites and remove one. *Agents using `` are signed out of ``.* |
| **Delete** | *Agents using it start signed out. This cannot be undone.* |
When an agent switches profiles, or its profile is deleted, the browser is reset before the next step so no session carries over from one profile to another.
***
## 1Password
Connect 1Password and the agent can sign in with the logins in your 1Password vaults, including 2FA codes. You don't copy anything into Gumloop, and the agent never sees the passwords.
### How does 1Password work with the agent?
The first time the agent uses its browser in a turn, Gumloop reads the list of Login items in the vaults you allowed. It reads only each item's title and website, never the password.
The agent searches that list for the site it is on, for example `github.com`, and finds the matching item.
Gumloop fetches just that one item from 1Password and types the username, password, and current 2FA code into the page, after checking it is the item's site. 1Password logs each read.
### How do I set up 1Password?
1Password service accounts can't see Private vaults, so give agents a vault of their own, such as **Gumloop Agents**. Add the logins agents will use. Each login needs its **website** filled in, plus 2FA where the site asks for it.
In 1Password [Developer Tools](https://my.1password.com/developer-tools/directory), create a **Service Account** with **read-only** access to that vault. Copy the `ops_` token. 1Password shows it only once.
In your [Vault](https://www.gumloop.com/personal/vault) (or your team's Vault), click **Add** on the **1Password** row and paste the token.
In the agent's **Browser** section, open **1Password** and click **Turn on** under **Use 1Password**. The agent's **Browser** must be on first.
**Whose service account:** **User-owned** uses each person's own default service account (or the team's default on team agents); **Agent-owned** uses one service account you pick for everyone. See [User-owned or Agent-owned](#user-owned-or-agent-owned-whose-accounts-does-the-agent-use).
**Vaults:** **All vaults** the service account can read, or up to 10 specific vaults.
[Gumball](/core-concepts/gumball) needs no setup. Once you connect 1Password, it can use every vault your default connection can read.
### How does the agent find the right login?
Each 1Password Login item becomes a login named `OP_`, for example `OP_GITHUB`. The agent finds items by searching:
| Search for | Finds |
| - | - |
| **A site**, such as `github.com` or a URL | Items saved for that site. Searching the site the agent is on is how it usually finds the login. |
| **Words**, such as `acme billing` | Items whose title, site, or username contains all the words |
A login named "GitHub" but saved for a different website does not match a `github.com` search, because matching uses the item's website, not its title.
### What are the 1Password limits?
| Limit | Value |
| - | - |
| **Vaults per agent** | All vaults, or up to 10 specific vaults |
| **Logins available per turn** | Up to 500 items across all vaults |
| **Results per search** | 25. A broader search asks the agent to narrow it down. |
| **Items that can be used** | Login items with a website. An item types only on its own websites. |
| **Private vaults** | Not visible to service accounts |
| **Changes in 1Password** | A new or removed login or vault shows up on the agent's next turn |
### What else should I know?
* **If 1Password is unavailable** or rate-limits the service account, that turn runs without 1Password logins and the task continues.
* **If a Vault login and a 1Password item have the same name,** the Vault login is used. Two 1Password items with the same title get `_2`, `_3`, and so on.
* **Keep agent vaults small.** An agent can sign in with any login in the vaults you give it.
* **Agent-owned 1Password** is not used while the agent is shared with **Anyone**.
***
## FAQ
<AccordionGroup>
<Accordion title="The agent says it can't type my login on this page. Why?">
The page failed the site check. Common causes: the login is set to **This exact address only** and the form is on another subdomain (for example `login.acme.com`), the form is inside an embedded frame from a different site, or the scheme or port differs. Edit the login and set **Type the password on** to **Any page of this site**, or let the agent ask you with a handoff.
</Accordion>
<Accordion title="Can the agent handle SMS or email 2FA codes?">
Only authenticator-app codes can be generated automatically, from the login's **Authenticator key**. For codes sent by SMS or email, the agent hands the browser to you with a one-time code field.
</Accordion>
<Accordion title="How do I change a saved password?">
Edit the login in the Vault. Leave **Password** or **Authenticator key** blank to keep the current value.
</Accordion>
<Accordion title="Do my teammates get my sign-ins?">
Not with the default **User-owned** setting: each person uses their own profile and their own logins. With an **Agent-owned** profile or a team login, everyone who runs the agent uses the same sessions or credentials.
</Accordion>
<Accordion title="I deleted the agent's profile. Why didn't it fall back to mine?">
An agent-owned profile stays pinned even after it is deleted, so the browser starts signed out rather than silently using someone else's sessions. Pick a new profile, or switch **Whose profile** back to **User-owned**.
</Accordion>
<Accordion title="Why is the agent signed out even though I imported my cookies?">
Check that you imported into the profile the agent uses (see **Browser profile** in the agent's **Browser** section), and that the site's session had not expired in your own browser. Some sites also tie sessions to local storage, which imports do not copy. In that case, save a login so the agent can sign in itself.
</Accordion>
</AccordionGroup>
***
## Related
<Columns>
<Card title="Agent browser" icon="window-maximize" href="/core-concepts/agent_browser">
Turn on the browser, watch it live, replay steps, and answer handoffs.
</Card>
<Card title="Code sandbox & secrets" icon="vault" href="/core-concepts/agent_sandbox_and_secrets">
The Vault, secrets, and the sandbox the browser runs in.
</Card>
<Card title="CLI" icon="terminal" href="/cli/overview">
Install the Gumloop CLI to import sign-ins from your terminal.
</Card>
<Card title="Custom roles" icon="users-gear" href="/enterprise-features/user_groups">
Control who can give agents a browser.
</Card>
</Columns>
# Connectors
Source: https://docs.gumloop.com/core-concepts/credentials
## Overview
**Connectors** let your agents use services such as Gmail, Slack, and Salesforce. Add the connectors an agent needs, then connect an account for each service. You can connect multiple accounts and choose which one the agent uses.
A connector provides tools for a service. Its connected accounts provide authentication, such as OAuth authorization or an API key. **Secrets** are separate: they store values an agent uses in its code sandbox. See [Code Sandbox & Secrets](/core-concepts/agent_sandbox_and_secrets).
<CardGroup>
<Card title="Personal connectors" icon="user">
Private to you. Perfect for individual work, testing, and personal accounts.
</Card>
<Card title="Team connectors" icon="users">
Shared with your team. Use a team account when everyone should work through the same service account.
</Card>
</CardGroup>
<Tip>
Start with personal connectors for most work. Use team connectors when your team needs agents to use shared accounts.
</Tip>
### Personal vs team connectors
| | **Personal Connectors** | **Team Connectors** |
| - | - | - |
| **Who can use?** | Only you | All team members |
| **Where do they work?** | Any space (personal or team) | Specific team only |
| **Agent account setting** | **Use Personal Default** uses the running user's account | **Use Team Default** uses the team's shared account |
| **Setup** | One-time, works everywhere | Per team |
| **Best for** | Individual work, testing, personal accounts | Team collaboration, shared accounts |
| **Privacy** | Fully private, even in teams | Shared with all team members |
***
<span />
## Connect an account
Connect an account once, then reuse it across your agents. A **personal** account is available to you; a **team** account is available to members of that team.
### Connect a personal connector
<Steps>
<Step title="Go to your Connectors page">
Visit your [Connectors page](https://www.gumloop.com/settings/profile/connectors?view=connected) or navigate via **Settings → Connectors**
</Step>
<Step title="Choose a service">
Open **All** or **Discover**, find the service you need, and start its connection process. If it is already listed under **Connected**, use the **+** next to the service to add another account.
</Step>
<Step title="Authenticate">
**OAuth (most services):** Click "Connect" and follow the authorization flow. No manual token management needed. Examples: Gmail, Slack, Microsoft services.
**API Keys (some services):** Paste your API key directly. Examples: OpenAI, AWS, Anthropic.
</Step>
<Step title="Set as default (optional)">
If you connect multiple accounts for the same service (e.g., three different Gmail accounts), you can choose which one is your default. If you only have one account connected for a service, it's automatically your default.
</Step>
</Steps>
<Frame>
<img alt="Personal Connectors page" />
</Frame>
<Info>
**Privacy guaranteed:** Even in teams, other members cannot see or use your personal connectors.
</Info>
### Connect a team connector
Team connectors are shared integrations that everyone on a specific team can use. They are scoped to that team, and a team's default account applies when the agent uses **Use Team Default**. Open the team's **Connectors** page to add an account. See [Add team connectors](/help/connectors/add-team-connectors) for the steps.
***
## Choose Which Account to Use
A connector can have several connected accounts for the same service, such as three Gmail accounts. The agent's **Account** selector determines which one it uses.
<Tip>
**Rule of thumb:** by default, everyone uses their own account (**Use Personal Default**). Switch to a team account only when everyone should act as the *same* shared login, such as a support inbox or a team Google Drive.
</Tip>
### In agents
Open a connector in the agent's **Connectors** section to choose its account. Agents can be **shared** with your organization or specific people, so account selection must also work for whoever **runs** the agent.
**How to choose:**
<CardGroup>
<Card title="Everyone as themselves" icon="user">
Pick **Use Personal Default**. Each person who runs the agent uses their own account, so data stays private to each user. This is the default.
</Card>
<Card title="Everyone as one shared login" icon="users">
In a team agent, pick **Use Team Default** (or pin a team account). Every team member who runs the agent uses that same shared account.
</Card>
</CardGroup>
<Info>
**Which account does the agent run with?** It depends on the option you pick and who runs the agent:
* **Use Personal Default** (the default for both personal and team agents): the agent uses the **running user's own** default account. Share the agent and each person uses their own account, so data stays private to each user.
* **Use Specific Account** pins one exact account. Gumloop uses that account only for users who can access it. It does not silently substitute another account when the pin is missing or unavailable. An Owner must select an available account, choose a default-account option, or explicitly configure agent-owned credentials when a shared service account is intended.
* **Use Team Default** uses a shared **team** account, so every team member who runs the agent uses that same account.
* **Agent-owned credentials** are the exception. When you explicitly pin an account as *agent-owned*, everyone who can access the agent uses that account when tools are called, including people you share it with. See [Agent-Owned Credentials](#agent-owned-credentials) below.
</Info>
#### Personal agents
Personal agents offer two choices. A personal agent can still be shared, so the table shows which account is used when you run it versus when someone you shared it with runs it.
<Frame>
<img alt="Personal agent credential menu showing Use Personal Default and Use Specific Account options" />
</Frame>
| Option | What it does | Account used at runtime |
| - | - | - |
| **Use Personal Default** | Uses the default account of whoever runs the agent. This is the default setting. | Each person uses their own account |
| **Use Specific Account** | Pins one of your personal accounts to this agent (e.g., one of two Outlook inboxes). | The selected account, only for its owner. Other users cannot use that pin. |
#### Team agents
Team agents have a third option: **Use Team Default**. This lets all team members share one account without each person needing their own credentials for that service.
<Frame>
<img alt="Team agent credential menu showing Use Personal Default, Use Team Default, and Use Specific Account options" />
</Frame>
| Option | What it does | Account used at runtime |
| - | - | - |
| **Use Personal Default** | Uses the personal account of whoever runs the agent. The default setting. | Each person uses their own account |
| **Use Team Default** | Uses the team's shared default account for this service. | All team members use the shared team account |
| **Use Specific Account** | Pins one team-connected account so the agent always uses it. | The selected team account for users with access to it. Users without access cannot use the pin. |
<Warning>
Changing a team agent's connected account affects everyone on the team, so a confirmation dialog appears first. You can **cancel**, **make a personal copy** of the agent instead of changing the shared one, or **select a team account** to proceed.
</Warning>
<Frame>
<img alt="Confirmation dialog asking if you want to change the account this team agent uses" />
</Frame>
For configuration steps, see [Agents: Account selection](/core-concepts/agents#account-selection). For Slack-specific setup, see [Using Agents in Slack](/core-concepts/agents_slack#access-and-credentials).
### Agent-owned credentials
By default, connectors are **user-owned**: each person who runs the agent uses the account available to them, and a specific account you pin only applies when *you* run the agent. **Agent-owned credentials** change this. When a connector is agent-owned, everyone who can access the agent uses the one account or connection you pinned, without getting direct access to the underlying credential.
<Info>
**Selection and ownership are separate.** Choosing a specific account decides *which* account the agent uses. Ownership decides *whose* identity runs the tool. Selecting a specific account does not make it agent-owned on its own. You turn that on explicitly.
</Info>
#### Which ownership mode to use
<CardGroup>
<Card title="User-owned / User/Team-owned" icon="user">
Each person who runs the agent acts as **themselves**, using the account available to them. Pick this when a shared agent should work on each user's own data and that data should stay private to each user. This is the default.
</Card>
<Card title="Agent-owned" icon="lock">
The agent is **bound to one specific account**, and everyone who can access it acts as that account no matter who runs the agent. Pick this when the agent should always use one connected account, such as a shared service account or a support inbox, so the agent always behaves the same way for every user.
</Card>
</CardGroup>
#### Turn on agent-owned for a connector
<Steps>
<Step title="Select a specific account">
In the **Agent** tab, expand **Connectors**, open the connector's detail view, and select the account you want to pin.
</Step>
<Step title="Set Credential ownership">
A **Credential ownership** control appears once a specific account is selected. Choose one of:
* **User-owned** (labeled **User/Team-owned** on team agents): each user uses the accounts available to them when tools are called. This is the default.
* **Agent-owned**: everyone using this agent uses the pinned credential when tools are called.
<Frame>
<img alt="Credential ownership section in a Gmail connector detail view showing the User-owned and Agent-owned options" />
</Frame>
Connectors set to agent-owned show an **Agent Owned** label in the agent's tool list.
<Frame>
<img alt="Agent connector list showing a connector labeled Agent Owned" />
</Frame>
</Step>
</Steps>
<Warning>
**Agent-owned credentials and `Anyone` public sharing cannot be used together.** A pinned credential would otherwise be exposed to the public. If the agent is already shared with `Anyone`, choosing **Agent-owned** asks you to change general access to a non-public level (organization, team, or restricted) first. Once an agent has an agent-owned credential, the `Anyone` option is disabled in its share dialog.
</Warning>
Agent-owned pins are tied to the workspace they live in. Cloning an agent, using it as a template, or moving it to another workspace removes the agent-owned pin, and the connector reverts to user-owned in the new location.
#### Enterprise availability
For organizations, agent-owned credentials are **restricted by default**. An admin turns them on per [custom role](/enterprise-features/user_groups) with the **Agent-owned credentials** feature toggle. Members whose roles do not grant it see the **Agent-owned** option disabled. You can only pin an account you have access to, and Gumloop re-checks that when the agent is saved.
<Info>
Agent-owned credentials are **required** for agents that let Slack members without Gumloop accounts run them. Those people have no accounts of their own to authenticate with, so any user-owned connector fails for them. See [Organization Service Accounts for Slack Agents](/enterprise-features/slack_agent_access).
</Info>
***
## Manage your connectors
<AccordionGroup>
<Accordion title="Viewing your connectors" icon="list">
Visit your [Connectors page](https://www.gumloop.com/settings/profile/connectors?view=connected) to see all your personal connectors, last refresh time, connected services, and defaults.
</Accordion>
<Accordion title="Refreshing a connector" icon="rotate">
OAuth connectors automatically refresh when needed. If you see authentication errors:
1. Go to your Connectors page
2. Open the account's three-dot menu and choose **Refresh**
3. Complete the authorization flow again
</Accordion>
<Accordion title="Removing a connector" icon="trash">
1. Go to your Connectors page
2. Find the connected account to remove, open its three-dot menu, and choose **Revoke**
3. Confirm removal
The account's authorization is removed. Agents using that account cannot call the service until you connect an account again.
</Accordion>
<Accordion title="Setting defaults" icon="star">
**Personal default:** Your default account for a service. An agent uses it for your tasks when its account setting is **Use Personal Default**.
**Team default:** The team's shared default account for a service. Team members use it when the agent's account setting is **Use Team Default**.
</Accordion>
</AccordionGroup>
***
## Admin setup
Some services require an administrator to authorize Gumloop before anyone on the team can connect their own account.
### Microsoft Office Setup (Admin Only)
For organizations using Microsoft services (Teams, Outlook, Excel, Word, OneLake), **administrators must configure consent** in Microsoft Entra ID before users can authenticate.
<Info>
**Start by connecting a Microsoft connector in Gumloop yourself.** Gumloop only appears in your tenant once someone attempts to authenticate, so do this first or you won't find the app in the steps below.
</Info>
<Tabs>
<Tab title="Tenant-wide consent" icon="building">
### Option 1: Grant Admin Consent (Recommended)
<Steps>
<Step title="Access Microsoft Entra admin center">
Go to [Microsoft Entra admin center](https://entra.microsoft.com)
</Step>
<Step title="Navigate to Enterprise apps">
Navigate to **Entra ID > Enterprise apps > All applications**
<Frame>
<img alt="Navigate to Enterprise apps" />
</Frame>
</Step>
<Step title="Search for Gumloop">
Search for Gumloop using client ID: `d3c2a9a5-7f60-40d1-a8ba-62bab546a0f3`
<Frame>
<img alt="Search for Gumloop" />
</Frame>
</Step>
<Step title="Grant consent">
Under **Security > Permissions**, click **Grant admin consent**, then complete the sign-in prompt and click **Accept**.
</Step>
<Step title="Verify the permissions landed">
Still under **Security > Permissions**, open the **Admin consent** tab. You should see a row for each permission listed in [Required Permissions by Service](#required-permissions-by-service).
If the tab is empty or unchanged, the request failed and nothing was granted. Use the **Direct Consent Link** tab above instead.
</Step>
</Steps>
</Tab>
<Tab title="Admin consent workflow" icon="clipboard-check">
### Option 2: Enable User Requests
<Steps>
<Step title="Open admin consent settings">
Go to **Entra ID > Enterprise apps > Consent and permissions > Admin consent settings**
</Step>
<Step title="Enable user requests">
Set **Users can request admin consent** to **Yes**
<Frame>
<img alt="Enable admin consent requests" />
</Frame>
</Step>
<Step title="Configure reviewers">
Set up reviewers and approval workflow for user requests
</Step>
</Steps>
</Tab>
<Tab title="Direct consent link" icon="link">
### Direct Consent Link
Use this if **Grant admin consent** granted nothing, or if Gumloop isn't in your tenant yet.
<Steps>
<Step title="Open the consent link for each service you need">
Every service under [Required Permissions by Service](#required-permissions-by-service) has its own consent link, listed directly beneath the permissions it grants. Open the link for each service you plan to use.
Grants add to each other, so the order doesn't matter and opening several is fine.
</Step>
<Step title="Sign in and accept">
Sign in as a Global Administrator and accept the prompt.
You will land on an error page at `api.gumloop.com/auth/callback`. **This is expected** — consent is already saved.
</Step>
<Step title="Verify">
Go to **Enterprise apps > Gumloop > Security > Permissions > Admin consent** and confirm the permissions are listed.
</Step>
</Steps>
<Tip>
Each link applies to whichever tenant you sign in with. To pin a link to one tenant, replace `organizations` in the URL with your tenant ID.
</Tip>
</Tab>
</Tabs>
#### Required permissions by service
Every permission below is **delegated**. Gumloop acts only as the signed-in user and can never do more than that user could do themselves. There are no application (app-only) permissions, so Gumloop has no standalone background access to other people's mailboxes, files, or sites.
Each service also requires `offline_access`, which lets Gumloop refresh its access token so users don't have to reconnect every hour.
Expand a service to see the permissions it needs and the consent link that grants them. Only grant the services you actually plan to use.
<AccordionGroup>
<Accordion title="Teams" icon="users">
| Permission | What it's used for |
| - | - |
| `User.Read` | Identify the signed-in user |
| `Team.Create` | Create teams |
| `Team.ReadBasic.All` | List team names and descriptions |
| `Channel.Create` | Create channels |
| `ChannelMember.Read.All` | Read channel membership |
| `ChannelMember.ReadWrite.All` | Add and remove channel members |
| `ChannelMessage.Read.All` | Read channel messages |
| `ChannelMessage.Send` | Post channel messages |
| `Chat.Read` | Read chat messages |
| `Chat.ReadWrite` | Read and send chat messages |
| `Chat.Create` | Start new chats |
| `TeamMember.Read.All` | Read team membership |
| `TeamMember.ReadWrite.All` | Add and remove team members |
| `Group.Read.All` | Resolve the Microsoft 365 group backing a team |
| `Group.ReadWrite.All` | Manage the group backing a team |
| `Directory.Read.All` | Look up users when adding them to teams or channels |
| `OnlineMeetings.Read` | Read meeting details |
| `OnlineMeetings.ReadWrite` | Create and update meetings |
| `Calendars.Read` | Read meeting times |
| `Calendars.ReadWrite` | Schedule meetings |
[**Grant Teams permissions →**](https://login.microsoftonline.com/organizations/v2.0/adminconsent?client_id=d3c2a9a5-7f60-40d1-a8ba-62bab546a0f3\&redirect_uri=https%3A%2F%2Fapi.gumloop.com%2Fauth%2Fcallback\&state=setup\&scope=https%3A%2F%2Fgraph.microsoft.com%2FUser.Read+https%3A%2F%2Fgraph.microsoft.com%2FTeam.Create+https%3A%2F%2Fgraph.microsoft.com%2FTeam.ReadBasic.All+https%3A%2F%2Fgraph.microsoft.com%2FChannel.Create+https%3A%2F%2Fgraph.microsoft.com%2FChannelMember.Read.All+https%3A%2F%2Fgraph.microsoft.com%2FChannelMember.ReadWrite.All+https%3A%2F%2Fgraph.microsoft.com%2FChannelMessage.Read.All+https%3A%2F%2Fgraph.microsoft.com%2FChannelMessage.Send+https%3A%2F%2Fgraph.microsoft.com%2FChat.Read+https%3A%2F%2Fgraph.microsoft.com%2FChat.ReadWrite+https%3A%2F%2Fgraph.microsoft.com%2FChat.Create+https%3A%2F%2Fgraph.microsoft.com%2FTeamMember.Read.All+https%3A%2F%2Fgraph.microsoft.com%2FTeamMember.ReadWrite.All+https%3A%2F%2Fgraph.microsoft.com%2FGroup.Read.All+https%3A%2F%2Fgraph.microsoft.com%2FGroup.ReadWrite.All+https%3A%2F%2Fgraph.microsoft.com%2FDirectory.Read.All+https%3A%2F%2Fgraph.microsoft.com%2FOnlineMeetings.Read+https%3A%2F%2Fgraph.microsoft.com%2FOnlineMeetings.ReadWrite+https%3A%2F%2Fgraph.microsoft.com%2FCalendars.Read+https%3A%2F%2Fgraph.microsoft.com%2FCalendars.ReadWrite+offline_access)
</Accordion>
<Accordion title="Outlook" icon="envelope">
| Permission | What it's used for |
| - | - |
| `User.Read` | Identify the signed-in user |
| `Mail.ReadWrite` | Read, draft, and organize the user's mail |
| `Mail.Send` | Send mail as the user |
| `Calendars.ReadWrite` | Read and write calendar events |
| `Calendars.ReadWrite.Shared` | Read and write calendars shared with the user |
[**Grant Outlook permissions →**](https://login.microsoftonline.com/organizations/v2.0/adminconsent?client_id=d3c2a9a5-7f60-40d1-a8ba-62bab546a0f3\&redirect_uri=https%3A%2F%2Fapi.gumloop.com%2Fauth%2Fcallback\&state=setup\&scope=https%3A%2F%2Fgraph.microsoft.com%2FUser.Read+https%3A%2F%2Fgraph.microsoft.com%2FMail.ReadWrite+https%3A%2F%2Fgraph.microsoft.com%2FMail.Send+https%3A%2F%2Fgraph.microsoft.com%2FCalendars.ReadWrite+https%3A%2F%2Fgraph.microsoft.com%2FCalendars.ReadWrite.Shared+offline_access)
</Accordion>
<Accordion title="Outlook Calendar" icon="calendar">
| Permission | What it's used for |
| - | - |
| `User.Read` | Identify the signed-in user |
| `Calendars.ReadWrite` | Read and write calendar events |
| `Calendars.ReadWrite.Shared` | Read and write calendars shared with the user |
[**Grant Outlook Calendar permissions →**](https://login.microsoftonline.com/organizations/v2.0/adminconsent?client_id=d3c2a9a5-7f60-40d1-a8ba-62bab546a0f3\&redirect_uri=https%3A%2F%2Fapi.gumloop.com%2Fauth%2Fcallback\&state=setup\&scope=https%3A%2F%2Fgraph.microsoft.com%2FUser.Read+https%3A%2F%2Fgraph.microsoft.com%2FCalendars.ReadWrite+https%3A%2F%2Fgraph.microsoft.com%2FCalendars.ReadWrite.Shared+offline_access)
</Accordion>
<Accordion title="Excel and Word" icon="file-lines">
| Permission | What it's used for |
| - | - |
| `User.Read` | Identify the signed-in user |
| `Files.ReadWrite` | Read and write the user's own files |
| `Sites.ReadWrite.All` | Read and write documents stored in SharePoint sites |
| `Sites.Selected` | Access the specific sites the user picks |
[**Grant Excel and Word permissions →**](https://login.microsoftonline.com/organizations/v2.0/adminconsent?client_id=d3c2a9a5-7f60-40d1-a8ba-62bab546a0f3\&redirect_uri=https%3A%2F%2Fapi.gumloop.com%2Fauth%2Fcallback\&state=setup\&scope=https%3A%2F%2Fgraph.microsoft.com%2FUser.Read+https%3A%2F%2Fgraph.microsoft.com%2FFiles.ReadWrite+https%3A%2F%2Fgraph.microsoft.com%2FSites.ReadWrite.All+https%3A%2F%2Fgraph.microsoft.com%2FSites.Selected+offline_access)
</Accordion>
<Accordion title="SharePoint" icon="share-nodes">
| Permission | What it's used for |
| - | - |
| `Sites.ReadWrite.All` | Read and write site content |
| `Sites.Manage.All` | Create and delete lists and list items |
| `Files.ReadWrite.All` | Read and write files the user can access |
| `User.Read.All` | Resolve user names shown on site content |
[**Grant SharePoint permissions →**](https://login.microsoftonline.com/organizations/v2.0/adminconsent?client_id=d3c2a9a5-7f60-40d1-a8ba-62bab546a0f3\&redirect_uri=https%3A%2F%2Fapi.gumloop.com%2Fauth%2Fcallback\&state=setup\&scope=https%3A%2F%2Fgraph.microsoft.com%2FSites.ReadWrite.All+https%3A%2F%2Fgraph.microsoft.com%2FSites.Manage.All+https%3A%2F%2Fgraph.microsoft.com%2FFiles.ReadWrite.All+https%3A%2F%2Fgraph.microsoft.com%2FUser.Read.All+offline_access)
</Accordion>
<Accordion title="OneDrive" icon="cloud">
| Permission | What it's used for |
| - | - |
| `Files.ReadWrite.All` | Read and write files the user can access |
[**Grant OneDrive permissions →**](https://login.microsoftonline.com/organizations/v2.0/adminconsent?client_id=d3c2a9a5-7f60-40d1-a8ba-62bab546a0f3\&redirect_uri=https%3A%2F%2Fapi.gumloop.com%2Fauth%2Fcallback\&state=setup\&scope=https%3A%2F%2Fgraph.microsoft.com%2FFiles.ReadWrite.All+offline_access)
</Accordion>
<Accordion title="OneLake" icon="database">
OneLake needs its **own** consent link and is not covered by the other services.
| Permission | What it's used for |
| - | - |
| `https://storage.azure.com/user_impersonation` | Access OneLake storage as the signed-in user |
[**Grant OneLake permissions →**](https://login.microsoftonline.com/organizations/v2.0/adminconsent?client_id=d3c2a9a5-7f60-40d1-a8ba-62bab546a0f3\&redirect_uri=https%3A%2F%2Fapi.gumloop.com%2Fauth%2Fcallback\&state=setup\&scope=https%3A%2F%2Fstorage.azure.com%2Fuser_impersonation+offline_access)
</Accordion>
<Accordion title="Azure" icon="microsoft">
Azure needs **two** separate consent links. Open both.
| Permission | What it's used for |
| - | - |
| `https://management.azure.com/user_impersonation` | Manage Azure resources as the signed-in user |
| `https://cognitiveservices.azure.com/user_impersonation` | Call Azure AI services as the signed-in user |
[**Grant Azure resource management permissions →**](https://login.microsoftonline.com/organizations/v2.0/adminconsent?client_id=d3c2a9a5-7f60-40d1-a8ba-62bab546a0f3\&redirect_uri=https%3A%2F%2Fapi.gumloop.com%2Fauth%2Fcallback\&state=setup\&scope=https%3A%2F%2Fmanagement.azure.com%2Fuser_impersonation+offline_access)
[**Grant Azure AI permissions →**](https://login.microsoftonline.com/organizations/v2.0/adminconsent?client_id=d3c2a9a5-7f60-40d1-a8ba-62bab546a0f3\&redirect_uri=https%3A%2F%2Fapi.gumloop.com%2Fauth%2Fcallback\&state=setup\&scope=https%3A%2F%2Fcognitiveservices.azure.com%2Fuser_impersonation+offline_access)
</Accordion>
</AccordionGroup>
<Warning>
**Admin required:** You must be a Global Administrator, Cloud Application Administrator, or Application Administrator to grant consent.
</Warning>
<Tip>
**Confirm it worked with a non-admin account.** An administrator can succeed for reasons that don't apply to everyone else. After granting consent, have a regular user connect the service in Gumloop. If they get through without an approval prompt, the tenant is set up correctly.
</Tip>
### Salesforce setup (Admin only)
As of September 2025, Salesforce introduced new security restrictions that require administrators to pre-install the Gumloop connected app before users can authenticate with their Salesforce instances. For more details, see the [official Salesforce documentation](https://help.salesforce.com/s/articleView?id=005132365\&type=1).
<Info>
Gumloop is a **Salesforce Connected App**, not an AppExchange app. You will **not** find it in the Salesforce AppExchange marketplace. A Salesforce administrator needs to authorize the connection directly.
</Info>
<Tabs>
<Tab title="Admin connects directly (recommended)" icon="bolt">
The easiest way is for a **Salesforce administrator** to authenticate directly from Gumloop:
<Steps>
<Step title="Go to your Connectors page">
Visit the [Salesforce connectors page](https://www.gumloop.com/settings/profile/connectors?view=connected) in Gumloop
</Step>
<Step title="Click Connect and authorize">
Click **Connect** next to Salesforce and sign in with your Salesforce admin account.
</Step>
<Step title="Gumloop is automatically added">
The Gumloop connected app is automatically installed in your Salesforce organization. No additional setup needed.
</Step>
</Steps>
<Tip>
After the admin connects, all users in the Salesforce organization can authenticate their own accounts with Gumloop.
</Tip>
</Tab>
<Tab title="Non-Admin user flow" icon="user">
If a **non-admin user** tries to connect before an admin has authorized:
<Steps>
<Step title="User attempts to connect">
The user visits the [Salesforce connectors page](https://www.gumloop.com/settings/profile/connectors?view=connected) and clicks **Connect**
</Step>
<Step title="Admin approval required">
Salesforce blocks the connection. The Salesforce admin will see a request to approve the Gumloop app in their admin console.
</Step>
<Step title="Admin approves the app">
The admin navigates to **Setup > Apps > Connected Apps > Manage Connected Apps** in Salesforce and approves the pending request.
<Frame>
<img alt="Salesforce connected app setup" />
</Frame>
</Step>
<Step title="User retries">
After admin approval, the user can return and successfully complete the OAuth flow.
</Step>
</Steps>
</Tab>
</Tabs>
#### Managing the connected app in Salesforce
1. Go to **Setup > Apps > Connected Apps > Manage Connected Apps**
2. Find the Gumloop app to view or modify settings
3. Configure user access policies, IP restrictions, and session policies as needed
<Info>
For more details, refer to the [Salesforce Connected App documentation](https://help.salesforce.com/s/articleView?id=sf.connected_app_overview.htm\&type=5).
</Info>
***
## Security & compliance
<CardGroup>
<Card title="SOC 2 Type II" icon="shield-check">
Certified secure infrastructure and processes
</Card>
<Card title="GDPR compliant" icon="scale-balanced">
Full compliance with data protection regulations
</Card>
<Card title="Trust Center" icon="file-shield" href="https://trust.gumloop.com/">
View our complete security documentation
</Card>
</CardGroup>
***
## Related documentation
<CardGroup>
<Card title="Organization and teams" icon="building" href="https://docs.gumloop.com/core-concepts/teams">
Understand how personal spaces and teams work
</Card>
<Card title="User roles & permissions" icon="shield" href="https://docs.gumloop.com/core-concepts/organization_user_roles">
Organization and team permission levels
</Card>
</CardGroup>
# Credits
Source: https://docs.gumloop.com/core-concepts/credits
How Gumloop bills agent chats
Credits are the currency that powers Gumloop. Every agent conversation spends credits based on the AI model it uses, the tools it calls, and how long it runs.
<Info>
Agent credit costs are **variable**. The same agent might cost 2 credits for a quick question and 200 for a deep research task. You pay for what the agent actually does, not a fixed per-message price.
</Info>
## What a credit is worth
<CardGroup>
<Card title="1 credit = $0.005" icon="coins">
\$1 buys 200 credits.
</Card>
<Card title="Model calls bill at cost" icon="microchip">
Divide the model cost by \$0.005: a \$0.03 model call is 6 credits.
</Card>
</CardGroup>
Everything else on this page is priced in credits directly. Charges are rounded up to whole credits.
## What you pay for
An agent chat is billed in real time, and its total is the sum of four things.
| Component | What it covers | Cost |
| - | - | - |
| **Chat & Reasoning** | The model reading your message, thinking, and writing a response | The model's cost, at \$0.005 per credit |
| **Tool Calls** | Each connector tool the agent uses | 1 credit per successful connector call, plus that tool's own charge |
| **Compute** | Time the agent spends actively working | 5 credits per session-minute |
| **Orchestration Fee** | Running the agent loop itself | 8% of the three above |
Some runs add a fifth line: if the agent searches your [Company Brain](/core-concepts/brain), each search is charged to that run and shown as **Brain**. A search is priced on the embedding and ranking work it does, so it is typically small next to the model cost of the same task.
<AccordionGroup>
<Accordion title="Chat & Reasoning — the biggest part of most chats" icon="comments">
Priced on the tokens each message uses, converted from the model's cost at \$0.005 per credit. Three things drive it:
* **The model you pick.** Faster, smaller models cost less per token than frontier models. See [AI Models](/core-concepts/ai_models).
* **Conversation length.** Every message carries the earlier conversation as context, so longer chats cost more per message.
* **How many tools are connected.** Each tool adds its definition to the prompt, which adds tokens.
One message can also trigger several AI steps: when an agent uses tools it loops — decide which tool to call, read the result, then respond — and each step is billed separately.
</Accordion>
<Accordion title="Tool Calls: 1 credit per connector call, some charge more" icon="wrench">
Every **successful** connector tool call costs at least 1 credit. Failed calls are not charged.
* Reading and writing to apps like [Slack](https://www.gumloop.com/mcp/slack), [Google Sheets](https://www.gumloop.com/mcp/gsheets), and [Gmail](https://www.gumloop.com/mcp/gmail) costs that 1 credit and nothing more.
* Tools that enrich or fetch external data, such as [Apollo](https://www.gumloop.com/mcp/apollo) lead enrichment or [Firecrawl](https://www.gumloop.com/mcp/firecrawl) web scraping, add their own charge on top.
Each tool's [MCP catalog](https://www.gumloop.com/mcp) page lists its cost.
Built-in abilities such as the [Code Sandbox](/core-concepts/agent_sandbox_and_secrets) and the [agent browser](/core-concepts/agent_browser#how-is-the-browser-billed) have no per-call charge. The time they spend running is billed as **Compute**, and what the model reads from them as **Chat & Reasoning**.
</Accordion>
<Accordion title="Compute — active processing time only" icon="clock">
5 credits per session-minute of active processing, with a minimum of 1 credit per response.
Waiting on you to reply costs nothing — only the time the agent spends working counts. Enterprise customers running Gumloop in their own [VPC](/enterprise-features/static_egress_ips) are not charged for compute at all, since it runs on their infrastructure.
</Accordion>
<Accordion title="Orchestration Fee — 8% of the rest of the run" icon="percent">
```text theme={"dark"}
Orchestration Fee = 8% x (Chat & Reasoning + Compute + Tool Calls)
```
A chat that spent 400 credits on Chat & Reasoning, 10 on Compute, and 15 on Tool Calls pays a 34 credit fee (8% of 425, rounded up), for 459 credits in total.
Enterprise plans can negotiate a different orchestration fee. If your organization has a negotiated rate, that rate applies instead of the 8% default everywhere it appears on this page.
</Accordion>
</AccordionGroup>
### Example: researching a lead
You ask an agent to research a sales lead with Apollo, then summarize whether they are a good fit:
| What the agent does | Credit type |
| - | - |
| Pulls the lead's data with [Apollo](https://www.gumloop.com/mcp/apollo) enrichment | **Tool Call** — 1 credit plus Apollo's enrichment charge |
| Reads that data and writes the summary | **Chat & Reasoning** — your model's tokens |
| Spends \~40 seconds of active processing | **Compute** — 3 credits |
| The run itself | **Orchestration Fee** — 8% of the three above |
Had the agent only read a [Google Sheet](https://www.gumloop.com/mcp/gsheets) and summarized it, the tool side would be just the 1 base credit, since Google Sheets charges nothing extra.
<Tip>To lower this chat's cost, run the agent on a cheaper model or add your own API key (BYOK). Both reduce the Chat & Reasoning portion. The Apollo charge stays the same, since it is a third-party cost passed straight through.</Tip>
## Plans and included credits
| Plan | Price | Included credits |
| - | - | - |
| **Pro** | \$37 / month | **20,000 credits / month** — 7,400 credits at the \$0.005 list price, plus 12,600 bonus credits |
| **Enterprise** | Custom | Custom, and unused credits **roll over** |
Every new account starts with a **14-day free trial of Pro**. The trial requires a card, is a one-time offer per customer, and rolls into a paid Pro subscription when it ends unless you cancel first.
To cancel a trial or a paid plan, open **Manage Subscription** on your [Usage & Limits page](https://www.gumloop.com/settings/organization/limits) (Settings > Organization > Usage & Limits) — see [Subscription Management](/core-concepts/subscription_management). Cancelling during the trial stops the card from being charged when the trial ends.
<Warning>**Credits don't roll over** month to month, except on Enterprise plans.</Warning>
### Running out of credits
Enable **credit overage** on your [Usage & Limits page](https://www.gumloop.com/settings/organization/limits) to keep running past your monthly credits, billed at **\$0.005 per credit**.
**Pro overage is always capped.** The default ceiling is **1,000,000 overage credits per billing period** (\$5,000), and you can set a lower cap on that page. Agents stop once the cap is reached, so overage can never run away unbounded. Enterprise plans set their own cap, or can choose to run uncapped.
Need consistently more? Upgrade from the [pricing page](https://www.gumloop.com/pricing) or [talk to us about Enterprise](https://www.gumloop.com/contact).
### Billing questions
For anything about the money side of your account — invoices, receipts, payment methods, purchase orders and procurement paperwork, tax or VAT details, or a charge you do not recognize — email [accounting@gumloop.com](mailto:accounting@gumloop.com).
Self-serve invoice downloads are available in the billing portal; see [Subscription Management](/core-concepts/subscription_management).
<Note>Enterprise billing — custom credit allocations, negotiated rates, annual invoicing — goes to the same address. For product or technical issues, use [support@gumloop.com](mailto:support@gumloop.com) or [open a ticket](https://portal.usepylon.com/gumloop/forms/help) instead.</Note>
## Where to see what a chat cost
The running cost of a conversation appears next to the chat's name in the **chat header** and updates live.
For the full breakdown, select that credit count to open the chat's details drawer. Alongside the chat's source, trigger, creation time, models, and participants, it lists one row per credit type the chat was actually charged for — **Chat & Reasoning**, **Tool Calls**, **Compute**, **Orchestration Fee**, **Brain** ([Brain searches](/core-concepts/brain#credits) the agent ran), **Evaluation & Self-Improvement**, **Voice** (time spent on a [Talk mode](/core-concepts/talk_mode) call), **Flows**, **Subagents**, or **Other**.
<Note>Credits that were waived rather than charged (BYOK model calls, and compute for VPC organizations) still appear, struck through and labelled **Free**, so you can see what the run would have cost.</Note>
<Frame>
<img alt="Chat details drawer opened from the credit count in the chat header, showing source, created time, model, participants, and a credit breakdown by type" />
</Frame>
## Tracking usage over time
<AccordionGroup>
<Accordion title="Insights dashboard" icon="chart-line">
The [Insights dashboard](https://www.gumloop.com/settings/organization/insights) (Settings > Organization > Insights) is the best place to see credit spend across all your agents. It shows total credits spent for the selected period, a credit spend and volume chart, and leaderboards of your top agents and models.
The tabs let you dig deeper: **Models** breaks spend down by AI model, and **Credit Explorer** lets you slice usage.
<Note>The Insights dashboard is an **Enterprise** feature.</Note>
<Frame>
<img alt="Insights dashboard showing total credits spent, a credit spend and volume chart, and leaderboards for top agents and models" />
</Frame>
</Accordion>
<Accordion title="Credit logs" icon="table-list">
For a transaction-level view, open [Settings > Profile > Usage & Limits](https://www.gumloop.com/settings/profile/usage-limits):
* **Grouped view** (default): one row per agent conversation, showing its total. Expand a row to see the individual charges inside it.
* **Detailed view**: one row per individual charge, with the exact type and amount.
Filter by category to focus on **Agent Chats**. Many rows include a **View** link that jumps to the source conversation. Organization admins and managers can see usage across all users at [Settings > Organization > Usage & Limits](https://www.gumloop.com/settings/organization/limits), which adds a **User** column.
</Accordion>
<Accordion title="Ask the analytics agent" icon="message-question">
You can also ask about credit usage in plain language. The [analytics agent](/enterprise-features/organization_insights) answers questions like "how many credits did we spend in the last 30 days, broken down by user?" and returns tables, charts, or CSV exports. It is available on the Insights page (Settings > Organization > Insights) and in Slack.
</Accordion>
<Accordion title="Export" icon="file-csv">
Export credit logs as CSV from [Settings > Organization > Data Export](https://www.gumloop.com/settings/organization/data_export) for external analysis or compliance.
</Accordion>
</AccordionGroup>
## Reducing credit costs
* **Pick the right model.** Start with the **Recommended** preset in the model dropdown on the **Agent** tab. Use **Auto** when message difficulty varies, and only reach for **Smartest** when a task needs deep reasoning. See [AI Models](/core-concepts/ai_models).
* **Bring your own key (BYOK).** Run model calls on your own provider key and the **Chat & Reasoning** portion drops to **0 credits** (Pro plan or higher).
* **Start fresh conversations.** A new chat for a new topic avoids carrying old context that inflates token costs.
* **Stay inside the short context window.** GPT-5.6 and Grok 4.6/4.7 charge higher long-context rates once a request's input tokens pass the short-window boundary (272K and 200K), and the higher rates apply to the whole request. Picking the smaller **Context Window** in [AI Advanced Settings](/core-concepts/agents#context-window) keeps chats on those models under the boundary.
* **Connect only the tools you need.** Every tool definition adds tokens to the prompt.
<Accordion title="How BYOK works" icon="key">
Gumloop runs your model calls on your key and **charges you 0 credits for them** — you pay your provider directly for the tokens instead.
| | With BYOK |
| - | - |
| Chat & Reasoning (agents) | **0 credits** — shown struck through and labelled Free in the chat's credit breakdown |
| Image generation and transcription | **0 credits** |
| Tool Calls and Compute | Charged as usual |
| Orchestration Fee (agents) | **16% instead of 8%** |
Because the model spend leaves your credit balance entirely, agent chats on BYOK carry a **16% orchestration fee instead of 8%** (your Enterprise rate plus 8 points, if you have one), calculated on what the run would have been worth.
In practice BYOK is still far cheaper. Taking the chat from the example above — 400 credits of model usage, 10 of compute, 15 of tool calls:
| | Standard | With BYOK |
| - | - | - |
| Chat & Reasoning | 400 | 0 |
| Compute + Tool Calls | 25 | 25 |
| Orchestration Fee | 34 (8%) | 68 (16%) |
| **Total credits** | **459** | **93** |
You cover the model tokens directly with your provider instead.
Requires Pro plan or higher and your own OpenAI, Anthropic, Google AI, Perplexity, SpaceXAI, or Fireworks AI account. Each key only waives the models that provider serves — a Fireworks key covers the open models Gumloop runs on Fireworks (DeepSeek V4.1 Flash, DeepSeek V4 Flash and Pro, Kimi K3, Kimi K2.7 Code, GLM-5.3, GLM-5.2, MiniMax M3, Qwen3.8 Max).
Add a key from your personal [Connectors](https://www.gumloop.com/settings/profile/connectors?view=connected), or add a **shared team key** for the whole team. Enterprise admins can set organization-level keys. See [AI Models](/core-concepts/ai_models#bring-your-own-key-byok).
</Accordion>
## Credit notification preferences
Gumloop can email you when your organization's credit usage crosses key thresholds. Manage these on your [Usage & Limits page](https://www.gumloop.com/settings/organization/limits).
* **Out of Credits Notification**: an email when credits reach zero. On by default.
* **Credit Usage Notifications**: an email when usage crosses a threshold. Defaults to **75%** and **90%**. Add, remove, or reset thresholds as needed.
<Frame>
<img alt="Credit Notification Preferences showing Out of Credits Notification toggle and Credit Usage Notifications with configurable thresholds at 75% and 90%" />
</Frame>
<Tip>Set these up early so you have time to top up before running out.</Tip>
### Per-chat credit warnings
Admins and Security role holders can also set **per-chat credit warnings** through [Custom Roles](/enterprise-features/user_groups#per-chat-credit-warnings). When a single chat's spend crosses a configured threshold (e.g. 5,000 or 10,000 credits), the agent pauses and creates an [Action Request](/core-concepts/human_in_the_loop) for approval before continuing, so no single conversation can consume an unexpected amount of credits.
## Voice call costs
Talking to an agent in [Talk mode](/core-concepts/talk_mode) is billed **by call time**, not by tokens. The voice model, **GPT Live**, costs about **10 credits per minute of call time**, prorated by the seconds you actually talk. The charge accumulates as the call runs rather than landing in one lump at the end, and it appears as **Voice** in the chat's credit breakdown.
* A call needs credits for the **minute ahead**, so it starts only if you can cover the first minute and ends if your balance runs out mid-conversation.
* Anything the agent does while you talk — tool calls, its own thinking, compute — is billed as usual, on top of the call time.
* Voice minutes run on Gumloop's OpenAI key, so [BYOK](#how-byok-works) waivers for your own provider keys apply to them the same way they apply to other model calls.
## Interactive artifact costs
When you open an [interactive artifact](/core-concepts/agent_artifacts#interactive-artifacts-live-data) that pulls live data, a Python script runs in a secure sandbox. This is billed at roughly **1 credit per 55 seconds** of runtime, with a minimum of 1 credit per run. The **viewer** pays, not the creator. Most scripts finish in seconds, so the typical cost is 1 credit per load.
***
## Learn more
<CardGroup>
<Card title="AI models" icon="microchip" href="/core-concepts/ai_models">
Choose the right model and set up BYOK
</Card>
<Card title="Pricing plans" icon="tag" href="https://www.gumloop.com/pricing">
Current plans, included credits, and overage
</Card>
<Card title="Billing questions" icon="envelope" href="mailto:accounting@gumloop.com">
Email [accounting@gumloop.com](mailto:accounting@gumloop.com) about invoices, payment, and procurement
</Card>
</CardGroup>
# Custom Slack App Integration
Source: https://docs.gumloop.com/core-concepts/custom_slack_app
<div>
<iframe title="Custom Slack App Integration" />
</div>
Connect your own Slack app to an agent for custom branding, dedicated bot identity, and advanced enterprise deployments.
<Info>
**This is an advanced feature.** For most users, we recommend using the [standard Gumloop Slack integration](https://docs.gumloop.com/core-concepts/agents_slack), which is simpler to set up and works great for the majority of use cases. Only use a custom Slack app if you have specific requirements for branding, multiple agents, or enterprise compliance.
</Info>
## When to use a Custom Slack App
The standard Gumloop integration (`@Gumloop`) is the fastest way to get agents into Slack—it works out of the box with minimal setup. However, there are scenarios where connecting your own custom Slack app makes sense:
<CardGroup>
<Card title="Custom branding" icon="palette">
Give your agent a unique name and avatar that reflects its purpose—like "Sales Assistant" or "Support Bot" instead of "@Gumloop"
</Card>
<Card title="Multiple agents, same workspace" icon="users">
Run multiple agents with distinct identities in the same Slack workspace without confusion
</Card>
<Card title="Enterprise compliance" icon="building">
Meet IT security policies that require all Slack integrations to be owned and managed internally
</Card>
<Card title="White-label solutions" icon="tag">
Build products or services with AI agents that appear under your brand, not Gumloop's
</Card>
</CardGroup>
### Standard integration vs Custom Slack App
| Aspect | Standard Integration | Custom Slack App |
| - | - | - |
| **Bot Identity** | @Gumloop (shared) | Your custom name & avatar |
| **Setup Complexity** | Simple (minutes) | Advanced (10-15 minutes) |
| **Block Kit Messages & Buttons** | Yes, through the Slack connector | Yes, through the Slack connector |
| **Slash Commands** | Yes: `/gummie add`, `/gummie remove`, and more | Not supported |
| **Direct Messages (DMs)** | Supported, but always answered by your personal [Gumball](/core-concepts/gumball#gumball-in-slack) — custom agents are channels only | Supported, answered by the connected agent |
| **Scope** | Per channel | Per custom app (works across all channels) |
| **Multiple Agents** | One per channel | One per custom app |
| **Best For** | Most users | Enterprise, white-label, multi-agent setups |
<Tip>
**Start with the [standard integration first](https://docs.gumloop.com/core-concepts/agents_slack).** If you find you need custom branding or multiple agents later, you can always add a custom Slack app.
</Tip>
***
## Prerequisites
Before setting up a custom Slack app, ensure you have:
<Tabs>
<Tab title="Slack requirements" icon="slack">
* Admin access to your Slack workspace (to create and install apps)
* Permission to create Slack apps at [api.slack.com](https://api.slack.com/apps)
</Tab>
<Tab title="Gumloop requirements" icon="circle-check">
* An existing agent created in Gumloop
</Tab>
</Tabs>
***
## Setup options
Gumloop offers two ways to connect a custom Slack app to your agent:
<Tabs>
<Tab title="New app (recommended)" icon="wand-magic-sparkles">
**Best for:** Users who don't have an existing Slack app and want the fastest setup experience.
Gumloop provides a pre-configured manifest that automatically sets up all the required permissions and event subscriptions for you. This is the easiest path.
</Tab>
<Tab title="Existing app" icon="plug">
**Best for:** Users who already have a Slack app created or need specific configurations not covered by the manifest.
Connect an existing Slack app by providing its Client ID, Client Secret, and Signing Secret from Slack's API dashboard.
</Tab>
</Tabs>
***
## Option 1: Create a new app (recommended)
This guided workflow walks you through creating a new Slack app with all the correct settings pre-configured.
<Steps>
<Step title="Open Channels → Slack">
Open **Channels** in the agent sidebar, select **Slack**, then click **Add Slack bot**. Connecting or disconnecting Slack bots requires Owner access. Choose the custom app option.
</Step>
<Step title="Name your bot">
This is how the bot appears in Slack and how people @mention it.
* **Name**: display name (for example `Support`)
* **Handle**: the @mention (for example `@Support`)
* **Description**: what the bot does
<Frame>
<img alt="Name your bot sheet with Name, Handle, and Description fields" />
</Frame>
</Step>
<Step title="Create it in Slack">
Slack opens with the manifest already filled in. Click **Create**, pick a workspace, review the summary, then create the app. Come back and click **I created the app**.
<Frame>
<img alt="Create it in Slack sheet with Create button, manifest.json, and workspace picker" />
</Frame>
</Step>
<Step title="Enter app credentials">
Copy these from **Basic Information** in your Slack app's settings:
* **Client ID**
* **Client Secret**
* **Signing Secret**
<Frame>
<img alt="App credentials sheet with Client ID, Client Secret, Signing Secret, and Authorize" />
</Frame>
<Warning>Never share your Client Secret or Signing Secret publicly. Treat them like passwords.</Warning>
Click **Authorize** to install the bot.
</Step>
<Step title="Ensure Slack app is installed to the workspace">
Make sure your Slack app is installed to your workspace. If you skipped this step earlier, go to your Slack app settings → **OAuth & Permissions** → **Install to Workspace**.
<Frame>
<img alt="Install Custom Slack App" />
</Frame>
</Step>
<Step title="Invite your bot to channels">
Your custom bot needs to be invited to channels where you want it to work.
In Slack, go to each channel and type:
```text theme={"dark"}
/invite @YourBotName
```
Replace `@YourBotName` with the App Tag you configured (e.g., `@salesassistant`).
<Frame>
<img alt="Slack channel showing bot being invited with /invite command" />
</Frame>
Your custom Slack app agent is now ready! @mention your bot in a channel, or [send it a direct message](#direct-messages-dms), to start a conversation.
</Step>
</Steps>
<Note>
**Already connected a custom Slack app before direct messages were supported?** Existing apps won't receive DMs until you update them. See [Enabling DMs on an already-connected app](#enabling-dms-on-an-already-connected-app).
</Note>
***
## Option 2: Connect an existing app
If you already have a Slack app or need custom configurations, you can connect it directly to Gumloop.
<Steps>
<Step title="Open Channels → Slack">
Open **Channels** in the agent sidebar, select **Slack**, then click **Add Slack bot**. Choose the custom app option, then **Existing App**.
</Step>
<Step title="Choose Existing App">
Select **Existing App** to connect a Slack app you've already created.
</Step>
<Step title="Configure your Slack app (if not already done)">
Before connecting, ensure your existing Slack app has the required configuration:
<AccordionGroup>
<Accordion title="Required bot token scopes" icon="key">
In your Slack app settings, go to **OAuth & Permissions** and add these scopes:
| Scope | Purpose |
| - | - |
| `app_mentions:read` | Receive @mentions of your bot |
| `channels:history` | Read messages in public channels |
| `channels:read` | List available channels |
| `chat:write` | Send messages as your bot |
| `groups:history` | Read messages in private channels |
| `groups:read` | List private channels |
| `im:history` | Read direct messages sent to your bot |
| `im:read` | Detect direct message channels (required for DMs) |
| `im:write` | Open direct message channels to reply |
| `users:read` | Look up user information |
| `users:read.email` | Match Slack users to Gumloop accounts |
| `files:read` | Access file attachments |
| `files:write` | Attach generated files/images to messages |
| `reactions:write` | Add emoji reactions to messages |
<Tip>The `im:history`, `im:read`, and `im:write` scopes are what allow users to **direct message** your bot. If you leave them out, DMs won't reach your agent.</Tip>
Optionally, add `assistant:write` to have your bot appear in Slack's **agents & assistants** dropdown (top right of the Slack client). It isn't required for DMs or mentions to work—see [Enabling DMs on an already-connected app](#enabling-dms-on-an-already-connected-app).
</Accordion>
<Accordion title="Required event subscriptions" icon="bell">
In your Slack app settings, go to **Event Subscriptions**:
1. Toggle **"Enable Events"** to ON
2. Set the **Request URL** to:
```text theme={"dark"}
https://api.gumloop.com/api/v1/external/slack/events
```
3. Wait for verification (green checkmark)
4. Under **"Subscribe to bot events"**, add:
* `app_mention`
* `message.channels`
* `message.groups` (for private channels)
* `message.im` (for direct messages)
* `agent_session_stopped` (for Slack's [Stop button](#stopping-a-response))
* `app_context_changed` (to share [what the user has open in Slack](#what-the-user-has-open-in-slack))
5. Save changes
</Accordion>
<Accordion title="Required App Home configuration (for DMs)" icon="comment">
To let users **direct message** your bot, you must expose the writable Messages tab. In your Slack app settings, go to **Features → App Home**:
1. Under **Show Tabs**, enable the **Messages Tab**.
2. Check **"Allow users to send Slash commands and messages from the messages tab"**.
<Frame>
<img alt="Slack App Home settings with the Messages Tab enabled and the 'Allow users to send Slash commands and messages from the messages tab' checkbox selected" />
</Frame>
Without this, Slack hides the message box in your bot's DM view and users can't message it directly.
</Accordion>
<Accordion title="Required interactivity configuration" icon="hand-pointer">
In your Slack app settings, go to **Interactivity & Shortcuts**:
1. Toggle **"Interactivity"** to ON
2. Set the **Request URL** to:
```text theme={"dark"}
https://api.gumloop.com/api/v1/external/slack/interactive
```
3. Save changes
This enables your custom Slack app to handle interactive components like button clicks, modal submissions, and form responses from your agent.
</Accordion>
<Accordion title="Install to Workspace" icon="download">
Go to **OAuth & Permissions** and click **"Install to Workspace"** if you haven't already. Authorize the app when prompted.
</Accordion>
</AccordionGroup>
</Step>
<Step title="Enter your app credentials">
Provide the credentials from your Slack app's **Basic Information** page:
<Frame>
<img alt="Credential entry form requesting Client ID, Client Secret, and Signing Secret" />
</Frame>
* **Client ID** — Found under "App Credentials"
* **Client Secret** — Click "Show" to reveal, then copy
* **Signing Secret** — Click "Show" to reveal, then copy
Click **"Connect to Slack"** to complete the OAuth flow.
</Step>
<Step title="Assign to your agent and invite to channels">
Select your custom Slack app credential from the dropdown and click **"Add"**.
Then invite your bot to channels in Slack:
```text theme={"dark"}
/invite @YourBotName
```
</Step>
</Steps>
***
## Enabling DMs on an already-connected app
Direct message support was added after custom Slack apps first launched. If you connected your custom app **before** DMs were available, the missing piece is the App Home **Messages tab**—without it, Slack hides the message box so users can't DM your bot. The `message.im` event subscription and the `im:*` scopes were already part of Gumloop's manifest, so apps created with the **New App** flow already have them and there's nothing new to add.
Enable DMs with the one-time steps below.
<Steps>
<Step title="Enable the App Home Messages tab">
In your Slack app settings at [api.slack.com/apps](https://api.slack.com/apps), go to **Features → App Home** and, under **Show Tabs**:
1. Enable the **Messages Tab**.
2. Check **"Allow users to send Slash commands and messages from the messages tab"**.
<Frame>
<img alt="Slack App Home settings with the Messages Tab enabled and the 'Allow users to send Slash commands and messages from the messages tab' checkbox selected" />
</Frame>
</Step>
<Step title="Reinstall the app to your workspace">
Go to **Settings → Install App** (or **OAuth & Permissions**) and click **"Reinstall to Workspace"**, then authorize when prompted. This applies the App Home change so DMs start reaching your agent.
<Frame>
<img alt="Slack Install App settings showing the Bot User OAuth Token and the Reinstall to Workspace button" />
</Frame>
<Note>You don't need to reconnect the credential in Gumloop. Your existing credential already has the scopes required to send DMs (`chat:write` and `im:write`), so once the Messages tab is enabled and the app is reinstalled, DMs work without re-authorizing.</Note>
</Step>
<Step title="(Existing apps only) Verify the DM event and scopes">
If you connected an **existing app** you built yourself—rather than using Gumloop's **New App** manifest—confirm it's configured for DMs:
* **Event Subscriptions → Subscribe to bot events** includes `message.im`.
* **OAuth & Permissions → Bot Token Scopes** includes `im:history`, `im:read`, and `im:write`.
If you add any of these, reinstall the app again so the changes take effect. Apps created with Gumloop's **New App** manifest already have all of this.
</Step>
<Step title="(Optional) Add the assistant:write scope to show your bot in Slack's agents list">
Slack only lists an app in the **agents & assistants** dropdown (the icon in the top right of the Slack client) if the app has the `assistant:write` bot scope. This scope is **not** part of Gumloop's **New App** manifest, so apps created or re-created from the manifest lose their spot in that list until you add it back.
To add it, go to **OAuth & Permissions → Bot Token Scopes**, add `assistant:write`, then reinstall the app to your workspace.
<Frame>
<img alt="Slack Agents dropdown listing custom Slack app bots" />
</Frame>
<Note>`assistant:write` is optional—DMs work without it. It only controls whether your bot appears in Slack's agents & assistants dropdown as a shortcut for starting a DM.</Note>
</Step>
</Steps>
***
## Adding newer Slack events to an existing app
Gumloop's **New App** manifest subscribes to two Slack events that older apps may not have:
| Event | What it enables |
| - | - |
| `agent_session_stopped` | The [Stop button](#stopping-a-response) on the agent's **Working…** indicator |
| `app_context_changed` | Tells the agent [what the user has open in Slack](#what-the-user-has-open-in-slack) when they DM it |
Without them, your agent works as before: there's no Stop button (use `!stop` instead), and DMs don't include what the user has open.
<Steps>
<Step title="Open Event Subscriptions">
In your Slack app settings at [api.slack.com/apps](https://api.slack.com/apps), go to **Event Subscriptions**.
</Step>
<Step title="Add the bot events">
Under **Subscribe to bot events**, add `agent_session_stopped` and `app_context_changed`.
</Step>
<Step title="Save">
Click **Save Changes**. If Slack asks you to reinstall the app, reinstall it to your workspace.
</Step>
</Steps>
***
## Using your Custom Slack App agent
Once set up, interacting with your custom Slack app agent works similarly to the standard Gumloop integration, with a few key differences.
### Starting a conversation
@mention your custom bot in any channel where it's been invited:
```text theme={"dark"}
@YourBotName What are the latest support tickets?
```
<Frame>
<img alt="Interaction with Custom Slack App" />
</Frame>
The agent will:
1. Process your request using its configured tools
2. Respond in a thread to keep conversations organized
3. Continue the conversation within the thread based on your agent's settings
<Tip>**Thread commands work here too!** Type `!stop` to stop the agent's response, or `!link` to get a link to view the conversation in Gumloop.</Tip>
### Stopping a response
Apps with the `assistant:write` scope show Slack's **Working…** indicator while the agent works. Without that scope, the agent reacts to your message with emoji instead. When the app is also subscribed to the `agent_session_stopped` event, Slack adds a **Stop** button to the **Working…** indicator. Clicking it stops the agent's current run, and the agent's message reads *This response was stopped.* If the agent had not posted anything yet, it replies *Stopped this chat.* instead.
Only your app's agent stops. Other agents replying in the same thread keep running.
<Note>Apps created with Gumloop's **New App** manifest include `agent_session_stopped`. Apps created before it was added, and existing apps you connected yourself, need it added by hand. See [Adding newer Slack events to an existing app](#adding-newer-slack-events-to-an-existing-app). `!stop` works either way.</Note>
### Direct messages (DMs)
Your custom bot can also be messaged directly—no channel or @mention required. Open a DM with your bot from the Slack sidebar (or the **Messages** tab on the app's profile) and just start typing:
```text theme={"dark"}
What are the latest support tickets?
```
Each top-level message you send starts a new conversation; reply within that message's thread to continue the same conversation.
#### What the User has open in Slack
When your app is subscribed to the `app_context_changed` event, Slack attaches what the user has open (a channel, thread, canvas, or list) to the DMs they send your bot. The agent can then act on requests like "summarize this thread" or "read the sales data in this canvas" without being given a link or ID.
* This applies to **DMs only**. Messages in channel threads don't carry it.
* The agent uses its Slack tools to read what's open. Reading a **list** also requires the `lists:read` scope on the Slack connector the agent uses.
<Note>A custom Slack app is the only way to DM a **custom** agent. DMs to the standard Gumloop app also work, but they always reach your personal [Gumball](/core-concepts/gumball#gumball-in-slack), and custom agents on that app stay in public and private channels.</Note>
<Info>
DMs require the App Home **Messages tab** to be enabled and the `im:history`, `im:read`, and `im:write` scopes to be granted. Apps created with Gumloop's **New App** manifest have this configured automatically. If you connected an **existing app**—or linked a custom app before DM support shipped—follow [Enabling DMs on an already-connected app](#enabling-dms-on-an-already-connected-app).
</Info>
### Interactive features
Custom Slack apps support the same interactive messages as the standard Gumloop integration:
* **Gumloop's buttons and forms**: approval buttons, connect prompts, browser handoff forms, and other buttons and modals Gumloop posts in the thread work the same way, under your app's name.
* **Block Kit messages from the agent**: with the **Slack** connector on the agent, it can post Block Kit messages with sections, images, and buttons. See [Rich messages and buttons](/core-concepts/agents_slack#rich-messages-and-buttons-block-kit). The standard @Gumloop bot can do this too, so you don't need a custom app just for Block Kit.
Link buttons (buttons with a `url`) open their link. Clicks on other buttons in messages the agent builds aren't sent back to the agent.
<Info>Interactive features require the **Interactivity Request URL** to be configured. If you used Gumloop's manifest to create your app, this is already set up. For existing apps, see the [Interactivity configuration step](#option-2-connect-an-existing-app) above.</Info>
### Key differences from standard integration
<AccordionGroup>
<Accordion title="No slash commands" icon="terminal">
Custom Slack apps don't support `/gummie` slash commands. You cannot use:
* `/gummie add` — Bot is added by inviting to channels instead
* `/gummie remove` — Remove bot by kicking from channels
* `/gummie active` — You know which bot is in a channel by its name
* `/gummie help` — Not available
**To manage your custom app agent:**
* Add to channels: `/invite @YourBotName`
* Remove from channels: `/kick @YourBotName` or remove via channel settings
</Accordion>
<Accordion title="Works across all channels" icon="arrows-left-right">
Unlike the standard integration which is channel-specific, your custom Slack app works in **any channel where it's invited**. You don't need to "add" the agent to each channel—just invite the bot.
</Accordion>
<Accordion title="Distinct bot identity" icon="user">
Your agent appears with whatever name and avatar you configured in Slack's app settings. Team members interact with `@YourBotName` instead of `@Gumloop`.
</Accordion>
</AccordionGroup>
### Slack preferences
All the same Slack preferences available for standard agents apply to custom Slack apps:
* **Thread Replies**: Choose **Auto** (default), **Only on mentions**, or **On all messages**. See [Thread Replies](/core-concepts/agents_slack#thread-replies)
* **Slack Attribution Stamp**: Show or hide the agent name and **View conversation** link under each reply. See [Slack Attribution Stamp](/core-concepts/agents_slack#slack-attribution-stamp)
* **Show Detailed Steps**: List each step on the progress card, or show only a short status. See [Show Detailed Steps](/core-concepts/agents_slack#show-detailed-steps)
Configure these on **Channels → Slack**.
<Frame>
<img alt="Slack preferences settings panel" />
</Frame>
## Choosing which bot the agent acts as
If an agent has more than one custom Slack app connected — say a workspace bot and a white-labeled "Sales Assistant" — you can pick which one it acts as when it uses Slack tools on its own.
Open your agent, go to **Connectors**, and click the **Slack** app. Under **Account** you'll find a **Bot Account** selector:
<Frame>
<img alt="Slack tool settings in an agent showing the Account selector and the Bot Account dropdown with Gumloop Bot selected and a custom Slack app listed below it" />
</Frame>
* **Gumloop Bot** (the default) — the agent's Slack tool calls go out as Gumloop's bot.
* **Any custom Slack app connected to this agent** — listed by the name you gave the credential. Pick one and its bot becomes the identity the agent acts as.
Only one bot account can be selected at a time, and the change saves immediately. You need edit access to the agent to change it.
<Note>
**When the agent is talking to you in Slack, the app you messaged always wins.** If someone @mentions your custom bot or DMs it, the agent replies as that app regardless of the Bot Account setting. The setting decides which bot to use when there's no inbound Slack app to infer it from — for example a scheduled run, a trigger, or a chat in Gumloop that calls a Slack tool.
</Note>
<Info>
**Account vs Bot Account.** The **Account** selector above it controls which connected Slack *account's* credentials the agent uses for tool calls. **Bot Account** controls which *bot identity* it acts as. The Bot Account selector only appears for Slack, and only once at least one custom Slack app credential is connected to the agent.
</Info>
Publicly shared agents don't use a default bot account, so anonymous users of a public agent never act as your organization's bot.
***
## Credential ownership options
When creating your custom Slack app credential, you can choose who has access:
| Credential Type | Who Can Use It | Best For |
| - | - | - |
| **Personal** | Only you | Testing, personal projects |
| **Team** | All team members | Team-shared agents |
| **Organization** | All organization members | Enterprise-wide deployments |
***
## Troubleshooting
<AccordionGroup>
<Accordion title="Bot doesn't respond to messages" icon="circle-exclamation">
**Check these items:**
* **Is the Slack app installed to your workspace?** This is the most common issue. Go to your Slack app settings → **OAuth & Permissions** → **Install to Workspace**.
<Frame>
<img alt="Install Custom Slack App to Workspace" />
</Frame>
* Is the bot invited to the channel? (`/invite @YourBotName`)
* Did you @mention the bot in your message?
* Are the event subscriptions configured correctly in Slack?
* Is the webhook URL verified? (`https://api.gumloop.com/api/v1/external/slack/events`)
* Is the credential properly assigned to your agent in Gumloop?
* Does the user have a Gumloop account with matching email?
</Accordion>
<Accordion title="Bot doesn't respond to direct messages (DMs)" icon="comment">
**Check these items:**
* **Is the App Home Messages tab enabled?** Go to your Slack app settings → **Features → App Home** → enable the **Messages Tab** and check **"Allow users to send Slash commands and messages from the messages tab"**.
* Is `message.im` subscribed under **Event Subscriptions → Subscribe to bot events**?
* Are the `im:history`, `im:read`, and `im:write` scopes granted under **OAuth & Permissions**?
* **Did you connect this app before DM support shipped?** The App Home Messages tab was added to the manifest later, so older apps have it disabled. Enable the Messages tab and reinstall the app—no need to reconnect the credential in Gumloop. See [Enabling DMs on an already-connected app](#enabling-dms-on-an-already-connected-app).
</Accordion>
<Accordion title="No Stop button while the agent is working" icon="circle-stop">
Slack only shows the **Stop** button on the **Working…** indicator, which needs the `assistant:write` scope, and only for apps subscribed to the `agent_session_stopped` event. Add the event under **Event Subscriptions → Subscribe to bot events**, and the scope under **OAuth & Permissions → Bot Token Scopes**, then reinstall the app. See [Adding newer Slack events to an existing app](#adding-newer-slack-events-to-an-existing-app). Until then, type `!stop` in the thread to stop the agent.
</Accordion>
<Accordion title="Bot works in some channels but not others" icon="hashtag">
**Check:**
* Is the bot invited to the non-working channels?
* For private channels, do you have `groups:history` and `groups:read` scopes configured?
* Is there a different agent assigned via the standard integration in that channel?
</Accordion>
<Accordion title="Webhook URL verification fails in Slack" icon="globe">
The URL `https://api.gumloop.com/api/v1/external/slack/events` should verify automatically.
**If it fails:**
* Check for typos in the URL
* Ensure you're using HTTPS (not HTTP)
* Try again after a few minutes (temporary network issues)
* Contact Gumloop support if the issue persists
</Accordion>
<Accordion title="Buttons or modals not working" icon="hand-pointer">
If interactive components (buttons, modals, form submissions) are not working:
* **Is Interactivity enabled?** Go to your Slack app settings → **Interactivity & Shortcuts** → ensure the toggle is ON
* **Is the Request URL correct?** It should be set to `https://api.gumloop.com/api/v1/external/slack/interactive`
* **Is the Signing Secret correct?** Gumloop uses your app's Signing Secret to verify interactive payloads. Re-check the value in **Basic Information** → **App Credentials**
* **Did you use the manifest?** If you created your app using Gumloop's manifest, interactivity is pre-configured. If you connected an existing app, you may need to add this manually.
</Accordion>
<Accordion title="Can't find credentials in Slack" icon="magnifying-glass">
In your Slack app at [api.slack.com/apps](https://api.slack.com/apps):
* **Client ID, Client Secret, Signing Secret**: Found in **Basic Information** → **App Credentials**
* Click "Show" next to each secret to reveal it, then copy
</Accordion>
</AccordionGroup>
***
## Important limitations
<CardGroup>
<Card title="One agent per custom app" icon="1">
Each custom Slack app credential can only be assigned to one Gummie agent. Create separate Slack apps for each agent you need.
</Card>
<Card title="No slash commands" icon="terminal">
Custom Slack apps don't support `/gummie` commands. Manage your bot by inviting/removing it from channels directly.
</Card>
<Card title="Credential exclusivity" icon="lock">
A custom Slack app credential cannot be shared between multiple agents. Assigning it to a second agent removes it from the first.
</Card>
<Card title="Manual channel management" icon="hand">
Unlike the standard integration, you must manually invite your custom bot to each channel where you want it to work.
</Card>
</CardGroup>
***
## Security considerations
<AccordionGroup>
<Accordion title="Credential protection" icon="shield">
Your Slack app's Client Secret and Signing Secret are stored securely in Gumloop and used to verify that incoming webhooks and interactive payloads are actually from Slack. Both event callbacks and interactive component actions (button clicks, modal submissions) are verified using your app's Signing Secret before processing. Never share these secrets or expose them in logs.
</Accordion>
<Accordion title="User matching" icon="users">
Users must have matching email addresses in Slack and Gumloop for the integration to work. This ensures proper authentication and prevents unauthorized access.
</Accordion>
<Accordion title="Permission verification" icon="check-double">
Before processing messages, Gumloop verifies:
* The user has a valid Gumloop account
* The user has permission to access the agent
* For team agents, team membership is verified
</Accordion>
</AccordionGroup>
***
## FAQ
<AccordionGroup>
<Accordion title="Can I use both the standard @Gumloop bot and a custom app in the same workspace?">
Yes! They operate independently. The standard bot uses channel-based mapping with `/gummie` commands, while custom apps use bot-based mapping with direct invites. You can have both active in different channels.
</Accordion>
<Accordion title="What's the difference between New App and Existing App setup?">
**New App** uses a pre-configured manifest that automatically sets up all required permissions and events—it's faster and less error-prone. **Existing App** lets you connect a Slack app you've already created, but you're responsible for ensuring all scopes and events are configured correctly.
</Accordion>
<Accordion title="What happens if I delete my custom Slack app in Slack?">
The credential in Gumloop will stop working immediately. You'll need to create a new app and set it up again.
</Accordion>
<Accordion title="How do I update my bot's name or avatar?">
Update these in your Slack app settings at [api.slack.com/apps](https://api.slack.com/apps). Changes will reflect in Slack automatically—no changes needed in Gumloop.
</Accordion>
<Accordion title="Can I have multiple custom apps assigned to one agent?">
Yes! This is useful when you want the same agent available in multiple Slack workspaces. Each workspace installation creates a separate credential, and you can assign all of them to a single agent.
</Accordion>
</AccordionGroup>
***
## Next steps
<CardGroup>
<Card title="Build your first agent" icon="compass" href="/core-concepts/agents">
Learn how to create and configure agents in Gumloop
</Card>
<Card title="Standard Slack integration" icon="slack" href="/core-concepts/agents_slack">
Review the standard Slack setup if you haven't used it yet
</Card>
<Card title="Managing credentials" icon="key" href="/core-concepts/credentials">
Learn more about credential types and management
</Card>
</CardGroup>
# Evaluations
Source: https://docs.gumloop.com/core-concepts/evaluations
Automatically grade every agent interaction against your criteria, collect structured data, and tag conversations for reporting.
Evaluations give you **automated quality assurance** for your agents. After every interaction completes, an AI evaluator analyzes the full conversation transcript and produces a structured report: a grade, per-criterion pass/fail results with rationales, sentiment analysis, applied tags, and extracted data points.
Think of it as having a QA analyst reviewing every single conversation your agent has, 24/7, without you lifting a finger.
## Where to find evaluations
Open your agent, click **Performance** in the sidebar, then open the **Evaluations** tab. Performance is the home for everything about how the agent is doing — **Insights**, **Evaluations**, and **Tasks**. [Agent Performance](/core-concepts/agent_performance) is the tour of that screen; this page is the deep dive on evaluations themselves.
<Frame>
<img alt="Performance page on the Evaluations tab showing grading, criteria, impact report, and reflections" />
</Frame>
***
## The building blocks
Before jumping into setup, here's the mental model. Evaluations have four building blocks:
<CardGroup>
<Card title="Criteria" icon="list-check">
**Quality rules** the evaluator checks pass/fail on every conversation. Like a QA checklist.
</Card>
<Card title="Tags" icon="tags">
**Labels** applied for categorization and filtering. Like folders in your inbox.
</Card>
<Card title="Data points" icon="table">
**Structured values** extracted from conversations. Like columns in a spreadsheet.
</Card>
<Card title="Sentiment" icon="face-smile">
**Emotional tone** of the interaction. A customer satisfaction thermometer.
</Card>
</CardGroup>
**Criteria** answer: "Did the agent do what it was supposed to do?" Each one is a yes/no check.
**Tags** answer: "What kind of conversation was this?" Use them to filter and find patterns.
**Data Points** answer: "What specific facts or values came up?" They pull structured data out of unstructured conversation.
**Sentiment** answers: "How did the user feel?" Sentiment is optional reporting data and does not affect the grade.
***
## How evaluations work
<Steps>
<Step title="Interaction completes">
Your agent finishes a conversation (reaches the "completed" state). Incognito chats and internal system interactions are never evaluated.
</Step>
<Step title="Transcript is built">
The evaluator constructs a role-tagged transcript of the entire conversation, including user messages, agent responses, tool calls, and results. Long transcripts are automatically trimmed.
</Step>
<Step title="AI evaluator runs">
A single structured-output LLM call analyzes the transcript against your configured criteria, tags, data points, and sentiment settings.
</Step>
<Step title="Grade is computed">
The overall grade is determined deterministically based on which criteria failed, the action set on each failed criterion, and call outcome. Sentiment does not affect the grade.
</Step>
<Step title="Results stored & alerts fired">
Results are persisted. If the grade is **Notify**, the notification channels you enabled fire immediately. Configure **Delivery** and **To** on the Performance evaluation card, including email recipients and selected Slack channels. Recipients must have permission to manage the agent.
</Step>
</Steps>
<AccordionGroup>
<Accordion title="When does the evaluation fire?">
The evaluation fires automatically shortly after the interaction reaches the "completed" state.
* For a simple back-and-forth that ends naturally, the evaluation runs once the chat is marked complete.
* The evaluation covers the **entire transcript** up to that point.
* There is a short debounce period after the last message so the system doesn't prematurely evaluate a chat that's still active.
</Accordion>
<Accordion title="What happens if I keep chatting after the evaluation ran?">
If you continue a conversation after an evaluation has already run:
* The new messages extend the transcript, and the interaction re-enters an active state.
* Once the conversation reaches the "completed" state again, a **new evaluation automatically runs** covering the full updated transcript.
* The new evaluation replaces the previous result. You don't need to manually re-run it.
* You always see the most recent evaluation result for any given interaction.
</Accordion>
<Accordion title="Do I have to manually re-run it, or is it automatic?">
Fully automatic. As long as evaluations are enabled, the system handles re-evaluation whenever conversations continue and complete again. You only need to run manually if you want to backfill old conversations or re-evaluate after changing your criteria.
</Accordion>
</AccordionGroup>
***
## Setting up evaluations
Go to **Performance** → **Evaluations**. You'll see the settings panel:
<Frame>
<img alt="Evaluation settings panel showing the enable toggle, model selector, sentiment analysis, and auto-tags options" />
</Frame>
| Setting | What It Does |
| - | - |
| **Enable evaluations** | Toggle to start automatically grading interactions |
| **Default analysis model** | Which LLM runs the evaluation. "Smartest" = most accurate but costs more per token |
| **Sentiment analysis** | Captures overall sentiment (Positive / Neutral / Negative). Reporting only; it does not affect the grade. |
| **Suggest tags automatically** | Lets the evaluator propose new tags beyond your predefined vocabulary |
<Tip>For sentiment, you can provide custom **guidance** (for example, "Consider the customer's final message tone, not their initial frustration"). Sentiment remains reporting data and does not change the grade.</Tip>
***
## Configuring criteria, tags & data points
<Tabs>
<Tab title="Criteria" icon="list-check">
Criteria are the **quality rules** your evaluator checks every interaction against. Each one is a clear statement that's either true or false for a given conversation.
**How to think about it:** Ask yourself, "If I were reviewing this conversation manually, what would I check for?" Each answer becomes a criterion.
<Frame>
<img alt="Evaluation criteria table" />
</Frame>
### Adding a Criterion
Click **+ Add criterion** and fill in:
<Frame>
<img alt="Add criterion form showing Name, Evaluation prompt, Type, and the Action dropdown with Flag and Notify options" />
</Frame>
| Field | Description |
| - | - |
| **Name** | A short label (e.g., "Accuracy", "Stayed on Topic") |
| **Evaluation prompt** | A true/false statement describing the desired behavior. Be specific. |
| **Type** | Categorizes the criterion: Prohibited action, Prohibited words, Voice & tone, or Other |
| **Action** | What happens when the criterion fails: **Flag** (flags the chat for review without notifying you) or **Notify** (notifies you the moment the evaluator spots one) |
### Types & Actions
| Type | When to Use |
| - | - |
| **Prohibited action** | Agent must NOT do something (e.g., don't offer unauthorized discounts) |
| **Prohibited words** | Agent must NOT say certain things (e.g., no profanity) |
| **Voice & tone** | Agent should communicate in a certain style |
| **Other** | Anything else (stayed on topic, provided accurate info, etc.) |
**Choosing an action:** Use **Notify** for rules that must never be broken (data leaks, compliance violations) so you're alerted right away. Use **Flag** for quality standards that matter but aren't urgent (tone issues, minor drifts); those chats are only marked for review.
<Info>"Notify" alerts the people responsible for the agent, not the person chatting with it. Configure **Delivery** and **To** for email recipients and Slack destinations. Recipients must have permission to manage the agent. End users never see evaluation results.</Info>
<Accordion title="Example criteria for common use cases">
| Use Case | Criterion | Prompt | Type | Action |
| - | - | - | - | - |
| Support | Stayed on Topic | "The agent stayed focused on resolving the customer's issue and did not go off on tangents." | Other | Flag |
| Support | Accuracy | "The agent provided factually correct information and did not hallucinate." | Other | Notify |
| Sales | No Unauthorized Discounts | "The agent did not offer discounts not in the approved pricing sheet." | Prohibited action | Notify |
| Sales | Professional Tone | "The agent maintained a professional, friendly tone throughout." | Voice & tone | Flag |
| Helpdesk | No PII Disclosure | "The agent did not reveal personal information of other employees." | Prohibited action | Notify |
| Content | Brand Voice | "The content matches the brand's voice: confident, concise, and jargon-free." | Voice & tone | Flag |
</Accordion>
<Tip>Write evaluation prompts as true/false statements. The evaluator returns "success" if it holds, "failure" if it doesn't, and "unknown" if there's not enough info to judge.</Tip>
### Pausing a Criterion
Every criterion is either **Active** or **Paused**. Use the criterion's action menu to switch:
| Action | What happens |
| - | - |
| **Pause** | Skips this criterion when grading chats. It's left out of the evaluation entirely, so new interactions are never graded against it. |
| **Resume** | Grades chats against this criterion again. |
Pausing keeps the criterion's name, prompt, type, and action intact, so you can bring it back later without rewriting it. It's the middle ground between deleting a rule you might need again and leaving a noisy one switched on.
<Info>Pausing only affects **future** interactions. Grades already recorded against the criterion stay as they are.</Info>
**Limit:** 30 criteria per agent. Paused criteria still count toward that limit, since they're kept on the agent rather than removed.
</Tab>
<Tab title="Tags" icon="tags">
Tags are **labels for categorization**. After analyzing a conversation, the evaluator applies tags whose description matches what happened. You can then filter your interactions list by tag.
**How to think about it:** Tags are like labels in Gmail. They don't pass/fail anything. They just categorize. Ask yourself, "What categories would help me filter and find patterns in my conversations?"
<Frame>
<img alt="Tags section showing AI_SLOP and OFF_COURSE tags" />
</Frame>
### Adding a Tag
Click **+ Add tag** and provide:
| Field | Description |
| - | - |
| **Name** | Automatically uppercased to `UPPER_SNAKE_CASE`. Max 100 characters. |
| **Description** | Tells the evaluator when to apply this tag. Be specific. Max 500 characters. |
### How Tags Work
* You define a vocabulary of tags with descriptions
* The evaluator applies matching tags after analyzing the conversation
* Tag names are normalized (e.g., "off course" → `OFF_COURSE`)
* You can manually add/remove tags on any evaluated interaction
* Use them to filter the interactions list
<Accordion title="Example tags for common use cases">
| Tag | Description | Use Case |
| - | - | - |
| `ESCALATION_NEEDED` | "Customer asked to speak with a human or the issue is too complex for the agent." | Support triage |
| `UPSELL_OPPORTUNITY` | "Customer expressed interest in additional features beyond what they currently use." | Sales analytics |
| `AI_SLOP` | "Agent's response contained filler phrases or generic AI-sounding language." | Quality monitoring |
| `OFF_COURSE` | "Agent deviated from the user's original question." | Focus tracking |
| `POSITIVE_FEEDBACK` | "User explicitly praised the agent or expressed satisfaction." | CSAT proxy |
| `TECHNICAL_ISSUE` | "Conversation involved a bug report or system malfunction." | Issue categorization |
</Accordion>
<Tip>Enable "Suggest tags automatically" in Settings and the evaluator will also generate new tags for patterns it notices beyond your predefined vocabulary.</Tip>
**Limit:** 50 tags per agent.
</Tab>
<Tab title="Data points" icon="table">
Data collection lets you **extract structured values** from every interaction. Define what to extract, and the evaluator pulls it out automatically.
**How to think about it:** Imagine hiring someone to read every conversation and fill out a spreadsheet. Each column is a data point. You define the column name, value type, and extraction instructions.
<Frame>
<img alt="Data collection section showing a Confidence Score data point" />
</Frame>
### Adding a Data Point
Click **+ Add data point** and configure:
| Field | Description |
| - | - |
| **Name** | What you're extracting (e.g., "Confidence Score") |
| **Type** | Text, Boolean, Integer, or Number |
| **Description** | Extraction instructions. Be precise about what to look for and valid values. |
### Data Point Types
| Type | Returns | Best For |
| - | - | - |
| **Text** | String | Categories, summaries, reasons |
| **Boolean** | Yes / No | Binary checks (was something done?) |
| **Integer** | Whole number | Counts, quantities |
| **Number** | Decimal | Scores, ratings, percentages |
<Accordion title="Example data points for common use cases">
| Name | Type | Description | Use Case |
| - | - | - | - |
| Confidence Score | Number | "Rate 1-10 how confident the agent appeared based on hedging language vs. direct statements." | Quality scoring |
| Resolution Status | Text | "Values: resolved, unresolved, partial, or unknown." | Support metrics |
| Handoff Requested | Boolean | "Did the user ask to speak with a human?" | Escalation tracking |
| Number of Tool Calls | Integer | "Count distinct tools the agent used." | Efficiency analysis |
| Customer Intent | Text | "Summarize the customer's primary intent in 2-5 words." | Intent classification |
| Response Quality | Number | "Rate 1-10 considering accuracy, completeness, and helpfulness." | Performance benchmarking |
</Accordion>
<Tip>Data points that return `null` mean the evaluator couldn't find the information in the transcript. This is expected for data points that don't apply to every conversation.</Tip>
**Limit:** 40 data points per agent.
</Tab>
</Tabs>
***
## Understanding results
Once an interaction is evaluated, you can see the full results in the interaction detail view's **Overview** tab.
<Frame>
<img alt="Evaluation result showing summary, grade, outcome, sentiment, criteria results, tags, and collected data" />
</Frame>
### Grades
| Grade | API Value | Meaning | What Triggers It |
| - | - | - | - |
| **Pass** | `pass` | Met all criteria | No failures, and the call wasn't a failure |
| **Flag** | `needs_review` | Flagged for review | A criterion set to **Flag** failed, OR call outcome "failure" |
| **Notify** | `needs_attention` | Immediate attention | A criterion set to **Notify** failed (fires your enabled notification channels) |
<Info>When using the [Evaluations API](/api-reference/evaluations/list-evaluations), use the API values (`pass`, `needs_review`, `needs_attention`) for the `grade` query parameter, not the UI labels.</Info>
<Accordion title="Grade computation logic (deterministic)">
The grade is computed deterministically (not by the LLM) after results come back:
1. If any criterion set to **Notify** failed → **Notify**
2. If any other criterion failed → **Flag**
3. If overall **call outcome** was "failure" → **Flag**
4. Otherwise → **Pass**
</Accordion>
### What's shown in results
* **Summary**: One or two sentence narrative of what happened
* **Grade**: Pass / Flag / Notify badge
* **Outcome**: Successful / Failed / Unknown
* **Sentiment**: Positive / Neutral / Negative (if enabled)
* **Tags**: Applied tags from your vocabulary + auto-generated
* **Criteria**: Per-criterion pass/fail with the evaluator's rationale
* **Collected data**: Extracted values for each data point
### Interactions list view
The interactions list includes an **Evaluation** column showing the grade and criteria pass rate at a glance (e.g., "Pass 3/3" or "Notify 1/3"). Lifecycle states also appear: Queued, Evaluating, or Failed.
***
## Running evaluations manually
Evaluations run automatically, but you can also trigger them manually from the task list.
<Steps>
<Step title="Go to Tasks">
Open **Performance** → **Tasks** on your agent.
</Step>
<Step title="Find the task">
Locate the task you want to evaluate. The **Evaluation** column shows the current state.
</Step>
<Step title="Open the Actions Menu">
Click the **three-dot menu** (⋮) on the right side of the interaction row.
</Step>
<Step title="Click Run Evaluation">
Select **"Run evaluation"** from the dropdown. Results will appear shortly.
</Step>
</Steps>
<Frame>
<img alt="Interactions list showing the three-dot menu with Run evaluation option" />
</Frame>
You can also select multiple interactions for bulk evaluation.
**When to use manual runs:**
* Backfilling existing conversations after enabling evaluations
* Re-evaluating after changing your criteria/tags/data points
* Retrying a failed evaluation
* Spot-checking specific conversations on demand
<Info>Manual evaluations use the **current** configuration. If you've changed your setup, a re-run reflects the new rules.</Info>
You can also queue evaluations from the [API](/api-reference/evaluations/run-evaluations), the Python SDK (`client.agents.run_evaluations`), or the CLI (`gumloop agents eval-run`).
### Letting the agent manage its own evaluations
Turn on the **Manage Evaluations** ability in the agent's configuration and anyone who can edit the agent can ask it, in chat, to review its results, add or change criteria, or re-run evaluations on past chats. Reads happen immediately. Every change and every run shows an approval card listing exactly what will change before it happens. The ability is available on Pro and Enterprise plans, on custom agents.
<Frame>
<img alt="Agent Abilities list showing the Manage Evaluations ability turned on" />
</Frame>
| What you can ask for | What happens |
| - | - |
| "What's failing?" | Reads the rubric, a failure-rate rollup per criterion, and individual results. Both default to the last 30 days and can look back up to a year. No approval. |
| "Add criteria for X" / "Rewrite this one" / "Drop these two" | Proposes the exact criteria and waits for your approval before saving. The 30-criteria limit still applies. |
| "Change the settings" | Patches only the settings you name — on/off, frequency, analysis model, language, sentiment, notifications, automatic tags — and leaves the rest alone. Approval required. |
| "Re-run these chats" | Queues up to 200 finished chats, using the current configuration. Costs credits per chat, and skips chats that are already being evaluated. Approval required. |
<Info>The agent only sees the chats you can see. If your role cannot view other people's interactions, it analyzes your own chats and says so. It also cannot evaluate the chat it is having with you — that chat is still running.</Info>
***
## Notifications
Notifications fire only when a chat receives a **Notify** grade, i.e. a criterion whose action is **Notify** failed. Configure the channels in the **Notifications** section of the Evaluations tab.
| Channel | Who receives it |
| - | - |
| **Slack** | The Slack destinations you select under **Delivery** and **To**, including selected channels. Recipients must have permission to manage the agent. |
| **Email** | The email recipients you list. Recipients must have permission to manage the agent. Up to 50 recipients. |
<Frame>
<img alt="Notifications section with Slack notifications and Email notifications toggles and a recipient input" />
</Frame>
<Info>"You" in this UI means the agent's owner and the recipients you configure, never the end user chatting with the agent.</Info>
<Tip>Flag-grade chats are marked in the interactions list but never send a notification. Review them periodically by filtering for the Flag grade.</Tip>
***
## Credits and costs
Evaluations are billed as **AI credits** under the "AI Utilities" category. Each evaluation is a single LLM call.
<Accordion title="What determines the cost?">
Three factors:
1. **Transcript length**: Longer conversations use more input tokens. A 5-message chat costs significantly less than a 50-message conversation.
2. **Analysis model**: The model you select determines the per-token rate. "Smartest" costs more than faster alternatives.
3. **Schema complexity**: More criteria, tags, and data points = more output tokens to generate.
The evaluator checks that the user has sufficient credits before running. If credits are insufficient, the evaluation is skipped silently.
</Accordion>
### Where to see credit usage
View all evaluation credit usage on your **[Usage & Limits](https://www.gumloop.com/settings/organization/limits)** page. Filter by "AI Utilities" to see individual evaluation runs and their credit amounts.
<Frame>
<img alt="Credit Usage Logs page filtered to AI Utilities showing Interaction Evaluation entries" />
</Frame>
***
## Limits
| Resource | Maximum |
| - | - |
| Criteria per agent | 30 |
| Tags per agent | 50 |
| Data points per agent | 40 |
| Tag name length | 100 characters |
| Tag description length | 500 characters |
| Email notification recipients | 50 |
***
## Exporting evaluation data
Every evaluation result, including grades, criteria outcomes, extracted data points, tags, and sentiment, is available through the [Evaluations API](/api-reference/evaluations/list-evaluations). You can use this to export evaluation data to any external system (spreadsheets, databases, BI tools, etc.).
On the Enterprise plan there is a second route that needs no code: **Interaction Evaluations** is a data type in [Data Export and Data Drains](/enterprise-features/organization_data_export), so you can download every agent's evaluations across the organization as a CSV, or keep them flowing continuously into S3, Datadog, or your own endpoint. Those rows cover the headline result — grade, call outcome, sentiment, summary, evaluation model, and credit cost — one row per rubric per chat. Use the API when you need per-criterion detail, extracted data points, or applied tags.
### API
Use the **List evaluations** endpoint to pull all results for an agent:
```bash theme={"dark"}
curl 'https://api.gumloop.com/api/v1/agents/AGENT_ID/evaluations?page_size=100' \
-H 'Authorization: Bearer YOUR_API_KEY'
```
Each result includes:
* `grade` (`pass` / `needs_review` = Flag / `needs_attention` = Notify)
* `criteria_results` with per-criterion pass/fail and rationale
* `data_results` with extracted values for each configured data point
* `applied_tags`
* `sentiment`
* `summary`
Paginate through all results using the `next_cursor` field. Narrow the list with `grade`, `status`, `session_id`, `created_after`, and `created_before` (ISO 8601), for example `?grade=needs_attention&created_after=2026-01-01T00:00:00Z`.
For a single evaluation, use the [Retrieve evaluation](/api-reference/evaluations/retrieve-evaluation) endpoint.
For aggregate metrics over time, use the [Get metrics](/api-reference/evaluations/get-metrics) endpoint.
<Tip>Call the evaluations API on a schedule and push results to Google Sheets, a database, or a webhook for automated reporting.</Tip>
### Python
```python theme={"dark"}
import csv
import requests
API_KEY = "YOUR_API_KEY"
AGENT_ID = "YOUR_AGENT_ID"
# Paginate through all evaluations
cursor = None
all_evaluations = []
while True:
params = {"page_size": 100}
if cursor:
params["cursor"] = cursor
response = requests.get(
f"https://api.gumloop.com/api/v1/agents/{AGENT_ID}/evaluations",
headers={"Authorization": f"Bearer {API_KEY}"},
params=params,
)
response.raise_for_status()
data = response.json()
all_evaluations.extend(data["evaluations"])
cursor = data.get("next_cursor")
if not cursor:
break
# Export data points to CSV
with open("eval_export.csv", "w", newline="") as f:
writer = csv.writer(f)
writer.writerow(["interaction_id", "grade", "sentiment", "summary"])
for ev in all_evaluations:
writer.writerow([ev["interaction_id"], ev["grade"], ev["sentiment"], ev["summary"]])
```
***
## FAQ
<AccordionGroup>
<Accordion title="Which interactions get evaluated?">
All completed interactions are evaluated, except:
* **Incognito chats**: Never evaluated (privacy guarantee)
* **Internal interactions**: Agent-to-agent feedback loops like reflections are excluded
* **Non-terminal states**: Only interactions that reach "completed" are evaluated
</Accordion>
<Accordion title="Can I evaluate interactions from before I enabled evaluations?">
Yes. Go to **Performance → Tasks**, click the three-dot menu on any interaction, and select "Run evaluation." You can also select multiple for bulk evaluation. They'll be graded against your current criteria.
</Accordion>
<Accordion title="What happens if I keep chatting after an evaluation already ran?">
The interaction re-enters an active state. Once it completes again, a new evaluation runs automatically covering the full updated transcript. The new result replaces the previous one.
</Accordion>
<Accordion title="Does the evaluation fire only once per chat?">
By default, yes. The evaluation fires once after the conversation completes (with a short debounce window to avoid premature evaluation). If the conversation is resumed and completes again, a new evaluation runs automatically covering the updated transcript.
</Accordion>
<Accordion title="What happens if the evaluation fails?">
It's marked as "Failed" rather than showing a misleading pass. Doesn't affect metrics. You can manually re-run it from **Performance → Tasks**, or it will be re-evaluated if the conversation continues.
</Accordion>
<Accordion title="How is the analysis model different from my agent's model?">
It's a separate LLM call dedicated to evaluation. Doesn't affect your agent's behavior. You can choose a different model. The evaluator never sees your agent's system prompt directly, only the transcript and agent description/skills as context.
</Accordion>
<Accordion title="Does the evaluator see my agent's system prompt?">
It receives your agent's **name**, **description**, and **available skills** as context. It does NOT receive the full system prompt. Transcript content is treated as data to analyze, never as instructions.
</Accordion>
<Accordion title="Can I set up evaluations at the organization level?">
Yes, on the Enterprise plan. Organization admins with the **Manage evaluations** permission create evaluations under **Organization → Evaluations** and apply them to the whole organization, specific teams, people, or individual agents. They are also available through the [API](/api-reference/organization-evaluations/list-evaluations), [SDK](/api-reference/sdk/python#organization-evaluations) and [CLI](/cli/evaluations).
</Accordion>
<Accordion title="What happens if I delete a criterion or tag?">
Past evaluation results retain their original data. Deleting only affects future evaluations.
</Accordion>
<Accordion title="Can I edit tags on an evaluation result?">
Yes. Manually add or remove tags using the tag editor in the evaluation detail view.
</Accordion>
<Accordion title="Why does my evaluation show 'Inconclusive'?">
All criteria returned "unknown" (evaluator couldn't determine pass/fail). Typically means the conversation was too short or didn't touch on what your criteria check.
</Accordion>
<Accordion title="How much do evaluations cost in credits?">
Each evaluation is billed based on tokens used. Cost depends on conversation length, model selected, and number of criteria/tags/data points configured. Track usage on your [Usage & Limits](https://www.gumloop.com/settings/organization/limits) page under "AI Utilities."
</Accordion>
<Accordion title="Can I export evaluation data?">
Yes, in two ways. The [Evaluations API](/api-reference/evaluations/list-evaluations) gives you full programmatic access to all evaluation results, including grades, criteria outcomes, extracted data points, tags, and sentiment. On Enterprise, organization admins can also export or continuously drain evaluations without writing code by picking the **Interaction Evaluations** type in [Data Export](/enterprise-features/organization_data_export). See [Exporting Evaluation Data](#exporting-evaluation-data) above.
</Accordion>
</AccordionGroup>
# Gumball
Source: https://docs.gumloop.com/core-concepts/gumball
Your personal Gumloop agent — chat, a labeled inbox, a morning report, and a brief before every meeting.
Gumball is the personal agent that comes with every Gumloop account. Unlike [custom agents](/core-concepts/agents), which you build and share with your team, Gumball belongs to you: it is created automatically the first time you open it, it can search every [skill](/core-concepts/skills) you can access — including your teams' skills — and it uses your own [connectors](/core-concepts/credentials) to read and act in the apps you've connected.
<Frame>
<img alt="Gumball home screen showing the chat box, the Daily Chew tab, and the right rail with Accounts, Triggers, and Personalization" />
</Frame>
On top of chat, Gumball runs three proactive features that work while you're away:
<CardGroup>
<Card title="Daily Chew" icon="sun">
A short report from your connected apps, delivered on your schedule.
</Card>
<Card title="Smart Inbox" icon="inbox">
Labels new email as it arrives in Gmail or Outlook, moves the noise out of your Inbox, and can draft replies for you.
</Card>
<Card title="Meeting Prep" icon="calendar-check">
A context brief before each meeting on your calendar.
</Card>
</CardGroup>
<Info>All three are **owner-only**. Gumball is a personal agent, so only you can configure or view its Smart Inbox, Daily Chew, and Meeting Prep — they can't be shared like a custom agent.</Info>
***
## What Gumball comes with
The right-hand rail on the Gumball home screen is the control panel for everything below.
| Section | What it does |
| - | - |
| **Email** | Gumball's own address, `gumball@gumloop.ai`. Email it like a coworker and it replies. |
| **Text** | Gumball's phone number. Text it over iMessage, RCS, or SMS from a verified phone number. See [Text Gumball](/core-concepts/text_gumball). |
| **Inbox** | Connect a Gmail or Outlook mailbox for [Smart Inbox](#smart-inbox). |
| **Calendar** | Connect a Google Calendar or Outlook Calendar account for [Meeting Prep](#meeting-prep). |
| **Slack** | Opens your DM with the Gumloop Slack app, where you can chat with Gumball. See [Gumball in Slack](#gumball-in-slack). |
| **Connectors** | Every app Gumball can read and act in. |
| **Triggers** | Schedules and event triggers that run Gumball automatically. |
| **Personalization** | The **Tone** and **Design** skills Gumball curates about how you like to be written to and how you like output laid out. |
Below the chat box are tabs for **Daily Chew**, **Smart Inbox**, **Tasks**, and **Artifacts** — the reports Gumball has produced, the Situations it has surfaced, and the [files](/core-concepts/agent_artifacts) it has created.
### Emailing Gumball
Gumball's email address is reserved and fixed — you can't rename it or hand it to another agent. Send it a request and it replies in the same thread using your connectors.
<Frame>
<img alt="Gmail thread where a user emails gumball and Gumball replies with a summary of assigned Linear tickets" />
</Frame>
<Tip>Gumball follows the same rules as any [agent email inbox](/core-concepts/agents_email) — including DKIM checks on the sending domain.</Tip>
### Texting Gumball
Gumball also has a phone number, shown in the **Text** row under **Where to reach me**. Verify your phone number in Gumloop, then text Gumball over iMessage, RCS, or SMS and it replies in the same chat. See [Text Gumball](/core-concepts/text_gumball) for setup, approvals by text, opt-out keywords, and permissions.
### Gumball in Slack
You can talk to Gumball by **direct messaging the Gumloop Slack app** in your workspace. There is nothing to set up and no channel to create — find the Gumloop app in your Slack sidebar (or under **Apps**) and send it a message.
<Frame>
<img alt="Slack DM with the Gumloop app where a user asks to fetch their latest emails and Gumball replies with progress" />
</Frame>
The **Slack** row in the right rail links straight to that DM once you have connected a Slack account; click **Open**.
| | How it works in a DM |
| - | - |
| **Which agent answers** | Always your own Gumball. [Custom agents](/core-concepts/agents) live in channels — DMs never reach them. |
| **Who you are** | Gumball matches your Slack email to your Gumloop account, and runs on your connectors and skills, exactly like the web app. Without a matching Gumloop account you get a sign-up prompt instead. |
| **Conversations** | Each top-level message you send starts a new conversation; reply in that message's thread to continue it. |
| **Everything else** | Same Gumball — your skills, connectors, artifacts, and history are shared with the web app, and thread commands like `!stop` and `!link` work. |
<Info>Gumball DMs use your workspace's existing Gumloop Slack app. If it was installed before DMs were supported, Gumball replies asking a workspace admin to reconnect the Gumloop Slack app — reconnecting it from the [Connectors page](https://www.gumloop.com/settings/profile/connectors?view=connected) grants the extra direct-message permissions and nothing else changes.</Info>
<Tip>Want a DM with a **custom** agent and its own name and avatar? Use a [Custom Slack App](/core-concepts/custom_slack_app#direct-messages-dms).</Tip>
***
## Daily Chew
The Daily Chew is a short report of **what you missed** across your connected apps, on the schedule you pick. It's deliberately a one-pager, not an activity digest.
<Frame>
<img alt="Build your Daily Chew dialog with a connector search and an Enable Daily Chew button" />
</Frame>
### Configuring it
<Frame>
<img alt="Daily Chew settings with Time, Days, Connectors, Instructions, Model, and Delivery toggles" />
</Frame>
| Setting | Notes |
| - | - |
| **Time** and **Days** | When the report runs, in your timezone. Both are required the first time you set it up. |
| **Connectors** | **All connectors** uses everything you have connected at run time. **Selected connectors** pins a specific list (up to 50). |
| **Instructions** | What you want emphasised, up to 4,000 characters. |
| **Model** | Defaults to Gumball's model. |
| **Delivery** | Reports always appear in Gumball. **Email**, **Slack DM**, and **Text message** are optional extras. See [Getting briefs by text](#getting-briefs-by-text). |
<Tip>Leave **All connectors** selected if you keep adding tools — the report picks up new connectors automatically instead of needing to be re-configured.</Tip>
### What a report looks like
Every report has two parts:
| Part | What it is |
| - | - |
| **Summary** | The one-glance line on the Gumball home screen: exactly two sentences, 40 words max, plain text. The first names the thing that most needs you; the second names the next priority, decision, or blocker. |
| **Document** | The overnight catch-up, written as a single `## Catch-up` section: one short story about what changed while you were away, and why it matters. |
The document does not repeat the card list. Every other thing you missed lives in **Things to know** as a [Situation](#situations), so the one-pager stays a short read rather than a beat-by-beat recap.
<Note>A document with nothing real to say is **left out entirely** — you won't get a "Nothing to report" placeholder. There's no title, date banner, or preamble above the heading either; the report starts straight in on the content.</Note>
Facts in the document are attributed back to the app they came from with a citation chip. Routine calendar entries don't become their own item — a meeting only earns a mention when a conflict, deadline, or required prep changes what you should do.
### How it behaves
* **Runs are read-only.** The Daily Chew can only use tools that read; anything that could write, send, or change something is blocked, including tools reached through another tool.
* **Sources fail independently.** If Slack is down, the rest of the report still gets written and Slack is simply marked as failed for that run.
* **A failed source doesn't lose your place.** Gumball only advances its "last read" marker for sources that actually succeeded, so the next run picks up what it missed.
* **First run looks back 16 hours.** After that, each run covers everything since the previous successful one.
* **Reports are never sent twice.** If a run is retried internally, you get one report, not two.
* **Pausing** stops it from running; **resuming** puts it back on schedule. Past reports stay in your history either way.
### Getting briefs by text
Turn on **Text message** under **Delivery** to get Daily Chew and Meeting Prep briefs on your phone. It's off by default, and it's set separately for Daily Chew and Meeting Prep.
Each brief arrives from Gumball's phone number, the same line you [text Gumball](/core-concepts/text_gumball) on, and contains:
* The brief's title and its summary.
* The titles of its [Situations](#situations).
* A final **Open in Gumloop** link to the full brief. The document and its citations stay in Gumloop.
<Note>Text delivery needs a **verified phone number**. If you haven't linked one, the **Text message** row shows **Link phone number** and you can't turn it on until you do. If texting Gumball is off for your role, the row says so and offers **Request access** instead.</Note>
If you remove your number or [opt out](/core-concepts/text_gumball#opting-out) of texts, briefs stop arriving by text. They are still saved in Gumball and sent to any other delivery channel you turned on.
### Telling Gumball a report needs work
Daily Chew and Meeting Prep briefs delivered as a **Slack DM** carry two buttons: **Give Feedback** and **Open in Gumloop**.
<Steps>
<Step title="Click Give Feedback">
A dialog opens asking what Gumball missed or got wrong. The text is required.
</Step>
<Step title="Gumball replies in a thread">
Your feedback is posted as a thread under that brief in Slack, and Gumball answers there with the brief already in front of it, so you don't have to re-explain what it said.
</Step>
<Step title="It becomes a standing rule">
Gumball turns the feedback into a general instruction for the product it came from, rather than a note about that one brief, so the next run is different.
</Step>
</Steps>
<Info>Only the person the brief was delivered to can use **Give Feedback**, and only on Daily Chew and Meeting Prep briefs. Gumball is personal, so nobody else in the workspace can send feedback on your brief.</Info>
The same thing happens when you give feedback in a normal Gumball chat: telling it a Daily Chew or Meeting Prep report was wrong edits that product's **Instructions**, and telling it a Smart Inbox message was labeled or drafted wrong edits the relevant [label](#labels) or your [drafting preferences](#reply-drafts). Gumball keeps the rest of your setup as it is, and leaves schedule, sources, and delivery alone unless you ask for those.
### Situations
Daily Chew “things to know” are first-class **Situations**, surfaced on the Gumball home screen in **Highlights**. Highlights shows the current morning's open Situations plus earlier Situations you haven't dismissed.
Each Situation is **one thing you missed**, with every source that belongs to it grouped onto the same card — two apps carrying the same thread give you one Situation, not two. A Situation has a title, a short summary of what changed and why it matters, an optional next step, and its source citations. It can also include zero or more ordered nested steps. Open a Situation card to see its detail sheet and its nested list under **Plan**.
For each step, you can:
* Edit the prompt before sending. The editor includes the hint “Use @ to mention agents and skills in the prompt.”
* Change its status to **To do**, **Done**, or **Skipped**.
* Accept or dismiss the step.
Editing a step only saves the edited prompt and any changed @mentions; it does not start a chat. Accepting an individual step can start a chat for that step.
**Send to Gumball** sends the whole Situation as one plan: all steps run in order in a single chat, not one chat per step. Your edited prompt and @mentions are used when the chat starts. Sending the same Situation again returns the existing chat instead of creating a second one. Completed Situations and steps show **View chat**. A Situation with no steps cannot be sent as a plan.
At the Situation level, you can choose **Dismiss**. A Situation with no nested steps also shows **Mark handled**. You can dismiss anything you can see. Citations can appear on the Situation itself and on individual steps where available.
Situations are deliberately narrow: they represent real work you own with a concrete outcome Gumball could take on. A mention in a channel does not qualify on its own; a customer waiting on a document you promised does.
***
## Smart Inbox
Smart Inbox labels **new** email as it lands in your mailbox, using labels you define in plain English. It's not a separate inbox — everything happens as native tags in your real mailbox (Gmail labels, Outlook categories), so it works in the Gmail or Outlook app, on mobile, and in any client you already use.
<Info>Smart Inbox supports **Gmail** and **Microsoft Outlook**, and requires a **Pro** plan or above. Gumball watches **one mailbox at a time** — connecting a second one replaces the first.</Info>
Smart Inbox labels and categorizes mail, then makes one drafting decision for each message. It can create native drafts in Gmail or Outlook, but it does not create suggested actions or reply suggestions in Gumball.
### Turning it on
<Steps>
<Step title="Open the Smart Inbox tab">
From the Gumball home screen, open the **Smart Inbox** tab and click **Enable Smart Inbox**.
<Frame>
<img alt="Smart Inbox tab showing the Connect your inbox empty state with an Enable Smart Inbox button" />
</Frame>
</Step>
<Step title="Pick the mailbox">
Choose the connected **Gmail** or **Outlook** account Gumball should watch, then confirm.
<Frame>
<img alt="Connect your inbox dialog with a mailbox account selector and an Enable Smart Inbox button" />
</Frame>
Gumball seeds five built-in labels and starts classifying the next email that arrives.
</Step>
</Steps>
<Warning>Enabling requires permission to **read email** and **modify messages** — on Gmail it also needs to list and create labels. Two capabilities are optional, and if your organization's [app rules](/enterprise-features/app-policies/app-rules) block them, labeling keeps working without them: **creating drafts** (no draft is created) and, on Outlook, **archiving** (labels still apply, but mail stays in your Inbox).</Warning>
### Gmail vs. Outlook
Both mailboxes get the same classification, labels, and reply drafts. Three things behave differently because the providers themselves do.
| | Gmail | Outlook |
| - | - | - |
| **Native tag** | A Gmail label. | An Outlook category, registered so it shows up in the **Categorize** menu with its colour. |
| **Renaming a label** | The Gmail label is renamed too, so mail you already have follows the new name. | Outlook can't rename a category, so the new name applies to **future** mail only and older mail keeps the old category. |
| **Moving mail out of the Inbox** | Always available. | Needs the archive permission. Without it, labels apply and mail stays in your Inbox. |
### Labels
You start with five built-in labels, and you can add your own up to a total of **25**.
| Built-in label | Applied when |
| - | - |
| **Needs reply** | You should reply. |
| **Time sensitive** | There's an explicit deadline or urgency. |
| **Waiting on you** | Progress requires your action. |
| **FYI** | Useful information, no action needed. |
| **Low priority** | Non-urgent, limited immediate value. |
A label is just a name, a definition, and a colour. The definition is the instruction Gumball classifies against — write it the way you'd explain it to a new assistant.
<Frame>
<img alt="New label form with Name, Definition, and a colour picker" />
</Frame>
### Keep in inbox vs. move out
Every label sits in one of two groups, and the group decides where matching mail ends up.
<Frame>
<img alt="Labels card with a Move these out of my Inbox column and a Keep these in my Inbox column" />
</Frame>
<Warning>**Keep wins.** A message leaves your Inbox only when *every* label Gumball applied to it is in the "Move these out" group. One "Keep" label anywhere on the message keeps it in your Inbox.</Warning>
The **Existing labels** toggle in **Manage** controls whether Gumball skips mail you've already organised: when it's on, any message that already carries one of your own labels or categories is left alone. Labels Gumball manages don't count for this.
<Frame>
<img alt="Labels management panel showing the Existing labels toggle and the two label groups" />
</Frame>
<Info>A message can receive at most **5** labels. Labels Gumball isn't confident about are dropped rather than guessed.</Info>
### Classification happens once
Gumball classifies each email **as it arrives**, and never re-runs on old mail.
* Editing a label's definition, colour, or group changes **future** email only.
* Turning a label off stops it being applied going forward; mail already labelled keeps its label.
* Deleting a custom label removes it from Gumball; the native label or category stays on the messages that already have it.
* Renaming a label renames the matching Gmail label, so your existing mail follows the new name. On Outlook the new name is used going forward and older mail keeps the old category.
* The five built-in labels can be disabled or edited, but not deleted.
* A label that shares a name with one of your own labels or categories is adopted rather than duplicated, and Gumball starts managing it.
### Reply drafts
When Gumball decides a message needs a reply, it can write one straight into your mailbox as a native draft — so you open Gmail or Outlook, read it, edit it, and hit send.
<Frame>
<img alt="Smart Inbox settings with Inbox account, Classification model, Drafting instructions, and Draft replies options" />
</Frame>
| Setting | What it controls |
| - | - |
| **Inbox account** | Which Gmail or Outlook mailbox Smart Inbox watches. |
| **Classification model** | The model used to label email. Defaults to Gumball's own model. |
| **Drafting instructions** | Standing instructions applied to every reply Gumball drafts. These outrank your Tone personalization. |
| **Draft replies** | Whether a native draft is created in your mailbox at all. |
| **Connectors** | Which of your apps Gumball may read while writing a draft. See [Grounding drafts in your apps](#grounding-drafts-in-your-apps). |
**Draft replies** is an on/off choice, not a scale:
| Option | What happens |
| - | - |
| **When confident** (default) | Gumball writes a native draft when it decides the message needs a reply and it is confident in the reply it produced. Otherwise, no draft is created. |
| **Off** | No drafts are created in your mailbox. Gumball skips reply generation altogether, so it doesn't cost you credits. |
Drafts are written from the thread itself plus up to three of your past replies to that sender, so they sound like you. Point Gumball at your other apps and it can go further — see [Grounding drafts in your apps](#grounding-drafts-in-your-apps).
<Note>If you configured this back when it offered several confidence levels, it now reads as **When confident**. Only an explicit **Off** is carried over.</Note>
#### Who the draft is addressed to
A draft keeps the conversation intact, so nobody is quietly dropped:
| The mail you received | Who the draft goes to |
| - | - |
| Sent to you and other people | A **reply all** — the sender plus everyone who was on **To**, with the original **Cc** kept on Cc. |
| Sent to you alone | A normal reply to the sender. |
Your own connected address is always removed from the recipients, and Bcc is never carried over. If you would rather reply to the sender only, edit the recipients in Gmail or Outlook before you send.
#### When Gumball drafts
A draft is created only when all three of these hold:
| Check | What it means |
| - | - |
| **The ask is aimed at you** | The latest ask in the message is for the mailbox owner. Being on **To** or **CC**, or being mentioned, isn't enough — if the greeting names someone else, or only that person can answer, Gumball stays out of it. |
| **There's something to reply to** | A real ask, a decision, a deadline, or a commitment you made. FYIs, mentions, notifications, meeting notices, being looped in, and polite mail with no ask don't qualify. |
| **Your instructions allow it** | **Drafting instructions** that say to ignore this kind of mail block the draft. |
When the signals conflict, Gumball prefers not to draft rather than guess.
Two kinds of mail are skipped before that even applies:
* **No-reply, newsletter, and system senders** (`noreply@`, `notifications@`, mailer daemons, and similar) never get a native draft.
* **Calendar invitations with nothing to reply to** — just the invite chrome and no note from the organizer — are skipped. An invitation with a real message from the organizer goes through the checks above like any other mail.
#### Known senders only
By default, Gumball drafts only for known or trusted senders:
* You have previously sent email to that exact address, or the sender's email domain has the same registrable domain as your mailbox's domain. Shared free, personal, and disposable email domains do not count, so a Gmail sender does not match another Gmail mailbox this way.
* Mail you have only received from does not make a sender known. If Gumball cannot complete the check for whether you have emailed the sender, it treats the sender as known rather than skipping the draft.
**Why didn't I get a draft?** The sender may not have passed this filter, or the message may not have passed one of the three checks above. To draft for all eligible messages, ask Gumball to turn off **only draft replies for people you have emailed or who share your work domain**.
Labeling always continues, even when no draft is created, and you can ask Gumball for a reply in chat at any time.
#### Follow-up messages in a thread
When a new message lands in a thread Gumball already drafted for:
* If you **haven't touched** the draft, Gumball replaces it with one that accounts for the newer message, so you don't end up with a stack of stale drafts.
* If you **edited** it, Gumball leaves your text alone and skips drafting entirely.
<Warning>Gumball never overwrites a draft you've touched.</Warning>
<Info>Gumball only ever creates **drafts**. Smart Inbox cannot send email on your behalf.</Info>
#### Grounding drafts in your apps
By default a draft is written from the email thread alone, so it can't answer anything the thread doesn't already contain. Under **Connectors** in Smart Inbox settings you can let Gumball look things up first:
| Choice | What Gumball may read |
| - | - |
| **All connectors** | Everything you have connected, at the time the mail arrives — so new apps are picked up automatically. |
| **Selected connectors** | Only the apps you pick (up to 50). |
| *Nothing selected* | Thread-only drafts, exactly as before. No lookups happen. |
What that changes:
* Lookups are **read-only and minimal**. Gumball checks a source to confirm a fact or pull a number the reply needs — it doesn't go browsing because a tool exists.
* It can also draw on your [Brain](/core-concepts/brain) sources when the agent already has them, your past conversations, that morning's [Daily Chew](#daily-chew) Situations, and any [Meeting Prep](#meeting-prep) briefs for the people on the thread.
* If a fact is still missing after a sensible check, Gumball **asks or leaves a placeholder** rather than inventing it.
* Drafts cite where a grounded fact came from, and citations must come from a source that was actually in scope for that draft.
* A grounded draft is billed like a short triggered agent run rather than a single model call, so it costs more [credits](/core-concepts/credits) than a thread-only draft.
<Info>Grounding never widens what Gumball can do: the run is read-only, so it cannot send, reply, archive, or change anything in the apps it reads — including tools reached through another tool.</Info>
### Disconnecting
Turning Smart Inbox off, or switching to a different mailbox, clears Gumball's record of what it labelled and its link to the native labels or categories. Those stay in your mailbox on the mail that already has them, and Gumball re-adopts them by name if you reconnect.
***
## Meeting Prep
Meeting Prep gives you a brief before a meeting starts: who's attending, what you've discussed with them before, what's still open, and what to raise.
### Turning it on
<Steps>
<Step title="Connect a calendar">
Pick the **Google Calendar** or **Outlook Calendar** account Gumball should watch, then click **Enable Meeting Prep**.
<Frame>
<img alt="Prep every meeting dialog with a calendar account selector and an Enable Meeting Prep button" />
</Frame>
</Step>
<Step title="Choose what gets prepped">
<Frame>
<img alt="Meeting Prep settings with calendar account, automatic prep toggle, trigger mode, minutes before event, meeting scope, connectors, instructions, model, and delivery" />
</Frame>
</Step>
</Steps>
| Setting | Notes |
| - | - |
| **Prep meetings automatically** | When off, meetings still appear and you prep them one at a time with **Prepare now**. |
| **Calendar account** | The connected Google Calendar or Outlook Calendar account. |
| **Calendar** | Which calendar on that account to watch. |
| **Minutes Before Event** | How far ahead of the meeting the brief is written. |
| **Meetings to prep** | **All meetings**, or **External meetings only**. |
| **Connectors** | All connected apps, or a specific list. |
| **Instructions** | What research you want done and how you want it framed. |
| **Delivery** | In Gumball always; **Email**, **Slack DM**, and **Text message** optional. See [Getting briefs by text](#getting-briefs-by-text). |
<Info>**External meetings only** is the default. A meeting counts as external when at least one guest — other than you — has an email domain different from yours. Solo events and all-internal meetings are skipped.</Info>
### Prepping a meeting yourself
Upcoming meetings are listed on the Gumball home screen whether or not automatic prep is on.
<Frame>
<img alt="Upcoming meetings list on the Gumball home screen" />
</Frame>
Open one and click **Prepare now** to generate a brief on demand.
<Frame>
<img alt="Meeting detail dialog showing time, location, guests, and Join meeting and Prepare now buttons" />
</Frame>
<Tip>**Prepare now** works even when automatic prep is turned off — turning it off just means Gumball won't fire on its own.</Tip>
### What a brief looks like
A short summary (two to three sentences, 60 words max) plus a document with up to four sections, in this order, omitting any that are empty:
`## Attendees` · `## Prior context` · `## Open questions` · `## Talking points`
**Prior context** opens with a recap of your history with these people, then the relevant threads, decisions, and risks across every connected app — email, Slack, meeting notes, CRM activity — woven together rather than listed per tool. The meeting's time, location, and guest list aren't restated, since they're already on the card next to the brief.
Meeting Prep runs are read-only and handle source failures exactly like the Daily Chew. Briefs delivered to Slack carry the same **Give Feedback** button, described under [Telling Gumball a Report Needs Work](#telling-gumball-a-report-needs-work). Meeting Prep briefs delivered to Slack also include links to the brief's cited sources when those sources have a URL.
<Info>Google Calendar and Outlook Calendar behave the same way here: same settings, same automatic and **Prepare now** paths, and the same brief.</Info>
***
## Availability and permissions
| Feature | Requirement |
| - | - |
| **Gumball chat** | Included with every account. Gated by the `access_general_agent` organization permission. |
| **Smart Inbox** | **Pro** plan or above, plus a connected Gmail or Outlook mailbox. |
| **Daily Chew** | Any plan, with at least one connector. |
| **Meeting Prep** | Any plan, with a connected Google Calendar or Outlook Calendar account. |
| **[Texting Gumball](/core-concepts/text_gumball)** | **Enterprise** plan, plus a verified phone number. |
Organization admins control access through [user roles](/core-concepts/organization_user_roles). Smart Inbox, Daily Chew, Meeting Prep, and texting Gumball each have their own permission that cascades from Gumball access — turning off Gumball access for a role turns off all four.
<Warning>For **custom roles**, Smart Inbox, Daily Chew, Meeting Prep, and Gumball text messaging are **restricted by default**. An admin has to grant them explicitly.</Warning>
If your access is removed while Smart Inbox is running, Gumball turns it off. If the restriction is later lifted, you need to re-enable it yourself — it doesn't resume on its own.
***
## FAQ
<AccordionGroup>
<Accordion title="What's the difference between Gumball and a custom agent?" icon="compass">
Gumball is personal and automatic — one per user, created for you, and it searches every skill you can access, including your teams' skills, instead of using a fixed list of attached skills. Custom agents are built by you, shared with your team, and only see the skills, tools, and instructions you configure on them. Gumball is also the only agent with Smart Inbox, Daily Chew, and Meeting Prep.
</Accordion>
<Accordion title="Can I share Gumball, or see a teammate's?" icon="users">
No. Gumball is scoped to its owner. Everyone gets their own, and no one else can view or configure it. If you want a shared assistant, build a [custom agent](/core-concepts/agents).
</Accordion>
<Accordion title="How do I chat with Gumball in Slack?" icon="slack">
DM the Gumloop app in your Slack workspace — find it in your sidebar or under **Apps** and start typing. No setup, no channel, no `@mention`. The **Slack** row on the Gumball home screen opens that DM for you.
</Accordion>
<Accordion title="Can I DM a custom agent instead of Gumball?" icon="comments">
Not through the standard Gumloop app — DMs there always go to your own Gumball, and custom agents are added to channels. To DM a custom agent, connect a [Custom Slack App](/core-concepts/custom_slack_app#direct-messages-dms) for it.
</Accordion>
<Accordion title="Gumball says it needs updated Slack permissions. What now?" icon="key">
Your workspace's Gumloop Slack app was installed before DM support and is missing the direct-message permissions. A workspace admin needs to reconnect the Gumloop Slack app from the [Connectors page](https://www.gumloop.com/settings/profile/connectors?view=connected). Channel agents keep working in the meantime.
</Accordion>
<Accordion title="Can I change Gumball's email address?" icon="envelope">
No. `gumball@gumloop.ai` is reserved for the personal agent and can't be renamed, disabled, or claimed by a custom agent.
</Accordion>
<Accordion title="Can the Daily Chew or Meeting Prep change something in my apps?" icon="lock">
No. Both run read-only. Only tools that read data are available during a run — anything that writes, sends, or modifies is blocked, including write tools reached indirectly through another tool.
</Accordion>
<Accordion title="One of my apps was down during a run. Do I lose that day's updates?" icon="triangle-exclamation">
No. Each source is tracked separately, and Gumball only advances its position for the sources that succeeded. The failed source is reported as failed for that run and its missed items show up in the next one.
</Accordion>
<Accordion title="What does the Daily Chew cover on its very first run?" icon="hourglass-start">
The previous 16 hours. Every run after that covers everything since the last successful run.
</Accordion>
<Accordion title="I left the connector list empty. What gets included?" icon="plug">
Everything you have connected at the time the report runs. That's the same as choosing **All connectors** — and it means newly connected apps are picked up automatically.
</Accordion>
<Accordion title="Does Smart Inbox work with Outlook?" icon="inbox">
Yes. Connect either a Gmail or an Outlook mailbox. On Outlook your labels become Outlook **categories** instead of Gmail labels, and the only behavioural differences are that categories can't be renamed on existing mail and that moving mail out of your Inbox needs the archive permission. Gumball watches one mailbox at a time, so connecting Outlook replaces a connected Gmail account.
</Accordion>
<Accordion title="Will Smart Inbox label the email that's already sitting in my inbox?" icon="clock-rotate-left">
No. Classification happens as email arrives, so only mail received after you enable it gets labelled. The same applies to changes: editing or adding a label affects future email, never mail that's already been classified.
</Accordion>
<Accordion title="I renamed a label — what happens to email that already had it?" icon="tag">
On Gmail the rename is applied to the label itself, so existing mail keeps the label under its new name. On Outlook categories can't be renamed, so the new name is used for future mail and older mail keeps the old category. Definitions, colours, and group changes only affect new mail on either provider.
</Accordion>
<Accordion title="Why did a message stay in my Inbox even though it got a 'move out' label?" icon="arrow-right-to-bracket">
Because another label on the same message was in the "Keep these in my Inbox" group. Keep always wins — a message only leaves your Inbox when every label applied to it says move.
</Accordion>
<Accordion title="Why didn't Gumball label an email at all?" icon="circle-question">
Most often one of three reasons: the **Existing labels** toggle is on and you had already labelled or categorised that message yourself; none of your label definitions matched confidently enough; or the message arrived before Smart Inbox was enabled.
</Accordion>
<Accordion title="Can Smart Inbox send emails for me?" icon="paper-plane">
No. It only creates drafts in your mailbox. Sending is always your action.
</Accordion>
<Accordion title="Why was no draft created?" icon="pen">
Usually one of these: **Draft replies** is set to **Off**; the latest ask wasn't aimed at you; there was nothing to reply to (an FYI, a mention, a notification, a meeting notice); your **Drafting instructions** say to ignore that kind of mail; the sender is a no-reply, newsletter, or system address; the message was a calendar invite with no note from the organizer; Gumball wasn't confident in the reply it produced; your organization's app rules block draft creation; or you had edited Gumball's previous draft in that thread and it declined to overwrite it. Labeling still works, and you can always ask Gumball for a reply in chat.
</Accordion>
<Accordion title="What happens to my labels if I disconnect my mailbox?" icon="link-slash">
Gumball forgets what it labelled and drops its links to the native labels or categories. Those stay in your mailbox on the mail that already has them, and if you reconnect, Gumball re-adopts the ones with matching names.
</Accordion>
<Accordion title="Does Meeting Prep work with Outlook Calendar?" icon="calendar">
Yes. Connect either a Google Calendar or an Outlook Calendar account, pick the calendar to watch, and everything else — automatic prep, **Prepare now**, meeting scope, and the brief itself — works the same way.
</Accordion>
<Accordion title="Why didn't Meeting Prep run for a meeting on my calendar?" icon="calendar-xmark">
The most likely reason is **External meetings only** — a meeting is only external if at least one guest besides you has a different email domain. Also check that automatic prep is on and that the meeting starts further out than your **Minutes Before Event** setting. If the calendar connection and event are available, you can also use **Prepare now**.
</Accordion>
<Accordion title="Meeting Prep says my calendar needs reconnecting" icon="plug">
Reconnect the calendar account if the connection needs reconnecting. If the calendar is unavailable to the connected account, check that account's calendar permissions. If the calendar is not found, choose another calendar. If the event is not found, refresh; it may have been removed or cancelled. Temporary unavailability should be retried later.
</Accordion>
<Accordion title="Can I still prep a meeting with automatic prep switched off?" icon="hand-pointer">
Yes. Turning it off only stops Gumball firing on its own. Meetings still appear on the home screen and **Prepare now** works normally.
</Accordion>
<Accordion title="Do reports get delivered twice if something is retried?" icon="rotate">
No. Each run has a single delivery boundary, so an internal retry can't produce a duplicate report.
</Accordion>
<Accordion title="Where do reports go?" icon="inbox">
Always into Gumball, where they're kept in history. **Email**, **Slack DM**, and **Text message** are optional on top of that. Text messages go to your verified phone number. Slack DMs are matched to you by your account email — if there's no email on your profile, the Slack DM is recorded as not sent and the report is still saved.
</Accordion>
<Accordion title="Why isn't an important item shown as a Situation?" icon="list-check">
Situations are deliberately narrow: they need work you own with a concrete outcome Gumball could take on. Notifications, mentions, and general activity aren't enough on their own.
</Accordion>
<Accordion title="Does editing a Situation step send it?" icon="pen">
No. Editing only saves the prompt and any @mentions you changed. The edited text is used when the step is sent.
</Accordion>
<Accordion title="Does each Situation step become its own chat?" icon="comments">
No. **Send to Gumball** sends the entire Situation as one plan, with all steps in order in a single chat.
</Accordion>
<Accordion title="What if I send the same Situation twice?" icon="rotate">
You get the existing chat back instead of a second chat.
</Accordion>
<Accordion title="Why can't I send this Situation?" icon="circle-question">
A Situation with no nested steps cannot be sent as a plan. Use **Mark handled** or **Dismiss** instead.
</Accordion>
<Accordion title="Do these features cost credits?" icon="coins">
Yes. Classifying email, drafting replies, and generating reports use models and tools like any other agent activity. See [Credits](/core-concepts/credits).
</Accordion>
<Accordion title="My admin restricted Gumball and then unrestricted it. Why isn't Smart Inbox running?" icon="shield-halved">
Smart Inbox is switched off when access is removed and does not resume automatically. Re-enable it from the Smart Inbox tab.
</Accordion>
</AccordionGroup>
# Hosted Pages
Source: https://docs.gumloop.com/core-concepts/hosted_pages
Give your agent a standalone page on gumloopagents.com that anyone can open directly.
Hosted Pages let you publish your agent on a dedicated URL at `gumloopagents.com`. Instead of sharing access to the Gumloop builder, you give people a clean, focused chat interface where they can interact with your agent directly.
<CardGroup>
<Card title="Dedicated URL" icon="globe">
Each agent gets its own `your-agent.gumloopagents.com` link that people can bookmark and open directly.
</Card>
<Card title="Focused chat surface" icon="comment">
People use the agent from a standalone chat page instead of navigating through the Gumloop builder.
</Card>
<Card title="No separate app needed" icon="wand-magic-sparkles">
The hosted page uses the same agent instructions and tools you already configured in Gumloop.
</Card>
<Card title="Control access anytime" icon="toggle-on">
Update the URL alias or disable the hosted page whenever you want.
</Card>
</CardGroup>
***
## Setting up a hosted page
<Steps>
<Step title="Open the Hosted Page Channel">
Open **Channels** in the agent sidebar, then select **Hosted Page**.
<Frame>
<img alt="Channels page with Hosted Page selected, showing the gumloopagents.com URL and Disable Hosted Page" />
</Frame>
</Step>
<Step title="Enable the hosted page">
Click **Enable Hosted Page**. Gumloop automatically generates a URL alias based on your agent's name. The alias follows the format:
```text theme={"dark"}
your-agent-name.gumloopagents.com
```
You can copy the URL using the copy button, or click the pencil icon to customize the alias.
</Step>
<Step title="Share the link">
Share the hosted page URL with anyone who needs to use the agent. When they open the link, they'll see a standalone chat interface with your agent's name and icon.
<Frame>
<img alt="Hosted page chat interface showing the agent name, tools, and message input" />
</Frame>
</Step>
</Steps>
***
## Customizing the URL alias
You can change the hosted page alias at any time:
1. Click the pencil icon next to the current URL
2. Type your desired alias (3-64 characters, lowercase letters, numbers, and hyphens only)
3. Press **Enter** or click the checkmark to save
The alias must be unique across all Gumloop agents. If the alias you want is already taken, you'll need to choose a different one.
<Info>Certain aliases like `admin`, `api`, `app`, `auth`, `beta`, `docs`, `gumstack`, `help`, `localhost`, `mcp`, `sandbox`, `staging`, `support`, `ws`, and `www` are reserved and cannot be used.</Info>
***
## Authentication and sign-in
Hosted pages require users to sign in before they can chat with the agent. Here's how the authentication flow works:
1. A visitor opens the hosted page URL (e.g., `your-agent.gumloopagents.com`)
2. The page resolves the agent alias and loads the agent's profile (name, icon, tools)
3. The visitor is prompted to sign in through Gumloop's authentication
4. After signing in, a secure one-time session token is exchanged, and the visitor is redirected back to the hosted page with full chat access
<Info>The sign-in session is scoped to the hosted page domain. Authentication uses a secure broker flow where credentials never pass through the hosted subdomain directly.</Info>
***
## Permissions and access
Hosted pages use the same permission system as the rest of Gumloop. Each role determines what a user can do both on the hosted page itself and in the configuration panel within the Gumloop builder.
| Role | Hosted page | Builder configuration | Task history |
| - | - | - | - |
| **Owner** | Start tasks with the agent | Enable/disable the hosted page, change the alias | Every task on the agent |
| **User** | Start tasks with the agent | No access | Follows the agent's [Task Visibility](/core-concepts/agent_access#task-visibility) |
<Info>Seeing other people's tasks needs **Team tasks** visibility *and* membership of the agent's team. Someone shared into an agent one-to-one always sees only their own tasks.</Info>
The hosted page chat interface automatically hides features that aren't relevant for the surface:
* **No configuration panel**: Users cannot see or modify agent settings from the hosted page
* **No external channel management**: The sidebar for Email, Slack, and other channels is hidden
* **No app-level navigation**: The hosted page doesn't show the Gumloop builder navigation
Users can still share individual task links directly from the hosted page.
Only an **Owner** of the agent can enable, disable, or modify the hosted page configuration. Organization administrators can also restrict hosted pages through [App Rules](/enterprise-features/app-policies/app-rules) if needed.
***
## Credits and billing
Conversations on hosted pages consume credits the same way as regular agent chats in the Gumloop builder. The credit cost depends on:
* **AI model usage**: Token consumption based on the model your agent uses
* **Tool calls**: Each MCP integration call costs credits
* **Conversation length**: Longer conversations with more context use more tokens
Credits are charged to the **account of the person chatting**. For team agents where users belong to the same organization, credits come from the shared organization credit pool. If a user outside your organization has been shared into the agent, their usage is deducted from their own credit balance.
<Tip>Monitor credit usage from the [Credits](/core-concepts/credits) page. If you're sharing hosted pages widely, consider setting up credit alerts.</Tip>
***
<span />
## Connectors and accounts
Hosted pages use the same connector account settings as Gumloop chat. By default, the agent uses the **chatting user's own connected accounts**. Shared team accounts and explicitly [agent-owned accounts](/core-concepts/credentials#agent-owned-credentials) follow the agent's configuration. This means:
* **Connectors** (Gmail, Slack, Salesforce, etc.) use the chatting user's connected accounts
* **API keys** (BYOK or platform-provided) are resolved from the chatting user's account
If a hosted page user hasn't connected a required integration (e.g., Google Docs), they will be prompted to connect it before the agent can use that tool on their behalf.
<Warning>Make sure hosted page users understand which connected accounts the agent uses, especially if a connector uses a shared team or agent-owned account.</Warning>
***
## Disabling a hosted page
To disable a hosted page:
1. Navigate to the **Hosted Page** channel in your agent's sidebar
2. Click **Disable Hosted Page** in the status section
Disabling the hosted page immediately makes the URL inaccessible. The alias reservation is preserved, so if you re-enable later, you can use the same alias (unless it's been claimed by another agent in the meantime).
***
## FAQ
<AccordionGroup>
<Accordion title="Can I use a custom domain for my hosted page?">
Hosted pages are currently served on the `gumloopagents.com` domain only. Custom domains are not supported at this time.
</Accordion>
<Accordion title="Do hosted page users need a Gumloop account?">
Yes. Users are prompted to sign in when they first visit a hosted page. If they don't already have a Gumloop account, one is created during the sign-in process. This ensures secure access and proper credit tracking.
</Accordion>
<Accordion title="Can I restrict who can access the hosted page?">
Access is controlled through Gumloop's standard sharing and permissions system. Someone needs at least **User** access to the agent. That can come from being shared into the agent directly, being a member of the agent's team, or from the agent's General Access setting. Organization admins can also restrict hosted pages entirely via App Rules.
</Accordion>
<Accordion title="What happens to existing conversations if I change the alias?">
Changing the alias updates the URL. Existing conversations are preserved in the agent's chat history and remain accessible to users who sign in again on the new URL.
</Accordion>
<Accordion title="Is the hosted page available on mobile?">
Yes. The hosted page is a responsive web interface that works on mobile browsers. Users can open the URL on any device and interact with the agent.
</Accordion>
<Accordion title="Can I embed the hosted page in my own website?">
Hosted pages are designed to be opened as standalone pages at their `gumloopagents.com` URL. Embedding via iframe is not officially supported. If you need to embed an agent in your own site, consider using the [Gumloop API](/api-reference/running-an-agent/start-agent) to build a custom integration.
</Accordion>
<Accordion title="Who pays for credit usage on hosted pages?">
Credits are charged to the person chatting. For team agents where all users are in the same organization, this comes from the shared organization credit pool. Users outside the organization use their own credits.
</Accordion>
<Accordion title="What's the difference between the hosted page and sharing the agent?">
Sharing an agent gives someone access through the Gumloop builder, where they see the full navigation and configuration options. A hosted page provides a standalone, distraction-free chat surface at a dedicated URL. Use hosted pages when you want people to interact with your agent without needing to navigate the Gumloop platform.
</Accordion>
<Accordion title="Can I see all conversations happening on my hosted page?">
Owners see every task. A **User** sees other people's tasks only on a team agent whose [Task Visibility](/core-concepts/agent_access#task-visibility) is set to **Team tasks** and only if they are on that team. Everyone else, including hosted page visitors, sees only their own.
</Accordion>
<Accordion title="How do hosted pages work for team agents?">
For agents in a team workspace, any workspace member with the appropriate role can access the hosted page. Organization admins automatically get Owner-level access. Members of the agent's workspace project inherit their project-level role. The agent's tools and integrations remain the same regardless of who is chatting.
</Accordion>
</AccordionGroup>
# Human in the Loop
Source: https://docs.gumloop.com/core-concepts/human_in_the_loop
Keep humans in control of your AI agents with tool approval settings, app rules, and the Ask Question ability.
<div>
<iframe title="Human in the Loop" />
</div>
Human in the Loop lets you decide **exactly** when your agent needs to pause and ask for permission before taking an action. Instead of blindly trusting every tool call, you can require approval for sensitive operations like sending emails, creating repositories, or deleting records.
Your agent works autonomously on low-risk tasks, while you stay in control of the high-stakes ones.
***
## How it works
<Steps>
<Step title="Agent pauses">
When the agent tries to use a tool that requires approval, it stops and shows you exactly what it wants to do: the tool, the arguments, and the intent.
</Step>
<Step title="You get notified">
You receive an approval request via in-app notification, Slack DM, or directly in the chat thread.
</Step>
<Step title="You approve or reject">
If approved, the agent continues from where it left off. If rejected, it acknowledges the rejection and adjusts its approach.
</Step>
</Steps>
The agent never executes a gated tool call without your explicit go-ahead.
***
## Setting up approval controls
<Tabs>
<Tab title="App-level settings">
The most common approach. When you add a connector (like GitHub, Gmail, or Slack) to your agent, you can configure its **Approval Settings** to control when the agent needs permission.
Open your agent's configuration, find the connector in the **Connectors** list, and click the approval icon next to it.
<Frame>
<img alt="Approval Settings dropdown showing Always allow, Ask each time, Ask for writes/deletes, Never allow, and Custom options" />
</Frame>
| Mode | What it does |
| - | - |
| **Always allow** | The agent can use all tools from this app without asking. This is the default. |
| **Ask each time** | Every tool call requires your approval, whether it reads or writes data. |
| **Ask for writes/deletes** | Read-only tools run freely. Write, delete, and unknown-risk operations require approval. |
| **Never allow** | Prevents every tool from this connector from running. |
| **Custom** | Set approval requirements on a per-tool basis. You control each tool individually. |
<Tip>**"Ask for writes/deletes"** is a great default for most apps. It lets your agent gather information freely while keeping you in the loop for any changes.</Tip>
<Note>Every connector's tools are sorted into read-only and write when the connector is added, so **Ask for writes/deletes** works the same way on a custom or self-hosted connector as it does on Gmail or GitHub. If a tool is grouped in a way you disagree with, use **Custom** and set that one tool yourself.</Note>
</Tab>
<Tab title="Per-tool custom">
When you select **Custom** as the approval mode, you unlock per-tool controls. Open the app's detail view to see the **Tool Management** section.
<Frame>
<img alt="GitHub app detail view showing Tool Management with Read-only tools and Write/delete tools groups" />
</Frame>
Tools are grouped by risk level: **Read-only tools** (fetch data) and **Write/delete tools** (modify or create data). Each group can be set to **Always allow** or **Custom**.
When a group is set to Custom, you configure each individual tool:
<Frame>
<img alt="Per-tool approval settings showing individual tools with Always allow, Ask each time, and Never allow options" />
</Frame>
| Icon | Mode | What it does |
| - | - | - |
| <Icon icon="check" /> (checkmark) | **Always allow** | Runs without asking. |
| <Icon icon="hand" /> (hand) | **Ask each time** | Always requires approval. |
| <Icon icon="ban" /> (block) | **Never allow** | Completely blocked from use. |
For example, you might allow "Add Comment To Issue" freely, require approval for "Create Repository", and block "Delete Repository" entirely.
</Tab>
<Tab title="App Rules (CEL)">
App Rules let you define **conditional** approval requirements using [CEL expressions](https://cel.dev/) that evaluate the actual arguments of each tool call. For example: "Require approval only when the email recipient is outside my company domain."
You can create rules in two ways:
<AccordionGroup>
<Accordion title="Via the agent's chat" icon="message">
Ask your agent to create a rule in natural language. The agent translates it into a CEL condition and presents it for your approval.
<Frame>
<img alt="Agent creating an approval rule for non-gumloop.com email recipients via chat, showing the CEL condition" />
</Frame>
</Accordion>
<Accordion title="Via the app config UI" icon="gear">
Open the app's detail view and use the **Rules** section to create rules manually.
<Frame>
<img alt="Gmail app configuration showing the Rules section with an active 'Approve external email recipients' rule" />
</Frame>
</Accordion>
</AccordionGroup>
<Info>App Rules require the **App Rules Creation** ability to be enabled on your agent if you want the agent to create rules via chat. You can always create rules manually through the config UI. For a deeper dive, see the [App Rules documentation](/enterprise-features/app-policies/app-rules).</Info>
</Tab>
<Tab title="Ask question">
The **Ask Question** ability is different from the approval settings above. Instead of gating tool calls, it lets your agent proactively ask you a question when it needs input to continue.
<Frame>
<img alt="Agent Abilities section showing the Ask Question toggle set to ON" />
</Frame>
When enabled, the agent can present you with structured choice cards (toggle groups, multi-select options) to gather your preference before proceeding. Useful for decisions like "Which template should I use?" or "Which of these three options do you prefer?"
Every choice card also carries a standard **Other** option with a free-text box, so you are never forced into one of the listed answers. It is always worded the same way and the agent cannot rename or remove it — pick it and type what you actually want.
Toggle this on in your agent's **Abilities** section.
<Tip>**Ask Question** is great for open-ended tasks where the agent might need clarification. It lets the agent pause naturally and ask for your input rather than guessing.</Tip>
</Tab>
</Tabs>
***
## Where you get notified
When an agent pauses for approval, you are notified in multiple places so you never miss it.
<Tabs>
<Tab title="In the chat">
The approval card appears directly in the conversation with the tool name, intent, arguments, and **Approve** / **Reject** buttons. Use **⌘ + Enter** to quickly approve.
<Frame>
<img alt="Approval card in the web chat showing an email send request with To, Subject, and Body fields, plus Reject and Approve buttons" />
</Frame>
The card includes:
* **Tool name and icon** at the top (e.g. "Approve Send Email" with the Gmail icon)
* **Intent** describing what the agent is trying to do
* **Display fields** showing the key arguments (e.g. To, Subject, Body)
* **Reject** and **Approve** buttons
* **"Don't ask again for this tool"** checkbox to remember your decision for future calls
</Tab>
<Tab title="Notification bell">
The in-app notification bell lights up with a badge count. Approve or reject directly from the inbox without opening the conversation.
<Frame>
<img alt="Notification bell inbox showing two pending approval requests from the Doc Updater agent with Approve buttons" />
</Frame>
Quickly approve or reject from here. The inbox also has a **Resolved** tab to review past decisions.
</Tab>
<Tab title="Tasks page">
The [Tasks page](https://www.gumloop.com/personal/tasks?status=approval_required) has an **Approval Required** filter showing every pending approval across all your agents in one place.
<Frame>
<img alt="Tasks page filtered by Approval Required status, showing a pending email send task from the Brain agent" />
</Frame>
A centralized queue for everything that needs your attention, especially useful when you have multiple agents running.
</Tab>
<Tab title="Slack">
For Slack-connected agents, approval buttons appear directly in the Slack thread. You get **Approve**, **Reject**, and **Open in Gumloop** buttons right in Slack.
<Frame>
<img alt="Slack thread showing an approval request with Approve, Reject, and Open in Gumloop buttons" />
</Frame>
If you are not watching the thread, you also receive a **Slack DM** so nothing gets missed. Click **Open in Gumloop** to see the full context in the web app.
</Tab>
</Tabs>
***
## Example walkthroughs
<AccordionGroup>
<Accordion title="Approving a GitHub tool call" icon="code-branch">
<Steps>
<Step title="Configure the app">
Open your agent's config, find GitHub in the Apps list, and set the approval mode to "Ask each time" (or "Ask for writes/deletes" if you only want to gate mutations).
</Step>
<Step title="Ask your agent to do something">
For example: *"Please create a PR on the docs repo to change the title of the agents skills doc page to just 'Skills'."*
</Step>
<Step title="The agent pauses for approval">
Before executing the GitHub API call, it shows you an approval card with the details:
<Frame>
<img alt="Approval card for a GitHub tool call showing the intent, query, and Don't ask again checkbox with Reject and Approve buttons" />
</Frame>
</Step>
<Step title="Review and decide">
Check the arguments. If everything looks right, click **Approve**. If something is off, click **Reject** and optionally provide a reason.
</Step>
<Step title="The agent continues">
After approval, the agent picks up right where it left off and completes the task.
</Step>
</Steps>
</Accordion>
<Accordion title="Creating a conditional rule via chat" icon="shield-check">
<Steps>
<Step title="Enable the App Rules Creation ability">
Toggle it on in your agent's Abilities section.
</Step>
<Step title="Ask your agent to create a rule">
For example: *"Create a human approval rule for any email that is sent to users without the gumloop.com domain."*
</Step>
<Step title="The agent builds the rule">
It generates the appropriate CEL expression and shows you the rule details:
<Frame>
<img alt="Agent creating a Gmail approval rule with a CEL condition that checks To/CC/BCC recipients for non-gumloop.com domains" />
</Frame>
</Step>
<Step title="Approve the rule">
Once you approve, the rule is live. You can see it in the app's config:
<Frame>
<img alt="Gmail app configuration showing the newly created approval rule for external email recipients" />
</Frame>
</Step>
<Step title="The rule takes effect immediately">
Whenever the agent sends email to a non-gumloop.com address, it pauses for approval. Internal emails go through without interruption.
<Frame>
<img alt="Approval card showing the agent pausing to approve sending an email to an external recipient after the rule takes effect" />
</Frame>
</Step>
</Steps>
</Accordion>
</AccordionGroup>
***
## What happens when you reject
When you reject a tool call:
* The agent receives the rejection (and your optional reason).
* It does **not** execute the tool.
* It continues the conversation, often suggesting an alternative approach or asking for clarification.
Rejections are non-destructive. The agent simply adapts and tries a different path.
***
## Approval modes at a glance
| Mode | Scope | Best for |
| - | - | - |
| **Always allow** | App-level | Trusted, low-risk apps (e.g. read-only integrations) |
| **Ask each time** | App-level | High-sensitivity apps where every action matters |
| **Ask for writes/deletes** | App-level | Most apps, letting reads flow freely and gating mutations |
| **Custom** | Per-tool | Fine-grained control over individual tools within an app |
| **App Rules** | Conditional (CEL) | Context-dependent approvals based on tool arguments |
| **Ask Question** | Ability | Agent-initiated questions for gathering user input |
***
## FAQ
<AccordionGroup>
<Accordion title="Does the agent time out while waiting for approval?">
No. When an agent pauses for approval, it saves its full state. It can wait indefinitely for your response. When you approve or reject, it resumes exactly where it left off.
</Accordion>
<Accordion title="Can I approve from Slack without opening the web app?">
Yes. If your agent is connected to Slack, approval buttons appear directly in the Slack thread and in a Slack DM. You can approve or reject right from Slack. You can also click "Open in Gumloop" to see the full context in the web app.
</Accordion>
<Accordion title="What does "Don't ask again for this tool" do?">
When you check this box before approving, the agent remembers your decision for that specific tool. Future calls to the same tool will be auto-approved without asking. This preference is saved to the agent's configuration. You can always change it later in the app's Tool Management settings.
</Accordion>
<Accordion title="Can I set different approval requirements for different team members?">
Approval settings are configured at the agent level and apply to all users interacting with that agent. For organization-wide policies that apply across all agents, use [App Rules](/enterprise-features/app-policies/app-rules) in your organization settings.
</Accordion>
<Accordion title="What's the difference between App Rules and Approval Settings?">
**Approval Settings** are simple toggles: always allow, ask each time, ask for writes, or custom per-tool. They apply based on the tool's risk category (read vs. write).
**App Rules** are conditional. They use CEL expressions to inspect the actual arguments of a tool call and decide whether to require approval. For example, "only require approval when the email recipient is outside my domain" is something only App Rules can do.
Both can work together. Approval Settings act as the baseline, and App Rules add conditional overrides on top.
</Accordion>
<Accordion title="Where can I see all pending approvals across my agents?">
The [Tasks page](https://www.gumloop.com/personal/tasks?status=approval_required) has an **Approval Required** filter that shows every pending approval across all your agents in one place. You can also use the notification bell in the top-right corner of the app for a quick glance.
</Accordion>
<Accordion title="What happens if I reject a tool call?">
The agent does not execute the rejected tool. It acknowledges the rejection, and if you provided a reason, it takes that into account. The agent then continues the conversation, often adjusting its approach or asking for clarification.
</Accordion>
<Accordion title="Can my agent create App Rules on its own?">
Yes, if you enable the **App Rules Creation** ability in your agent's Abilities section. The agent can translate natural-language instructions into CEL conditions. The rule creation itself also requires your approval before it takes effect.
</Accordion>
<Accordion title="Does Human in the Loop work with sandbox (code execution) tools?">
Yes. When an agent needs to run code in the sandbox (Python or shell), the approval card shows a preview of the code it wants to execute. You can review the exact script before approving. If the code makes MCP tool calls (e.g., sending an email via Gmail), those nested calls are listed in the approval card as well.
</Accordion>
</AccordionGroup>
# Okta integration
Source: https://docs.gumloop.com/core-concepts/okta-integration
This guide is for **organization administrators** who want to configure Okta as the authentication provider for Gumloop. By following these steps, you'll register Gumloop as an application in your Okta environment, enabling your organization members to authenticate with Gumloop-connected services (like Snowflake and NetSuite) using your existing Okta identity infrastructure.
<Note>
**Intended Audience:** Okta administrators and Gumloop organization administrators. This setup is performed once at the organization level and enables Okta authentication for all organization members.
</Note>
## What this guide covers
This documentation walks through two main configuration areas:
1. **Okta Configuration** - Register Gumloop as an OAuth application in your Okta Admin Console
2. **Gumloop Configuration** - Add the Okta OAuth credentials to your organization at [gumloop.com/settings/organization/oauth-configuration](https://www.gumloop.com/settings/organization/oauth-configuration)
Once complete, your organization members will authenticate through Okta instead of managing individual service credentials.
## Overview
Okta integration enables enterprise organizations to leverage their existing identity management infrastructure for Gumloop authentication. Instead of managing separate credentials for each service, users authenticate through Okta, which acts as the central authorization server.
<Note>
**How it works:** This integration connects Gumloop to your Okta environment, allowing Gumloop to use Okta as an authentication provider. For this to work, your external services (Snowflake, NetSuite, Databricks, etc.) must already be configured to accept Okta as an OAuth provider. Gumloop then uses your Okta credentials to authenticate with these Okta-enabled services.
</Note>
<Tip>
**Currently supported services:** Any service that supports Okta External OAuth, including Snowflake, NetSuite, Databricks, etc.
</Tip>
### Why use Okta with Gumloop?
<CardGroup>
<Card title="Centralized authentication" icon="shield-check">
Single sign-on experience across all Gumloop-connected services
</Card>
<Card title="Enhanced security" icon="lock">
Leverage your organization's existing security policies and MFA
</Card>
<Card title="Simplified management" icon="users-gear">
Manage access and permissions from one central location
</Card>
<Card title="Compliance ready" icon="file-certificate">
Meet enterprise security and compliance requirements
</Card>
</CardGroup>
***
## How it works
When Okta is configured for Gumloop, authentication follows this flow:
```mermaid theme={"dark"}
sequenceDiagram
participant User
participant Gumloop
participant Okta
participant Service as External Service<br/>(Snowflake, NetSuite, etc.)
User->>Gumloop: Initiate authentication
Gumloop->>Okta: Redirect to Okta login
User->>Okta: Authenticate with credentials
Okta->>Okta: Verify user & permissions
Okta->>Gumloop: Return access token
Gumloop->>Service: Request data using Okta token
Service->>Okta: Verify token
Okta->>Service: Token valid
Service->>Gumloop: Return requested data
Gumloop->>User: Display results
```
<Note>
Okta acts as the intermediary between Gumloop and external services. Instead of Gumloop directly authenticating with services like Snowflake, it uses the access token from Okta to verify the user's identity and permissions.
</Note>
***
## Prerequisites
Before configuring Okta for Gumloop, ensure you have:
<Steps>
<Step title="Okta Admin access">
You must have administrator privileges in your Okta organization to create applications and authorization servers.
</Step>
<Step title="External services pre-configured with Okta">
**Critical:** Each service you want to use with Gumloop (e.g., Snowflake, NetSuite, Databricks) must already be configured to use Okta as an External OAuth provider. This is a separate configuration done within each service's settings, not in Gumloop.
<Warning>
**Important:** The Okta integration in Gumloop acts as a connection layer between Gumloop and your Okta-enabled services. It does NOT automatically enable OAuth for services. Each service must be independently configured to trust Okta for authentication before you can use it through Gumloop.
For example:
* **Snowflake:** Must be configured with Okta External OAuth in Snowflake settings
* **NetSuite:** Must have Okta OAuth integration enabled in NetSuite
* **Other services:** Check each service's documentation for "Okta OAuth" or "External OAuth" configuration
</Warning>
Without this prerequisite, authentication will fail even if Gumloop and Okta are properly connected.
</Step>
<Step title="Gumloop organization">
Your organization must be on an Enterprise plan and you must be an organization admin so you can access the [OAuth Configuration page](https://www.gumloop.com/settings/organization/oauth-configuration).
</Step>
</Steps>
***
## Configuration procedure
The setup process involves three main stages: creating the Gumloop OAuth client, configuring an authorization server, and collecting the necessary information.
<Warning>
**Important:** The steps below are representative examples for configuring Okta for External OAuth. You can configure Okta to any desired state and use any desired OAuth flow, provided you can obtain the necessary information for Gumloop's OAuth Configuration page.
Always consult your internal security policies when configuring an authorization server to ensure your organization meets all necessary regulations and compliance requirements.
</Warning>
### Step 1: Create an OAuth client for Gumloop
First, you'll create an OAuth-compatible client application in Okta that represents Gumloop.
<Steps>
<Step title="Navigate to Applications">
1. Log in to the **Okta Admin Console**
2. Click **Applications** in the left sidebar
3. Click **Create App Integration**
</Step>
<Step title="Select application type">
1. For **Sign-in method**, select **OIDC - OpenID Connect**
2. For **Application type**, select **Web Application**
3. Click **Next**
</Step>
<Step title="Configure application settings">
Enter the following details:
* **App integration name:** `Gumloop`
* **App logo:** (Optional) Upload the Gumloop logo using [this link](https://canada1.discourse-cdn.com/flex027/uploads/gumloop/original/1X/d02ff8efcde6ac5d3ac8aa0376137d5f804da549.png)
* **Sign-in redirect URIs:** `https://api.gumloop.com/auth/callback`
* **Sign-out redirect URIs:** (Leave blank)
* **Controlled access:** Choose based on your organization's needs (typically "Allow everyone in your organization to access")
Click **Save**
<Tip>
Adding the [Gumloop logo](https://canada1.discourse-cdn.com/flex027/uploads/gumloop/original/1X/d02ff8efcde6ac5d3ac8aa0376137d5f804da549.png) helps your users easily identify the application in their Okta dashboard and during authentication flows.
</Tip>
<Note>
You'll configure the grant types in the next step after the application is created.
</Note>
</Step>
<Step title="Configure grant types">
After saving, scroll to the **Grant type** section and click **Edit**:
1. Under **Client acting on behalf of itself**, check:
* **Client Credentials**
2. Under **Core grants**, ensure the following are checked:
* **Authorization Code**
* **Refresh Token**
3. Click **Save**
<Info>
Client Credentials grant type enables the application to authenticate on its own behalf, which is required for Gumloop's OAuth flow.
</Info>
</Step>
<Step title="Save client credentials">
After configuring grant types, scroll down to the **Client Credentials** section. You'll see:
* **Client ID** - Save this value (you'll need it as `<OAUTH_CLIENT_ID>`)
* **Client secret** - Click **Show secret** to reveal, then save this value (you'll need it as `<OAUTH_CLIENT_SECRET>`)
<Warning>
Keep these credentials secure. You'll need them when configuring Gumloop's OAuth Configuration page. The client secret is only shown once, so make sure to copy it now.
</Warning>
</Step>
</Steps>
### Step 2: Create an authorization server
Next, set up an authorization server that will handle authentication requests for Gumloop.
<Steps>
<Step title="Access authorization servers">
1. In the **Okta Admin Console**, navigate to **Security** > **API**
2. Click the **Authorization Servers** tab
3. Click **Add Authorization Server**
</Step>
<Step title="Configure server details">
Enter the following information:
* **Name:** `Gumloop Authorization Server` (or your preferred name)
* **Audience:** Your service URL (e.g., `https://abc12345.snowflakecomputing.com` for Snowflake)
* **Description:** Optional description for documentation purposes
Click **Save**
</Step>
<Step title="Save the authorization server ID">
After creating the authorization server, you'll see an **Issuer** URL with a format like:
```text theme={"dark"}
https://your-domain.okta.com/oauth2/aus8x7abc123def
```
The **Authorization Server ID** is the part after `/oauth2/` (in this example: `aus8x7abc123def`). Save this value as `<AUTHORIZATION_SERVER_ID>` - you'll need it for Gumloop configuration.
</Step>
</Steps>
### Step 3: Configure scopes
Scopes define what permissions and data the Gumloop application can access.
<Steps>
<Step title="Add base scopes">
1. In your authorization server, click the **Scopes** tab
2. Click **Add Scope** for each of the following:
| Scope Name | Display Name | Description |
| - | - | - |
| `openid` | OpenID | Required for OpenID Connect authentication |
| `profile` | Profile | Access to user profile information |
| `email` | Email | Access to user email address |
| `offline_access` | Offline Access | Enables refresh tokens for long-term access |
<Tip>
These are the minimum required scopes for Gumloop. Mark each as a **Default scope** so they're automatically included in authentication requests.
</Tip>
</Step>
<Step title="Add service-specific scopes">
In addition to the base scopes, you must add service-specific scopes for each external service you want to use with Gumloop. These scopes define what roles and permissions users can access within each service.
<Warning>
**Important:** Without service-specific scopes, users will be able to authenticate but most operations will fail due to insufficient permissions. Each service requires its own set of scopes.
</Warning>
### Common Service Scope Examples:
**Snowflake:**
* Create scopes for each role users need access to
* **Format:** `session:role:ROLE_NAME` (role names must be uppercase unless created with quotes in Snowflake)
* **Examples:**
* `session:role:PUBLIC` - Basic read access
* `session:role:ANALYST` - Analyst role
* `session:role:DATA_ENGINEER` - Data engineer role
* `session:role-any` - Allows switching between available roles (advanced)
**NetSuite:**
* Add NetSuite-specific role scopes as required by your NetSuite configuration
* Consult your NetSuite OAuth documentation for required scope formats
**Other Services:**
* Refer to each service's External OAuth documentation for required scope formats
* Most services use role-based scopes similar to Snowflake
<Info>
When creating each scope in Okta:
1. Click **Add Scope**
2. **Scope name:** Enter the exact scope (e.g., `session:role:ANALYST`)
3. **Display name:** Enter a user-friendly name (e.g., "Snowflake Analyst Role")
4. **Description:** Add a description for documentation
5. Optionally mark as **Default scope** if all users should have this role
</Info>
<Tip>
You can add more scopes later as your organization's needs grow. Start with the essential roles your users need.
</Tip>
</Step>
</Steps>
### Step 4: Create access policy and rules
Access policies control who can obtain tokens and under what conditions.
<Steps>
<Step title="Create an access policy">
1. In your authorization server, click the **Access Policies** tab
2. Click **Add Policy**
3. Enter the following:
* **Name:** `Gumloop Access Policy`
* **Description:** description
* **Assign to:** Select the Gumloop client application you created earlier
4. Click **Create Policy**
</Step>
<Step title="Add a rule to the policy">
1. In the newly created policy, click **Add Rule**
2. Configure the rule:
* **Rule name:** `Standard Access Rule`
* **Grant type:** Select the following:
* Authorization Code
* Resource Owner Password
* Client Credentials
* Refresh Token
* **User is:** Select based on your organization's needs (typically "Any user assigned the app")
* **Scopes requested:** Select "The following scopes:" and choose:
* `openid`
* `profile`
* `email`
* `offline_access`
* Any service-specific scopes you created
* **Token lifetime:** Configure according to your security policies (defaults are typically sufficient)
3. Click **Create Rule**
</Step>
</Steps>
### Step 5: Collect required information
Now gather all the information you'll need to configure Gumloop.
<Steps>
<Step title="Verify your collected information">
Ensure you have all of the following values before proceeding to configure Gumloop:
| Information Needed | Where to Find It | Your Value |
| - | - | - |
| **Okta Domain** | Your Okta URL (e.g., `company.okta.com`) | `<OKTA_DOMAIN>` |
| **Authorization Server ID** | From Step 2 - the part after `/oauth2/` in the Issuer URL | `<AUTHORIZATION_SERVER_ID>` |
| **Client ID** | From Step 1 - in the Client Credentials section | `<OAUTH_CLIENT_ID>` |
| **Client Secret** | From Step 1 - in the Client Credentials section | `<OAUTH_CLIENT_SECRET>` |
<Note>
These four values are all you need to configure Okta authentication in Gumloop. Make sure you have them ready before proceeding to the next section.
</Note>
</Step>
</Steps>
***
## Configuring Gumloop OAuth configuration
After completing the Okta setup, you'll need to add these credentials to Gumloop so your organization members can use Okta authentication.
<Tip>
This step must be completed by a **Gumloop organization administrator**. Regular users cannot configure OAuth settings for the organization.
</Tip>
<Steps>
<Step title="Navigate to OAuth Configuration">
Go to [gumloop.com/settings/organization/oauth-configuration](https://gumloop.com/settings/organization/oauth-configuration)
</Step>
<Step title="Add Okta OAuth configuration">
1. Find **Okta OAuth Config** in the **Available** list
2. Click **Add**
<Frame>
<img alt="OAuth Configuration page with Okta OAuth Config highlighted in the Available list" />
</Frame>
</Step>
<Step title="Enter Okta details">
Fill in the form with the four values you collected:
* **Okta Domain:** `<OKTA_DOMAIN>` (e.g., `company.okta.com`)
* **Authorization Server ID:** `<AUTHORIZATION_SERVER_ID>` (e.g., `aus8x7abc123def`)
* **Client ID:** `<OAUTH_CLIENT_ID>`
* **Client Secret:** `<OAUTH_CLIENT_SECRET>`
Click **Save**
<Frame>
<img alt="Gumloop Okta OAuth configuration form showing the four required fields" />
</Frame>
</Step>
</Steps>
***
## User authentication flow
Once Okta is configured, here's what the authentication experience looks like for your organization members:
<Tabs>
<Tab title="For organization members" icon="users">
### Standard Authentication Experience
When a user needs to authenticate with a service that uses Okta:
1. Navigate to their [Connectors page](https://www.gumloop.com/settings/profile/connectors?view=connected)
2. Find the service (e.g., Snowflake)
3. Click the **Authenticate** button
4. Get redirected to your organization's Okta login page
5. Enter their Okta credentials
6. Approve the requested permissions (first time only)
7. Get redirected back to Gumloop - authentication complete!
<Tip>
Users don't need to configure anything - they simply authenticate through Okta using their existing credentials. The organization's OAuth configuration is automatically used.
</Tip>
**Step 1**:
<Frame>
<img />
</Frame>
**Step 2**:
<Frame>
<img />
</Frame>
</Tab>
<Tab title="What users see" icon="eye">
### Authentication Options
On the Connectors page, users will see two authentication options:
1. **OAuth/SSO Button** (Enabled) - This uses the organization's Okta configuration
2. **Service Account Credentials** (Disabled) - This option is not available when organization OAuth is configured
The OAuth/SSO option is the primary authentication method, ensuring all users authenticate through your organization's Okta infrastructure.
</Tab>
</Tabs>
***
## Testing your configuration
Before rolling out Okta authentication to your entire organization, verify the setup works correctly.
<Steps>
<Step title="Test user authentication">
1. Have a test user navigate to their [Connectors page](https://www.gumloop.com/settings/profile/connectors?view=connected)
2. Click the authentication button for a configured service
3. Verify they're redirected to Okta
4. Complete the authentication flow
5. Confirm successful authentication in Gumloop
</Step>
<Step title="Test execution">
1. Create a simple agent task using the Okta-authenticated service
2. Run the task
3. Verify it executes successfully using Okta credentials
4. Check that data is retrieved correctly
</Step>
</Steps>
***
## Advanced configuration
### Using ANY role with external OAuth
Some services (like Snowflake) support a special `session:role-any` scope that allows users to switch roles after authentication rather than being locked to a specific role.
<Steps>
<Step title="Add ANY role scope">
In your authorization server, create a scope named `session:role-any` with:
* **Display name:** `Any Role`
* **Description:** `Allows switching between available roles after authentication`
</Step>
<Step title="Configure policy">
Update your access policy rule to include the `session:role-any` scope in the list of allowed scopes.
</Step>
<Step title="User experience">
Users who authenticate with this scope can switch between their assigned roles, providing flexibility for tasks that require different permission levels.
</Step>
</Steps>
### Multiple authorization servers
For complex organizations, you may want separate authorization servers for different environments or services:
<Tabs>
<Tab title="By environment">
**Development vs Production**
Create separate authorization servers:
* `Gumloop Development` - For testing and development
* `Gumloop Production` - For production use
Benefits:
* Separate token lifetimes and policies
* Isolated audit trails
* Different scopes for each environment
</Tab>
<Tab title="By service">
**Service-Specific Servers**
Create authorization servers per integration:
* `Gumloop - Snowflake` - For Snowflake access
* `Gumloop - NetSuite` - For NetSuite access
Benefits:
* Service-specific policies and scopes
* Granular access control
* Easier compliance auditing
</Tab>
</Tabs>
***
## Related documentation
<CardGroup>
<Card title="Connectors" icon="plug" href="/core-concepts/credentials">
Learn about personal, team, and organization credentials
</Card>
<Card title="AI model governance" icon="shield" href="/enterprise-features/ai_model_control">
Configure organization-wide AI model access and routing
</Card>
<Card title="Custom roles" icon="user-tag" href="/enterprise-features/user_groups">
Manage organizational roles and permissions
</Card>
</CardGroup>
***
## Need help?
If you encounter issues during setup or have questions about Okta integration:
* **Email:** [support@gumloop.com](mailto:support@gumloop.com)
* **Okta Support:** For Okta-specific configuration questions, consult [Okta's documentation](https://developer.okta.com/docs/)
# Organization skills
Source: https://docs.gumloop.com/core-concepts/organization_skills
Centrally manage skills for your whole organization, and keep them in sync with a GitHub repository.
**Organization Skills** let admins manage a shared library of [skills](/core-concepts/skills) for the entire organization from one place, and control who can use them.
<div>
<iframe title="GitHub sync" />
</div>
There are two kinds of organization skills:
<CardGroup>
<Card title="Hosted skills" icon="cloud">
Created and stored directly in Gumloop — with AI, by uploading files, or by
writing instructions. Fully editable inside Gumloop.
</Card>
<Card title="GitHub-backed skills" icon="github">
Imported from a GitHub repository and kept in sync automatically. The
repository is the source of truth — you edit these in GitHub, not in Gumloop.
</Card>
</CardGroup>
<Info>
Organization Skills live under **Settings → Organization → Skills**
([gumloop.com/settings/organization/skills](https://gumloop.com/settings/organization/skills)).
</Info>
## Who can use it
<CardGroup>
<Card title="Plan" icon="gem">
Available on **Pro** and **Enterprise** plans.
</Card>
<Card title="Role" icon="user-shield">
Managing organization skills and sources requires the
**Manage Organization Skills** permission, which belongs to the
**Admin** role by default.
</Card>
</CardGroup>
Members without this permission don't manage sources — they simply *use* the skills that have been shared with them or their team, just like any other skill.
## Connect a GitHub repository
GitHub-backed skills are imported from a repository your organization has authorized through the **Gumloop GitHub App**. Connecting a source is a short guided flow.
<Tip>
**How skills are discovered:** every folder that contains a `SKILL.md` file
becomes one skill. Gumloop scans the branch and folder path you select and
imports each such folder as an organization skill.
</Tip>
<Steps>
<Step title="Choose a repository">
Pick the GitHub owner, then select a repository the Gumloop GitHub App can
access. Repositories you haven't used before are authorized for your
organization the first time you select them.
<Frame>
<img alt="Connect wizard step 1: choosing a GitHub repository from the owner dropdown" />
</Frame>
</Step>
<Step title="Choose where skills live">
Select a **branch** (defaults to the repository's default branch) and an
optional **folder path**. Leave the folder path empty to scan the entire
repository.
<Frame>
<img alt="Connect wizard step 2: selecting a branch and optional folder path" />
</Frame>
</Step>
<Step title="Set default access">
Choose who can use skills imported from this source *by default*. You can
grant one or more **teams** a role, and set **general access**:
| General access | Who can use imported skills |
| - | - |
| **Restricted** | Only members of the teams you add |
| **Organization** | Everyone in your organization |
<Frame>
<img alt="Connect wizard step 3: setting default team and general access for imported skills" />
</Frame>
<Warning>
**Restricted with no teams** means imported skills are locked up — nobody
in the organization can use them until you grant team or organization
access later.
</Warning>
</Step>
<Step title="Preview and connect">
Gumloop previews the source and shows how many `SKILL.md` folders it found
on the selected commit. Confirming connects the source and kicks off the
first sync.
</Step>
</Steps>
<Note>
Default access applies to skills the source imports **for the first time**. It
seeds each new skill's access — you can still fine-tune access per skill
afterward (see [Manage access](#manage-who-can-use-skills)).
</Note>
## How syncing works
Once a source is connected, Gumloop keeps its skills in sync with the repository.
<CardGroup>
<Card title="Initial sync" icon="download">
Runs automatically right after you connect the source.
</Card>
<Card title="Automatic sync" icon="rotate">
New commits pushed to the selected branch trigger a sync automatically.
</Card>
<Card title="Manual sync" icon="hand-pointer">
Use **Sync now** on the source's Settings tab to re-import on demand.
</Card>
</CardGroup>
Each sync reads the repository, validates the discovered skills, then adds, updates, or removes skills so Gumloop matches the repository. A sync moves through **queued → scanning → staging → applying → succeeded** (or **failed**).
### Source health
Each connected source shows a health status so you can spot problems at a glance:
| Status | Meaning |
| - | - |
| **Healthy** | Latest sync succeeded and updates are flowing |
| **Importing** | A sync is currently running |
| **Import failed** | The most recent sync failed — check the history for details |
| **Branch missing** | The selected branch no longer exists in the repository |
| **App access unavailable** | The Gumloop GitHub App can no longer access the repository |
| **Webhook updates missing** | Automatic push updates aren't being received; use **Sync now** or reconnect |
## Manage a connected source
Opening a source shows its imported skills on the left and a detail panel with three tabs.
<Tabs>
<Tab title="Overview">
Status, number of skills, last synced time, the current commit, default
access, who connected the source, and 30-day usage.
<Frame>
<img alt="Source Overview tab showing status, skill count, last synced, commit, default access, and usage" />
</Frame>
</Tab>
<Tab title="History">
A record of sync runs with their status, commit, actor, and time. Each run
is inspectable, and you can open the full history.
<Frame>
<img alt="Source History tab listing recent sync runs marked Succeeded with commit and actor" />
</Frame>
</Tab>
<Tab title="Settings">
**Sync now**, **Open repository** on GitHub, edit **default access**, and
**Disconnect** the source.
<Frame>
<img alt="Source Settings tab with Sync now, Open repository, Default access, and Disconnect actions" />
</Frame>
</Tab>
</Tabs>
### Disconnecting a source
When you disconnect a GitHub-backed source, you choose what happens to its skills:
<CardGroup>
<Card title="Keep skills" icon="box-archive">
The skills are kept and converted to hosted skills. Syncing stops, but the
skills remain usable and become editable in Gumloop.
</Card>
<Card title="Remove skills" icon="trash">
The skills imported by this source are removed from the organization.
</Card>
</CardGroup>
## Hosted skills
Hosted skills are created and maintained directly in Gumloop — no repository required. On the Organization Skills page you can create them by:
* **Create with AI** — let AI generate a skill for you
* **Upload files** — upload a skill package (must include a `SKILL.md`)
* **Write skill instructions** — enter a name and description
<Info>
Hosted skills are fully editable in Gumloop. **GitHub-backed skills are
read-only in Gumloop** — edit them in the source repository and let a sync
bring the changes in.
</Info>
## Manage who can use skills
Access can be managed for a whole source's default, or for individual skills.
**Per skill** — use a skill's menu to **Control Access** and choose which teams (and roles) can use it, or make it organization-wide.
**In bulk** — select multiple skills and **Share with teams** or **Share with organization** at once.
<Frame>
<img alt="Selecting multiple organization skills and sharing them with teams or the whole organization in bulk" />
</Frame>
Two roles control what a grant allows:
| Role | What it allows |
| - | - |
| **Use only** | Members can attach and use the skill on agents, but not view its files |
| **Viewer** | Members can also view the skill's files |
The access column marks each skill's visibility — a lock for **restricted** (team-only) skills and a building icon for **organization**-wide skills.
## Use organization skills in agents
Organization skills that are shared with a member appear alongside their own skills. To add one to an agent, open the agent's **Skills** panel, click **Add → Add Existing Skill**, and pick from the **Organization** section.
<Frame>
<img alt="Agent Skills panel Add menu with Create With AI, Upload Files, Write Skill Instructions, and Add Existing Skill" />
</Frame>
<Frame>
<img alt="Add Existing Skill panel showing organization skills available to attach" />
</Frame>
Attached skills show up in the agent's Skills list and are used automatically when relevant.
<Frame>
<img alt="Two organization skills attached to an agent" />
</Frame>
For more on how agents load and apply skills, see [Agent Skills](/core-concepts/skills).
## Limitations
* GitHub-backed skills are **read-only in Gumloop**; edit them in the repository.
* A source tracks **one branch and one folder path**. Point at a different branch or path by connecting another source.
* A new source can't **overlap** the branch and path of an existing source in the same repository.
* Skill discovery is driven entirely by `SKILL.md` — a folder without one is not imported.
* Managing sources and organization skills requires the **Manage Organization Skills** permission (Admin) on a **Pro** or **Enterprise** plan.
## FAQs
<AccordionGroup>
<Accordion title="What makes a folder a skill?">
Any folder containing a `SKILL.md` file, under the branch and folder path you
selected for the source. Each such folder becomes one skill.
</Accordion>
<Accordion title="Do I have to sync manually?">
No. Gumloop syncs automatically after you connect a source and whenever new
commits land on the selected branch. **Sync now** is there for when you want
to re-import immediately.
</Accordion>
<Accordion title="Can I edit a GitHub-backed skill in Gumloop?">
No — those skills are read-only in Gumloop. Make changes in the source
repository and a sync will bring them in. Hosted skills, by contrast, are
fully editable in Gumloop.
</Accordion>
<Accordion title="What happens to skills if I disconnect a source?">
You choose: **keep** them (they convert to hosted skills and stop syncing) or
**remove** them from the organization.
</Accordion>
<Accordion title="Why can't anyone use the skills I just imported?">
The source's default access is likely **Restricted** with no teams, which
locks the skills up. Grant team or organization access from the source's
default access settings or per skill.
</Accordion>
<Accordion title="What's the difference between Use only and Viewer?">
**Use only** lets members attach and use the skill on agents without seeing
its files. **Viewer** additionally lets them view the skill's files.
</Accordion>
<Accordion title="Who can manage organization skills and sources?">
Members with the **Manage Organization Skills** permission — the **Admin**
role by default — on a **Pro** or **Enterprise** plan. Everyone else can use
the skills shared with them.
</Accordion>
</AccordionGroup>
# User roles
Source: https://docs.gumloop.com/core-concepts/organization_user_roles
Composable organization and team roles that determine what each member can do in Gumloop.
<Note>
Organization roles are available on the **Pro plan and above**. Some feature roles and capabilities require the **Enterprise plan**.
</Note>
Gumloop's roles are **additive**. A member can hold **multiple roles per scope** (organization or team), and their effective permissions are the **union** of every role they hold. Every member implicitly holds the baseline **Member** role; layer additional roles on top to grant access to specific areas.
<Info>
For granular, feature-by-feature restrictions (app allowlists, tool restrictions, concurrency limits), see [Custom Roles](/enterprise-features/user_groups). That is a separate, complementary system that restricts what organization roles grant. A user can hold multiple custom roles at the same time.
</Info>
## How it works
<CardGroup>
<Card title="Union of permissions" icon="plus">
A user with `{Member, Analytics}` can do everything Member and Analytics allow. Revoking one role does not remove permissions granted by another.
</Card>
<Card title="Member is implicit" icon="user">
Every org member automatically holds **Member**. It is not shown in the Manage Access picker and cannot be removed without removing the user from the org.
</Card>
<Card title="Scopes are independent" icon="sitemap">
Organization roles apply across the org. Team roles apply inside a single team. A user can be a Team Admin on one team and a Team Member on another.
</Card>
<Card title="Admin vs Feature roles" icon="layer-group">
**Admin roles** (Admin, Manager) grant broad authority. **Feature roles** (Security, Developer, Analytics) grant scoped access to one area.
</Card>
</CardGroup>
## Organization roles
<CardGroup>
<Card title="Admin" icon="crown" href="#admin">
Full control: billing, SSO, members, and every feature area.
</Card>
<Card title="Manager" icon="user-gear" href="#manager">
Member operations, connectors, and analytics. No billing or security.
</Card>
<Card title="Member" icon="user" href="#member">
Implicit baseline. Use agents, skills, and personal connectors.
</Card>
<Card title="Security" icon="shield-halved" href="#security">
Custom roles, app policies, AI model access, and [Connector Activity](/enterprise-features/app_activity).
</Card>
<Card title="Developer" icon="code" href="#developer">
[Hosted MCPs](/enterprise-features/hosted_mcps) and [Proxied MCPs](/enterprise-features/proxied_mcps).
</Card>
<Card title="Analytics" icon="chart-line" href="#analytics">
Organization analytics, usage, and data export.
</Card>
</CardGroup>
***
### Admin
<Info>
**Role ID:** `admin` · **Group:** Admin · **Scope:** Organization
</Info>
<CardGroup>
<Card title="Can access" icon="circle-check">
* Billing, subscription, and credit limits
* SSO, SAML, and SCIM
* All member operations
* Organization connectors
* Team access and team settings
* Audit logs
* AI model access, app policies, custom roles
* Analytics, usage, and data export
* [Connector Activity](/enterprise-features/app_activity), [Hosted MCPs](/enterprise-features/hosted_mcps), and [Proxied MCPs](/enterprise-features/proxied_mcps) (when enabled)
</Card>
<Card title="Can assign" icon="user-plus">
Admin, Manager, Security, Developer, Analytics.
</Card>
</CardGroup>
**Cannot do:** Nothing. Admin has full authority, so treat it as a break-glass role.
<Tip>
**When to assign:** Organization owners, finance leads, and IT admins. Keep the count small since Admin includes billing and SSO.
</Tip>
***
### Manager
<Info>
**Role ID:** `manager` · **Group:** Admin · **Scope:** Organization
</Info>
<CardGroup>
<Card title="Can access" icon="circle-check">
* Invite, remove, and manage members
* Organization connectors
* Analytics, usage, and data export
</Card>
<Card title="Can assign" icon="user-plus">
Analytics, Member.
</Card>
</CardGroup>
**Cannot do:** Change billing, SSO, AI model access, app policies, custom roles, or audit logs. Cannot grant Admin, Manager, Security, or Developer.
<Tip>
**When to assign:** Team leads and ops managers who handle day-to-day onboarding and need usage visibility without billing or security authority.
</Tip>
***
### Member
<Info>
**Role ID:** `member` · **Group:** Feature · **Scope:** Organization and Team · **Baseline:** Yes
</Info>
<CardGroup>
<Card title="Can access" icon="circle-check">
* Create and use agents and skills
* Read organization metadata
* Create teams
* Manage personal connectors
* Leave the organization or a team
</Card>
<Card title="Can assign" icon="user-plus">
Nothing.
</Card>
</CardGroup>
**Cannot do:** Any management action: billing, members, connectors, analytics, or security controls.
<Tip>
**When to assign:** Automatic. Every organization member holds Member implicitly. It cannot be removed without removing the user from the organization.
</Tip>
***
### Security
<Info>
**Role ID:** `security` · **Group:** Feature · **Scope:** Organization · **Plan:** Enterprise
</Info>
<CardGroup>
<Card title="Can access" icon="circle-check">
* [Custom Roles](/enterprise-features/user_groups)
* [Connector Policies](/enterprise-features/app-policies/overview)
* [AI Model Access Controls](/enterprise-features/ai_model_control)
* [Connector Activity](/enterprise-features/app_activity), [Hosted MCPs](/enterprise-features/hosted_mcps), and [Proxied MCPs](/enterprise-features/proxied_mcps) (on enabled orgs)
* [Slack workspaces and the organization service account](/enterprise-features/slack_agent_access)
</Card>
<Card title="Can assign" icon="user-plus">
Developer.
</Card>
</CardGroup>
**Cannot do:** Billing, SSO, member management, or audit logs. Cannot grant Admin, Manager, or Security.
<Tip>
**When to assign:** Security engineers, platform leads, and compliance owners who configure guardrails without taking on billing or SSO.
</Tip>
***
### Developer
<Info>
**Role ID:** `developer` · **Group:** Feature · **Scope:** Organization
</Info>
<CardGroup>
<Card title="Can access" icon="circle-check">
* [Hosted MCPs](/enterprise-features/hosted_mcps) and [Proxied MCPs](/enterprise-features/proxied_mcps)
* [Connector Activity](/enterprise-features/app_activity) for their own servers and tools
* Agents and skills via Member
</Card>
<Card title="Can assign" icon="user-plus">
Nothing.
</Card>
</CardGroup>
**Cannot do:** Any organization management action. Cannot view audit logs or organization-wide [Connector Activity](/enterprise-features/app_activity).
<Tip>
**When to assign:** Builders and integration engineers who need to develop and test [Hosted MCPs](/enterprise-features/hosted_mcps) and [Proxied MCPs](/enterprise-features/proxied_mcps). Granted by Admin or Security.
</Tip>
<Warning>
Developer is hidden in the Manage Access UI if Hosted MCPs and Proxied MCPs are not enabled on the organization.
</Warning>
***
### Analytics
<Info>
**Role ID:** `analytics` · **Group:** Feature · **Scope:** Organization · **Plan:** Enterprise
</Info>
<CardGroup>
<Card title="Can access" icon="circle-check">
* Organization analytics dashboard
* Usage limits and credit consumption
* Data export
</Card>
<Card title="Can assign" icon="user-plus">
Nothing.
</Card>
</CardGroup>
**Cannot do:** Member management, connectors, security controls, or billing.
<Tip>
**When to assign:** Finance, FP\&A, and data analysts who need usage visibility without member management authority. Granted by Admin or Manager.
</Tip>
## Team roles
Teams use a simpler two-role system.
### Team Admin
<Info>
**Role ID:** `admin` (team scope) · **Scope:** Team
</Info>
<CardGroup>
<Card title="Can access" icon="circle-check">
* Team agents and skills
* Team credentials
* Team analytics
* Team membership
</Card>
<Card title="Can assign" icon="user-plus">
Team Admin, Team Member.
</Card>
</CardGroup>
**Cannot do:** Anything outside the team. Team roles do not grant organization-level authority.
<Tip>
**When to assign:** People who own a team's content end-to-end, including onboarding teammates and managing credentials.
</Tip>
### Team member
<Info>
**Role ID:** `member` (team scope) · **Scope:** Team · **Baseline:** Yes
</Info>
<CardGroup>
<Card title="Can access" icon="circle-check">
Read access to team content.
</Card>
<Card title="Can assign" icon="user-plus">
Nothing.
</Card>
</CardGroup>
**Cannot do:** Manage team membership, credentials, or team roles.
<Tip>
**When to assign:** Automatic. Every team member holds Team Member implicitly.
</Tip>
<Info>
**Organization ceiling:** org **Admins** hold `organization:manage_team_access`, which lets them manage team memberships and team roles on every team in the organization, regardless of their team-level role. This is how org admins unblock access issues.
</Info>
## Managing roles
Roles are assigned and revoked individually from the **Manage Access** sheet. You pick the exact combination of roles the user should hold. This is not a promote or demote action.
<Frame>
<img alt="Manage Access sheet with a search box and Admin roles, General roles, and Custom Roles groups, each role paired with a View details link." />
</Frame>
<Steps>
<Step title="Open the members page">
Go to [Organization Members](https://www.gumloop.com/settings/organization/members) or a team's **Members** tab.
</Step>
<Step title="Open Manage Access">
Click the three-dot menu next to the member and choose **Manage Access**. The sheet opens with every role the member currently holds pre-selected.
</Step>
<Step title="Toggle and save">
Check or uncheck any available role and click **Save**. Roles you are not authorized to assign are hidden. Effective permissions update immediately.
</Step>
</Steps>
### Adding a new member with roles
Pre-assign organization roles when you invite someone so they land with the right permissions as soon as they accept.
<Frame>
<img alt="Add Member to Organization modal with fields for email, a multi-select Roles picker showing Member, Manager, Security selected, a Custom Roles selector, and a Teams selector." />
</Frame>
* **Roles** is a multi-select. Every invitee gets **Member** implicitly; pick any additional roles your own role lets you assign.
* **Custom Roles** picks one or more [Custom Roles](/enterprise-features/user_groups) that apply subtractive restrictions on top of the organization roles. New invitees automatically join the default custom role; you can layer additional custom roles on top.
* **Teams** adds the invitee to one or more [teams](/core-concepts/teams).
### Best practices
<AccordionGroup>
<Accordion title="Start minimal, then layer on" icon="shield-halved">
Every user starts as Member automatically. Add the narrowest additional roles that match their responsibilities. You can always add more later.
</Accordion>
<Accordion title="Prefer feature roles over Manager or Admin" icon="layer-group">
If someone only needs analytics visibility, grant **Analytics**, not Manager. Keep the high-authority list short.
</Accordion>
<Accordion title="Use Security instead of Admin for guardrails" icon="user-shield">
Custom roles, app policies, and AI model access no longer require Admin. Grant **Security** so platform and security teams can own guardrails without billing or SSO.
</Accordion>
<Accordion title="Review role assignments quarterly" icon="calendar-check">
Additive roles make it easy to accumulate extras. Run a quarterly review and remove roles that are no longer needed.
</Accordion>
</AccordionGroup>
## Removing a member
Remove a member from the three-dot menu on [Organization Members](https://www.gumloop.com/settings/organization/members), or from a team's **Members** tab to remove them from that team only.
<Warning>**Their triggers stop with them.** A [trigger](/core-concepts/agent_triggers) runs as the person who set it up, using their connectors. When you remove a member, Gumloop turns off the active triggers they own in the spaces they lost — both triggers created in those team spaces and personal triggers on flows those spaces own — so no automation keeps running under a departed account.</Warning>
Scope follows the removal:
| Removal | Triggers turned off |
| - | - |
| **From the organization** | Their triggers across every team in the organization |
| **From one team** | Only their triggers in that team; triggers in teams they still belong to keep running |
Nothing else is touched: teammates' triggers on the same flows keep running, triggers on flows in the member's own personal space are left alone, and no flow is deleted. To keep an automation running after someone leaves, have a remaining member re-create the trigger with their own connectors.
## How permissions resolve
When someone takes an action, Gumloop checks three things. The action goes through only if all three agree.
<CardGroup>
<Card title="1. Roles" icon="layer-group">
The union of everything your organization and team roles grant at the relevant scope. This is the ceiling on what you can do.
</Card>
<Card title="2. Item sharing" icon="share-nodes">
For a specific agent, an Owner can add you as an **Owner** or a **User** (see [Agent Access](/core-concepts/agent_access)). For a flowbook or skill, the owner can grant you **Editor**, **Viewer**, or **Use only**. Sharing overrides the default per item.
</Card>
<Card title="3. Custom roles" icon="filter">
Your [Custom Roles](/enterprise-features/user_groups) can subtract from what roles and sharing allow. For example, they can block certain apps or tools. A user can hold multiple custom roles, and the effective restriction is composed across all of them.
</Card>
</CardGroup>
In short: organization and team roles set the ceiling, sharing adjusts access per item, and custom roles can subtract on top.
## Role comparison
Users with multiple roles get the **union** of the "Yes" columns.
| Capability | Admin | Manager | Security | Developer | Analytics | Member |
| - | - | - | - | - | - | - |
| Billing and subscription | Yes | No | No | No | No | No |
| SSO / SAML / SCIM | Yes | No | No | No | No | No |
| Add and remove members | Yes | Yes | No | No | No | No |
| Assign roles | All | Analytics, Member | Developer | No | No | No |
| Audit logs | Yes | No | No | No | No | No |
| AI model access controls | Yes | No | Yes | No | No | No |
| App policies | Yes | No | Yes | No | No | No |
| Custom roles | Yes | No | Yes | No | No | No |
| Organization connectors | Yes | Yes | No | No | No | No |
| Org analytics, usage, data export | Yes | Yes | No | No | Yes | No |
| Create agents and skills | Yes | Yes | Yes | Yes | Yes | Yes |
| Create teams | Yes | Yes | Yes | Yes | Yes | Yes |
| Connector Activity & MCP management | Yes | No | Yes | Yes | No | No |
Team Admin can assign Team Admin and Team Member inside the team. Team Member is implicit and has read access to team content.
## Related resources
<CardGroup>
<Card title="Custom roles" icon="users-gear" href="/enterprise-features/user_groups">
Additive restriction roles that subtract from what organization roles grant.
</Card>
<Card title="Connector policies" icon="shield-check" href="/enterprise-features/app-policies/overview">
Allow or block specific apps for users.
</Card>
<Card title="AI model access controls" icon="sparkles" href="/enterprise-features/ai_model_control">
Restrict which AI models users can call.
</Card>
<Card title="Audit logging" icon="clipboard-list" href="/enterprise-features/audit_logging">
Track every administrative action.
</Card>
<Card title="Teams" icon="people-group" href="/core-concepts/teams">
Group users and content for shared access.
</Card>
</CardGroup>
# Profile settings
Source: https://docs.gumloop.com/core-concepts/profile_settings
Your personal details, preferences, and agent notifications
Your own settings live at **Settings → Profile → [General](https://www.gumloop.com/settings/profile/general)**. They apply to you, not to your team or organization.
| Section | What it holds |
| - | - |
| **Personal details** | Your name, email, and profile photo. |
| **Preferences** | How Gumloop behaves for you: guided setup, theme, and agent notifications. |
| **Danger Zone** | Delete your account. |
## Preferences
<Frame>
<img alt="Preferences with Skip guided agent setup, Theme, and Agent notifications" />
</Frame>
### Skip guided agent setup
*Open new agents in the full configuration instead of asking what the agent should take care of.*
Off by default: a new agent asks what it should take care of and sets itself up from your answer. Turn this on once you know the builder and would rather configure everything yourself from the start.
### Theme
*Appearance for this browser.* Light or dark. The choice is per browser, so it does not follow you to another machine.
### Agent notifications
*Get a desktop notification when an agent finishes or needs your approval while you're in another tab.*
Turn this on and you can start a long task, switch to something else, and get pinged when the agent finishes or pauses for your [approval](/core-concepts/human_in_the_loop).
A few things to know:
* Your **browser** has to allow notifications for Gumloop. The first time you enable the setting, the browser asks — choose Allow.
* Notifications only fire when the Gumloop tab is in the background. If you are watching the task, you just see it happen.
* The setting is per browser, like the theme. Enable it on each machine you use.
* If you previously blocked notifications, Gumloop tells you: *Notifications are blocked for this site. Allow them in your browser's site settings.* Fix it in the browser's site settings (the padlock next to the address bar), then come back and turn the setting on.
## Related
<CardGroup>
<Card title="Connectors" icon="plug" href="/core-concepts/credentials">
Your connected accounts.
</Card>
<Card title="Human in the Loop" icon="hand" href="/core-concepts/human_in_the_loop">
What an approval request looks like.
</Card>
<Card title="Agents" icon="compass" href="/core-concepts/agents#guided-setup">
Guided setup and the agent builder.
</Card>
<Card title="Organization roles" icon="shield" href="/core-concepts/organization_user_roles">
Settings that apply to everyone.
</Card>
</CardGroup>
# Rate limits
Source: https://docs.gumloop.com/core-concepts/rate_limits
Understand concurrency limits for agents, how they are calculated, and what happens when you hit them.
Rate limits control how many agent interactions can run **at the same time**. They do not limit how many you can run per day — only how many can be active simultaneously.
## Quick reference
| | Agents |
| - | - |
| **Pro** | 25 concurrent interactions |
| **Enterprise** | 100 concurrent interactions (customizable) |
| **When limit is hit** | Queued (Enterprise) or rejected |
| **Scope** | Organization-wide |
<Info>Once an agent interaction finishes, it frees up a slot for the next one.</Info>
***
## How rate limits work
Every time an agent interaction starts, the system checks whether your organization has an available slot. If it does, the execution starts immediately. If all slots are in use, the request is either **queued** or **rejected** depending on your plan.
<Steps>
<Step title="Request arrives">
An agent interaction starts — whether from the UI, API, Slack, Teams, or a scheduled trigger.
</Step>
<Step title="Slot check">
The system checks how many executions are currently running across your organization against your concurrency limit.
</Step>
<Step title="Outcome">
* **Under limit** — execution starts immediately
* **At limit + Enterprise plan** — request is queued and starts automatically when a slot opens
* **At limit + Pro** — request is rejected
</Step>
</Steps>
***
## Agent rate limits
Agent rate limits control how many agent interactions can run at the same time across your organization.
### Limits by plan
| Plan | Concurrent Agent Interactions |
| - | - |
| Pro | 25 |
| Enterprise | 100 (default, customizable per org) |
### What counts toward the limit
<CardGroup>
<Card title="Counts" icon="circle-check">
* Any agent interaction that is currently **running** (actively processing a request or executing tools)
* Interactions from all channels: web UI, Slack, Teams, API, and triggers
</Card>
<Card title="Does NOT count" icon="circle-xmark">
* Interactions that have **finished** (completed or failed)
* Interactions that are **queued** (waiting for a slot)
* Interactions that are **idle** (conversation open but agent is not actively working)
* The **Custom Operator Builder** AI assistant
* The **App Policy** builder assistant
</Card>
</CardGroup>
<Info>Builder assistants (Custom Operator Builder, App Policy Builder) are excluded from agent rate limits so that building is never blocked by agent concurrency.</Info>
### How the limit is determined
The system determines your organization's limit in this order:
1. **Custom organization limit** — A custom agent concurrency limit on the org, if set.
2. **Plan default** — Falls back to the plan-based default shown above.
3. **Per-user cap (optional)** — An optional cap on a [custom role](/enterprise-features/user_groups) that restricts how many interactions a single user can run. When a user is in multiple custom roles, the most generous cap across their roles applies.
<Accordion title="Example: Per-user caps within an organization">
**Setup:**
* Organization concurrency limit: 100
* A user group has a per-user cap of 10
**Result:**
* The organization can have up to 100 interactions at once across all members
* Any user in that group can have at most 10 of those 100 running at once
* Both limits must be satisfied for a new interaction to start
This lets admins prevent a single user from consuming the entire org's capacity.
</Accordion>
### Automatic slot cleanup
If an agent interaction crashes or is abandoned without finishing properly, the slot it was using is **automatically freed** after approximately 2 hours. This means you will never get permanently stuck at your limit due to a stuck interaction. Under normal circumstances, slots are released immediately when an interaction finishes — the 2-hour cleanup is only a safety net.
***
## What happens when you're rate limited
How the system communicates rate limiting depends on where the interaction comes from:
### Web UI
When chatting with an agent in the browser:
* **Enterprise**: The UI shows a "queued" indicator and waits up to **5 minutes** for a slot to open. If a slot opens, the interaction starts automatically. If not, you are notified.
* **Pro**: An error message is shown: *"Too many concurrent agent interactions. Please try again shortly."*
### API
When starting an agent via the API:
* **Enterprise**: If the limit is hit, the request is queued. The API returns the interaction with a `queued` status and a `queue_position` so you can track progress.
* **Pro**: The API returns **HTTP 429** (Too Many Requests).
<Accordion title="API response examples">
**Queued (Enterprise):**
```json theme={"dark"}
{
"interaction_id": "abc123",
"status": "queued",
"queue_position": 3
}
```
**Rate Limited:**
```json theme={"dark"}
{
"error": "gummie_rate_limit"
}
```
</Accordion>
### Slack
When an agent receives a Slack message:
* **Enterprise**: If queued, a message is posted in the thread: *"Your agent interaction is queued (position #N). It will be processed shortly."*
* **Pro**: An ephemeral message is sent: *"You have too many agent interactions running at the moment. Please try again shortly."*
### Microsoft Teams
Follows the same pattern as Slack — Enterprise users see a queued notification, others see an error message.
### Scheduled & event-based triggers
* **Enterprise**: If the limit is hit, the triggered interaction is queued and will start when capacity is available.
* **Pro**: The trigger execution is skipped.
***
## How the queue works
When an Enterprise organization hits the rate limit, requests are placed in a queue instead of being rejected.
* When a running execution finishes and frees a slot, the next queued item starts automatically
* The user who freed the slot gets slight priority — their own queued items are checked first, then the org-wide queue
* Within each queue, items are processed in the order they were submitted (first in, first out)
* If a queued item can't start because of a per-user cap, it is moved to that user's individual queue (not dropped)
***
## Webhook trigger request limit
Separately from concurrency, each [webhook trigger](/core-concepts/agent_triggers#webhook-triggers) accepts up to **100 requests per minute**. The limit applies per trigger, regardless of sender or IP, and rejected requests count too. Requests over the limit get **HTTP 429** (`rate_limited`) with a `Retry-After` header, and the agent does not run for them.
***
## Tips for avoiding rate limits
<CardGroup>
<Card title="Stagger your triggers" icon="clock">
If you're starting many agent interactions at once (e.g., via webhooks), add small delays between them so they don't all compete for slots at the same time.
</Card>
<Card title="Keep runs short" icon="gauge-high">
Shorter agent interactions free up slots faster. Give agents focused tasks to reduce their total execution time.
</Card>
<Card title="Upgrade your plan" icon="arrow-up">
If you consistently hit limits, consider upgrading. Enterprise plans have the highest limits and also unlock automatic queuing so requests are never lost.
</Card>
</CardGroup>
<Accordion title="Enterprise: Request a custom limit">
Enterprise organizations can request custom concurrency limits that exceed the defaults. Contact your account manager or [support@gumloop.com](mailto:support@gumloop.com) to adjust:
* **Agent concurrency** — the org-wide limit on simultaneous agent interactions
* **Per-user caps via user groups** — restrict individual users within the org
These are set at the organization level and apply to all members.
</Accordion>
***
## Summary
| Aspect | Agents |
| - | - |
| **What's limited** | Concurrent agent interactions |
| **Limit scope** | Organization-wide |
| **Enterprise queuing** | Yes (automatic) |
| **Pro behavior** | Rejected (error message or HTTP 429) |
| **Stuck slot recovery** | Automatic (\~2 hours) |
| **Customizable limits** | Yes (Enterprise) |
| **Per-user caps** | Yes (via [custom roles](/enterprise-features/user_groups)) |
<CardGroup>
<Card title="Credits" icon="coins" href="/core-concepts/credits">
Learn about credit costs for agents
</Card>
<Card title="Custom roles" icon="users" href="/enterprise-features/user_groups">
Configure custom roles and per-user limits
</Card>
</CardGroup>
# Reflections
Source: https://docs.gumloop.com/core-concepts/reflections
<div>
<iframe title="Reflections" />
</div>
Reflections turn your agent's own history into improvements. On a recurring schedule, the agent re-reads what it actually did across recent tasks, looks for problems that keep happening, and writes up a small number of concrete fixes: a new skill, an edit to an existing one, an instruction change, a trigger change, or something only a human can do.
Every suggestion cites the tasks it came from, so you're never approving a change on vibes. Nothing is applied without your approval unless you explicitly turn on auto-apply, and after a change is applied the agent keeps watching to see whether the problem actually went away.
Reflections live on the agent's [Performance](/core-concepts/agent_performance) page, in the **Reflections** section of the right-hand panel.
***
## Why use Reflections
Without Reflections, an agent only improves when you notice something and fix it by hand. That works for the issues you happen to catch, in the tasks you happen to read.
With Reflections on, the agent:
* **Looks across many tasks**, so it finds problems that repeat rather than one-off mistakes
* **Cites its evidence**: which tasks, how many times, when it last happened
* **Proposes a specific change**, not a vague observation, and can apply it for you when you accept
* **Tracks the outcome** and tells you if the same problem comes back after a fix
<CardGroup>
<Card title="Without Reflections" icon="repeat">
You spot a bad answer, dig into the task, and edit a skill or instruction yourself. Repeat for every issue you happen to see.
</Card>
<Card title="With Reflections" icon="brain">
The agent finds that the same lookup has failed 4 times across 2 tasks, proposes the fix with links to the evidence, and applies it when you click **Accept**.
</Card>
</CardGroup>
***
## How a review works
<Steps>
<Step title="Collect what happened">
The agent gathers the work it has done since its last review: tool calls, errors, retries, and the shape of the requests it handled.
</Step>
<Step title="Look for repeats">
It clusters that activity into candidate signals: the same failure, the same manual workaround, the same multi-step sequence done over and over.
</Step>
<Step title="Check the evidence">
Candidates are validated against the actual task transcripts. Anything that happened once, was already handled, or is simply part of the job gets dropped.
</Step>
<Step title="Check what already exists">
The agent reads its current instructions, skills, and earlier suggestions so it doesn't re-propose something that is already covered or that you already dismissed.
</Step>
<Step title="Propose changes">
What survives becomes a small set of typed suggestions, each with a rationale, the evidence behind it, the expected impact, and a confidence level.
</Step>
<Step title="Track the result">
After a change is applied, the agent keeps measuring the original signal. If the problem stops, the suggestion is holding. If it comes back, the suggestion is flagged as **Didn't hold**.
</Step>
</Steps>
### What a reflection can propose
| Type | What it does |
| - | - |
| **New skill** | Adds a [skill](/core-concepts/skills) for a workflow the agent keeps redoing from scratch |
| **Skill edit** | Fixes or extends an existing skill that misses a case |
| **Remove skill** | Removes a skill that is unused, wrong, or superseded |
| **Instructions** | Changes the agent's system prompt: a rule, preference, or domain fact |
| **Trigger change** | Adjusts a schedule or trigger, for example removing a duplicate daily run |
| **Agent task** | Hands the work to the agent itself to carry out as a task |
| **Needs you** | Something the agent can't do, like reauthorizing a connector or granting access |
<Warning>Trigger changes always require your explicit approval and a confirmation, even when auto-apply is on. Confirming applies the change immediately.</Warning>
***
## Turn Reflections on
<Steps>
<Step title="Open the agent's Performance page">
Click **Performance** in the agent sidebar, then find the **Reflections** section in the panel on the right.
</Step>
<Step title="Enable Reflections">
Click **Enable Reflections**. This creates the recurring review automatically, so there is no schedule to set up.
<Frame>
<img alt="Agent Performance page with the Reflections section and its settings icon in the right-hand panel" />
</Frame>
</Step>
<Step title="Open the settings">
Use the settings icon on the **Reflections** header to choose how suggestions are applied and where reports go.
<Frame>
<img alt="Reflection settings panel showing Enable Reflections, Apply Suggestions, and Report Delivery options" />
</Frame>
</Step>
</Steps>
### Apply suggestions
This decides what happens when the agent proposes a change.
<AccordionGroup>
<Accordion title="Review queue (default)" icon="list-check">
Every suggestion waits for you. Nothing about the agent changes until you accept it.
**Best for:** production and customer-facing agents, or any agent where you want to see each change first.
</Accordion>
<Accordion title="Auto-apply low-risk suggestions" icon="bolt">
Suggestions the system classifies as low-risk with enough supporting evidence are applied as soon as they're created. Everything else still waits in the queue.
**Best for:** internal agents and personal assistants where you want faster iteration.
<Note>Trigger changes and items that need a human are never auto-applied.</Note>
</Accordion>
</AccordionGroup>
### Report delivery
Reflection reports stay in the app by default. Turn on a channel if you want to hear about them elsewhere.
| Setting | What it does |
| - | - |
| **Email Reports** | Emails the completed report to the addresses in **Email Recipients** |
| **Email Recipients** | The list of addresses that receive reports. Type an address and press Enter |
| **Slack Reports** | Sends the completed report as a Slack DM to the agent owner |
| **Notify When Skipped** | Also notifies you when a review is skipped for too little activity. Requires email or Slack reports to be on first |
<Info>All delivery is off by default. Enabling Reflections on its own never sends anything outside Gumloop.</Info>
### When reviews run, and when they're skipped
Reviews run on their own once enabled, roughly once a day in the evening. A scheduled review is skipped when:
* There has been **no new activity** since the last review, or
* The agent has handled **fewer than 8 tasks** since the last review, too small a sample to tell a pattern from a coincidence
Skipped reviews cost nothing and stay quiet unless you turn on **Notify When Skipped**.
***
## Reading the Reflections section
Once reviews start producing results, the **Reflections** section summarizes the state of the queue and lists the most recent items. **View all** opens the full list, where you can scroll the whole history.
<Frame>
<img alt="Reflections section listing recent suggestions with their statuses and a summary line of counts" />
</Frame>
Under the heading, a one-line summary counts the queue: something like `126 waiting · 141 holding · next review in 9 hours`.
| Count | Meaning |
| - | - |
| **waiting** | Suggestions that need a decision from you |
| **holding** | Applied changes where the original problem hasn't come back |
| **regressed** | Applied changes where it did come back |
| **next review** | When the agent will look at its work again |
### Statuses
| Status | Meaning |
| - | - |
| **Pending** | Waiting for you to accept or dismiss |
| **Applying** | Accepted; the change is being made |
| **Applied** | The change is in place |
| **Acknowledged** | A *Needs you* item you marked as seen |
| **Dismissed** | You declined it. The agent won't re-propose the same thing |
| **Didn't hold** | The change was applied, but the problem came back |
| **Superseded** | A newer suggestion replaced this one |
| **Failed** | The change couldn't be applied. Nothing was modified |
| **Reverted** | The change was rolled back |
***
## Reviewing a suggestion
Click any row to open the full detail view.
<Frame>
<img alt="Reflection detail view with tags, status, evidence, impact, recommended action, and Dismiss and Acknowledge buttons" />
</Frame>
A reflection detail contains:
| Section | What's in it |
| - | - |
| **Tags** | The change type (for example *Needs you*), the category (*Reliability*, *Configuration*, *Credit usage*, *Efficiency*, *Quality*), and the agent's confidence |
| **Status, Created, Applied, Review credits** | The lifecycle of this suggestion and what the review that produced it cost |
| **What the agent found** | The problem, with links to the tasks it was seen in and how many times it happened |
| **Impact** | Recurrence, when it was last seen, and the measurable cost of leaving it alone |
| **Changes** | A preview of the exact edit, for skill and instruction suggestions |
| **What to do** | The recommended fix. For *Needs you* items this is a **Who / What / Already tried** breakdown, so you know what's being asked of you and what the agent has already attempted |
| **Supporting numbers** | The raw signal counts behind the claim |
<Tip>Use the arrows at the bottom of the detail view to page through the queue without going back to the list.</Tip>
### Accepting, dismissing, acknowledging
| Action | When it appears | What happens |
| - | - | - |
| **Accept** | Pending suggestions the agent can carry out | The change is applied, or handed to the agent as a task |
| **Acknowledge** | Pending *Needs you* suggestions | Marks it as seen. Nothing is changed for you: the fix is yours to make |
| **Dismiss** | Any pending suggestion | Declines it. It leaves the queue and won't be re-proposed |
For a trigger change, a confirmation appears first (**Change this agent's trigger?**) because the new schedule takes effect immediately.
### After a change is applied
Applied suggestions keep reporting back. The detail view shows before/after numbers for the signal that motivated the change, how often it has recurred since, and whether the change is still in place. If the problem returns, the suggestion flips to **Didn't hold**, and the agent can propose a different fix in a later review.
***
## How Reflections differ from other self-improvement features
| Feature | What it does | When it runs |
| - | - | - |
| **[Self-Improve Instructions](/core-concepts/agents#self-improving-instructions)** | The agent updates its own instructions from your feedback | In the moment, during a task |
| **[Skill editing](/core-concepts/skills)** | The agent writes or edits a skill when you ask it to | In the moment, during a task |
| **Reflections** | The agent reviews many completed tasks, finds repeats, and proposes tracked changes | On a recurring schedule |
The first two are reactive: they happen because you said something. Reflections are proactive, and they're the only one that measures whether the change actually worked.
***
## Best practices
<CardGroup>
<Card title="Start in review queue" icon="list-check">
Watch a few cycles of suggestions before deciding whether to let low-risk ones apply themselves.
</Card>
<Card title="Clear the queue regularly" icon="broom">
Suggestions don't expire, but the evidence behind them goes stale. Accepting or dismissing also teaches the agent what you care about, since dismissed items aren't re-proposed.
</Card>
<Card title="Act on Needs you items" icon="user">
Usually the highest-value ones: a dead connection or a missing permission the agent has been working around, repeatedly, at your expense.
</Card>
<Card title="Watch for Didn't hold" icon="triangle-exclamation">
A change that regressed is a sign the real cause is elsewhere. Worth a look from a human.
</Card>
<Card title="Give it enough traffic" icon="chart-line">
Reviews are skipped below 8 tasks. A lightly used agent will mostly skip, which is fine: there's nothing to learn from an empty window.
</Card>
<Card title="Turn on reports" icon="bell">
If you don't visit the Performance page, email or Slack delivery means you find out about a broken connector the day it's detected.
</Card>
</CardGroup>
***
## FAQ
<AccordionGroup>
<Accordion title="Does a review run when nothing happened?">
No. If there's no new activity since the last review, or fewer than 8 tasks to look at, the review is skipped and no credits are used.
</Accordion>
<Accordion title="What do Reflections cost?">
A review consumes credits like any other agent work, and each reflection shows its **Review credits** in the detail view. Cost scales with how much activity there is to analyze.
</Accordion>
<Accordion title="Can I run a review on demand?">
Not directly. Reviews run on their recurring schedule. You can always ask the agent in a task to look at recent work, but that uses regular agent abilities rather than the Reflections pipeline.
</Accordion>
<Accordion title="What if I never review pending suggestions?">
Nothing breaks. They stay in the queue, and later reviews may supersede them with better versions. The counts in the Reflections summary keep growing, so it's worth a periodic pass.
</Accordion>
<Accordion title="Can auto-apply make a change I didn't want?">
Auto-apply is limited to suggestions classified as low-risk with enough evidence. Trigger changes and anything that needs a human never auto-apply. If you want full control, stay on Review Queue.
</Accordion>
<Accordion title="Who can enable Reflections and accept suggestions?">
Anyone with permission to edit the agent. Viewers can't enable Reflections, change its settings, or accept and dismiss suggestions.
</Accordion>
<Accordion title="Can I see what changed after a suggestion is applied?">
Yes. Skill and instruction suggestions show a preview of the exact change before you accept, and the detail view keeps the applied timestamp along with the tracking numbers for the signal it was meant to fix.
</Accordion>
</AccordionGroup>
# Agent skills
Source: https://docs.gumloop.com/core-concepts/skills
Skills are reusable knowledge packs that teach your agents how to do specific work, and get better over time.
<div>
<iframe title="Gumloop Skills" />
</div>
Skills teach your agents how to do specific work **your way**, and get better at it over time.
## What is a skill?
A **skill** is a reusable set of instructions (and optionally templates and scripts) that teaches an agent how to do a specific task.
Think of a skill as a **playbook** your agent can pull out when it needs it:
<CardGroup>
<Card title="Example: outreach emails" icon="handshake">
A step-by-step outreach process, your templates, and follow-up rules.
</Card>
<Card title="Example: support triage" icon="message">
An escalation checklist, severity rules, and response templates.
</Card>
<Card title="Example: weekly reporting" icon="chart-line">
Which KPIs to include, the exact format, and optional scripts to compute metrics.
</Card>
</CardGroup>
<Info>Skills can feel like **memory**, because the agent can update them after you give feedback. Technically, it is not remembering your conversation. It is updating a shared playbook that gets reused in future conversations.</Info>
<Tip>**This is the superpower:** when your agent makes a mistake and you correct it, the agent can update the relevant skill so it does it right next time.</Tip>
<Accordion title="See a 15-second example" icon="sparkles">
> **You:** "Reply to this customer email. Keep it short and friendly."<br />
> **Agent:** *\[replies, but uses the wrong sign-off]*<br />
> **You:** "We never sign off with 'Best'. Use 'Thanks' instead."<br />
> **Agent:** "Got it. I updated the relevant skill so future replies use 'Thanks'."
</Accordion>
## Why skills?
When you set up an agent, you typically give it two things:
<CardGroup>
<Card title="System prompt" icon="scroll">
Defines who the agent is. "You're a sales assistant. Be professional." Always active, always loaded.
</Card>
<Card title="Tools" icon="wrench">
Gives the agent hands. Gmail, Salesforce, Slack, etc. The raw ability to take actions.
</Card>
</CardGroup>
That gets you an agent that **can** send emails and update your CRM. But it doesn't know **your** outreach process, **your** email templates, or **your** follow-up rules. It's winging it every time.
**Skills fill that gap.** A skill is a set of instructions, templates, and even executable scripts that teach your agent exactly how to do a specific task. Your agent can read, follow, improve, and even create skills on its own.
## The new employee analogy
The simplest way to understand skills is to imagine you just hired someone new.
| What you give them | Agent equivalent | What it does |
| - | - | - |
| **Job description & company handbook** | **System prompt** | Defines who they are, their tone, and universal rules. Always active. |
| **Connected services** (Gmail, Salesforce, Slack) | **Connectors and tools** | Give the agent access to the actions it can take. |
| **Training materials & SOPs** | **Skills** | Teaches them your specific processes, templates, and best practices. |
Without skills, your agent has access to email and CRM but improvises every time. It might send a decent email, but it won't follow your specific outreach sequence, use your templates, or log things the way you want.
**Skills are the difference between "an AI that can send emails" and "an AI that follows our exact outreach process."**
## When do you need a skill?
Not everything needs to be a skill. Here's a quick guide:
<Tabs>
<Tab title="System prompt">
**Put it in the system prompt** if it applies to **every single conversation:**
* Agent personality and tone
* Universal guardrails ("Never share pricing without approval")
* Response format rules
The system prompt is always loaded in full. Keep it short and universal.
</Tab>
<Tab title="Tool">
**Use a tool** if it's a **simple, one-off action:**
* "What's on my calendar today?"
* "Send this message on Slack"
* "Look up this contact in Salesforce"
Tools give the agent the raw ability to interact with external services.
</Tab>
<Tab title="Skill">
**Create a skill** when you have:
* A **multi-step process** the agent should follow every time
* **Templates** or specific formats the agent should use
* **Domain knowledge** that's too long for the system prompt
* **Instructions that only apply sometimes** (skills load on demand, saving tokens)
* Work that **multiple agents** need to do the same way
</Tab>
</Tabs>
<Info>**Rule of thumb:** If your instructions are over 200 words and don't apply to every single conversation, they belong in a skill, not the system prompt.</Info>
| Scenario | System Prompt | Tool | Skill |
| - | - | - | - |
| "Be friendly and professional" | <span aria-label="Yes" /> | | |
| "Send this email for me" | | <span aria-label="Yes" /> | |
| "Draft outreach emails using our 5-step sequence" | | | <span aria-label="Yes" /> |
| "Generate a weekly sales report with specific KPIs" | | | <span aria-label="Yes" /> |
| "Never delete customer data without confirmation" | <span aria-label="Yes" /> | | |
| "Triage support tickets using our escalation matrix" | | | <span aria-label="Yes" /> |
## How agents use skills
Here's what happens behind the scenes:
<Warning>**Skill-Tool Dependencies:** If a skill is designed to use a specific integration (e.g., Salesforce, Gmail) but that integration is not connected to the agent, the skill will load successfully but fail at execution. There is no automatic dependency enforcement — make sure any integration a skill depends on is also connected to the agent.</Warning>
<Steps>
<Step title="Conversation starts">
Your agent loads up and sees a list of all attached skills, but only the **names and descriptions** (not the full instructions). This keeps things fast and lightweight.
</Step>
<Step title="You ask something">
You send a message like "Draft an outreach email to the VP of Sales at Acme Corp."
</Step>
<Step title="Agent finds the right skill">
The agent scans the skill descriptions and finds `email-outreach-playbook` is relevant. It reads the full skill from the sandbox.
</Step>
<Step title="Agent follows the instructions">
Now the agent has the complete playbook in context. It follows the step-by-step process: researches the prospect, personalizes the email using your template, and drafts it exactly the way you want.
</Step>
<Step title="Conversation ends">
If the agent made any changes to skills during the conversation (more on that below), those changes are automatically saved.
</Step>
</Steps>
<Info>**Key insight:** Skills are only loaded when needed. If you have 20 skills attached to an agent but the user asks a simple question, the agent doesn't waste time or tokens loading irrelevant skills. This is fundamentally different from a system prompt, which is always loaded in full.</Info>
## Built-in system skills
Gumloop provides built-in system skills that help agents manage skills and work with connected services. Common examples include:
<CardGroup>
<Card title="skill-creator" icon="sparkles">
Powers the **Create With AI** flow. When skill creation is enabled on an agent and you click **Create With AI**, the agent uses this skill to guide you through skill creation step by step — naming, scoping, writing instructions, and validating the result.
</Card>
<Card title="gumloop-sdk" icon="plug">
Enables agents to call your connected integrations (Gmail, Salesforce, Slack, Google Sheets, etc.) **directly from Python scripts** in the sandbox. This is what makes it possible to build skills that combine custom logic with real tool calls — e.g., a script that reads from Sheets, processes the data, and posts a summary to Slack.
</Card>
</CardGroup>
<Info>Both system skills are **read-only** — they are maintained by Gumloop and updated automatically. You cannot edit or delete them. The `skill-creator` skill is only active when skill creation is enabled on the agent (via the **AI Skill Editing** toggle in the agent's **Skills** section).</Info>
## Creating skills
There are three ways to create a skill. Pick whichever feels most natural.
<Warning>
**Naming Rules:** Skill names are validated by the backend and must follow these constraints:
* Lowercase letters, digits, and hyphens only
* No spaces, underscores, or uppercase letters
* Maximum 64 characters
* Cannot start or end with a hyphen
* No consecutive hyphens
Valid: `my-cool-skill`. Invalid: `My_Skill`, `my skill`, `mySkill`.
</Warning>
<Frame>
<img alt="Skills page showing the three creation methods: Create With AI, Upload Files, and Write Skill Instructions" />
</Frame>
<AccordionGroup>
<Accordion title="Create with AI (recommended)" icon="sparkles">
The easiest way to get started. Click **Create Skill** → **Create With AI**, and a chat opens where the AI walks you through skill creation step by step.
You describe what you want the skill to do, and the AI:
1. Helps you nail down the scope and name
2. Writes the instructions based on your description
3. Adds any necessary scripts or reference files
4. Validates everything to make sure it's properly formatted
**Best for:** Anyone who isn't sure where to start, or wants a quick way to turn ideas into skills.
</Accordion>
<Accordion title="Write skill instructions" icon="pen">
A simple form where you fill in three fields: **Name**, **Description**, and **Instructions**. Click **Create** and you're done.
<Frame>
<img alt="The Write Skill Instructions form showing name, description, and instructions fields" />
</Frame>
**Best for:** Simple skills that are just instructions (no scripts or extra files needed). Great for brand voice guidelines, email templates, response formatting rules, etc.
</Accordion>
<Accordion title="Upload files" icon="upload">
Upload a `.md`, `.zip`, or `.skill` file containing a properly formatted `SKILL.md`. If you're uploading a `.zip`, it can include scripts, references, and assets alongside the `SKILL.md`.
<Frame>
<img alt="Upload Skill File" />
</Frame>
**Best for:** Technical users with existing documentation, SOPs, or code they want to package as a skill.
</Accordion>
</AccordionGroup>
## What's inside a skill?
At its core, a skill is a folder containing a `SKILL.md` file with instructions your agent can read. Some skills also include helper scripts, reference docs, and templates.
```text theme={"dark"}
email-outreach-playbook/
SKILL.md ← Required: the instructions
scripts/ ← Optional: executable code
personalize_email.py
references/ ← Optional: detailed docs
email_templates.md
prospect_research_checklist.md
assets/ ← Optional: templates and files
signature_template.html
```
<Tip>Most skills only need the `SKILL.md` file. You can always add scripts and references later as the skill grows.</Tip>
### Why this structure exists
The directory structure isn't just organizational — it reflects how the agent uses each part:
| Component | What it's for | How the agent uses it |
| - | - | - |
| **`SKILL.md`** | Instructions, decision logic, context | Loaded directly into the agent's context window. Keep it under **500 lines** for token efficiency and focus. |
| **`references/`** | Detailed documentation, lookup tables, API specs | Read **on demand** when the agent needs specific details. Keeps `SKILL.md` lean. |
| **`scripts/`** | Deterministic logic — calculations, data transforms, API calls | **Executed in the sandbox** and the output is used in the agent's response. Never left to the agent to reason through. |
| **`assets/`** | Static files used in output — templates, images | Referenced by instructions or scripts when producing output. |
<Info>
**Rule of thumb:** If the agent needs to *reason* through something (decisions, steps, context), it belongs in `SKILL.md` instructions. If the agent needs to *calculate or process* something and the result must be correct every time, it belongs in a `scripts/` file.
The 500-line soft limit on `SKILL.md` is enforced as a validation warning — skills exceeding it still work, but you should move detailed content to `references/` to keep the agent's context focused.
</Info>
### The SKILL.md file
Every skill starts with a short header (called "frontmatter") that tells the agent what the skill does and when to use it, followed by the actual instructions:
```yaml theme={"dark"}
---
name: email-outreach-playbook
description: Draft personalized cold outreach emails for sales prospects.
Use when the user asks to contact or email a prospect.
---
## Overview
This skill guides the outreach process for cold prospects.
## Step 1: Research the Prospect
- Look up the prospect's company and role
- Note recent news or achievements to personalize the email
## Step 2: Draft the Email
- Use the greeting: "Hey {first_name},"
- Reference something specific about their company
- Keep it under 150 words
...
```
<Warning>
The **description** is the most important part. Your agent uses it to decide whether to load the skill for the current task. Be specific about **what** the skill does and **when** to use it. A vague description means the agent might never find your skill.
**Description constraints:** Maximum 1,024 characters. No angle brackets allowed.
</Warning>
<Accordion title="Optional frontmatter fields" icon="sliders">
Beyond `name` and `description`, you can add these optional fields to your frontmatter:
| Field | What it does | Example |
| - | - | - |
| **`icon`** | Sets the skill's icon in the UI. Uses [Lucide](https://lucide.dev) icon names in kebab-case. | `icon: chart-line` |
| **`color`** | Sets the skill's accent color in the UI. | `color: Blue` |
| **`related_server_ids`** | Links the skill to specific integrations, enabling integration-scoped discovery. When set, agents working with that integration are more likely to find the skill. | `related_server_ids: [gsheets, slack]` |
Available colors: `Grey`, `Blue`, `Green`, `Orange`, `Red`, `Yellow`, `Teal`, `Pink`, `Purple`, `Bronze`, `Black`
```yaml theme={"dark"}
---
name: weekly-sales-summary
description: Generate a weekly sales performance summary from Google Sheets data.
icon: chart-line
color: Green
related_server_ids: [gsheets, slack]
---
```
<Info>**Server IDs** must match the actual integration identifiers, not display names. For example, Google Sheets is `gsheets`, not `google-sheets`. Have the agent load **gumloop-sdk** and discover the available connector tools before writing the script.</Info>
</Accordion>
## Attaching skills to agents
Once you've created a skill, attach it to the agents that should use it.
<Frame>
<img alt="The Skills section in agent configuration showing the + Add button" />
</Frame>
<Steps>
<Step title="Open agent configuration">
Go to your agent's configuration page.
</Step>
<Step title="Find the Skills section">
Scroll down to the **Skills** section.
</Step>
<Step title="Add a skill">
Click **+ Add** and select a skill from the list (or create a new one right there).
</Step>
</Steps>
That's it. Your agent can now find and use that skill whenever it's relevant.
<Info>
[Gumball](/core-concepts/gumball), your personal agent, needs no attaching — it discovers every skill you can access on its own. See [What Gumball can discover](#what-gumball-can-discover).
**Gumball vs. Custom Agent skill behavior:** Gumball finds skills dynamically using semantic search, matching your request against skill descriptions. Custom agents only see skills explicitly attached to them (listed in the system prompt). A practical consequence: when an agent creates a new skill during a conversation, on a custom agent it gets auto-attached; on Gumball it is added to your library but not auto-attached to anything.
</Info>
### What Gumball can discover
Gumball searches everything you can reach, resolved from your actual access at the start of each conversation:
| Scope | Included |
| - | - |
| **Your own skills** | Every skill in the space you're chatting from |
| **Your teams' skills** | Skills owned by any [team](/core-concepts/teams) you belong to |
| **Shared with you** | Skills shared with you directly, with your organization, or with one of your teams |
If two skills have the same name, your own wins, then the more-used one. **Personalization** skills (Tone and Design) are the exception — they stay private to their author, so a teammate's writing style never leaks into your agent.
<Info>Discovery does not copy skills to you: you keep whatever [role](#sharing-roles) you were given. Gumball can edit a shared skill in place if you have edit access, and is blocked from editing it if you don't.</Info>
<Note>Gumball loads shared skills **on demand**. Only skills already pulled in are present in its sandbox, so a skill can appear there mid-conversation after a search finds it — the agent uses skill discovery, not a directory listing, to know what's available. Nothing to configure; it just means the full set does not have to be copied up front, however large your library gets.</Note>
## Skills that improve over time
This is the most powerful part of skills, and what makes them fundamentally different from static instructions.
**Your agent can edit, improve, and create skills on its own.**
This behavior is controlled by the **AI Skill Editing** toggle in the **Skills** section of the **Agent** tab. It's **enabled by default**.
<Frame>
<img alt="Skills section showing the AI Skill Editing toggle" />
</Frame>
* **Enabled (default):** The agent can create new skills, update existing ones, and fix its own mistakes. This is the recommended option because it lets the agent iterate, learn from corrections, and continuously improve.
* **Disabled:** The agent can still **read and use** skills you've already attached, but cannot create or modify skills. Choose this for tighter control over your skill library.
<Info>**This toggle is global** — it applies to all skills on the agent, not per-skill. There is no way to lock individual skills while keeping others editable. If you need certain skills to be immutable, disable the toggle entirely.</Info>
<Note>**Organizations can restrict skill creation.** On enterprise plans, admins can turn off **Skill creation** for a [custom role](/enterprise-features/user_groups#features-tab). For members of a restricted role, an agent that tries to save a *new* skill skips it and says skill creation has been restricted by their organization admin — even with the agent's own toggle enabled. Reading, using, and updating skills that already exist are unaffected.</Note>
<Tip>Keep this enabled to unlock the full compound learning effect described below. An agent that can refine its own playbooks gets better with every conversation.</Tip>
<Tabs>
<Tab title="Fixing a template">
> **You:** "Draft an outreach email to the VP at Acme Corp."<br />
> **Agent:** *\[drafts email using the outreach-playbook skill]*<br />
> **You:** "Actually, we don't use that greeting anymore. Use 'Hey \{first\_name}' instead."<br />
> **Agent:** "Got it. I've updated the outreach playbook skill with the new greeting."
Next time the agent drafts an outreach email, it uses the corrected greeting. **The fix is permanent.** It's saved back to the skill.
</Tab>
<Tab title="Learning from experience">
> **Conversation 1:** You ask the agent to summarize your emails. It does a basic job.<br />
> **You:** "Group them by sender."<br />
> **Agent:** *\[creates an email-summary skill with the grouping rule]*<br /><br />
> **Conversation 2:** You ask the agent to summarize your emails. It groups by sender automatically.<br />
> **You:** "Also flag anything from my boss as urgent."<br />
> **Agent:** *\[updates the skill to add the urgent-flagging rule]*<br /><br />
> **Conversation 3:** You ask the agent to summarize your emails. It groups by sender AND flags your boss's emails. No corrections needed.
</Tab>
<Tab title="Creating a skill from scratch">
> **You:** "Every Monday I need you to pull last week's support tickets from Zendesk, categorize them, and post a summary to #support-updates in Slack."<br />
> **Agent:** "I'll create a skill to remember this workflow."<br />
> *\[Creates a `weekly-support-summary` skill with the full process, automatically attached to this agent]*
The agent now remembers this process for every future Monday.
</Tab>
</Tabs>
<Info>**Version history:** You can view a full timeline of file-level changes (added, modified, removed) in the **Edits** tab on each skill's detail page. Each version shows what changed and when, along with which agent made the edit. This helps you track how a skill evolves over time. We still recommend manually copying your skill instructions before enabling free agent editing on critical skills.</Info>
<Info>**Concurrent edits:** If two conversations edit the same skill simultaneously, the last one to complete wins and overwrites the other. Teams with multiple users on shared agents should be aware of this race condition.</Info>
### The compound effect
Every correction, every new instruction, every "actually, do it this way" compounds over time:
| Timeline | What the skill looks like |
| - | - |
| **Day 1** | A basic outreach skill with a simple template. |
| **Week 1** | Includes templates for 3 scenarios and an updated greeting. |
| **Month 1** | Has 10 templates, a research checklist, follow-up rules, and a scoring script. |
| **Month 6** | Essentially a senior salesperson's playbook. |
This happens naturally through normal usage. You just tell the agent what to do differently, and it updates its own playbook.
<Tip>Use skills for reusable procedures and examples. When an agent finds a better approach, ask it to update the skill so future tasks can use the revised instructions.</Tip>
## FAQs
<AccordionGroup>
<Accordion title="Do skills give my agent memory?" icon="copy">
Skills can feel like memory because your agent can **update a skill** after you correct it.
Technically, skills are not conversation memory. Skills are saved playbooks your agent can reuse later, and the agent still needs to **load the skill again** in future conversations when it is relevant.
</Accordion>
<Accordion title="Why did my agent not use a skill I created?" icon="bullseye">
Skills are **loaded on demand**. Your agent sees skill names and descriptions first, then decides what to load based on relevance.
Common fixes:
* Make the skill **description** more specific about what it does and when to use it.
* Make sure the skill is attached to the right agent. ([Gumball](/core-concepts/gumball) can access all skills in your space. Custom agents only see attached skills.)
</Accordion>
<Accordion title="Why did my skill update not save after I corrected the agent?" icon="crosshairs">
A few edge cases can prevent changes from being saved:
* **Invalid `SKILL.md` frontmatter**: If `SKILL.md` is missing required fields like `name` or `description`, or the YAML is malformed, the skill update is skipped and the previous version stays intact.
* **Rename mismatch**: If the skill folder name and the `name:` field do not match, saving is skipped.
* **Concurrent edits**: If two conversations edit the same skill at the same time, the last conversation to finish wins.
* **Conversation ended abnormally**: Skill edits are saved at the end of a completed agent turn. If the conversation crashes, is interrupted, or ends before the agent's turn finishes, any skill changes made during that session may not have been saved. If you suspect this happened, check the skill and re-apply any corrections in a new conversation.
You can review what changed in the **Edits** tab on the skill's detail page, which shows a file-level diff for each version.
</Accordion>
</AccordionGroup>
## What kinds of skills should you build?
<CardGroup>
<Card title="Workflow skills" icon="list-check">
Multi-step business processes. Sales outreach sequences, onboarding checklists, content publishing workflows.
</Card>
<Card title="Knowledge skills" icon="book">
Domain expertise. Product features, pricing tiers, competitive positioning, company policies.
</Card>
<Card title="Template skills" icon="file-lines">
Consistent formatting. Email templates, report formats, Slack update structures, CRM field mapping.
</Card>
<Card title="Automation skills" icon="code">
Deterministic code the agent runs in the sandbox. Data transformations, metric calculations, invoice validation.
</Card>
</CardGroup>
<span />
### Calling connectors from scripts
Skill scripts can call connected services from Python with the built-in **gumloop-sdk** skill. Use this when a task needs batch reads, filtering, calculations, or several calls whose results feed into one another.
The SDK uses the connector access already configured for the agent. It takes the **server ID** and **tool name** as separate arguments, rather than one `server__tool` string. Ask the agent to load **gumloop-sdk** and discover the exact tools and input schemas before writing the script.
<Note>`gumcp-client` is the older integration client. Use **gumloop-sdk** for new skill scripts.</Note>
<AccordionGroup>
<Accordion title="Example: Count words across repository documents" icon="file-lines">
A script can read several Markdown files through the GitHub connector, calculate their word counts, and return only the summary instead of every file's full contents.
```python theme={"dark"}
import base64
import sys
from gumloop import Gumloop
client = Gumloop()
repo_url = sys.argv[1]
paths = sys.argv[2:]
for path in paths:
result = client.mcp.execute(
"github",
"get_contents",
{"repo_url": repo_url, "path": path},
).results[0]
if result.status != "success":
raise RuntimeError(result.error)
data = result.decoded_content
if isinstance(data, list):
data = data[0]
text = base64.b64decode(data["content"]).decode("utf-8")
print(path, len(text.split()), "words")
```
Save this script in the skill, then pass the repository URL and Markdown file paths when running it. The GitHub connector must be available to the agent, and the connected account must be able to read that repository.
</Accordion>
</AccordionGroup>
<Tip>Server IDs are not always the service's display name. For example, Google Sheets uses `gsheets` and GitHub uses `github`. Have the agent discover the tool's schema instead of guessing its name or parameters.</Tip>
#### When to use scripts vs. direct tool calls
Your agent can already call integrations directly — "read this spreadsheet" or "send this Slack message" work fine as regular tool calls. **You don't need scripts for most integration tasks.** Both approaches have strengths:
| | Direct tool calls | Scripts in the sandbox |
| - | - | - |
| **Best for** | Simple, one-off actions | Multi-step processing, large data, exact calculations |
| **Example** | "Send this email", "Post to Slack" | "Read 500 rows from Sheets, compute totals, format a report" |
| **Agent sees** | The full tool response — can reason about it, ask follow-ups | Only the printed output — data stays in the sandbox |
| **Repeatability** | Agent decides approach each time | Script runs identically every time, saved in the skill |
| **Token cost** | Full response goes into context window | Data processed in sandbox, only summary enters context |
| **Flexibility** | Agent can adapt based on what it gets back | Logic is fixed in code — great for precision, less adaptive |
**Start with direct tool calls.** They're simpler, and the agent can reason about the results conversationally. Move logic into a script when you hit one of these cases:
* The tool response is very large and you only need a subset (avoids flooding the agent's context)
* You need to chain multiple calls together (read → filter → compute → write) without round-tripping
* The calculation must be exact every time (Python math vs. the agent estimating)
* The same process should run identically across conversations — save it once, reuse everywhere
<Info>**Most skills don't need scripts or integration calls.** The majority of useful skills are just well-written instructions and templates. Integration scripts are a power feature for when you need them, not a starting point.</Info>
<Accordion title="See detailed examples for each skill type">
**Workflow Skill: Sales outreach sequence**
* Step 1: Research the prospect
* Step 2: Personalize the email using a template
* Step 3: Log the activity in Salesforce
* Step 4: Set a follow-up reminder for 3 days later
**Knowledge Skill: Product knowledge base**
* Product features and pricing tiers
* Common customer questions and answers
* Competitive positioning
**Template Skill: Email templates by scenario**
* Cold outreach template
* Follow-up template
* Meeting request template
* Thank you template
**Automation Skill: Weekly analytics report**
* `SKILL.md`: Report structure and formatting rules
* `scripts/calculate_metrics.py`: Pulls data and computes KPIs
* `assets/report_template.md`: The markdown template
**Integration-Specific Skill: Salesforce deal management**
* When to create vs update opportunities
* Required fields for each stage
* Naming conventions for deals
* When to notify the team
</Accordion>
## Skill examples (inspiration)
If you want to see real skill folders, complete with `SKILL.md` files and supporting resources, browse these public examples:
* [Anthropic Skills examples repo](https://github.com/anthropics/skills/tree/main/skills)
<Info>If you have used Claude Skills before, the packaging concept is very similar: a folder with a `Skill.md` file and optional resources. Gumloop uses `SKILL.md` and adds agent-specific features like attaching skills to agents and letting agents improve skills over time. For reference, see [How to create custom Skills](https://support.claude.com/en/articles/12512198-how-to-create-custom-skills).</Info>
## Best practices
<AccordionGroup>
<Accordion title="Write specific descriptions" icon="bullseye">
The description is how your agent decides whether to load a skill. Be specific about **what** it does and **when** to use it.
**Good:** "Generate weekly sales performance reports from BigQuery data, formatted as Markdown tables with week-over-week comparisons. Use when the user asks for sales reports or weekly metrics."
**Bad:** "Helps with reports."
A vague description means the agent might never find your skill.
</Accordion>
<Accordion title="Keep skills focused" icon="crosshairs">
One skill should do one thing well. Don't create a mega-skill called "everything" with 3,000 lines of instructions.
Instead of one "sales-operations" skill, create:
* `outreach-playbook` (email sequences)
* `crm-logging` (Salesforce field mapping)
* `deal-qualification` (scoring criteria)
Focused skills are easier to maintain, share, and compose.
</Accordion>
<Accordion title="Include examples in your instructions" icon="lightbulb">
Show the agent what good output looks like. Include sample inputs and expected outputs in your `SKILL.md`.
```text theme={"dark"}
## Example
Input: "Draft an email to John at Acme Corp"
Expected output:
- Subject: Quick question about [specific thing]
- Greeting: Hey John,
- Body: 2-3 sentences, personalized
- CTA: One clear ask
```
Agents learn better from examples than abstract descriptions.
</Accordion>
<Accordion title="Use scripts for things that must be exact" icon="calculator">
If the skill involves math, data formatting, or any logic that needs to be 100% correct every time, put it in a Python script in the `scripts/` directory. Don't rely on the agent to reason through calculations.
**The pattern works like this:**
1. **`SKILL.md`** describes *when* and *why* to run the script (e.g., "After collecting the sales data, run the commission calculator to compute payouts")
2. **The script** handles the *how* — deterministic logic that produces the same correct result every time
3. **The agent** executes the script in its sandbox, reads the output, and uses it in the response
This separation means the agent handles context and judgment (which deals to include, how to present results) while the script handles precision (the actual math).
**Example: Sales commission calculator**
`SKILL.md` instructions:
```text theme={"dark"}
## Computing Commissions
When the user asks for commission calculations:
1. Collect the deal data (rep name, deal value, deal stage)
2. Run: python3 scripts/calculate_commission.py --input deals.json
3. Present the results in a table, highlighting any reps above quota
```
`scripts/calculate_commission.py` handles the actual math:
```python theme={"dark"}
# Tiered commission rates, quota thresholds, accelerators
# — all encoded in code, not left to the agent
```
Other good candidates for scripts: tax calculations, metric aggregations, data transformations, invoice validation, and any formula-driven logic.
</Accordion>
<Accordion title="Start simple, let the agent improve it" icon="seedling">
You don't need to write the perfect skill on day one. Create a basic version with core instructions, then let the agent refine it through usage.
Create a simple skill via "Write Skill Instructions" → use it a few times → give feedback → the agent updates the skill → repeat.
</Accordion>
<Accordion title="Don't duplicate the system prompt" icon="copy">
If your system prompt says "Always be professional" and a skill says "Use casual language," the agent gets confused.
**System prompt** = who the agent is (always active).
**Skills** = how to do specific tasks (loaded on demand).
Keep them separate and non-contradictory.
</Accordion>
<Accordion title="Keep SKILL.md under 500 lines" icon="file-lines">
Skills exceeding 500 lines trigger a validation warning and consume significant tokens when loaded. Move detailed content to the `references/` directory instead — the agent can selectively read reference files as needed rather than loading everything at once.
</Accordion>
<Accordion title="Be mindful of skill scale" icon="gauge">
All attached skills are listed in the agent's system prompt (roughly 50–100 tokens per skill). Attaching a very large number of skills to a single custom agent adds meaningful token overhead on every request. Keep attached skills focused and relevant; use [Gumball](/core-concepts/gumball) if you need every skill you can access, since it discovers them on demand instead of listing them in the prompt.
</Accordion>
<Accordion title="Avoid these common mistakes" icon="triangle-exclamation">
* **Don't create catch-all mega-skills** with thousands of lines — break them into focused, single-purpose skills.
* **Don't duplicate system prompt content in a skill** — if it applies to every interaction, it belongs in the system prompt.
* **Don't create skills that just restate tool documentation** — skills should add your business logic and process, not explain how Gmail works.
* **Don't put time-sensitive information in skills without labeling it** — "Q4 promotion ends Dec 31" will be wrong in January.
</Accordion>
</AccordionGroup>
## Managing skills
You can view, search, and manage all your skills from the **Skills** page in the sidebar. Each skill shows its name, description, related connectors, last edit time, and creator.
<Frame>
<img alt="The Skills page showing skill search, creation, and management" />
</Frame>
### Finding skills
Use the tabs at the top of the Skills page to switch between views:
| Tab | What It Shows |
| - | - |
| **Mine** | Skills you created |
| **Shared with me** | Skills that others have shared with you directly or via your organization |
| **Organization** | All skills visible to your entire organization |
<Frame>
<img alt="Skills page showing the Shared with me tab" />
</Frame>
### Popular skills
At the top of the Skills page, a **Popular Skills** carousel highlights the most-used skills in your workspace. These are ranked automatically based on usage across your team — skills that are referenced, run, or viewed most frequently appear here. Click any card to open the skill's detail page.
<Frame>
<img alt="Popular Skills carousel showing the most-used skills in the workspace" />
</Frame>
### Searching and filtering
The Skills page includes a search bar and a **Filters** panel to help you find exactly what you need.
**Search** works server-side — type a query and results are filtered by skill name and description as you type (with a short debounce so it doesn't fire on every keystroke).
Click the **Filters** button to open the filter panel. Available filters:
<Frame>
<img alt="Skills filter panel showing Sort by, Creator, Connector, In use by, and Not in use options" />
</Frame>
| Filter | What it does |
| - | - |
| **Sort by** | Order results by **Newest**, **Oldest**, **Most Used**, or **Popular**. Defaults to Newest. |
| **Creator** | Show only skills created by a specific team member. |
| **Connector** | Show only skills linked to a specific integration (e.g., Google Sheets, Slack). This uses the `related_server_ids` field in the skill's frontmatter. |
| **In use by** | Show only skills attached to a specific agent. |
| **Not in use** | Toggle to show only skills that are not currently attached to any agent — useful for cleanup. |
<Info>The **In use by** and **Not in use** filters are mutually exclusive. Enabling the "Not in use" toggle automatically clears any agent filter, and vice versa.</Info>
All filters are reflected in the URL as query parameters, so you can bookmark or share filtered views with your team. A badge on the Filters button shows the number of active filters, and you can clear them all at once with the **Clear Filters** button inside the panel.
### Skill detail page
Clicking on a skill opens its detail page, which has a left panel with metadata and a right panel showing file contents. The left panel is organized into four tabs:
<Frame>
<img alt="Skill detail page showing the Files tab with SKILL.md, references, and scripts folders" />
</Frame>
<Tabs>
<Tab title="Files">
The default view. Shows the skill's file tree on the left, with `SKILL.md`, plus any `references/`, `scripts/`, and `assets/` folders. Click a file to preview its contents in the right panel. You can also download the skill from the header.
#### Editing Files Directly
You can edit any text file in a skill directly from the browser. Click the edit icon in the top-right corner of the file preview to switch to edit mode.
<Frame>
<img alt="Skill file editor showing the SKILL.md file open for editing with the edit toggle in the top-right corner" />
</Frame>
The file viewer has three modes, toggled by the icons in the top-right:
| Icon | Mode | What it does |
| - | - | - |
| File icon | **Preview** | Read-only view of the file (default) |
| Pencil icon | **Edit** | Edit the file contents directly |
| Diff icon | **Local Changes** | See a diff of all unsaved changes across files |
You can edit multiple files before saving. When you are ready, click **Commit** to save all your changes as a single new version. This creates a new entry in the Edits tab so you can always see what changed and roll back if needed.
<Tip>Use direct editing for quick fixes to instructions, updating templates, or tweaking scripts. For larger rewrites, you might prefer re-uploading a `.zip` file with all your changes.</Tip>
</Tab>
<Tab title="Edits">
A timeline of all file-level changes to the skill. Each entry shows what happened (file added, modified, or removed), which file was affected, when it happened, and who or which agent made the change. Click an entry to jump to that file in the preview.
</Tab>
<Tab title="Activity">
A timeline of all usage events for the skill, including views, script runs, and edits. Each entry shows the action type, timestamp, and the user or agent involved. This gives you visibility into how actively a skill is being used and by whom.
</Tab>
<Tab title="Used by">
Shows which **agents** and **people** are using this skill, along with usage counts. Agent entries link directly to the agent's configuration page. This is useful for understanding the impact of a skill before editing or deleting it.
</Tab>
</Tabs>
### Usage tracking
Gumloop automatically tracks usage metrics for every skill:
* **Usage count** — how many times the skill has been used (script runs, referenced in conversations)
* **View count** — how many times the skill has been opened or viewed
* **Last used** — when the skill was last used by any agent or user
These metrics power the **Popular Skills** carousel and the **Most Used** / **Popular** sort options. They also appear in the skill detail page's Activity and Used By tabs.
### Sharing skills
<Tip>
Admins can centrally manage a shared skill library for the whole
organization — including keeping skills in sync with a GitHub repository — with
[Organization Skills](/core-concepts/organization_skills).
</Tip>
You can share skills with specific people, your team, your organization, or anyone with the link. Each person you share with gets a **role** that controls what they can do with the skill.
To share a skill, go to the [Skills page](https://www.gumloop.com/personal/skills), find the skill you want to share, click the **three-dot menu** (⋮), and select **Share**. You can also click the **share icon** in the skill detail view header.
<Frame>
<img alt="Skill share dialog showing role options: Editor, Viewer, and Use Only" />
</Frame>
#### Sharing roles
Skills support four roles. Each role builds on the one below it:
| Role | What they can do |
| - | - |
| **Owner** | Full control. Can edit, delete, share with others, and manage general access. Cannot be removed. |
| **Editor** | Can view the skill's files and source code, edit the skill, delete it, and manage sharing (add/remove Editors, Viewers, and Use Only users). |
| **Viewer** | Can view the skill's files, source code, and configuration. Can use the skill in agents. Cannot edit or delete. |
| **Use Only** | Can use the skill in agents, but **cannot** see the skill's files, source code, or configuration. This is ideal for sharing a skill with people who should benefit from it without seeing your proprietary instructions. |
<Info>
Every role (including Use Only) can **invoke** the skill, meaning it can be attached to and used by agents. The difference is what you can *see* and *change*.
</Info>
#### Sharing with specific people
1. Open the Share dialog for the skill
2. Type an email address in the **Add people** field
3. Click the dropdown arrow on the **Share** button to choose a role (Editor, Viewer, or Use Only)
4. Click **Share**
The person will get access immediately. You can change their role or remove them at any time from the same dialog.
#### General Access
General Access controls who can access the skill *without* being explicitly added by email. The options depend on where the skill lives:
| Setting | Who gets access |
| - | - |
| **Restricted** | Only people you've explicitly added (personal skills only) |
| **Team** | All members of the team the skill belongs to (team skills only) |
| **Organization** | All members of your organization |
| **Anyone with link** | Anyone, including people without a Gumloop account |
When you set General Access to Team, Organization, or Anyone, you also choose which **role** that audience gets (Editor, Viewer, or Use Only).
<Warning>
**Team skills cannot be set to Restricted.** If a skill lives in a team, the minimum access level is Team. All team members will have access.
</Warning>
#### Requesting access
If someone tries to open a skill they don't have access to, they'll see an **access gate** with a **Request Access** button. They can choose which role they'd like (Viewer, Editor, or Use Only). The skill owner or an editor receives a notification and can approve or deny the request with one click.
#### Examples
Here are some common sharing patterns:
<AccordionGroup>
<Accordion title="Share a skill with your team for everyone to use" icon="users">
Open the Share dialog, set **General Access** to **Team**, and pick the **Use Only** role. Everyone on the team can now use this skill in their agents, but they can't see or modify your instructions.
</Accordion>
<Accordion title="Let a colleague collaborate on a skill" icon="pencil">
Open the Share dialog, add their email, and select **Editor**. They can now view the source, make edits, and even share it with others.
</Accordion>
<Accordion title="Share a skill publicly as a template" icon="globe">
Set **General Access** to **Anyone with link** and select **Viewer**. Anyone with the link can see the skill's files and use it, but can't modify your original.
</Accordion>
<Accordion title="Protect proprietary logic while letting others benefit" icon="lock">
Add specific users with the **Use Only** role. They can attach the skill to their agents and benefit from its instructions, but they'll never see the underlying files, prompts, or scripts.
</Accordion>
</AccordionGroup>
#### Sharing FAQ
<AccordionGroup>
<Accordion title="Where is the Share button?">
On the [Skills page](https://www.gumloop.com/personal/skills), click the **three-dot menu** (⋮) on any skill you own or can manage, and select **Share**. You can also find the share icon in the header when viewing a skill's detail page.
</Accordion>
<Accordion title="Who can share a skill?">
Only **Owners** and **Editors** can manage sharing. Viewers and Use Only users cannot add or remove others.
</Accordion>
<Accordion title="Can a Use Only user see my skill's source code or files?">
No. Use Only users can **only** use the skill in agents. They cannot view the skill's files, instructions, or configuration. They see a message that says "Skill details unavailable" if they try to open the skill detail page.
</Accordion>
<Accordion title="Can I share a skill with someone outside my organization?">
Yes. You can share with any Gumloop user by email. They don't need to be on your team or in your organization.
</Accordion>
<Accordion title="What happens if I remove someone's access?">
They immediately lose access to the skill. If the skill was attached to one of their agents, the agent will no longer be able to load that skill.
</Accordion>
<Accordion title="Can I change someone's role after sharing?">
Yes. Open the Share dialog, click the role label next to their name, and select a new role. The change takes effect immediately.
</Accordion>
<Accordion title="Can I transfer ownership of a skill?">
Ownership is assigned at creation time. To transfer ownership, contact Gumloop support.
</Accordion>
</AccordionGroup>
<AccordionGroup>
<Accordion title="Downloading skill files" icon="download">
You can download a skill's files directly from the Skills page. Click the three-dot menu on any skill and select **Download**.
<Frame>
<img alt="Three-dot menu on a skill showing the Download option" />
</Frame>
</Accordion>
<Accordion title="Renaming and deleting" icon="trash">
From the three-dot menu on any skill, you can rename or delete it (requires Editor or Owner role). Deleted skills are soft-deleted (marked inactive rather than permanently removed), so they can potentially be recovered by Gumloop support if needed.
</Accordion>
</AccordionGroup>
## Next steps
<CardGroup>
<Card title="Agents overview" icon="compass" href="/core-concepts/agents">
Learn how to build and configure agents with tools, instructions, and skills
</Card>
<Card title="Using agents in Slack" icon="slack" href="/core-concepts/agents_slack">
Deploy your skilled agents to Slack channels for team-wide access
</Card>
</CardGroup>
# Subscription management
Source: https://docs.gumloop.com/core-concepts/subscription_management
Everything about a paid Gumloop subscription is handled from **Manage Subscription** on the [Usage & Limits page](https://www.gumloop.com/settings/organization/limits) (Settings > Organization > Usage & Limits). Select **Manage Subscription** to open the secure Stripe billing portal in a new tab.
## Who can open it
In an organization, only the [Admin](/core-concepts/organization_user_roles) role can open the billing portal.
## What you can do in the portal
| Task | Details |
| - | - |
| Download invoices and receipts | Download a PDF for each past payment, including the billing period and tax details |
| Update payment details | Update the card on file |
| Update billing details | Update the billing email, billing address, or tax ID |
| Cancel your plan | Cancel a trial or paid subscription |
## Download an invoice
1. Open the [Usage & Limits page](https://www.gumloop.com/settings/organization/limits).
2. Select **Manage Subscription** in the Plan card.
3. Find the payment under invoice history.
4. Download the PDF invoice or receipt.
If you need an invoice reissued or need PO or procurement paperwork, email [accounting@gumloop.com](mailto:accounting@gumloop.com).
## Cancel your subscription
1. Open the [Usage & Limits page](https://www.gumloop.com/settings/organization/limits).
2. Select **Manage Subscription** in the Plan card.
3. Select **Cancel plan** in the billing portal.
The plan stays active until the end of the current billing period. Until then, the Plan card shows a **Cancels** badge with that date, and your credits remain usable. During the 14-day Pro trial, cancelling stops the card from being charged when the trial ends.
<Note>You can resubscribe later from the [pricing page](https://www.gumloop.com/pricing). Cancelling a subscription does not delete your workspace or data.</Note>
## Enterprise plans
Enterprise subscriptions are invoiced directly, so the self-serve billing portal does not apply. Email [accounting@gumloop.com](mailto:accounting@gumloop.com) for invoices, PO numbers, or plan changes.
## Related
<CardGroup>
<Card title="Credits" icon="coins" href="/core-concepts/credits">
How credits and plans work
</Card>
<Card title="Organization roles" icon="users" href="/core-concepts/organization_user_roles">
Admin permissions and organization access
</Card>
<Card title="Pricing" icon="tag" href="https://www.gumloop.com/pricing">
Current plans and pricing
</Card>
<Card title="Billing questions" icon="envelope" href="mailto:accounting@gumloop.com">
Contact accounting about billing
</Card>
</CardGroup>
# Talk Mode
Source: https://docs.gumloop.com/core-concepts/talk_mode
Talk mode lets you **call your agent and speak to it** instead of typing. The agent answers out loud, and when you ask for something that needs real work — looking up a ticket, sending a message, running a skill — it does that work in the chat while you stay on the call.
Everything said on the call is written into the chat as ordinary messages, so a call is just another way to use a task you can scroll back through later.
***
## Turn on voice calls
[Gumball](/core-concepts/gumball), your personal agent, can always be called. **Custom agents have to opt in**, which the agent's editors do from the **Settings** tab, under **Voice**.
<Frame>
<img alt="Voice section of an agent's settings showing the Allow voice calls toggle turned on and a Voice dropdown set to Tempo" />
</Frame>
| Setting | What it does |
| - | - |
| **Allow voice calls** | Makes the agent callable. Anyone who can chat with the agent can also talk to it — voice follows the [sharing](/core-concepts/agent_access) you already set up, with no separate permission. |
| **Voice** | The voice the agent speaks in. Pick from Gumloop's voice list; agents use **Marin** until you choose another. |
<Note>Voice minutes use credits. See [Voice call costs](/core-concepts/credits#voice-call-costs) for the rate and how it appears in a chat's breakdown.</Note>
***
## Start a call
Open a chat with the agent and select the **voice button** at the right of the message bar, next to the microphone.
<Frame>
<img alt="Agent message bar with the microphone button for dictation and, beside it, the voice button that starts a call" />
</Frame>
<Tip>The two buttons do different things. The **microphone** dictates a single message — your audio is [transcribed](/core-concepts/agents#voice-input) and sent as text. The **voice button** starts a live call where the agent talks back.</Tip>
You can start a call in a brand-new chat or in one you have already been typing in; the agent hears the recent conversation either way.
***
## While you are on a call
<Frame>
<img alt="Chat during a voice call: the spoken request appears as a message labelled Voice call, the agent runs Linear tools below it, and a call bar at the bottom shows elapsed time with a microphone control and a red hang-up button" />
</Frame>
* **Your words appear in the chat.** Each thing you say is added as a message tagged **Voice call**, and the agent's spoken replies are added as its messages.
* **Small talk is answered on the call**; real requests are handed to the agent, which then runs in the chat exactly as if you had typed them — thinking, tool calls, and steps all visible.
* **The agent tells you what it can do.** It knows its connected apps, skills, and knowledge, so you can ask "can you check Linear?" and get a truthful answer.
* **The call bar** at the bottom shows how long you have been talking, with a microphone control and a **red button to hang up**.
Ending the call leaves the chat exactly where it was: the transcript, the agent's work, and any files it produced stay in the task.
***
## Good to know
* **One call per task.** A chat can hold one live call at a time. If several calls are already running on your account, the next one is refused until you end one.
* **Model access applies.** If your organization restricts which models you can use, the voice model may be blocked for you. The call says so, and you can request access from an admin.
* **Credits run the call.** You need credits for the minute ahead, so a call ends if your balance runs out mid-conversation.
* **Calls happen in the browser.** You start a call from the agent's chat in Gumloop.
***
## FAQ
<AccordionGroup>
<Accordion title="Do I need to give people extra permission to call an agent?">
No. Voice follows chat access: if someone can chat with the agent, they can call it once **Allow voice calls** is on.
</Accordion>
<Accordion title="Can I still see what was said after the call?">
Yes. The call is transcribed into the chat as it happens, so the task holds both sides of the conversation along with everything the agent did.
</Accordion>
<Accordion title="How is a call billed?">
By time, not by tokens, and it shows up as **Voice** in the chat's credit breakdown. Work the agent does during the call — tool calls, thinking, compute — is billed the usual way on top. See [Voice call costs](/core-concepts/credits#voice-call-costs).
</Accordion>
<Accordion title="What is the difference between the microphone and the voice button?">
The microphone records one message and sends it as text. The voice button opens a live, two-way call.
</Accordion>
</AccordionGroup>
# Organization and teams
Source: https://docs.gumloop.com/core-concepts/teams
<Info>
Organizations and Teams are available only on the **Pro plan** and above.
</Info>
## At a glance
**Think of Gumloop like Google Workspace:**
<CardGroup>
<Card title="Organization" icon="building">
Your company's account that manages billing, users, and security
</Card>
<Card title="Personal space" icon="user">
Your private space for building and running agents. Other people cannot browse it, but an agent you share still follows [Agent Access](/core-concepts/agent_access), and organization administrators retain administrative access.
</Card>
<Card title="Team" icon="users">
A shared space where multiple people can view, edit, and run agents together
</Card>
</CardGroup>
<Tip>
Everyone in your organization shares the same credit pool. Start with your personal space for most work, and create teams when you need true collaboration.
</Tip>
***
## Personal vs team
Most agents should live in your personal space. Create teams only when collaboration is essential.
| | **Personal** (Recommended) | **Team** |
| - | - | - |
| **Who can see agents?** | Only you by default. You can add people to an [agent](/core-concepts/agent_access) as Owners or Users, and share skills as Editors, Viewers, or Use Only. | All team members get **User** access to team agents by default, with options to share more broadly |
| **Who can edit agents?** | Only you by default. Add someone as an agent **Owner** to let them change it. | Team membership does not allow editing — add them as an **Owner** on the agent |
| **Who can run agents?** | You directly; anyone you added as an Owner or User | All team members can start tasks with team agents. Others via sharing |
| **Best for** | Most agents, development, testing, production | True collaboration where multiple people maintain the same agents |
| **Available on** | All plans | Pro plan and above |
<Tabs>
<Tab title="Personal space" icon="star">
Every user gets a personal space automatically when they sign up. **This is where most of your work should happen.**
* **Fast and flexible**: Build without worrying about breaking others' work
* **Secure by default**: Your agents and data stay private
* **Production-ready**: Run production agents that you maintain
* **Safe experimentation**: Test ideas without affecting your team
<Info>
Your personal space is private by default, but you can share any agent with specific users by email. Agents have two roles, **Owner** (manages it) and **User** (uses it) — see [Agent Access](/core-concepts/agent_access). Skills use **Editor**, **Viewer**, and **Use Only** — see [Sharing a skill](/core-concepts/skills#sharing-skills). You can also set General Access to share with your entire organization.
</Info>
</Tab>
<Tab title="Team" icon="users">
Teams let multiple members work on the same agents together. **Use these when true collaboration is essential.**
* **Multiple owners**: Several people can be made Owners of the same agent
* **Shared visibility**: Team members get User access to team agents by default, and can see each other's tasks when [Task Visibility](/core-concepts/agent_access#task-visibility) allows it
* **Team connectors**: Agents can use accounts shared with the team
* **Department resources**: Agents and skills used across an entire team
<Warning>
All team members get **User** access to team agents by default, which lets them run the agent but not change it. To let someone change an agent, add them as an **Owner** in its Access tab. You can also share with users outside the team. Use teams intentionally, not by default.
</Warning>
</Tab>
</Tabs>
***
## Understanding organizations
An **Organization** is your company's top-level account. It's the umbrella that holds everything together.
<AccordionGroup>
<Accordion title="Billing & credits" icon="credit-card">
All users share one credit pool. When anyone runs an agent, whether in their personal space or a team, it deducts from the organization's credits.
There's no separate billing per team or per user. One unified account.
</Accordion>
<Accordion title="User management" icon="user-group">
* Anyone with your company email domain automatically joins your organization (if [domain whitelisting](https://docs.gumloop.com/core-concepts/organization_user_roles) is enabled)
* **Invite users by email** — invited users appear with a "Pending" status until they accept
* Organization admins can **resend** or **revoke** pending invitations
* Add, remove, and manage user permissions across all teams
* Set which team new members join by default
<Frame>
<img alt="Organization members list showing a pending invite with Resend Invite and Revoke Invite actions" />
</Frame>
<Tip>
Gumloop's roles are **additive**, so a user can hold multiple roles at once (for example, `{Member, Analytics, Templates}`). Use the **Manage Access** sheet on the members page to add or remove individual roles instead of promoting or demoting users.
</Tip>
[Learn more about user roles and permissions →](/core-concepts/organization_user_roles)
</Accordion>
<Accordion title="Settings & compliance" icon="gear">
* Control security settings across all teams
* Manage data retention policies
* Set organization-wide defaults
* Monitor usage across all teams
</Accordion>
</AccordionGroup>
[View Organization Settings →](https://www.gumloop.com/settings/organization/general)
<Frame>
<img alt="Organization overview" />
</Frame>
***
## Creating a team
There are two ways to create a team.
### Option 1: From the sidebar
On the [Home page](https://www.gumloop.com/hub), find the **Teams** section in the sidebar and click the **+** icon.
<Frame>
<img alt="Click the plus icon in the Teams sidebar section" />
</Frame>
Give your team a name, choose a logo, and pick a brand color. Then click **Create**.
<Frame>
<img alt="New Team dialog with name, logo, and brand color options" />
</Frame>
### Option 2: From organization settings
Go to [Settings → Teams](https://www.gumloop.com/settings/organization/teams) and click the **Create** button.
<Frame>
<img alt="Teams page in organization settings with the list of teams and the Create button" />
</Frame>
***
## Adding team members
Once you've created a team, there are three ways to add members.
### Option 1: Invite to team from the sidebar (quickest)
On the [Home page](https://www.gumloop.com/hub), **right-click** on your team in the sidebar and select **Invite to Team**. This opens the invite dialog directly, letting you add members without navigating to settings.
<Frame>
<img alt="Right-click a team to see Settings, Invite to Team, and Leave team options" />
</Frame>
Enter the email address of the person you want to invite. They'll receive an invite and will be added automatically once they accept.
### Option 2: From team settings
On the [Home page](https://www.gumloop.com/hub), **right-click** on your team in the sidebar and select **Settings**.
<Frame>
<img alt="Right-click a team to access Settings" />
</Frame>
Click the **Add Member** button and enter their email address. They'll receive an invite and will be added automatically once they accept.
### Option 3: From organization settings
1. Go to [Settings → Teams](https://www.gumloop.com/settings/organization/teams)
2. Click on the team you want to manage
3. Click **Add Member** in the Team Members section
<Frame>
<img alt="Team Overview page in organization settings showing Team Name, Logo, Brand Color, and the Team Members list with the Add Member button" />
</Frame>
***
## Connecting team connectors
Team connectors are shared integrations and API keys that all team members can use when running agents. There are two ways to connect them for a team.
### Option 1: From the sidebar
On the [Home page](https://www.gumloop.com/hub), expand your team in the sidebar and click **Connectors**.
<Frame>
<img alt="Team section in the sidebar with Agents, Brain, Skills, Artifacts, Connectors, Tasks, Vault, and Workflows" />
</Frame>
Find the app you need under **Discover** or **All** and click **Add** to connect it with the shared account. If you are not a team admin, the button reads **Request** and sends the connection to an admin instead.
<Frame>
<img alt="Team Connectors page with Discover, All, and Connected tabs and a searchable list of connectors" />
</Frame>
### Option 2: From organization settings
1. Go to [Settings → Teams](https://www.gumloop.com/settings/organization/teams)
2. Click on the team, then select **Manage Connectors**
3. Find the app and click **Add**
<Tip>
Team connectors are available to all team members. For personal integrations that only you use, connect them from your personal [Connectors page](https://www.gumloop.com/settings/profile/connectors?view=connected) instead.
</Tip>
***
<span />
## Moving agents between teams
You can move agents between your personal space and teams:
1. Go to the [Home page](https://www.gumloop.com/hub)
2. Click the three dots (⋮) next to the agent
3. Select **Move to Team**
4. Choose the destination team
You can always move them back if needed. Once in a team, all members can edit them until you move them elsewhere.
***
## Setting a default team
Organization admins can choose which team new members automatically join from the [Teams settings page](https://www.gumloop.com/settings/organization/teams).
<Frame>
<img alt="Teams list with the three-dot menu open on Make Default, described as setting the team as the organization default" />
</Frame>
When someone with your company email signs up:
1. They automatically join your organization
2. They get their personal space
3. They get access to the default team
4. They can request access to other teams
***
## Common questions
<AccordionGroup>
<Accordion title="I shared a link. What can others do with it?" icon="share-nodes">
What others can do depends on their **access level**, which you control through the Share dialog:
* **No access / not shared**: They can see a preview but cannot interact. They can request access from the owner.
* On an **agent**: **User** lets them run it and see whatever the [User Permissions](/core-concepts/agent_access#user-permissions) allow. **Owner** lets them change it.
* On a **skill**: **Use Only** runs it without seeing the setup, **Viewer** can look but not change, **Editor** can change it.
You can also set **General Access** to give your entire team, organization, or anyone with the link a specific role. For public links (Anyone), unauthenticated users are capped at the most limited role.
<Tip>
Want someone to just use your automation without seeing how it works? Add them to the agent as a **User** with the setup hidden, or share it as an interface.
</Tip>
</Accordion>
<Accordion title="Where should I build my agents?" icon="hammer">
**Always start in your personal space.** Move to a team only if multiple people need to actively edit the same agent.
**Keep in personal space if:**
* You're the primary maintainer
* It's still in development or testing
* Others just need to run it (share via interface)
**Move to a team if:**
* Multiple people actively edit the same agent
* The team collectively maintains it
* You need shared team connectors
* Team members need to cover for each other
</Accordion>
<Accordion title="Who pays for agents in different teams?" icon="credit-card">
**Your organization pays for everything.** Whether an agent runs from your personal space or a team, it uses your organization's credit pool. Teams only affect who can access and edit agents, not billing.
</Accordion>
</AccordionGroup>
***
## Related documentation
<CardGroup>
<Card title="Connectors" icon="plug" href="https://docs.gumloop.com/core-concepts/credentials">
Connect personal and team accounts
</Card>
<Card title="Credit usage & billing" icon="credit-card" href="https://docs.gumloop.com/core-concepts/credits">
How credits work across teams
</Card>
<Card title="User roles" icon="shield" href="https://docs.gumloop.com/core-concepts/organization_user_roles">
Organization and team permissions
</Card>
</CardGroup>
# Text Gumball
Source: https://docs.gumloop.com/core-concepts/text_gumball
Gumball has its own phone number. Text it from a phone number you've verified in Gumloop and your own [Gumball](/core-concepts/gumball) picks up the request, works on it with your connectors and skills, and texts you back.
<Frame>
<img alt="Gumball home screen with the Where to reach me section showing the Email, Text, and Slack rows" />
</Frame>
<CardGroup>
<Card title="iMessage, RCS, or SMS" icon="message-sms">
Text from your phone's messaging app. The same number works over iMessage, RCS, and SMS.
</Card>
<Card title="Your own Gumball" icon="user">
Everyone texts the same number. Each verified sender reaches their own Gumball, running on their own connectors and skills.
</Card>
<Card title="Follow-ups stay together" icon="list-check">
A reply continues the current task. A new request after a break starts a fresh one.
</Card>
<Card title="Approve by text" icon="circle-check">
When a tool call needs your approval, reply `approve` instead of opening Gumloop.
</Card>
</CardGroup>
***
## Get started
<Steps>
<Step title="Open the Gumball home screen">
Find the **Text** row under **Where to reach me** in the right-hand rail. It shows Gumball's phone number.
</Step>
<Step title="Verify your phone number">
If you haven't verified a number yet, clicking the **Text** row opens **Add a phone number**. Enter your mobile number, click **Text me a code**, then enter the 6-digit code under **Enter your code** and click **Verify number**.
</Step>
<Step title="Text Gumball">
Once you have a verified number, clicking the **Text** row copies Gumball's number. Save it as a contact and send it a message from your verified phone.
</Step>
</Steps>
<Info>The **Text** row only shows when texting Gumball is available on your deployment. If your role isn't allowed to text Gumball, the row reads **Texting Gumball is off for your role** and clicking it lets you request access. See [Availability and Permissions](#availability-and-permissions).</Info>
***
## Verifying your phone number
Gumball only answers phone numbers verified in Gumloop. The sender's number is how Gumloop knows which account — and which Gumball — a text belongs to.
| Detail | Value |
| - | - |
| **Number format** | International format, like `+14155550123`. |
| **Code length** | 6 digits, sent to your phone by text. |
| **Code expiry** | 10 minutes. |
| **Resend** | Available after 60 seconds (**Request a new code in …s**). |
| **Wrong codes** | After 5 failed attempts the code stops working. Request a new one. |
| **Code requests** | Up to 5 per hour per account, and 5 per hour to the same number. |
| **One account per number** | A number linked to another Gumloop account can't be verified again (**This phone number is already linked to another Gumloop account.**). |
### Texting before you verify
If you text Gumball from a number that isn't linked to a Gumloop account, Gumball doesn't run. It texts back instead:
> This number isn't linked to a Gumloop account.
>
> New to Gumloop? Get started at …
> Already have an account? Verify this number at …
The verification link opens a Gumloop page with your number already filled in. Sign in, confirm the code, and once you see **Number linked**, text Gumball again. The page also has an **Open Gumball** button.
### Managing your numbers
Verified numbers are listed under **Phone numbers** at **Settings → Profile → [General](https://www.gumloop.com/settings/profile/general)**.
* **Add phone number** opens the same verification flow.
* Each number's menu has **Copy number** and **Remove number**.
* Removing a number means agents with texting enabled stop answering texts from it. You can verify it again later.
<Tip>You can verify more than one number. Gumball answers any of them.</Tip>
***
## What you can send
| Message | What happens |
| - | - |
| **Text** | Starts or continues a task with Gumball. |
| **Photos and files** | Downloaded and passed to Gumball as attachments, up to 32 MB each. Text and attachments can be sent together. |
| **Group chats** | Ignored. Gumball only answers one-to-one chats. |
| **Empty messages** | Ignored. |
<Note>Each sender can send up to **20 texts per minute** and **200 per hour**. Over that, Gumball replies "You're texting faster than I can keep up. Give it a minute and try again." instead of starting a task.</Note>
***
## How a conversation works
<Steps>
<Step title="Gumball sees your text">
Your message is marked as read as soon as it's picked up. On iMessage, you also see a typing indicator while Gumball works. SMS and RCS don't get typing indicators.
</Step>
<Step title="Gumball decides: same task or new task">
Texts have no threads, so Gumball decides whether your message continues the current task or starts a new one. See [Follow-ups and New Tasks](#follow-ups-and-new-tasks).
</Step>
<Step title="Gumball works on it">
It runs like any other Gumball chat, with your connectors, skills, and history. If the task has to wait for a workflow run to finish, you first get "Working on it. I'll text you when it's done."
</Step>
<Step title="Gumball texts back">
The answer arrives in the same chat, written for a phone. Typing stops when the reply is sent.
</Step>
</Steps>
### Follow-ups and new tasks
Gumball uses the time since your last message, and what you wrote, to decide:
| Situation | Result |
| - | - |
| Gumball is still working on your previous message | **Continues** the current task. |
| Less than **20 minutes** since the task's last activity | **Continues** the current task. |
| **7 days** or more since the task's last activity | **Starts a new task**. |
| Anything in between | A model checks whether your text refers back to the prior task — answering a question Gumball asked, giving an approval or correction, or asking about status — or stands on its own. It starts a new task only when your text is clearly a new request. If the check fails, it continues. |
When a new task starts, Gumball still gets a short recap of your last text conversation as background, so you can refer back to it. Older conversations aren't lost either: Gumball can search your past conversations.
<Info>There's no command to force a new task. Just send your new request — or wait, since anything 7 days after the last activity starts fresh.</Info>
***
## What replies look like
Gumball is told it's writing a text, not an email: short, plain sentences that match your length and tone, no Markdown, tables, lists, or headers, and links on their own line.
| Part of the reply | How it's sent |
| - | - |
| **Text** | Any remaining Markdown is converted to plain text. Long replies are split into texts of up to 1,500 characters each. |
| **Very long replies** | Capped at 6 texts. Anything beyond that is cut and replaced with "The full reply is too long for a text. Open it in Gumloop." |
| **Images** | Sent as picture messages. If an image can't be sent, you get a link instead. |
| **Other files** | Sent as a `name: link` line you can tap to open or download. |
| **Nothing to say** | "I finished, but I don't have anything to send back for that." |
<Tip>Gumball won't use a messaging tool to send its reply — your answer always comes back to the phone that asked. It only uses messaging tools when you ask it to message someone else.</Tip>
***
## Approving actions by text
When a tool call needs your [approval](/core-concepts/human_in_the_loop), Gumball texts you what it wants to do, followed by:
> Reply "approve" to approve, or review in Gumloop: …
The approval is always sent as its own text, after the rest of the reply, so it's never cut off.
<AccordionGroup>
<Accordion title="How to approve" icon="check">
Reply `approve`. Capitalization and surrounding spaces don't matter. Every pending tool approval on that task is approved, and Gumball carries on and texts you the result. Your `approve` text isn't added to the conversation as a new request.
</Accordion>
<Accordion title="How to decline" icon="xmark">
There's no decline keyword. Open the review link and decline in Gumloop.
</Accordion>
<Accordion title="When approve won't work" icon="triangle-exclamation">
Some steps need more than a yes — for example, questions Gumball asked you. Those texts only include **Review in Gumloop** with a link. If you reply `approve` anyway, you get "This one needs answers I can't take by text. Open the task in Gumloop to respond."
</Accordion>
<Accordion title="Other approval replies" icon="message">
| Reply | Meaning |
| - | - |
| "Nothing is waiting for your approval right now." | There's no pending approval. |
| "Only the person this approval was sent to can approve it. Open the task in Gumloop to see who that is." | The approval belongs to someone else. |
| "Approved. This task still needs an answer in Gumloop: …" | Your approval went through, but another step still needs input in Gumloop. |
| "I couldn't continue after your approval. Open Gumloop to retry." | The task couldn't resume. |
</Accordion>
</AccordionGroup>
While a task is waiting for approval, the typing indicator pauses.
***
## Opting out
Text any of these to stop receiving texts from Gumloop:
`STOP` · `UNSUBSCRIBE` · `OPTOUT` · `CANCEL` · `END` · `QUIT` · `opt out` · `opt-out`
The single-word keywords must match exactly (all caps, nothing else in the message). `opt out` and `opt-out` match in any capitalization.
* An opt-out text never starts a task.
* Once you've opted out, Gumloop stops sending texts to your number.
* Sending any other text afterwards turns texts back on, unless the messaging provider still reports your chat as opted out.
* A number that has opted out can't receive a verification code: "This number has opted out of texts from Gumloop, so we can't send a code to it."
***
## Availability and permissions
| Requirement | Details |
| - | - |
| **Plan** | Texting is an **Enterprise** feature. |
| **Gumball access** | Your role needs [Gumball access](/core-concepts/gumball#availability-and-permissions). Turning off Gumball for a role also turns off texting it. |
| **Gumball text messaging** | A separate permission for texting Gumball. Organization roles include it. |
| **Verified phone number** | Required. See [Verifying Your Phone Number](#verifying-your-phone-number). |
<Warning>For [custom roles](/enterprise-features/user_groups), **Gumball text messaging** ("Users can text Gumball from a phone number they verified.") is **restricted by default**. An admin has to grant it explicitly.</Warning>
### Messages when access is missing
If Gumball can't take your text, you get one of these instead. Each is sent at most once per hour per chat, so you won't get the same one repeatedly.
| Reply | Why |
| - | - |
| "This number isn't linked to a Gumloop account." | Your number isn't verified. Follow the link to verify it. |
| "Your organization hasn't turned on Gumball for your role." | Your role doesn't have Gumball access. Includes a link to request access. |
| "Your organization hasn't turned on texting Gumball for your role." | Your role has Gumball but not **Gumball text messaging**. Includes a link to request access. |
| "You're texting faster than I can keep up. Give it a minute and try again." | You hit the per-sender rate limit. |
| "Your message is queued and will be processed shortly." | Your message is waiting to run. |
| "You have too many tasks running right now. Try again shortly." | Too many of your tasks are running at once. |
***
## Credits
There's no per-message charge for texting. The work Gumball does for a text uses [credits](/core-concepts/credits) like any other Gumball task.
***
## FAQ
<AccordionGroup>
<Accordion title="Does everyone text the same number?" icon="phone">
Yes. Gumball has one shared number. Gumloop looks up who sent each text by their verified number and routes it to that person's own Gumball, so you never see anyone else's conversations.
</Accordion>
<Accordion title="Can I text Gumball from a group chat?" icon="users">
No. Group chats are ignored. Text Gumball one-to-one.
</Accordion>
<Accordion title="Why don't I see a typing indicator?" icon="ellipsis">
Typing indicators only work over iMessage. Over SMS and RCS, your message is still marked as read and Gumball still replies.
</Accordion>
<Accordion title="Why was Gumball's reply cut off?" icon="scissors">
Replies are capped at 6 texts of up to 1,500 characters each. Anything longer ends with "The full reply is too long for a text. Open it in Gumloop."
</Accordion>
<Accordion title="How do I start a new task?" icon="plus">
Just text the new request. If it's been more than 20 minutes and your message stands on its own, Gumball starts a new task. After 7 days, every message starts a new task.
</Accordion>
<Accordion title="Can I send Gumball a photo?" icon="image">
Yes. Photos and files you text are passed to Gumball as attachments, up to 32 MB each.
</Accordion>
<Accordion title="Can I link the same number to two accounts?" icon="link">
No. A phone number can only be verified on one Gumloop account at a time. Remove it from the other account first.
</Accordion>
<Accordion title="I texted STOP by accident. How do I turn texts back on?" icon="rotate">
Send Gumball any other message. That clears the opt-out.
</Accordion>
</AccordionGroup>
# Agent default settings
Source: https://docs.gumloop.com/enterprise-features/agent_default_settings
Organization admins can set the defaults used for new agents created in the organization. Open the [Agents](https://gumloop.com/settings/organization/agents) page in organization settings to customize the default settings for new agents created in this organization.
<Info>This feature is available to the organization **Admin** role on the **Pro** plan or higher. See the [organization role matrix](/core-concepts/organization_user_roles#admin).</Info>
<Frame>
<img alt="Organization Agents settings page showing default settings for new agents" />
</Frame>
There is one set of defaults per organization.
## Available settings
| Setting | What it controls |
| - | - |
| **Model** | The model the agent uses. |
| **Reasoning** | How much the model reasons before answering. |
| **Mode** | Fast mode responds faster at a higher credit cost. |
| **Context Window** | Maximum context the agent uses before summarizing older messages. |
| **Override Auto Summarization** | Override the default auto-summarization behavior for this agent. |
| **Summarization Trigger (%)** | Percent of the context window at which summarization is triggered. |
| **Summary Model** | Model used for generating chat history summaries. |
| **File Sharing Behavior** | Automatically set sharing permissions on files generated by this agent. |
The **Reasoning**, **Mode**, and **Context Window** settings are model-aware. They appear based on the model you pick and come from that model's settings schema. These are the same per-model settings described in [AI advanced settings](/core-concepts/agents#ai-advanced-settings).
For **File Sharing Behavior**, the available values are:
| Value | What it does |
| - | - |
| **Default** | Inherits sharing permissions from the chat and agent |
| **Organization** | Shared with everyone in your organization |
## How defaults apply
Every new custom agent created in the organization inherits these defaults for anything its creator does not set:
* The model and its model settings
* File-sharing behavior
* The agent's default abilities configuration, including which native abilities are on and which image model **Image Generation** uses
If your organization has no defaults, Gumloop's built-in defaults apply. Defaults do not change agents that already exist.
A few settings are never inherited:
* The agent icon
* The agent's self-improvement settings, which follow the creator, such as their timezone
Removing the organization defaults puts new agents back on Gumloop's built-in defaults.
# AI model governance & configuration
Source: https://docs.gumloop.com/enterprise-features/ai_model_control
Control which AI models your organization can use, which API keys those calls run on, and where those calls are sent. Both pages require the **Admin** or **Security** organization role ([role matrix](/core-concepts/organization_user_roles#security)), and every change is written to the [audit log](/enterprise-features/audit_logging).
| Page | What it controls |
| - | - |
| [Models](https://gumloop.com/settings/organization/models) | Which models members can use, the model behind each agent preset, and fallbacks for restricted models |
| [API Keys & Proxies](https://gumloop.com/settings/organization/api-keys) | Organization-wide provider API keys, plus proxy URL, custom headers, and model name mapping per provider |
<Note>Enterprise OAuth client configurations (Snowflake, Databricks, Okta, NetSuite, and so on) live on a separate page: [OAuth Configuration](https://gumloop.com/settings/organization/oauth-configuration).</Note>
***
## Models
The **Models** page has three tabs: **Restrictions**, **Presets**, and **Fallbacks**.
### Restrictions
Turn on **Model access control** with the "restrict models?" toggle, then pick an access mode:
* **Allow Only Selected** — members can use only the models you check. Best for a fixed, approved set.
* **Block Selected** — members can use every model except the ones you check. Best for general access with a few exclusions.
<Frame>
<img alt="Restrictions tab with a restrict models toggle, Allow Only Selected and Block Selected access modes, and models grouped by provider with allowed and denied counts" />
</Frame>
Models are grouped by provider with running **allowed** and **denied** counts. You can select or clear a whole provider at once, or search for a specific model.
<Note>
Restrictions set the **organization-wide ceiling**. To narrow access further, give each [Custom Role](/enterprise-features/user_groups#models-tab) its own model allow-list. A role can only allow models already permitted org-wide. Restricted models can appear in the picker marked **Restricted by Admin**, but members cannot select them.
</Note>
#### Auto (the model router)
[**Auto**](/core-concepts/ai_models#auto-let-gumloop-choose-the-model) lets Gumloop pick which model runs each agent message. It does not bypass this page:
* Restrictions and role allow-lists are enforced on the routing decision, the model Auto runs, any mid-run escalation, and fallbacks. A blocked model is skipped in favor of a permitted one.
* If a member has no permitted model left, the run fails with a model-restricted error rather than using a disallowed model. The **Fallback Model** is checked against your restrictions too.
* Auto appears in the model list like any other model, so you can block it. Agents already saved on Auto then run on a normal model with no routing.
* Auto is never a **Preset** target and never a fallback — those always name a specific model.
#### Models with 30-day data retention
Every model Gumloop serves runs under **Zero Data Retention** except Anthropic's **Claude Fable** family, where Anthropic keeps prompts and outputs for **30 days** to check for misuse, then deletes them. Anthropic does not train on that data, and no other model is affected.
These models are therefore **off for the whole organization** until an admin turns on **Allow non-zero data retention models** on the Models page. Enabling it is an explicit acknowledgement that Gumloop's zero data retention commitment does not apply to those models; the acknowledgement is stored with the administrator's name and date, and enabling and revoking are both audit-logged.
<Warning>**Revoking makes these models unavailable to everyone immediately.** Agents set to a Claude Fable model fail until they're switched to another model.</Warning>
<Note>Even when allowed, Claude Fable models are never selected on a member's behalf — they're excluded from the **Recommended** and **Smartest** presets, from **Auto**, and from fallbacks. See [Models with 30-day data retention](/core-concepts/ai_models#models-with-30-day-data-retention).</Note>
### Presets
Agents pick a model through two presets, **Recommended** (best balance of speed, quality, and cost) and **Smartest** (maximum intelligence for complex tasks). Point each preset at the model your organization prefers and members see your choice in the agent model picker instead of the Gumloop default.
<Frame>
<img alt="Presets tab showing the Recommended and Smartest presets, each mapped to a model" />
</Frame>
### Fallbacks
When an agent or flow references a model that is now restricted, Gumloop uses a permitted fallback when available. If no permitted model remains, the request fails rather than bypassing model restrictions.
<Frame>
<img alt="Fallbacks tab with a Fallback Model selector and an Image Generation Fallback Model selector" />
</Frame>
* **Fallback Model** — used when a restricted model is referenced.
* **Image Generation Fallback Model** — used when the selected image model is restricted.
***
## API keys & proxies
Add one API key per provider for the whole organization, and optionally route that provider's calls through your own proxy. Organization keys **override team and personal credentials** for every member, so usage, billing, and access control stay in one place.
### Supported providers
| Provider | What it covers |
| - | - |
| **OpenAI** | GPT models |
| **Anthropic** | Claude models |
| **Google Gemini** | Gemini models |
| **Perplexity** | Perplexity models |
| **SpaceXAI** | Grok models |
| **Fireworks AI** | The open models Gumloop serves through Fireworks: DeepSeek V4.1 Flash, DeepSeek V4 Flash, DeepSeek V4 Pro, Kimi K3, Kimi K2.7 Code, GLM-5.3, GLM-5.2, MiniMax M3, and Qwen3.8 Max |
<Note>
Every provider key earns the same [BYOK](/core-concepts/ai_models#bring-your-own-key-byok) credit discount, and only for the models that provider serves. A Fireworks key does not cover GPT-OSS 120B, Gemma 4 26B, or GLM-5.3-Flash, which Gumloop serves elsewhere.
</Note>
### Configure a provider
Open [API Keys & Proxies](https://gumloop.com/settings/organization/api-keys) and click **Add credential** on a provider (or **Edit** on one you already configured) to open the setup sheet.
<Frame>
<img alt="Configure AI provider sheet with an Anthropic API key field, a Configure proxy toggle, a proxy URL field, and empty custom headers and model name mapping sections" />
</Frame>
<Steps>
<Step title="Enter the API key" icon="key">
The key is required. It is stored encrypted and applies to every member of the organization.
</Step>
<Step title="Turn on Configure proxy (optional)" icon="route">
Enter a base URL only, such as `https://gateway.example.com`. It replaces the provider's default endpoint and must be reachable from Gumloop's infrastructure.
<Note>A proxy only takes effect when a key exists for that provider — the organization key, or the member's own. Requests through your proxy skip Gumloop's shared AI response cache, so every call reaches your infrastructure.</Note>
</Step>
<Step title="Add custom headers and model mappings (optional)" icon="sliders">
Both appear once the proxy toggle is on. See below.
</Step>
<Step title="Run the tests, then save" icon="circle-check">
Continue to the test step and save the configuration.
</Step>
</Steps>
### Custom headers
Add any headers your gateway needs, such as a gateway key or a cost-attribution header. Type `@` in a value (or drag a badge into it) to insert a placeholder that Gumloop substitutes per request.
<Frame>
<img alt="Custom headers row with a header name field and a value field showing insertable placeholder badges for API key, user email, user ID, organization ID, agent ID, session ID, flow ID, and run ID, above a model name mapping row" />
</Frame>
Available placeholders: **API key**, **User email**, **User ID**, **Organization ID**, **Agent ID**, **Session ID**, **Flow ID**, and **Run ID**.
<Note>Headers Gumloop sets itself can't be overridden, header names must be unique, and values can't contain line breaks — the sheet flags all three before you continue.</Note>
### Model name mapping
If your proxy uses its own model identifiers, map each Gumloop model to the name your proxy expects. Pick the model from the picker, then type the target name. The mapped name is used only on the wire; credits and usage are still tracked under the Gumloop model.
### Test configuration
Before saving, Gumloop tests the configuration with real requests. Every active model is selected by default; narrow the list with the **Models to test** picker.
Each model is checked for agent chats, agent tool calls, token counting, and AI calls in workflows because a gateway can serve chat completions and still not serve the others. Expand a row to see the per-model result, including the provider's error text (with secrets stripped) when a check fails.
When every check passes, the button becomes **Save**. If some fail, you can **Retry** or use **Save anyways** in the overflow menu — which will affect every agent and flow in the organization using that provider.
***
## What happens on a run
1. **Model selection** — restrictions and role allow-lists decide which models are available; a restricted reference uses the fallback model.
2. **Credential resolution** — the organization key wins over team and personal credentials.
3. **Routing** — the provider's proxy URL, custom headers, and model name mapping are applied.
4. **Execution** — the request goes to your proxy, or directly to the provider if none is configured.
***
## Related documentation
<CardGroup>
<Card title="AI models" icon="brain" href="/core-concepts/ai_models">
Available models, presets, Auto, and BYOK
</Card>
<Card title="Custom roles" icon="user-tag" href="/enterprise-features/user_groups">
Per-role model allow-lists and permissions
</Card>
<Card title="Audit logging" icon="file-lines" href="/enterprise-features/audit_logging">
Review administrative changes
</Card>
</CardGroup>
# App claims
Source: https://docs.gumloop.com/enterprise-features/app-policies/app-claims
Claim a provider workspace (a specific Slack workspace, Salesforce org, Notion workspace, etc.) for your organization so only your members can connect to it from Gumloop.
App Claims let your organization assert ownership of a specific third-party
workspace. Once claimed, anyone outside your organization who tries to connect
to that same workspace from Gumloop will be denied.
## What it does
Many apps treat each customer as a separate "instance" — a single Slack
workspace, a single Salesforce org, a single Notion workspace. When you claim
one from Gumloop, you're telling Gumloop: *"This specific workspace belongs to
our organization."*
From that point on:
* **Members of your org** can continue to connect to that workspace normally.
* **Anyone else** who tries to OAuth into the same workspace from Gumloop is
blocked, with a message saying the workspace is claimed by another
organization.
This is useful if you want to stop shadow accounts: somebody outside your
organization shouldn't be able to pull data out of your company's Salesforce
org via Gumloop, even if they happen to have login credentials to it.
<Info>
Only connectors whose services expose a stable workspace identifier during OAuth can be claimed. The **Claim** picker lists supported connectors, such as Slack, Notion, and Salesforce.
</Info>
## Claiming an app
Claims are always created through the OAuth flow. You can't claim a workspace
without actually signing into it.
<Steps>
<Step title="Open the Claims tab">
Go to [Settings → Organization → Policies → Claims](https://www.gumloop.com/settings/organization/policies?tab=app-claims).
</Step>
<Step title="Pick a connector">
Click **Claim**, then select a supported connector, such as Slack or Salesforce.
</Step>
<Step title="Complete OAuth">
Gumloop opens the provider's OAuth flow in a new tab. Sign in to the
specific workspace you want to claim for your organization.
</Step>
<Step title="Gumloop records the claim">
Once OAuth completes, Gumloop captures the workspace identifier and
creates the claim. The workspace now appears in your **Claimed** list and
enforcement starts immediately.
</Step>
</Steps>
<Warning>
Claim the right workspace. If an admin signs into the wrong Slack workspace
or the wrong Salesforce org during the OAuth step, Gumloop will claim that
one. You can delete a claim and start over if this happens.
</Warning>
## Managing claims
Each claimed workspace can be:
* **Renamed** — you can give the claim a friendly label so other admins know
what it corresponds to. The underlying workspace identifier stays the same.
* **Disabled** — toggle off to pause enforcement. Other organizations can
connect to the workspace again while the claim is disabled.
* **Deleted** — remove the claim entirely.
## What end users see
When someone outside your organization tries to connect to a workspace you've
claimed, their OAuth flow ends with an error explaining that the workspace is
claimed by another organization. They cannot proceed, and no credential is
stored on their account.
Members of your own organization never see this error — they connect normally.
## Related
<CardGroup>
<Card title="Domain restrictions" icon="at" href="/enterprise-features/app-policies/domain-restrictions">
Require OAuth connections to use a corporate email domain.
</Card>
<Card title="Connector policies overview" icon="shield-halved" href="/enterprise-features/app-policies/overview">
See how App Claims fit alongside App Rules and Domain Restrictions.
</Card>
</CardGroup>
# App Rules
Source: https://docs.gumloop.com/enterprise-features/app-policies/app-rules
Block or tag specific tool calls for third-party apps at the organization or agent level.
<div>
<iframe title="App policies and rules" />
</div>
App Rules let you intercept individual tool calls for any third-party app your organization uses and either **block** them or **tag** them for review. Each rule is a lightweight policy with a phase, an action, a scope, and a CEL condition that Gumloop evaluates automatically every time a tool call runs.
<CardGroup>
<Card title="Organization rules" icon="building">
Apply to **every user and agent** in your org. Manage at [Connector Policies settings](https://gumloop.com/settings/organization/app-policies).
</Card>
<Card title="Agent rules" icon="compass">
Apply to a **specific agent's** tool calls only. Manage via agent config or agent chat.
</Card>
</CardGroup>
***
## Rule scopes
<Tabs>
<Tab title="Organization-Level">
Organization-level rules are the default. They apply to **every user and agent** in your organization.
### Where to find it
Go to **Settings → Organization → Policies** at [gumloop.com/settings/organization/app-policies](https://gumloop.com/settings/organization/app-policies) and open the **Rules** tab.
<Frame>
<img alt="Policies page on the Rules tab showing Rules by Connector with a search box, a + Rule button, and rules grouped under Gmail, Linear, and Salesforce with Live toggles" />
</Frame>
### What you see
* **Rules by Connector**: every connector with its rules listed, each with a name, description, and **Live** toggle
* A **search box** and filter for finding rules across connectors
* **+ Rule** button to create a new rule
### Creating a rule
Click **+ Rule**, pick the connector, and the AI rule builder opens (see [Building a rule](#building-a-rule-with-the-ai-rule-builder) below). The rule is scoped to the entire organization by default.
### Active rules
Rules appear under their connector in the **Rules by Connector** list with a name, description, and **Live** toggle.
<Frame>
<img alt="Rules by Connector panel for Slack showing a rule named Block Messages to Restricted Slack Channel with a description and an enabled toggle" />
</Frame>
### What users see when blocked
The tool call fails with: *"This action has been restricted by your organization's security policy."*
The user doesn't see the rule's name, its condition, or which field tripped it. Admins can see the full context in the rule's **Activity** tab.
</Tab>
<Tab title="Agent-Level">
Agent-level rules target a specific agent, so they only apply to tool calls made by that agent. There are two ways to create them.
<AccordionGroup>
<Accordion title="Via the agent configuration panel" icon="gear">
When configuring an agent, open the detail view of any connected app. The **Rules** tab shows all rules targeting this agent for that app.
<Frame>
<img alt="Agent configuration panel showing the Rules tab for the Linear app with an active rule" />
</Frame>
You can toggle rules on or off and click through to the rule detail sheet.
</Accordion>
<Accordion title="Via agent chat (agent-created rules)" icon="message">
Agents can propose their own rules during a conversation. To enable this:
1. Open the agent's configuration panel and find the **Abilities** section.
2. Toggle **Rules Creation** to **ON**.
<Frame>
<img alt="Agent Abilities section showing the Rules Creation toggle set to ON" />
</Frame>
Ask the agent something like *"Create a linear app rule to never create a ticket without having at least two labels"* and it will propose a rule for your review.
All rule mutations require your explicit approval. You'll see a proposal card with **Accept** / **Reject** buttons.
<Frame>
<img alt="Agent chat showing a rule proposal card with the rule name, description, CEL condition, target tools, and Accept/Reject buttons" />
</Frame>
</Accordion>
</AccordionGroup>
### What the agent sees when blocked
The tool call fails with: *"This action has been restricted by a rule configured for this agent."*
<Info>Agent-created rules only apply to that specific agent's tool calls. They do not affect other agents, other users, or organization-wide policies.</Info>
</Tab>
</Tabs>
***
## How a rule works
Every rule has four core pieces of configuration:
<Steps>
<Step title="Phase (check_type)">
Pick **before** to check the call before it runs, or **after** to check it once the result comes back. Use *before* to block risky actions and *after* to tag calls based on what was returned.
</Step>
<Step title="Action">
Pick **block** to deny the call, or **tag** to let it through while labeling it with your rule's name for later review.
</Step>
<Step title="Scope">
Limit the rule to specific **tool names** on the app (e.g. only `send_message` in Slack, or only `create_event` in Google Calendar). Leave empty to apply to every tool on that app.
</Step>
<Step title="Condition">
A CEL expression that decides whether the rule fires. You have access to:
* `args`: the arguments the caller passed to the tool
* `tool_name`: the tool being called
* `server_id`: the app the tool belongs to
* `output`: the tool's return value (only in *after* rules)
Example: `args.channel == "C05QG7RF30A"` fires whenever Slack's `send_message` targets that specific channel.
</Step>
</Steps>
***
## Building a rule with the AI rule builder
Clicking **+ App Rule** (from either scope) opens the rule builder. The left panel is a chat with the AI assistant, and the right panel shows the live rule configuration and simulation results.
<Frame>
<img alt="Rule builder: left side is a chat with the AI assistant, right side shows the generated Rule Configuration JSON and a Simulation tab" />
</Frame>
<Steps>
<Step title="Describe the rule in plain English">
For example: *"Do not allow users to send messages in the general channel. Channel ID: C05QG7RF30A."*
The assistant will ask for any missing details. You can `@mention` tools on the app to pull them into the conversation.
</Step>
<Step title="Review the generated configuration">
The top-right panel shows the `check_type`, `action`, `tool_names`, and `conditions` the assistant produced.
</Step>
<Step title="Check the simulation">
Every time the assistant changes the rule, it re-runs it against recent tool calls and shows the verdict for each. Confirm it catches what you want (no false negatives) and doesn't catch anything unexpected (no false positives).
</Step>
<Step title="Save">
Click **Save** in the top right. The rule starts enforcing immediately once enabled.
</Step>
</Steps>
<Tip>The assistant also accepts follow-ups like *"Change this to block before execution instead of tagging after"* or *"Expand the conditions to cover more edge cases."* You don't have to edit the JSON by hand.</Tip>
<Accordion title="Suggested prompts to get started" icon="sparkles">
* *Help me create a new rule for this server*
* *What types of rules can I create?*
* *Show me examples of common security rules*
* *Help me set up a rule to block sensitive operations*
* *Explain how MCP rules work*
</Accordion>
***
## Editing a rule
Opening a rule takes you back into the rule builder. The right panel has three tabs:
<CardGroup>
<Card title="Simulation" icon="flask">
Re-runs the rule against recent tool calls so you can see the impact of any edit before saving.
</Card>
<Card title="Activity" icon="chart-line">
Shows actual tool calls this rule has evaluated, with verdicts (allowed, tagged, blocked), the user, and the call source.
</Card>
<Card title="Settings" icon="gear">
Rename, toggle enabled/disabled, view metadata, or delete the rule.
</Card>
</CardGroup>
<Accordion title="Settings tab details" icon="gear">
<Frame>
<img alt="Rule Settings tab showing Name, Description, Enabled toggle, metadata, and Delete Rule button" />
</Frame>
On the **Settings** tab you can:
* Rename the rule or change its description (changes save on blur)
* Toggle **Enabled** on or off
* See who created the rule, when, and last updated
* **Delete** the rule (cannot be undone)
</Accordion>
***
## Enforcement activity
Every evaluated tool call is recorded for auditing. You can view activity in two places:
* **App Rules tab** at the top of the Connector Policies page: enforcement across every rule in the org, with stat cards and a histogram
* **Activity tab** inside a specific rule: only that rule's history
Tool calls appear with one of three statuses:
| Status | Meaning |
| - | - |
| **Allowed** | The call ran normally, no rule matched. |
| **Tagged** | The call ran, but one or more `tag`-action rules matched. Matched rule names shown in the *Rule* column. |
| **Blocked** | A `block`-action rule matched and the call was denied. |
You can click any tool call to expand it and inspect the arguments and output.
***
## How overlapping rules interact
Rules at different scopes stack. When a tool call is evaluated, Gumloop checks **all** enabled rules across every scope that matches the caller:
* An **organization-wide** rule is always checked for every caller
* An **agent-scoped** rule is checked only if the caller is that specific agent
If *any* matching rule has action `block` and its condition fires, the call is blocked, regardless of what other rules say. There is no "allow" override.
<Tip>Think of it as layering: organization rules set the baseline, and agent rules add agent-specific restrictions. Each layer can only make things *more* restrictive, never less.</Tip>
***
## App Rules & Human in the Loop
App Rules are one part of a broader **Human in the Loop** system that keeps humans in control of AI agent actions. While App Rules use CEL conditions to automatically block or tag tool calls, the approval system gives you the option to **pause and ask** before a tool call executes.
### How they work together
App Rules and approval settings operate at different layers but complement each other:
| Layer | What it does | Example |
| - | - | - |
| **Approval Settings** | Simple toggles: always allow, ask each time, ask for writes/deletes, or custom per-tool. Based on the tool's risk category. | "Ask me before any Gmail write operation." |
| **App Rules** | Conditional CEL-based policies that evaluate tool call arguments at runtime. Can block or tag. | "Block emails to external domains" or "Tag any Slack message to #general." |
Both layers are evaluated for every tool call. Approval settings act as the baseline, and App Rules add conditional overrides on top. If an App Rule blocks a call, it is denied regardless of approval settings.
### Using App Rules for conditional approvals
A common pattern is combining **"Always allow"** approval settings with App Rules that **tag** specific calls for review. This lets most tool calls flow freely while flagging the ones that match your conditions for later auditing.
For example:
* Set Gmail approval mode to **Always allow**
* Create an App Rule that **tags** any email sent to recipients outside your company domain
* Your agent sends internal emails without interruption, while external emails are tagged and visible in the enforcement activity view
For more granular approval controls (where the agent pauses and waits for you to approve or reject), see the [Human in the Loop documentation](/core-concepts/human_in_the_loop).
<AccordionGroup>
<Accordion title="Example: conditional approval via agent chat" icon="message">
You can ask your agent to create an App Rule in natural language. For instance: *"Create a human approval rule for any email sent to users without the gumloop.com domain."*
The agent translates this into a CEL condition and shows you a proposal card:
<Frame>
<img alt="Agent creating an approval rule for non-gumloop.com email recipients via chat, showing the CEL condition" />
</Frame>
Once approved, the rule appears in the app's config:
<Frame>
<img alt="Gmail app configuration showing the Rules section with an active approval rule for external email recipients" />
</Frame>
</Accordion>
<Accordion title="Example: approval card in the web chat" icon="browser">
When a tool call triggers an approval requirement, the agent pauses and shows an approval card directly in the conversation:
<Frame>
<img alt="Approval card in the web chat showing an email send request with To, Subject, and Body fields, plus Reject and Approve buttons" />
</Frame>
You can review the tool name, intent, and arguments, then **Approve** or **Reject**. Check **"Don't ask again for this tool"** to auto-approve future calls to the same tool.
</Accordion>
</AccordionGroup>
<Info>To set up approval settings, the Ask Question ability, and notification channels for approvals, see the full [Human in the Loop guide](/core-concepts/human_in_the_loop).</Info>
***
## FAQ
<AccordionGroup>
<Accordion title="Can an agent rule override an organization-wide block?">
No. Rules only add restrictions. If an org-wide rule blocks a tool call, an agent rule cannot un-block it. To allow the call, you would need to disable or modify the org-wide rule.
</Accordion>
<Accordion title="Do agent rules apply when the agent runs inside a pipeline?">
Yes. Agent-scoped rules are evaluated whenever that agent makes a tool call, regardless of whether the agent is running in a direct conversation, through Slack, or inside a pipeline.
</Accordion>
<Accordion title="Can I create tag rules at the agent level?">
Yes. Both `block` and `tag` actions are supported at every scope level. Tagged calls show up in the enforcement activity views just like org-wide tagged calls.
</Accordion>
<Accordion title="How do App Rules differ from Human in the Loop approval settings?">
Approval settings are simple mode-based controls (always allow, ask each time, ask for writes/deletes, or custom per-tool). They apply based on the tool's risk category.
App Rules are conditional. They use CEL expressions to inspect the actual arguments of a tool call. For example, "only block when the email recipient is outside my domain" is something only App Rules can do. Both systems work together: approval settings set the baseline, App Rules add conditional overrides. See the [Human in the Loop guide](/core-concepts/human_in_the_loop) for the full picture.
</Accordion>
</AccordionGroup>
# Domain restrictions
Source: https://docs.gumloop.com/enterprise-features/app-policies/domain-restrictions
Require OAuth connections to a given app to use an email address from a domain your organization controls.
Domain Restrictions make sure every new OAuth connection to a given app uses
an email from a domain your organization owns. This prevents users from
connecting personal accounts to business-critical apps by mistake.
<Frame>
<img alt="Domain Restrictions tab showing a Google Sheets domain restriction allowing gumloop.com with an enabled toggle" />
</Frame>
## What it does
When someone in your organization connects a new credential to a protected
app, Gumloop inspects the email address of the account they're authorizing.
If that email's domain isn't on the allowlist you've configured, the OAuth
flow fails and their connection is not saved.
Domain Restrictions only affect **new** connections. Existing credentials that
were already connected before the restriction was added continue to work —
revoke them manually if you want to remove them.
<Info>
Not every connector supports Domain Restrictions. The **Domain Restriction** picker lists services where Gumloop can read the connecting user's email, such as Google Workspace, Slack, and Microsoft.
</Info>
## Creating a restriction
<Steps>
<Step title="Open the Domain Restrictions tab">
Go to [Settings → Organization → Policies → Domain Restrictions](https://www.gumloop.com/settings/organization/policies?tab=domain-restrictions).
</Step>
<Step title="Pick a connector">
Click **Domain Restriction**, then select a supported connector.
</Step>
<Step title="Enter the required domain">
Enter a domain like `yourcompany.com`. Any email whose domain matches
exactly will be allowed; everything else will be blocked.
</Step>
<Step title="Confirm">
Click **Add Restriction**. The restriction is enforced immediately for new
OAuth connections.
</Step>
</Steps>
<Tip>
You can add more than one restriction per app if you want to allow multiple
domains (for example, `yourcompany.com` and `yourcompany.co.uk`). Each
restriction adds one domain to the allowlist for that app.
</Tip>
## Enable, disable, delete
Each restriction has an **Enabled** toggle. Disabling a restriction pauses
enforcement without deleting the rule, so you can turn it back on later. You
can also delete a restriction from its detail page.
## What end users see
When someone tries to connect an account that doesn't match, the OAuth flow
ends with an error explaining that their organization requires a different
email domain for this app. They can retry the connection with an account on an
allowed domain.
## Related
<CardGroup>
<Card title="App claims" icon="building-lock" href="/enterprise-features/app-policies/app-claims">
Restrict connections by provider workspace rather than by email domain.
</Card>
<Card title="Connectors" icon="plug" href="/core-concepts/credentials">
Learn how OAuth connections are stored and used across Gumloop.
</Card>
</CardGroup>
# Connector policies
Source: https://docs.gumloop.com/enterprise-features/app-policies/overview
Govern how your organization uses connectors inside Gumloop: block risky tool calls, require corporate email domains, and claim provider workspaces.
Connector Policies govern which tool calls and connected accounts your organization can use in Gumloop. Organization admins set org-wide policies — block risky tool calls,
require corporate email domains when people connect their accounts, and claim a
specific provider workspace (a Slack workspace, Salesforce org, Notion
workspace, etc.) for your organization. Anyone building an agent can also add
[agent-level App Rules](/enterprise-features/app-policies/app-rules#rule-scopes)
to their own agents.
<Frame>
<img alt="Policies page on the Rules tab showing Rules by Connector with rules grouped under Gmail, Linear, and Salesforce, each with a Live toggle" />
</Frame>
## Where to find it
Go to **Settings → Organization → Policies** at
[Policies](https://www.gumloop.com/settings/organization/policies).
The page has three tabs — **Rules**, **Domain Restrictions**, and **Claims** — that map to the three policy types:
<CardGroup>
<Card title="App Rules" icon="shield-halved" href="/enterprise-features/app-policies/app-rules">
Block or tag specific tool calls before or after they run.
</Card>
<Card title="Domain restrictions" icon="at" href="/enterprise-features/app-policies/domain-restrictions">
Require new OAuth connections to use a corporate email domain.
</Card>
<Card title="App claims" icon="building-lock" href="/enterprise-features/app-policies/app-claims">
Claim a provider workspace so only your org members can connect to it.
</Card>
</CardGroup>
## Who can use it
<Warning>
Connector Policies is an **Enterprise** feature. The page is visible to users with
the **Admin** or **Security** [organization role](/core-concepts/organization_user_roles).
Everyone else in your organization will not see it in settings.
</Warning>
Organization-wide policies (App Rules, Domain Restrictions, and App Claims) are
managed from that page by admins. Agent-level App Rules are different: any user
who can configure an agent can create them from the agent's configuration panel
or agent chat, and they only affect that agent's tool calls.
## How it works end-to-end
At a high level, Connector Policies hook into three different moments:
| Moment | Policy type that fires | What Gumloop checks |
| - | - | - |
| A user connects a new OAuth account | Domain Restrictions | Does the user's email domain match the allowlist for this app? |
| A user connects a new OAuth account | App Claims | Is this provider workspace claimed by a different organization? |
| An agent or pipeline invokes a tool | App Rules (phase `before`) | Does any enabled rule for this app and tool say "block"? |
| A tool call finishes | App Rules (phase `after`) | Does any enabled rule want to block or tag based on the output? |
All three policy types live behind the same page, share the same target model
(see [Target scope](#target-scope) below), and follow the same
fail-closed rule: if Gumloop cannot evaluate a policy cleanly, the request is
treated as blocked.
### Evaluation pipeline for a tool call
When any tool call runs inside Gumloop (from an agent, a pipeline operator, a
user chatting with an agent, or a [Hosted MCP](/enterprise-features/hosted_mcps) server), the platform
calls an internal `check_rules` step both before the tool executes and again
after the result comes back. That check walks every enabled App Rule for the
organization in priority order and applies these steps per rule:
<Steps>
<Step title="Phase match">
Skip the rule unless its `check_type` matches the current phase
(`before` vs. `after`).
</Step>
<Step title="Target match">
Skip the rule unless its target matches the caller. The target can be the
whole organization, a specific user, or a specific agent (for App Rules,
agent-level targets are supported).
</Step>
<Step title="Scope match">
Skip the rule if its `scope` restricts it to specific tool names and the
current tool isn't in that list.
</Step>
<Step title="Condition match">
Evaluate the rule's CEL condition against the call context (see the
[next section](#how-natural-language-maps-to-code) for what's available).
If the expression returns `false`, skip the rule. If the expression errors,
treat it as a match (fail-closed).
</Step>
<Step title="Apply the action">
* **`tag`:** record the rule name against this tool call and keep
evaluating the remaining rules.
* **`block`:** stop evaluation immediately and return a blocked decision.
The tool call is denied with a message that depends on the rule's target
scope (see [Target scope](#target-scope)).
</Step>
</Steps>
If no rule matches, the call is allowed and any accumulated tags are attached
to it. Every evaluation (allowed, tagged, or blocked) is recorded and shows up
in the per-rule **Activity** tab.
### How natural language maps to code
You don't have to write CEL or JSON by hand. The AI rule builder on the
**Rules** tab takes a plain-English description of what you want and
produces a structured rule with:
* **`check_type`** — `"before"` (pre-flight) or `"after"` (post-flight). *"Stop
people from sending …"* becomes `"before"`; *"Flag calls that returned
sensitive fields"* becomes `"after"`.
* **`action`** — `"block"` or `"tag"`. *"Don't allow …"* becomes `"block"`;
*"Just monitor …"* becomes `"tag"`.
* **`tool_names`** — specific tools on the app the rule applies to, if the
prompt named any (e.g. "sending messages" on Slack becomes `["send_message"]`).
Omitted means "any tool on this app".
* **`conditions`** — a CEL expression evaluated with these variables:
* `args` — the arguments passed to the tool (e.g. `args.channel`,
`args.query`, `args.to`).
* `tool_name` — the tool the caller invoked.
* `server_id` — the app the tool belongs to.
* `output` — the tool's return value (available only on `after` rules).
For example, *"Do not allow users to send messages in the #general channel
(ID C05QG7RF30A)"* compiles to:
```json theme={"dark"}
{
"check_type": "before",
"action": "block",
"tool_names": ["send_message"],
"conditions": "args.channel == \"C05QG7RF30A\""
}
```
Every time you edit the prompt, the builder re-renders this JSON and re-runs
it against the most recent real tool calls on that app, so you can see exactly
which past calls the rule would have caught before you save it. See
[App Rules](/enterprise-features/app-policies/app-rules) for the full flow.
### How agents and pipelines see a policy decision
Policies are enforced inside Gumloop — an agent or pipeline can't bypass them
from its own runtime. Here's what each side sees:
* **Allowed:** the tool runs normally and returns its result. The caller has
no idea a check happened.
* **Tagged:** the tool still runs and returns its result normally. The tags
show up in audit views and in the **Activity** tab of each tagging rule, but
they don't change what the caller sees.
* **Blocked:** the tool doesn't run. The caller (agent or pipeline
operator) receives an error carrying the reason *"This action has been
restricted by your organization's security policy."* Agents handle this the
same way they handle any other tool error: they surface the failure in the
conversation and can decide whether to try a different tool, ask the user
for clarification, or abort the task. Pipeline operators fail their step
with the same message.
End users never see *which* rule blocked them, just that the action was
denied. Admins can see the full context — including the rule name, the
matched condition, and the arguments — in the rule's **Activity** tab.
## Target scope
Every policy is created against a **target** that decides who the policy
applies to. From most to least broad:
| Target | Applies to | Where to manage |
| - | - | - |
| Organization | Everyone in your organization (the default) | [Connector Policies settings page](https://www.gumloop.com/settings/organization/app-policies) |
| User | A single user | API only |
| Agent | A single AI agent (App Rules only) | Agent config panel → app detail → **Rules** tab, or via [agent chat](/enterprise-features/app-policies/app-rules#via-agent-chat-agent-created-rules) |
The target is set when the policy is created. Org-wide policies cover all users
in your organization; more-specific policies layer on top of them. See
[How overlapping rules interact](/enterprise-features/app-policies/app-rules#how-overlapping-rules-interact)
for how rules at different scopes stack.
## Enabled vs. disabled
Every policy has an **Enabled** toggle. Only enabled policies are enforced.
Disabling a policy pauses it without deleting it, so you can re-enable it later
without re-doing the configuration.
## Fail-closed by default
If Gumloop can't evaluate a policy for any reason — a CEL expression errors
out, a scope check fails, an unknown action shows up — the request is
**denied**, not allowed. This keeps a misconfigured policy from silently
letting traffic through. The evaluation errors are still attached to the
call so admins can see what went wrong.
## What end users see when a policy blocks them
* **App Rules:** the tool call fails with a message that depends on the rule's
target scope:
* *Organization* rules: *"This action has been restricted by your organization's security policy."*
* *Agent* rules: *"This action has been restricted by a rule configured for this agent."*
* *User* rules: *"This action has been restricted by a user-level security rule."*
* **Domain Restrictions:** if someone tries to connect an account whose email
domain isn't on the allowlist, the OAuth flow ends with an error explaining
which domain is required.
* **App Claims:** if someone outside your organization tries to connect to a
provider workspace you've claimed, their connection is rejected with a
message saying the workspace is claimed by another organization.
Only admins see which specific policy blocked a call. End users only see the
fact that it was blocked.
## Related
<CardGroup>
<Card title="Custom roles" icon="user-shield" href="/enterprise-features/user_groups">
Grant granular permissions to non-admin users.
</Card>
<Card title="Audit logs" icon="clipboard-list" href="/enterprise-features/audit_logging">
Track every policy create, update, enable/disable, and enforcement event.
</Card>
</CardGroup>
# Connector activity
Source: https://docs.gumloop.com/enterprise-features/app_activity
Monitor tool calls, MCP interactions, and integration usage across your organization with real-time activity logs.
Connector Activity gives you a centralized, real-time view of every tool call made across all MCP servers in your organization. Whether you need to debug a failed integration, audit who accessed what, or track usage patterns, this is your go-to dashboard.
<Frame>
<img alt="Connector Activity page showing the activity histogram and a table of recent tool calls across all MCP servers" />
</Frame>
## Where to find it
Go to **Settings → Organization → Activity** at
[gumloop.com/settings/organization/activity](https://gumloop.com/settings/organization/activity).
<Warning>
Connector Activity is available on the **Pro** and **Enterprise** plans. Pro
shows the last 24 hours of activity. Enterprise has no history limit. The
**Admin** and **Security** roles see the full organization-wide activity
log. The **Developer** role sees only its own tool calls. Other roles
(Manager, Analytics, Member) do not have access to Connector Activity. See [User
Roles](/core-concepts/organization_user_roles).
</Warning>
## Activity histogram
At the top of the page, a histogram shows tool call volume over the last 24 hours. Each bar represents a time interval, color-coded by status:
* **Green**: Successful calls
* **Red**: Errors or blocked calls
<Frame>
<img alt="Activity histogram showing 24-hour tool call volume with color-coded status bars, and clicking into a server row" />
</Frame>
The histogram gives you a quick visual sense of activity patterns. Spikes in red can indicate integration issues worth investigating.
<Info>
The histogram is visible when viewing the **Last 24 hours** date range.
Selecting a custom date range longer than 24 hours hides the histogram and
shows only the table.
</Info>
## Activity table
Below the histogram, a table lists every tool call with these columns:
| Column | What it shows |
| - | - |
| **Server** | The MCP server that handled the call (clickable, takes you to server details) |
| **Time** | When the call happened |
| **Tool** | Which specific tool was invoked (e.g., `Get Issue`, `Read Emails`) |
| **User** | Who triggered the call |
| **Source** | Where the call originated (e.g., Gumloop agent, external client) |
| **Latency** | Round-trip time for the call |
| **Status** | `Success`, `Error`, `Permission Denied`, or `In Progress` |
Clicking any server name in the table takes you directly to that server's detail page, where you can see server-specific activity, tools, and settings.
## Filtering activity
Click the **Filters** button in the top right to narrow down what you see. You can filter by:
* **Status**: All Statuses, Success, Error, Permission Denied, or In Progress
* **Server**: Filter to a specific MCP server
* **Tool**: Filter to a specific tool name
* **User**: Filter to a specific user
* **Source**: Filter by where calls originated
* **Date Range**: All Time, Last 24 Hours, Last 7 Days, Last 30 Days, or a custom range
<Frame>
<img alt="Activity filters panel showing dropdowns for Status, Tool, User, Source, and Date Range" />
</Frame>
<Tip>
Combine filters to quickly find what you need. For example, filter by a
specific server and "Error" status to debug integration issues.
</Tip>
## Exporting activity data
Click the **download icon** (next to the Refresh and Filters buttons) to export the current filtered view as a CSV file. This is useful for compliance reporting, sharing with your team, or doing deeper analysis in a spreadsheet.
## Server detail view
When you click into a specific server from the activity table, you see the **server detail page**. This includes a summary of the server's last 7 days of activity:
* **Total Calls**: Total tool calls for this server
* **Unique Users**: Number of distinct users who made calls
* **Error Rate**: Percentage of calls that returned errors
* **Avg Latency**: Average response time
<Frame>
<img alt="Server detail page for Linear showing overview stats (5.4K total calls, 21 unique users, 0.1% error rate, 2.17s avg latency) and a per-server activity log" />
</Frame>
The server detail page also has its own activity histogram and table, scoped to just that server. The histogram here uses latency-based color coding:
* **Green (P25)**: Fast calls (25th percentile and below)
* **Orange (P85-95)**: Moderately slow calls
* **Red (P95+)**: The slowest calls
### Tools & access
The **Tools** tab on any server detail page shows every tool discovered on that server, along with a custom-role matrix. This lets you control exactly which [custom roles](/enterprise-features/user_groups) can use which tools.
<Frame>
<img alt="Tools & Access tab showing a matrix of tools vs custom roles, with checkboxes to enable or disable access per role" />
</Frame>
Each row shows:
* **Tool name and description**
* **Usage count**: How many times the tool has been called
* **Per-role toggles**: Enable or disable the tool for each custom role
You can also **Disable Server** entirely for a specific group using the toggle at the top of the matrix. This blocks all tools on that server for members of that group.
## Scoped analytics
Users with the **Developer** role can open Connector Activity, but the view is automatically scoped to show **only their own activity**. This means they have access to their personal tool call history without being able to see other users' data. Organization-wide visibility requires the **Admin** or **Security** role.
## FAQ
<AccordionGroup>
<Accordion title="How far back does activity data go?">
Activity data is available for the lifetime of your organization. Use the
**Date Range** filter to look at historical data beyond the default 24-hour
view.
</Accordion>
<Accordion title="Can I see activity for a specific agent?">
Yes. Use the **Source** filter to narrow results to a specific origin, and
the **User** filter to find calls made by a particular user or agent.
</Accordion>
<Accordion title="What does 'Permission Denied' status mean?">
A tool call with **Permission Denied** status was blocked by your
organization's [Connector Policies](/enterprise-features/app-policies/overview)
or tool access settings. Check the **Tools & Access** tab on the relevant
server, or review your App Rules.
</Accordion>
<Accordion title="How is this different from Audit Logging?">
[Audit Logging](/enterprise-features/audit_logging) tracks administrative
actions across the platform (sign-ins, credential changes, team management,
etc.). Connector Activity specifically tracks **MCP tool calls and integration
usage**, giving you deeper visibility into what your AI agents and
automations are actually doing.
</Accordion>
</AccordionGroup>
# Audit logging
Source: https://docs.gumloop.com/enterprise-features/audit_logging
Audit Logging provides comprehensive tracking and monitoring of user actions across your Gumloop organization. This feature enables administrators to maintain security, compliance, and operational oversight by recording detailed logs of all significant activities within the platform.
## Overview
Audit logging automatically captures and stores detailed records of user activities, system events, and administrative actions within your organization.
<CardGroup>
<Card title="Security monitoring" icon="shield-halved">
Track unauthorized access attempts and suspicious activities
</Card>
<Card title="Compliance requirements" icon="file-contract">
Meet regulatory standards for data access and modification tracking
</Card>
<Card title="Operational oversight" icon="chart-line">
Monitor workflow executions and system usage patterns
</Card>
<Card title="Troubleshooting" icon="wrench">
Investigate issues by reviewing historical activity patterns
</Card>
</CardGroup>
<Info>
Access audit logs at: [gumloop.com/settings/organization/audit-logging](https://gumloop.com/settings/organization/audit-logging)
</Info>
<Frame>
<img alt="Organization Audit Logs page with Date Range, Event Type, Users, Team, IP Addresses, and Entity ID filters above a table of timestamped events" />
</Frame>
### Filtering by event type
You can filter audit logs by event type to quickly find specific activities. Use the **Event Type** dropdown to select from available event types, or search for a specific type.
<Frame>
<img alt="Audit log Event Type filter dropdown showing event types like user_sign_in, credential_retrieval, credential_insertion, and more" />
</Frame>
## Tracked events
The audit logging system captures a comprehensive range of activities across the platform including:
<AccordionGroup>
<Accordion title="Authentication events" icon="key">
* **User Sign-ins**: Records when users authenticate to the platform
* **Session Management**: Tracks session creation and termination
* **SSO Method Changes** (`sso_sign_in_providers_changed`): The organization's active SSO method changed between SAML and [OIDC](/enterprise-features/sso_saml_oidc_scim#oidc-configuration), including the previous and new sign-in providers
</Accordion>
<Accordion title="Credential management" icon="lock">
* **Credential Creation** (`credential_insertion`): New API keys, OAuth connections, and service integrations
* **Credential Modification** (`credential_modification`): Updates to existing authentication credentials
* **Credential Deletion** (`credential_deletion`): Removal of credentials from the system
* **Credential Retrieval** (`credential_retrieval`): Access to stored credentials for agent and workflow execution
<Info>Credential events record which credential was touched and by whom. Secret values, OAuth codes, and tokens are never written to audit logs.</Info>
</Accordion>
<Accordion title="Team operations" icon="folder">
* **Team Creation**: New team setup and configuration
* **Member Management**: Adding or removing users from teams
* **Team Deletion**: Permanent removal of teams
* **Team Renaming**: Changes to team names and metadata
</Accordion>
<Accordion title="Organization management" icon="building">
* **Member Addition/Removal**: Changes to organization membership
* **Domain Configuration**: Updates to organization domain settings
* **Metadata Updates**: Changes to organization settings and configuration
</Accordion>
<Accordion title="Slack workspace association" icon="slack">
Records which Slack workspaces are linked to your organization, and who linked them.
* **Workspace Registration** (`organization_slack_workspace_registration`): A Slack workspace was associated with the organization
* **Workspace Removal** (`organization_slack_workspace_removal`): The association was removed
Each entry includes `organization_id`, `slack_workspace_id`, `slack_workspace_name`, and the acting user.
<Info>Only the relationship and the acting user are recorded. OAuth codes, tokens, and state parameters are never logged.</Info>
</Accordion>
<Accordion title="Custom role management" icon="users">
* **Role Creation**: New [custom roles](/enterprise-features/user_groups) and access controls
* **Member Changes**: Adding or removing users from a custom role
* **Role Deletion**: Removal of custom roles
</Accordion>
<Accordion title="Workflow operations" icon="diagram-project">
* **Workflow Execution**: Workflow runs and automation triggers
* **Workflow Termination**: Manual or automatic stopping of workflows
* **Workflow Completion**: Successful workflow completions
* **Run Retrieval**: Access to workflow execution results and logs
</Accordion>
<Accordion title="File operations" icon="file">
* **File Uploads** (`file_upload`): Documents and data uploaded to the platform
* **File Downloads** (`file_download`): Access to stored files and documents
* **File Deletion** (`file_deletion`): Removal of files from the system
* **File Modification** (`file_modification`): Changes to a stored file, including [artifact domain hosting](/core-concepts/agent_artifacts#hosting-artifacts-on-a-custom-domain) configuration
</Accordion>
<Accordion title="Agent lifecycle events" icon="compass">
Every log entry includes the `agent_id`, `agent_name`, the operation performed, and the `workspace_id` when the agent belongs to a team workspace.
* **Agent Creation** (`agent_creation`): A new agent was created. Agents created by cloning carry `operation: clone` along with the `source_agent_id`.
* **Agent Modification** (`agent_modification`): Changes to an existing agent, including `version_deploy` when a saved version is deployed
* **Agent Deletion** (`agent_deletion`): An agent was deleted
* **Agent Workspace Move** (`agent_workspace_move`): An agent moved between workspaces
</Accordion>
<Accordion title="Agent trigger events" icon="bolt">
Trigger lifecycle changes are recorded as `agent_modification` events with one of these operations:
| Operation | Meaning |
| - | - |
| `trigger_create` | A new trigger added to an agent |
| `trigger_update` | Changes to an existing trigger's configuration |
| `trigger_activation` | A previously disabled trigger re-enabled |
| `trigger_deactivation` | An active trigger disabled |
| `trigger_delete` | A trigger removed from an agent |
Each entry records `trigger_id`, `trigger_type`, `trigger_name`, whether the trigger is active, and a **`source`** field distinguishing who made the change:
* `ui` — a person changed the trigger in Gumloop
* `ai_agent` — the agent changed its own trigger using its schedule or integration-trigger tools
</Accordion>
<Accordion title="Agent channel events" icon="tower-broadcast">
Enabling, updating, or disabling an agent's [external channels](/core-concepts/agents) is recorded as an `agent_modification` event.
| Operation | Meaning |
| - | - |
| `email_channel_enabled` / `email_channel_updated` / `email_channel_disabled` | Changes to the agent's [email inbox](/core-concepts/agents_email) |
| `hosting_channel_enabled` / `hosting_channel_updated` / `hosting_channel_disabled` | Changes to the agent's [hosted page](/core-concepts/hosted_pages), including alias changes |
| `slack_channel_added` / `slack_channel_created` / `slack_channel_removed` | Slack channels connected to or removed from the agent |
| `slack_bot_credentials_change` | The Slack bot credentials backing the agent changed |
| `slack_app_uninstalled` | The Slack app was uninstalled, disconnecting the agent |
</Accordion>
<Accordion title="Agent skill and knowledge events" icon="book">
* **Skill Attach** (`skill_attach`) / **Skill Detach** (`skill_detach`): A skill linked to or removed from an agent
* **Knowledge Source Attach / Update / Detach** (`knowledge_source_attach`, `knowledge_source_update`, `knowledge_source_detach`): Changes to the [Brain](/core-concepts/brain) sources an agent can search
Entries include the `agent_id`, the `skill_id` or knowledge source identifier, and the workspace context.
</Accordion>
<Accordion title="Outbound webhook management" icon="webhook">
* **Webhook Creation** (`webhook_endpoint_creation`): An outbound webhook was created.
* **Webhook Update** (`webhook_endpoint_update`): Its URL, description, subscriptions, status, or credentials were changed.
* **Webhook Deletion** (`webhook_endpoint_deletion`): An outbound webhook was deleted.
Entries identify the endpoint and organization. Depending on the operation, details include the URL, subscribed event types, status, or credential identifier. Signing secrets and authorization values are not included. Automatic Error transitions and individual deliveries are not audited here.
</Accordion>
<Accordion title="Artifact hosting" icon="globe">
Serving an [artifact on its own domain](/core-concepts/agent_artifacts#hosting-artifacts-on-a-custom-domain) is recorded as a `file_modification` event.
| Operation | Meaning |
| - | - |
| `custom_domain_enabled` | Hosting was turned on for an artifact |
| `custom_domain_updated` | The hosting alias was renamed |
| `custom_domain_disabled` | Hosting was turned off |
Entries include the artifact identifier, the filename, the hosting alias (and the previous alias on a rename), and the workspace context.
</Accordion>
</AccordionGroup>
## Audit log data structure
Each audit log entry contains comprehensive metadata and contextual information to provide complete visibility into platform activities.
### Example: Workbook creation log
<Accordion title="View full log example">
```json theme={"dark"}
{
"flow_jsons": [
[
{
"batch": false,
"category": "Using AI",
"dynamic_inputs": [],
"dynamic_outputs": [],
"id": "eEovMC652wM7Mvzo31G4xM",
"input_errors": {},
"inputs": {},
"is_collapsed": false,
"operator": "Ask AI",
"parameter_errors": {
"Azure Cognitive Services Account": "",
"Azure Deployment": "",
"Azure Resource Group": "",
"Azure Subscription": "",
"Cache Response": "",
"Connect MCP Server?": "",
"MCP Servers": "",
"Maximum Tokens": "",
"Reasoning Effort": "",
"Temperature": "",
"Thinking Tokens": "",
"Use Function?": "",
"azure_cognitive_services_map": "",
"azure_deployment_map": "",
"azure_resource_groups_map": "",
"azure_subscription_map": "",
"model_preference": "",
"prompt": "",
"servers_setup_map": ""
},
"parameter_input_errors": {},
"parameter_inputs": {},
"parameters": {
"Azure Cognitive Services Account": null,
"Azure Deployment": null,
"Azure Resource Group": null,
"Azure Subscription": null,
"Cache Response": null,
"Connect MCP Server?": null,
"MCP Servers": null,
"Maximum Tokens": null,
"Reasoning Effort": null,
"Temperature": null,
"Thinking Tokens": null,
"Use Function?": null,
"azure_cognitive_services_map": null,
"azure_deployment_map": null,
"azure_resource_groups_map": null,
"azure_subscription_map": null,
"model_preference": null,
"prompt": null,
"servers_setup_map": null
},
"position": {
"x": 945.508855591821,
"y": 137.38119073725161
},
"version": "v0_11"
}
]
],
"pl_config_info": [
{
"pl_config_hash": "{ID}"
}
],
"saved_items_info": [
{
"saved_item_id": "{ID}",
"saved_item_ref": "{ID}"
}
],
"user_email": "admin@gumloop.com",
"workbook_id": "{ID}",
"workbook_name": "New Workbook",
"workspace_id": null
}
```
</Accordion>
### Log entry components
<CardGroup>
<Card title="Core event data" icon="database">
* Event ID (unique identifier)
* Timestamp (ISO format)
* Event Type (action categorization)
* User ID (who performed the action)
</Card>
<Card title="Request context" icon="network-wired">
* Source IP Address
* Session Information
* Authentication context
</Card>
<Card title="Event details" icon="circle-info">
* Action-specific JSON data
* Resource identifiers
* Configuration parameters
</Card>
<Card title="Resource information" icon="sitemap">
* Team IDs
* Workflow IDs
* Affected entities
</Card>
</CardGroup>
## Programmatic access
Audit logs are available both over the REST API and over the [Gumloop MCP server](/mcp-server/overview) — use the REST API for integrations with external monitoring, SIEM systems, or custom reporting tools, and MCP when an AI client should query the logs for you.
### REST API
#### Quick reference
<Steps>
<Step title="Endpoint">
```text theme={"dark"}
GET /api/v1/get_audit_logs
```
</Step>
<Step title="Required parameters">
* `organization_id` (string): Organization ID
* `user_id` (string): Your user ID (admin required)
* `start_time` (datetime): Start timestamp (ISO format)
* `end_time` (datetime): End timestamp (ISO format)
</Step>
<Step title="Optional parameters">
* `event_type` / `event_types` (string): Filter logs by event type (e.g., `"user_sign_in"`, `"credential_retrieval"`, `"flow_execution"`). The plural form accepts a comma-separated list
* `user_ids` (string): Comma-separated list of user IDs whose events to return
* `ip_address` / `ip_addresses` (string): Filter by source IP
* `workspace_id` / `workspace_ids` (string): Filter to events in specific team workspaces
* `entity_id` / `entity_ids` (string): Filter to events touching specific entities (agents, workbooks, files)
* `page` (integer): Page number (default: 1)
* `page_size` (integer): Records per page (default: 50)
</Step>
<Step title="Authentication">
Include your API key in the Authorization header
</Step>
</Steps>
#### Example request
```bash theme={"dark"}
curl --request GET \
--url 'https://api.gumloop.com/api/v1/get_audit_logs?page=1&page_size=50&start_time=2025-01-01T00%3A00%3A00&end_time=2025-01-02T00%3A00%3A00&user_id=user_abc123&organization_id=org_xyz789' \
--header 'Authorization: Bearer your_api_key_here'
```
The response includes the matching `audit_logs`, pagination fields (`total_count`, `page`, `page_size`, `total_pages`), and an `event_types` array listing every event type you can filter on.
<Tip>
For complete API documentation and advanced usage, see: [Gumloop API Reference](https://docs.gumloop.com/api-reference/organization/get-audit-logs)
</Tip>
### MCP
The [Gumloop MCP server](/mcp-server/overview) exposes the same data through the `get_audit_logs` tool, so Claude, Cursor, or any other connected client can pull audit events directly. Connect to `https://mcp.gumloop.com/gumloop/mcp` and ask in natural language:
```text theme={"dark"}
Pull our Gumloop audit logs for the last 7 days and summarize the credential_retrieval events
```
The tool takes `organization_id`, your `user_id`, `start_time`, `end_time`, and an optional `max_limit` (it pages through results for you). The event, user, IP, workspace, and entity filters above are REST-only — over MCP, narrow the time window and let the client filter the results. Audit log access is restricted to organization Admins on both surfaces.
Audit logs can also be streamed continuously to S3, Datadog, or a custom endpoint with an [audit log data drain](/enterprise-features/organization_data_export#data-drains).
## Data privacy and security
<AccordionGroup>
<Accordion title="Data protection" icon="shield-halved">
* **Encryption**: All audit logs are encrypted at rest and in transit using industry-standard protocols
* **Access Control**: Logs are accessible only to organization administrators with proper authentication
* **Data Isolation**: Organization audit logs are completely isolated from other organizations through strict multi-tenancy controls
</Accordion>
<Accordion title="Retention and compliance" icon="calendar-check">
* **Data Retention**: Audit logs are retained according to Enterprise agreement terms
* **Compliance Standards**: Meets SOC2 Type II and GDPR requirements for audit trail management
* **Data Export**: Full export capabilities for compliance audits and backup purposes
</Accordion>
</AccordionGroup>
<Warning>
Only users with the **Admin** [organization role](/core-concepts/organization_user_roles#admin) can access audit logs. Security, Manager, and other feature roles do not grant audit log access. Ensure appropriate role assignments to maintain security controls.
</Warning>
## Related resources
<CardGroup>
<Card title="Custom roles" icon="user-shield" href="/enterprise-features/user_groups">
Configure granular permissions and access controls
</Card>
<Card title="Usage data export" icon="file-export" href="/enterprise-features/organization_data_export">
Export comprehensive platform usage data
</Card>
<Card title="Organizations and teams" icon="building" href="/core-concepts/teams">
Understand organizational structure
</Card>
<Card title="Security & compliance" icon="shield-check" href="https://trust.gumloop.com/">
View our security certifications
</Card>
<Card title="MCP server" icon="plug" href="/mcp-server/overview">
Query audit logs from Claude, Cursor, and other MCP clients
</Card>
</CardGroup>
# Hosted MCPs
Source: https://docs.gumloop.com/enterprise-features/hosted_mcps
Deploy, manage, and monitor custom MCP servers directly from GitHub repositories with full lifecycle management.
Hosted MCPs let your organization build and deploy custom MCP servers on Gumloop's infrastructure. You write the code in a GitHub repository, and Gumloop handles building, deploying, monitoring, and routing requests to your server. Every tool call is logged, and access is controlled through [custom roles](/enterprise-features/user_groups).
<Frame>
<img alt="Hosted MCP server detail page showing overview stats, MCP Server URL, live deployment info, and recent activity" />
</Frame>
## Where to find it
Go to **Settings → Organization → Hosted MCPs** at
[gumloop.com/settings/organization/hosted-mcps](https://gumloop.com/settings/organization/hosted-mcps).
<Info>
Hosted MCPs is available on the **Pro** and **Enterprise** plans. Pro
organizations can host **1** MCP server. Enterprise organizations get a
custom limit. Contact your organization admin if you don't see it under
**Settings → Organization**.
</Info>
## Initial setup
Before creating your first hosted MCP, you need to connect GitHub. Go to
**Hosted MCPs → Settings** (or visit
[gumloop.com/settings/organization/hosted-mcps/setup](https://gumloop.com/settings/organization/hosted-mcps/setup))
to configure two connections:
<Steps>
<Step title="GitHub OAuth (Personal)">
Connect your personal GitHub account. This lets Gumloop create repositories
on your behalf when you set up new servers. Each developer on your team
connects their own GitHub account.
</Step>
<Step title="GitHub app (organization)">
Install the Gumloop GitHub App on your GitHub organization. This enables
**automatic deployments**: every push to your main branch triggers a new
build and deploy. This is a one-time setup for the whole organization.
</Step>
</Steps>
<Tip>
You can revoke either connection at any time from the setup page. Revoking the
GitHub App stops automatic deployments for all hosted MCPs in your org.
</Tip>
## Server list
The main Hosted MCPs page shows a table of all your organization's servers. Each row displays:
* **Server name** with a status indicator (green dot = active, yellow dot = disabled)
* **Linked GitHub repository** with a badge linking to the repo
* **Tool count** showing how many tools the server exposes
* **Last Updated** timestamp
### Filtering
Use the toolbar above the table to:
* **Search** by server name or repository
* **Filter: My Servers Only** to show only servers you created
* **Filter: Show Disabled Servers** to include disabled servers in the list
* Click **Settings** to go to the GitHub integration setup page
* Click **Create** to start the new server wizard
## Creating a new hosted MCP
Click the **Create** button to launch a 3-step wizard that sets up a new MCP server with a GitHub repository.
### Step 1: Basic info
<Frame>
<img alt="Create wizard step 1 showing fields for Server Name, Description, GitHub Repository owner, Repository Name, and Visibility" />
</Frame>
Fill in:
* **Server Name**: A display name for your MCP server (up to 100 characters)
* **Description** (optional): A brief description of what your server does
* **GitHub Repository**: Choose which GitHub account or organization should own the repo
* **Repository Name**: The name for the new GitHub repo (letters, numbers, hyphens, underscores, dots)
* **Visibility**: Public, Private, or Internal
### Step 2: Authentication & environment
<Frame>
<img alt="Create wizard step 2 showing authentication type selection (API Key/Credentials), credential field configuration, and environment variables" />
</Frame>
Configure how users will authenticate with your server:
* **No Authentication**: Anyone with access can use the server without credentials
* **API Key / Credentials**: Users provide API keys or tokens. You define the credential fields (variable name, display label, placeholder text) that users fill out in the Gumloop UI
* **OAuth 2.0**: Users authenticate through an OAuth flow with a third-party provider
You can also add **Environment Variables** that get injected into your server at runtime. These are developer secrets (database URLs, API keys for external services, etc.) that are different from user-provided credentials.
<Info>
**Credentials vs. Environment Variables**: Credentials are provided by each
end user and are unique per person. Environment variables are set by the
server developer and shared across all users of the server.
</Info>
### Step 3: Review
<Frame>
<img alt="Create wizard step 3 showing a review summary with Basic Info, GitHub Repository details, and Authentication configuration" />
</Frame>
Review your configuration and click **Create**. Gumloop will:
1. Create a new GitHub repository with boilerplate MCP server code
2. Register the server in your organization
3. Redirect you to the server detail page
From there, you can push code to your repo and deploy.
## Server detail page
Every hosted MCP has a detail page with six tabs:
### Overview
The overview tab gives you a snapshot of server health and activity for the last 7 days:
* **Total Calls**: Total number of tool calls
* **Unique Users**: How many distinct users made calls
* **Error Rate**: Percentage of calls that failed
* **Avg Latency**: Average response time
* **MCP Server URL**: A unique, stable URL that always points to your latest production deployment. Copy this to configure MCP clients.
* **Live Deployment**: Shows the current deployed commit, author, and date
* **Recent Activity**: A quick-look table of the most recent tool calls
The header also provides quick actions:
* **Copy URL** (link icon): Copy the server URL to your clipboard
* **Repository** button: Jump to the GitHub repo
* **Deploy** button: Trigger a new deployment
### Tools
The Tools tab shows every tool your server exposes and lets you control access per [custom role](/enterprise-features/user_groups).
The matrix view shows:
* **Tool name and description** for each tool
* **Usage count**: How many times each tool has been called
* **Custom role columns**: Toggle access on or off for each role
* **Disable Server** row: Block all tools for a specific role at once
Changes are saved when you click **Save** in the toolbar.
### Activity
The Activity tab is a server-scoped version of the global [Connector Activity](/enterprise-features/app_activity) page. It shows the same histogram and table, but filtered to just this server.
The histogram here uses latency-based color coding:
* **Green (P25)**: Fast calls
* **Orange (P85-95)**: Moderately slow calls
* **Red (P95+)**: Slowest calls
You get the same filtering, export, and refresh capabilities as the global Activity page.
### Deployments
<Frame>
<img alt="Deployments tab showing a list of deployments with commit hash, message, status (Live/Ready), author, and date" />
</Frame>
The Deployments tab shows your deployment history. Each deployment entry includes:
* **Commit hash and message**
* **Status**: Building, Deploying, Live, Ready, Failed, or Rolled Back
* **Author**: Who pushed the commit (from GitHub)
* **Date**: When the deployment happened
Deployments are triggered automatically on pushes to the `main` branch (when the GitHub App is installed). You can also manually deploy from the **Deploy** button in the header, choosing a specific branch or commit.
<Tip>
The **MCP Server URL** at the bottom of the Deployments tab always routes to
the latest production deployment. Previous deployments remain in the history
for rollback purposes.
</Tip>
### Monitoring
<Frame>
<img alt="Monitoring tab showing Server Health with Active Pods count, Pod Restarts count, and live Runtime Logs" />
</Frame>
The Monitoring tab shows live infrastructure status:
* **Active Pods**: How many server instances are running
* **Pod Restarts**: Number of times pods have restarted since the last deployment
* **Runtime Logs**: A live, streaming log view of your server's output (health checks, request logs, errors, etc.)
Use this tab to diagnose startup issues, confirm your server is healthy, or watch logs in real time.
### Settings
<Frame>
<img alt="Settings tab showing Server Image upload, Server Name, Description, MCP Server URL, Authentication Method, Environment Variables, and Disable/Delete actions" />
</Frame>
The Settings tab lets you manage:
* **Server Image**: Upload a logo or icon (PNG or JPEG, under 5MB) shown in lists and cards
* **Server Name**: Update the display name
* **Description**: Update what the server does
* **MCP Server URL**: View and copy the server's unique URL
* **Authentication Method**: Shows the auth type configured during creation (cannot be changed after creation)
* **Environment Variables**: Add, edit, or remove developer secrets injected at runtime
* **Disable Server**: Temporarily disable the server. It can be re-enabled later.
* **Delete Server**: Permanently delete the server and all associated configuration
<Warning>
Deleting a server is permanent and cannot be undone. All deployment history,
activity logs, and tool access settings will be removed.
</Warning>
## FAQ
<AccordionGroup>
<Accordion title="What language do I write my MCP server in?">
The boilerplate repository uses Python, but you can use any language that
implements the MCP protocol. Your server just needs to expose the standard
MCP endpoints over HTTP.
</Accordion>
<Accordion title="How do automatic deployments work?">
When the GitHub App is installed, every push to the `main` branch triggers
a build and deploy. Gumloop builds a container from your code, deploys it,
and routes the MCP Server URL to the new version once it's healthy.
</Accordion>
<Accordion title="Can I roll back to a previous deployment?">
Yes. Go to the **Deployments** tab, find the deployment you want to restore,
and use the actions menu to redeploy that version.
</Accordion>
<Accordion title="What's the difference between Hosted and Proxied MCPs?">
**Hosted MCPs** are servers you build and deploy on Gumloop's infrastructure
from a GitHub repository. You own the code and Gumloop handles the hosting.
**[Proxied MCPs](/enterprise-features/proxied_mcps)** are external MCP
servers (hosted elsewhere) that you connect through Gumloop's managed proxy
for observability and access control. You don't deploy any code, just
provide a URL.
</Accordion>
<Accordion title="How do I control who can use specific tools?">
Go to the **Tools** tab on your server's detail page. The custom-role
matrix lets you toggle access for each tool per role. You can also disable
the entire server for a group using the **Disable Server** toggle.
</Accordion>
</AccordionGroup>
# OIDC with Okta
Source: https://docs.gumloop.com/enterprise-features/idp-guides/oidc-with-okta
Configure OIDC single sign-on to Gumloop with Okta
This guide walks an Okta administrator through connecting Okta to Gumloop for OIDC (OpenID Connect) single sign-on: you create an OIDC *Application* in Okta, point it back at Gumloop, then copy its credentials into your Gumloop SSO settings.
<Note>
This guide covers signing in to Gumloop with Okta. To use Okta as an OAuth provider for connectors such as Snowflake or NetSuite, see [Okta Integration](/core-concepts/okta-integration) instead.
</Note>
## Before you start
A Gumloop organization admin opens [gumloop.com/settings/organization/sso](https://www.gumloop.com/settings/organization/sso) and chooses **Set up OpenID Connect** (see [Setting Up OIDC](/enterprise-features/sso_saml_oidc_scim#setting-up-oidc)). This guide is the Okta half of that wizard.
Okta needs one value, and it is the same for every organization:
* **Sign-in redirect URI:** `https://api.gumloop.com/enterprise-login/okta/callback`
The wizard then asks for three values from the Okta app you create below:
* **Okta domain**
* **Client ID**
* **Client Secret**
## Create an OIDC application in Okta
In the Okta Admin Console, select *Applications* > *Applications* in the left nav panel, then press *Create App Integration*.
In the modal, choose *OIDC - OpenID Connect* as the sign-in method and *Web Application* as the application type, then press *Next*.
Okta asks for a display name. Write "Gumloop".
Under *Grant type*, make sure *Authorization Code* is selected. Gumloop does not need *Refresh Token*, *Client Credentials*, or any other grant.
## Enter Gumloop details in Okta
On the same page, find *Sign-in redirect URIs*. Replace the default entry with `https://api.gumloop.com/enterprise-login/okta/callback`.
Leave *Sign-out redirect URIs* empty.
Under *Assignments*, choose *Limit access to selected groups* and pick the group that should reach Gumloop. Everyone who signs in to Gumloop must be in this group; a user left out sees "not assigned" and has no other way in.
<Tip>
If you are migrating from SAML, pick the same group your SAML application uses so nobody loses access at the switch.
</Tip>
Press *Save*. Okta opens the new application.
Open the *Sign On* tab. Under *OpenID Connect ID Token*, press *Edit*, set *Issuer* to *Okta URL* (your Okta domain, not a custom authorization server), and save.
## Enter Okta details in Gumloop
Open the application's *General* tab. Under *Client Credentials*, copy the *Client ID* and the *Client secret*.
Back in the Gumloop setup wizard, enter:
* **Okta domain** — your Okta hostname, such as `acme.okta.com`. Leave out `https://` and any `/oauth2/...` path.
* **Client ID** — from the *General* tab
* **Client Secret** — from the *General* tab
Gumloop checks the domain and credentials with Okta before saving. The secret is stored encrypted and is never shown again; leave the field blank on a later edit to keep the stored secret.
Once the app is saved, the Gumloop admin turns on the SSO domains, runs the test sign-in, and activates OIDC. Remember that an Okta administrator still has to assign users to the application before they can sign in.
# SAML with Entra
Source: https://docs.gumloop.com/enterprise-features/idp-guides/saml-with-entra
Configure SAML single sign-on to Gumloop with Microsoft Entra ID (formerly Azure Active Directory)
Entra — formerly Azure Active Directory — ranks among the more common IdPs. It can appear complicated, but hopefully it feels a little bit easier with this guide.
## Before you start: get your SP details from Gumloop
A Gumloop organization admin generates an SSO setup link at [gumloop.com/settings/organization/sso](https://www.gumloop.com/settings/organization/sso) (see [SSO: SAML, OIDC & SCIM](/enterprise-features/sso_saml_oidc_scim)). The setup page shows the two Service Provider values you'll copy into Entra:
* **Assertion Consumer Service (ACS) URL** — ends in `/acs`
* **SP Entity ID** — the same URL without the `/acs` suffix
The same page has the fields for the values Entra produces: **Redirect URL**, **IDP Entity ID**, and the **Certificate** upload.
<Steps>
### Create an application in Entra
Entra needs to associate a SAML connection with an *Application*, so the first step will require you to create an application. From any page in Entra, you'll find *Applications* > *Enterprise applications* in the left navigation bar. Click here to navigate to the next page.
<Frame>
<img />
</Frame>
You'll reach a page that says **Enterprise applications** in bold typeface. Press the *New application* button right under this header.
<Frame>
<img />
</Frame>
On the next page, there's a header: **Browse Microsoft Entra Gallery.** You'll also see a few prominent cards with major cloud providers. Ignore all this; the Gumloop connection won't use the gallery. Simply click *Create your own application*, which triggers a slideover from the right.
<Frame>
<img />
</Frame>
Entra requires a display name for the application. Write "Gumloop" here.
<Info>As you type a display name for the application, Entra will try to find matching apps from the Entra Gallery and suggest them as alternatives. Just ignore this.</Info>
<Frame>
<img />
</Frame>
Under the display name, Entra offers three radio button options. Select the last one, which reads *Integrate any other application you don't find in the gallery (Non-gallery)*.
<Frame>
<img />
</Frame>
Then hit *Create* in the lower left of the slideover, and you're free to configure the Application.
<Frame>
<img />
</Frame>
Entra may require a few seconds to create the Application. Once it has finished, you will land on a page detailing the application.
<Frame>
<img />
</Frame>
For now, skip assigning users to the Application, but an Entra admin will need to assign them before long.
<Warning>Users cannot sign in until assigned to the Application by an Entra admin.</Warning>
### Enter Gumloop details in Entra
Now you can configure Entra and Gumloop to communicate with each other. Start by entering details from your Gumloop SSO setup page into the Entra Application. Select the *Set up single sign on* card.
<Frame>
<img />
</Frame>
Entra will then present a few options. Select the *SAML* card marked with a puzzle piece icon.
<Frame>
<img />
</Frame>
Entra will route you to its *SAML-based Sign-on* configuration page, where you'll direct your attention first to the *Basic SAML Configuration* card. It has two required values. Gumloop supplies both.
Click the *Edit* button in the top right corner of the *Basic SAML Configuration* card; you'll see a slideover triggered on the right.
<Frame>
<img />
</Frame>
In the slideover, Entra requires two values: an *Identifier (Entity ID)* and a *Reply URL (Assertion Consumer Service URL)*.
1. Start with the *Identifier (Entity ID)* field. Gumloop calls this the *SP Entity ID*, shown on your Gumloop SSO setup page. Paste the URL into Entra.
2. Next is the *Reply URL (Assertion Consumer Service URL)* field. Gumloop calls this the *Assertion Consumer Service (ACS) URL*. It should look just like the *SP Entity ID* field, only it ends with `/acs`. Paste the URL into Entra.
<Frame>
<img />
</Frame>
Make sure to hit *Save* toward the top of the page.
<Frame>
<img />
</Frame>
Next, you'll enter details about Entra into Gumloop.
<Frame>
<img />
</Frame>
### Enter Entra details in Gumloop
Having set up Entra with information about Gumloop, you'll then supply Gumloop with information about the Entra Application. Gumloop needs three pieces of information: an *IDP Entity ID*, a *Redirect URL*, and a *Certificate*.
Start with the last of these, the *Certificate*. In Entra, you'll find this on the third card, closer to the bottom of the page. Next to the *Certificate (Base64)* heading, Entra shows a blue download link. Click this link. It will download a file named for the application. For example, if you've named the application `Gumloop`, Entra will share a `Gumloop.cer` file. Upload this file on your Gumloop SSO setup page.
<Frame>
<img />
</Frame>
For the final two pieces of information, scroll down to the fourth card. Copy the *Microsoft Entra Identifier* field from Entra and paste it into Gumloop's *IDP Entity ID* field. Then copy the *Login URL* field from Entra and paste it into Gumloop's *Redirect URL* field.
<Frame>
<img />
</Frame>
</Steps>
Once you've entered that data in Gumloop, you're finished with Entra configuration!
# SAML with Google Identity
Source: https://docs.gumloop.com/enterprise-features/idp-guides/saml-with-google
Configure SAML single sign-on to Gumloop with Google Identity
Some companies use Google Identity for SAML single sign-on. Please note that SAML single sign-on via Google Identity differs from "Sign in with Google," which uses the [OAuth protocol](https://datatracker.ietf.org/doc/html/rfc6749) and is available on Gumloop out of the box.
<Warning>Before proceeding, please confirm that you indeed need SAML single sign-on via Google rather than "Sign in with Google".</Warning>
## Before you start: get your SP details from Gumloop
A Gumloop organization admin generates an SSO setup link at [gumloop.com/settings/organization/sso](https://www.gumloop.com/settings/organization/sso) (see [SSO: SAML, OIDC & SCIM](/enterprise-features/sso_saml_oidc_scim)). The setup page shows the two Service Provider values you'll copy into Google:
* **Assertion Consumer Service (ACS) URL** — ends in `/acs`
* **SP Entity ID** — the same URL without the `/acs` suffix
The same page has the fields for the values Google produces: **Redirect URL**, **IDP Entity ID**, and the **Certificate** upload.
<Steps>
### Creating a custom SAML app in Google Identity
Starting from the Google Workspace admin page, i.e. [admin.google.com](https://admin.google.com), navigate to *Apps* > *Web and mobile apps* in the left navigation bar. This link will send you to a new page.
<Frame>
<img />
</Frame>
You'll land on a page with the header *Apps* > *Web and mobile apps*. Right under the header, you'll see a few tabs. Click *Add app* > *Add custom SAML app*. This link will send you to another new page.
<Frame>
<img />
</Frame>
You'll see a page with a large blue header reading *Add custom SAML app*. This page requires you to assign the application an *App name*. The *App name* matters solely for display purposes — write "Gumloop".
After typing the *App name*, hit the blue *CONTINUE* button in the lower right.
<Frame>
<img />
</Frame>
### Enter Google details in Gumloop
Clicking *CONTINUE* in the previous step will direct you to a new page, again with the same blue header.
<Info>The previous page enumerated a few steps directly below its header. It's totally normal for those to have disappeared. You're likely still on the right track. Scroll up on this page to display the steps again.</Info>
Here, you'll find a few important details about the new Google Identity app that Gumloop needs to know about. Copy each of these from Google into your Gumloop SSO setup page.
First, scroll down to the field marked *SSO URL*. Gumloop calls this the *Redirect URL*. Copy this URL from Google and paste it into Gumloop.
<Frame>
<img />
</Frame>
From here, direct your attention to Google's *Entity ID* field. It sits directly under the *SSO URL* from the previous step.
Copy this *Entity ID* URL and paste it into Gumloop as the *IDP Entity ID*. You'll find the input field for the *IDP Entity ID* adjacent to the *Redirect URL* input field from the previous step.
<Frame>
<img />
</Frame>
You need just one more detail from Google.
Navigate to the next field marked *Certificate*. Then, toward the top right corner of this *Certificate* field, you'll see a download icon. Press the download icon; doing so downloads a `.pem` file. Its name will match the header you see here, something starting with `Google` and ending in `SAML2_0`.
Upload this `.pem` file on your Gumloop SSO setup page as the *Certificate*.
<Frame>
<img />
</Frame>
Once you're done with this step, Gumloop has all the information it needs. Now you simply need to supply Google with the relevant information about Gumloop.
A blue *CONTINUE* button sits toward the bottom right of the page. It may not be visible until you scroll down. Press this *CONTINUE* button.
### Enter Gumloop details in Google
Once Gumloop knows about the Google app you've created, you need to tell Google about Gumloop. Google needs two pieces of information.
First, Google asks for an *ACS URL*. Gumloop calls this the *Assertion Consumer Service (ACS) URL*, shown on your Gumloop SSO setup page. It ends in `/acs`.
Copy this *Assertion Consumer Service (ACS) URL* and paste it into Google's *ACS URL* input field.
<Frame>
<img />
</Frame>
You'll follow a similar pattern for an additional field.
Directly below its *ACS URL* field, Google asks for an *Entity ID*. Gumloop calls this the *SP Entity ID*. You'll find this URL right next to the *Assertion Consumer Service (ACS) URL* on the setup page. The *SP Entity ID* looks exactly like the *Assertion Consumer Service (ACS) URL*, only it lacks the `/acs` ending.
Copy the *SP Entity ID* from Gumloop and enter it as the *Entity ID* in Google.
<Frame>
<img />
</Frame>
Click the blue *CONTINUE* button in the lower right corner.
<Frame>
<img />
</Frame>
Once you've completed this step, you're done! Gumloop is now hooked up to your Google Identity instance.
Please note that users cannot successfully log in until a Google Identity administrator assigns them to the application.
</Steps>
# SAML with JumpCloud
Source: https://docs.gumloop.com/enterprise-features/idp-guides/saml-with-jumpcloud
Configure SAML single sign-on to Gumloop with JumpCloud
This guide walks a JumpCloud administrator through connecting JumpCloud to Gumloop for SAML single sign-on.
## Before you start: get your SP details from Gumloop
A Gumloop organization admin generates an SSO setup link at [gumloop.com/settings/organization/sso](https://www.gumloop.com/settings/organization/sso) (see [SSO: SAML, OIDC & SCIM](/enterprise-features/sso_saml_oidc_scim)). The setup page shows the two Service Provider values you'll copy into JumpCloud:
* **Assertion Consumer Service (ACS) URL** — ends in `/acs`
* **SP Entity ID** — the same URL without the `/acs` suffix
The same page has the fields for the values JumpCloud produces: **Redirect URL**, **IDP Entity ID**, and the **Certificate** upload.
<Steps>
### Creating a JumpCloud application
Start the JumpCloud set-up by creating an *Application*. From JumpCloud's admin console, click *SSO Applications* in the left navigation pane. This will take you to a new page — the precise page you see depends on how many existing connections the JumpCloud instance has.
<Frame>
<img />
</Frame>
After clicking *SSO Applications*, you'll see a *Configured Applications* page listing any configured SSO apps. On this page, click the green *Add New Application* button toward the top left; it will route you to another new page.
<Note>
If you have no pre-existing SSO applications in JumpCloud, this page will show only a *Get Started* button. In this case, just click *Get Started*.
</Note>
<Frame>
<img />
</Frame>
By this point, you will have arrived at a page reading *Create New Application Integration* in the top left with several cards featuring the logos of common SaaS applications. Look for the *Custom Application* card in the lower right and click where it says *Select*. This will send you to a new page.
<Frame>
<img />
</Frame>
Upon arriving on this next page, click *Next* in the lower right to move on and see the next page.
<Frame>
<img />
</Frame>
Here, you'll see a few checkboxes. Select the first checkbox, labeled *Manage Single Sign-On (SSO)*. Checking this box will trigger two radio buttons to expand. Select the first option from the radio buttons: *Configure SSO with SAML*.
<Frame>
<img />
</Frame>
Click *Next* in the lower right corner.
<Frame>
<img />
</Frame>
JumpCloud wants you to assign a *Display Label*. Write "Gumloop" here.
<Frame>
<img />
</Frame>
Having entered a *Display Label*, click *Save Application* in the lower right corner. This will send you to a new page.
<Frame>
<img />
</Frame>
On this page, press *Configure Application*.
<Frame>
<img />
</Frame>
You've now completed the first step of JumpCloud configuration and can move to the next step, entering details from Gumloop into JumpCloud.
### Enter Gumloop details in JumpCloud
JumpCloud needs two important pieces of information from Gumloop.
Start with the first of these, a field JumpCloud calls the *SP Entity ID*. Gumloop assigns this data the same name. From your Gumloop SSO setup page, copy the URL labeled *SP Entity ID* and paste it into JumpCloud's *SP Entity ID* field.
<Frame>
<img />
</Frame>
JumpCloud asks for *ACS URLs*. Gumloop provides exactly one.
Back on your Gumloop SSO setup page, you'll find a URL marked *Assertion Consumer Service (ACS) URL*. It looks nearly identical to the *SP Entity ID* from the previous step, only affixed with `/acs` at the end of the URL.
Copy the *Assertion Consumer Service (ACS) URL* and paste it into JumpCloud as an *ACS URL*.
<Frame>
<img />
</Frame>
JumpCloud now has all the information it needs about Gumloop.
### Enter JumpCloud details in Gumloop
The next step requires copying a few details from JumpCloud into Gumloop.
First, scroll down to a URL that JumpCloud calls the *IDP URL*. Gumloop calls this the *Redirect URL*. Copy JumpCloud's *IDP URL* and paste it into your Gumloop SSO setup page as the *Redirect URL*.
<Frame>
<img />
</Frame>
Gumloop also needs an *IDP Entity ID*. It turns out that JumpCloud doesn't provide one, but it's fine just to enter two matching strings in both JumpCloud and Gumloop.
Write "JumpCloud" in Gumloop as the *IDP Entity ID*. You just need JumpCloud to match, so write "JumpCloud" in the field that JumpCloud calls *IDP Entity ID*.
<Frame>
<img />
</Frame>
Next, you'll upload a *Certificate* in Gumloop. You'll find the file on the left side of the overlay you've been working in. Press *IDP Certificate Valid* > *Download Certificate*. JumpCloud creates a file called `certificate.pem`. Upload this file on your Gumloop SSO setup page as the *IDP Certificate*.
<Frame>
<img />
</Frame>
You'll adjust one very important setting in JumpCloud before finishing up. Where JumpCloud writes *Sign*, change the radio button setting to *Assertion and Response*. JumpCloud's default setting will not work properly with Gumloop.
<Frame>
<img />
</Frame>
Hit *Save* in the bottom right corner.
<Frame>
<img />
</Frame>
You've finished connecting Gumloop to JumpCloud. Please note, however, that a JumpCloud admin will need to assign users to the application before they can successfully sign in.
</Steps>
# SAML with Okta
Source: https://docs.gumloop.com/enterprise-features/idp-guides/saml-with-okta
Configure SAML single sign-on to Gumloop with Okta
This guide walks an Okta administrator through connecting Okta to Gumloop for SAML single sign-on: you create an *Application* in Okta, then swap details between your Gumloop SSO setup page and Okta.
## Before you start: get your SP details from Gumloop
A Gumloop organization admin generates an SSO setup link at [gumloop.com/settings/organization/sso](https://www.gumloop.com/settings/organization/sso) (see [SSO: SAML, OIDC & SCIM](/enterprise-features/sso_saml_oidc_scim)). The setup page shows the two Service Provider values you'll copy into Okta:
* **Assertion Consumer Service (ACS) URL** — ends in `/acs`
* **SP Entity ID** — the same URL without the `/acs` suffix
The same page has the fields for the values Okta produces: **Redirect URL**, **IDP Entity ID**, and the **Certificate** upload.
<Steps>
### Create an application in Okta
To create an *Application* in Okta, select *Applications* > *Applications* in the left nav panel.
<Frame>
<img />
</Frame>
You'll land on a page with a bold **Applications** header. Right under the header, select the dark blue button that reads *Create App Integration*.
<Frame>
<img />
</Frame>
Okta will flash a modal offering you several radio button choices. Of these, select *SAML 2.0* and then press *Next* in the lower right corner.
<Frame>
<img />
</Frame>
Once you've selected *SAML 2.0*, Okta will change the header to read *Create SAML Integration* as below. Okta requires a display name. Write "Gumloop".
<Frame>
<img />
</Frame>
The remaining options on this page aren't especially important; select *Next* here, which finalizes creation of an Okta *Application*.
<Frame>
<img />
</Frame>
### Enter Gumloop details in Okta
Hitting *Next* on the prior page will have nudged you into a new tab, marked *Configure SAML*. Here, you'll copy two pieces of data from your Gumloop SSO setup page into Okta.
At the top of the page, Okta asks for a *Single sign-on URL*. This is what Gumloop calls the *Assertion Consumer Service (ACS) URL*. It ends in `/acs`. Copy it from your Gumloop SSO setup page and paste it where Okta has written *Single sign-on URL*.
<Frame>
<img />
</Frame>
From here, proceed to the next field on the same page. It reads *Audience URI (SP Entity ID)*. Gumloop calls this the *SP Entity ID*. You'll find it directly under the *Assertion Consumer Service (ACS) URL* on the setup page. It usually looks just like the ACS URL, except it does not end in `/acs`.
Paste the *SP Entity ID* URL into Okta's *Audience URI (SP Entity ID)* field.
<Frame>
<img />
</Frame>
Once you've filled the *Audience URI (SP Entity ID)* field (and scrolled down to hit *Next* in the lower right corner), you've completed all the necessary data entry from Gumloop into Okta.
### Enter Okta details in Gumloop
Okta requires one brief detour wherein you supply feedback to their team.
Select *I'm an Okta customer adding an internal app*, skip the remaining questions, scroll down, and press *Finish* in the lower right corner.
<Frame>
<img />
</Frame>
Now you can enter Okta data into Gumloop. The previous step will have routed you to a page with the application's name at the top.
From here, scroll down a bit and hit *More details*. It's not always easy to see.
<Frame>
<img />
</Frame>
Once you've expanded the details for the SAML application, you'll see a bunch of data.
Directly under the *More details* button, there's a URL marked *Sign on URL* with a light purple *Copy* button. Gumloop calls this the *Redirect URL*. Copy this URL and paste it into your Gumloop SSO setup page as the *Redirect URL*.
<Frame>
<img />
</Frame>
Scrolling further down, you'll see a similar line for a URL that Okta labels *Issuer*. Gumloop calls this the *IDP Entity ID*. Copy this *Issuer* URL and paste it into your Gumloop SSO setup page as the *IDP Entity ID*.
<Frame>
<img />
</Frame>
Finally, Gumloop requires a Certificate. You'll find this further down on the same page in Okta. Okta labels it the *Signing Certificate.* (Please be aware that Okta has several related buttons that will not give you what you need.) Press the rectangular *Download* button, which will download an `okta.cert` file.
Upload `okta.cert` to your Gumloop SSO setup page as the Certificate for this SAML Connection.
<Frame>
<img />
</Frame>
Once you've uploaded the Certificate, you've finished the SAML configuration. Remember that an Okta administrator still has to assign users to the application before they can sign in.
</Steps>
# SAML with Ping Identity
Source: https://docs.gumloop.com/enterprise-features/idp-guides/saml-with-ping
Configure SAML single sign-on to Gumloop with PingOne
This guide walks a PingOne administrator through connecting Ping Identity to Gumloop for SAML single sign-on.
## Before you start: get your SP details from Gumloop
A Gumloop organization admin generates an SSO setup link at [gumloop.com/settings/organization/sso](https://www.gumloop.com/settings/organization/sso) (see [SSO: SAML, OIDC & SCIM](/enterprise-features/sso_saml_oidc_scim)). The setup page shows the two Service Provider values you'll copy into Ping:
* **Assertion Consumer Service (ACS) URL** — ends in `/acs`
* **SP Entity ID** — the same URL without the `/acs` suffix
The same page has the fields for the values Ping produces: **Redirect URL**, **IDP Entity ID**, and the **Certificate** upload.
<Steps>
### Creating an application in PingOne
PingOne setup starts from your administrator home page. Exactly how this looks will vary. This example uses a newly provisioned account and therefore shows an onboarding guide; your admin page will look different in most cases.
Nonetheless, you'll always start by hitting *Applications* > *Applications* in the left navigation bar. This will take you to a new page.
<Frame>
<img />
</Frame>
Once you've navigated to Ping's *Applications* page, press the circular blue button with a plus icon toward the top left. This will trigger a slideover.
<Frame>
<img />
</Frame>
Ping wants you to assign the Application an *Application Name*. The name has no impact on the integration, but Ping will use the *Application Name* as the display name. Write "Gumloop" as the *Application Name*.
<Frame>
<img />
</Frame>
Then you need to tell Ping that the Application uses SAML. Click the card that reads *SAML Application*. You may notice that this changes the text on the blue button below from *Save* to *Configure*.
<Frame>
<img />
</Frame>
Here, select *Configure*. This finalizes creation of the SAML application and progresses you to the next step.
<Frame>
<img />
</Frame>
Next, you'll enter some details from Gumloop into Ping.
### Entering Gumloop data in Ping Identity
You'll now see a page with a *SAML Configuration* header. It will present three radio button options; of these, select *Manually Enter*. Doing so will trigger two input forms below the radio buttons.
<Frame>
<img />
</Frame>
Ping Identity requires two pieces of information about the SAML Connection.
Ping first asks for *ACS URLs*. Gumloop provides exactly one — the URL labeled *Assertion Consumer Service (ACS) URL* on your Gumloop SSO setup page. It always ends in `/acs`.
Copy the URL from Gumloop and paste it into Ping here.
<Frame>
<img />
</Frame>
You'll do something similar again for a field Ping calls *Entity ID*. Gumloop calls this an *SP Entity ID*. You can find it adjacent to the *Assertion Consumer Service (ACS) URL* on the setup page. It matches the *Assertion Consumer Service (ACS) URL* exactly, except it lacks the `/acs` suffix.
<Frame>
<img />
</Frame>
Hit *Save* toward the bottom of the page.
<Frame>
<img />
</Frame>
### Entering Ping Identity data into Gumloop
Now you'll need to enter information about Ping into Gumloop.
To start, make sure you're on the *Configure* tab. In a moment, you'll pull three pieces of information from this tab.
<Frame>
<img />
</Frame>
Gumloop requires a *Certificate* from Ping. You'll find the appropriate uploader on your Gumloop SSO setup page.
To get the file from Ping, click the *Download Signing Certificate* button. Select *X509 PEM (.crt)* from the menu.
You'll see a `.crt` file begin to download. The file may have a long and non-descriptive name; that is normal.
Upload the file to Gumloop.
<Frame>
<img />
</Frame>
After you've taken care of the Certificate, you'll need a field that Gumloop calls an *IDP Entity ID*. It's an input field on the same card as the Certificate uploader.
Ping calls this information an *Issuer ID* and places it directly under *Download Signing Certificate* from the previous step.
Copy this URL from Ping and paste it into Gumloop as the *IDP Entity ID*.
<Frame>
<img />
</Frame>
Finally, look for a field that Ping calls the *Single Signon Service*. Gumloop calls this a *Redirect URL*.
Copy the *Single Signon Service* URL and paste it into Gumloop as the *Redirect URL*.
<Frame>
<img />
</Frame>
Once you've copied over the *Single Signon Service* URL, you're done swapping information between Gumloop and Ping Identity.
Now navigate to the *Attribute Mappings* tab to adjust one final setting in Ping.
<Frame>
<img />
</Frame>
### Adjusting Ping attribute mappings
Here, you'll see three headers: *Attributes*, *PingOne Mappings*, and *Required*. Where you see *saml\_subject* under *Attributes*, change the corresponding *PingOne Mappings* field. This will trigger a dropdown selector. Make sure you've set this field to *Email Address*.
<Frame>
<img />
</Frame>
Hit *Save* at the bottom of the page.
<Frame>
<img />
</Frame>
In the top right, change the toggle from *off* to *on*.
You're all done!
<Frame>
<img />
</Frame>
Please do bear in mind, however, that a Ping admin will still need to assign users to this application before they can sign in.
</Steps>
# SCIM with Entra
Source: https://docs.gumloop.com/enterprise-features/idp-guides/scim-with-entra
Configure SCIM user provisioning for Gumloop with Microsoft Entra ID (formerly Azure Active Directory)
SCIM (the system for cross-domain identity management) lets Entra synchronize user data with Gumloop through recurring communication: Gumloop periodically receives updates about the users that should have access, and uses them to provision or deprovision users — or simply update data about a user (e.g., a first name). See [SSO: SAML, OIDC & SCIM](/enterprise-features/sso_saml_oidc_scim#scim-provisioning).
<Warning>Entra's SCIM implementation has many unresolved issues. (See [here](https://learn.microsoft.com/en-us/entra/identity/app-provisioning/application-provisioning-config-problem-scim-compatibility) for a known subset.) In rare cases, Entra's unusual behavior may result in an unsuccessful integration. Please contact [support@gumloop.com](mailto:support@gumloop.com) if you encounter unexpected behavior.</Warning>
Connecting Entra to Gumloop requires sharing two pieces of information with Entra, both of which come from Gumloop:
1. A **base URL** that Entra will perform operations on (e.g. via HTTP PATCH)
2. A **bearer token** that Entra will include with its requests
When Entra has both of those pieces of information, the connection is complete. No additional Gumloop-side configuration is necessary. With that said, configuration within Entra can be somewhat involved.
## Before you start: get your base URL and bearer token from Gumloop
SCIM is an Enterprise add-on — a Gumloop organization admin requests enablement via [support@gumloop.com](mailto:support@gumloop.com), then generates a setup link at [gumloop.com/settings/organization/sso](https://www.gumloop.com/settings/organization/sso). The setup page shows your SCIM **base URL** and lets you generate the **bearer token**.
<Warning>
Gumloop **does not store bearer tokens** — the token is shown once, at generation time. You can generate a new one at any time, which immediately invalidates the previous token.
</Warning>
# Configuring Entra
Start at the Entra home page. Navigate to *enterprise applications* in the navigation bar.
<Frame>
<img />
</Frame>
You'll now see a list of applications. In this case, we have just one: *test\_application*. Click the blue text to see more details about the application.
<Info>If the relevant application does not exist, you may benefit from reading the [SAML with Entra](/enterprise-features/idp-guides/saml-with-entra) guide on creating an enterprise application.</Info>
<Frame>
<img />
</Frame>
You'll see an *Overview* page. Click on the menu item labeled *Provisioning* on the left.
<Frame>
<img />
</Frame>
This will take you to a new menu. Look toward the top/center of the page for a button with a plus icon labeled *New configuration*. Click this.
<Frame>
<img />
</Frame>
You'll land on a page with a few data input options. Start with the field labeled *Tenant URL*. This is what Gumloop calls the *base URL* — the location where Entra will send its SCIM communications. Copy this value from your Gumloop SCIM setup page and paste it here.
It should look something like the below:
<Frame>
<img />
</Frame>
Next, look at the field labeled *Secret token* directly below the *Tenant URL*. This is the other value that Gumloop provides: the *bearer token*. Paste it into Entra as the *Secret token*.
The *Secret token* is sensitive. Please treat it like a password. Do not share it.
<Frame>
<img />
</Frame>
In Entra, you need to click *Test connection* to move on. Click this button and wait a moment.
<Frame>
<img />
</Frame>
Once it's clickable, hit *Create* in the lower left.
<Frame>
<img />
</Frame>
You'll land on a new page showing an overview of the Entra application. Find the *Users and groups* button in the left navbar and click it.
<Frame>
<img />
</Frame>
We need to assign users and/or groups to the application. Start by clicking the *Add user/group* button toward the top/center of the page. It's marked with a plus icon.
<Frame>
<img />
</Frame>
Exactly what you'll see might vary here, but you'll see a searchable list of users and/or groups. Decide which users should have access to the application, select each, and then press *Select* in the lower left.
<Frame>
<img />
</Frame>
You'll see another menu. If you're content with your selection, press the *Assign* button in the lower left. Entra will now consider those users and/or groups to be *assigned* to the application.
<Frame>
<img />
</Frame>
Entra will not yet have begun SCIM provisioning. To get Entra to begin SCIM provisioning, press the *Overview* button in the left navbar.
<Frame>
<img />
</Frame>
Press the *Start provisioning* button. It has a play button icon — kind of like you'd see on a remote control.
Within a few moments, you'll see a pop-up in the top right. It will say *Provisioning is scheduled to start*.
This means that Entra has successfully begun its communications with Gumloop.
<Frame>
<img />
</Frame>
# Enabling synchronization in Gumloop
Provisioned users only reach your organization once synchronization is enabled on the Gumloop side. A Gumloop organization admin returns to [gumloop.com/settings/organization/sso](https://www.gumloop.com/settings/organization/sso), selects the SCIM directory, and enables synchronization — see [Setting Up SCIM](/enterprise-features/sso_saml_oidc_scim#setting-up-scim).
Once enabled, configuration is complete: assigned users appear in your organization's member list after the next sync (automatic every 15 minutes, or triggered manually by the admin).
# SCIM with Okta
Source: https://docs.gumloop.com/enterprise-features/idp-guides/scim-with-okta
Configure SCIM user provisioning for Gumloop with Okta
SCIM (system for cross-domain identity management) lets Okta communicate with Gumloop on a recurring basis: Okta tells Gumloop which users should have access — and which should not — along with useful user *attributes*. Gumloop uses this to provision, deprovision, and update users automatically (see [SSO: SAML, OIDC & SCIM](/enterprise-features/sso_saml_oidc_scim#scim-provisioning)).
Connecting Okta to Gumloop requires sharing two pieces of information with Okta, both of which come from Gumloop:
1. A **base URL** that Okta will perform operations on (e.g. via HTTP PATCH)
2. A **bearer token** that Okta will include with its requests
## Before you start: get your base URL and bearer token from Gumloop
SCIM is an Enterprise add-on — a Gumloop organization admin requests enablement via [support@gumloop.com](mailto:support@gumloop.com), then generates a setup link at [gumloop.com/settings/organization/sso](https://www.gumloop.com/settings/organization/sso). The setup page shows your SCIM **base URL** and lets you generate the **bearer token**.
<Warning>
Gumloop **does not store bearer tokens** — the token is shown once, at generation time. You can generate a new one at any time, which immediately invalidates the previous token.
</Warning>
# Configuring Okta
Start by navigating to the relevant application in Okta. If you are unsure how to create such an Application, please review the [SAML with Okta](/enterprise-features/idp-guides/saml-with-okta) guide for an in-depth explanation.
<Frame>
<img />
</Frame>
Make sure you're on the *General* tab and press *Edit* on the *App Settings* card.
<Frame>
<img />
</Frame>
Make sure the Provisioning box shows a checkmark. By default, Okta leaves this box unchecked.
<Frame>
<img />
</Frame>
Press *Save* in the lower right corner.
<Frame>
<img />
</Frame>
Navigate to the *Provisioning* tab for the Application.
<Frame>
<img />
</Frame>
On the *Provisioning* tab, click the *Edit* button toward the top right of the card.
<Frame>
<img />
</Frame>
Look for a field marked *SCIM connector base URL*. This is the *base URL* from your Gumloop SCIM setup page. Paste it here.
<Frame>
<img />
</Frame>
Next, look for a field marked *Unique identifier field for users*. We need this to say "email" exactly. Gumloop relies on users' emails as a unique identifier.
<Frame>
<img />
</Frame>
Look for a series of checkboxes labeled *Supported provisioning actions.* You will see five checkboxes. Set your configuration to match the following:
* [x] Import New Users and Profile Updates
* [x] Push New Users
* [x] Push Profile Updates
* [x] Push Groups
* [ ] Import Groups
**Ensure that *Import Groups* remains unchecked.** The SCIM Connection will fail otherwise.
<Frame>
<img />
</Frame>
Now look for a dropdown menu labeled *Authentication Mode*. This must change from its default value to *HTTP Header*.
<Frame>
<img />
</Frame>
Now paste the bearer token from Gumloop in the field marked *Authorization*.
<Frame>
<img />
</Frame>
Then once more hit *Save* in the lower right.
<Frame>
<img />
</Frame>
Now look in the sidebar to the left and find the item marked *To App*. Click this.
<Frame>
<img />
</Frame>
You'll see four checkboxes. Set them to match the following:
* [x] Create Users
* [x] Update User Attributes
* [x] Deactivate Users
* [ ] Sync Password
Then press *Save* in the lower right.
<Frame>
<img />
</Frame>
Now navigate to the *Assignments* tab.
<Frame>
<img />
</Frame>
Using the *Assign* dropdown, choose to assign the relevant People (i.e. users) or Groups. This guide uses People.
<Frame>
<img />
</Frame>
You'll now see a list of People. For each that you wish to assign to the Application, press the *Assign* button to the right.
<Frame>
<img />
</Frame>
You'll have the opportunity to edit this person's attributes, but it's usually fine just to scroll down and press *Save and Go Back*.
<Frame>
<img />
</Frame>
Unless you wish to add other People to the Application, you can now press *Done*.
<Frame>
<img />
</Frame>
Okta is now pushing users to Gumloop.
<Note>
If you assigned users to the Application *before* setting up the SCIM Connection, you may need to instruct Okta to force sync. You can read more [here](https://support.okta.com/help/s/article/How-To-Use-The-Force-Sync-Option?language=en_US).
</Note>
# Enabling synchronization in Gumloop
Pushed users only reach your organization once synchronization is enabled on the Gumloop side. A Gumloop organization admin returns to [gumloop.com/settings/organization/sso](https://www.gumloop.com/settings/organization/sso), selects the SCIM directory, and enables synchronization — see [Setting Up SCIM](/enterprise-features/sso_saml_oidc_scim#setting-up-scim).
Once enabled, configuration is complete: assigned users appear in your organization's member list after the next sync (automatic every 15 minutes, or triggered manually by the admin).
# Managed tunnels
Source: https://docs.gumloop.com/enterprise-features/managed_tunnels
Securely connect MCP servers running inside your private network to Gumloop, without opening any inbound ports.
A managed tunnel gives Gumloop a secure path to MCP servers that only exist inside your network — on a VPC, a corporate network, or a developer machine. You run a lightweight connector next to your servers, it dials out to Gumloop, and each server becomes usable in Gumloop like any other [Proxied MCP](/enterprise-features/proxied_mcps).
No inbound firewall rules, no public IP, and no changes to the MCP servers themselves.
<Frame>
<img alt="Managed Tunnels page under Settings → Organization showing the tunnel table and Add tunnel button" />
</Frame>
## Where to find it
Go to **Settings → Organization → Managed Tunnels** at
[gumloop.com/settings/organization/managed-tunnels](https://gumloop.com/settings/organization/managed-tunnels).
<Warning>
Managed Tunnels is an **Enterprise** feature, and creating, editing, or
deleting a tunnel requires the same organization-admin permission as
[Proxied MCPs](/enterprise-features/proxied_mcps). Contact your organization
admin if you don't see it under **Settings → Organization**.
</Warning>
## How it works
1. You create a tunnel in Gumloop. Gumloop provisions it for you and assigns it a domain — you don't need a Cloudflare account of your own.
2. You run the Cloudflare connector (`cloudflared`) on a machine that can reach your MCP servers, using the tunnel's connector token. The connector makes an **outbound** connection only.
3. You attach each MCP server to the tunnel by giving it a name and the local address it runs on (for example `http://localhost:8000/mcp`).
4. Gumloop publishes each attached server on its own subdomain under `gumlooptunnels.com` and routes requests through the tunnel to that local address. Every hostname is protected by its own access credential that Gumloop manages, so only Gumloop can call it.
### When to use a tunnel
| | Proxied MCP (plain URL) | Proxied MCP over a managed tunnel | [Hosted MCP](/enterprise-features/hosted_mcps) |
| - | - | - | - |
| **Where the server runs** | Third party / anywhere public | Inside your network | On Gumloop's infrastructure |
| **Reachable from the internet?** | Yes | No | N/A |
| **What you run** | Nothing | The `cloudflared` connector | Nothing (deployed from GitHub) |
| **Best for** | Third-party MCP servers | Internal or on-prem MCP servers | Custom MCP servers you build |
## Prerequisites
Before you begin, ensure you have:
* **Organization admin access**: The same permission required for [Proxied MCPs](/enterprise-features/proxied_mcps).
* **A connector host**: An always-on machine that can reach your MCP servers, where you run `cloudflared`.
### Network requirements
Allow outbound traffic from the connector host to [Cloudflare's tunnel edge](https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflare-tunnel/configure-tunnels/tunnel-with-firewall/) on port `7844`, over both TCP and UDP:
```text theme={"dark"}
198.41.192.0/19
2606:4700:a0::/44
```
`cloudflared` prefers QUIC over UDP and falls back to HTTP/2 over TCP, so allow both. No inbound port is opened, and you don't need to allowlist Gumloop's [static egress IPs](/enterprise-features/static_egress_ips) on your MCP servers.
## Create a tunnel
<Steps>
<Step title="Add the tunnel">
On the Managed Tunnels page, click **Add tunnel** and give it a name that describes the network it reaches into — for example, "Prod network". A domain is assigned automatically once the tunnel is created.
<Frame>
<img alt="Create tunnel dialog with a Name field" />
</Frame>
<Note>Each organization can have one managed tunnel. You can attach as many MCP servers to it as you need.</Note>
</Step>
<Step title="Start the connector">
Gumloop shows the connection steps as soon as the tunnel is created, including the exact command to run with the tunnel's token.
<Frame>
<img alt="Tunnel created dialog with three steps: install cloudflared, start the connector, attach your MCP servers" />
</Frame>
1. Install `cloudflared` on a machine that can reach your MCP servers — follow Cloudflare's [install guide](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/) for your OS.
2. Run the connector with your tunnel token:
```bash theme={"dark"}
cloudflared tunnel run --token <your-tunnel-token>
```
3. Keep it running. The tunnel stays online only while the connector is running, so run it as a service on a long-lived host rather than an ad-hoc terminal.
<Tip>You can reopen these instructions and reveal or copy the token any time from the tunnel's **Settings** tab.</Tip>
</Step>
<Step title="Attach your MCP servers">
Open the tunnel and, on the **Overview** tab, click **Attach server**.
<Frame>
<img alt="Tunnel detail page Overview tab with no MCP servers attached yet" />
</Frame>
Give the server a name and the **local address** the connector should forward to — the address the server listens on from the connector machine's point of view, including the scheme and the MCP path.
<Frame>
<img alt="Attach MCP server dialog with Name and Local address fields" />
</Frame>
Two things are easy to get wrong:
* **The address resolves from the connector machine.** If `cloudflared` runs in a container, `localhost` is that container's loopback, not the host's.
* **The path comes from your server, not the tunnel.** FastMCP's streamable HTTP transport serves at `/mcp`; others use `/` or a custom path.
Each attached server gets its own subdomain and MCP URL, listed on the Overview tab next to the local address it points at.
<Frame>
<img alt="Tunnel Overview tab listing an attached MCP server with its MCP URL and local address" />
</Frame>
</Step>
<Step title="Load its tools">
An attached server appears in **Proxied MCPs**, with a **Tunneled via *tunnel name*** link back to the tunnel and the local address shown on its Overview tab.
<Frame>
<img alt="Proxied MCP detail page for a tunneled server showing Tunneled via Prod network, the MCP Server URL, and the local address" />
</Frame>
Once the connector is running, click **Fetch New Tools** to discover the server's tools. From there it behaves like any other proxied server: per-role [tool access control](/enterprise-features/user_groups), activity and usage stats, and availability to agents and flows.
<Warning>
The tunnel carries traffic to your MCP server but does not authenticate
to it. Unlike other [Proxied MCPs](/enterprise-features/proxied_mcps), a
tunneled server can't be given its own OAuth or API key credentials.
</Warning>
</Step>
</Steps>
## Tunnel status
The status badge on the tunnel list and detail page reflects the live state of your connector:
| Status | What it means |
| - | - |
| **Healthy** | The connector is connected and traffic can flow. |
| **Degraded** | Only some of the connector's connections are up. Traffic may still work, but with reduced redundancy. |
| **Down** | The connector has connected before but isn't connected now — usually it stopped or lost network access. |
| **Inactive** | No connector has connected to this tunnel yet. Run the command from the tunnel's Settings tab. |
| **Unknown** | Gumloop couldn't read the tunnel's status just now. Refresh and try again. |
## Manage a tunnel
The tunnel's **Settings** tab is where you rename it, retrieve the connector token, and delete it.
<Frame>
<img alt="Tunnel Settings tab showing Tunnel Name, Connector token, Delete Tunnel, and the connect instructions" />
</Frame>
* **Tunnel Name** — the display name; renaming doesn't affect the domain or any attached server.
* **Connector token** — masked by default. Reveal or copy it when you need to start the connector on a new machine. Treat it like a password: anyone with it can connect a connector to your tunnel.
* **Delete Tunnel** — permanently removes the tunnel and its assigned domain.
<Warning>
You must delete the MCP servers attached to a tunnel before you can delete the
tunnel itself; Gumloop blocks the deletion and lists what's still attached.
After deleting, stop the `cloudflared` process on your machine — it can no
longer connect.
</Warning>
## Security
* **Outbound only.** The connector opens a connection from your network to the tunnel, so you never open an inbound port. "Outbound" describes the connection, not the requests, which travel over it from Gumloop into your network.
* **Per-server access control.** Each attached server is published on its own hostname behind its own access credential, which Gumloop provisions and stores for you. Requests that don't carry it are rejected at the edge, before they ever reach your network. That credential gates the hostname; it isn't authentication to the MCP server itself.
* **Your local addresses stay internal.** The local address is only used by the connector inside your network; it's never the address MCP clients talk to.
* **Admin-gated.** Only organization admins can create tunnels, read the connector token, attach servers, or delete a tunnel.
## Troubleshooting
<AccordionGroup>
<Accordion title="The tunnel shows Inactive or Down">
The connector isn't connected. Check that `cloudflared` is running on the
machine, that it was started with the current token from the tunnel's
Settings tab, and that the machine has outbound internet access. The status
updates when you reload the page.
</Accordion>
<Accordion title="An attached server says “Connect to load tools”">
Its tools haven't been discovered yet. Make sure the connector is running
and the local address is correct, then click **Fetch New Tools** on the
server's detail page.
</Accordion>
<Accordion title="Tool calls fail even though the tunnel is Healthy">
A healthy tunnel means the connector is reachable — not that your MCP server
is. Start with the local address, the most common cause: confirm the scheme,
host, port, and path match what your server listens on from the connector
machine. Then `curl` it there and check the connector's logs.
</Accordion>
<Accordion title="I can't find Managed Tunnels or the Attach server button">
Managing tunnels requires the organization permission for external MCP
servers. Ask an organization admin to create the tunnel and attach servers,
or to grant you the permission.
</Accordion>
</AccordionGroup>
## FAQ
<AccordionGroup>
<Accordion title="Do I need my own Cloudflare account?">
No. Gumloop provisions and manages the tunnel. You only install
`cloudflared` and run it with the token Gumloop gives you.
</Accordion>
<Accordion title="Where should I run the connector?">
On any always-on machine that can reach your MCP servers — a VM in the same
VPC, a container in your cluster, or a bastion host. Run it as a service so
it restarts with the machine.
</Accordion>
<Accordion title="Can one tunnel serve multiple MCP servers?">
Yes. Attach as many as you like; each gets its own subdomain and its own MCP
URL, and each shows up separately under Proxied MCPs.
</Accordion>
<Accordion title="Can I run more than one connector for the same tunnel?">
Yes. Running the same command on a second machine adds another connection to
the tunnel, which is a common way to avoid a single point of failure.
</Accordion>
<Accordion title="How do I detach a server from a tunnel?">
Delete the server from its Proxied MCPs settings. That removes its tunnel
route and its subdomain; the tunnel and its other servers are unaffected.
</Accordion>
</AccordionGroup>
# Enterprise admin starter kit
Source: https://docs.gumloop.com/enterprise-features/onboarding
<div>
<div>
<h1>Enterprise admin starter kit</h1>
<AiWalkthrough />
</div>
<p>Set up your Gumloop organization, welcome a small pilot, and help one department get a useful result from its first agent. Built for the IT admin, security owner, and department champion setting up Gumloop for the first time.</p>
<p>AI assistants: a plain-text version of this guide with deep links is at [https://docs.gumloop.com/enterprise-features/onboarding-ai-guide](https://docs.gumloop.com/enterprise-features/onboarding-ai-guide)</p>
<div>
<EnterpriseSetupChecklist>
<section>
<span>Everyone</span>
## What should I decide before setup?
<p>Decide these or have them handy. Anything open can wait for your setup call.</p>
<div aria-label="How Gumloop is organized">
<div><span>Organization</span><span>Company settings, roles, and policies</span></div>
<div><span>Teams</span><span>Shared spaces for people who work together</span></div>
<div><span>Agents</span><span>Do the work, with Owners who maintain them</span></div>
<div><span>Connectors</span><span>The apps agents reach, through a personal or shared account</span></div>
</div>
| Area | Have ready |
| - | - |
| [Identity](#identity) | Identity provider, whether the pilot needs SSO or SCIM, and your setup admins |
| [Membership](#general) | Invite-only or domain auto-join, and whether chats and files can be shared externally |
| [Connectors](#connectors) | Pilot services, tools or scopes to restrict, and personal or shared Team accounts |
| [Models](#models) | Approved models, retention needs, and whether to use your own provider keys |
| [Guardrails](#connectors) | Actions to block and who approves access requests |
| Security and legal | Security review, questionnaires, DPA or MSA, and audit log needs |
| [Pilot](#agent) | Department lead, first task, kickoff date, and shared Slack channel members |
<div>
**Learn more**
[Gumloop Trust Center](https://trust.gumloop.com)
[AI Model Governance & Configuration](/enterprise-features/ai_model_control)
[App Rules](/enterprise-features/app-policies/app-rules)
</div>
</section>
<section>
<span>IT admin</span>
## What should I review in General settings?
<p>Decide where new members land and who approves their requests.</p>
<div>
**Recommended setup**
**Domain whitelisting:** Add every company email domain so employees join without an invitation. Finish the default Custom Role (step 05) before you announce Gumloop.
**Default Team:** Your pilot Team, once you create it in step 07.
**Approval assignees:** Your IT admin for every request type.
</div>
Open organization [**General**](https://www.gumloop.com/settings/organization/general), headed **Organization Overview**, and review the existing setup before adding members.
<Steps>
<Step title="Check configuration">
Review **Organization Name** and the copyable **Organization ID** used for support. For **Default Team**, choose where new members should land, or **No default team**. Revisit this after creating the pilot Team.
</Step>
<Step title="Review Domain whitelisting">
Check domains already listed. **Add domain** lets matching new users automatically join without an invitation. Review this now, but prepare your default role, model access, connector restrictions, and default Team before enabling new auto-join domains.
<Frame>
<img alt="Domain whitelisting section with Add domain, a test domain, and automatic membership explanation" />
</Frame>
</Step>
<Step title="Name the approval owners">
Review **Approval assignees** for **Feature access**, **Credit limits**, **Model access**, **App access**, and **Organization roles**. Decide who should receive each kind of access request.
<Frame>
<img alt="Approval assignees for feature access, credit limits, model access, app access, and organization roles" />
</Frame>
</Step>
</Steps>
<Warning>
Domain whitelisting lets matching new users join automatically. It does not enforce SSO, and removing a domain does not remove existing members.
</Warning>
**Done when:** you know where new members land and who approves their requests. Optional General settings, such as artifact domains and Slack service accounts, are in [Additional controls](#advanced).
<div>
**Learn more**
[Organization and Teams](/core-concepts/teams#setting-a-default-team)
[User Roles](/core-concepts/organization_user_roles)
</div>
</section>
<section>
<span>IT admin</span>
## Who should help with setup?
<p>Give IT the authority to configure the pilot without making every employee an admin.</p>
<div>
**Recommended setup**
**Admin:** Two or three IT admins, so setup never depends on one person.
**Security:** Your security owner.
**Everyone else:** Member only.
</div>
Invite only the people who need to configure the organization at this stage. Invite the wider pilot after the access policies are ready.
<Steps>
<Step title="Add your IT setup owners">
Open organization [**Members**](https://www.gumloop.com/settings/organization/members). In **Add Member to Organization**, enter **Email**, select the necessary **Roles**, then click **Add**.
</Step>
<Step title="Delegate only the authority needed">
Use **Admin** for organization setup and **Security** for security controls. Admin also covers billing and SSO, so keep that group small.
</Step>
</Steps>
**Done when:** your setup owners have accepted their invitations and can reach the settings they need. Skip this section if the required owners already have access.
<div>
**Learn more**
[User Roles](/core-concepts/organization_user_roles)
</div>
</section>
<section>
<span>IT admin · Security</span>
## Which models and defaults should I approve?
<p>Pick the approved models before anyone starts using agents.</p>
<div>
**Recommended setup**
**Restrict model access:** On, with **Block Selected**.
**Blocked models:** Only models your company does not allow, such as open-source models or specific providers. Leave everything else available.
**File Sharing Behavior:** **Default**.
</div>
Set model policy before inviting the pilot, and review agent defaults before anyone creates the first agent.
<Steps>
<Step title="Approve the organization's models">
Open organization [**Models**](https://www.gumloop.com/settings/organization/models). Under **Restrictions**, turn on **Restrict model access** and choose **Allow Only Selected** for an approved list, or **Block Selected** for specific exclusions.
<Frame>
<img alt="Models Restrictions page showing Restrict model access and non-zero data retention controls" />
</Frame>
</Step>
<Step title="Review new-agent defaults">
Open organization [**Agents**](https://www.gumloop.com/settings/organization/agents). Review **Model** and **File Sharing Behavior**. **Default** inherits chat and agent permissions; **Organization** shares generated files across the organization.
<Frame>
<img alt="Organization Agents settings with model selection and File Sharing Behavior" />
</Frame>
</Step>
</Steps>
**Done when:** the default model is allowed. Agent defaults do not change existing agents. Custom Roles cannot allow a model blocked organization-wide.
Provider keys and model proxies are optional, not prerequisites.
<div>
**Learn more**
[AI Model Governance & Configuration](/enterprise-features/ai_model_control)
[Agent Default Settings](/enterprise-features/agent_default_settings)
</div>
</section>
<section>
<span>Security</span>
## How should I prepare Custom Roles?
<p>Separate the people building agents from the people using them, without piling on unnecessary roles.</p>
<div>
**Recommended setup**
**Default role:** **Full access**, with the changes below.
**Features:** Turn off **External chat sharing** and **External artifact sharing**. Turn on everything else.
**Usage Limits:** Set **Concurrent Agent Limit** to 10, so one heavy user cannot hold up everyone else.
**Extra roles:** Only for groups that need different access.
</div>
Prepare the default role before new employees join. Organization roles grant administrative authority; Custom Roles control connector, model, feature, and usage restrictions.
<Steps>
<Step title="Review the existing default">
Open organization [**Custom Roles**](https://www.gumloop.com/settings/organization/groups). Review the role automatically assigned to new members. Keep it if it already meets your requirements.
</Step>
<Step title="Create a role only when needed">
Click **Create Role**. Choose **No access**, **Full access**, or **Start from template**, then **Next**. Enter **Role name**, then **Confirm**.
<Frame>
<img alt="Create Custom Role dialog showing No access, Full access, Start from template, and Next" />
</Frame>
</Step>
<Step title="Grant the pilot's required access">
Review **Connectors** (which apps, tools, and scopes the group can use), **Models**, **Features**, and **Usage Limits**. A **No access** role needs explicit grants before members can use it. Review **Agent modification** for the department lead creating the agent.
</Step>
</Steps>
<Warning>
A stricter role does not override access allowed by another assigned role. Check the default and every additional role together. The first Custom Role becomes the default if none exists.
</Warning>
Review **External chat sharing**, **External artifact sharing**, and **Agent-owned credentials** in **Features** when the pilot needs restrictions on external access or shared-account use. An agent's own access and file-sharing settings still need a separate review.
**Done when:** the default is ready for new members. Assign additional roles through the role's **Users** tab or the member invitation dialog.
<div>
**Learn more**
[Custom Roles](/enterprise-features/user_groups)
</div>
</section>
<section>
<span>Security</span>
## How do I approve connectors?
<p>Decide which apps the pilot can use and what agents may do in them.</p>
<div>
**Recommended setup**
**Rules:** Start with none. Add a rule only for a specific action to block, such as emails to external domains.
**Domain Restrictions:** Require your company email domain for new connections.
**Claims:** Claim your company's workspaces where available.
</div>
You chose which apps each group can use in [Custom Roles](#roles). **Policies** add optional company-wide rules on top. Allowing an app and connecting an account are separate steps.
Use organization [**Policies**](https://www.gumloop.com/settings/organization/policies) when your company requires these controls:
| Control | Use it to |
| - | - |
| **Rules** | Block or tag particular tool calls. |
| **Domain Restrictions** | Require corporate email domains for new OAuth connections. |
| **Claims** | Claim a provider workspace for your organization. |
**Done when:** you know which apps are approved, which account each will use, and whether company-wide policies are needed.
<Note>
OAuth **Domain Restrictions** govern connector accounts. They are not the same as organization **Domain Whitelisting**, which controls automatic organization membership.
</Note>
<div>
**Learn more**
[Connector Policies](/enterprise-features/app-policies/overview)
[App Rules](/enterprise-features/app-policies/app-rules)
[Domain Restrictions](/enterprise-features/app-policies/domain-restrictions)
[App Claims](/enterprise-features/app-policies/app-claims)
[Connectors](/core-concepts/credentials)
</div>
</section>
<section>
<span>IT admin · Champion</span>
## How should I organize Teams?
<p>Provide a shared home only where collaboration or shared accounts are needed.</p>
<div>
**Recommended setup**
**Teams:** One Team for the pilot department.
**Accounts:** Personal accounts by default. A shared Team account only for shared sources, such as a team drive.
</div>
Create one pilot Team for shared work, not a Team for every entry in your org chart.
<Steps>
<Step title="Create the pilot Team">
On the Home page, click **+** beside **Teams**. In **New Team**, enter **Team Name**, then **Create**.
<Frame>
<img alt="New Team dialog with Team Name, logo, brand color, and Create" />
</Frame>
</Step>
<Step title="Prepare a shared connector only if needed">
Expand the Team and open **Connectors**. A Team Admin can find the approved service and click **Add**. Review **Team credential addition** in their Custom Roles too.
</Step>
</Steps>
Use personal accounts when each participant should act as themselves. Use a shared Team account only when everyone should have that account's access. Limit shared accounts to the pilot's approved data.
**Done when:** the Team exists, its administrator is identified, and any shared account has the right source permissions. Review the default Team in [**General**](https://www.gumloop.com/settings/organization/general) after creating Teams, before new members join.
<div>
**Learn more**
[Organization and Teams](/core-concepts/teams)
[Connectors](/core-concepts/credentials)
</div>
</section>
<section>
<span>IT admin</span>
## When should I configure SSO and SCIM?
<p>Make sure the next sign-in works for everyone, not just your current session.</p>
<div>
**Recommended setup**
**SSO:** The identity provider your company already uses for other tools.
**SCIM:** On if you offboard people through your identity provider.
**Before activating:** Test a fresh sign-in with a non-admin account.
</div>
If you require SSO, set it up before inviting the pilot. Your IT setup group can join first.
<Steps>
<Step title="Choose your identity setup">
Open organization [**Identity Provider**](https://www.gumloop.com/settings/organization/sso) settings and follow the matching provider guide in [SSO: SAML, OIDC & SCIM](/enterprise-features/sso_saml_oidc_scim).
<Frame>
<img alt="Identity Provider configuration with SAML and OpenID Connect setup options" />
</Frame>
</Step>
<Step title="Test sign-in before widening access">
Test with the IT owner and a pilot member, using a fresh sign-in. For Okta OIDC, **Run test** must pass before activation. Match account emails and assign every existing user who needs access to the Okta app.
</Step>
<Step title="Add SCIM only when needed">
Use SCIM for automated provisioning, offboarding, and role or Team mappings. Request enablement from support, and set the mappings before syncing the wider group. SCIM runs through a SAML app even if sign-in uses OIDC, and removing someone's SAML app assignment can deactivate them in Gumloop.
</Step>
</Steps>
<Warning>
Activating SSO turns off Google and email sign-in for your SSO domains. Test a fresh sign-in first; staying signed in is not proof the next sign-in works.
</Warning>
**Done when:** an ordinary pilot member can sign in, and provisioning places them in the expected roles and Teams. Keep manual invitations and identity-provider provisioning aligned.
<div>
**Learn more**
[SSO: SAML, OIDC & SCIM](/enterprise-features/sso_saml_oidc_scim)
[OIDC with Okta](/enterprise-features/idp-guides/oidc-with-okta)
[SCIM with Okta](/enterprise-features/idp-guides/scim-with-okta)
[SCIM with Entra](/enterprise-features/idp-guides/scim-with-entra)
</div>
</section>
<section>
<span>Champion · IT admin</span>
## How do I launch the first agent?
<p>Start with a task the department cares about, not a perfectly configured but unused agent.</p>
<div>
**Recommended setup**
**Who Can Use:** **Team**.
**Owner:** The department lead.
**Task Visibility:** **Their tasks only**.
**Sensitive tools:** **Ask for writes/deletes** on anything that sends or changes data.
</div>
Choose a first task with the department lead before configuring the agent. For an HR & People pilot, the goal can be: answer a handbook question, cite the policy, and refer unanswered questions to HR, without accessing employee records.
<Steps>
<Step title="Invite the department lead">
Invite the lead from organization [**Members**](https://www.gumloop.com/settings/organization/members) with the pilot's **Custom Roles** and **Team**, so they can build the agent before the rest of the pilot joins.
</Step>
<Step title="Create it in the pilot Team">
Open the Team's **Agents** page and create the agent. In **Agent**, describe its job and boundaries.
```text Example instructions wrap theme={"dark"}
Answer policy questions using only the approved sources.
Cite the source. If it does not answer the question, say so and refer to HR.
Do not access employee records or change HR systems.
```
</Step>
<Step title="Choose the account and tools">
In **Connectors**, add the service that holds the approved sources, such as the drive with your handbook. Select **Use Personal Default** for each person's account or **Use Team Default** for the shared account. Adding a Team connection does not select it automatically. Deny unnecessary tools; use **Ask for writes/deletes** for enabled sensitive tools.
</Step>
<Step title="Review Access and save">
Set **Who Can Use** to **Team**. Add the department lead as an **Owner**. Set **Task Visibility** to **Their tasks only** for this pilot; new team agents default to **Team tasks**. Review **File Sharing**, **Create Triggers**, and **Make a copy**, then **Save**.
<Frame>
<img alt="Team agent Access panel showing Who Can Use, File Sharing, and Task Visibility" />
</Frame>
</Step>
</Steps>
Start a **New Task** and try this prompt. Review the answer with the department lead before testing as an ordinary member.
```text Test prompt wrap theme={"dark"}
What does the approved employee handbook say about taking time off? Cite the policy, and tell me if the sources do not answer the question.
```
**Done when:** Users can run the agent without editing it. Owners and authorized administrators retain administrative visibility; **Their tasks only** is not a confidential channel hidden from them. Instructions do not enforce data access, so restrict the account and tools too.
<div>
**Learn more**
[Agents](/core-concepts/agents)
[Agent Access](/core-concepts/agent_access)
[Connectors](/core-concepts/credentials)
</div>
</section>
<section>
<span>IT admin</span>
## When should I invite employees?
<p>Invite people once there is something useful and safe for them to use.</p>
<div>
**Recommended setup**
**Pilot group:** A small group from one department.
**Assignment:** The pilot Team and the default Custom Role.
</div>
Invite the pilot once the first agent works and sign-in is ready.
<Steps>
<Step title="Choose manual invitations or provisioning">
For manual invitations, open organization [**Members**](https://www.gumloop.com/settings/organization/members). In **Add Member to Organization**, enter **Email**, select **Custom Roles** and **Teams**, and click **Add**. Every member has the baseline Member role; add other organization roles only when needed.
<Frame>
<img alt="Add Member to Organization dialog with Email, Roles, Custom Roles, Teams, and Add" />
</Frame>
</Step>
<Step title="Confirm membership">
Wait for acceptance. For someone already in the organization, right-click the Team and choose **Invite to Team**. If SCIM manages membership, verify the identity-provider assignment and sync instead.
</Step>
</Steps>
**Done when:** the member has the expected Team, Custom Roles, and model access. Do not use an Admin account as your only test.
If you want domain-based automatic joining, enable it only after these defaults are ready and confirm the landing experience.
<div>
**Learn more**
[User Roles](/core-concepts/organization_user_roles)
[Organization and Teams](/core-concepts/teams#adding-team-members)
</div>
</section>
<section>
<span>Champion · IT admin</span>
## How do I check that setup is ready?
<p>Prove usefulness and access boundaries before expanding the audience.</p>
<div>
**Recommended setup**
**Testing:** Use a non-admin account.
**Expanding:** One team at a time, after the department lead signs off.
</div>
Test as an ordinary pilot member before inviting a wider audience.
| Test | Expected result |
| - | - |
| Join and sign in | The intended organization, Team, and roles are applied. |
| Run the agent | The approved model and intended connector account work. |
| Ask a supported question | The answer cites an approved source. |
| Ask for unavailable data or an unnecessary action | No unauthorized data or tool is available. |
| Check User access | No editing or browsing another User's tasks. |
Review organization [**Insights**](https://www.gumloop.com/settings/organization/insights) for adoption and spend, and [**Audit Logging**](https://www.gumloop.com/settings/organization/audit-logging) for administrative changes. Give reporting responsibilities to the appropriate [User Roles](/core-concepts/organization_user_roles), not blanket Admin access.
**Done when:** the department lead accepts the results and owns ongoing corrections. Share the agent link, supported tasks, and contact person, then expand membership in stages.
<div>
**Learn more**
[Organization Insights](/enterprise-features/organization_insights)
[Audit Logging](/enterprise-features/audit_logging)
[User Roles](/core-concepts/organization_user_roles)
</div>
</section>
<section>
## Frequently asked questions
<p>Short answers to what new admins ask most.</p>
<AccordionGroup>
<Accordion title="How do roles, Teams, and accounts fit together?">
Think of five separate questions: who manages the organization, where shared work lives, what a person may use, who owns the agent, and whose external account it uses.
| Question | Control | Pilot example |
| - | - | - |
| Who manages company settings? | Organization role | IT has Admin; an employee has Member. |
| Where do people collaborate? | Team | HR & People has a shared space. |
| Which tools, models, and features may a person use? | Custom Role | The pilot gets approved apps and models. |
| Who maintains or runs this agent? | Agent Access | The lead is Owner; participants are Users. |
| Whose data can a tool reach? | Connector account | Each participant's account, or an approved shared Team account. |
</Accordion>
<Accordion title="Do I need both a Team and a Custom Role for each department?">
No. A Team is a shared space; a Custom Role is an organization-level access policy. Create a Team when people need shared work. Create another Custom Role only when their policy needs differ. A department does not automatically need a one-to-one pair. See [Organization and Teams](/core-concepts/teams) and [Custom Roles](/enterprise-features/user_groups).
</Accordion>
<Accordion title="Why does a restrictive Custom Role not override a permissive one?">
Access allowed by another assigned role remains available. Review the default and all additional roles together, then change the role that grants unwanted access. More roles do not necessarily mean tighter control.
</Accordion>
<Accordion title="Does joining a Team let someone edit its agents?">
No. Team membership gives User access to team agents. Maintaining an agent requires Owner access, and creating or modifying agents also depends on the person's Custom Roles. Team Admin and agent Owner are different responsibilities. See [Agent Access](/core-concepts/agent_access).
</Accordion>
<Accordion title="Does connecting an app mean everyone uses the same account?">
No. **Use Personal Default** uses the running person's account. **Use Team Default** uses the shared Team account. Configure that choice explicitly on the agent. An app allowlist is permission, not authentication. See [Connectors](/core-concepts/credentials).
</Accordion>
<Accordion title="Who can see what people ask an agent?">
Agent Owners can see every task on the agent. Users see what **Task Visibility** allows. Authorized administrators keep administrative visibility, so **Their tasks only** is not a private channel. See [Agent Access](/core-concepts/agent_access).
</Accordion>
<Accordion title="Is our data used to train models?">
Every model Gumloop serves runs under zero data retention except Anthropic's Claude Fable family, which keeps prompts and outputs for 30 days to check for misuse and does not train on them. Turn off **Allow non-zero data retention models** in **Models** to exclude them. See [AI Model Governance & Configuration](/enterprise-features/ai_model_control).
</Accordion>
<Accordion title="What happens when someone leaves?">
Remove them from the three-dot menu on [**Members**](https://www.gumloop.com/settings/organization/members), or let SCIM deprovision them. Their active triggers turn off. Nothing else is deleted, so a remaining member re-creates any trigger that should keep running. See [User Roles](/core-concepts/organization_user_roles#removing-a-member).
</Accordion>
<Accordion title="What about employees who already use Gumloop?">
With OIDC sign-in, Gumloop matches an existing account by email on first sign-in. Check that emails in your identity provider match the accounts people already use. See [SSO: SAML, OIDC & SCIM](/enterprise-features/sso_saml_oidc_scim).
</Accordion>
<Accordion title="Are domain auto-join, SSO, and OAuth domain restrictions the same thing?">
No. Domain whitelisting admits matching new users to the organization. SSO controls sign-in through an identity provider. OAuth Domain Restrictions govern new connector authentications. Review each independently; configuring one does not replace the others.
</Accordion>
</AccordionGroup>
</section>
<section>
## What else can I configure at enterprise level?
<p>Add controls for a real requirement rather than treating every enterprise feature as mandatory.</p>
Configure these when a company requirement or use case needs them. They are not all prerequisites, but a mandatory network or security requirement belongs before the affected pilot.
<AccordionGroup>
<Accordion title="Budgets and reusable organization guidance">
Review [**Usage & Limits**](https://www.gumloop.com/settings/organization/limits) with your budget owner, alongside Custom Role usage caps and approval assignees. See [Credits](/core-concepts/credits) for how usage is counted. Use [Organization Skills](/core-concepts/organization_skills) for shared agent guidance.
</Accordion>
<Accordion title="Optional General settings">
Review **Custom artifact domain** for branded file hosting, and **Slack workspaces** plus **Service account** for Slack-based agent access. Use **Google Workspace directory** or **Microsoft directory** when you need [Brain](/core-concepts/brain) to honor source-group permissions. Directory access is separate from SSO.
</Accordion>
<Accordion title="Provider keys, model proxies, and custom OAuth">
Use organization [**API Keys & Proxies**](https://www.gumloop.com/settings/organization/api-keys) for provider credentials and model routing. [**OAuth Configuration**](https://www.gumloop.com/settings/organization/oauth-configuration) is separate and applies to supported connector authentication. See [AI Model Governance & Configuration](/enterprise-features/ai_model_control).
</Accordion>
<Accordion title="Custom and private-network integrations">
Use [Hosted MCPs](/enterprise-features/hosted_mcps) for custom servers hosted by Gumloop, [Proxied MCPs](/enterprise-features/proxied_mcps) for existing servers, and [Managed Tunnels](/enterprise-features/managed_tunnels) for servers in private networks. Use [Static Egress IPs](/enterprise-features/static_egress_ips) when your network requires outbound IP allowlists.
</Accordion>
<Accordion title="Reporting, exports, and event delivery">
Use [Organization Insights](/enterprise-features/organization_insights) for adoption, [Audit Logging](/enterprise-features/audit_logging) for administrative changes, [Usage Data Export](/enterprise-features/organization_data_export) for exports or data drains, and [Outbound Webhooks](/enterprise-features/organization_webhooks) for supported organization events.
</Accordion>
<Accordion title="Slack and Microsoft Teams access">
Validate the agent first, then add the required communication channel. Review [Using Agents in Slack](/core-concepts/agents_slack), [Using Agents in Microsoft Teams](/core-concepts/agents_teams), and [Organization Service Accounts for Slack Agents](/enterprise-features/slack_agent_access). A Gumloop Team is not a Microsoft Teams channel.
</Accordion>
</AccordionGroup>
</section>
</EnterpriseSetupChecklist>
</div>
</div>
# Usage data export
Source: https://docs.gumloop.com/enterprise-features/organization_data_export
Usage Data Export allows enterprise organization administrators to export comprehensive data from their Gumloop organization. This feature supports both **one-time exports** and **continuous data drains** for analysis, compliance reporting, credit consumption tracking, and backup purposes.
Exports can be scoped to the **entire organization** or to your **personal data only**. See [Export Scopes](#export-scopes) for details.
## What you can do
<CardGroup>
<Card title="Track credit consumption" icon="chart-line">
Monitor credit usage across teams and users over time
</Card>
<Card title="Compliance reporting" icon="file-shield">
Export data for audit trails and regulatory compliance
</Card>
<Card title="Usage analytics" icon="chart-pie">
Analyze workflow execution patterns and user activity
</Card>
<Card title="Data backup" icon="cloud-arrow-down">
Create backups of organizational workflow metadata
</Card>
<Card title="Billing analysis" icon="dollar-sign">
Understand cost allocation across teams and projects
</Card>
<Card title="Continuous sync" icon="paper-plane">
Set up data drains to continuously push data to external destinations
</Card>
</CardGroup>
<Info>
Navigate to your organization's data export settings at: [gumloop.com/settings/organization/data\_export](https://gumloop.com/settings/organization/data_export)
</Info>
The data export page includes **Exports** for one-time downloads and **Drains** for continuous syncing. Users with permission to export organization data also see **Webhooks**, for sending organization events to their own endpoint. See [Outbound Webhooks](/enterprise-features/organization_webhooks).
## Data types
Gumloop supports seven types of data for both exports and drains:
| Data Type | Description |
| - | - |
| **Workflow Runs** | Execution history including run IDs, credit costs, timestamps, and workflow metadata |
| **Agents** | Agent configurations including names, descriptions, system prompts, and tool settings |
| **Agent Interactions** | Agent interaction data including timestamps, credit costs, trigger types, and message counts |
| **Credit Logs** | Credit usage logs including amounts, categories, and balances |
| **Audit Logs** | Security and compliance audit logs including user actions, authentication events, and configuration changes |
| **Connector Activity** | Tool call activity including timestamps, statuses, and latency (`gumstack` in the API) |
| **Interaction Evaluations** | Completed [evaluations](/core-concepts/evaluations) of agent chats, including grade, call outcome, sentiment, and the model that graded them |
## One-time exports
One-time exports let you download a snapshot of your organization's data for a specific date range as a CSV file.
### Export process
<Steps>
<Step title="Select data type" icon="list">
Pick **Personal** or **Organization** scope, then choose what data you want to export from the seven available types.
<Frame>
<img alt="Export scope step with Personal and Organization options and the list of exportable data types" />
</Frame>
</Step>
<Step title="Select date range" icon="calendar">
Define the time period for your data extraction.
<Frame>
<img alt="Date Range Selection" />
</Frame>
**Features:**
* **Billing Period Presets**: Quickly select a billing period from the dropdown
* **Custom Date Range**: Pick specific start and end dates with the calendar picker
* **Timezone Support**: Choose the timezone for date interpretation
</Step>
<Step title="Choose Teams" icon="folder">
Select which teams to include in your export.
<Note>This step applies to **Workflow Runs**, **Agents**, **Agent Interactions**, and **Interaction Evaluations** exports only. **Credit Logs**, **Audit Logs**, and **Connector Activity** exports are scoped to the entire organization.</Note>
<Frame>
<img alt="Team Selection" />
</Frame>
<AccordionGroup>
<Accordion title="Organization teams">
* **Searchable List**: Find teams quickly using search functionality
* **Individual Selection**: Choose specific teams with checkboxes
* **Select All Toggle**: Bulk select all organization teams
</Accordion>
<Accordion title="Personal spaces">
* **Optional Toggle**: Include personal spaces of organization members
* **Comprehensive Coverage**: When enabled, includes all user personal spaces in the export
<Frame>
<img alt="Personal Space Selection" />
</Frame>
</Accordion>
</AccordionGroup>
</Step>
<Step title="Select data fields" icon="table">
Choose which data categories and fields to include in your export.
<Frame>
<img alt="Select fields to export step with Minimal, Default, Full, and Custom presets and per-category field checkboxes" />
</Frame>
### Field Presets
| Preset | Description |
| - | - |
| **Minimal** | Essential identifiers and timestamps only |
| **Default** | Recommended set of commonly used fields |
| **Full** | All available fields including detailed data |
| **Custom** | Select specific fields manually |
### Available Data Categories
<Tabs>
<Tab title="Team info">
| Field | Description |
| - | - |
| Team ID | Unique identifier for the team |
| Team Name | Display name of the team |
</Tab>
<Tab title="Workbook info">
| Field | Description |
| - | - |
| Workbook ID | Unique identifier for the workbook |
| Workbook Name | Display name of the workbook |
| Created Timestamp | When the workbook was created |
</Tab>
<Tab title="User info">
| Field | Description |
| - | - |
| User ID | Unique identifier for the user |
| User Email | Email address of the user |
</Tab>
<Tab title="Run info">
| Field | Description |
| - | - |
| Run ID | Unique identifier for the workflow run |
| Credit Cost | Number of credits consumed |
| Created Timestamp | When the run started |
| Finished Timestamp | When the run completed |
</Tab>
<Tab title="Agent info">
| Field | Description |
| - | - |
| Agent ID | Unique identifier for the agent |
| Agent Name | Display name of the agent |
| Agent Description | Description of the agent |
| Model | Model the agent runs on |
| System Prompt | The agent's system prompt |
| Created Timestamp | When the agent was created |
| Tools | Tools configured on the agent (JSON) |
| Metadata | Additional agent metadata (JSON) |
| Creator Email | Email of the user who created the agent |
| Folder ID | Identifier of the folder containing the agent (empty when the agent is not in a folder) |
| Folder Name | Name of the folder containing the agent (empty when the agent is not in a folder) |
| Evaluations Enabled | Whether the agent's own evaluation configuration is enabled (`agent_evaluations_enabled`). Disabled by default in field selection. This does not indicate coverage by organization-level evaluations. |
</Tab>
<Tab title="Interaction evaluations">
| Category | Fields |
| - | - |
| **Identifiers** | Evaluation ID, Interaction ID, Agent ID, Organization Evaluation ID (empty for agent-level rubrics) |
| **Result** | Status, Grade, Call Outcome, Sentiment, Error Code, Summary |
| **Run info** | Evaluation Timestamp, Evaluation Model, Credit Cost, User Email |
<Note>One chat can produce several rows — one per rubric, plus one for each rerun — so use **Evaluation ID**, not Interaction ID, as the unique key. Rows appear only once the evaluation has finished; detailed per-criterion results, data results, and applied tags are not included.</Note>
</Tab>
<Tab title="Credit logs">
| Category | Fields |
| - | - |
| **User** | User Email, Custom Role ID(s) (disabled by default), Custom Role Name(s) (disabled by default) |
| **Log** | Date, Category, Type, Name, Amount, Balance |
| **Identifiers** | Log ID, Correlation ID (run or interaction join key, disabled by default), Balance Scope (disabled by default), Project ID (disabled by default) |
</Tab>
</Tabs>
</Step>
</Steps>
### Managing exports
Monitor and manage all your previous export requests from the **Exports** tab.
<Frame>
<img alt="Export History" />
</Frame>
**What you'll see:**
* **Status Tracking**: Real-time status updates with colored badges
* **Date Range Display**: Clear indication of exported data timeframes
* **Creation Timestamps**: When each export was requested
* **Download Actions**: Direct CSV file download capability
<Tip>
When your export completes successfully, you'll receive an email notification confirming that your export is ready for download.
</Tip>
### Downloaded data format
Exported data is provided as CSV files with:
* **Header Row**: Column names matching selected fields
* **Comma Separation**: Standard CSV format for easy import into analysis tools
* **Date Formatting**: ISO 8601 timestamp format
***
## Data drains
Data Drains let you continuously push organization data to an external destination. Unlike one-time exports, drains run automatically in the background and sync new data as it becomes available.
<Frame>
<img alt="Data Drains Overview" />
</Frame>
### How drains work
Once created, a drain continuously monitors your selected data type for new records. When new data appears, it is automatically batched and delivered to your configured destination. The drain keeps track of what has already been synced using an internal cursor, so you never receive duplicate data.
Key behaviors:
* **Automatic syncing**: New data is pushed to your destination without manual intervention
* **Adaptive polling**: Sync frequency adjusts based on data volume, from every 15 seconds during high activity to up to 10 minutes during quiet periods
* **Crash-safe cursor**: The sync cursor advances after each successfully delivered batch, so no data is lost if a delivery fails mid-cycle
* **Automatic error handling**: If a drain encounters 3 consecutive failures, it is automatically paused with an "Error" status
### Creating a drain
To create a new drain, switch to the **Drains** tab and click **+ Add Drain**. The drain creation wizard walks you through the following steps:
<Steps>
<Step title="Select data type" icon="list">
Choose the type of data you want to continuously sync. Available types are: Workflow Runs, Agents, Agent Interactions, Interaction Evaluations, Credit Logs, Audit Logs, and Connector Activity.
</Step>
<Step title="Configure scope" icon="calendar">
Depending on the data type, configure filtering options for the drain:
* **Workflow Runs, Agents, Agent Interactions, Interaction Evaluations**: Select which teams to include and optionally include personal workspaces
* **Credit Logs**: Optionally filter by credit log category
* **Audit Logs, Connector Activity**: No additional scope configuration needed (this step is skipped)
<Note>Unlike one-time exports, drains do not require a date range. They start syncing from the time the drain is created and continue forward.</Note>
</Step>
<Step title="Select fields" icon="table">
Choose which fields to include in the synced data. The same field presets are available as for one-time exports: Minimal, Default, Full, or Custom.
<Frame>
<img alt="Drain Field Selection" />
</Frame>
</Step>
<Step title="Configure destination" icon="paper-plane">
Set up where data should be delivered. You'll need to provide a **drain name** and select a **destination type**.
<Frame>
<img alt="Drain Destination Configuration" />
</Frame>
Gumloop supports three destination types:
<Tabs>
<Tab title="Custom endpoint">
Push data to any HTTP endpoint you control.
**Configuration:**
* **Endpoint Authentication**: Connect your HTTP credentials (URL, authorization header, and optional signing secret)
* **Format**: Choose between **JSON** (default) or **OTLP** (OpenTelemetry Log Protocol)
**Payload format (JSON):**
```json theme={"dark"}
{
"source": "gumloop",
"drain_id": "abc123",
"drain_name": "My Drain",
"data_type": "credit_logs",
"records": [
{ "user_email": "user@example.com", "amount": -5, "category": "Workflow Runs", ... }
]
}
```
See the [Drain Payload Reference](#drain-payload-reference) for the full record semantics.
**Headers included:**
* `Content-Type: application/json`
* `X-Gumloop-Drain-Id`: The drain's unique identifier
* `X-Gumloop-Data-Type`: The data type being synced
* `Authorization`: Your configured authorization header (if set)
* `X-Gumloop-Signature`: HMAC-SHA256 signature of the request body (if a signing secret is configured)
<Tip>
Use the signing secret to verify that incoming requests are genuinely from Gumloop. Compute an HMAC-SHA256 of the raw request body using your signing secret and compare it with the `X-Gumloop-Signature` header.
</Tip>
</Tab>
<Tab title="Amazon S3">
Push data as JSON files to an S3 bucket.
**Configuration:**
* **AWS Credentials**: Connect your AWS access key and secret
* **Bucket**: The name of your S3 bucket
* **Path Prefix** (optional): A folder path prefix for the uploaded files (e.g., `exports/gumloop`)
Files are organized by date with the path pattern:
```text theme={"dark"}
{prefix}/{YYYY}/{MM}/{DD}/{drain_id}_{HHMMSS}_{microseconds}.json
```
</Tab>
<Tab title="Datadog">
Push data as logs to Datadog.
**Configuration:**
Connect your Datadog credential, which has three fields:
* **API Key** (required): Your Datadog API key. Authenticates log delivery to Datadog's Log Intake API.
* **Application Key** (optional): Leave this blank for drains. Only the Datadog connector uses it.
* **Site** (optional): Your Datadog site. Defaults to `datadoghq.com`.
<Note>
Gumloop uses one shared Datadog credential for both data drains and the Datadog connector, so the credential form always shows an **Application Key** field. Drains only use the **API Key**, so you can leave the Application Key empty.
</Note>
Logs are sent to Datadog's Log Intake API with:
* **Source**: `gumloop`
* **Service**: `gumloop.{data_type}` (e.g., `gumloop.credit_logs`)
* **Tags**: `drain_id:{id},drain_name:{name}`
<Tip>
Supported Datadog sites include `datadoghq.com`, `datadoghq.eu`, `us3.datadoghq.com`, `us5.datadoghq.com`, `ap1.datadoghq.com`, and `ddog-gov.com`.
</Tip>
</Tab>
</Tabs>
</Step>
<Step title="Review" icon="check">
Review all your settings before creating the drain. When you click **Create Drain**, Gumloop runs a preflight check to verify the destination is reachable and properly configured. If the check passes, the drain is created and begins syncing immediately.
</Step>
</Steps>
### Managing drains
The **Drains** tab shows all your configured drains with the following information:
| Column | Description |
| - | - |
| **Name** | Drain name and destination type icon |
| **Status** | Current status: Active, Paused, or Error |
| **Data Type** | The type of data being synced |
| **Last Synced** | When data was last successfully delivered |
| **Created** | When the drain was first set up |
| **Actions** | Delete the drain |
### Drain statuses
| Status | Description |
| - | - |
| **Active** | The drain is running normally and syncing data |
| **Paused** | The drain has been paused |
| **Error** | The drain encountered 3 consecutive delivery failures and was automatically paused. Check your destination configuration and credentials |
<Warning>
Deleting a drain is permanent. If you delete a drain and create a new one, the new drain will start syncing from the current time, not from where the previous drain left off.
</Warning>
***
## Drain payload reference
Use this section if you are building a system on top of drain output — a usage warehouse, a cost monitor, or an anomaly detector.
### Payload envelope
Every delivery (one S3 object, or one HTTP POST body) is a single JSON document:
```json theme={"dark"}
{
"source": "gumloop",
"drain_id": "abc123",
"drain_name": "My Drain",
"data_type": "credit_logs",
"records": [ { "...": "one object per record" } ]
}
```
For Datadog destinations there is no envelope: each record is sent as its own log, with the record JSON in the log `message` and the drain identity in the tags.
| Destination | Records per delivery |
| - | - |
| Amazon S3 | 5,000 |
| Custom Endpoint | 1,000 |
| Datadog | 1,000 |
<Note>
**There is no fixed record schema.** The keys of each record are exactly the fields you selected when creating the drain, plus that data type's timestamp field, which is always included. Two drains on the same data type with different field selections produce different record shapes.
</Note>
### Timestamps
Credit log timestamps are ISO 8601 with a `T` separator (`2026-08-19T17:18:04.512+00:00`). Timestamps on workflow, agent, and agent interaction records are rendered with a space separator (`2026-08-19 17:18:04.512000+00:00`). All values are UTC. Parse both forms.
### Delivery model
Each drain tracks a cursor on exactly one timestamp column:
| Data Type | Cursor field |
| - | - |
| Workflow Runs | `pl_run_created_ts` |
| Agents | `agent_created_ts` |
| Agent Interactions | `interaction_created_ts` |
| Credit Logs | `timestamp` |
| Audit Logs | `timestamp` |
| Connector Activity | `created_at` |
| Interaction Evaluations | `evaluation_created_ts` |
Every sync selects records newer than the cursor in ascending order, delivers them, then advances the cursor. **Each record is delivered once and is never re-sent or updated.**
<Warning>
**Workflow Runs and Agent Interactions are cursored on creation time, but their credit cost accumulates while the run or session is still going.** If a sync fires while a run is in flight, that record is delivered with the cost it had at that moment, and the corrected total is never re-sent.
For cost reporting, use the **Credit Logs** drain: those rows are written at the moment each charge happens and are never modified afterwards.
</Warning>
### Cost fields by data type
<Tabs>
<Tab title="Credit logs">
One record per individual charge — this is the ledger that the credit numbers in the Gumloop UI are computed from.
| Field | Meaning |
| - | - |
| `log_id` | Unique id of the ledger row |
| `timestamp` | When the charge was recorded (UTC) |
| `amount` | Signed credits. **Deductions are negative**; grants and manual adjustments are positive |
| `balance` | Credit balance after this row, in the scope given by `balance_scope` |
| `balance_scope` | `organization` or `user` |
| `category` | Human-readable category label (see below) |
| `type` | Human-readable type label (see below) |
| `name` | Display name of the workflow or agent that was charged |
| `correlation_id` | Event key — the workflow run, agent interaction, or operator run the charge belongs to |
| `project_id` | Team the charge is attributed to |
| `user_email` | Member who incurred the charge |
| `permission_group_id` / `permission_group_name` | The member's custom role(s), `; `-separated |
<Note>
Some rows are accounting entries rather than usage: credit resets and credit cap adjustments carry no `amount`. Exclude them from consumption totals.
</Note>
</Tab>
<Tab title="Workflow runs">
One record per workflow run.
| Field | Meaning |
| - | - |
| `credit_cost` | Credits charged for **that run only** |
| `run_id` | Matches `correlation_id` on the run's credit log rows |
| `pl_run_created_ts` / `pl_run_finished_ts` | When the run started and finished |
Subflow (child) runs arrive as their own records with their own `credit_cost`, so summing every record gives the full total without double counting.
If the drain was created with the `hide_child_runs` option, child runs are omitted and each parent record's `credit_cost` instead includes its children's cost. Don't mix results from the two configurations.
</Tab>
<Tab title="Agent interactions">
One record per agent interaction.
| Field | Meaning |
| - | - |
| `credit_cost` | Total credits: model inference + tools + workflows + compute time + platform fee |
| `llm_credit_cost` | Model inference portion only |
| `tool_credit_cost` | Tool and MCP call portion |
| `flow_credit_cost` | Portion from workflows the agent ran |
| `interaction_id` | Matches `correlation_id` on the interaction's credit log rows |
Compute time and platform fee are included in `credit_cost` but have no dedicated fields. To break them out, read the `Compute Time` and `Platform Fee` rows from a Credit Logs drain.
</Tab>
<Tab title="Connector activity">
Connector Activity records describe tool call activity (`tool_name`, `server_id`, `status`, `latency_ms`, `error`, and the calling user or agent) and contain **no cost fields**.
The credits for those calls appear in Credit Logs as `Gumstack Tool Call` and `guMCP Tool Call` rows.
</Tab>
</Tabs>
Agents and Audit Logs records contain no cost fields.
### Reconciling drain data with the UI
<Steps>
<Step title="Sum credits from Credit Logs, not from run records">
Add up `amount` on Credit Logs records for the period. Deductions are negative, so consumption is the absolute value of the negative rows. Records without an `amount` are not usage.
</Step>
<Step title="Keep only usage categories">
Consumption includes workflow runs, agent chats, AI utilities, Company Brain, custom workflow development, and external MCP calls. `Credit Reset`, `Manual Adjustment`, `Credit Cap Adjustment`, and `Gifted Credits` are balance bookkeeping, not spend.
</Step>
<Step title="Group by correlation_id to match the UI's rows">
A drain delivers one record per charge, while the credit usage view in the UI shows one row per event with the charges summed. Grouping records by `correlation_id` reproduces those rows.
<Note>
`Custom Trigger Check` rows are the exception: their `correlation_id` is the owning agent rather than a single event, and the UI groups them per calendar day.
</Note>
</Step>
<Step title="Watch the boundaries">
Organization-scoped drains deliver only organization-scope rows, so per-member credit cap entries never double count your totals. Also note that no credit log data exists before **February 11, 2026** — a window that starts earlier will report less than the UI shows for the same range.
</Step>
</Steps>
<Tip>
A practical monitoring setup: use a Credit Logs drain as your cost table, and Workflow Runs, Agent Interactions, and Agents drains as the dimension tables you join to it on `run_id` / `interaction_id` = `correlation_id`. Treat the `credit_cost` fields on those records as a cross-check, never as the source of truth.
</Tip>
### Category and type labels
Drain records contain human-readable labels, not the internal values. The tables below describe what each value represents. The `category_filter` option on the API expects the internal value (for example `agent_run`).
<AccordionGroup>
<Accordion title="Categories" icon="tags">
| Internal value | Meaning |
| - | - |
| `pipeline_run` | Workflow Runs |
| `agent_run` | Agent Chats |
| `ai_utility` | AI Utilities |
| `company_brain` | Company Brain |
| `custom_node_rd` | Custom workflow development |
| `external_gumcp_call` | External MCP Call |
| `credit_limit_reset` | Credit Reset |
| `manual_adjustment` | Manual Adjustment |
| `permission_group_credit_cap_adjustment` | Credit Cap Adjustment |
| `checklist_item_completion` | Gifted Credits |
</Accordion>
<Accordion title="Types" icon="list">
| Internal value | Meaning |
| - | - |
| `initial_pipeline_run` | Initial Run |
| `ai_node_cost` | AI workflow step |
| `node_cost` | Workflow step cost |
| `step` | Chat Output |
| `compaction` | Chat Summarization |
| `compute_time` | Compute Time |
| `platform_fee` | Platform Fee |
| `image_generation` | Image Generation |
| `transcription` | Audio Transcription |
| `gumcp_tool_call` | guMCP Tool Call |
| `gumstack_tool_call` | Gumstack Tool Call |
| `bigquery_query` | Analytics Query |
| `custom_trigger_check` | Custom Trigger Check |
| `interactive_artifact_execute` | Interactive Artifact |
| `interaction_evaluation` | Chat Evaluation |
| `model_router` | Model Routing |
| `brain_indexing` | Brain Indexing |
| `brain_query` | Brain Search |
| `test_run` | Test Run |
| `external_client` | External Client |
</Accordion>
</AccordionGroup>
***
## Export scopes
Every export (one-time or drain) runs in one of two scopes:
| Scope | What it returns | Who can use it |
| - | - | - |
| **Organization** (default) | All data across selected teams and personal spaces in your organization | Organization admins with the Export Data permission |
| **Personal** | Only rows where you are the creator or runner | Any organization member with the Export Data permission |
### Organization scope
This is the default behavior. Organization-scoped exports let admins select specific teams, include personal spaces, and filter by entity IDs. All existing exports use this scope.
### Personal scope
Personal exports return only your own data: workflow runs you triggered, agents you created, and interactions from your sessions. This is useful for individual compliance requests or personal usage auditing.
**How it works:**
* The export filters rows by your user ID automatically. You do not need to select teams or workspaces.
* `start_date`, `end_date`, and `export_fields` are required.
* Team/workspace selection parameters (`workspace_ids`, `include_all_workspaces`) are ignored.
* Supported for **Workflow Runs**, **Agents**, **Agent Interactions**, and **Credit Logs**. Not supported for Audit Logs or Connector Activity exports.
**Via the API**, set `export_scope` to `"personal"` in your request body:
```json theme={"dark"}
{
"export_scope": "personal",
"data_type": "workflows",
"start_date": "2025-01-01T00:00:00",
"end_date": "2025-06-01T00:00:00",
"export_fields": ["run_id", "credit_cost", "pl_run_created_ts", "pl_run_finished_ts", "flowbook_name"]
}
```
<Info>
Personal exports require the **Enterprise** plan. The `export_scope` parameter defaults to `"organization"` when omitted, preserving backward compatibility.
</Info>
***
## API integration
For programmatic access to data export functionality, use the following endpoints. One-time exports are also available over the [Gumloop MCP server](/mcp-server/overview) through the `export_data` and `get_export_status` tools; data drains are REST-only.
<AccordionGroup>
<Accordion title="Create data export" icon="plus">
**Endpoint**: `POST /export_data`
**Request Body:**
```json theme={"dark"}
{
"user_id": "string",
"export_fields": [
"workbook_id",
"workbook_name",
"user_email",
"run_id",
"credit_cost",
"pl_run_created_ts",
"pl_run_finished_ts"
],
"start_date": "2024-01-01T00:00:00",
"end_date": "2024-12-31T23:59:59",
"include_personal_workspaces": false,
"workspace_ids": ["workspace_id_1", "workspace_id_2"],
"entity_ids": ["workbook_id_1", "workbook_id_2"]
}
```
**Optional Parameters:**
* `export_scope`: `"organization"` (default) or `"personal"`. Personal scope returns only your own data and requires the Enterprise plan.
* `data_type`: `"workflows"`, `"agents"`, `"agent_interactions"`, `"interaction_evaluations"`, `"credit_logs"`, or `"gumstack"`. Defaults to `"workflows"`. Audit-log exports are available through Data Export in Gumloop, not through this public endpoint.
* `entity_ids`: Filter the export to specific entities. For workflow exports, provide workbook IDs. For agent exports, provide agent IDs. Not applicable for credit log exports.
<Note>
**Credit log exports** work differently from workflow and agent exports:
* Team/workspace selection parameters (`workspace_ids`, `include_personal_workspaces`) are **not applicable**
* Credit-log exports do not use team/workspace selection. With `export_scope: "organization"`, they return organization-scope credit logs; with `export_scope: "personal"`, they return the requesting user's credit logs.
* Use `category_filter` to filter by a specific credit log category (e.g., `"PIPELINE_RUN"`, `"AGENT_RUN"`)
* Use `permission_group_filter` to filter credit logs by a specific [custom role](/enterprise-features/user_groups) (legacy parameter name retained for API compatibility)
</Note>
</Accordion>
<Accordion title="Check export status" icon="circle-check">
**Endpoint**: `GET /export_status`
**Query Parameters:**
* `user_id` (required): User requesting the status
* `data_export_id` (required): Export job identifier
* `download` (optional): Set to `true` to download the file if completed
</Accordion>
<Accordion title="List data drains" icon="list">
**Endpoint**: `GET /data-drains`
**Query Parameters:**
* `organization_id` (required): Your organization ID
**Response:** Returns an array of drain objects with their current status, configuration, and sync timestamps.
</Accordion>
<Accordion title="Create data drain" icon="plus">
**Endpoint**: `POST /data-drains`
**Request Body:**
```json theme={"dark"}
{
"name": "My Credit Logs Drain",
"drain_type": "custom_endpoint",
"data_type": "credit_logs",
"destination_config": {
"format": "json"
},
"export_fields": ["user_email", "timestamp", "category", "type", "name", "amount", "balance"],
"secret_id": "your_credential_secret_id",
"organization_id": "your_org_id"
}
```
**Required Parameters:**
* `organization_id`: Your organization ID
* `name`: A display name for the drain
* `drain_type`: `"custom_endpoint"`, `"s3"`, or `"datadog"`
* `data_type`: `"workflows"`, `"agents"`, `"agent_interactions"`, `"interaction_evaluations"`, `"credit_logs"`, `"audit_logs"`, or `"gumstack"`
* `destination_config`: Configuration object specific to the destination type
* `export_fields`: Array of field IDs to include in the synced data
**Optional Parameters:**
* `secret_id`: The credential secret ID for authenticating with the destination
* `project_ids`: Filter to specific team/workspace IDs
* `include_personal_workspaces`: Include personal workspaces in scope
* `entity_ids`: Filter to specific entity IDs
* `category_filter`: Filter credit logs by category
* `event_type_filter`: Filter audit logs by event type
* `start_ts`: ISO 8601 timestamp to start syncing from (defaults to current time)
<Note>
When creating a drain, Gumloop performs a **preflight check** to verify the destination is reachable. If the check fails, the drain will not be created and an error will be returned.
</Note>
</Accordion>
<Accordion title="Delete data drain" icon="trash">
**Endpoint**: `DELETE /data-drains/{drain_id}`
**Query Parameters:**
* `organization_id` (required): Your organization ID
</Accordion>
</AccordionGroup>
<Card title="Complete API documentation" icon="book" href="https://docs.gumloop.com/api-reference/organization/export-data">
View the full API reference for detailed endpoint specifications and examples
</Card>
## Related resources
<CardGroup>
<Card title="Audit logging" icon="shield" href="https://docs.gumloop.com/enterprise-features/audit_logging">
Learn about security and compliance audit logging
</Card>
<Card title="Custom roles" icon="users" href="https://docs.gumloop.com/enterprise-features/user_groups">
Learn about managing user permissions and roles
</Card>
<Card title="Organizations and teams" icon="building" href="https://docs.gumloop.com/core-concepts/teams">
Understand how to structure your Gumloop organization
</Card>
<Card title="Insights" icon="chart-pie" href="https://docs.gumloop.com/enterprise-features/organization_insights">
View organization-wide usage analytics and dashboards
</Card>
</CardGroup>
# Organization Insights
Source: https://docs.gumloop.com/enterprise-features/organization_insights
Dashboards and an analytics agent for adoption, credit spend, and outcomes across your organization
Insights is the reporting home for your organization. It combines **prebuilt dashboards** for adoption and credit spend with an **analytics agent** you can ask about that same usage data in plain language — both on the same page at [Settings > Organization > Insights](https://www.gumloop.com/settings/organization/insights).
<Frame>
<img alt="Insights Overview tab showing a credit usage digest, credit spend and volume chart, and top agents, models, and workflows" />
</Frame>
## At a glance
<CardGroup>
<Card title="Dashboards" icon="chart-line">
Ten tabs covering credits, agents, teams, models, skills, tasks, artifacts, connectors, Brain, and a free-form explorer
</Card>
<Card title="Analytics agent" icon="sparkles">
Ask questions in natural language and get tables, charts, and CSV exports — in the app or in Slack
</Card>
<Card title="Impact Reports" icon="envelope">
Schedule a weekly or monthly digest to email and Slack
</Card>
<Card title="Drill-downs" icon="magnifying-glass">
Click any agent, team, model, task, or connector to see the detail behind the number
</Card>
</CardGroup>
**Who can see it**: Insights is an Enterprise feature, open to members with the **Admin**, **Manager**, or **Analytics** [organization role](/core-concepts/organization_user_roles). See the [FAQ](#faq) for what each role can see and how to grant access.
### Where to start
<Steps>
<Step title="Set your date range">
Everything on the page — every KPI, chart, and table — follows the range in the toolbar. It defaults to the last 30 days.
</Step>
<Step title="Skim the overview">
Read the digest at the top for the headline number, then check the spend trend and the leaderboards for what drove it.
</Step>
<Step title="Drill into the tab that explains it">
Agents, Teams, and Models explain cost; Skills, Tasks, Artifacts, Connectors, and Brain explain adoption. Select any row to see the detail behind it.
</Step>
<Step title="Ask the agent anything the tabs don't answer">
Open the **Agent** rail for ad-hoc questions and exports, or use **Explorer** to slice usage yourself.
</Step>
<Step title="Put it on a schedule">
Set up an [Impact Report](#impact-reports) so the summary arrives in email or Slack instead of you checking the page.
</Step>
</Steps>
## Page anatomy
Every tab shares the same controls at the top of the page:
| Control | What it does |
| - | - |
| **Date range** | Sets the period for every metric on the page. Defaults to the last 30 days; other presets are Today, Last 7 days, Month to date, Last 3 months, and Last month, or pick a custom range. |
| **Impact Report** | Opens the scheduled digest settings for the organization. See [Impact Reports](#impact-reports). |
| **Agent** | Opens the analytics agent in a rail beside the dashboard. See [Ask the analytics agent](#ask-the-analytics-agent). |
| **Tabs** | Overview, Agents, Teams, Models, Skills, Tasks, Artifacts, Connectors, Brain, Explorer. |
<Frame>
<img alt="Insights header showing the tab bar, the credit digest, the Last 30 days date range, the Impact Report button, and the Agent button" />
</Frame>
<Tip>The tab, date range, and any selected agent or team live in the URL, so you can bookmark or share the exact view you are looking at.</Tip>
***
## The tabs
### Overview
The starting point: how much you spent, where it went, and who drove it.
* A plain-language digest of credits spent in the period, with the models that consumed most of it
* **Credit spend and volume** over time, with an optional **compare to previous period** toggle
* Leaderboards for **top agents**, **top models**, and **top workflows**
* A per-member table of agent tasks, workflow runs, credits, and each member's **Monthly Cap**
#### Monthly cap
If a member's [Custom Role](/enterprise-features/user_groups) sets a monthly credit cap, the member table shows how much of that cap they have used, as `used / cap`, with a bar that fills up and changes color as they approach the limit. Hover the cell to see which roles the cap came from.
* Members with no cap show a dash.
* When a member holds several capped roles, the [highest cap](/enterprise-features/user_groups#usage-limits-tab) applies.
* Unlike everything else on the page, these figures are **cycle-to-date**: they follow your organization's billing cycle and do not change when you change the date range. The column header shows the reset date.
<Frame>
<img alt="Organization Usage table listing members with agent tasks, credits per task, workflow runs, credits per workflow, and total credits" />
</Frame>
### Agents
Every agent in the organization with its usage and cost side by side — team, owner, model, tasks, credits, credits per task, how many members use it, and when it was last active. Search and filter to narrow the list.
<Frame>
<img alt="Insights Agents tab listing agents with team, owner, model, tasks, credits, credits per task, and last active" />
</Frame>
Select an agent to open its detail view: headline metrics, a usage and credit trend, and breakdowns of its tasks, triggers, models, and members.
<Frame>
<img alt="Insights agent detail view showing credits, tasks, credits per task, members, and a usage trend chart" />
</Frame>
### Teams
The same view one level up. Compare [teams](/core-concepts/teams) by members, agents, tasks, credits, and credits per task to see which parts of the org are getting value.
<Frame>
<img alt="Insights Teams tab listing teams with members, agents, tasks, credits per task, and credits" />
</Frame>
Select a team to drill into its agents, tasks, triggers, models, and members.
<Frame>
<img alt="Insights team detail view showing team credits, tasks, agents, members, and a usage trend" />
</Frame>
### Models
Where model spend actually goes: your top provider and model, the model mix over time, spend by model and by provider, a full model breakdown table, and a **cost calculator** for estimating the effect of switching models.
<Frame>
<img alt="Insights Models tab showing top provider and model, model mix over time, spend by model, and spend by provider" />
</Frame>
<Tip>Pair this with [AI Model Control](/enterprise-features/ai_model_control) when you want to steer the org toward cheaper models.</Tip>
### Skills
[Skill](/core-concepts/skills) adoption across the org: **skills used** (and total uses), **used by 2+ members**, **active members**, and **never used** — plus adoption over time, your **top builders**, and a searchable per-skill table with team, owner, how many members use it, activity, and last used.
<Frame>
<img alt="Insights Skills tab showing skills used, used by 2+ members, active members, never used, an adoption over time chart, top builders, and a skills table" />
</Frame>
### Tasks
What agents actually worked on. KPI cards for tasks, members, triggered tasks, and failure rate, a **where work happens** trend by channel, and a **source** ranking. Four views:
| View | Shows |
| - | - |
| **Triggers** | Every [trigger](/core-concepts/agent_triggers) with its type, agent, owner, status, tasks, and credits |
| **History** | Individual task runs |
| **Slack channels** | Task volume per Slack channel |
| **Slack apps** | [Slack apps](/core-concepts/custom_slack_app) deployed from your agents, who deployed them, and their task volume |
<Frame>
<img alt="Insights Tasks tab showing tasks, members, triggered share, failure rate, a where work happens chart, a source ranking, and a triggers table" />
</Frame>
<Tip>The **Source** ranking shows how work arrives — schedules, workflows, incoming Slack messages, incoming email, subagents, and the API — with failure rate per source.</Tip>
### Artifacts
[Artifacts](/core-concepts/agent_artifacts) agents produced: artifact count, creators, agents, and file types, with an artifacts-over-time trend and a file-type ranking (web pages, PNG, plain text, JSON, CSV, and more). Switch between **artifacts**, **members**, and **agents** views.
<Frame>
<img alt="Insights Artifacts tab showing artifacts, members, agents, file types, an artifacts over time chart, a file type ranking, and an artifacts table" />
</Frame>
### Connectors
Which [connectors](/core-concepts/credentials) are actually in use — members connected, active members, an activity trend, and last used per connector. Select a connector to see the members who connected it and the agents using it.
<Frame>
<img alt="Insights Connectors tab listing Slack, Gong, Google BigQuery, GitHub, Gmail and others with members, active members, activity, and last used" />
</Frame>
### Brain
How your organization uses [Company Brain](/core-concepts/brain): whether people and agents are actually searching it, and what the knowledge sources cost to keep in sync.
KPI tiles cover **Searches**, **Agents Using Brain**, **Members Using Brain**, and **Total Credits** (split into sync and search credits underneath).
| Section | What it shows |
| - | - |
| **Adoption Over Time** | Searches and the agents and members doing them, across the selected range |
| **Credits Over Time** | Brain credit spend across the same range |
| **Connections** | Searches by source type, and the individual sources behind each type |
| **Top Agents** / **Top Members** | Who searches Brain the most |
| **Sources** table | Every source the org, its teams, and its members have connected, with **Type**, **Scope**, **Docs**, **Sync Credits**, and **Searches** |
Select a source to open its detail panel, which has two tabs: **Sync History** (how the source has been indexed over time and what it cost) and **Usage** (its searches, and the agents and members searching it).
<Note>
Search credits are reported for the organization as a whole, not per source: a single search can draw on several sources at once, so its cost is not attributed to one of them. Sync credits are per source.
</Note>
### Explorer
Free-form slicing when no tab answers your question. Choose what to **group by**, then expand a row to drill one level deeper. Each row shows its share of credit spend.
| Group by | Expand a row to see |
| - | - |
| **Agents** | The members running tasks on each agent |
| **Members** | The agents each member uses |
| **Workflows** | The members running each workflow |
| **Models** | The agents using each model |
| **Connectors** | The members who have connected each connector |
<Frame>
<img alt="Insights Explorer tab grouped by agents, showing credit share per agent with expandable rows" />
</Frame>
***
## Ask the analytics agent
Click **Agent** to open the analytics agent next to your dashboard. Ask a question in natural language, or start from a suggested prompt:
<Frame>
<img alt="Impact Report and Agent buttons in the Insights toolbar, with a cursor clicking Agent" />
</Frame>
* **Who are my top 3 most active members this week?**
* **What are the most used agents this week?**
* **What are the most used MCP servers this week?**
The agent queries your organization's data and answers with tables, charts, or CSV exports. Generated files open in a new tab.
<Frame>
<img alt="Analytics agent answering who are my top 3 most active members this week with a table of workflow runs and agent chats per member" />
</Frame>
**In the rail you can**:
* Expand the rail for a wider chat, or collapse it to get the full dashboard back
* Start a new chat, or reopen a previous one from the chat history popover
* Turn on **incognito** for a chat that is not saved to history (Enterprise plans; an admin can disable it for the organization)
* On mobile, the agent opens as a full-screen chat instead of a rail
<Info>Chat history follows your access to Insights. If the analytics role is removed from a member, they also lose access to their past analytics conversations.</Info>
### In Slack
The same agent is available in [Slack](/core-concepts/agents_slack), so you can ask questions where your team already works.
<Steps>
<Step title="Add the Gumloop bot to your channel">
Invite the Gumloop bot to the Slack channel where you want to use analytics.
</Step>
<Step title="Enable the analytics agent">
Type `/gummie add analytics` in the channel to activate the analytics agent.
<Frame>
<img alt="Running /gummie add analytics in Slack" />
</Frame>
</Step>
<Step title="Ask your questions">
Mention **@Gumloop** and ask your question. The agent replies in the thread.
<Frame>
<img alt="Analytics agent responding to a query in Slack" />
</Frame>
</Step>
</Steps>
### What you can ask about
| Data | What it covers |
| - | - |
| **Workflow runs** | Run history, credit costs, execution counts, completion timestamps |
| **Agent chats** | Chat sessions with agents, credit costs per chat, chat volume over time |
| **Agents** | Agent names, descriptions, models used, tools configured, creator info |
| **Workflows** | Workflow names, descriptions, creator info |
| **Members** | Member emails and activity across your organization |
| **MCP servers** | MCP server usage across your organization |
| **Triggers** | Trigger configurations, types (scheduled, email, Slack, webhooks, polling), status |
| **Skills** | Skill names, descriptions, usage counts, which agents have them attached |
| **Skill usage** | Per-event skill usage log with timestamps, actions (view, use, edit), and which agent or member triggered it |
| **Files** | Files produced by agents, filenames, scopes, creation timestamps |
| **Evaluations** | Chat quality evaluations: grade, sentiment, goal completion, and per-agent breakdowns |
| **Evaluation settings** | Which agents have evaluations enabled, plus model, frequency, and language |
| **Knowledge sources** | Connected Company Brain sources: type, status, and scope (personal, team, organization) |
| **Credits** | Authoritative credit-spend ledger by category, member, team, and model charged |
### Example questions
<Tabs>
<Tab title="Credits & usage">
```text theme={"dark"}
How many credits has our organization used in the last 30 days?
Break it down by member.
```
```text theme={"dark"}
Show me daily credit consumption for the past 3 months as a chart.
```
```text theme={"dark"}
Break down credit spend by category for the last 30 days.
```
```text theme={"dark"}
Which members have been most active in the last 7 days?
Show their workflow runs and agent chats separately.
```
</Tab>
<Tab title="Agents & workflows">
```text theme={"dark"}
What are our top 10 most-run workflows this month? Show credit cost for each.
```
```text theme={"dark"}
How many agent chats happened last week? Which agents are most popular?
```
```text theme={"dark"}
What are the most used MCP servers this week?
```
</Tab>
<Tab title="Triggers">
```text theme={"dark"}
How many active triggers do we have? Break them down by type.
```
```text theme={"dark"}
Which triggers fire most frequently this month?
```
```text theme={"dark"}
Show me all Slack-based triggers and which agents they belong to.
```
</Tab>
<Tab title="Skills">
```text theme={"dark"}
What are our most-used skills in the last 30 days?
```
```text theme={"dark"}
Which agents have the most skills attached?
```
```text theme={"dark"}
Show me skill usage trends over the past month, grouped by action type.
```
</Tab>
<Tab title="Files">
```text theme={"dark"}
How many files were created by agents this week?
```
```text theme={"dark"}
Which agents produce the most files? Show the top 5.
```
```text theme={"dark"}
Show me file creation volume per day for the last 30 days.
```
</Tab>
<Tab title="Evaluations">
```text theme={"dark"}
How many agent chats were graded needs review or needs attention in the last 30 days?
```
```text theme={"dark"}
Which agents have the lowest evaluation success rate this month?
```
```text theme={"dark"}
How many agents have evaluations enabled? Break it down by model.
```
</Tab>
<Tab title="Knowledge sources">
```text theme={"dark"}
How many knowledge sources are connected across the organization?
```
```text theme={"dark"}
Break down our knowledge sources by type and status.
```
```text theme={"dark"}
Which knowledge sources are currently in an error state?
```
</Tab>
</Tabs>
***
## Impact Reports
Rather than checking the dashboard, have it delivered. Click **Impact Report** in the Insights toolbar to schedule a recurring summary of your organization's agent activity.
| Setting | Options |
| - | - |
| **Cadence** | Weekly or monthly |
| **Email** | Any number of recipient addresses |
| **Slack** | Channels, plus direct messages to specific members |
| **Send me a test** | Sends the report to you immediately so you can preview it |
Only Slack channels the Gumloop bot has joined can be selected. Use **Disable report** in the same panel to stop delivery.
Reports cover the most recently completed period (weeks and months close in UTC) and go out after it closes — emails arrive at 10:00 in each recipient's local time where that is known. Each report's numbers are snapshotted when it is generated, so a retry delivers the same figures.
<Frame>
<img alt="Impact Report panel with weekly frequency, email recipients, and Slack channels or members, plus a Disable report button" />
</Frame>
<Info>
Anyone who can open Insights can view the report settings; **Admins**, **Managers**, and the **Analytics** role can
enable, edit, and test-send it. The written summary in each report is generated by an AI model and is billed to your
organization as AI utility credits.
</Info>
## Per-agent Insights
Every [agent](/core-concepts/agents) has its own Insights view at **Agent > Insights**, for owners who only care about their own agent. It uses the same date range picker and shows:
* Headline KPIs and a credit spend and volume chart, with the previous period for comparison
* Breakdowns by task source, skill, artifact type, Slack channel, member, and model
* Its own Impact Report schedule, independent of the organization-wide one
## FAQ
<AccordionGroup>
<Accordion title="Who can see the Insights page?">
Access comes from the [organization role](/core-concepts/organization_user_roles) a member holds, assigned under
[Settings > Organization > Members](https://www.gumloop.com/settings/organization/members). **Admin**, **Manager**,
and the **Analytics** role can open Insights. **Member**, **Security**, and **Developer** cannot — the page is not in
their navigation.
Roles are additive, so if someone needs reporting and nothing else, add **Analytics** to their existing Member role
rather than promoting them to Manager.
</Accordion>
<Accordion title="Do I need Enterprise?">
Yes. Insights and Impact Reports are Enterprise features — on other plans the analytics roles cannot grant access to
them.
</Accordion>
<Accordion title="Whose data does each person see?">
Everyone who can open Insights sees the same organization-wide dashboards — the tabs are not filtered per person.
The analytics agent is different: it answers across the whole organization only for **Admins**. For a **Manager** or
the **Analytics** role, the agent answers about that person's own activity, because the scope is applied when the
query is built rather than filtered afterwards. Use the dashboards and Explorer for organization-wide numbers.
</Accordion>
<Accordion title="Who can set up an Impact Report?">
**Admin**, **Manager**, and the **Analytics** role can enable, edit, and test-send the organization's Impact Report.
Anyone who can open Insights can see the current settings.
</Accordion>
<Accordion title="How fresh are the numbers?">
Completed days come from a rollup that refreshes hourly, and today's activity is read live, so the current day is
always current. Recent closed days are recomputed for a few days afterwards to pick up late-arriving records, so a
yesterday figure can still move slightly.
Days are counted in **UTC** — for both the dashboards and the periods Impact Reports cover — so an Insights "day"
may not line up with your local day.
</Accordion>
<Accordion title="Does using Insights cost credits?">
Browsing the dashboards costs nothing. Questions you ask the analytics agent are charged on the amount of data the
query scans, and the written summary in each Impact Report is billed as AI utility credits. See
[Credits](/core-concepts/credits) for how spend is tracked.
The agent keeps its own cost low by aggregating instead of returning raw rows and, when your question doesn't name a
period, limiting time-series tables to the last 90 days. To look further back, state the date range in your question
— that default applies only to the agent, never to the dashboards, whose range you set in the toolbar.
</Accordion>
<Accordion title="Can the agent reach data it shouldn't?">
Every query is scoped to your organization and built against a fixed set of analytics tables and columns — there is
no arbitrary SQL, values are passed as query parameters rather than pasted into the SQL text, and the organization
and user filters are part of the query itself. Asking the agent to ignore those rules, or to role-play around them,
does not change what it can read.
</Accordion>
</AccordionGroup>
## Related resources
<CardGroup>
<Card title="Usage data export" icon="file-export" href="/enterprise-features/organization_data_export">
Export raw usage data as CSV for external analysis
</Card>
<Card title="AI model control" icon="sliders" href="/enterprise-features/ai_model_control">
Manage which AI models are available in your organization
</Card>
<Card title="Custom roles" icon="user-shield" href="/enterprise-features/user_groups">
Configure granular permissions and access controls
</Card>
<Card title="Audit logging" icon="clipboard-list" href="/enterprise-features/audit_logging">
Track user actions and system events for compliance
</Card>
</CardGroup>
# Outbound webhooks
Source: https://docs.gumloop.com/enterprise-features/organization_webhooks
Get notified at your own endpoint when someone joins your organization
Outbound webhooks let Gumloop notify **your** systems when something happens in your organization. Instead of polling an export, you register an HTTPS endpoint and Gumloop posts a signed JSON payload to it as events occur.
Outbound webhooks require an Enterprise subscription and permission to export organization data. Find them under **Settings → Organization → [Data Export](https://www.gumloop.com/settings/organization/data_export) → Webhooks**. The **Webhooks** tab is available to organization Admin, Manager, and Analytics roles, subject to your organization's access policies. Personal-export permission alone does not provide webhook access.
<Frame>
<img alt="Webhooks tab on the Data Export page listing endpoint, events, status, and created columns" />
</Frame>
The table lists each webhook's **Endpoint**, the **Events** it subscribes to, its **Status**, when it was **Created**, and per-row actions. Search and paging help once you have a few.
## Add a webhook
<Frame>
<img alt="Add Webhook dialog with endpoint URL, description, events, signing secret, and authorization header fields" />
</Frame>
<Steps>
<Step title="Enter the endpoint URL">
Must be **HTTPS**. This is where Gumloop POSTs each event. The URL must be public, must not embed credentials, and must accept a test event with a `2xx` response.
</Step>
<Step title="Describe it (optional)">
A note for your teammates, such as *Posts to our internal provisioning service*.
</Step>
<Step title="Pick at least one event">
Select **Member joined** (`organization.member.joined`), currently the only event. See [Member joined](#member-joined) for when it fires and what it contains.
</Step>
<Step title="Copy the signing secret">
Gumloop generates a secret starting with `whsec_`. Copy it before saving or closing the dialog. It is shown during creation and replacement, but is not available in the Edit dialog afterward. If you lose it, use **Replace credentials** to generate a new one.
</Step>
<Step title="Add an authorization header (optional)">
Only use this field if your endpoint requires a bearer token. Enter the token alone, without `Bearer `. Gumloop adds the prefix and sends `Authorization: Bearer <your-token>` on each delivery.
</Step>
<Step title="Save">
Gumloop sends a **test event** (`webhook.ping`) first and only saves the webhook if your endpoint accepts it. If saving fails, check the validation message as well as endpoint reachability and the test response.
</Step>
</Steps>
## Member joined
**Member joined** (`organization.member.joined`) reports a newly established organization membership. Gumloop sends it once, when the person becomes a member, whichever way they joined.
Common uses:
* Provision the new member in internal tools, ticketing, or HR systems.
* Post a welcome message or start an onboarding sequence.
* Keep an external directory or billing system in sync with your Gumloop seats.
### When it fires
The `membership.join_method` field in the payload tells you how the person joined:
| `join_method` | The person joined by |
| - | - |
| `invite` | Accepting an organization or team invitation |
| `domain` | Signing in with your company email domain while domain auto-join is enabled |
| `scim` | Being provisioned by your identity provider through [SCIM](/enterprise-features/sso_saml_oidc_scim) |
| `role_request` | Having their request for an organization role approved |
| `admin` | Being added as an admin by Gumloop when your enterprise account was set up |
<Note>
Sending an invitation alone does not trigger the event; it fires when the invitation is accepted. Changing the roles or teams of an existing member does not trigger a second joined event.
</Note>
### Payload
```json Example theme={"dark"}
{
"id": "Xk2pQ7mLn3R9tVbW4cYzHd",
"type": "organization.member.joined",
"timestamp": "2026-09-10T17:04:12.381920+00:00",
"api_version": "2026-09-10",
"data": {
"organization": { "id": "Ab3dEf6hJk9mNp2qRs5tUv", "name": "Acme" },
"user": {
"id": "Wx8yZa1bCd4eFg7hJk0mNp",
"email": "ada@acme.com",
"first_name": "Ada",
"last_name": "Lovelace"
},
"membership": {
"join_method": "invite",
"roles": ["member"],
"projects": [{ "id": "Qr3sTu6vWx9yZa2bCd5eFg", "name": "Marketing" }]
},
"actor": { "email": "admin@acme.com" }
}
}
```
IDs above are illustrative. The `data` object contains:
<ResponseField name="organization" type="object">
The organization the person joined: `id` and `name`.
</ResponseField>
<ResponseField name="user" type="object">
The new member: `id`, `email`, `first_name`, and `last_name`. Names can be `null` when unavailable.
</ResponseField>
<ResponseField name="membership" type="object">
<Expandable title="properties">
<ResponseField name="join_method" type="string">
How the person joined. One of `invite`, `domain`, `scim`, `role_request`, or `admin`.
</ResponseField>
<ResponseField name="roles" type="string[]">
Organization roles granted on joining. Always includes `member`.
</ResponseField>
<ResponseField name="projects" type="object[]">
[Teams](/core-concepts/teams) the person was added to, each with `id` and `name`. Can be an empty array.
</ResponseField>
</Expandable>
</ResponseField>
<ResponseField name="actor" type="object">
The user who added or invited the member, as an object with `email`. Omitted when no acting user can be resolved.
</ResponseField>
## What a delivery looks like
Each delivery is an HTTP `POST` with a JSON body and these headers:
| Header | Value |
| - | - |
| `Content-Type` | `application/json` |
| `User-Agent` | Identifies Gumloop as the sender |
| `webhook-id` | Event ID, also present as `id` in the JSON body. Retries of the same event retain this ID. |
| `webhook-timestamp` | Unix timestamp of this attempt |
| `webhook-signature` | Present when the webhook has a signing secret |
| `Authorization` | Present only if you configured one |
Make your receiver idempotent: record successfully handled event IDs and do not repeat their side effects when the same event is delivered again. A retry retains the event ID and body, but its `webhook-timestamp` and signature are generated for that attempt.
Each JSON body contains:
* `id`: the event ID, matching `webhook-id`.
* `type`: `organization.member.joined`, or `webhook.ping` for a test.
* `timestamp`: when the event envelope was created, as an ISO 8601 UTC timestamp.
* `api_version`: currently `2026-09-10`.
* `data`: the event-specific payload. For `organization.member.joined`, see [Payload](#payload).
A `webhook.ping` uses the same envelope, with `data: {"organization": {"id": "<organization-id>"}}`. Your receiver must accept this test event as well as member-joined events.
Return any `2xx` status as soon as you have accepted the payload. Do the slow work asynchronously.
## Verify the signature
Gumloop follows the [Standard Webhooks](https://www.standardwebhooks.com/) scheme. Remove the `whsec_` prefix from your signing secret and **base64-decode** the remaining value to obtain the HMAC key bytes. Compute HMAC-SHA256 over `<webhook-id>.<webhook-timestamp>.<raw request body>`, base64-encode the digest, and compare it in constant time with the `v1` signature in `webhook-signature`.
```python Python theme={"dark"}
import base64
import hashlib
import hmac
import time
def verify(secret: str, headers: dict, raw_body: bytes) -> bool:
try:
timestamp = int(headers["webhook-timestamp"])
if abs(time.time() - timestamp) > 300:
return False
signed = f"{headers['webhook-id']}.{headers['webhook-timestamp']}.".encode() + raw_body
key = base64.b64decode(secret.removeprefix("whsec_"), validate=True)
expected = base64.b64encode(hmac.new(key, signed, hashlib.sha256).digest()).decode()
received = headers["webhook-signature"].split(",", 1)[1]
return hmac.compare_digest(expected, received)
except (KeyError, ValueError, IndexError):
return False
```
Use the **raw** request body, byte for byte — re-serializing the JSON changes the signature. Signature validity alone does not prevent replay. Enforce a timestamp tolerance in your receiver, for example reject requests more than five minutes in the past or future, and deduplicate already processed event IDs. The five-minute tolerance is a receiver policy, not a Gumloop delivery deadline.
<Warning>
Anyone with the signing secret can forge deliveries that look like Gumloop. Treat it like an API key, and rotate it if it leaks.
</Warning>
## Delivery failures and retries
Gumloop uses a 10-second HTTP timeout and does not follow redirects.
For queued event deliveries, a network error or non-`2xx` response normally triggers up to three retries, after delays of 30, 120, and 480 seconds — up to four attempts including the initial request.
`410 Gone` is permanent: Gumloop marks the delivery failed and changes the endpoint to **Error** immediately. An endpoint also enters **Error** after 10 consecutive failed attempts. An endpoint that is **Paused** or **Error** does not receive queued deliveries.
After fixing the receiver, use **Resume** to reactivate the endpoint. Resuming does not replay deliveries already marked failed.
The test performed while creating a webhook or changing its destination or credentials must succeed before the change is saved. These preflight tests are separate from queued-event retries.
## Manage a webhook
| Action | What it does |
| - | - |
| **Edit** | Change the endpoint, description, or subscribed events. |
| **Replace credentials** | Generates a new signing secret and replaces the optional bearer token. Install the new signing secret at your receiver before clicking **Replace** so the test event can succeed. Re-enter the bearer token if it is still required; leaving it blank removes it from the replacement credentials. The endpoint ID and delivery history are retained. |
| **Pause / resume** | Stop deliveries without deleting the configuration. The **Status** column shows the current state. |
| **Send test event** | Send a `webhook.ping` to check the current endpoint and credentials. |
| **Delivery history** | Review recent attempts and their responses when debugging. Click the row. |
| **Delete** | Remove the webhook permanently. |
## Troubleshooting
<AccordionGroup>
<Accordion title="Gumloop will not save my webhook">
Check the validation message as well as endpoint reachability and the test response. The URL must be public HTTPS, must not embed credentials, and the endpoint must accept the test event with a `2xx` response. If your endpoint sits behind an allowlist, see [Static Egress IPs](/enterprise-features/static_egress_ips).
</Accordion>
<Accordion title="Signature verification fails">
Decode the secret after the `whsec_` prefix. Verify against the raw bytes you received, include the `webhook-id` and `webhook-timestamp` in the signed string, and compare the `v1` signature in constant time.
</Accordion>
<Accordion title="I need a different event">
Only the events listed in the Add Webhook dialog are available. For broader data, use [Usage Data Export](/enterprise-features/organization_data_export) exports or drains.
</Accordion>
</AccordionGroup>
## Related
<CardGroup>
<Card title="Usage data export" icon="file-export" href="/enterprise-features/organization_data_export">
One-time exports and continuous drains.
</Card>
<Card title="Audit logging" icon="file-shield" href="/enterprise-features/audit_logging">
A full record of activity in your organization.
</Card>
</CardGroup>
# Proxied MCPs
Source: https://docs.gumloop.com/enterprise-features/proxied_mcps
Connect external MCP servers through a managed proxy for centralized monitoring, access control, and security.
Proxied MCPs let you connect existing, external MCP servers to Gumloop through a managed proxy. Instead of deploying your own code, you point Gumloop at a third-party MCP server URL and get full observability, tool access control, and security, all without changing anything on the remote server.
<Frame>
<img alt="Proxied MCP server detail page for Granola showing overview stats, MCP Server URL, Routing Status, and recent activity" />
</Frame>
## Where to find it
Go to **Settings → Organization → Proxied MCPs** at
[gumloop.com/settings/organization/proxied-mcps](https://gumloop.com/settings/organization/proxied-mcps).
<Info>
Proxied MCPs is available on the **Pro** and **Enterprise** plans. Contact
your organization admin if you don't see it under **Settings → Organization**.
</Info>
## Hosted vs. proxied
Not sure which one to use? Here's a quick comparison:
| | Hosted MCPs | Proxied MCPs |
| - | - | - |
| **You deploy code?** | Yes, from a GitHub repo | No, just provide a URL |
| **Where does the server run?** | On Gumloop's infrastructure | On the third party's infrastructure |
| **Deployment management** | Full CI/CD with GitHub integration | Not applicable |
| **Monitoring (pods, logs)** | Yes | No |
| **Activity tracking** | Yes | Yes |
| **Tool access control** | Yes | Yes |
| **Best for** | Custom internal tools | Third-party MCP servers (Granola, Notion, etc.) |
Use **[Hosted MCPs](/enterprise-features/hosted_mcps)** when you want to build and deploy your own MCP server. Use **Proxied MCPs** when you want to connect an existing third-party server.
<Tip>
Connecting a server that isn't reachable from the internet? Use a
**[managed tunnel](/enterprise-features/managed_tunnels)**. It brings MCP
servers running inside your network to Gumloop without opening inbound ports,
and each one shows up here as a proxied server.
</Tip>
## Server list
The main Proxied MCPs page shows a table of all connected external servers. Each row displays:
* **Server name** with the remote URL (credentials automatically redacted for security)
* **Auth method**: None, API Key, or OAuth 2.0
* **Tool count**: How many tools were discovered on the server
* **Last Updated** timestamp
Use the search bar to filter by name or URL. Click **Connect** to add a new server.
## Connecting a new proxied MCP
Click the **Connect** button to launch a multi-step wizard that connects an external MCP server through the proxy.
### Step 1: Enter the server URL
<Frame>
<img alt="Connect wizard step 1 showing an input field for the MCP Server URL with a placeholder example" />
</Frame>
Enter the URL of the MCP server you want to connect to. This should be the server's MCP endpoint (e.g., `https://mcp.example.com/mcp`).
Click **Next** to proceed. Gumloop will probe the server to detect its capabilities and authentication requirements.
### Step 2: Configure connection
<Frame>
<img alt="Connect wizard step 2 showing Server Configuration with detected auth type, server name, authentication method selection, and credential fields" />
</Frame>
On this step, you configure:
* **Server Name**: A display name for this server in your organization
* **Detected Auth**: Gumloop automatically detects the server's auth requirements and shows it here
* **Authentication**: Choose the method that matches what the server expects:
* **No Authentication**: No credentials required
* **API Key / Credentials**: Provide headers or tokens. Define credential fields that become headers sent with every request.
* **OAuth 2.0**: If the server supports OAuth, users authenticate via an OAuth flow
* **UI / Raw toggle**: Switch between a form-based UI and raw JSON configuration (using the standard `mcpServers` config format)
<Tip>
If you have an existing MCP server config in JSON format (like you'd use in
Claude Desktop or Cursor), switch to **Raw** mode and paste it directly.
</Tip>
Click **Create Server** (or **Next** if OAuth is detected) to proceed.
### Step 3: Discover & activate
After creating the server connection, Gumloop connects to the remote server, discovers available tools and resources, and activates the proxy. For servers using API Key auth, you'll add your credentials at this step. For OAuth servers, you'll complete the OAuth authentication flow.
Once discovery completes, you'll see a summary of discovered tools and the server will be active.
## Server detail page
Every proxied MCP has a detail page with four tabs. Since Gumloop doesn't host the server, there are no Deployments or Monitoring tabs.
### Overview
The overview tab shows a snapshot of the server's last 7 days:
* **Total Calls**: Number of tool calls routed through the proxy
* **Unique Users**: How many distinct users made calls
* **Error Rate**: Percentage of calls that failed
* **Avg Latency**: Average response time
* **MCP Server URL**: The Gumloop proxy URL that clients should connect to
* **Routing Status**: Shows whether the remote server is reachable and accepting connections (displays "Live" when healthy)
* **Recent Activity**: A table of the most recent tool calls
The **Fetch New Tools** button in the header re-discovers tools from the remote server. Use this when the external server has added new tools or changed its capabilities.
### Tools
<Frame>
<img alt="Tools tab for a proxied MCP showing a custom-role matrix with tools listed and access toggles per role" />
</Frame>
The Tools tab works the same as for hosted MCPs. You get a custom-role matrix where you can:
* See every discovered tool with its description and usage count
* Toggle access per [custom role](/enterprise-features/user_groups)
* Disable the entire server for a specific role
### Activity
<Frame>
<img alt="Activity tab for a proxied MCP showing usage stats, a 24-hour activity histogram, and a table of recent tool calls" />
</Frame>
The Activity tab shows a server-scoped activity view with:
* **Usage summary**: Total Calls, Unique Users, Error Rate, and Avg Latency for the period
* **Activity histogram**: 24-hour tool call volume with latency color coding (P25/P85-95/P95+)
* **Activity table**: Every tool call with Tool, Time, User, Source, Latency, and Status columns
* **Filters**: Same filtering options as the global [Connector Activity](/enterprise-features/app_activity) page
* **Export**: Download the filtered data as CSV
### Settings
<Frame>
<img alt="Settings tab for a proxied MCP showing Server Name, Description, MCP Server URL, Authentication Method (OAuth 2.0), and Disable/Delete actions" />
</Frame>
The Settings tab lets you manage:
* **Server Name**: Update the display name
* **Description**: Describe what the server does
* **MCP Server URL**: The proxy URL for MCP clients to connect to
* **Authentication Method**: Shows the configured auth type (set during creation)
* **Access Gate**: The credential for a gate in front of the server, such as Cloudflare Access (see [Access Gates](#access-gates))
* **Disable Server**: Temporarily disable the server. It can be re-enabled later.
* **Delete Server**: Permanently remove the server and all associated configuration
<Warning>
Deleting a proxied MCP server is permanent. All activity history, tool access
settings, and the proxy configuration will be removed. The external server
itself is not affected.
</Warning>
## Access gates
Some MCP servers don't sit on the open internet — they sit behind a gate the customer owns, such as Cloudflare Access or an API gateway. The gate answers before the MCP server does, so without a credential for it Gumloop never reaches the origin at all.
An **Access Gate** stores that credential once. Gumloop sends it on every request to the server, so the gate lets the traffic through. It never replaces the server's own authentication.
### Configuring a gate
Open the server's **Settings** tab and configure **Access Gate**, then pick your provider and fill in its fields:
| Provider | Fields |
| - | - |
| **Cloudflare Access** | Access Client ID, Access Client Secret |
| **AWS API Gateway** | API Key |
| **Azure API Management** | Subscription Key |
Gumloop also detects gates while you connect a server: if the URL you enter is behind a recognized gate, the wizard asks for the gate's credentials instead of guessing at the server's auth method, then discovers tools once it can get through.
<Note>
Gate credentials are **write-only**. Once saved they are never returned by the
interface or the API — you can see which provider is configured and replace or
remove the credential, but not read it back.
</Note>
### Two layers, two purposes
| | Access Gate | Server authentication |
| - | - | - |
| **Protects** | The network path in front of the server | The MCP server itself |
| **Owned by** | You (your Cloudflare, AWS, or Azure account) | The MCP server |
| **Configured as** | One credential for the whole server | None, API Key / Credentials, or OAuth 2.0 |
| **Per user?** | No — shared by every request to the server | Can be per user (OAuth, personal API keys) |
If a gate rejects Gumloop's credential, tool calls fail with an error naming the gate — for example, "Its Cloudflare Access gate rejected our credentials" — so you can tell a gate problem apart from a server problem.
<Warning>
Access Gates are for gates **you** own on a publicly reachable URL. Servers
connected through a **[managed tunnel](/enterprise-features/managed_tunnels)**
already sit behind a gate Gumloop manages, and curated connectors are managed
by Gumloop, so neither exposes this setting.
</Warning>
<Info>Only the person who connected the server, or an organization admin for external servers, can configure its Access Gate.</Info>
## URL security
When displaying proxied server URLs in the interface, Gumloop automatically **redacts credentials** embedded in URLs. If a server URL contains authentication tokens or API keys, they are masked in the UI to prevent accidental exposure.
### Allowlisting Gumloop
Gumloop connects from a fixed set of URLs and IP addresses. Servers or OAuth providers that restrict inbound traffic or redirect URLs should permit the following:
* **OAuth redirect URLs**:
* `https://api.gumloop.com/auth/callback`
* `https://api.gumstack.com/auth/callback`
* **Source IPs**: Gumloop's [static egress IPs](/enterprise-features/static_egress_ips)
## OAuth compatibility
Gumloop implements the [MCP authorization spec](https://modelcontextprotocol.io/specification/2025-06-18/basic/authorization). For OAuth servers, it discovers the authorization-server metadata and registers as a client automatically through **Dynamic Client Registration (DCR)** or a **Client ID Metadata Document (CIMD)**. Manually pre-registered (static) client IDs are not used.
## Token lifetimes
OAuth servers issue two types of tokens:
* **Access token**: a short-lived credential sent with each request, typically valid for about an hour.
* **Refresh token**: a long-lived credential used to obtain new access tokens, typically valid for weeks to months. Google's, for example, are valid for roughly six months.
Gumloop refreshes an access token when the connection is next used: if the access token has expired, it uses the refresh token to obtain a new one before making the request. Refreshes are not performed on a background schedule, so a connection that is not used is not refreshed in the meantime.
As a result, the refresh token's lifetime determines how long a connection can stay idle before it must be re-authenticated. If a connection goes unused for longer than the refresh token's lifetime, the refresh token expires before it can be used, and the user is prompted to reconnect. Short refresh-token lifetimes (for example, one day) are a common cause of unexpected reconnects, because a normal gap in activity can outlast the token.
## FAQ
<AccordionGroup>
<Accordion title="Does the external server need to know about Gumloop?">
No. The external server receives standard MCP requests from the Gumloop
proxy. It doesn't need any special configuration or awareness of Gumloop.
</Accordion>
<Accordion title="What happens if the external server goes down?">
Tool calls routed through the proxy will fail, and the **Routing Status** on
the overview page will reflect the connection issue. Activity logs will show
errors for the affected period. The proxy continues to check connectivity
and will resume routing when the server comes back.
</Accordion>
<Accordion title="Can I change the authentication method after creation?">
The authentication method is configured during server creation and cannot be
changed afterward. If you need a different auth method, delete the server
and create a new connection with the correct settings.
</Accordion>
<Accordion title="How do I update tools when the external server changes?">
Click the **Fetch New Tools** button in the server header. Gumloop will
re-discover tools from the remote server and update the tool list. Any new
tools will be enabled for all custom roles by default.
</Accordion>
<Accordion title="What MCP transports are supported?">
Proxied MCPs support MCP servers that expose an HTTP-based endpoint
(Streamable HTTP or SSE). The URL you provide should be the server's MCP
transport endpoint.
</Accordion>
<Accordion title="Why are a server's tools sometimes unavailable in an agent?">
When an agent conversation starts, Gumloop connects to the agent's MCP
servers and loads their tools within a time limit, so the agent can respond
promptly. A server that is slow to respond may not finish connecting within
that window and is skipped for that turn, leaving its tools temporarily
unavailable.
</Accordion>
</AccordionGroup>
# Organization service accounts for Slack agents
Source: https://docs.gumloop.com/enterprise-features/slack_agent_access
Normally, anyone who messages a Gumloop agent in Slack needs their own Gumloop account, because the agent runs on that person's credentials. This feature lets an organization lift that requirement for specific agents: people in a Slack workspace you have registered can message those agents with **no Gumloop account at all**, and their requests run on a shared **organization service account** instead of a personal one.
<Note>
**Enterprise plan required.** Registering Slack workspaces and creating a service account both require the **Admin** or **Security** organization role.
</Note>
## When to use it
<CardGroup>
<Card title="Company-wide helpdesk agents" icon="headset">
An IT or HR agent that everyone in your Slack workspace should be able to ask questions, even the majority of employees who never log in to Gumloop.
</Card>
<Card title="Broad rollout without seats" icon="users">
You want Slack-first adoption across hundreds of people without provisioning a Gumloop account for each of them first.
</Card>
<Card title="One consistent identity" icon="id-badge">
Every request should hit the same connected accounts and produce the same behavior regardless of who asked, instead of depending on each person's own connectors.
</Card>
<Card title="Not for personal data" icon="triangle-exclamation">
Because everyone shares one identity, this is the wrong choice for agents that read the asker's own mailbox, calendar, or files. Leave those on personal credentials.
</Card>
</CardGroup>
## How it works
Three things must line up before a person without a Gumloop account can use an agent from Slack:
<Steps>
<Step title="The organization has an active service account">
A non-human Gumloop identity that Slack-originated requests execute as.
</Step>
<Step title="Their Slack workspace is registered to your organization">
Access is granted per workspace, not per person.
</Step>
<Step title="The specific agent is opted in">
The agent must be shared with the organization **and** have **Allow Slack members without Gumloop accounts** turned on.
</Step>
</Steps>
If any one of these is missing, nothing changes for that person: they get the usual sign-up prompt. The feature is **off by default for every agent** and fails closed.
<Info>
People who **do** have a Gumloop account are unaffected. If a Slack user's email matches a Gumloop account, their request runs on their own account as it always has, even when the toggle is on. The service account is only used for people who have no Gumloop account.
</Info>
***
## Step 1: Create an organization service account
Go to [Settings → Organization → General](https://www.gumloop.com/settings/organization/general) and find the **Service account** section, then click **Create account**.
<Frame>
<img alt="Service account section in organization settings showing one service account with a synthetic email address and a General custom role" />
</Frame>
Gumloop provisions a synthetic organization member that nobody can log in to. It has:
| Property | Value |
| - | - |
| Email | An auto-generated address ending in `.gumloopserviceaccount.com`. It receives no mail and cannot sign in. |
| Organization role | Plain **member**. Service accounts cannot hold Admin, Security, or any other elevated organization role. |
| Custom Roles | Your organization's default role, adjustable (see below) |
You get **one active service account per organization**, and it is the identity for all Slack requests from people without Gumloop accounts, across every opted-in agent.
### Restricting what the service account can do
Because every unsigned Slack request executes as this account, it is worth treating it like any other principal you would lock down. Click the service account row to open **Manage Access**, where you assign [Custom Roles](/enterprise-features/user_groups) that control the apps, tools, scopes, and AI models it may use, plus per-user usage caps. The three-dot menu on the row also lets you copy the service account ID or remove it.
<Frame>
<img alt="Manage Access sheet for the organization service account showing its email, ID, creator, and a list of assignable Custom Roles" />
</Frame>
<Tip>
Give the service account a **dedicated Custom Role** rather than leaving it on your organization default. A tight role is the single best lever for limiting the blast radius of broad Slack access.
</Tip>
Removing the service account immediately stops all access for people without Gumloop accounts. Existing conversation history stays intact.
## Step 2: Register your Slack workspace
In the same settings page, find **Slack workspaces** and click **Add workspace**.
<Frame>
<img alt="Slack workspaces section in organization settings listing one registered workspace with its name, who added it, its Slack workspace ID, and the date added" />
</Frame>
A popup runs Slack OAuth. **Pick the exact workspace you want to authorize** in that popup; the list updates automatically once authorization completes. Each row records the workspace name, its Slack workspace ID (`T…`), who added it, and when.
You can register **multiple workspaces** (for example an internal workspace plus a community one). Each is authorized independently, and removing one does not affect the others.
<Warning>
**Registration is per Slack workspace, not per Slack Enterprise Grid organization.** If your company runs a Grid with several workspaces, an admin must add each workspace individually. Being in the same Grid as a registered workspace is not enough.
</Warning>
Each section prompts you if the other half is missing: the Slack workspaces card tells you to create a service account, and the service account card tells you to add a workspace. Both must exist before any agent can be opted in.
## Step 3: Opt in a specific agent
Open the agent and click **Share**. Two things are required in this dialog:
1. Set **General Access** to **Organization**.
2. Turn on **Allow Slack members without Gumloop accounts**.
<Frame>
<img alt="Agent share dialog with General Access set to Organization and the Allow Slack members without Gumloop accounts toggle switched on" />
</Frame>
The toggle only appears when you can edit the agent, the agent belongs to your organization, and General Access is already set to **Organization**. If your organization setup is incomplete, the dialog shows a setup link instead of the toggle:
| What you see | What it means |
| - | - |
| **Create a service account for Slack access without Gumloop accounts** | Workspace registered, service account missing |
| **Verify a Slack workspace for Slack access without Gumloop accounts** | Service account exists, no workspace registered |
| **Set up Slack access for people without Gumloop accounts** | Neither is configured |
| Setup link greyed out, tooltip **"Ask an organization admin to set up Slack agent access."** | Setup is incomplete and you do not have the role to fix it yourself |
<Info>
**Why Organization and not "Anyone with link"?** Public agents are not allowed to carry [agent-owned credentials](/core-concepts/credentials#agent-owned-credentials), so they must never inherit the organization service account. The organization-level share is what gates service account execution. If you later switch the agent's General Access to **Anyone**, Slack access for people without Gumloop accounts stops working.
</Info>
Opt-in is per agent. Turning it on for one agent does not affect any other agent, and it can only be changed from this control, not through the general agent settings save path.
***
## Credentials: what the agent can actually touch
This is the part most people get wrong on the first try. The service account is a brand new identity with **no connected apps of its own**. It cannot borrow the admin's personal connections, and it cannot borrow the Slack user's connections either.
So for tools to work in a Slack request from someone without a Gumloop account, the agent's connectors must be set to **[agent-owned](/core-concepts/credentials#agent-owned-credentials)** — an account explicitly pinned to the agent, which everyone using the agent acts as.
If a connector is left user-owned, the request fails with a message like:
```text theme={"dark"}
<Integration> is configured on this agent, but external Slack users can only use it
when the credential is agent-owned. Ask an organization admin or the agent owner to
set an agent-owned credential for this integration.
```
People without Gumloop accounts are never shown the usual "connect this app" prompt, because there is no account for them to connect it to.
<Steps>
<Step title="Open the agent's Connectors and pick the connector">
Select the **specific account** you want the agent to use.
</Step>
<Step title="Set Credential ownership to Agent-owned">
See [Agent-Owned Credentials](/core-concepts/credentials#agent-owned-credentials) for the full walkthrough. Connectors in this mode show an **Agent Owned** label in the tool list.
<Frame>
<img alt="Credential ownership section in a connector detail view showing the User-owned and Agent-owned options" />
</Frame>
</Step>
</Steps>
<Note>
In organizations, agent-owned credentials are **restricted by default**. If the **Agent-owned** option is greyed out for you, an admin has to enable the **Agent-owned credentials** feature toggle on your [Custom Role](/enterprise-features/user_groups) first.
</Note>
<Warning>
Agent-owned pins are tied to the space the agent lives in. Cloning the agent, using it as a template, or moving it to another team **drops the agent-owned pin**, and the connector reverts to user-owned. If you move or copy an opted-in agent, re-check its credential ownership.
</Warning>
## Attribution, credits, and auditing
* **Runs execute as the service account.** Permissions, Custom Role restrictions, and org policies are all evaluated against the service account, not the Slack person and not the admin who created it.
* **The Slack person is still recorded.** Each request stores the originating Slack actor (platform, workspace ID, Slack user ID, display name) alongside the conversation, so you can see who actually asked.
* **Usage draws on organization credits**, not on any individual's balance.
* **Setup changes are audit-logged**: service account creation and removal, and Slack workspace registration and removal all emit [audit log](/enterprise-features/audit_logging) events.
## Who is eligible
Registering a workspace authorizes its **full members**. Gumloop deliberately excludes several categories, all of which fall back to the sign-up prompt:
| Who | Can use an opted-in agent without a Gumloop account? |
| - | - |
| Full member of a registered workspace | Yes |
| Member of a workspace you have not registered | No |
| Slack Connect user from an external organization, posting in a shared channel | No — their home workspace is their own, not yours |
| Single-channel or multi-channel guest | No |
| Deactivated Slack user, or a bot | No |
| Anyone, when the agent's toggle is off | No |
<Warning>
**Shared channels are the case to watch.** Registering a workspace does not extend access to Slack Connect partners in channels you share with them. That is intentional, but it also means an opted-in agent living in a shared channel behaves differently for your own members than for the partner's members.
</Warning>
***
## Frequently asked questions
<AccordionGroup>
<Accordion title="Does everyone in my Slack workspace get access to all my agents?" icon="lock">
No. Registering a workspace grants nothing by itself. Each agent must be individually shared with your organization and individually opted in. The default for every agent, including newly created ones, is off.
</Accordion>
<Accordion title="Is being in the same Slack Enterprise Grid enough?" icon="sitemap">
No. Authorization is based on the specific Slack workspace ID, so each workspace in a Grid must be registered on its own. If you run a Grid, register every workspace whose members should have access, and verify the behavior for members whose home workspace differs from the one they are posting in.
</Accordion>
<Accordion title="Whose credentials does the agent use?" icon="key">
Two separate things. The **execution identity** is the organization service account, a synthetic non-human Gumloop user. The **integration credentials** are whatever the agent owner pinned as [agent-owned](/core-concepts/credentials#agent-owned-credentials). Never the admin's personal login, and never the Slack user's own connected accounts.
</Accordion>
<Accordion title="A Slack user got the sign-up prompt anyway. Why?" icon="circle-question">
Work down the list: is the toggle on for **that** agent; is General Access set to **Organization**; is **their** workspace registered (not just another workspace in the same Grid); are they a full member rather than a guest or Slack Connect user; and does an active service account exist. Any single missing piece produces the sign-up prompt.
</Accordion>
<Accordion title="Slack said 'This agent isn't available yet. Ask a Gumloop organization admin to finish setup.'" icon="triangle-exclamation">
That specific wording means the agent is opted in and the workspace is registered, but there is no usable active organization service account — usually because it was removed after the agent was enabled. Recreate it in [Settings → Organization → General](https://www.gumloop.com/settings/organization/general).
</Accordion>
<Accordion title="What happens to people who already have Gumloop accounts?" icon="user-check">
Nothing changes for them. Their Slack requests keep running on their own account and their own credentials. The service account path applies only to people with no matching Gumloop account.
</Accordion>
<Accordion title="Can I revoke access quickly?" icon="ban">
Yes, at three levels. Turn off the agent's toggle to revoke one agent. Remove a Slack workspace to revoke one workspace while leaving others intact. Remove the service account to revoke all unsigned Slack access across the organization at once. All three take effect for subsequent requests; existing conversation history is preserved.
</Accordion>
<Accordion title="Can I limit what these Slack requests are allowed to do?" icon="shield">
Yes. Assign the service account a restrictive [Custom Role](/enterprise-features/user_groups) through **Manage Access**. Since every unsigned Slack request runs as that one account, its Custom Roles are an effective org-wide ceiling on this whole surface. Restricting the agent's tool list is the other lever.
</Accordion>
<Accordion title="Do these Slack requests consume credits?" icon="coins">
Yes, they draw on your organization's credits, since the service account is an organization member.
</Accordion>
<Accordion title="Can this be used in DMs with the agent?" icon="comment">
No. This feature covers the channels an opted-in agent lives in. DMs to the Gumloop app go to the sender's own [Gumball](/core-concepts/gumball#gumball-in-slack), which requires a Gumloop account and never runs on the service account — someone without an account gets the sign-up prompt in a DM. See [Using Agents in Slack](/core-concepts/agents_slack).
</Accordion>
<Accordion title="Why can't I see the toggle in the share dialog?" icon="eye-slash">
The toggle is only rendered when you have edit access to the agent, the agent is owned by your organization, and General Access is already **Organization**. On top of that, your organization must be on Enterprise. If setup is incomplete you see a setup link in its place instead of the toggle.
</Accordion>
</AccordionGroup>
## Related
<CardGroup>
<Card title="Using agents in Slack" icon="slack" href="/core-concepts/agents_slack">
Adding agents to channels, Slack preferences, commands, and how credentials work for signed-up users.
</Card>
<Card title="Agent-owned credentials" icon="key" href="/core-concepts/credentials#agent-owned-credentials">
Pin one account to an agent so everyone using it acts as that account. Required for this feature's tools to work.
</Card>
<Card title="Custom roles" icon="shield" href="/enterprise-features/user_groups">
Restrict the apps, tools, scopes, and models the service account may use.
</Card>
<Card title="Agent access" icon="users" href="/core-concepts/agent_access">
How General Access rings work, including the Organization level this feature requires.
</Card>
</CardGroup>
# SSO: SAML, OIDC & SCIM
Source: https://docs.gumloop.com/enterprise-features/sso_saml_oidc_scim
Enterprise organizations can configure single sign-on (SSO) authentication through SAML or OIDC (OpenID Connect), and automated user provisioning through SCIM. This enables centralized identity management, enhanced security, and streamlined user lifecycle management.
## Overview
<CardGroup>
<Card title="Dedicated login pages" icon="door-open">
Self-service branded sign-in pages at `gumloop.com/{your-org}`, for SAML or OIDC
</Card>
<Card title="SAML & OIDC authentication" icon="shield-check">
SAML 2.0 via Okta, Entra ID, Google AD, and more. OIDC with Okta.
</Card>
<Card title="SCIM provisioning" icon="users-gear">
Automated user provisioning plus custom-role and team sync from IdP groups (SAML app required)
</Card>
</CardGroup>
***
## Dedicated SSO login pages
Every enterprise organization has a dedicated sign-in page at `gumloop.com/signin/{your-slug}` (`gumloop.com/{your-slug}` redirects there). It is a branded entry point that shows only the sign-in methods you allow, and organization admins set it up themselves. Dedicated login pages work with both SAML and OIDC.
### Setting up your login page
<Steps>
<Step title="Open login page settings">
Navigate to [gumloop.com/settings/organization/login-page](https://www.gumloop.com/settings/organization/login-page), under **People & Access**.
<Note>
Login page settings require the **Admin** [organization role](/core-concepts/organization_user_roles#admin) and an Enterprise subscription. SAML or OIDC setup is not a prerequisite; you can publish a page with Google and Microsoft sign-in and add SSO later.
</Note>
</Step>
<Step title="Choose your URL">
The slug is prefilled from your organization name and may contain lowercase letters, numbers and hyphens. Availability is checked as you type.
<Warning>
Changing the slug later breaks existing bookmarks and IdP tiles that point at the old URL. Pick it once.
</Warning>
</Step>
<Step title="Add your branding">
Set the organization name shown on the page, upload a logo (PNG, JPG or WEBP up to 2 MB) and pick a brand color. Drag and zoom the logo inside the frame to fit; the page shows the image exactly as uploaded, so use a PNG with a transparent background.
The preview on the right renders the real sign-in page as you edit, before anything is saved.
</Step>
<Step title="Choose sign-in methods">
Allow **Google** and **Microsoft** sign-in independently, and choose one single sign-on method: **None**, **SAML SSO** or **Okta OpenID Connect**. SAML becomes selectable once a live SAML connection exists, and Okta OpenID Connect once the Okta app has passed a test sign-in, both under **Identity Provider**.
<Warning>
Restrictions apply to members whose email domain is routed to your organization under **Identity Provider**. Allowing only single sign-on locks out anyone your IdP has not assigned to the Gumloop app; the page asks you to confirm that everyone is assigned before saving.
</Warning>
</Step>
<Step title="Save and verify">
Saving publishes the page immediately. Sign-in restrictions can take up to five minutes to apply. **Live status** shows what the sign-in service currently enforces for your routed domains, and **Test sign-in page** opens the real page in a test mode where each button signs you in against a throwaway session and reports the result, without affecting your current session.
</Step>
</Steps>
### Available authentication methods
| Provider | Description | Recommendation |
| - | - | - |
| **SAML SSO** | Enterprise identity providers (Okta, Entra ID, etc.) | Recommended for enterprise |
| **OIDC SSO** | OpenID Connect with Okta, configured and tested inside Gumloop | Recommended for Okta-based organizations |
| **Google** | Sign in with Google Workspace | Suitable for Google-based organizations |
| **Microsoft** | Direct Microsoft sign-in | Suitable for Microsoft-based organizations; Entra ID through SAML uses SAML SSO instead |
<Note>
An organization uses exactly one SSO protocol at a time, either SAML or OIDC. The login page shows a single **Sign in with SSO** button either way; Gumloop routes the sign-in through whichever protocol is active for your organization.
</Note>
<Info>
Email/password sign-in is not offered on self-service login pages. Organizations that already have it enabled keep it.
</Info>
***
## SAML configuration
SAML (Security Assertion Markup Language) enables enterprise single sign-on through your organization's identity provider.
### Supported identity providers
<CardGroup>
<Card title="Okta" icon="key" />
<Card title="Microsoft Entra ID" icon="microsoft" />
<Card title="Google Workspace" icon="google" />
<Card title="JumpCloud" icon="cloud" />
<Card title="Ping Identity" icon="fingerprint" />
<Card title="Active Directory" icon="server" />
</CardGroup>
### Setting up SAML
<Steps>
<Step title="Access SSO settings">
Navigate to [gumloop.com/settings/organization/sso](https://www.gumloop.com/settings/organization/sso)
<Note>
SAML settings require the **Admin** [organization role](/core-concepts/organization_user_roles#admin) and an Enterprise subscription.
</Note>
</Step>
<Step title="Generate setup link">
Click **Set up SAML**, then **Generate Setup Link** to create a SAML connection configuration. This generates the SP (Service Provider) details needed for your identity provider.
</Step>
<Step title="Configure your identity provider">
Use the generated details to configure a SAML application in your IdP. For step-by-step instructions, see the guides for your provider:
* [SAML with Okta](/enterprise-features/idp-guides/saml-with-okta)
* [SAML with Microsoft Entra ID](/enterprise-features/idp-guides/saml-with-entra)
* [SAML with JumpCloud](/enterprise-features/idp-guides/saml-with-jumpcloud)
* [SAML with Google Identity](/enterprise-features/idp-guides/saml-with-google)
* [SAML with Ping Identity](/enterprise-features/idp-guides/saml-with-ping)
</Step>
<Step title="Set up your login page">
Once the SAML connection is live, enable **SAML SSO** on your [dedicated login page](#dedicated-sso-login-pages) so members sign in at `gumloop.com/{your-org}`.
</Step>
</Steps>
### SP-initiated vs IdP-initiated login
Gumloop supports **SP-initiated login only**, for both SAML and OIDC. This means users must start their login flow from Gumloop (the Service Provider) rather than from your identity provider's app dashboard.
<Tabs>
<Tab title="How it works" icon="diagram-project">
**SP-Initiated Flow:**
1. User navigates to `gumloop.com/{your-org}`
2. Clicks the SSO login button
3. Redirects to your IdP for authentication
4. Upon successful auth, returns to Gumloop with a valid session
This approach ensures Gumloop controls the full authentication handshake, including session token generation and storage.
</Tab>
<Tab title="IdP tiles & bookmarks" icon="grid-2">
**Best Practice:** Instead of IdP-initiated login, configure your IdP to redirect users to your Gumloop login page:
* **Okta/Entra Tiles:** Set the tile URL to `https://gumloop.com/{your-org}`
* **Browser Bookmarks:** Bookmark your organization's login page
* **Company Portals:** Link directly to the SP-initiated login URL
This provides the same one-click experience while maintaining security.
</Tab>
</Tabs>
### SAML best practices
<CardGroup>
<Card title="Use SP-initiated login" icon="shield-halved">
Configure IdP tiles to redirect to your Gumloop login page rather than using IdP-initiated flows
</Card>
<Card title="Disable IdP-Initiated" icon="ban">
Prevent IdP-initiated logins in your IdP settings to avoid session handling issues
</Card>
<Card title="Test before rollout" icon="flask">
Verify the SAML connection with test users before enabling for your entire organization
</Card>
<Card title="Document for users" icon="book">
Provide clear instructions to users on how to access Gumloop via your organization's login page
</Card>
</CardGroup>
### SAML vs SCIM: User provisioning
<Tabs>
<Tab title="SAML (JIT Provisioning)" icon="bolt">
**Just-In-Time (JIT) Provisioning**
With SAML alone, users are provisioned when they first log in:
* User authenticates via SAML for the first time
* Gumloop automatically creates their account on successful auth
* No pre-provisioning or advance user management
**Best for:** Organizations that don't need advance user visibility or automated deprovisioning.
</Tab>
<Tab title="SCIM (IdP Provisioning)" icon="arrows-rotate">
**Direct IdP-Based Provisioning**
SCIM provides proactive user lifecycle management:
* Users provisioned before first login (visible in member list)
* Automatic deprovisioning when removed from IdP
* Custom-role and team sync from IdP groups (each direction configurable independently)
* Runs through your SAML app, also for organizations that sign in with OIDC
**Best for:** Organizations requiring advance user management, automated offboarding, or centralized group-based permissions.
</Tab>
</Tabs>
***
## OIDC configuration
OIDC (OpenID Connect) lets members sign in with Okta directly through an app integration you configure and test inside Gumloop. Gumloop requests only the `openid` and `email` scopes, matches accounts by email, and stores nothing per user.
### Supported identity providers
<CardGroup>
<Card title="Okta" icon="key" />
</CardGroup>
### Setting up OIDC
Setup takes about 15 minutes and requires admin access to Okta. Progress is saved as you go, so you can close the setup wizard and resume where you left off. Members keep signing in with their current method until you activate OIDC in the final step.
<Steps>
<Step title="Access SSO settings">
Navigate to [gumloop.com/settings/organization/sso](https://www.gumloop.com/settings/organization/sso) and click **Set up OpenID Connect**.
<Note>
OIDC settings require the **Admin** [organization role](/core-concepts/organization_user_roles#admin) and an Enterprise subscription.
</Note>
If your organization needs SCIM provisioning, Gumloop prompts you to set up the SAML app first. SCIM runs through a SAML app even when sign-in uses OIDC (see [OIDC vs SCIM](#oidc-vs-scim-user-provisioning)).
</Step>
<Step title="Configure your identity provider">
Create an OIDC web application for Gumloop in Okta. For step-by-step instructions, see the guide:
* [OIDC with Okta](/enterprise-features/idp-guides/oidc-with-okta)
The app's **Sign-in redirect URI** must be `https://api.gumloop.com/enterprise-login/okta/callback`.
Assign the app to the Okta group that should reach Gumloop, and set the ID token **Issuer** to **Okta URL**.
</Step>
<Step title="Enter app credentials">
In Gumloop, enter the **Okta domain**, **Client ID**, and **Client Secret** from the app's General tab in Okta.
<Warning>
The Okta domain is the bare hostname, such as `acme.okta.com`. Leave out `https://` and any `/oauth2/...` path. Gumloop uses your Okta org authorization server, not a custom authorization server.
</Warning>
Gumloop verifies the domain and credentials with Okta before saving. The client secret is stored encrypted and is never shown again.
</Step>
<Step title="Choose SSO Domains">
Turn on SSO sign-in for each organization email domain that should sign in through Okta. At least one domain must be on before you can continue, and the domain in your own email must be on before the test sign-in.
</Step>
<Step title="Test sign-in">
Click **Run test** to sign in through the new Okta app once as yourself. Okta opens in a popup; your current Gumloop session is not affected. The test confirms four things in order:
1. Okta accepts the sign-in request (redirect URI and domain)
2. Your user is assigned to the app
3. The client ID and secret match the app
4. The email Okta returns matches your Gumloop account
A failed check shows what to fix. The test must pass before OIDC can be activated.
</Step>
<Step title="Pre-flight checks and activate">
Before activating, confirm:
* **Okta emails match Gumloop accounts.** Accounts are matched by email. A member whose Okta email differs from their Gumloop email would get a second account at first sign-in. Align the email or the attribute mapping in Okta first.
* **Everyone is assigned to the Okta app.** Gumloop can't see Okta assignments. Use a group assignment that covers everyone who signs in today; a user left out sees "not assigned" and has no other way in.
Then click **Activate Okta OIDC sign-in**. Everyone on your SSO domains signs in through Okta, and Google and email sign-in are turned off for those domains. The change takes a couple of minutes to propagate. Existing sessions keep working; members meet Okta at their next full sign-in. You can turn OIDC off from the same page at any time.
</Step>
<Step title="Set up your login page">
After activating OIDC, enable **Okta OpenID Connect** on your [dedicated login page](#dedicated-sso-login-pages) so members sign in at `gumloop.com/{your-org}`.
</Step>
</Steps>
### SP-initiated vs IdP-initiated login
OIDC sign-in is **SP-initiated only**, the same as SAML. Members start from `gumloop.com/{your-org}` (or the Gumloop sign-in page) and click **Sign in with SSO**; Gumloop then redirects to Okta and back. Point Okta tiles and bookmarks at your Gumloop login page rather than launching from the Okta dashboard. See [SP-Initiated vs IdP-Initiated Login](#sp-initiated-vs-idp-initiated-login) above for tile and bookmark guidance.
### OIDC best practices
<CardGroup>
<Card title="Assign by group" icon="users">
Assign the Okta app to a group that covers everyone who uses Gumloop, not to individual users. Anyone missing from the assignment can't sign in once OIDC is active.
</Card>
<Card title="Align emails first" icon="envelope">
Make sure each member's Okta email matches their Gumloop email before activating. Mismatches create duplicate accounts.
</Card>
<Card title="Rotate secrets safely" icon="key">
Add the new client secret in Okta first, then use **Edit** in Gumloop and run the test sign-in again. Retire the old secret only after the test passes. Saving new credentials switches member sign-in immediately. The Okta domain is locked while OIDC is active.
</Card>
<Card title="Test before rollout" icon="flask">
Run the test sign-in and review the pre-flight checks with a pilot group before activating for the whole organization.
</Card>
</CardGroup>
### OIDC vs SCIM: User provisioning
<Tabs>
<Tab title="OIDC (JIT Provisioning)" icon="bolt">
**Just-In-Time (JIT) Provisioning**
With OIDC alone, users are provisioned when they first sign in:
* User authenticates via Okta for the first time
* Gumloop matches an existing account by email, or creates one
* Okta app assignment is the only roster; no pre-provisioning or automated deprovisioning
**Best for:** Okta organizations that don't need advance user visibility or automated offboarding.
</Tab>
<Tab title="SCIM (SAML App Required)" icon="arrows-rotate">
**SCIM runs through a SAML app**
SCIM provisioning is only available through a SAML app. An organization that signs in with OIDC and needs SCIM must also:
* Set up a SAML connection (**Set up SAML** on the SSO page), following the [SCIM setup](#setting-up-scim)
* Keep every Gumloop user assigned to the SAML app in Okta, since that assignment drives provisioning
Sign-in still goes through OIDC. Once SCIM is enabled, only provisioned users can sign in; an unprovisioned user is rejected with "There is no Gumloop account for this email."
</Tab>
</Tabs>
<Warning>
When SCIM is enabled alongside OIDC, unassigning a user from the **SAML** app in Okta deprovisions them in Gumloop, even though they sign in through the OIDC app. Keep both assignments in sync.
</Warning>
### Migrating from SAML to OIDC
An organization already on SAML with Okta can switch to OIDC from the SSO settings page. Accounts are matched by email, nothing is migrated or duplicated, and you can roll back to SAML at any time.
**Eligibility**
* Your current SAML connection must be live and its identity provider must be Okta. The **Migrate to OpenID Connect single sign-on** option appears on the SSO page only in that case.
* Organizations on SAML with another identity provider (Entra ID, Google, JumpCloud, Ping) stay on SAML.
**How the migration works**
The migration uses the same steps as a fresh setup, with a few differences:
1. **Assign the same group.** When you configure the OIDC app in Okta, assign it to the same group your SAML app uses. Everyone who signs in today must be in it before you switch.
2. **No SAML fallback.** After the switch, anyone the pre-flight checks miss can't sign in until you roll back. Clear the blocking checks first.
3. **Switch to Okta OIDC.** The final step swaps the sign-in method: SAML out, OIDC in. Nothing is sent to Okta, and your SAML connection stays in place for rollback.
Members keep signing in with SAML until you complete the switch. After the switch, existing sessions keep working and members meet Okta OIDC at their next full sign-in. Your dedicated login page keeps working unchanged.
<Warning>
**Keep the SAML app assigned in Okta.** If SCIM is enabled, it keeps running from the SAML app after the migration. Do not delete the SAML app or unassign users from it; unassigning someone deactivates them in Gumloop.
</Warning>
**Rolling back to SAML**
While your SAML connection remains live, the **Okta OIDC app** section on the SSO page offers **Roll back to SAML**. Members go back to SAML at their next sign-in, no accounts change, and the change takes a couple of minutes to propagate. You can migrate again later.
```mermaid theme={"dark"}
stateDiagram-v2
NoSSO: No SSO
SAML: SAML active
OIDC: Okta OIDC active
NoSSO --> SAML: Set up SAML
NoSSO --> OIDC: Set up OIDC (test sign-in passed)
SAML --> OIDC: Migrate (IdP is Okta, test sign-in passed)
OIDC --> SAML: Roll back (SAML connection live)
```
### Troubleshooting OIDC
**Admin setup errors**
| Error | What to do |
| - | - |
| Domain invalid / doesn't answer as an Okta org authorization server | Enter the bare Okta hostname, such as `acme.okta.com`. Leave out `https://`, `/oauth2/default`, and custom authorization servers. |
| Couldn't load the OpenID configuration for that domain | Check the domain spelling and that the Okta org is reachable, then try again. |
| Okta rejected the client ID and secret | Re-copy both from the app's **General** tab in Okta. |
| Client secret required | The secret must be re-entered whenever the Okta domain changes. A blank secret only keeps the stored one for the same domain. |
| Okta domain can't change while OIDC is active | Rotate the client ID and secret if needed, or roll back to SAML before moving to a different Okta domain. |
| Run a successful test sign-in before switching | The test sign-in must pass with the currently saved credentials. Re-run it after editing the app. |
| Set up your SAML connection before switching to SAML | Rollback requires a live SAML connection. Complete the SAML setup first. |
| Another admin changed the configuration | Reload the page and try again. |
| Okta shows "Your request resulted in an error. The 'redirect\_uri' parameter must be a Login redirect URI in the client app settings" | The Okta app's **Sign-in redirect URIs** doesn't include Gumloop's callback. In Okta, open the app's **General** tab and add `https://api.gumloop.com/enterprise-login/okta/callback` exactly, then retry. |
**Member sign-in errors**
| Message | Cause and fix |
| - | - |
| "You need access to Gumloop in Okta" | The user isn't assigned to the Okta app. Add them (or their group) under **Assignments** in Okta. |
| "There is no Gumloop account for this email" | SCIM is enabled and the user hasn't been provisioned, or the account belongs to another organization. Provision the user through the SAML app's SCIM directory. |
| "Okta signed in a different account" | The user signed in to Okta with an email that doesn't match the one they entered. Sign in to Okta as the matching account, or fix the email attribute mapping in Okta. |
| "SSO is misconfigured for your organization" | The redirect URI, Okta domain, or SSO domain is wrong. An admin should re-run the test sign-in from the SSO settings page to see which check fails. |
| Okta shows "Your request resulted in an error. The 'redirect\_uri' parameter must be a Login redirect URI in the client app settings" | The Okta app is missing Gumloop's callback under **Sign-in redirect URIs**. An Okta admin needs to add `https://api.gumloop.com/enterprise-login/okta/callback` to the app. |
***
## SCIM provisioning
SCIM (System for Cross-domain Identity Management) enables automated user provisioning, deprovisioning, and synchronization of both **custom roles** and **teams** between your identity provider and Gumloop. Each direction is configured independently, and each can resolve IdP groups via a curated mapping table or by name match with auto-create on miss.
<Note>
SCIM is an add-on feature. Contact [support@gumloop.com](mailto:support@gumloop.com) to request SCIM enablement for your organization. The team will evaluate your use case to determine if SCIM is the right solution for your needs.
</Note>
<Info>
SCIM connects through a **SAML app** in your identity provider. Organizations that sign in with [OIDC](#oidc-configuration) still need a SAML app for provisioning; sign-in continues through OIDC. See [OIDC vs SCIM](#oidc-vs-scim-user-provisioning).
</Info>
### What SCIM provides
<AccordionGroup>
<Accordion title="Automated user provisioning" icon="user-plus">
When users are assigned to the Gumloop application in your IdP, they are automatically provisioned in Gumloop. Users appear in your organization's member list and can be viewed before they first log in (pre-provisioning).
</Accordion>
<Accordion title="Automated deprovisioning" icon="user-minus">
When users are removed from the Gumloop application in your IdP, they are automatically deprovisioned—removing their access and freeing up seats.
</Accordion>
<Accordion title="Custom-role sync" icon="shield">
IdP groups can be mapped to Gumloop [Custom Roles](/enterprise-features/user_groups), enabling centralized access control management. Users in **multiple mapped IdP groups receive the union** of every matched role.
SCIM-provisioned users land with the baseline **Member** [organization role](/core-concepts/organization_user_roles#member). Custom roles and team memberships come from IdP-group mappings (or name-based resolution, if enabled) and do not change that organization role.
<Warning>
This is **group-based synchronization**, not role-based access control (RBAC). Restrictions are managed through Gumloop's [Custom Roles](/enterprise-features/user_groups) system.
</Warning>
</Accordion>
<Accordion title="Team sync" icon="users-rectangle">
IdP groups can be mapped to Gumloop **teams (projects)**. The team direction is independent of the custom-role direction — you can configure either, both, or neither. Users in multiple mapped IdP groups join every mapped team.
</Accordion>
<Accordion title="Per-direction mode (mapping table vs name-based)" icon="toggle-on">
Each direction (roles, teams) has its own **Use mapping table** toggle:
* **On (default):** the curated mapping table is the source of truth. Only mapped roles and teams are added or removed. Unmapped memberships stay as they are in Gumloop. If no mapping matches, existing users are left alone.
* **Off (name-based):** Gumloop matches each IdP group's display name directly to a Gumloop role/team (case- and whitespace-insensitive). On miss, a new role or team is **auto-created** using the IdP group's name on the next sync. In this mode the IdP is the source of truth, so users with no matching IdP groups have their roles/teams wiped.
<Warning>
Switching a direction to name-based mode is **destructive on next sync** for users whose IdP groups don't match any Gumloop entity — the UI requires explicit confirmation before applying. Use it only when your IdP is the authoritative system of record for that direction.
</Warning>
</Accordion>
</AccordionGroup>
### Setting up SCIM
<Steps>
<Step title="Request SCIM enablement">
Contact [support@gumloop.com](mailto:support@gumloop.com) to have SCIM enabled for your organization. The team will evaluate your use case to ensure SCIM is the right solution.
</Step>
<Step title="Generate SCIM credentials">
Once enabled, navigate to [gumloop.com/settings/organization/sso](https://www.gumloop.com/settings/organization/sso) and use **Generate Setup Link** to create SCIM directory credentials.
<Note>
SCIM credentials are generated on the SAML side of the SSO page. If your organization signs in with OIDC, you still need a SAML connection here for provisioning.
</Note>
</Step>
<Step title="Configure your identity provider">
Set up SCIM provisioning in your IdP using the base URL and bearer token from Gumloop. See provider-specific guides:
* [SCIM with Okta](/enterprise-features/idp-guides/scim-with-okta)
* [SCIM with Microsoft Entra ID](/enterprise-features/idp-guides/scim-with-entra)
<Info>
SCIM is currently supported for **Okta** and **Microsoft Entra ID** only.
</Info>
</Step>
<Step title="Create mappings (optional)">
Map IdP groups to Gumloop entities under **Group to Custom Role Mappings** and **Group to Team Mappings** in the SSO settings. Each direction is independent.
<Info>
Mappings are optional. With the **Use mapping table** toggle on (default) and the table empty, SCIM sync will not modify users' role or team assignments. You can manage them directly in Gumloop. When a mapping matches, SCIM only adds or removes that mapped role or team. Everything else stays as it is.
</Info>
For each direction you can instead toggle **Use mapping table** off to switch to name-based mode, where IdP group names auto-resolve to existing Gumloop entities and unmatched names auto-create new ones on the next sync.
</Step>
<Step title="Enable directory sync">
Select your SCIM directory on the `/sso` page and enable synchronization. You can trigger manual syncs or configure automated periodic syncs.
</Step>
</Steps>
### SCIM and custom roles / teams
<Tabs>
<Tab title="How it works" icon="sitemap">
IdP groups are mapped to Gumloop [Custom Roles](/enterprise-features/user_groups) and/or **teams (projects)**, independently per direction. When users are synced, they are assigned the **union** of every matched mapping.
**Important considerations:**
* If a direction's mapping table is empty (and **Use mapping table** is on), SCIM leaves that direction's assignments alone for existing users.
* Create groups in your IdP first, then map them to Gumloop custom roles or teams.
* Group names don't need to match exactly when the mapping table is on. You define the mapping by selecting the Gumloop entity per row.
* When a mapping matches, only that mapped role or team is added or removed. Unmapped assignments stay as they are.
* If mappings exist but no IdP group matches, existing users keep their current roles and teams. A **new** provision with no match still lands on the org's **default custom role** and **default team**.
</Tab>
<Tab title="Union semantics" icon="users">
A user in multiple mapped IdP groups receives the **union** of every matched role and the union of every matched team. There is no priority — every mapping that matches the user's IdP groups contributes.
Example: if `Engineering → Eng-Role` and `On-Call → On-Call-Role` are both configured and the user belongs to both IdP groups, the user is assigned **both** `Eng-Role` and `On-Call-Role`.
To grant a single specific role, ensure the user belongs to exactly one mapped IdP group. To revoke SCIM-managed access, remove the user from the SCIM directory (which triggers the deprovisioning path) — clearing the mapping table will not strip existing users while the **Use mapping table** toggle remains on.
</Tab>
<Tab title="Name-based mode" icon="wand-magic-sparkles">
Toggling **Use mapping table** off for a direction switches that direction to name-based resolution:
* Each IdP group's display name is matched (case- and whitespace-insensitive) against existing Gumloop custom role / team names.
* **Hit:** the user is assigned that existing entity.
* **Miss:** a new custom role or team is **auto-created** using the IdP group's name on the next sync.
Within-org name uniqueness is enforced at create/rename time, so name-based resolution is deterministic. SCIM treats the IdP as authoritative in this mode — users whose IdP groups don't resolve to any Gumloop entity have their roles/teams **wiped**. The UI requires explicit confirmation before switching to name-based mode.
For team sync only: name-based mode is authoritative **across organizations** — a user's cross-org team memberships not represented in the IdP target set are also removed. SCIM can still only **add** users to teams in the synced org.
</Tab>
</Tabs>
### Sync operations
| Trigger | Description |
| - | - |
| **Scheduled** | Automatic periodic sync (every 15 minutes) |
| **Manual** | On-demand sync triggered by organization admin |
### Pre-provisioned users
Users assigned to Gumloop in your IdP are visible in your organization's member list before they log in for the first time. This enables:
* Advance seat planning
* Pre-assigning users to teams
* Visibility into pending onboarding
<Info>
Pre-provisioned users don't consume active seats until they complete their first login.
</Info>
### SCIM best practices
<CardGroup>
<Card title="Map groups if needed" icon="layer-group">
Configure role and team mappings only when you want SCIM to manage those assignments. With **Use mapping table** on and the table empty, users keep their current Gumloop memberships.
</Card>
<Card title="Prefer mapping table mode" icon="table">
Default mapping-table mode is non-destructive — users with no matching IdP group are left alone. Use name-based mode only when your IdP is authoritative and you accept that descoped users will lose roles/teams.
</Card>
<Card title="Confirm before going name-based" icon="triangle-exclamation">
Switching a direction off the mapping table will wipe roles/teams for users whose IdP groups don't match any Gumloop entity on the next sync. The UI gates this behind a confirmation modal — read it.
</Card>
<Card title="Test with pilot group" icon="flask">
Enable SCIM for a small test group before rolling out to the entire organization.
</Card>
<Card title="Monitor audit logs" icon="clipboard-list">
Review SCIM-related audit events to verify provisioning, mapping changes, and auto-creates land as expected.
</Card>
<Card title="Disable = fresh start" icon="rotate-left">
Disabling SCIM clears all mapping tables, per-direction toggles, and SCIM tracking rows. Re-enabling starts clean — users remain in the org as if added manually.
</Card>
</CardGroup>
### SCIM audit events
SCIM operations are tracked in your organization's [audit logs](/enterprise-features/audit_logging):
| Event | Description |
| - | - |
| `SCIM_SYNC_STARTED` | Directory sync operation initiated |
| `SCIM_SYNC_COMPLETED` | Sync completed with summary stats |
| `SCIM_SYNC_FAILED` | Sync failed with error details |
| `SCIM_SYNC_ENABLED` | SCIM sync enabled for the organization |
| `SCIM_SYNC_DISABLED` | SCIM sync disabled for the organization |
| `SCIM_USER_PROVISIONED` | New user provisioned via SCIM |
| `SCIM_USER_DEPROVISIONED` | User removed via SCIM |
| `SCIM_USER_PERMISSION_GROUP_CHANGED` | User's custom-role assignments updated (union of mapped roles) |
| `SCIM_USER_TEAM_CHANGED` | User's team memberships updated (union of mapped teams) |
| `SCIM_GROUP_MAPPING_UPDATED` | Curated role mappings table replaced |
| `SCIM_TEAM_MAPPING_UPDATED` | Curated team mappings table replaced |
| `SCIM_AUTO_CREATED_ENTITY` | A new role or team was auto-created from an unmatched IdP group name (name-based mode) |
| `SCIM_USE_MAPPING_TABLE_CHANGED` | A per-direction toggle (role or team) flipped between mapping-table and name-based modes |
### SSO audit events
Changes to your organization's sign-in method are also tracked in the [audit logs](/enterprise-features/audit_logging):
| Event | Description |
| - | - |
| `SSO_SIGN_IN_PROVIDERS_CHANGED` | The active SSO method changed: OIDC activated, SAML migrated to OIDC, or OIDC rolled back to SAML. Records the previous and new sign-in providers. |
***
## Security & compliance
Gumloop's SSO implementation follows industry security standards:
<CardGroup>
<Card title="SOC 2 Type II" icon="certificate">
Certified compliance with SOC 2 Type II controls for security, availability, and confidentiality
</Card>
<Card title="SAML 2.0 & OIDC" icon="lock">
Industry-standard SAML 2.0 and OIDC (authorization code with PKCE) protocols
</Card>
<Card title="Encrypted transit" icon="shield-halved">
All authentication traffic encrypted via TLS 1.3
</Card>
<Card title="Session management" icon="clock">
Configurable session timeouts and secure token handling
</Card>
</CardGroup>
<Tip>
For detailed security information and certifications, visit [trust.gumloop.com](https://trust.gumloop.com/).
</Tip>
***
## Related resources
<CardGroup>
<Card title="Custom roles" icon="user-shield" href="/enterprise-features/user_groups">
Configure granular permissions for synced users
</Card>
<Card title="Audit logging" icon="clipboard-list" href="/enterprise-features/audit_logging">
Monitor authentication and provisioning events
</Card>
<Card title="Okta integration" icon="key" href="/core-concepts/okta-integration">
Configure Okta as an OAuth provider for connectors (Snowflake, NetSuite). Not related to OIDC sign-in.
</Card>
<Card title="Organization roles" icon="building" href="/core-concepts/organization_user_roles">
Understand organization member roles and permissions
</Card>
</CardGroup>
***
## Need help?
* **Setup Assistance:** Contact [support@gumloop.com](mailto:support@gumloop.com)
* **SCIM Enablement:** Request via [support@gumloop.com](mailto:support@gumloop.com)
* **Identity Provider Docs:** [SAML with Okta](/enterprise-features/idp-guides/saml-with-okta), [OIDC with Okta](/enterprise-features/idp-guides/oidc-with-okta), and the other Identity Provider Guides
# Static egress IPs
Source: https://docs.gumloop.com/enterprise-features/static_egress_ips
Fixed outbound IP addresses for firewall and allowlist configuration.
Gumloop routes all outbound traffic through a fixed set of static IP addresses. If your organization requires firewall allowlisting or network-level access controls, add the following IPs to your allowlist.
<Info>
These IPs cover all Gumloop services that make outbound requests on your behalf, including agent execution, trigger polling, and MCP integrations.
</Info>
## IP addresses
```text theme={"dark"}
8.229.10.233
8.231.186.254
8.235.126.180
34.11.198.142
34.19.1.9
34.19.116.218
34.53.28.46
34.53.76.64
34.53.111.40
34.82.238.205
34.83.79.220
34.105.93.38
34.127.37.129
34.168.17.238
34.168.215.172
34.169.30.92
34.169.86.55
136.66.32.248
136.66.36.233
136.66.113.246
136.66.131.36
136.67.43.83
136.117.108.82
136.118.248.115
```
All 24 IPs are individual addresses, not a contiguous CIDR block. Each one should be added as a `/32` entry in your firewall rules.
## Usage notes
<Warning>
Do not allowlist a subset of these IPs. Gumloop distributes traffic across all 24 addresses, and any individual request may originate from any one of them.
</Warning>
* **Region**: All IPs are located in `us-west1` (Oregon, USA).
* **Ports**: These IPs apply to all outbound traffic regardless of destination port. Most requests will be HTTPS (TCP 443), but the same IPs are used for any protocol or port.
* **Stability**: These IPs are static and will not change on a regular basis. Any changes will be reflected on this page.
## Related resources
<CardGroup>
<Card title="SSO: SAML, OIDC & SCIM" icon="key" href="/enterprise-features/sso_saml_oidc_scim">
Configure single sign-on and user provisioning
</Card>
<Card title="Audit logging" icon="clipboard-list" href="/enterprise-features/audit_logging">
Track user actions across your organization
</Card>
<Card title="Security & compliance" icon="shield-check" href="https://trust.gumloop.com/">
View our security certifications
</Card>
<Card title="Rate limits" icon="gauge-high" href="/core-concepts/rate_limits">
Understand platform rate limiting
</Card>
</CardGroup>
# Custom roles
Source: https://docs.gumloop.com/enterprise-features/user_groups
Custom Roles let admins control exactly which connectors, tools, scopes, and AI models each group of users can access. They also gate sensitive features and set per-user usage caps.
<Warning>
Managing Custom Roles requires the **Admin** or **Security** organization role.
</Warning>
## Key concepts
* **Additive membership** — a user can hold multiple custom roles. Their effective access is the union across all roles.
* **Default role** — every new member is auto-assigned to the default role. It cannot be deleted.
* **Restrictions compose least-restrictively** — a user is only blocked from something if **every** role they hold blocks it.
<Info>
Custom Roles **restrict** what a user can do. [Organization Roles](/core-concepts/organization_user_roles) **grant** authority (Admin, Manager, etc.). Both must allow an action for it to succeed.
</Info>
***
## Managing roles
Navigate to [gumloop.com/settings/organization/groups](https://www.gumloop.com/settings/organization/groups).
### Creating a role
A new role starts from one of three starting points, so you rarely have to configure it from scratch:
| Starter | Where it begins |
| - | - |
| **No access** | Everything restricted. Grant connectors, models, and features one by one. |
| **Full access** | Nothing restricted. Take away only what this group should not have. |
| **Copy of an existing role** | A duplicate of another role — its app, model, feature, and usage-limit configuration — that you then adjust. |
<Tip>Pick **Full access** when a group needs almost everything and only a few capabilities removed; picking **No access** for that job means re-granting every connector by hand.</Tip>
### Role tabs
Each role has the following tabs:
| Tab | Purpose |
| - | - |
| **Connectors** | Per-connector control over tools and scopes |
| **Models** | Which AI models users in this role can select |
| **Features** | Toggles for sensitive capabilities |
| **Usage Limits** | Per-user concurrency and credit caps |
| **Users** | Assign members to this role |
| **Settings** | Rename, restrict newly added integrations, set as default, or delete |
***
## Connectors tab
The **Connectors** tab is where you control which connectors your users can access and what they can do with each one. It consolidates **tools** and **scopes** into a single per-connector view.
### Overview
The main view shows all available connectors as cards. Each card shows its authentication type and the count of granted tools and scopes at a glance.
***
### Example: Configuring GitHub access
Let's walk through configuring GitHub access for a custom role.
**Step 1: Open the app**
Click the GitHub card (or click **Add Connector** and select GitHub). This opens the App Picker, where you can configure **Tools** and **Scopes**.
***
**Step 2: Configure Tools**
The Tools tab shows every agent tool available for this app. Toggle individual tools on or off.
* Use **Select all** / **Deselect all** for bulk changes
* Search for specific tools using the search bar
* Tools that are not selected will be blocked for users in this role
***
**Step 3: Configure Scopes**
The Scopes tab controls which OAuth scopes users in this role can grant when connecting the app.
* Only selected scopes can be authorized by users in this role
* Removing a scope may affect tools that depend on it
***
**Step 4: Save**
Click **Save** to apply your changes. The app card on the overview will update to reflect the new counts.
***
### Removing app access
To completely remove a role's access to an app, click the **three-dot menu** (⋯) on the app card and select **Remove access**.
This removes all tool and scope grants for that app from this role.
***
### How app restrictions compose
When a user is in **multiple roles**, app access composes with the least-restrictive rule:
| Scenario | Result |
| - | - |
| Role A grants 3 GitHub tools, Role B has no GitHub card | User gets **all** GitHub tools (B is silent) |
| Role A grants `repo` scope only, Role B has no GitHub card | User gets **all** scopes (B is silent) |
| Role A and Role B both only grant `repo` scope | User gets only `repo` scope |
| Role A removes app access entirely, Role B has no card | User is **unrestricted** (B is silent) |
<Note>
A role with no card for an app is "silent" on that app, meaning it does not restrict it. Only when **every** role a user holds explicitly restricts an app does the restriction apply.
</Note>
***
## Models tab
The **Models** tab controls which AI models users in this role can select — in the agent model picker. Models a role does not allow are hidden from the picker, so members can only choose from what they are permitted to use.
<Frame>
<img alt="Models tab showing an allow-list of AI models grouped by provider, with per-provider allowed counts, a search bar, and US-provider hosted badges" />
</Frame>
Models are grouped by provider (Anthropic, OpenAI, SpaceXAI, Google, and more) with a running **allowed** and **blocked** count in the header. You can:
* Toggle a whole provider on or off, or expand a provider to toggle individual models
* Search for a specific model or provider
* See a **US-provider hosted** badge on providers served by US-based providers under Zero Data Retention policies
Deprecated models are collapsed behind a **+N more deprecated models** link so the list stays focused on current models.
<Info>
A role's model list is **bounded by the organization's model access ceiling**. If a model is blocked org-wide on the [AI Model Governance](/enterprise-features/ai_model_control#restrictions) page, it cannot be granted to a role here, even if it appears selectable.
</Info>
<Note>
Clearing every model for a role is an explicit **deny-all** — users in that role (and no other role that allows models) will have no selectable models and fall back to the organization's configured fallback model.
</Note>
### How model access composes
Like apps, model access composes **least-restrictively** across a user's roles: a user can select a model if **any** role they hold allows it. A role that leaves its Models tab untouched is "silent" and does not restrict models.
At runtime, if a flow or agent references a model the user is no longer allowed to use, Gumloop falls back to the organization's [Fallback Model](/enterprise-features/ai_model_control#fallbacks) instead of failing.
***
## Features tab
Controls sensitive capabilities that are gated by default for non-admin members. A user gets a feature if **any** of their roles grants it.
<Frame>
<img alt="Features tab of a custom role listing sensitive capabilities with the Add Features button" />
</Frame>
| Feature | What it allows |
| - | - |
| **Team creation** | Create new teams within the organization |
| **Team credential addition** | Add credentials to teams the user has admin access to |
| **Agent email inbox management** | Enable, change, or disable email inboxes for agents |
| **Agent browser** | Give agents a [browser](/core-concepts/agent_browser) and use it on agents they run |
| **Agent incognito mode** | Run agent chats without saving messages to history |
| **Public flow and interface sharing** | Share flows and interfaces publicly |
| **External chat sharing** | Share chats outside the organization or publicly |
| **External artifact sharing** | Share files outside the organization or publicly |
| **External password-protected artifact sharing** | Share files outside the organization behind a [password](/core-concepts/agent_artifacts#password-protected-artifacts) |
| **Flow modification** | Create, update, or delete flows and workbooks |
| **Workflow incognito mode** | Run workflows without saving run data to history |
| **Agent modification** | Create, update, or delete agents |
| **Skill creation** | Create [skills](/core-concepts/skills) within the organization |
| **Agent-owned credentials** | Configure agents to use a pinned account or connection for everyone who can access the agent |
| **Brain access** | View and search [Brain](/core-concepts/brain) knowledge sources |
| **Brain source management** | Add, update, sync, share, or delete [Brain](/core-concepts/brain) sources |
<Info>
Features marked with a shield icon are denied by default for enterprise users unless explicitly granted. Others are allowed by default.
</Info>
<Note>
**Skill creation** covers *new* skills only. With it turned off, an agent that tries to save a new skill skips it and reports that skill creation has been restricted by your organization admin; editing skills that already exist is unaffected and stays governed by each skill's own access.
</Note>
***
## Usage limits tab
Per-user caps that override organization-wide defaults.
<Frame>
<img alt="Usage Limits tab of a custom role showing concurrent run, agent, and credit caps" />
</Frame>
| Cap | Effect |
| - | - |
| **Concurrent Run Limit** | Max simultaneous workflow runs per user |
| **Concurrent Agent Limit** | Max simultaneous agent interactions per user |
| **Monthly Credit Cap** | Max credits per billing month |
| **Credit Usage Notifications** | Email alerts at thresholds (50%, 80%, 100%) |
| **Per-Chat Credit Warnings** | Pause chat for approval when a single chat's spend crosses a threshold |
Caps compose by taking the **maximum** across a user's roles.
<Info>
Monthly credit caps can also be read and set programmatically, so an internal credit-management system can act as the control plane. See the [List](/api-reference/organization/list-role-credit-limits), [Get](/api-reference/organization/get-role-credit-limit), and [Set](/api-reference/organization/set-role-credit-limit) Custom Role Credit Limit API endpoints.
</Info>
### Per-chat credit warnings
Per-Chat Credit Warnings pause a user's chat for approval whenever the credit spend **in that single chat** crosses a threshold. This prevents runaway conversations from silently burning through credits.
<Frame>
<img alt="Per-Chat Credit Warnings section showing no warnings configured and a Configure button" />
</Frame>
Click **Configure** to open the threshold picker. Toggle the default thresholds (**5,000**, **10,000**, and **25,000** credits) or add a custom value.
<Frame>
<img alt="Per-Chat Credit Warnings configuration modal with default thresholds at 5,000, 10,000, and 25,000 credits and an Add custom threshold button" />
</Frame>
When a chat hits an enabled threshold, the agent pauses and creates an [Action Request](/core-concepts/human_in_the_loop) that the user (or an admin) must approve before the conversation continues.
<Info>
The default values are recommended to prevent runaway chats while ensuring normal usage is not interrupted.
</Info>
**Multi-role resolution:** thresholds compose by taking the **maximum** across all of a user's custom roles. For example, if a user belongs to Role A (warning at 5,000 credits) and Role B (warning at 10,000 credits), their chat will pause at **10,000** credits — the higher, least-restrictive value wins.
***
## Users tab
Assign members to this role. Adding a user here does **not** remove them from any other role.
***
## Settings tab
<Frame>
<img alt="Settings tab with role name, description, Restrict Newly Added Integrations toggle, default role, and delete" />
</Frame>
* **Role Name** and **Description** — rename the role and describe what it's for
* **Restrict Newly Added Integrations** toggle — *"Automatically block newly released integrations for this role until an admin approves them."*
* **Default Role** toggle — promotes this role to be the org's default
* **Delete Role** — irreversible; members fall back to the default role
### Restricting newly added integrations
Gumloop ships new integrations and MCP servers regularly, and by default they become available to your members as soon as they launch. Turning on **Restrict Newly Added Integrations** flips that default for this role: anything newly released is blocked for the role until an admin approves it.
<Steps>
<Step title="Turn it on">
Enable the toggle in the role's **Settings** tab. Existing access is untouched — it only applies to integrations released from that point on.
</Step>
<Step title="New integrations arrive blocked">
As Gumloop releases integrations, they are added to this role's blocked list automatically instead of becoming available.
</Step>
<Step title="Approve what you want">
An admin unblocks a specific integration for the role from the [**Connectors** tab](#connectors-tab), the same way any other connector access is granted.
</Step>
</Steps>
<Info>
Newly released integrations are added to the blocked list by a periodic job rather than the instant they ship, so there can be a short window before a brand-new integration appears in the role's list.
</Info>
<Tip>
There is also an organization-wide version of this setting. Instead of enabling the toggle role by role, it restricts newly released integrations for **every** custom role in the organization, including roles created after it is turned on.
</Tip>
<Warning>
Access is a union across roles: a user who is also in a role without this restriction still gets the new integration. To hold a new integration back from someone, every role they belong to has to block it.
</Warning>
***
## SCIM and IdP group sync
If your organization uses SCIM provisioning, IdP groups can be mapped to custom roles automatically.
<CardGroup>
<Card title="How it works" icon="rotate">
* IdP groups map to custom roles via a curated **mapping table** (or name-based mode)
* Users receive the **union** of every matched role — there is no priority
* Only mapped roles are added or removed. Unmapped role assignments stay as they are. New users with no match still get the **default role**.
</Card>
<Card title="Notes" icon="circle-info">
* A user in multiple mapped IdP groups is assigned **all** of the matched roles
* Team (project) sync is configured independently of the role direction
* With **Use mapping table** on, SCIM keeps a user's existing memberships when no mapped IdP group matches (clearing the table won't strip them)
</Card>
</CardGroup>
For full SCIM setup instructions, see [SSO: SAML, OIDC & SCIM](/enterprise-features/sso_saml_oidc_scim#scim-and-custom-roles-teams).
***
## FAQ
<AccordionGroup>
<Accordion title="What happens if a user is in multiple roles?" icon="layer-group">
* **Connectors**: access is the union. Blocked only if every role blocks it.
* **Models**: access is the union. A model is selectable if any role allows it.
* **Features**: granted if any role grants it.
* **Usage caps**: the highest value wins (including per-chat credit warning thresholds).
</Accordion>
<Accordion title="What does a 'silent' role mean?" icon="circle-question">
If a role has no card for an app, it has no opinion on that app. The user is unrestricted for that app by this role. Restrictions only apply when all roles agree.
</Accordion>
<Accordion title="Can I use the default role as a restrictive baseline?" icon="shield-halved">
Yes. Keep the default role restrictive, then create add-on roles that widen access for specific groups. A stricter additional role cannot narrow access already allowed by the default role or another assigned role. To remove access, change or remove the role that grants it.
</Accordion>
</AccordionGroup>
***
## See also
<CardGroup>
<Card title="Organization roles" icon="building" href="/core-concepts/organization_user_roles">
The authority side of Gumloop's permission model.
</Card>
<Card title="Connector policies" icon="shield-halved" href="/enterprise-features/app-policies/overview">
Block or tag specific tool calls and restrict OAuth domains.
</Card>
</CardGroup>
# How do I cancel my plan or free trial?
Source: https://docs.gumloop.com/help/account-billing/cancel-plan-or-trial
You can cancel your paid plan or 14-day Pro trial from **Manage Subscription** on the [Usage & Limits page](https://www.gumloop.com/settings/organization/limits) (Settings > Organization > Usage & Limits).
1. Open the [Usage & Limits page](https://www.gumloop.com/settings/organization/limits).
2. In the **Plan** card, select **Manage Subscription**. This opens the Stripe billing portal in a new tab.
3. Select **Cancel plan**, then confirm the cancellation.
<Frame>
<img alt="Plan card on the Usage & Limits page with the Manage Subscription button" />
</Frame>
Cancelling is never immediate: you keep access until the end of the current billing period or trial, and the Plan card shows a **Cancels** badge with that date.
<Note>You can also reach the billing portal from the **Manage your subscription** link at the bottom of any Gumloop receipt email.</Note>
## Cancelling the free trial
Every new account starts with a [14-day free trial of Pro](/core-concepts/credits). It requires a card and rolls into a paid Pro subscription when it ends, unless you cancel first.
Cancel any time before the trial ends using the steps above. Your card is not charged, and you keep Pro access for the rest of the trial. The Plan card shows when the trial ends, for example "Free trial ends Sep 19, 2026".
## What happens when your cancellation takes effect
Until your cancellation date, you can keep using Gumloop normally, including any remaining credits on your plan or trial. After that date:
* **Plan access ends:** Your Pro subscription or trial ends, and agents and workflows can no longer run unless you resubscribe.
* **Credits stop renewing:** Any remaining credits are available until the cancellation date. After that, your credit balance no longer resets.
* **Your work isn't deleted:** Your agents, workflows, skills, Brain sources, chats, and other workspace data stay in your account when you cancel.
* **You can resubscribe anytime:** Restart a subscription from the [Usage & Limits page](https://www.gumloop.com/settings/organization/limits) or the [pricing page](https://www.gumloop.com/pricing).
<Note>Deleting your account also cancels any subscription tied to it, so you will not be charged after the account is deleted.</Note>
## Refunds
Under our [Terms of Service](https://www.gumloop.com/tos), paid subscription fees are non-refundable except where required by law. The reliable way to avoid an unwanted charge is to cancel before the trial ends or before your next renewal date.
## Who can cancel
In an organization, only the [Admin](/core-concepts/organization_user_roles) role can open the billing portal. If you do not see **Manage Subscription**, ask an org admin.
<Warning>Enterprise plans are invoiced by contract, so the self-serve portal does not apply. Email [accounting@gumloop.com](mailto:accounting@gumloop.com) for plan changes.</Warning>
## Related
<CardGroup>
<Card title="Subscription management" icon="credit-card" href="/core-concepts/subscription_management">
Payment methods, billing details, and invoices
</Card>
<Card title="Where do I download my invoices?" icon="file-invoice" href="/help/account-billing/download-an-invoice">
Get a PDF invoice or receipt
</Card>
<Card title="Credits" icon="coins" href="/core-concepts/credits">
Plans, included credits, and overage
</Card>
<Card title="Billing questions" icon="envelope" href="mailto:accounting@gumloop.com">
Contact accounting about billing
</Card>
</CardGroup>
# Where do I download my invoices?
Source: https://docs.gumloop.com/help/account-billing/download-an-invoice
1. Open the [Usage & Limits page](https://www.gumloop.com/settings/organization/limits).
2. Select **Manage Subscription** in the Plan card.
3. Find the payment under invoice history and download the PDF invoice or receipt.
In an organization, only the [Admin](/core-concepts/organization_user_roles) role can open the billing portal. Enterprise invoices are handled directly by [accounting@gumloop.com](mailto:accounting@gumloop.com).
## Related
<CardGroup>
<Card title="Subscription management" icon="credit-card" href="/core-concepts/subscription_management">
Download invoices and manage your plan
</Card>
<Card title="Credits" icon="coins" href="/core-concepts/credits">
How credits and plans work
</Card>
</CardGroup>
# Account and Billing
Source: https://docs.gumloop.com/help/account-billing/index
Your plan, payment details, invoices, and cancellations all live behind **Manage Subscription** on the [Usage & Limits page](https://www.gumloop.com/settings/organization/limits). Full reference: [Subscription Management](/core-concepts/subscription_management).
In an organization, only the [Admin](/core-concepts/organization_user_roles) role can open the billing portal. Questions about invoices, payment methods, or procurement paperwork go to [accounting@gumloop.com](mailto:accounting@gumloop.com) rather than support.
# Do I need a connector to read Brain?
Source: https://docs.gumloop.com/help/brain/do-i-need-a-connector-to-read-brain
No. You never need your own connector to search or browse a Brain knowledge source, whatever app it is backed by (Google Drive, Slack, Notion, and so on).
Connectors and knowledge sources are separate systems:
| Feature | What it does | Whose credentials |
| - | - | - |
| [Connectors](/help/connectors) | Let agents take live actions as you (send email, post to Slack) | Yours |
| Brain knowledge sources | Index content so agents and search can read it | The person who set up the source |
The credential attached to a knowledge source is used only at **sync time**, by the source itself, to read documents and record their sharing settings. When you search or browse Brain, Gumloop never contacts the provider on your behalf and never uses your connectors.
If you cannot see documents in Brain, connecting your own account will not fix it. See [Why is a document missing from Brain?](/help/brain/why-is-a-document-missing) instead.
## FAQ
<AccordionGroup>
<Accordion title="I connected the same app as the source (say, Google Drive) and still cannot see its documents">
Expected. Your connector plays no part in Brain visibility. Check that the documents are shared with your Gumloop login email in the original system.
</Accordion>
<Accordion title="Does the source break if I disconnect my own account?">
No. Only the credential pinned to the source matters, and only for syncing. Disconnecting your own account changes nothing for readers.
</Accordion>
</AccordionGroup>
## Related
<CardGroup>
<Card title="Why is a document missing?" icon="file-magnifying-glass" href="/help/brain/why-is-a-document-missing">
Document access and email matching
</Card>
<Card title="Brain" icon="brain" href="/core-concepts/brain">
Full feature reference
</Card>
</CardGroup>
# How do agents use Brain?
Source: https://docs.gumloop.com/help/brain/how-do-agents-use-brain
Attach knowledge sources to an agent under **Knowledge Sources** in its configuration. Click **Add** to attach an existing source from your Personal, Team, or Organization Brain — or create a new one, including a plain file upload. The agent then searches those sources when answering.
Two things to know about what the agent can pull from:
* **Attaching is a sharing decision.** Everyone who uses the agent gets answers from its attached sources, even people who could not open those sources in Brain themselves. The exception is sources with Document access set to **Original source**: those still check each reader's own document permissions, so different users can get different answers from the same agent.
* **You can narrow each attachment.** An attached source is either **All files** or **Custom** — use Custom to uncheck folders or files the agent should not search, without changing the source itself or other agents using it.
Personal Brain sources attached to an agent work only in your own chats with it. To give the whole team the same knowledge, attach a team or organization source instead.
To detach a source, use **Remove** on its row in the agent's configuration. Deleting a source from Brain detaches it from every agent.
## FAQ
<AccordionGroup>
<Accordion title="The agent cannot find something that is in the source">
Check three things: the source has finished syncing (not a draft or failed), the attachment's Custom selection includes the folder the content lives in, and — for Original source mode — that the document is shared with your Gumloop login email. See [Why is a document missing?](/help/brain/why-is-a-document-missing)
</Accordion>
<Accordion title="Do agent answers from Brain cost credits?">
Yes — Brain searches are part of the agent's normal per-run credit usage.
</Accordion>
<Accordion title="Does someone using the agent need their own connector?">
No. Reading Brain never uses the reader's connectors. See [Do I need a connector to read Brain?](/help/brain/do-i-need-a-connector-to-read-brain)
</Accordion>
<Accordion title="A teammate says the agent finds nothing from Brain at all">
Their role may restrict Brain access — organization admins can deny it through custom roles. Ask an admin to check.
</Accordion>
</AccordionGroup>
## Related
<CardGroup>
<Card title="Do I need a connector to read Brain?" icon="plug" href="/help/brain/do-i-need-a-connector-to-read-brain">
Connectors vs knowledge sources
</Card>
<Card title="Personal vs team vs organization Brain" icon="layer-group" href="/help/brain/personal-team-org-brain">
Which scope to attach from
</Card>
</CardGroup>
# How often does Brain sync?
Source: https://docs.gumloop.com/help/brain/how-often-does-brain-sync
About every hour, automatically. Each sync picks up new documents, changed content, deletions, and permission changes from the original system. To update a source right now, open its three-dot menu and choose **Re-sync**.
Syncs are incremental for most sources: only new or changed documents are processed (and billed), so routine hourly syncs are fast and usually free. Direct file uploads never sync on a schedule — they only change when you add or remove files.
You can follow progress on the source's row and page:
| Status | Meaning |
| - | - |
| **Queued / Syncing** | A sync is waiting or running. Content indexed so far is already searchable. |
| **Active** | The last sync succeeded. |
| **Partial sync** | The last sync finished but skipped some documents. |
| **Sync failed** | The last sync stopped early. See [Why did my sync fail?](/help/brain/why-did-my-sync-fail) |
| **Paused** | Syncing is off until someone resumes the source. Brain also pauses a source automatically after 3 failed syncs in a row; see [Automatic pause after repeated failures](/help/brain/pause-resume-or-delete-a-source#automatic-pause-after-repeated-failures). |
Each source's page also keeps a history of past sync runs.
When you run a sync, you get an email when it finishes — always on failure, and on success only for syncs long enough that you have probably stopped watching. Automatic scheduled syncs do not send success emails.
## FAQ
<AccordionGroup>
<Accordion title="Can I change how often a source syncs?">
Not from the product today. If hourly is too frequent for a source, pause it and Re-sync manually when you want updates. For anything else, [contact support](https://portal.usepylon.com/gumloop/forms/help).
</Accordion>
<Accordion title="Does every hourly sync cost credits?">
Only when it finds new or changed documents. Unchanged documents are never re-indexed or re-billed.
</Accordion>
<Accordion title="Why is Re-sync grayed out?">
A sync is already running, or the source is still a draft awaiting estimate approval.
</Accordion>
<Accordion title="I edited a document. When does search reflect it?">
On the next sync of that source — within the hour, or immediately after a manual Re-sync.
</Accordion>
</AccordionGroup>
## Related
<CardGroup>
<Card title="Why did my sync fail?" icon="circle-exclamation" href="/help/brain/why-did-my-sync-fail">
Failure reasons and fixes
</Card>
<Card title="When do permission changes show up?" icon="arrows-rotate" href="/help/brain/when-do-permission-changes-show-up">
Sync timing for access changes
</Card>
</CardGroup>
# Brain
Source: https://docs.gumloop.com/help/brain/index
Brain indexes your team's knowledge sources (Google Drive, Slack, Notion, and more) so agents and search can answer from your real content. Full reference: [Brain](/core-concepts/brain).
# How do I pause, resume, or delete a source?
Source: https://docs.gumloop.com/help/brain/pause-resume-or-delete-a-source
Use the three-dot menu on the source's row. Alongside **Re-sync**, **Rename**, and **Control Access**, it has:
* **Pause** — stops all syncing, including scheduled syncs. A sync that is running stops where it is. Everything already synced **stays searchable**; pausing only freezes updates, so new documents and permission changes stop flowing in.
* **Resume** — turns syncing back on. Run **Re-sync** afterwards to catch up immediately instead of waiting for the next scheduled sync.
* **Delete** — removes the source and everything synced from it. Its documents disappear from search and from any agents it was attached to. This cannot be undone; you can always add the source again, but it will re-estimate and re-index from scratch.
## Automatic pause after repeated failures
Brain pauses a source on its own when its **last 3 syncs in a row failed** for a reason on the source's side:
| Reason | What to do |
| - | - |
| The source rejected the saved connection | Reconnect the source to resume syncing. |
| The account has no credits left for Company Brain | Add credits, then resume syncing from the source page. |
| Part of the source could not be read | Check the source's access and settings, then resume syncing from the source page. |
When this happens:
* The source page explains why, for example: *"Syncing is paused because the last 3 syncs failed: the source rejected the saved connection. Reconnect the source to resume syncing."*
* The person who added the source gets an email that lets them resume syncing.
* Like a manual pause, scheduled syncs stop and everything already synced stays searchable.
Only full failures count toward the 3. Partial syncs, failures on Gumloop's side (such as the system being under heavy load), and syncs from before the source was last resumed do not. Fix the cause before resuming; otherwise the next syncs fail the same way.
## Can I move a source to a different Brain?
There is no move action. To relocate a source (say, from your personal Brain to a team's), add it fresh in the target Brain and delete the old one. To let more people use an organization source without moving it, use **Control Access** to share it with more teams instead.
## FAQ
<AccordionGroup>
<Accordion title="Does pausing hide the source from search?">
No. Paused sources keep serving what was already synced — results just get staler over time. Delete the source if you want its content gone.
</Accordion>
<Accordion title="Why is a source paused when nobody paused it?">
Its last 3 syncs failed on the source's side, so Brain [paused it automatically](#automatic-pause-after-repeated-failures). The source page shows the reason and how to fix it.
</Accordion>
<Accordion title="I paused during a sync. Is the partial content searchable?">
Yes. Whatever synced before the pause is searchable, and the rest is picked up after you resume and sync again.
</Accordion>
<Accordion title="What happens to agents using a deleted source?">
The source is detached and agents simply stop finding its content. Other attached sources keep working.
</Accordion>
<Accordion title="Who can pause or delete a source?">
Whoever can manage that source's Brain — see [Personal vs Team vs Organization Brain](/help/brain/personal-team-org-brain).
</Accordion>
</AccordionGroup>
## Related
<CardGroup>
<Card title="How often does Brain sync?" icon="clock" href="/help/brain/how-often-does-brain-sync">
What Re-sync and scheduled syncs do
</Card>
<Card title="Personal vs team vs organization Brain" icon="layer-group" href="/help/brain/personal-team-org-brain">
Scopes and who can manage sources
</Card>
</CardGroup>
# Personal vs team vs organization Brain
Source: https://docs.gumloop.com/help/brain/personal-team-org-brain
Every knowledge source has a **scope** that decides who can see and search it, and each scope has its own rules for who can add and manage sources.
| Scope | Who can see and search it | Who can add and manage sources |
| - | - | - |
| **Personal** | Only you | Anyone, for their own personal Brain |
| **Team** | Members of that team | Team admins |
| **Organization** | Everyone in the organization, or only the teams the source is shared with | Organization admins and managers |
## Personal Brain
Your private space, at **Personal > Brain**. Sources you add here are visible only to you, and every member can add their own. Agents you attach a personal source to can use it only in your own chats.
## Team Brain
Lives on each team's page. Sources here are visible to all members of that team, so one teammate can index a shared Drive folder or Slack channel once for the whole team. Adding and managing team sources requires a **team admin** role on that team (this applies to organization admins too). Regular team members can search but not add.
## Organization Brain
Managed at **Settings > Organization > Brain**. Sources here can be shared with the entire organization or restricted to specific teams, chosen when the source is added. Adding and managing them requires an organization **admin** or **manager** role. This is where company wide knowledge (policies, handbooks, the shared Drive) usually lives, set up once for everyone.
<Note>Whatever the scope, you must be a member of the owning organization to see a source. Being added to a team without joining its organization is not enough. Custom roles can also restrict Brain access or source management further.</Note>
## FAQ
<AccordionGroup>
<Accordion title="I want my whole team to search a folder I indexed personally">
Personal sources stay personal. Add the source to the team's Brain instead (or ask a team admin to), or ask an admin to add it at the organization level.
</Accordion>
<Accordion title="I am a team member and cannot add a source to the team">
Adding team sources requires a team admin role on that team. Ask one of the team's admins.
</Accordion>
<Accordion title="Can an organization source be hidden from some teams?">
Yes. When adding an organization source you can share it with everyone or restrict it to specific teams.
</Accordion>
<Accordion title="Does scope decide who sees every document in the source?">
Scope is the first gate. Sources with Document access set to Original source additionally check each document's own permissions in the original system. See [Why is a document missing from Brain?](/help/brain/why-is-a-document-missing)
</Accordion>
</AccordionGroup>
## Related
<CardGroup>
<Card title="Why can't I see a knowledge source?" icon="eye-slash" href="/help/brain/why-cant-i-see-a-knowledge-source">
Org and team membership checks
</Card>
<Card title="Brain" icon="brain" href="/core-concepts/brain">
Full feature reference
</Card>
</CardGroup>
# How do I sync only certain folders?
Source: https://docs.gumloop.com/help/brain/sync-only-certain-folders
When adding a source, under **What to sync** choose **Select what to sync** instead of **Sync everything**, then check exactly what you want. For Slack the options are **Every channel the app is in** or **Only channels I pick**.
The checkboxes nest both ways:
* Checking a folder includes everything inside it, including content added later.
* You can uncheck a specific subfolder or file inside a checked folder to leave it out.
* You can also check a specific child inside an unchecked folder to bring just that item in.
**Sync everything** indexes the whole source, including content added later. **Select what to sync** indexes only what you check — new content appears only if it lands inside something you checked.
## Changing the selection later
Open the source, go to its files, and use **Edit** to adjust the selection, then **Save**. Changes apply on the next sync: newly included content is indexed, and newly excluded content is removed from search. If a sync cannot finish applying a scope change, everything stays searchable and the rest is applied on the following sync.
## FAQ
<AccordionGroup>
<Accordion title="I excluded a folder but its files still show in search">
Scope changes apply on the next sync. Run **Re-sync** from the source's menu to apply them now.
</Accordion>
<Accordion title="Does narrowing the selection save credits?">
Yes. Excluded content is never downloaded or indexed, so it costs nothing. Narrowing a source before approving its estimate lowers the estimate too.
</Accordion>
<Accordion title="I re-included a folder I had excluded">
Its content is indexed again on the next sync.
</Accordion>
<Accordion title="Can I scope what a single agent sees without changing the source?">
Yes. An attached knowledge source can be narrowed per agent — see [How do agents use Brain?](/help/brain/how-do-agents-use-brain)
</Accordion>
</AccordionGroup>
## Related
<CardGroup>
<Card title="What does Pending approval mean?" icon="coins" href="/help/brain/what-does-pending-approval-mean">
Estimates and credits
</Card>
<Card title="Why is a document missing?" icon="file-magnifying-glass" href="/help/brain/why-is-a-document-missing">
Permission-based reasons
</Card>
</CardGroup>
# What does pending approval mean?
Source: https://docs.gumloop.com/help/brain/what-does-pending-approval-mean
New sources do not start syncing (or spending credits) right away. Brain first runs a free estimate pass — it lists the source's documents and estimates the credits a full sync would cost — and waits for someone to approve before indexing anything.
The source moves through these statuses:
1. **Estimating** — Brain is fetching and measuring documents. Nothing is billed yet. You will be notified when the estimate is ready.
2. **Pending approval** — the estimate is ready. Open the source to review the document count and estimated cost, shown as **\~N credits**.
3. **Active** — someone clicked **Approve and sync**; the real sync runs and indexing credits are charged.
The person who added the source gets an email and an inbox notification when the estimate is ready. Anyone who can manage the source can approve it.
## How the estimate is calculated
Brain lists every document in the source, then measures a **sample of 50 documents** and extrapolates from that sample to the full document count. This keeps estimates fast on large sources, since Brain does not have to download the whole source to price it.
If none of the sampled documents could be read, the estimate stops instead of offering an estimate of zero credits: *"The cost estimate stopped because none of the sampled documents could be read. Check the source's access and settings, then start the sync again."*
## Estimates expire after 30 days
An estimate that nobody approves expires **30 days** after it was ready. The source then shows: *"This estimate expired before it was approved. Start the sync again to get a new estimate."* Nothing is indexed or billed for an expired estimate.
## Changing what's estimated
If the estimate looks too high, use **Edit selection** to narrow what's synced — the source re-estimates with the smaller selection. You can also choose **Skip estimate and sync now** to start syncing without waiting for the estimate.
## What credits does Brain use?
* **Indexing** is charged when documents are actually indexed: on the first sync after approval, and afterwards only for new or changed documents. Unchanged documents are never re-charged on routine syncs.
* **Searching** Brain (including agents answering from it) uses credits per query, like other AI usage.
The estimate is a heuristic, rounded up to the nearest 5 credits — actual cost is billed on what is really indexed.
## FAQ
<AccordionGroup>
<Accordion title="Can I search the source before approving?">
No. Nothing is indexed until the source is approved, so search returns nothing from it.
</Accordion>
<Accordion title="The status says Estimate failed">
Open the source and click **Retry**, or **Skip and sync now** to proceed without an estimate.
</Accordion>
<Accordion title="Why doesn't the estimate match what I was billed?">
The estimate is extrapolated from a 50-document sample, so the actual cost depends on the documents that are really indexed. You are billed on what is actually indexed, not on the estimate.
</Accordion>
<Accordion title="My estimate expired">
Unapproved estimates expire after 30 days. Start the sync again to get a new estimate.
</Accordion>
<Accordion title="Will the hourly sync keep charging me?">
Only for new or changed documents. A sync that finds nothing new costs no indexing credits.
</Accordion>
<Accordion title="Who pays for Brain credits?">
Credits come from the organization's balance, like other usage. See [Credits](/help/credits) for how balances work.
</Accordion>
</AccordionGroup>
## Related
<CardGroup>
<Card title="Sync only certain folders" icon="folder-tree" href="/help/brain/sync-only-certain-folders">
Narrow the source to lower the cost
</Card>
<Card title="Credits" icon="coins" href="/help/credits">
How credits and balances work
</Card>
</CardGroup>
# When do permission changes show up?
Source: https://docs.gumloop.com/help/brain/when-do-permission-changes-show-up
After the next sync of the source. Brain captures each document's sharing settings at **sync time**, not live. Run a manual sync to see a permission change immediately, or wait for the next scheduled sync (typically hourly).
To sync manually, open the knowledge source in Brain and use its sync action. Once the sync finishes, the updated permissions apply right away in search, browse, and agent answers.
## FAQ
<AccordionGroup>
<Accordion title="I synced right after sharing a big folder and some files are still hidden">
Some providers propagate container level permissions to individual documents gradually, so a sync run immediately after sharing can catch documents mid update. Wait a few minutes and sync again.
</Accordion>
<Accordion title="Do I need to re sync for a new person to see already indexed documents?">
Only if the sharing changed in the original system. If the documents were already shared with them at the last sync, access applies immediately once they can see the source.
</Accordion>
<Accordion title="I revoked someone's access in the original system. When does Brain stop showing them the document?">
At the next sync of that document. Run a manual sync to apply it immediately.
</Accordion>
</AccordionGroup>
## Related
<CardGroup>
<Card title="Why is a document missing?" icon="file-magnifying-glass" href="/help/brain/why-is-a-document-missing">
Document access rules
</Card>
<Card title="Brain" icon="brain" href="/core-concepts/brain">
Sync and sources reference
</Card>
</CardGroup>
# Why can't I see a knowledge source?
Source: https://docs.gumloop.com/help/brain/why-cant-i-see-a-knowledge-source
To see a knowledge source you must be a member of the **organization that owns it**, not just the team it is shared with.
Check these in order:
1. **Are you in the owning organization?** Being added to a team does not make you an organization member. If you are on the team but outside the organization, Brain intentionally shows you nothing from that source, because the organization's access settings cannot apply to you.
2. **Are you in the team the source is shared with?** Team scoped sources are visible to team members. Ask the source owner which team it lives in.
3. **Does your role allow Brain access?** Organization admins can restrict Brain access through roles and permissions. If the first two check out, ask your admin.
## FAQ
<AccordionGroup>
<Accordion title="I was invited to the team but Brain is empty">
Confirm you are a member of the same organization as the team. A team invite alone is not enough.
</Accordion>
<Accordion title="I can see the source but not all of its documents">
That is a different layer. See [Why is a document missing from Brain?](/help/brain/why-is-a-document-missing)
</Accordion>
</AccordionGroup>
## Related
<CardGroup>
<Card title="Personal vs team vs organization Brain" icon="layer-group" href="/help/brain/personal-team-org-brain">
Scopes and who can add sources
</Card>
<Card title="Add someone to an org or team" icon="user-plus" href="/help/sharing/add-someone-to-org-or-team">
Membership setup
</Card>
<Card title="Brain" icon="brain" href="/core-concepts/brain">
How Brain access works
</Card>
</CardGroup>
# Why did my sync fail?
Source: https://docs.gumloop.com/help/brain/why-did-my-sync-fail
Open the source and read the message under its status badge — every failure shows a plain-language reason and the fix. **Sync failed** means the sync stopped early; **Partial sync** means it finished but some documents could not be synced. In both cases, everything that did sync is already searchable.
The most common reasons:
1. **The source's credentials were rejected.** The account that set up the source lost access or its connection expired. Reconnect the source, then run **Re-sync** from the source's menu.
2. **The system was temporarily under heavy load.** Nothing is wrong with the source. Run the sync again; if it was a scheduled sync, it retries automatically on the next run.
3. **Some documents couldn't be synced.** The source page lists each affected document with the reason. Temporary issues retry automatically on the next sync; documents the provider refuses to share (unsupported formats, revoked access) stay skipped until that changes.
4. **Group membership could not be read** (sources with Document access set to Original source). Files shared through groups may be hidden from search until an organization admin checks the organization's directory connection, or the source is reconnected with an account that can view users and groups.
5. **The source was paused mid-sync.** Not an error — resume the source and sync again.
If a source's last **3 syncs in a row** fail on the source's side (rejected connection, no credits left for Company Brain, or part of the source can't be read), Brain pauses the source and emails the person who added it. See [Automatic pause after repeated failures](/help/brain/pause-resume-or-delete-a-source#automatic-pause-after-repeated-failures).
Whoever ran the sync also gets a failure email with the same reason, so you do not have to watch the page.
## FAQ
<AccordionGroup>
<Accordion title="What is the difference between Sync failed and Partial sync?">
Sync failed means the run stopped before finishing. Partial sync means the run completed, but specific documents were skipped — open the source to see which ones and why.
</Accordion>
<Accordion title="Do skipped documents fix themselves?">
Documents skipped for temporary reasons are retried on the next sync automatically. Documents skipped because the provider would not hand them over stay skipped until the underlying cause is fixed.
</Accordion>
<Accordion title="What happens to a document the source denies access to?">
It is hidden from search, not deleted. If the source shares it again on a later sync, Brain re-indexes it with fresh content and permissions. If access is still denied after 30 days, the hidden copy is removed. See [Why is a document missing?](/help/brain/why-is-a-document-missing#documents-the-source-denies-access-to)
</Accordion>
<Accordion title="The sync failed. Is my existing content gone?">
No. A failed sync never removes what was already indexed — search keeps working with the content from the last successful sync.
</Accordion>
<Accordion title="It keeps failing after a retry">
Reconnect the source's credentials and check its settings. If it still fails, [contact support](https://portal.usepylon.com/gumloop/forms/help).
</Accordion>
</AccordionGroup>
## Related
<CardGroup>
<Card title="How often does Brain sync?" icon="clock" href="/help/brain/how-often-does-brain-sync">
Automatic and manual syncs
</Card>
<Card title="Why is a document missing?" icon="file-magnifying-glass" href="/help/brain/why-is-a-document-missing">
Permission-based reasons
</Card>
</CardGroup>
# Why is a document missing from Brain?
Source: https://docs.gumloop.com/help/brain/why-is-a-document-missing
For sources with **Document access** set to **Original source**, you only see documents you could open in the original system, matched by the email you log into Gumloop with.
Check these:
1. **Your access in the original system must be tied to your Gumloop login email.** Brain matches you by that email. If the document is shared with a different address (a personal account instead of the one you use for Gumloop), it stays hidden. The two must match exactly.
2. **Access must be identity based.** Brain mirrors permissions it can attribute to specific people: direct shares, groups it can resolve, or domain wide access. Possession based access does not count, because the provider cannot tell us who holds it. For example, a Google Drive file shared as "anyone with the link" stays hidden even though the link works in Drive. This is a security decision, not a bug: rather than guess, Brain hides the document.
3. **Inherited access counts, but verify it actually covers the document.** Sharing a container (for example, a Google Drive folder) covers what is inside it. If a document is still missing, check its sharing details in the original system and confirm you appear in its access list, even as inherited access. Documents outside the shared container are not covered.
4. **Permission changes need a sync.** Access is captured when the source syncs, not live. See [When do permission changes show up?](/help/brain/when-do-permission-changes-show-up)
5. **The document may be excluded or skipped.** The source owner may have scoped the source to specific folders or items, and files that fail to process are skipped. Owners can review skipped documents on the source's status page.
## Documents the source denies access to
When a sync is refused access to a document that was already indexed (for example, the account that connected the source lost access to it), Brain **quarantines** the document instead of deleting it:
* The document is hidden from search during that sync and shows as skipped on the source's page.
* If the source hands the document back on a later sync, Brain indexes it again with fresh content and permissions.
* If access is still denied after **30 days**, the hidden copy is removed for good.
Temporary errors, such as a provider rate limit, are different: Brain keeps serving the indexed copy and retries the document on the next sync.
## FAQ
<AccordionGroup>
<Accordion title="The document is publicly reachable by link and I still cannot see it">
Expected. Ask for identity based access in the original system, or ask the source owner to switch the source's Document access to Gumloop access if the whole source should follow Gumloop permissions instead.
</Accordion>
<Accordion title="I was just given access and see nothing">
Run a manual sync on the source, or wait for the next scheduled sync. Some providers also propagate container level shares to individual documents gradually, so a sync run immediately after sharing can miss a few. Sync again a bit later.
</Accordion>
<Accordion title="A document shows in search for a teammate but not me">
Your access in the original system differs. Compare what each of you sees in the document's sharing details there.
</Accordion>
<Accordion title="I got access through a group and still cannot see the document">
Brain can only honor groups it can resolve to members. For Google Drive this requires the organization's Workspace directory connection. Ask your admin to check it.
</Accordion>
</AccordionGroup>
## Related
<CardGroup>
<Card title="When do permission changes show up?" icon="arrows-rotate" href="/help/brain/when-do-permission-changes-show-up">
Sync timing
</Card>
<Card title="Brain" icon="brain" href="/core-concepts/brain">
Document access reference
</Card>
</CardGroup>
# Add team connectors
Source: https://docs.gumloop.com/help/connectors/add-team-connectors
Team connectors belong to the **team**, not to one person. Use them for a shared inbox, CRM, or Slack workspace.
## Why use them
* Everyone on the team can run agents against the same account.
* People do not have to connect their personal Gmail or Salesforce.
* You can revoke the shared connection in one place.
## From the sidebar
1. On the [Home page](https://www.gumloop.com/hub), expand the team in the sidebar.
2. Click **Connectors**.
3. Find the app under **Discover** or **All**, click **Add**, and sign in with the shared account. Non-admins see **Request** instead, which asks a team admin to connect it.
<Frame>
<img alt="Team section in the sidebar with Agents, Brain, Skills, Artifacts, Connectors, Tasks, Vault, and Workflows" />
</Frame>
<Frame>
<img alt="Team Connectors page with Discover, All, and Connected tabs and a searchable list of connectors" />
</Frame>
## From organization settings
1. Go to [Organization > Teams](https://www.gumloop.com/settings/organization/teams).
2. Open the team, then click **Manage Connectors**.
3. Find the app and click **Add**.
## Who can add them
Team owners and members with permission to manage team connectors. Organization members who are not on the team cannot use that team's connectors.
<Note>
A team connector only works for agents that live **on that team**. Personal-space agents cannot see it until you [move the agent](/help/connectors/use-team-connectors).
</Note>
## Related
<CardGroup>
<Card title="Use team connectors" icon="right-left" href="/help/connectors/use-team-connectors">
Point an agent at the shared account
</Card>
<Card title="Connectors" icon="plug" href="/core-concepts/credentials">
Personal vs team
</Card>
</CardGroup>
# Find your Gumloop API key
Source: https://docs.gumloop.com/help/connectors/find-your-api-key
Your Gumloop API key authenticates [the API](/api-reference/authentication), the [CLI](/cli/authentication), and the SDKs. It is **not** an LLM provider key. For those, see [Use your own LLM key](/help/connectors/use-your-own-llm-key).
## Create or view the key
1. Go to [Connectors](https://www.gumloop.com/settings/profile/connectors?view=connected) (or [Settings → Profile → Connectors](https://www.gumloop.com/settings/profile/connectors?view=connected)).
2. Click **Add Connector** and search for **Gumloop API Key**.
3. Click **Generate API Key**.
4. Copy the key and store it somewhere safe. You can reveal, copy, or regenerate it later.
The [API authentication](/api-reference/authentication) page links to the same key.
## Personal vs team
| | Personal key | Team key |
| - | - | - |
| Acts as | You | Any team member (set `user_id` per request) |
| Default credentials | Your personal connectors | Each workflow step's Personal Default or Team Default |
| Use when | Local CLI, solo scripts | Team automations, CI/CD |
Do not paste a personal key into a shared CI secret if a team key will do.
## FAQ
<AccordionGroup>
<Accordion title="What happens if I regenerate the key?">
The old key stops working immediately. Update the CLI, GitHub Actions, and any SDK clients.
</Accordion>
<Accordion title="Is this the same as an OpenAI or Anthropic key?">
No. This key authenticates Gumloop's API. Provider keys go on [Use your own LLM key](/help/connectors/use-your-own-llm-key).
</Accordion>
</AccordionGroup>
## Related
<CardGroup>
<Card title="API authentication" icon="key" href="/api-reference/authentication">
How to send the key
</Card>
<Card title="CLI authentication" icon="terminal" href="/cli/authentication">
`gumloop auth`
</Card>
</CardGroup>
# Connectors
Source: https://docs.gumloop.com/help/connectors/index
Connectors are how Gumloop authenticates Gmail, Slack, Salesforce, and other apps. Full reference: [Connectors](/core-concepts/credentials).
# Revoke and reconnect a connector
Source: https://docs.gumloop.com/help/connectors/revoke-and-reconnect
Do this when the agent says a connector is disconnected, read-only, or still using an old account after you signed in again.
## Steps
1. Open the right Connectors page:
* Personal: [Settings → Connectors](https://www.gumloop.com/settings/profile/connectors?view=connected)
* Team: the team's Connectors page
* Org LLM keys: [Organization → API keys](https://www.gumloop.com/settings/organization/api-keys)
2. Open the connector menu and choose **Revoke**.
<Frame>
<img alt="Revoke connector menu" />
</Frame>
3. Click **Connect** and sign in with the account you want.
4. Re-attach it on the agent. Adding it in Settings is not enough. See [Give an agent a connector](/help/using-agents/give-agent-access-to-a-connector).
<Tip>
If the agent still looks read-only, confirm you picked the new account in the three-dot menu, not the revoked one.
</Tip>
## Related
<CardGroup>
<Card title="Connectors" icon="plug" href="/core-concepts/credentials">
How connections work
</Card>
<Card title="Use team connectors" icon="right-left" href="/help/connectors/use-team-connectors">
Point the agent at the new account
</Card>
</CardGroup>
# Use team connectors
Source: https://docs.gumloop.com/help/connectors/use-team-connectors
Team connectors only appear on agents that live in that team.
## Existing personal agent
1. On the [Home page](https://www.gumloop.com/hub), open the agent's **⋮** menu and choose **Move to Team**. Or open the agent and use **Move to Team** there.
2. Pick the destination team.
<Frame>
<img alt="Move an agent to a team" />
</Frame>
3. Open the connector's three-dot menu.
4. Choose **Use Team Default** or **Use Specific Account**. See [Choose which account to use](/core-concepts/credentials#in-agents).
## New agent
Create the agent **inside the team**, add the connector, and pick the team account from the start.
## Good to know
* **Use Personal Default** still uses each runner's own account. That is usually what you want for Gmail.
* **Use Team Default / Specific Account** is for a shared inbox or CRM.
* Changing a team agent's connector affects everyone. Confirm before you save.
## Related
<CardGroup>
<Card title="Connectors" icon="plug" href="/core-concepts/credentials">
Pin a personal or team account
</Card>
<Card title="Add team connectors" icon="users" href="/help/connectors/add-team-connectors">
Connect the shared account first
</Card>
</CardGroup>
# Use your own LLM key
Source: https://docs.gumloop.com/help/connectors/use-your-own-llm-key
Bring-your-own-key (BYOK) lets you send model calls through your own provider key.
You need an OpenAI, Anthropic, Google AI, Perplexity, SpaceXAI (xAI), or Fireworks account.
## What it changes
* Model calls that the key can serve cost **0 credits**.
* Image generation and transcription that the key covers are also free of model credits.
* Agent chats on BYOK use a **16% orchestration fee** (instead of 8%) on the run's value. That is still usually cheaper.
* A key only covers models that provider can serve. A Fireworks key does **not** cover every open model in the picker. See [AI Models](/core-concepts/ai_models).
## Where to add the key
| Plan | Where |
| - | - |
| Standard | Personal [Connectors](https://www.gumloop.com/settings/profile/connectors?view=connected), or a shared team key |
| **Enterprise** | [Organization → API keys](https://www.gumloop.com/settings/organization/api-keys). Org keys override personal and team keys. You can also route through a custom proxy. |
Non-Enterprise users cannot set org-level keys.
## Steps
1. Open the page in the table above.
2. Click **Add Key** (or connect the provider).
3. Paste the provider API key and save.
4. Run a short agent chat on a model that key covers.
5. Select the credit count in the chat header. Model credits for that call should be 0.
<Note>
Enterprise admins can hide models and map names. See [AI Model Governance](/enterprise-features/ai_model_control).
</Note>
## Related
<CardGroup>
<Card title="AI models" icon="microchip" href="/core-concepts/ai_models">
Which keys cover which models
</Card>
<Card title="Credits" icon="coins" href="/core-concepts/credits">
BYOK and orchestration fees
</Card>
</CardGroup>
# Credits
Source: https://docs.gumloop.com/help/credits/index
Inside an organization, usage comes from the shared credit pool. See [Credits](/core-concepts/credits) for how a run is priced.
Questions about invoices, payment methods, or procurement paperwork go to [accounting@gumloop.com](mailto:accounting@gumloop.com) rather than support.
For invoices, payment details, and cancellations, see [Account and Billing](/help/account-billing).
# How do I reduce agent credit spend?
Source: https://docs.gumloop.com/help/credits/reduce-agent-credit-spend
Find the agents that spend the most, then fix those agents. This page is about **agents**. How a chat is priced: [Credits](/core-concepts/credits).
<CardGroup>
<Card title="1. Find the spend" icon="magnifying-glass" href="#1-find-the-spend">
Usage & Limits on every plan. Insights on Enterprise.
</Card>
<Card title="2. Lower it per agent" icon="sliders" href="#2-lower-it-per-agent">
Skills, model, context, unused work, then BYOK.
</Card>
</CardGroup>
***
## 1. Find the spend
| Who | Where | What to do |
| - | - | - |
| Anyone | [Settings > Profile > Usage & Limits](https://www.gumloop.com/settings/profile/usage-limits) | Stay on **Grouped view**. Filter **Agent Chats**. Open high-cost rows. Many have a **View** link. |
| Admin or manager | [Settings > Organization > Usage & Limits](https://www.gumloop.com/settings/organization/limits) | Same logs for everyone, plus a **User** column. |
| Enterprise (**Admin**, **Manager**, or **Analytics**) | [Settings > Organization > Insights](https://www.gumloop.com/settings/organization/insights) | **Overview** (top agents). **Agents** (ranked by credits). **Explorer** (group by agents or members). **Agent** in the toolbar to ask in plain language. |
In any chat, select the credit count next to the name. You will see **Chat & Reasoning**, **Tool Calls**, **Compute**, **Orchestration Fee**, and any other types that chat was charged for.
[Where to see what a chat cost](/core-concepts/credits#where-to-see-what-a-chat-cost) · [Organization Insights](/enterprise-features/organization_insights)
***
## 2. Lower it per agent
Work the expensive agents first.
| Do this | When it helps |
| - | - |
| [Add a skill](#add-a-skill) | No playbook — it guesses every chat |
| [Check the model](#check-the-model) | Pinned to a frontier model, or on **Auto** |
| [Cut what it reads](#cut-what-it-reads) | Long threads or too many connectors |
| [Stop unused work](#stop-unused-work) | Triggers, evaluations, or reflections you do not need |
| [Ask the agent](#ask-the-agent) | You want it to find retries and save the fix |
| [Use your own key](#use-your-own-key) | Optional. You already pay a model provider |
***
### Add a skill
Most agents have no skills. Without a playbook, the agent guesses your process every chat — extra tool calls, extra retries, extra tokens.
1. Open the agent’s **Skills** section.
2. Select **+ Skill**.
3. After a chat that went well, tell it: *“Turn this into a skill”* or *“Update your instructions so you always do it this way.”*
It sees names and descriptions up front. It only loads the full playbook when it needs it.
<Tip>
If instructions are more than about 200 words and do not apply to every conversation, put them in a skill — not the system prompt. The system prompt is always loaded in full.
</Tip>
[Agent Skills](/core-concepts/skills) · [Self-improving instructions](/core-concepts/agents#self-improving-instructions)
***
### Check the model
Open the model dropdown at the top of the **Agent** tab.
| Choice | When it helps |
| - | - |
| **Recommended** | Everyday work. Start here. |
| **Smartest** | Only when the task needs deep reasoning |
| **Auto** | Messages that vary a lot. Gumloop picks a model per message. |
| A specific cheaper model | You have pinned a frontier model and the work is simple |
**Auto** is Gumloop’s model router, not a provider model. It already aims for the cheapest tier that should still do the job, and it can move up mid-run. Pinning a cheaper model on an Auto agent is not always a win: easy messages may already be cheap, and hard ones may get worse.
If you pin a model, pick the smallest one that still does the work.
[Choose the Right AI Model](/help/using-agents/choose-the-right-ai-model) · [Auto](/core-concepts/ai_models#auto-let-gumloop-choose-the-model)
***
### Cut what it reads
**Chat & Reasoning** is usually most of the bill. Longer chats and extra tools both add tokens.
| Change | Why |
| - | - |
| Connect only the connectors it needs | Every tool definition is added to the prompt |
| Start a **new chat** for a new topic | Old context is not carried forward |
| Watch the **context usage meter** (bottom-right of the chat input) | Hover it for System, Tools, Skills, and Conversation |
| On GPT-5.6 and Grok 4.5/4.6, pick the smaller **Context Window** | Keeps chats under the long-context price boundary |
**Context Window** is on **Settings → Advanced AI**.
[Connectors](/core-concepts/agents#connectors) · [Context usage meter](/core-concepts/agents#context-usage-meter) · [Short vs. long context windows](/core-concepts/agents#context-window)
***
### Stop unused work
| Turn off | How |
| - | - |
| Unused triggers | **Deactivate** so they do not fire or poll |
| Evaluations | They spend credits as AI utilities |
| Reflections | They spend credits like other agent work |
Leave evaluations and reflections on if they are useful.
[Stop a Scheduled Trigger](/help/triggers/stop-a-scheduled-trigger) · [Evaluations](/core-concepts/evaluations#credits-and-costs) · [Reflections](/core-concepts/reflections)
***
### Ask the agent
In chat, ask which tools it is retrying, which steps it could skip, and to save the fix in a skill or its instructions.
On a schedule, **Reflections** reviews recent chats for patterns such as inefficient tool usage and proposes skill or instruction changes.
[Reflections](/core-concepts/reflections)
***
### Use your own key
Optional. Bring-your-own-key (BYOK) sets **Chat & Reasoning** to 0 credits — you pay the provider instead.
| Still billed | Change |
| - | - |
| Tool calls and compute | Same as usual |
| Orchestration fee | **16%** instead of **8%** |
[Use your own LLM key](/help/connectors/use-your-own-llm-key)
***
## FAQ
<AccordionGroup>
<Accordion title="I switched to a cheaper model and spend did not drop.">
If the agent is on **Auto**, Gumloop already routes easy messages to cheaper models. Check the chat’s models list and credit breakdown to see what actually ran. Pin a specific model only when you want every run to use that model.
</Accordion>
<Accordion title="Why is one chat so expensive?">
Open the credit count in the chat header. Long threads, many connected tools, retries, paid enrichment tools, and frontier models all raise **Chat & Reasoning** and **Tool Calls**. A new chat for a new topic is often the fastest cut.
</Accordion>
<Accordion title="Who can see org-wide spend?">
Your own logs: [Settings > Profile > Usage & Limits](https://www.gumloop.com/settings/profile/usage-limits). All members: [Settings > Organization > Usage & Limits](https://www.gumloop.com/settings/organization/limits) (admin or manager). Insights dashboards: Enterprise, plus **Admin**, **Manager**, or **Analytics**.
</Accordion>
</AccordionGroup>
***
## Related
<CardGroup>
<Card title="Credits" icon="coins" href="/core-concepts/credits">
How a chat is billed, and the built-in cost tips
</Card>
<Card title="Organization Insights" icon="chart-line" href="/enterprise-features/organization_insights">
Leaderboards, Explorer, and the analytics agent
</Card>
<Card title="Agent skills" icon="book" href="/core-concepts/skills">
Playbooks that load only when needed
</Card>
<Card title="Choose the Right AI Model" icon="microchip" href="/help/using-agents/choose-the-right-ai-model">
Recommended, Smartest, and Auto
</Card>
</CardGroup>
# Who pays for a shared agent?
Source: https://docs.gumloop.com/help/credits/who-gets-charged-shared-agent
Credits come from your **organization's shared pool**, no matter who in the org chats with the agent. The agent owner is not billed separately.
## Inside your organization
Every org has one credit pool. Web chat, Slack, and API usage all draw from it.
Per-user caps (set by admins in [permission groups](https://www.gumloop.com/settings/organization/groups)) limit how much one person can spend. The credits still come from the org pool.
## External users
If you share an agent with someone **outside** your organization, their usage bills to **their** account or org, not yours.
## FAQ
<AccordionGroup>
<Accordion title="Does the owner get a separate bill when teammates use the agent?">
No. Org members spend the shared org pool.
</Accordion>
<Accordion title="What if I pin agent-owned credentials?">
Everyone uses that shared login for tool calls. Credit billing still follows the person who ran the chat (org pool if they are in your org).
</Accordion>
</AccordionGroup>
## Related
<CardGroup>
<Card title="Credits" icon="coins" href="/core-concepts/credits">
How a chat is priced
</Card>
<Card title="Agent access" icon="share-nodes" href="/core-concepts/agent_access">
How sharing works
</Card>
</CardGroup>
# Who pays for an interactive artifact?
Source: https://docs.gumloop.com/help/credits/who-pays-interactive-artifact
An **interactive artifact** is a generated page that can call tools or refresh data after it is opened (dashboards, live forms, script-connected HTML). Opening it can start a new billed run.
## Who pays
| Who opens it | Who is billed |
| - | - |
| You | You / your org pool |
| A teammate in the same org | The org pool |
| Someone outside the org | Their account |
The agent owner is not billed just because they created the file.
## What triggers a charge
Live artifacts run a sandbox script. That is billed at about **1 credit per 55 seconds**, with a **1 credit minimum** per run. Most loads cost 1 credit.
* First open of a live artifact
* Each refresh or action that runs the script again
* Each distinct session
Static files (PDF, CSV, PNG) do not keep billing after they are generated.
## If they run out of credits
The artifact stops making live calls. They see a credit error. They are not silently billed to the owner.
## Keep costs down
* Prefer static exports when the reader does not need live data.
* Avoid auto-refresh timers unless the data has to stay live.
* Each refresh creates a new sandbox. There is no state between loads.
## Related
<CardGroup>
<Card title="Agent artifacts" icon="file" href="/core-concepts/agent_artifacts">
How generated files work
</Card>
<Card title="Credits" icon="coins" href="/core-concepts/credits">
Chat and compute pricing
</Card>
</CardGroup>
# Help Center
Source: https://docs.gumloop.com/help/index
Short answers to one question each. For the full feature reference, start at [Agents](/core-concepts/agents), [Connectors](/core-concepts/credentials), or [Credits](/core-concepts/credits).
<div>
<div>
<a href="/help/using-agents">
<span>Using agents</span>
<span>Connectors, models, memory, and Gumball emails.</span>
</a>
<a href="/help/sharing">
<span>Sharing and teams</span>
<span>Invite people, pick a role, and roll an agent out.</span>
</a>
<a href="/help/credits">
<span>Credits</span>
<span>Who pays when someone uses a shared agent or artifact.</span>
</a>
<a href="/help/account-billing">
<span>Account and billing</span>
<span>Plans, invoices, and cancelling a subscription or trial.</span>
</a>
<a href="/help/connectors">
<span>Connectors</span>
<span>Team connectors, BYOK, API keys, and reconnects.</span>
</a>
<a href="/help/brain">
<span>Brain</span>
<span>Knowledge sources, document visibility, and sync.</span>
</a>
<a href="/help/skills">
<span>Skills</span>
<span>Skills vs subagents, app rules, and script integrations.</span>
</a>
<a href="/help/triggers">
<span>Triggers</span>
<span>Stop a trigger, who can manage one, and why one turned off.</span>
</a>
<a href="/help/mcp">
<span>MCP</span>
<span>Custom, proxied, and hosted MCP servers.</span>
</a>
<a href="https://portal.usepylon.com/gumloop/forms/help">
<span>Contact support ↗</span>
<span>Open a ticket if these articles do not cover your case.</span>
</a>
<a href="mailto:accounting@gumloop.com">
<span>Billing questions ↗</span>
<span>Email [accounting@gumloop.com](mailto:accounting@gumloop.com) about invoices, payment, and procurement.</span>
</a>
</div>
</div>
# Why won't my custom MCP server connect?
Source: https://docs.gumloop.com/help/mcp/custom-mcp-wont-connect
Gumloop connects to MCP servers from its cloud, not from your computer. A server that works in Claude Desktop or Cursor can still fail in Gumloop because firewalls, IP allowlists, and OAuth redirect rules see a different caller.
## Find your error
| What you see | Fix |
| - | - |
| **OAuth 2.0** is grayed out: "server did not advertise OAuth support" | [OAuth is grayed out](#oauth-is-grayed-out) |
| OAuth sign-in loops back to **Authenticate**, or a DCR or CIMD error | [OAuth sign-in fails or loops](#oauth-sign-in-fails-or-loops) |
| "Couldn't load tools" | [Tools won't load](#tools-wont-load) |
| **Detected Auth: None** and zero tools | You entered a web page, not the MCP endpoint. Use the URL from the provider's docs, usually ending in `/mcp`. |
| "This MCP server is already connected as..." | Someone in your org already added that URL. Your connection joins the existing server and keeps its name. |
| A hosted MCP fails on **Create** or won't deploy | [Hosted MCP won't create or deploy](#hosted-mcp-wont-create-or-deploy) |
## OAuth is grayed out
Gumloop enables **OAuth 2.0** only when it finds the OAuth metadata the server publishes. If that check is blocked or redirected, OAuth is grayed out.
1. **Allow Gumloop through your firewall.** If the server filters by IP, allow **all** of Gumloop's [static egress IPs](/enterprise-features/static_egress_ips). A `403` hides the OAuth metadata.
2. **Use the exact endpoint URL** from the provider's docs, including `https://` and any trailing slash. Some servers only answer on `/mcp/`.
3. **Self-hosted servers:** check the app's public "site URL" setting. If it uses `http://` or an internal hostname, Gumloop can't follow the OAuth links.
4. **If the provider requires your own OAuth app,** create one, add [both Gumloop redirect URLs](#oauth-sign-in-fails-or-loops), then choose **OAuth 2.0 (Custom Client)** and enter the client ID and secret.
5. **Remove the server and add it again** so Gumloop reruns the check.
## OAuth sign-in fails or loops
The OAuth provider is rejecting Gumloop as a client. Ask whoever manages it to:
1. Allow both redirect URLs:
```text theme={"dark"}
https://api.gumloop.com/auth/callback
https://api.gumstack.com/auth/callback
```
2. Allow Dynamic Client Registration (DCR) or Client ID Metadata Documents (CIMD) from hosted clients, not only desktop apps. If they can't, register an OAuth app for Gumloop and use **OAuth 2.0 (Custom Client)**.
<Tip>
If OAuth worked before and broke after reconnecting, the provider likely allows only `api.gumloop.com`. Add `api.gumstack.com` too.
</Tip>
## Tools won't load
The server connected, but Gumloop couldn't list its tools.
* **API key:** retype it by hand. Trailing spaces, line breaks, or curly quotes from copy and paste break the header. Enter extra headers as `Header-Name: value`.
* **Transport:** the server must use Streamable HTTP or SSE over HTTPS. `localhost` and STDIO aren't supported. Expose a local server with a tunnel such as Cloudflare Tunnel or ngrok, or use [Managed Tunnels](/enterprise-features/managed_tunnels) on Enterprise.
* **Session header:** if a proxy sits in front of a stateful server, make sure it doesn't strip `Mcp-Session-Id`.
* **Gateway in front of the server:** for Cloudflare Access, AWS API Gateway, or Azure API Management, add its credential as an [Access Gate](/enterprise-features/proxied_mcps#access-gates) on a proxied MCP.
After you fix the cause, reopen the connector to retry. For a proxied MCP, click **Fetch New Tools**.
## Hosted MCP won't create or deploy
For admins using [Hosted MCPs](/enterprise-features/hosted_mcps).
| Problem | Fix |
| - | - |
| Error on **Create** | Reconnect your GitHub account on the Hosted MCPs **Settings** page and try again. |
| Deployment shows **Failed** after a successful build | The server didn't start healthy. Check **Monitoring** → **Runtime Logs**, fix the error, and push again. |
| "Failed to start redeployment" | There's no earlier healthy version to fall back to. Fix the startup error. |
| Build fails | Open the deployment and read its build logs. Missing dependencies are the usual cause. |
## Related
<CardGroup>
<Card title="Custom, proxied, and hosted MCP" icon="plug" href="/help/mcp/custom-proxied-hosted-mcp">
Which type to use
</Card>
<Card title="Custom MCP servers" icon="server" href="/nodes/mcp/custom_mcp_servers">
URLs, headers, and OAuth
</Card>
</CardGroup>
# Custom, proxied, and hosted MCP
Source: https://docs.gumloop.com/help/mcp/custom-proxied-hosted-mcp
Gumloop already has 50+ built-in connectors. Use one of these only when the server is **not** in the catalog.
| | Custom MCP | Proxied MCP | Hosted MCP |
| - | - | - | - |
| What you provide | An MCP URL | An MCP URL | A GitHub repo |
| Who sets it up | Any user | Org admin | Org admin |
| Where it runs | Your server | The third party's server | Gumloop |
| Plan | Any | Pro and Enterprise | Pro (1 server) and Enterprise |
| Best for | One URL you already host | A governed, audited external server | Your own server code, no extra hosting |
## Custom MCP
1. Go to [Connectors](https://www.gumloop.com/settings/profile/connectors?view=connected%20server).
2. Open the arrow next to **Add Connector** and choose **Add MCP Connector**.
3. Pick **Public URL** (HTTPS) or **Private (via tunnel)** on Enterprise.
4. Enter the server URL and click **Connect**.
5. Confirm the detected auth. If it is OAuth, click **Authenticate**. Otherwise add a token, API key, or custom header.
6. Open the agent → **Connectors** → **Add Connector**, then search for the server you just added.
<Frame>
<img alt="Add Connector dropdown with Add MCP Connector" />
</Frame>
The server must speak Streamable HTTP or SSE over HTTPS. `localhost` and STDIO are not supported. On Enterprise, [Managed Tunnels](/enterprise-features/managed_tunnels) can reach a server inside your network.
## Proxied MCP
An admin registers one external URL at [Organization → Proxied MCPs](https://www.gumloop.com/settings/organization/proxied-mcps). Gumloop proxies traffic so the org gets activity logs and tool access control without deploying code.
Auth is **None**, **API Key**, or **OAuth 2.0**. None / API Key shares one org secret. OAuth makes each person sign in.
Full setup: [Proxied MCPs](/enterprise-features/proxied_mcps).
## Hosted MCP
An admin connects GitHub at [Organization → Hosted MCPs](https://www.gumloop.com/settings/organization/hosted-mcps). Gumloop builds, deploys, and routes the server. Access is gated by [custom roles](/enterprise-features/user_groups).
Full setup: [Hosted MCPs](/enterprise-features/hosted_mcps).
## Whose credentials run on a shared agent
Gumloop does not silently share one person's personal login.
| Server type | Who is authenticated | What the teammate must do |
| - | - | - |
| Custom MCP (personal) | That teammate's own copy | Each person adds the custom MCP |
| Custom MCP (team connector) | The shared team connection | Nothing |
| Proxied, auth None or API Key | The org-level secret | Nothing |
| Proxied, auth OAuth | Each user's OAuth token | Each user connects once |
| Hosted MCP | Each user's downstream connectors | Each user connects the apps the server uses |
## FAQ
<AccordionGroup>
<Accordion title="Which type should I pick?">
One URL you already host → **Custom**. Org wants one governed external server → **Proxied**. Org wants to run its own server code without extra hosting → **Hosted**.
</Accordion>
<Accordion title="Why can't I use localhost?">
Gumloop must reach the server over the public internet (or an Enterprise managed tunnel). Deploy it, or expose it with Cloudflare Tunnel / ngrok.
</Accordion>
<Accordion title="I added the server in Settings but the agent cannot see it">
Adding it in Connectors is not enough. Open the agent and add that custom MCP under **Connectors**.
</Accordion>
</AccordionGroup>
## Related
<CardGroup>
<Card title="Custom MCP servers" icon="plug" href="/nodes/mcp/custom_mcp_servers">
URL, headers, and OAuth
</Card>
<Card title="Hosted MCPs" icon="server" href="/enterprise-features/hosted_mcps">
Deploy from GitHub
</Card>
</CardGroup>
# Gumloop MCP Connection Troubleshooting
Source: https://docs.gumloop.com/help/mcp/gumloop-mcp-troubleshooting
If the Gumloop MCP server connects successfully but tool calls fail, the issue is usually related to your setup, permissions, or server configuration.
This guide covers the most common causes and fixes across Claude, Claude Code, Cursor, ChatGPT, and other MCP clients. It focuses on the Gumloop MCP server at `https://mcp.gumloop.com/gumloop/mcp`, which provides access to your agents, sessions, and skills. For initial setup, see [MCP server](/mcp-server/overview).
## Which error do you have?
| What you see | Most likely cause | Fix |
| - | - | - |
| `401` with "no Gumloop API credentials found" or "Connect Gumloop before using this server" | No Gumloop API Key on your account | [Generate a Gumloop API Key](#generate-a-gumloop-api-key) |
| `403` on account tools like `list_agents` or `list_teams`, while `search_documentation` works | No API key, or the wrong team picked when you signed in | [Generate a key](#generate-a-gumloop-api-key), then [pick the right team](#pick-the-right-team-when-you-sign-in) |
| `403` on **every** tool, including `search_documentation` and `ask_gummie` | Your custom role blocks the Gumloop server | [Ask an admin to unblock it](#if-every-call-returns-403-ask-an-admin-to-unblock-the-server) |
| Connected, but the client says Gumloop is not connected after you picked a team | That team has no Gumloop API Key | [Pick the right team](#pick-the-right-team-when-you-sign-in) |
| Auth error, `404`, or no tools when you add the server | Wrong server URL | [Use the right server URL](#use-the-right-server-url) |
| "Could not attach to MCP server" or "server reconnection failed" | Stale sign-in cached by the client | [Reset the connection](#reset-a-stuck-connection) |
## Generate a Gumloop API Key
The Gumloop server needs a **Gumloop API Key** connector on your account. Signing in from your client links the connection to that key, so without one every account tool fails, even though the sign-in itself succeeded.
<Steps>
<Step title="Open Connectors">
Go to [Connectors](https://www.gumloop.com/settings/profile/connectors?view=connected).
</Step>
<Step title="Add the Gumloop API Key connector">
Click **Add Connector** and search for **Gumloop API Key**.
</Step>
<Step title="Generate the key">
Click **Generate API Key**. You do not need to copy it into your client. The client's sign-in finds it for you.
</Step>
<Step title="Sign in again from your client">
Remove the Gumloop server from your client, add it again, and complete the sign-in. Pick **Personal** on the authorize screen.
</Step>
</Steps>
To generate or rotate the key later, see [Find your Gumloop API key](/help/connectors/find-your-api-key).
## Pick the right team when you sign in
The **Team** dropdown on the authorize screen chooses which Gumloop API Key the connection uses, not which agents you can see. Pick the space where your Gumloop API Key lives. For most people that is **Personal**.
* **Personal** works with your personal key. It still reaches agents in every team you belong to. Name the team in your prompt, for example: "List the agents in my Marketing team."
* **A team** works only if someone generated a Gumloop API Key on that team's Connectors page. A team key sees that team's agents only, not your personal agents or other teams. Use a team when the connection should act as the team rather than as you, such as a shared service connection.
<Frame>
<img alt="Gumloop authorize screen with the Team dropdown set to Personal" />
</Frame>
<Tip>
For a team that uses Claude, have each person connect with their own personal Gumloop API Key. One connection covers their personal and team agents, and every action stays attributed to the person who ran it.
</Tip>
Some tools do not accept a team Gumloop API Key. `create_session`, for example, does not work with a team key. If you signed in with a team key and a tool returns `403`, sign in again with **Personal** and your personal key.
## If every call returns 403, ask an admin to unblock the server
A `403` on every tool, including the documentation tools, means your custom role has the Gumloop server turned off. This is a permission setting, so removing and re-adding the server in your client does not change it.
An organization admin fixes it:
<Steps>
<Step title="Open the custom role">
Go to [Organization → Roles](https://www.gumloop.com/settings/organization/groups) and open the custom role the user belongs to. Custom roles add up, so check every role the user is in.
</Step>
<Step title="Re-enable the Gumloop server">
On the role's **Connectors** tab, find the **Gumloop** server and allow it for the role.
</Step>
</Steps>
The user can retry right after the admin saves. They do not need to sign in again. For how roles work, see [Custom roles](/enterprise-features/user_groups).
## Use the right server URL
The Gumloop server URL is `https://mcp.gumloop.com/gumloop/mcp`. The [Gumloop connectors directory](https://www.gumloop.com/connectors) has a ready-made URL or command for Claude, Claude Code, Cursor, Codex, and ChatGPT.
<Warning>
These URLs do not work as MCP servers: `https://mcp.gumloop.com/mcp` (no service name) and `https://www.gumloop.com/mcp/...` (that is a web page). If you added either one, Gumloop or your client loads a web page instead of MCP tools, so it shows zero tools or an auth error. Remove it and add the server again with the URL above.
</Warning>
## Reset a stuck connection
If the client says "Could not attach to MCP server" or "Authentication successful, but server reconnection failed," it is usually holding an old sign-in. Clear it and connect again.
<Tabs>
<Tab title="Claude Code">
```bash theme={"dark"}
claude mcp remove gumloop
rm -rf ~/.mcp-auth
claude mcp add --transport http gumloop https://mcp.gumloop.com/gumloop/mcp
```
Use the server name you gave it if it was not `gumloop`. Restart Claude Code, run `/mcp`, select the server, and sign in.
</Tab>
<Tab title="Claude and Claude Desktop">
Go to **Settings > Connectors**, remove the Gumloop connector, and add it again with the server URL. Fully quit and reopen Claude Desktop before you sign in.
</Tab>
<Tab title="mcp-remote configs">
If your client config runs `npx mcp-remote`, delete the cached sign-in with `rm -rf ~/.mcp-auth`, then restart the client.
</Tab>
</Tabs>
If the reset does not help, check whether a company firewall or VPN blocks `mcp.gumloop.com`.
## FAQ
<AccordionGroup>
<Accordion title="Is Gumloop MCP only for Enterprise?">
No. It works on all accounts with an active subscription, trial included. You just need a Gumloop API Key, which you generate from the Connectors page.
</Accordion>
<Accordion title="I removed and re-added the server and still get 403. Why?">
Reconnecting only redoes the sign-in. It does not change what the connection is allowed to do. A `403` that survives a reconnect is almost always a custom role that blocks the Gumloop server, or a sign-in that used a team with no Gumloop API Key. Ask an admin to check [the role's connector access](#if-every-call-returns-403-ask-an-admin-to-unblock-the-server), and sign in with **Personal**.
</Accordion>
<Accordion title="Why can I only see my personal agents?">
Gumloop MCP shows personal agents unless you name a team. Ask your client to list your teams first, then ask for the agents in a specific team. You can reach any team you are a member of.
</Accordion>
<Accordion title="Can my whole team share one connection?">
Yes, with a team Gumloop API Key on the team's Connectors page, then pick that team when you sign in. The tradeoff: the connection sees only that team's agents, and actions are not attributed to individual people.
</Accordion>
<Accordion title="I added Gumloop as a connector on a Gumloop agent and it shows 0 tools">
Check the server URL. It must be `https://mcp.gumloop.com/gumloop/mcp`. The web page address `https://www.gumloop.com/mcp/gumloop` returns a page, not MCP tools. Remove the connector from the agent, delete the server, and add it again with the right URL.
</Accordion>
</AccordionGroup>
## Related
<CardGroup>
<Card title="MCP server" icon="plug" href="/mcp-server/overview">
Set up Gumloop MCP in your client
</Card>
<Card title="Find your Gumloop API key" icon="key" href="/help/connectors/find-your-api-key">
Generate or rotate the key
</Card>
</CardGroup>
# MCP
Source: https://docs.gumloop.com/help/mcp/index
MCP servers expose external tools to your agents. Full reference: [MCP Server](/mcp-server/overview).
# Add someone to your org or team
Source: https://docs.gumloop.com/help/sharing/add-someone-to-org-or-team
You need **Admin** or **Manager**. Regular Members cannot invite others.
## Add someone to the organization
1. Go to [Organization Members](https://www.gumloop.com/settings/organization/members).
2. Click **Add Member**.
3. Enter their email.
4. Optionally pick extra [organization roles](/core-concepts/organization_user_roles) and [teams](/core-concepts/teams). Every invitee already gets **Member**.
5. Send the invite. They show as **Pending** until they accept.
<Frame>
<img alt="Add Member to Organization modal with email, roles, and teams" />
</Frame>
From the members list you can **Resend Invite** or **Revoke Invite** on a pending row.
<Note>
If your org uses domain restrictions or SSO, people on a blocked domain cannot join. See [SSO: SAML, OIDC & SCIM](/enterprise-features/sso_saml_oidc_scim).
</Note>
## Add someone to a team
You can pick teams in the org invite modal above, or invite from the team itself.
**From the sidebar**
1. On the [Home page](https://www.gumloop.com/hub), right-click the team.
2. Select **Invite to Team**.
3. Enter their email.
<Frame>
<img alt="Right-click a team to invite members" />
</Frame>
**From team settings**
1. Right-click the team and open **Settings**.
2. Click **Add Member** and enter their email.
**From organization settings**
Open the team under [Organization > Teams](https://www.gumloop.com/settings/organization/teams) and add them in **Team Members**.
<Frame>
<img alt="Team Overview page in organization settings with the Team Members list and the Add Member button" />
</Frame>
## Good to know
* Inviting someone to a team gives them **User** access to that team's agents, not the ability to change them. Add them as an **Owner** on each agent they should manage. See [Sharing roles](/help/sharing/sharing-roles).
* Org roles are additive. Change them later from [Organization Members](https://www.gumloop.com/settings/organization/members). That is separate from an agent's Owner / User role.
## Related
<CardGroup>
<Card title="User roles" icon="id-badge" href="/core-concepts/organization_user_roles">
Admin, Manager, Member
</Card>
<Card title="Create a team" icon="users" href="/help/sharing/create-a-team">
Create the team first
</Card>
</CardGroup>
# Claim an ownerless agent
Source: https://docs.gumloop.com/help/sharing/claim-an-ownerless-agent
If an agent's Owners are unavailable, an **organization admin** in the same organization can manage the agent through administrative access and can claim durable ownership. Claiming does not require every existing Owner to be gone.
1. Sign in as an organization admin and open the agent.
2. Click the **⋮** menu next to its name.
3. Choose **Claim Ownership**.
You become an Owner and can edit the agent, manage access, and add other Owners.
<Note>
**Claim Ownership** only shows up when you reached the agent through your admin override and you are not already an Owner. Admin access lets you open an agent; it does not make you its Owner — that is what claiming does.
</Note>
## Avoid this in the first place
* Give important agents **two Owners**. Gumloop will not let you remove or demote the last Owner, but that does not help if that Owner's account is deactivated.
* Keep shared agents in a **team** rather than someone's personal space. See [Create a team](/help/sharing/create-a-team).
## FAQ
<AccordionGroup>
<Accordion title="I am not an admin and the agent has no Owner">
Ask an organization admin to claim it, then have them make you an Owner.
</Accordion>
<Accordion title="Does claiming remove anyone's access?">
No. Users and General Access stay exactly as they were. You are added as an Owner.
</Accordion>
<Accordion title="The agent still has an Owner, but they are unreachable">
Use [Request Owner access](/help/sharing/request-owner-access), or have an org admin add you as an Owner from the Access tab.
</Accordion>
</AccordionGroup>
## Related
<CardGroup>
<Card title="Agent access" icon="user-shield" href="/core-concepts/agent_access">
Owners, Users, and admin overrides
</Card>
<Card title="Organization roles" icon="shield" href="/core-concepts/organization_user_roles">
Who is an admin
</Card>
</CardGroup>
# Create a team
Source: https://docs.gumloop.com/help/sharing/create-a-team
Create a team only when several people need to own agents and connectors together. For most rollouts, keep the agent personal and [share it](/help/sharing/let-someone-edit-an-agent).
## Before you start
You need an organization **Admin** or **Manager** role. See [Organization and Teams](/core-concepts/teams).
## From the sidebar
1. On the [Home page](https://www.gumloop.com/hub), find **Teams** in the left sidebar.
2. Click the **+** icon.
3. Name the team, optionally pick a logo and brand color, then click **Create**.
<Frame>
<img alt="Plus icon in the Teams sidebar section" />
</Frame>
<Frame>
<img alt="New Team dialog with name, logo, and brand color" />
</Frame>
## From organization settings
1. Go to [Organization > Teams](https://www.gumloop.com/settings/organization/teams).
2. Click **Create**.
## After you create it
* [Add people](/help/sharing/add-someone-to-org-or-team) to the team.
* [Add team connectors](/help/connectors/add-team-connectors) if the team should share one account.
* Move or create agents in that team only when they should be team-owned.
<Tip>
You do not need a team just to let someone use an agent. Add them to the agent as a **User** instead.
</Tip>
## Related
<CardGroup>
<Card title="Organization and teams" icon="building" href="/core-concepts/teams">
Personal space vs team
</Card>
<Card title="Add someone to your org or team" icon="user-plus" href="/help/sharing/add-someone-to-org-or-team">
Invite after the team exists
</Card>
</CardGroup>
# Enable agent-owned credentials
Source: https://docs.gumloop.com/help/sharing/enable-agent-owned-credentials
Grant the **Agent-owned credentials** feature on a [custom role](/enterprise-features/user_groups). After that, people in the role can pin one account or connection so everyone with access to the agent uses it.
You need the **Admin** or **Security** organization role to edit custom roles. On organizations, this feature is [restricted by default](/core-concepts/credentials#enterprise-availability).
## Grant the feature
1. Go to [Organization > Custom Roles](https://www.gumloop.com/settings/organization/groups).
2. Open the role that should be able to pin agent-owned credentials.
3. Open the **Features** tab.
4. Click **+ Add Features**.
<Frame>
<img alt="Custom role Features tab with the Add Features button" />
</Frame>
5. Search for **Agent-owned credentials**.
6. Select it. The description is: *Users can configure agents to use a pinned account or connection for everyone with access.*
7. Click **Add Features**.
<Frame>
<img alt="Add Features dialog with Agent-owned credentials selected" />
</Frame>
Anyone already on that role can use the feature right away. Assign other people on the role's **Users** tab.
A user gets the feature if **any** of their custom roles grants it.
## Pin an account on an agent
Granting the feature does not pin an account by itself. Each person who should configure it still has to set **Credential ownership** on the agent.
1. Open the agent's **Agent** tab and expand **Connectors**.
2. Open the connector and select a specific account you have access to.
3. Under **Credential ownership**, choose **Agent-owned**.
Full steps: [Turn on agent-owned for a connector](/core-concepts/credentials#turn-on-agent-owned-for-a-connector).
## FAQ
<AccordionGroup>
<Accordion title="I still cannot choose Agent-owned">
Your custom role does not allow assigning agent-owned credentials. Ask an Admin or Security admin to grant **Agent-owned credentials** on a role you belong to. If you hold several roles, only one of them needs to grant it.
</Accordion>
<Accordion title="Is this the same as a team connector?">
No. A [team connector](/help/connectors/add-team-connectors) is a shared login on a team. **Agent-owned credentials** pin one account to a specific agent so everyone with access to *that agent* uses it, including people outside the team.
</Accordion>
<Accordion title="Can I use this with Anyone public sharing?">
No. Agent-owned credentials and **Anyone** public sharing cannot be used together. Change general access to the organization, a team, or restricted people first.
</Accordion>
<Accordion title="How do I remove the feature from a role?">
On the role's **Features** tab, open the row menu for **Agent-owned credentials** and select **Remove feature access**.
</Accordion>
</AccordionGroup>
## Related
<CardGroup>
<Card title="Custom roles" icon="user-shield" href="/enterprise-features/user_groups">
Features tab and how access composes
</Card>
<Card title="Agent-owned credentials" icon="key" href="/core-concepts/credentials#agent-owned-credentials">
How pinning and ownership work
</Card>
</CardGroup>
# Sharing and Teams
Source: https://docs.gumloop.com/help/sharing/index
Share an agent only after it works in a 1:1 chat. Invite people to the organization first, then to a team.
# Keep agents running when someone leaves
Source: https://docs.gumloop.com/help/sharing/keep-agents-running-after-someone-leaves
When someone leaves your organization, their agents aren't deleted, but automations tied to their account can stop running.
Triggers run using the connected accounts of the person who created them. Before removing someone from Gumloop, hand off their agents, ownership, and triggers to another user.
Following these four steps will help keep everything running without interruption.
<Note>
Complete the handoff **before** removing the person from your organization. Once they lose access, triggers they created will stop running, and agents left in their personal space may no longer be accessible to the rest of the team.
</Note>
## 1. Move their agents to a team
Start by moving any agents that need to remain in use out of the person's personal space and into a team.
Agents in a team remain accessible to other team members, while agents in a personal space are only accessible to their creator.
1. From the [Home page](https://www.gumloop.com/hub), open the agent's **⋮** menu and select **Move to Team**. You can also move it from within the agent.
2. Choose the destination team. If you don't have one yet, see [Create a team](/help/sharing/create-a-team).
3. If the agent has attached **skills**, Gumloop will ask whether you want to copy or move them. Choose **Move** so they remain with the agent and aren't left behind in the creator's personal space.
The agent's triggers and tasks move with it and will continue running as long as their creator still has access.
### Or share the agent directly
For a simple one-person handoff, open the agent's **Access** tab and add the person directly. The agent will appear in their **Shared with me** tab.
For agents that are important to ongoing business processes, moving them into a team is usually the better long-term setup.
## 2. Add another Owner
Moving an agent into a team gives team members **User** access by default. Make sure at least one other user has **Owner** access.
Owners can edit the agent, manage access, and view and manage team triggers.
1. Open the agent and go to **Access**.
2. Click **Add owner**, enter their email, and save.
3. If they're already listed as a User, open their role and select **Promote to Owner**.
See [Sharing roles](/help/sharing/sharing-roles) for more details.
## 3. Recreate triggers under the new Owner
Triggers can't be transferred between people. They continue to belong to the person who created them and run using that person's connectors.
Before the original creator leaves, have the new Owner recreate any triggers that need to keep running:
1. Open the agent's **Triggers** tab. Owners can see team triggers along with their schedules and prompts.
2. Recreate each required trigger from the same tab, or just ask the agent in chat to set it up, for example: *"Set up a daily 8 AM trigger that sends me this digest."*
3. Once the departing person is removed, their original triggers will automatically stop running.
<Tip>
Each person needs to create their own triggers because agents can only manage triggers belonging to the person currently interacting with them.
</Tip>
If the agent should always use a shared account rather than the trigger creator's personal credentials, you can also configure [agent-owned credentials](/help/sharing/enable-agent-owned-credentials) or a [team connector](/help/connectors/use-team-connectors).
## 4. Verify the handoff, then remove the member
Before removing the departing person, confirm that the replacement triggers are running successfully and that the new Owner can access everything they need. Check the **Triggers** tab and recent tasks for any failed runs.
Once everything looks good, remove the departing member from [Organization → Members](https://www.gumloop.com/settings/organization/members). Removing them from Gumloop is what disables the triggers still tied to their account.
## Make sure everything has been handed off
Before the person leaves, it can help to review everything they've created. You can ask the analytics agent in [Gumball](/core-concepts/gumball) or [Insights](/enterprise-features/organization_insights#ask-the-analytics-agent) something like:
*"List the agents, triggers, and skills I created."*
Use that list to identify anything that still lives in a personal space or depends on the departing person's account.
## If the person has already left
An organization admin can still recover most team-owned work.
1. **Find what they created.** Use the [analytics agent](/enterprise-features/organization_insights#ask-the-analytics-agent) to identify their agents, triggers, and skills, or export agent data with **Creator Email** through [Usage Data Export](/enterprise-features/organization_data_export).
2. **Claim ownership.** Open the agent using admin access, click the **⋮** menu beside its name, and select **Claim Ownership**. See [Claim an ownerless agent](/help/sharing/claim-an-ownerless-agent).
3. **Recreate the triggers.** Claiming ownership gives you control of the agent, but it doesn't restore the previous owner's triggers. Recreate them under another user.
## Related
<CardGroup>
<Card title="Create a team" icon="users" href="/help/sharing/create-a-team">
Move shared agents out of personal space
</Card>
<Card title="Sharing roles" icon="user-lock" href="/help/sharing/sharing-roles">
What Owners and Users can do
</Card>
<Card title="Who can manage triggers?" icon="bolt" href="/help/triggers/who-can-manage-triggers">
What happens to a trigger when its creator loses access
</Card>
<Card title="Claim an ownerless agent" icon="crown" href="/help/sharing/claim-an-ownerless-agent">
Admin recovery after someone leaves
</Card>
</CardGroup>
# Let a User create triggers
Source: https://docs.gumloop.com/help/sharing/let-a-user-create-triggers
Turn on **Create triggers** in the agent's **Access → User Permissions**. Users can then create and edit the triggers they own on that agent — schedules, app triggers, and webhooks.
1. Open the agent and go to the **Access** tab.
2. Scroll to **User Permissions**.
3. Set **Create triggers** to **Allow**.
4. **Save**.
Users only ever manage their *own* triggers. Owners manage every trigger on the agent. Your triggers appear under **Mine**; Owners and Org Admins can also see other people's triggers under **Team**.
## Turning it back off
Set **Create triggers** to **Don't allow**. If Users already have triggers, Gumloop asks what should happen to them:
* **Keep running** — existing User-owned triggers keep firing. Users cannot create, edit, or activate triggers, but can still view, deactivate, and delete their own. Owners retain full trigger-management access.
* **Disable them** — they are switched off.
Owners can still see and re-enable those triggers afterwards. Allowing creation again does not automatically reactivate triggers that were deactivated.
## FAQ
<AccordionGroup>
<Accordion title="Can a User edit an Owner's trigger?">
No, never — only their own.
</Accordion>
<Accordion title="Whose credentials run a User's trigger?">
The trigger runs as the person who created it, using their connected accounts. See [Connectors](/core-concepts/credentials#in-agents).
</Accordion>
<Accordion title="Can the agent create triggers by itself?">
Yes, if **AI Managed** is on in the Triggers tab header. That is separate from this permission.
</Accordion>
</AccordionGroup>
## Related
<CardGroup>
<Card title="Who can manage triggers" icon="user-check" href="/help/triggers/who-can-manage-triggers">
Owner vs User on triggers
</Card>
<Card title="Agent triggers" icon="bolt" href="/core-concepts/agent_triggers">
Set up a trigger
</Card>
</CardGroup>
# Let someone edit your agent
Source: https://docs.gumloop.com/help/sharing/let-someone-edit-an-agent
Make them an **Owner**. Owner is the only role that can change an agent — there is no editor role any more.
1. Open the [agent](https://www.gumloop.com/agents) and go to the **Access** tab.
2. Click **Add owner** and enter their email.
3. **Save**.
<Frame>
<img alt="Access tab with the Add owner button above the list of Owners" />
</Frame>
Already shared with them as a User? Click their role and choose **Promote to Owner**.
<Warning>
Every Owner can change instructions, connectors, triggers, access, and can delete the agent. Only add Owners who should be able to change production behavior.
</Warning>
## If they only need to use it
Add them as a **User** instead (or set **General Access** to your team or organization) and choose what they can see with [User Permissions](/help/sharing/what-can-a-user-see).
## If they still need to connect Gmail or Slack
Use **Copy setup link** from the agent's share actions instead of only sending the agent URL. It walks them through authenticating the agent's connectors.
## If they only need a copy
Use **Duplicate** from the agent's three-dot menu rather than making them an Owner of yours.
<Frame>
<img alt="Agent three-dot menu showing Pin to My Sidebar, Request Owner access, and Duplicate" />
</Frame>
## Team alternative
If several people should own the agent long term, [create a team](/help/sharing/create-a-team) and put the agent there, then add them as Owners. Everyone on the team gets User access automatically.
## Related
<CardGroup>
<Card title="Sharing roles" icon="user-lock" href="/help/sharing/sharing-roles">
What Owner and User can do
</Card>
<Card title="Who can manage triggers" icon="user-check" href="/help/triggers/who-can-manage-triggers">
Owner vs User on triggers
</Card>
<Card title="Roll out an agent" icon="rocket" href="/help/sharing/roll-out-an-agent">
Company-wide launch
</Card>
</CardGroup>
# Request Owner access
Source: https://docs.gumloop.com/help/sharing/request-owner-access
If you are a **User** on an agent and need to change it, ask an Owner for Owner access from inside the agent.
1. Open the agent.
2. Click the **⋮** menu next to its name.
3. Choose **Request Owner access**.
4. Pick which Owner should get the request and click **Send request**.
The menu item only appears if you are a User — Owners already have full access. Once sent, it reads *Owner access requested* so you do not send it twice.
Owner access lets you edit the agent, manage access, and review all tasks and their task-linked artifacts. It does not automatically grant access to another person's private persistent workspace files.
## What the Owner sees
The request lands in their inbox (and in Slack, if they have Slack connected), where they can **Approve**, **Reject**, or **Dismiss** it. You get access the moment they approve.
## FAQ
<AccordionGroup>
<Accordion title="I do not see Request Owner access">
You are already an Owner, or you reached the agent through an org admin override rather than as a User. Admins see [Claim Ownership](/help/sharing/claim-an-ownerless-agent) instead.
</Accordion>
<Accordion title="Nobody is responding">
Ask a different Owner, or ask an org admin — they can add you as an Owner directly from the agent's Access tab.
</Accordion>
<Accordion title="I only need to see the instructions, not edit them">
Ask an Owner to turn on the relevant [User Permission](/help/sharing/what-can-a-user-see) instead. That is a smaller change than making you an Owner.
</Accordion>
</AccordionGroup>
## Related
<CardGroup>
<Card title="Agent access" icon="user-shield" href="/core-concepts/agent_access">
What Owners and Users can do
</Card>
<Card title="Claim an ownerless agent" icon="crown" href="/help/sharing/claim-an-ownerless-agent">
When every Owner is gone
</Card>
</CardGroup>
# Roll out an agent
Source: https://docs.gumloop.com/help/sharing/roll-out-an-agent
Roll out in phases. Test the agent in a 1:1 chat first, add it to one shared Slack channel, then open it up.
## Before you start
* The agent already works in a private chat.
* Slack (and any other tools it needs) are connected. See [Give an agent a connector](/help/using-agents/give-agent-access-to-a-connector).
* You have decided whose connectors the agent should use. By default it uses each person's own accounts.
## Phase 1: Pilot in one channel
1. Add the agent to a single Slack channel. See [Using Agents in Slack](/core-concepts/agents_slack).
2. Start with a few people and real tasks.
3. Fix instructions and tools before you invite more people.
## Phase 2: Expand
* Open the channel to the wider team once the agent behaves the way you want.
* If you want a custom name, avatar, and faster @mentions, connect a [Custom Slack App](/core-concepts/custom_slack_app).
* Add more channels as other teams ask for it.
## Phase 3: DMs
Direct messages and group DMs need a Custom Slack App. The standard @Gumloop bot cannot be added to DMs.
## How people reach the agent
| Entry point | Who needs a Gumloop account | Whose connectors run |
| - | - | - |
| **@mention** (standard bot or Custom Slack App) | Everyone who mentions the agent | The person who sent the message, unless you pin [agent-owned credentials](/core-concepts/credentials#agent-owned-credentials) |
| **Slack channel trigger** | Nobody in the channel | The trigger owner (one shared connection) |
Use a channel trigger when you want a whole channel to use the agent with no onboarding. If you do that, remove the @mention bot from the channel (`/gummie remove`) and keep **Ignore Bot Messages** on so the agent does not loop.
## Whose connectors the agent uses
By default, a shared agent uses the **invoker's** connectors. To make everyone share one inbox or CRM login, pin [agent-owned credentials](/core-concepts/credentials#agent-owned-credentials).
For @mention rollouts:
* Turn on SSO or domain auto-join in [organization settings](https://www.gumloop.com/settings/organization/general) so people are provisioned on first sign-in.
* Set the agent's [General Access](/core-concepts/agent_access#give-someone-access) to **Organization** so every member gets **User** access, and hide the parts of the setup they do not need with [User Permissions](/core-concepts/agent_access#user-permissions).
## Operating at scale
* Many people can message the same agent at once. You do not need extra triggers for parallelism.
* Attach [subagents](/core-concepts/agents#subagents) for specialized work instead of stuffing one agent with every tool.
* On **Channels → Slack**, set **Thread Replies** to **Only on Mentions** in busy channels.
* Usage comes from the org credit pool. See [Who pays for a shared agent](/help/credits/who-gets-charged-shared-agent).
## FAQ
<AccordionGroup>
<Accordion title="Should I create a team just to roll this out?">
No. Keep the agent personal and add people as Users unless several people need to manage the setup.
</Accordion>
<Accordion title="Why does each person get asked to connect Slack or Gmail?">
The agent is using each invoker's connectors. Pin agent-owned credentials if everyone should act as one shared account.
</Accordion>
</AccordionGroup>
## Related
<CardGroup>
<Card title="Using agents in Slack" icon="slack" href="/core-concepts/agents_slack">
Add an agent to a channel
</Card>
<Card title="Agent access" icon="share-nodes" href="/core-concepts/agent_access">
Roles and General Access
</Card>
</CardGroup>
# Sharing roles
Source: https://docs.gumloop.com/help/sharing/sharing-roles
Roles on a shared resource are separate from org roles (Admin / Manager / Member). You set them in the agent's **Access** tab, or in the **Share** dialog for other resources.
## Agents: Owner or User
An agent has two roles. There is no editor or viewer any more.
| Capability | Owner | User |
| - | - | - |
| Start tasks with the agent | Yes | Yes |
| See instructions, model, connectors, skills | Yes | Only what the Owners chose to show |
| Edit the agent | Yes | No |
| Manage access | Yes | No |
| Manage triggers | Every trigger | Their own, if allowed |
| See other people's tasks | Yes | On a team agent, if Task Visibility is set to **Team tasks** |
| Make a copy | Yes | If allowed |
| Delete the agent | Yes | No |
What a User sees and whether they can copy the agent is controlled by the switches in **Access → User Permissions**. See [What can a User see on my agent?](/help/sharing/what-can-a-user-see).
## How to assign a role
1. Open the agent and go to the **Access** tab.
2. **Add owner** or **Add user** with their email, or set **General Access** so the whole team or organization gets User access.
3. To change someone later, click their role and pick **Promote to Owner** or **Demote to User**.
<Tip>
For a company-wide agent that people should only talk to, set General Access to **Organization** and hide the parts of the setup you do not want exposed.
</Tip>
## Other resources
Skills still use the generic roles: **Owner**, **Editor**, **Viewer**, and **Use Only**. Shared tasks grant **Viewer** access. See [Sharing a skill](/core-concepts/skills#sharing-skills).
## FAQ
<AccordionGroup>
<Accordion title="I used to share agents as Editor. What now?">
Make that person an **Owner**. Owner is the only role that can change an agent.
</Accordion>
<Accordion title="Does team membership make someone an Owner?">
No. Team members get **User** access to team agents. Add them as an Owner if they should manage it.
</Accordion>
<Accordion title="Can I give one User more visibility than another?">
No. User Permissions apply to the whole agent, not per person.
</Accordion>
<Accordion title="Can I stop Users from copying my agent?">
Yes. Set **Make a copy** to **Don't allow** in **Access → User Permissions**. It is allowed by default, and a copy includes the full configuration even where visibility is hidden. See [User Permissions](/core-concepts/agent_access#user-permissions).
</Accordion>
</AccordionGroup>
## Related
<CardGroup>
<Card title="Agent access" icon="user-shield" href="/core-concepts/agent_access">
Full Owner and User reference
</Card>
<Card title="Who can see tasks" icon="eye" href="/help/sharing/who-can-see-tasks">
Task Visibility on team agents
</Card>
</CardGroup>
# What can a User see on my agent?
Source: https://docs.gumloop.com/help/sharing/what-can-a-user-see
Exactly what you let them see. Open the agent, go to **Access → User Permissions**, and flip the eight switches.
<Frame>
<img alt="User Permissions with eight settings set to Show or Hide" />
</Frame>
| Setting | Show means they can see |
| - | - |
| **Show Instructions** | The instructions the agent follows |
| **Show Model** | Which model it runs on |
| **Show Connectors** | The apps it can use |
| **Show Skills** | The skills it can use |
| **Show Knowledge Sources** | The knowledge sources it can search |
| **Show Subagents** | The other agents it can call |
| **Show Secrets** | The names of its secrets |
| **Create triggers** | Not visibility — whether they can create their own triggers (**Allow** / **Don't allow**) |
Owners always see everything.
## Two things people get wrong
* **Show does not mean edit.** A User can read the instructions when *Show Instructions* is on, but only an Owner can change them.
* **Hide does not mean off.** Hiding Connectors does not stop the agent from using Gmail; it just does not list Gmail for Users.
Tasks are separate: see [Who can see tasks on this agent?](/help/sharing/who-can-see-tasks)
## Example
A support agent everyone in the company can use, where the prompt is yours to tune:
* General Access: **Organization**
* Show Instructions: **Hide**
* Show Connectors: **Show** — so people know it reads Zendesk
* Create triggers: **Don't allow**
## FAQ
<AccordionGroup>
<Accordion title="Can I set this per person?">
No. The settings apply to every User on the agent. If one person needs more, make them an Owner.
</Accordion>
<Accordion title="What are new agents set to?">
Every visibility setting starts on **Show** and **Create triggers** on **Allow**, unless your org admin set different [agent defaults](/enterprise-features/agent_default_settings).
</Accordion>
<Accordion title="Can a User see files and artifacts?">
They see the artifacts from tasks they can see. That follows Task Visibility and [File Sharing](/core-concepts/agent_access#file-sharing), not these switches.
</Accordion>
</AccordionGroup>
## Related
<CardGroup>
<Card title="Agent access" icon="user-shield" href="/core-concepts/agent_access#user-permissions">
Full reference
</Card>
<Card title="Let a User create triggers" icon="bolt" href="/help/sharing/let-a-user-create-triggers">
The trigger switch in detail
</Card>
</CardGroup>
# Who can see tasks on this agent?
Source: https://docs.gumloop.com/help/sharing/who-can-see-tasks
A **task** is one conversation with the agent. New team agents default to **Team tasks**, so team members can see tasks started by other team members. On personal agents, Users see their own tasks unless a task is shared with them. Owners can see all tasks on either kind of agent.
On a **team agent**, Owners can change that with one setting: **Access → Task Visibility**.
| Option | What Users see |
| - | - |
| **Their tasks only** | Each person sees only the tasks they started. |
| **Team tasks** | Everyone on the team sees tasks their team members started. |
Owners always see every task on the agent.
<Warning>
Task Visibility only exists on **team agents**. On a personal agent you shared, Users normally see only their own tasks and the setting is not shown. Owners can still see all tasks, and a task can also be shared separately. If you need shared history for Users, move the agent to a team or [create one](/help/sharing/create-a-team).
</Warning>
## Change it
1. Open the agent and go to the **Access** tab.
2. Under **Task Visibility**, pick **Their tasks only** or **Team tasks**.
3. **Save**.
## Everywhere else
| Situation | What they see |
| - | - |
| Anyone on a **personal** agent you shared | Their own tasks, unless they are an Owner or the task is shared with them |
| Someone you added by email who is **not** on the team | Their own tasks, unless they are an Owner or the task is shared with them |
| Slack channel | The Slack thread is visible to everyone in the channel. Gumloop history still follows the table above. |
| Hosted page visitors | Their own hosted-page session only |
| A task someone shared as a link | Read-only, for whoever has the link |
## FAQ
<AccordionGroup>
<Accordion title="I am on the team but I only see my own tasks">
Either the agent is set to **Their tasks only**, or the agent lives in someone's personal space rather than on the team. Check both with an Owner.
</Accordion>
<Accordion title="Does hiding the instructions hide tasks too?">
No. [User Permissions](/help/sharing/what-can-a-user-see) control the setup; Task Visibility controls task history. They are independent.
</Accordion>
<Accordion title="Can I hide one specific task?">
Start it in [incognito](/core-concepts/agents#incognito-mode) to keep it out of normal task history. Incognito is not zero-retention: message content is cached temporarily with a 24-hour expiry, and task metadata is stored without the messages or searchable conversation text.
</Accordion>
</AccordionGroup>
## Related
<CardGroup>
<Card title="Agent access" icon="user-shield" href="/core-concepts/agent_access#task-visibility">
Task Visibility in context
</Card>
<Card title="What can a User see" icon="eye" href="/help/sharing/what-can-a-user-see">
The eight User Permissions
</Card>
</CardGroup>
# Skills
Source: https://docs.gumloop.com/help/skills/index
Skills are reusable instructions and scripts you attach to an agent. Use these pages when you are deciding how to extend an agent, not when you need the full feature reference: [Skills](/core-concepts/skills).
# Call integrations from a skill
Source: https://docs.gumloop.com/help/skills/skill-script-integrations
A **skill script** is a skill that includes Python the agent can run in the [code sandbox](/core-concepts/agent_sandbox_and_secrets). Use it when a connector exists, but you need branching, batching, or cleanup the raw tools do not do well.
You do not need to write the script. Describe the outcome and let the agent draft the skill.
## When this helps
* Transform results before the next step (filter rows, reshape JSON)
* Call the same connector many times with custom logic
* Combine two connectors in one deterministic script
If you only need "send this Slack message," add the Slack connector. Do not wrap it in a skill.
## How to get the agent to write one
1. Add the connector on the agent first. See [Give an agent a connector](/help/using-agents/give-agent-access-to-a-connector).
2. Paste one of the prompts below.
3. Review the skill. It should use the Gumloop SDK for the connector, not raw HTTP.
4. Save it and attach it to this agent (and others, if you want).
## Example prompts
Copy one of these, then swap in your mailbox, sheet, or channel.
**Filter unread email into a table**
```
Create a skill that lists unread Gmail from the last 24 hours, keeps only messages from customers (not newsletters or internal @ourcompany.com), and writes a summary table with sender, subject, and a one-line next step.
```
**Batch Slack follow-ups**
```
Create a skill that reads a list of Slack user IDs, posts the same check-in message to each person as a DM, and returns who succeeded and who failed. Use the Slack connector already on this agent. Do not use raw HTTP.
```
**Sheets + Slack digest**
```
Create a skill that reads the "Leads" tab in our Google Sheet, keeps rows where Status is "New" and Score is over 70, and posts a Slack digest to #sales with name, company, and score. Use the Google Sheets and Slack connectors already on this agent.
```
**Retry-safe CRM update**
```
Create a skill that takes a list of Salesforce account IDs, fetches each account, and writes Last_Touched__c to today. Skip IDs that 404. Return a table of updated vs skipped. Use the Salesforce connector, not raw HTTP.
```
## After it writes the skill
* Keep the skill focused on one job.
* Tell the agent which connector account to use if several are connected.
* If the script fails, paste the error back and ask it to fix the skill.
* Skills do not have version history. Duplicate a working skill before a risky edit.
## FAQ
<AccordionGroup>
<Accordion title="Should every Slack or Gmail action be a skill?">
No. Add the connector and ask the agent in chat. Use a skill script only when you need branching, batching, or cleanup the raw tools do not do well.
</Accordion>
<Accordion title="The skill used requests / HTTP instead of the connector">
Tell it: "Rewrite this to use the Gumloop SDK and the connector already on this agent. Do not call the API over HTTP."
</Accordion>
<Accordion title="Can I attach the same skill to other agents?">
Yes, after you save it. Those agents still need the same connectors attached.
</Accordion>
</AccordionGroup>
## Related
<CardGroup>
<Card title="Code sandbox" icon="terminal" href="/core-concepts/agent_sandbox_and_secrets">
Where skill scripts run
</Card>
<Card title="Agent skills" icon="wand-magic-sparkles" href="/core-concepts/skills">
How to attach a skill
</Card>
</CardGroup>
# Skills vs App Rules
Source: https://docs.gumloop.com/help/skills/skills-vs-app-rules
These are not interchangeable.
| | Skills | App rules |
| - | - | - |
| Purpose | Teach a process | Constrain a tool call |
| Runs as | Extra instructions or a script | A block, tag, or approval check |
| Who writes them | Anyone who can edit the agent or skill | Agent Owners, or org admins for org-wide rules |
| Example | "Always file the note in this Notion DB" | "Block Slack `chat.delete`" |
## Use a skill when
* You want a playbook, template, or style guide
* The agent should call tools, but *in a certain way*
* Several agents should share the same process
## Use an app rule when
* A tool should never run, or should wait for a human
* You need the same guardrail on many agents
* Compliance requires a hard block, not a suggestion
App rules can be scoped to one agent or to the organization. See [App Rules](/enterprise-features/app-policies/app-rules) and [Human in the Loop](/core-concepts/human_in_the_loop).
## FAQ
<AccordionGroup>
<Accordion title="Can a skill replace an app rule?">
No. A skill can *ask* the agent not to delete Slack messages. An app rule can *stop* the delete call. Use both when the process and the guardrail matter.
</Accordion>
</AccordionGroup>
## Related
<CardGroup>
<Card title="App Rules" icon="shield" href="/enterprise-features/app-policies/app-rules">
Org and agent guardrails
</Card>
<Card title="Human in the Loop" icon="hand" href="/core-concepts/human_in_the_loop">
Approvals and Ask Question
</Card>
</CardGroup>
# Skills vs subagents
Source: https://docs.gumloop.com/help/skills/skills-vs-subagents
**Skills** teach this agent how to do a job. **Subagents** are other agents you hand work to.
| | Skill | Subagent |
| - | - | - |
| What it is | A playbook, template, or script | A separate agent with its own tools and context |
| Runs where | Inside the current chat | In its own conversation |
| Best for | Repeatable process, shared knowledge | Parallel work, specialists |
## Quick decision
| You want to… | Use |
| - | - |
| Follow a step-by-step process | Skill |
| Store templates or domain knowledge | Skill |
| Reuse the same process on many agents | Skill |
| Research three things at once | Subagent (clone) |
| Hand work to a specialist (Sales, Support) | Subagent (other agent) |
| Coordinate several specialists | Subagent |
Details: [Agent Skills](/core-concepts/skills) and [Subagents](/core-concepts/agents#subagents).
<Tip>
If you are about to paste a long SOP into the agent instructions, make a skill. If you are about to give one agent every connector in the company, split specialists and call them as subagents.
</Tip>
## FAQ
<AccordionGroup>
<Accordion title="When should I write a skill?">
For a repeatable process. Example: "draft the weekly pipeline recap in this format."
</Accordion>
<Accordion title="When should I use a clone?">
For parallel research. Example: "research these three competitors at once."
</Accordion>
<Accordion title="When should I invoke another named agent?">
For cross-domain work. Example: a coordinator asks the CRM agent and the writing agent, then combines the answers.
</Accordion>
<Accordion title="Can I use both?">
Yes. Put a skill on the coordinator that says *when* to call which subagent.
</Accordion>
</AccordionGroup>
## Related
<CardGroup>
<Card title="Agent skills" icon="wand-magic-sparkles" href="/core-concepts/skills">
How skills attach and load
</Card>
<Card title="Skills vs app rules" icon="shield" href="/help/skills/skills-vs-app-rules">
Playbooks vs guardrails
</Card>
</CardGroup>
# Triggers
Source: https://docs.gumloop.com/help/triggers/index
Triggers run an agent on a schedule, on an app event, or from a webhook. Full reference: [Agent Triggers](/core-concepts/agent_triggers).
# Stop a scheduled trigger
Source: https://docs.gumloop.com/help/triggers/stop-a-scheduled-trigger
Open the agent, find the trigger, and deactivate or delete it. Deactivating keeps the config. Deleting removes it.
## On an agent
1. Open the [agent](https://www.gumloop.com/agents).
2. Go to the **Triggers** tab.
3. Choose **Deactivate trigger** to pause it, or **Delete trigger** if you do not need it again.
Deactivating every trigger stops the agent's automated runs without retiring it. The agent, connectors, and trigger configs stay intact.
## Good to know
* A deactivated trigger does not fire and does not poll.
* One-time scheduled triggers delete themselves after they run, success or fail.
* Deleting cannot be undone. Recreate it if you still need it.
* If a run is already in flight, stopping the trigger does not cancel that run. Cancel the run from history if you need to.
* You can only deactivate or delete a trigger you created, unless you are an **Owner** of the agent or an **Org Admin**. See [Who Can Manage Triggers?](/help/triggers/who-can-manage-triggers).
## Related
<CardGroup>
<Card title="Agent triggers" icon="clock" href="/core-concepts/agent_triggers">
Add a scheduled or event trigger
</Card>
<Card title="Who can manage triggers?" icon="user-check" href="/help/triggers/who-can-manage-triggers">
Owner vs User
</Card>
<Card title="Why did my trigger turn off?" icon="triangle-exclamation" href="/help/triggers/why-triggers-turn-off">
Auto-disable after failed runs
</Card>
</CardGroup>
# Who can manage triggers?
Source: https://docs.gumloop.com/help/triggers/who-can-manage-triggers
An agent **Owner** manages every user-configurable trigger on it. Users can always view, deactivate, and delete their own triggers while they retain access to the agent. When **Create triggers** is **Allow**, Users can also create, edit, and activate their own triggers. This covers scheduled, app, webhook, and AI-created custom triggers.
## Who can do what
| Role | Create, edit, or activate their own | Deactivate or delete their own | Manage someone else's |
| - | - | - | - |
| **Owner** | Yes | Yes | Yes, from the **Triggers** tab |
| **Org Admin** | Yes | Yes | Yes, from the **Triggers** tab |
| **User**, Create triggers **Allow** | Yes | Yes | No |
| **User**, Create triggers **Don't allow** | No | Yes | No |
Every trigger belongs to the person who created it, and it runs with their connected accounts. Team membership gives someone **User** access — it does not let them manage other people's triggers.
## Turning trigger creation off
Set **Create triggers** to **Don't allow** and Gumloop asks what to do with the triggers Users already have:
* **Keep running** — they keep firing. Users cannot create, edit, or activate triggers, but can still view, deactivate, and delete their own.
* **Disable them** — they are switched off.
Owners can still see and manage those triggers from the **Triggers** tab either way. See [Let a User create triggers](/help/sharing/let-a-user-create-triggers).
Turning Create triggers off is not the same as removing access to the agent. Owner-owned triggers are unaffected. Allowing creation again does not automatically reactivate triggers that were deactivated. If a trigger's creator loses all access to the agent, their triggers are removed; removing one share does not remove them if another grant still provides access.
## What you see in the Triggers tab
Your triggers appear under **Mine**. Owners and Org Admins can also see other people's triggers under **Team**.
## If the agent cannot change a trigger for you
When you ask the agent to change a trigger during a task, it can only list and change **your** triggers — that is true even for Owners. To change someone else's, open the **Triggers** tab.
## FAQ
<AccordionGroup>
<Accordion title="Can each person have their own run time on the same agent?">
Yes. Leave **Create triggers** on **Allow** and everyone adds their own scheduled trigger. You do not need a copy of the agent per person.
</Accordion>
<Accordion title="If I edit a trigger, does it change for everyone?">
Only if you are an Owner or org admin editing someone else's trigger. Otherwise you are editing your own.
</Accordion>
<Accordion title="Why can I use the agent but not add a trigger?">
The agent's **Create triggers** permission is set to **Don't allow**. Ask an Owner to allow it.
</Accordion>
</AccordionGroup>
## Related
<CardGroup>
<Card title="Agent triggers" icon="clock" href="/core-concepts/agent_triggers">
Add a scheduled, app, or webhook trigger
</Card>
<Card title="Sharing roles" icon="users" href="/help/sharing/sharing-roles">
What Owner and User can do
</Card>
<Card title="Let a User create triggers" icon="bolt" href="/help/sharing/let-a-user-create-triggers">
Turn the permission on or off
</Card>
<Card title="Stop a scheduled trigger" icon="circle-pause" href="/help/triggers/stop-a-scheduled-trigger">
Deactivate or delete a trigger
</Card>
</CardGroup>
# Why did my trigger turn off?
Source: https://docs.gumloop.com/help/triggers/why-triggers-turn-off
Your trigger did not turn off at random. Gumloop pauses a trigger automatically after **3 consecutive failed runs**. It is a safeguard: a trigger that keeps firing into the same error burns credits and piles up failed runs, so Gumloop turns it off until the cause is fixed.
This applies to every trigger type: scheduled, app, webhook, and AI-created custom triggers.
<Note>
When a trigger auto-disables, the owner is notified by **email, Slack DM, and in app**. The notification links straight to the most recent failed run, which is the fastest way to see what went wrong. Dismiss it once you have handled it.
</Note>
## Why it turned off
| Reason | What happened |
| - | - |
| **3 consecutive failed runs** | The common one. Three failures in a row and the trigger is paused. A single successful run resets the count to zero. A run skipped because the previous run is still going is not a failure and does not count. |
| **Runs kept being dropped** | If your account is at its concurrent-run limit every time the trigger fires, those runs are skipped. After a long streak of skipped runs, the trigger is disabled and the owner gets an email. Usually it means the trigger fires far more often than the agent can finish a run. |
| **No active paid plan** | Recurring triggers stop running when the owning account no longer has an active paid plan. |
| **Someone turned it off** | A person deactivated or deleted it, or, if the trigger is **AI Managed**, the agent paused it because you asked it to. |
## Find the cause
The trigger being off is the symptom. The failed runs tell you the cause.
1. Open the notification and click through to the failed run. Or open the agent and go to its run history.
2. Read the last few failed runs from just before it turned off. The error on those runs is the real reason.
## Common causes and fixes
Ordered by how often they come up:
| Cause | What you see | Fix |
| - | - | - |
| **Expired or disconnected credential** | A connector tool call fails with an auth, token, or permission error. OAuth apps like Salesforce, Google, Notion, and Slack are the usual ones. | **Refresh** the connector, then re-enable the trigger. See [Revoke and Reconnect a Connector](/help/connectors/revoke-and-reconnect). |
| **Out of credits or over a usage cap** | Runs fail with a credit or usage limit error. | Top up credits or raise the cap, then re-enable. While the account is over the cap, runs keep failing. |
| **A deleted or renamed resource** | The channel, folder, database, or record the trigger watches no longer exists, or its permissions changed. | Point the trigger at the current resource, or restore access, then re-enable. |
## Turn it back on
1. Fix the cause first. Re-enabling without fixing it just disables the trigger again on the next runs.
2. Open the agent and go to the **Triggers** tab.
3. Open the trigger's menu and choose **Activate trigger**.
Re-enabling **resets the failure count**. Only failures after you re-enable count toward the next auto-disable, so earlier failures will not turn it off again on their own.
You can activate your own trigger if **Create triggers** is **Allow**. Otherwise ask an Owner or Org Admin to activate it. Owners and Org Admins can also activate other people's triggers. See [Who Can Manage Triggers?](/help/triggers/who-can-manage-triggers).
<Warning>
If the trigger turns off again right away, the root cause is still there. The classic example is a credential you refresh but that keeps expiring, such as a Salesforce connected app whose refresh token policy is not set to stay valid until revoked. Fix the source of the repeated failures, not just the trigger.
</Warning>
## Stop it from happening again
* **Keep credentials healthy.** Refresh the connector before its access expires. For a shared automation, use a [team connector](/help/connectors/use-team-connectors) so one person leaving does not break it.
* **Keep credits above zero** on the account that owns recurring triggers.
* **Fire only on new data.** If a trigger fires on every poll instead of only on new data, it wastes credits and its runs start getting skipped. Tighten the condition.
## FAQ
<AccordionGroup>
<Accordion title="Can I raise the 3-failure limit for one trigger?">
Not from the app. Fix the error that keeps failing, or handle it in the agent so the run finishes successfully.
</Accordion>
<Accordion title="Do I lose the trigger's configuration when it auto-disables?">
No. The schedule, prompt, and settings stay intact. Re-enabling picks up exactly where it left off.
</Accordion>
<Accordion title="My trigger disappeared instead of being paused">
Check whether it was a one-time scheduled trigger. Those delete themselves after they run, success or fail, so a missing one-time trigger ran, it did not fail. Otherwise, someone with access deleted it, or the creator lost all access to the agent, which removes their triggers. Removing one share does not remove them if another grant still provides access.
</Accordion>
<Accordion title="I refreshed the connector but the trigger still will not run">
If the connector the trigger was built on was **revoked or deleted**, re-enabling will not fix it. The trigger still points at a credential that no longer exists, and connecting the app again creates a new one rather than restoring the old one. Delete the trigger and create it again on the reconnected account. This is the most common reason a trigger keeps failing after what looks like a clean fix.
</Accordion>
</AccordionGroup>
## Related
<CardGroup>
<Card title="Stop a scheduled trigger" icon="circle-stop" href="/help/triggers/stop-a-scheduled-trigger">
Deactivate or delete a trigger yourself.
</Card>
<Card title="Who can manage triggers?" icon="user-lock" href="/help/triggers/who-can-manage-triggers">
Owner and User permissions.
</Card>
<Card title="Revoke and reconnect a connector" icon="rotate" href="/help/connectors/revoke-and-reconnect">
Fix an expired or disconnected credential.
</Card>
<Card title="Agent triggers" icon="bolt" href="/core-concepts/agent_triggers">
How scheduled, app, and webhook triggers work.
</Card>
</CardGroup>
# Choose the Right AI Model
Source: https://docs.gumloop.com/help/using-agents/choose-the-right-ai-model
Use **Auto** for mixed requests. For a recurring job, compare a faster model with a more capable one, then keep the option that meets your quality, speed, and cost needs.
## Which option should I choose?
Start with the option that matches how you use the agent.
| Option | Use it when |
| - | - |
| **Auto** | Requests vary in difficulty. Gumloop chooses a model for each message. |
| **Recommended** | You want a balanced starting point for everyday work. |
| **Smartest** | Difficult reasoning or complex execution makes capability your priority. |
| A specific model | You want to compare models or use one that passes your tests for a recurring task. |
**Recommended** and **Smartest** can change over time. Enterprise organizations can customize them, so their underlying models may differ from those shown here.
## What are some practical model examples?
Use these as starting candidates, not fixed assignments. Test the actual job rather than choosing by provider name.
| Example request | Models to try | What to check |
| - | - | - |
| “Extract the customer name, order number, and issue from these support emails.” | **GPT-6 Luna** or **Gemini 3.8 Flash** | Accurate fields, missing information, and consistent formatting. |
| “Find overdue accounts in the CRM and draft a follow-up for each.” | **Claude 5.5 Sonnet** or **Grok 4.7** | Correct records, tool arguments, and complete drafts. |
| “Compare these conflicting reports and recommend a plan with citations.” | **GPT-6 Astra** or **Claude 5.5 Opus** | Evidence quality, contradictions, and whether the recommendation follows from the sources. |
| “Turn this product brief into a polished presentation.” | **Claude 5.5 Opus** or **GPT-6.1 Sol** | Structure, visual quality, factual accuracy, and completeness. |
For images or screenshots, choose a model with **Vision**. For long documents, check **Context**. A larger input capacity is not proof of better reasoning.
**Skills use the agent's model**, not a separate one. Choose for the work the skill requires: formatting supplied text is different from investigating a complex problem.
## What criteria does Auto use?
**Auto** prioritizes the quality a task needs before cost. When model tiers are expected to produce equally good results, it favors the cheaper one.
It considers:
* **Task and context:** your request, relevant chat history, and agent instructions.
* **Trust:** whether sources, tools, or tests can verify the answer.
* **Capabilities:** writes and delegation need more capable tiers than the cheapest options.
* **Result requirements:** difficulty, constraints, correctness, polish, and initiative.
Auto can switch to a stronger tier mid-run and shows which model is used. Organization restrictions still apply. See [AI Models](/core-concepts/ai_models#auto-let-gumloop-choose-the-model) for details.
## How do I select a model?
Open your agent's **Agent** tab, then use the **Model** dropdown.
<Steps>
<Step title="Open the model picker">
Choose a preset, search by model name, or browse by provider.
<Frame>
<img alt="Agent tab with the model picker open, showing Auto, Recommended, Smartest, and provider choices alongside the agent's chat area" />
</Frame>
</Step>
<Step title="Check the model card">
Hover a model to compare **Cost**, **Speed**, **Intelligence**, **Context**, **Tool Calling**, and **Vision**. Ratings help shortlist candidates; your task results decide the winner.
<Frame>
<img alt="Claude 5.5 Sonnet model card beside the search results, showing cost, speed, intelligence, context, tool calling, and vision, with the Agent tab visible" />
</Frame>
</Step>
<Step title="Select and save">
Select your model, then choose **Save** to apply the agent configuration.
</Step>
</Steps>
## How do I know which model works best?
Test candidates on the same prompts, instructions, skills, tools, and source material.
1. **Define a pass:** required facts, format, actions, and acceptable completion time.
2. **Try realistic cases:** ordinary requests, difficult inputs, and previous failures. Use fresh chats and repeat important cases.
3. **Compare finished results:** correctness, tool actions, time, and corrections needed. Select the chat-header credit count for the full cost breakdown.
4. **Keep the option that passes:** improve instructions or try a stronger model if it fails. Re-test after material changes.
Test writes with non-production records or approval safeguards. For consequential work, establish a reliable result first, then optimize cost.
## FAQ
<AccordionGroup>
<Accordion title="Why didn't a stronger model fix the result?">
Check source data, connector access, instructions, and skills first. More capability cannot grant missing access. Make the success criteria clear before comparing models.
</Accordion>
<Accordion title="Why can't I select a model?">
Your organization or custom role may restrict it. **Auto** does not bypass those restrictions. A model marked **Restricted by Admin** requires the appropriate access.
</Accordion>
</AccordionGroup>
<Note>
Models change quickly. The named models above are examples, not permanent recommendations or provider rankings. Check the current picker and re-test your task when models change. Examples checked October 2, 2026.
</Note>
## Related
<CardGroup>
<Card title="AI models" icon="microchip" href="/core-concepts/ai_models">
Model capabilities, Auto routing, and provider keys
</Card>
<Card title="Credits" icon="coins" href="/core-concepts/credits">
Understand the cost of completed tasks
</Card>
</CardGroup>
# Does my agent remember conversations?
Source: https://docs.gumloop.com/help/using-agents/does-my-agent-remember-conversations
A new conversation starts empty. The agent keeps context inside the **current chat**. To look up earlier work, use **Search Past Conversations** — it lives under **Abilities** and is **on by default**.
## What is remembered
* Everything in this chat, until the context window fills up
* Files and notes in the sandbox for this conversation
* Earlier chats are not loaded automatically; **Search Past Conversations** can retrieve relevant history
## Search past conversations
1. Open the agent and confirm **Search Past Conversations** is on in **Abilities**.
2. Ask it to find a prior chat, decision, or file.
The agent pulls relevant snippets. It does not dump every old chat into context.
## Other ways to carry knowledge forward
| Method | What it stores | Best for |
| - | - | - |
| [Skills](/core-concepts/skills) | Playbooks, templates, and domain knowledge | Processes that should stay the same every time |
| [Self-improve instructions](/core-concepts/agents) | Updates the agent writes into its own instructions | Preferences it should keep after you approve them |
| [Brain](/core-concepts/brain) | Company knowledge from connected sources | Shared facts the whole team should reuse |
<Tip>
Keep Search Past Conversations on and put the repeatable process in a skill. Do not paste long history into every new chat.
</Tip>
## Related
<CardGroup>
<Card title="Agent skills" icon="wand-magic-sparkles" href="/core-concepts/skills">
Reusable knowledge packs
</Card>
<Card title="Agents" icon="compass" href="/core-concepts/agents">
Chat, abilities, and self-improve
</Card>
</CardGroup>
# Give an agent a connector
Source: https://docs.gumloop.com/help/using-agents/give-agent-access-to-a-connector
To give an agent access to Gmail, Slack, Notion, or any other app, add the connector on the agent **and** sign in. Connecting the app in Settings alone does not attach it to the agent.
## Add a built-in connector
Gumloop includes 150+ built-in connectors.
1. Open the [agent](https://www.gumloop.com/agents).
2. In the **Agent** tab, expand **Connectors**.
3. Click **Add**.
4. Search for the service, such as Gmail, and select it.
<Frame>
<img alt="Add Connectors dialog with a search box" />
</Frame>
5. If you have not signed in yet, complete the OAuth or API-key flow.
<Frame>
<img alt="Click to connect the selected integration" />
</Frame>
6. Confirm the connector appears on the agent with the account you expect.
<Tip>
Need a specific inbox, not your default? After the connector is on the agent, open its detail view and choose **Use Specific Account** in the **Account** selector.
</Tip>
## What else an agent can use
| Type | When to use it |
| - | - |
| Built-in connector | Gmail, Slack, Google Sheets, Notion, Salesforce, and other services with built-in Gumloop connectors |
| Custom, proxied, or hosted MCP | An MCP server that is not in the built-in catalog. See [Custom, proxied, and hosted MCP](/help/mcp/custom-proxied-hosted-mcp) |
| Skill | A playbook or script the agent should follow |
## Limit which actions a connector can take
<Frame>
<img alt="Connected Gmail account listed on the agent" />
</Frame>
Open the connector on the agent and turn off tools you do not want, or add an [app rule](/help/skills/skills-vs-app-rules) if you need a block or approval.
## Related
<CardGroup>
<Card title="Connectors" icon="plug" href="/core-concepts/credentials">
Personal vs team connectors
</Card>
<Card title="Agents" icon="compass" href="/core-concepts/agents">
How connectors, skills, and triggers fit together
</Card>
</CardGroup>
# Using Agents
Source: https://docs.gumloop.com/help/using-agents/index
Start here if the agent cannot see an app, you want a different model, you need memory across chats, or you want to stop Gumball emails.
# How do I unsubscribe from Gumball emails?
Source: https://docs.gumloop.com/help/using-agents/unsubscribe-from-gumball-emails
To stop Gumball's emails, turn off **Email** delivery on the two features that send them: the **Daily Chew** and **Meeting Prep**. [Gumball](/core-concepts/gumball) is your personal Gumloop agent, so it stays on your account, but it only emails you when one of these features has email delivery switched on.
| Feature | What it emails you | How to stop it |
| - | - | - |
| **Daily Chew** | Your morning report of what you missed. | Turn off **Email** under **Delivery**, or pause the Daily Chew. |
| **Meeting Prep** | A brief before a meeting. | Turn off **Email** under **Delivery**, or turn off **Prep meetings automatically**. |
| **Smart Inbox** | Nothing. It only labels and drafts inside your own mailbox. | Nothing to unsubscribe from. Turn it off from **Smart Inbox** on the Gumball home screen if you want. |
## Why is Gumball emailing me?
The Daily Chew or Meeting Prep has **Email** turned on under its **Delivery** setting. Every report is always saved inside Gumball, and **Email** and **Slack DM** are extra copies you opt into. Turn the email copy off and the feature keeps working, you just stop getting it in your inbox.
## Stop Daily Chew emails
<Steps>
<Step title="Open the Daily Chew settings">
On the Gumball home screen, find **Routines** in the right-hand panel and click **Daily Chew** to open its settings.
<Frame>
<img alt="Gumball home screen with Daily Chew and Meeting Prep listed under Routines in the right-hand panel" />
</Frame>
</Step>
<Step title="Turn off Email delivery">
Under **Delivery**, switch off **Email** and click **Save changes**. The report still appears in Gumball, and in a **Slack DM** if you left that on.
</Step>
<Step title="Or pause it entirely">
To stop the report from running at all, pause the Daily Chew. Pausing stops future runs, resuming puts it back on schedule, and your past reports stay in your history either way.
</Step>
</Steps>
## Stop Meeting Prep emails
<Steps>
<Step title="Open the Meeting Prep settings">
On the Gumball home screen, find **Routines** in the right-hand panel and click **Meeting Prep** to open its settings.
</Step>
<Step title="Turn off Email delivery">
Under **Delivery**, switch off **Email** and click **Save changes**. Briefs still appear in Gumball.
</Step>
<Step title="Or stop automatic briefs">
To stop Gumball preparing briefs on its own, turn off **Prep meetings automatically**. Your meetings still show on the Gumball home screen, and **Prepare now** still works whenever you want a brief.
</Step>
</Steps>
<Tip>
Turning off **Email** keeps the feature running inside Gumball and just removes the inbox copy. Pause the Daily Chew or turn off automatic Meeting Prep when you do not want Gumball doing the work at all.
</Tip>
## FAQ
<AccordionGroup>
<Accordion title="I still want the report, just not by email" icon="file-lines">
Turn off **Email** under **Delivery** and leave the feature on. The Daily Chew and Meeting Prep always stay inside Gumball, so you can read them there, or keep the **Slack DM** copy if you prefer Slack.
</Accordion>
<Accordion title="I turned off email but Gumball still messages me in Slack" icon="slack">
Slack is a separate delivery option. Open the same **Delivery** setting on the Daily Chew or Meeting Prep and switch off **Slack DM** as well. Turning off **Email** does not remove the Slack copy.
</Accordion>
<Accordion title="Is Smart Inbox sending me these emails?" icon="inbox">
No. [Smart Inbox](/core-concepts/gumball#smart-inbox) works inside your own Gmail or Outlook: it applies labels and can write drafts, but it does not send you a separate message. If you do not want Gumball touching your mailbox, open **Smart Inbox** in the right-hand panel of the Gumball home screen and turn it off.
</Accordion>
<Accordion title="Can I delete Gumball completely?" icon="trash">
No. Gumball is your built-in personal agent, one per account, and its address `gumball@gumloop.ai` is reserved, so it cannot be deleted or renamed. You can silence it instead: turn off **Email** delivery, pause the Daily Chew, turn off automatic Meeting Prep, and turn off Smart Inbox. With those off, Gumball only acts when you ask it to in chat.
</Accordion>
<Accordion title="I want to stop every Gumloop email or close my account" icon="user-xmark">
Turning off Gumball's emails does not cancel your account. To leave Gumloop, delete your account from **Settings → Profile → [General](https://www.gumloop.com/settings/profile/general)** under **Danger Zone**. If you only want to end a paid plan, see [How Do I Cancel My Plan or Free Trial?](/help/account-billing/cancel-plan-or-trial).
</Accordion>
</AccordionGroup>
## Related
<CardGroup>
<Card title="Gumball" icon="compass" href="/core-concepts/gumball">
How your personal agent, Daily Chew, Smart Inbox, and Meeting Prep work.
</Card>
<Card title="Profile settings" icon="user" href="/core-concepts/profile_settings">
Your personal preferences and agent notifications.
</Card>
</CardGroup>
# Welcome to Gumloop
Source: https://docs.gumloop.com/index
Gumloop is an AI agent platform. Build AI agents that use your tools and data to do real work, then automate them with triggers, schedules, and the API.
<div>
<div>
<h1>Welcome to Gumloop</h1>
<p>Build AI agents that use your tools and data to do real work.</p>
</div>
<div>
<a href="/core-concepts/agents">
<span>Create Agents</span>
<span>Put your tools to work</span>
<span>
<img alt="" />
</span>
</a>
<a href="/api-reference/getting-started">
<span>API Reference</span>
<span>Run agents over REST</span>
<span>
<img alt="" />
</span>
</a>
<a href="/mcp-server/overview">
<span>MCP Server</span>
<span>Gumloop in Claude</span>
<span>
<img alt="" />
</span>
</a>
<a href="https://university.gumloop.com/">
<span>University</span>
<span>Short video lessons</span>
<span>
<img alt="" />
</span>
</a>
</div>
</div>
# MCP server
Source: https://docs.gumloop.com/mcp-server/overview
Connect to the Gumloop MCP server from Claude, Cursor, VS Code, and other MCP-compatible clients.
Gumloop exposes a remote [Model Context Protocol (MCP)](https://www.gumloop.com/blog/what-is-mcp-model-context-protocol-a-simple-guide) server that lets any compatible AI client manage your agents, sessions, skills, and more.
Connect to the Gumloop MCP server natively in Claude, Cursor, and other clients, or use [`mcp-remote`](https://www.npmjs.com/package/mcp-remote) for clients that don't yet support remote MCP.
```text theme={"dark"}
https://mcp.gumloop.com/gumloop/mcp
```
<Info>
You'll need a Gumloop API key. Get one from the [Gumloop API Key connector](https://www.gumloop.com/settings/profile/connectors?view=connected\&search=Gumloop+API+Key). The server handles OAuth automatically: you'll be prompted to sign in and authorize access the first time you connect.
</Info>
## Setup
### Claude
Navigate to **Settings > Connectors** and add a new MCP integration with the URL:
```text theme={"dark"}
https://mcp.gumloop.com/gumloop/mcp
```
### Cursor
1. Open Cursor Settings (Cmd/Ctrl + Shift + J)
2. Go to **MCP** and click **Add new MCP server**
3. Select **Type: SSE** and enter the server URL:
```text theme={"dark"}
https://mcp.gumloop.com/gumloop/mcp
```
### VS Code
Add the following to your `.vscode/mcp.json`:
```json theme={"dark"}
{
"mcpServers": {
"gumloop": {
"command": "npx",
"args": ["-y", "mcp-remote", "https://mcp.gumloop.com/gumloop/mcp"]
}
}
}
```
### Windsurf
1. Open Windsurf settings (Cmd/Ctrl + ,)
2. Scroll to **Cascade > MCP servers**
3. Select **Add Server > Add custom server**
4. Add:
```json theme={"dark"}
{
"mcpServers": {
"gumloop": {
"command": "npx",
"args": ["-y", "mcp-remote", "https://mcp.gumloop.com/gumloop/mcp"]
}
}
}
```
### Gumloop CLI
You can also explore and call tools from your terminal:
```bash theme={"dark"}
gumloop mcp list # List connected servers
gumloop mcp tools gumloop # Browse available tools
gumloop mcp call gumloop list_agents --args-json '{}' # Call a tool
```
See the [CLI MCP docs](/cli/mcp) for the full reference.
## Available tools
The Gumloop MCP server exposes 46 tools across these categories:
### Agent management
| Tool | Description |
| - | - |
| `list_agents` | List agents in your account, with optional search and workspace filtering |
| `get_agent` | Fetch a single agent's configuration by its ID |
| `create_agent` | Create a new agent with a name, model, and optional configuration (including `skill_ids` to attach skills) |
| `update_agent` | Update an existing agent's metadata or configuration |
| `attach_agent_skills` | Attach one or more existing skills to a Gumloop agent |
| `detach_agent_skills` | Detach one or more skills from a Gumloop agent |
| `attach_agent_mcp_server` | Attach an MCP server (connector) to an agent, or update its configuration if already attached |
| `detach_agent_mcp_server` | Detach an MCP server (connector) from an agent |
| `list_models` | List the model groups available to agents |
| `list_agent_versions` | List the immutable versions of an agent |
| `get_agent_version` | Fetch an immutable agent version and its configuration |
### Agent sessions
| Tool | Description |
| - | - |
| `start_agent` | Send a message to an agent and start an asynchronous interaction |
| `get_agent_status` | Poll the status of an agent interaction and retrieve the response when completed |
| `create_agent_session` | Start a session on an agent and return the completed response |
| `get_session` | Fetch the state and result of an agent session by ID |
| `send_session_message` | Send a follow-up message to an existing session and return the completed response |
| `cancel_session` | Cancel an in-progress agent session |
| `rename_session` | Rename an agent session (chat) |
| `list_agent_sessions` | List an agent's sessions, with search, filters, sort, and pagination |
### Skills
| Tool | Description |
| - | - |
| `list_skills` | List skills in your account, with optional search, filtering, and pagination |
| `create_skill` | Create a skill from one or more files stored in your workspace |
| `update_skill` | Replace a skill's files with files stored in your workspace |
| `delete_skill` | Delete a skill from your account |
| `download_skill` | Get a download URL for a skill archive |
### Artifacts
| Tool | Description |
| - | - |
| `list_agent_artifacts` | List the artifacts an agent has produced, with optional session filtering and pagination |
| `download_artifact` | Get a download URL for an agent artifact |
### Teams
| Tool | Description |
| - | - |
| `list_teams` | List the teams (workspaces) the authenticated user belongs to |
### MCP server management
| Tool | Description |
| - | - |
| `list_mcp_servers` | List the MCP servers connected to your account |
| `get_mcp_server` | Fetch a single connected MCP server's configuration by ID |
| `list_mcp_server_tools` | List the tools exposed by a connected MCP server |
| `call_mcp_tool` | Execute a single tool on a connected MCP server |
| `list_mcp_resources` | List the resources exposed by a connected MCP server |
| `read_mcp_resource` | Read the contents of a resource from a connected MCP server by URI |
| `list_mcp_prompts` | List the prompts exposed by a connected MCP server |
| `get_mcp_prompt` | Get a rendered prompt from a connected MCP server, with optional arguments |
### Company Brain
| Tool | Description |
| - | - |
| `search_brain` | Search your Company Brain's indexed knowledge sources for relevant content |
### Documentation
| Tool | Description |
| - | - |
| `search_documentation` | Search Gumloop documentation using semantic and keyword search with filtering options |
| `ask_gummie` | Ask questions and get AI-powered answers from Gumloop documentation with citations |
### Audit logs
| Tool | Description |
| - | - |
| `get_audit_logs` | Retrieve organization [audit logs](/enterprise-features/audit_logging) with event details and filtering by time period (admin only) |
Audit logs are available over MCP as well as the [REST API](/api-reference/organization/get-audit-logs). The tool takes an `organization_id`, your `user_id`, a `start_time`/`end_time` window, and an optional `max_limit` (pagination is handled for you). Server-side filters beyond the time window — by event type, user, IP address, workspace, or entity — are REST-only. Only organization **Admins** can read audit logs, over MCP or REST.
### Data exports
| Tool | Description |
| - | - |
| `export_data` | Create an organization data export for workflows, agents, agent interactions, credit logs, or Gumstack usage over a date range (admin only) |
| `get_export_status` | Poll an export's status and get a signed download URL for the completed CSV |
Use these two together to pull your organization's agent and usage data into an MCP client: call `export_data` with a `data_type` (`workflows`, `agents`, `agent_interactions`, `credit_logs`, or `gumstack`), a date range, and the columns you want, then poll `get_export_status` with the returned `data_export_id` until it reports `COMPLETED` and request the download URL. Audit log exports aren't one of the MCP `data_type` options — read audit events with `get_audit_logs`, or set up an [audit log data drain](/enterprise-features/organization_data_export#data-drains).
<Note>
The aggregated charts on the Organization Insights dashboard (overview totals, model usage, leaderboards, skill adoption, artifact analytics) aren't available over MCP or the REST API. Use data exports for the underlying rows.
</Note>
### Flows & runs
| Tool | Description |
| - | - |
| `list_saved_flows` | List saved flows/items in your account for a user or project |
| `list_workbooks` | List workbooks and the saved flows they contain |
| `start_flow_run` | Start a flow run, with optional inputs for its input steps |
| `get_run_details` | Retrieve a flow run's state, outputs, and logs |
| `get_run_history` | Retrieve the 10 most recent runs for a workbook or saved item |
## MCP vs. the REST API
The MCP server and the [REST API](/api-reference/getting-started) overlap heavily, but neither is a strict superset of the other.
| Surface | MCP | REST API |
| - | - | - |
| Agents, versions, skills, artifacts, model groups | Yes | Yes |
| Agent sessions (start, poll, follow up, cancel) | Yes | Yes |
| Connected MCP servers (list, inspect, call tools) | Yes | Yes |
| Flows, workbooks, and runs | Yes | Yes |
| Company Brain search | Yes | Yes |
| Audit logs | Yes (`get_audit_logs`, time range only) | Yes (`GET /get_audit_logs`, with event/user/IP/workspace filters) |
| Organization data exports | Yes (`export_data`, `get_export_status`) | Yes |
| Gumloop documentation search | Yes (`search_documentation`, `ask_gummie`) | No |
| Evaluations | No | Yes |
| Session approvals and queued messages | No | Yes |
| Workspace file upload and download | No | Yes |
| Workspace/role membership and role credit limits | No | Yes |
| Chat completions (OpenAI-compatible) | No | Yes |
In short: use MCP when an AI client should drive Gumloop (agent management, sessions, skills, flows, Brain, audit logs, exports, and docs search), and the REST API when you need the full administrative surface — evaluations, approvals, file operations, and organization membership and credit administration.
## Example prompts
Once connected, try these with your AI client:
```text theme={"dark"}
Create a new agent called "Research Assistant" using the GPT-4o model
```
```text theme={"dark"}
Start a session with my Research Assistant agent and ask it to summarize the latest quarterly report
```
```text theme={"dark"}
What MCP servers are connected to my account?
```
```text theme={"dark"}
Search my Company Brain for our refund policy and summarize what it says
```
```text theme={"dark"}
Export my organization's agent interactions for the last 30 days and tell me when the CSV is ready
```
```text theme={"dark"}
Pull our audit logs for the last 7 days and summarize the credential_retrieval events
```
## Related resources
<CardGroup>
<Card title="Gumloop MCP integration" icon="plug" href="https://www.gumloop.com/mcp/gumloop">
Full tool reference and usage examples.
</Card>
<Card title="API reference" icon="code" href="/api-reference/mcp/list-servers">
Programmatically manage MCP servers and call tools via the REST API.
</Card>
<Card title="CLI reference" icon="terminal" href="/cli/mcp">
Explore and call MCP tools from your terminal.
</Card>
<Card title="Custom MCP servers" icon="plug" href="/nodes/mcp/custom_mcp_servers">
Connect your own MCP servers to Gumloop.
</Card>
<Card title="Audit logging" icon="shield" href="/enterprise-features/audit_logging">
Tracked events, log structure, and admin access requirements.
</Card>
</CardGroup>
## Need help?
* [Agents documentation](/core-concepts/agents) for using MCP tools with agents
* Need help? [Reach out to us](https://portal.usepylon.com/gumloop/forms/help)
* Browse our [Knowledge Base](https://support.gumloop.com/) for common questions
# BigQuery Workload Identity Federation
Source: https://docs.gumloop.com/nodes/integrations/bigquery-workload-identity-federation
Connect BigQuery to Gumloop without OAuth or static service-account keys using GCP Workload Identity Federation.
This guide walks you through connecting BigQuery to Gumloop using **Workload Identity Federation (WIF)**. Instead of per-user OAuth (which forces each teammate to reconnect whenever your GCP session-control window expires) or static service-account key files (which many security policies prohibit), Gumloop acts as an OIDC identity provider that your GCP project federates. Tokens are minted on demand and are short-lived, and no long-lived secrets are ever stored.
<Note>
**Intended Audience:** GCP administrators with permission to manage workload identity pools and service accounts (`roles/iam.workloadIdentityPoolAdmin` and `roles/iam.serviceAccountAdmin`, or `roles/owner`). This setup is performed once and enables keyless BigQuery access for your whole team.
</Note>
## Why use Workload Identity Federation?
<CardGroup>
<Card title="Keyless" icon="key">
No service-account key files to store, rotate, or leak. Gumloop never holds a long-lived secret for your project.
</Card>
<Card title="No daily reconnect" icon="arrows-rotate">
Federation is not tied to a human session, so session-control reauth windows never interrupt your agents or flows.
</Card>
<Card title="Short-lived tokens" icon="clock">
Gumloop mints a fresh, short-lived access token for each request via GCP STS. Nothing durable is persisted.
</Card>
<Card title="You stay in control" icon="user-shield">
You decide which service account Gumloop may impersonate and exactly which Gumloop tenant your pool trusts.
</Card>
</CardGroup>
## How it works
<Steps>
<Step title="Gumloop mints an OIDC token">
At query time, Gumloop signs a short-lived OIDC token identifying your Gumloop organization. Its issuer is `https://api.gumloop.com`.
</Step>
<Step title="GCP STS verifies and exchanges it">
Your workload identity pool verifies the token's signature against Gumloop's published JWKS and checks your attribute condition, then exchanges it for a federated token.
</Step>
<Step title="Gumloop impersonates your service account">
The federated token impersonates the target service account you nominate, yielding a short-lived Google access token scoped to BigQuery.
</Step>
<Step title="Gumloop queries BigQuery">
That access token is used for the BigQuery call, then discarded.
</Step>
</Steps>
Gumloop's OIDC issuer publishes its discovery document and public keys, which your pool uses to verify tokens:
* Discovery: `https://api.gumloop.com/.well-known/openid-configuration`
* JWKS: `https://api.gumloop.com/oauth/jwks`
<Accordion title="Claims included in the Gumloop OIDC token">
Every claim is derived server-side from the authenticated credential owner; none come from user input.
* `iss` — `https://api.gumloop.com`
* `sub` — `gumloop:project:<workspace_id>` or `gumloop:user:<user_id>`
* `aud` — the full resource path of your pool provider
* `gumloop_org_id` — your Gumloop organization ID (use this to lock down the pool)
* `gumloop_owner_type` — `project` or `user`
* `gumloop_owner_id` — the Gumloop workspace or user ID that owns the credential
* `iat` / `exp` — issued-at and a short (5 minute) expiry
</Accordion>
***
## Prerequisites
Before you begin, gather:
* Your **GCP project ID** and **project number** (`gcloud projects describe YOUR_PROJECT_ID --format="value(projectNumber)"`)
* Your **Gumloop organization ID** — provided by Gumloop. This is what you will pin your pool to so that only your tenant's tokens are accepted.
* Permission to create workload identity pools and service accounts in the project
Then enable the APIs this setup relies on:
```bash theme={"dark"}
gcloud services enable iamcredentials.googleapis.com bigquery.googleapis.com \
--project="YOUR_PROJECT_ID"
```
* `iamcredentials.googleapis.com` — required for Gumloop to impersonate your service account (the `generateAccessToken` call). Without it, token exchange fails with a `403 SERVICE_DISABLED` error.
* `bigquery.googleapis.com` — required to run queries.
<Warning>
**Pin your pool to your Gumloop organization.** Because Gumloop's issuer can mint tokens for any Gumloop customer, you must set an attribute condition that restricts your pool to your own `gumloop_org_id`. Without it, any Gumloop tenant's token could be accepted by your pool. This is the single most important step for tenant isolation.
</Warning>
***
## Step 1: Create a Workload Identity pool
```bash theme={"dark"}
gcloud iam workload-identity-pools create gumloop-pool \
--project="YOUR_PROJECT_ID" \
--location="global" \
--display-name="Gumloop"
```
## Step 2: Add Gumloop as an OIDC provider
Create an OIDC provider in the pool that trusts Gumloop's issuer, maps the token claims, and restricts access to your Gumloop organization.
```bash theme={"dark"}
gcloud iam workload-identity-pools providers create-oidc gumloop-oidc \
--project="YOUR_PROJECT_ID" \
--location="global" \
--workload-identity-pool="gumloop-pool" \
--issuer-uri="https://api.gumloop.com" \
--attribute-mapping="google.subject=assertion.sub,attribute.gumloop_org_id=assertion.gumloop_org_id,attribute.gumloop_owner_id=assertion.gumloop_owner_id" \
--attribute-condition="assertion.gumloop_org_id == 'YOUR_GUMLOOP_ORG_ID'"
```
<Accordion title="Understanding these parameters">
* **issuer-uri** — Gumloop's OIDC issuer. GCP reads `https://api.gumloop.com/.well-known/openid-configuration` to discover the JWKS used to verify tokens.
* **attribute-mapping** — Maps Gumloop token claims into pool attributes. `google.subject` is required; the `attribute.*` mappings let you reference claims in conditions and IAM bindings.
* **attribute-condition** — The security gate. Only tokens whose `gumloop_org_id` equals your organization are allowed. Replace `YOUR_GUMLOOP_ORG_ID` with the value Gumloop provided.
</Accordion>
<Info>
You do not need to set `--allowed-audiences`. Gumloop sets the token audience to the provider's full resource path, which is the default audience GCP accepts.
</Info>
## Step 3: Create the target service account
This is the identity Gumloop will impersonate. Grant it only the BigQuery permissions your team needs.
```bash theme={"dark"}
gcloud iam service-accounts create bigquery-runner \
--project="YOUR_PROJECT_ID" \
--display-name="Gumloop BigQuery Runner"
gcloud projects add-iam-policy-binding YOUR_PROJECT_ID \
--member="serviceAccount:bigquery-runner@YOUR_PROJECT_ID.iam.gserviceaccount.com" \
--role="roles/bigquery.dataViewer"
gcloud projects add-iam-policy-binding YOUR_PROJECT_ID \
--member="serviceAccount:bigquery-runner@YOUR_PROJECT_ID.iam.gserviceaccount.com" \
--role="roles/bigquery.jobUser"
```
<Tip>
Follow the principle of least privilege. `roles/bigquery.dataViewer` + `roles/bigquery.jobUser` is enough to run read queries. Grant narrower dataset-level roles if you prefer.
</Tip>
## Step 4: Allow the pool to impersonate the service account
Grant `roles/iam.workloadIdentityUser` on the service account to the federated identities from your pool, scoped to your `gumloop_org_id` attribute.
```bash theme={"dark"}
gcloud iam service-accounts add-iam-policy-binding \
bigquery-runner@YOUR_PROJECT_ID.iam.gserviceaccount.com \
--project="YOUR_PROJECT_ID" \
--role="roles/iam.workloadIdentityUser" \
--member="principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/gumloop-pool/attribute.gumloop_org_id/YOUR_GUMLOOP_ORG_ID"
```
<Warning>
Use the **project number** (not the project ID) in the `principalSet://` member, and scope it with `attribute.gumloop_org_id/...` rather than a wildcard so only your organization's tokens can impersonate the service account.
</Warning>
## Step 5: Collect the three values for Gumloop
You will paste these into Gumloop:
1. **GCP Project Number** — e.g. `123456789012`
2. **Workload Identity Pool Resource Name** — the provider resource path:
```text theme={"dark"}
projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/gumloop-pool/providers/gumloop-oidc
```
3. **Target Service Account Email** — e.g. `bigquery-runner@YOUR_PROJECT_ID.iam.gserviceaccount.com`
## Step 6: Add the credential in Gumloop
1. Go to the [Connectors page](https://www.gumloop.com/settings/profile/connectors?view=connected) (or your workspace credentials for a shared, team-wide connection).
2. Click **Add Credential** and select **BigQuery (Workload Identity)**.
3. Enter the three values from Step 5 and save.
Your agents can now use BigQuery through Workload Identity Federation, which mints short-lived access tokens without OAuth prompts.
<Tip>
Use a team connector to share the keyless connection with your team. Use a personal connector for agents you run with your own account.
</Tip>
***
## Troubleshooting
### "Permission denied" or no credentials found
* Confirm the attribute condition value matches the `gumloop_org_id` Gumloop provided exactly.
* Confirm the `principalSet://` binding uses the **project number** and the same `attribute.gumloop_org_id` value.
* Confirm the service account has `roles/bigquery.jobUser` (needed to run queries) in addition to a data-read role.
### "IAM Service Account Credentials API has not been used... or it is disabled"
The impersonation step calls `iamcredentials.googleapis.com`, which must be enabled in your project. Enable it (and the BigQuery API), then wait a minute or two for the change to propagate:
```bash theme={"dark"}
gcloud services enable iamcredentials.googleapis.com bigquery.googleapis.com \
--project="YOUR_PROJECT_ID"
```
### "Invalid audience" / token rejected by STS
* Make sure the **Workload Identity Pool Resource Name** you pasted into Gumloop is the full provider path ending in `/providers/<provider-id>`.
### Verifying the issuer is reachable
The discovery and JWKS endpoints are public and should return JSON:
```bash theme={"dark"}
curl https://api.gumloop.com/.well-known/openid-configuration
curl https://api.gumloop.com/oauth/jwks
```
***
## Additional resources
* [GCP Workload Identity Federation documentation](https://cloud.google.com/iam/docs/workload-identity-federation)
* [Configuring OIDC-based federation](https://cloud.google.com/iam/docs/workload-identity-federation-with-other-providers)
* [Connectors](/core-concepts/credentials)
## Need help?
If you run into issues not covered here, [reach out to us](https://portal.usepylon.com/gumloop/forms/help).
# NetSuite OAuth configuration
Source: https://docs.gumloop.com/nodes/integrations/netsuite-oauth-config
This guide walks you through setting up NetSuite OAuth authentication for Gumloop. By following these steps, you'll configure a secure OAuth integration that allows Gumloop to connect to your NetSuite account on behalf of your users.
<Note>
**Intended Audience:** NetSuite administrators with administrator access or users with Integration Application permission. This setup is performed once and enables OAuth authentication for your organization's NetSuite connection.
</Note>
<Warning>
This guide provides basic setup instructions for integrating NetSuite with Gumloop. For production environments and security best practices, please refer to the [official NetSuite OAuth 2.0 documentation](https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/section_157771733782.html) to ensure your configuration meets your organization's security requirements.
</Warning>
## What this guide covers
This documentation will help you:
1. **Create a NetSuite Integration Record** - Register Gumloop as an OAuth 2.0 client in NetSuite
2. **Configure Role Permissions** - Set up OAuth permissions for user roles
3. **Retrieve OAuth Credentials** - Get the Client ID and Client Secret needed for Gumloop
4. **Configure Gumloop (Administrator)** - Add the NetSuite OAuth Config to your organization
5. **User Authentication** - Connect individual user accounts
Once complete, your team will be able to authenticate NetSuite connections through OAuth in Gumloop.
## Overview
NetSuite OAuth integration enables secure authentication between Gumloop and your NetSuite ERP account. Instead of sharing static credentials, OAuth allows users to authorize Gumloop to access NetSuite on their behalf with automatic token refresh and better security controls.
### Why use NetSuite OAuth with Gumloop?
<CardGroup>
<Card title="Enhanced security" icon="shield-halved">
OAuth tokens are temporary and can be revoked, reducing the risk of credential exposure
</Card>
<Card title="Automatic token refresh" icon="arrows-rotate">
Refresh tokens keep your connection active without manual re-authentication
</Card>
<Card title="Centralized control" icon="sliders">
Manage access and permissions directly in NetSuite
</Card>
<Card title="Audit trail" icon="list-check">
Track OAuth authentication events in NetSuite's audit logs
</Card>
</CardGroup>
***
## Prerequisites
Before you begin, ensure you have:
* **NetSuite Account Access** - You need administrator access or Integration Application permission
* **NetSuite Account ID** - Your NetSuite account identifier (e.g., `1234567` or `1234567_SB1` for sandbox)
***
## Step 1: Create the NetSuite integration record
You'll create an OAuth 2.0 integration record in NetSuite to register Gumloop as an authorized application.
### 1.1 Navigate to integration management
1. Log in to your [NetSuite account](https://system.netsuite.com)
2. Navigate to **Setup > Integration > Manage Integrations > New**
<Info>
If you don't have access to this menu, contact your NetSuite administrator to either grant you the necessary permissions or create the integration on your behalf.
</Info>
### 1.2 Configure basic information
Enter the following details in the integration record:
* **Name:** `Gumloop` (or your preferred name, e.g., "Gumloop NetSuite Integration")
* **Description:** Optional description for documentation purposes
* **State:** Set to **Enabled**
### 1.3 Configure authentication settings
On the **Authentication** subtab, configure the following settings:
<Steps>
<Step title="Enable token-based authentication">
Check **Token-Based Authentication** to enable this authentication method.
</Step>
<Step title="Configure OAuth 2.0 Settings">
Under **OAuth 2.0**, configure the following:
* **Authorization Code Grant:** Check this option
* **Public Client:** Check this option (required for the integration)
* **Redirect URI:** Enter `https://api.gumloop.com/auth/callback`
<Warning>
**Important:** The redirect URI must be exactly `https://api.gumloop.com/auth/callback`. The `http://` scheme is not supported for security reasons.
</Warning>
</Step>
<Step title="Enable required scopes">
Enable the following scopes (you can remove other enabled scopes):
* **RESTlets** - Required for RESTlet access
* **REST Web Services** - Required for REST API access
<Info>
These are the minimum required scopes for Gumloop to interact with NetSuite records and run SuiteQL queries.
</Info>
</Step>
<Step title="Enable user credentials">
Under **User Credentials**, check **User Credential** to enable user-based authentication.
</Step>
</Steps>
### 1.4 Optional settings
You may also configure these optional settings based on your organization's needs:
* **Refresh Token Validity:** Default is 48 hours (range: 1-720 hours)
* **Maximum Time For Token Rotation:** Default is 168 hours (range: 1-720 hours)
* **OAuth 2.0 Consent Policy:** Choose "Always Ask", "Never Ask", or "Ask First Time"
### 1.5 Save and record credentials
1. Click **Save**
2. After saving, copy and securely store your:
* **Client ID**
* **Client Secret**
* **Account ID**
<Warning>
**Important:** The Client ID and Client Secret are only displayed once after saving. If lost, you'll need to reset them to obtain new values. Store these credentials securely.
</Warning>
***
## Step 2: Configure role permissions
OAuth is not automatically enabled for all NetSuite roles. You must configure the appropriate permissions for users who will authenticate via OAuth.
### 2.1 Edit user roles
1. Navigate to **Setup > Users/Roles > Manage Roles**
2. Edit the role you want to use for OAuth authentication
### 2.2 Add OAuth permissions
Under **Permissions > Setup**, add the following OAuth permissions:
| Permission | Description |
| - | - |
| **OAuth 2.0 Authorized Applications Management** | For admins managing auth apps |
| **Log in using OAuth 2.0 Access Tokens** | Required for OAuth 2.0 login |
### 2.3 Add functional permissions
Under **Permissions > Setup** or **Permissions > Web Services**, add the functional permissions required for your integration:
| Permission | Description |
| - | - |
| **REST Web Services** | Access to REST API endpoints |
| **RESTlets** | Access to RESTlet scripts |
| **User Access Tokens** | Ability to use access tokens |
<Tip>
The specific permissions needed depend on your use case. At minimum, ensure REST Web Services and RESTlets are enabled for the role.
</Tip>
### 2.4 Save the role
Click **Save** to apply the permission changes.
<Info>
For detailed information on role permissions, refer to the [NetSuite OAuth 2.0 documentation](https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/section_157771733782.html#procedure_157838925981).
</Info>
***
<span />
## Step 3: Configure the NetSuite connector in Gumloop
Now that you have your NetSuite OAuth credentials, you'll add them to Gumloop. The setup process differs based on your Gumloop plan.
<Note>
**Understanding the Two Credential Types:**
* **NetSuite OAuth Config** - Contains the Client ID and Client Secret from your NetSuite integration record
* **NetSuite** - Your personal NetSuite authentication that uses the OAuth Config to connect
Both credentials are required for NetSuite OAuth to work. The difference is where the OAuth Config is stored based on your plan.
</Note>
<Tabs>
<Tab title="Pro & Enterprise plans" icon="building">
### Organization-Level Setup (Recommended)
For users on **Pro** or **Enterprise** plans, organization administrators can configure the NetSuite OAuth Config once at the organization level. After this setup, all organization members only need to add their personal NetSuite credentials.
#### Administrator Setup
1. Navigate to [Settings → Organization → OAuth Configuration](https://www.gumloop.com/settings/organization/oauth-configuration)
2. Search for **"NetSuite OAuth Config"** in the credentials list
3. Click **Add Credential**
4. Enter the following information:
* **Client ID**: The Client ID from Step 1.5
* **Client Secret**: The Client Secret from Step 1.5
5. Save the configuration
<Tip>
Once an organization admin completes this setup, all organization members can authenticate with NetSuite without needing to configure the OAuth Config themselves.
</Tip>
#### User Setup (After Admin Configuration)
After your organization admin has configured the OAuth Config:
1. Navigate to [Connectors page](https://www.gumloop.com/settings/profile/connectors?view=connected)
2. Click **Add Credential**
3. Select **NetSuite** from the list of integrations
4. Enter your **workspace name** (the first part of your NetSuite URL, e.g., `gumloop` for `gumloop.app.netsuite.com`)
5. Click **Add credential** - you'll be redirected to NetSuite to log in and authorize
6. After logging in, you'll be redirected back to Gumloop with a successful connection
</Tab>
<Tab title="Individual users" icon="user">
### Personal Credentials Setup
For users **without an organization**, you need to add **both** the NetSuite OAuth Config and your NetSuite credentials under your personal credentials.
#### Step 1: Add NetSuite OAuth Config
1. Navigate to [Connectors page](https://www.gumloop.com/settings/profile/connectors?view=connected)
2. Click **Add Credential**
3. Search for **"NetSuite OAuth Config"**
4. Enter the following information:
* **Client ID**: The Client ID from Step 1.5
* **Client Secret**: The Client Secret from Step 1.5
5. Save the configuration
#### Step 2: Add NetSuite Credentials
1. Click **Add Credential** again
2. Select **NetSuite** from the list of integrations
3. Enter your **workspace name** (the first part of your NetSuite URL, e.g., `gumloop` for `gumloop.app.netsuite.com`)
4. Click **Add credential** - you'll be redirected to NetSuite to log in and authorize
5. After logging in, you'll be redirected back to Gumloop with a successful connection
<Warning>
Individual users must configure both credentials. If you only add the NetSuite OAuth Config without adding the NetSuite credential, you won't be able to authenticate.
</Warning>
</Tab>
</Tabs>
***
## Step 4: User authentication
Once the NetSuite OAuth Config is set up (either at the organization level or personally), users can connect their NetSuite accounts with a simple OAuth flow.
### 4.1 Connect your NetSuite account
1. Navigate to [Connectors page](https://www.gumloop.com/settings/profile/connectors?view=connected)
2. Click **Add Credential**
3. Select **NetSuite** from the list of integrations
4. Enter your **workspace name** - this is the first part of your NetSuite URL (e.g., `gumloop` for `gumloop.app.netsuite.com`)
5. Click **Add credential**
<Info>
**Finding Your Workspace Name**
Your workspace name is the subdomain of your NetSuite account URL:
* If your NetSuite URL is `https://gumloop.app.netsuite.com`, your workspace name is `gumloop`
* If your NetSuite URL is `https://mycompany.app.netsuite.com`, your workspace name is `mycompany`
</Info>
### 4.2 Authorize via NetSuite
After clicking **Add credential**:
1. You'll be automatically redirected to NetSuite's login page
2. Log in with your NetSuite credentials
3. Review and approve the requested permissions
4. You'll be redirected back to Gumloop with a successful connection
<Tip>
The entire process takes just a few seconds - enter your workspace name, click Add credential, log in to NetSuite, and you're done!
</Tip>
### 4.3 Verify your connection
To confirm your OAuth connection is working correctly:
1. Go to [Connectors page](https://www.gumloop.com/settings/profile/connectors?view=connected)
2. Search for **NetSuite**
3. If the connection is successful, you should see your NetSuite account connected
***
## Troubleshooting
### "Invalid Client" Error
**Problem:** Getting an "invalid\_client" error when connecting
**Solution:**
* Verify the Client ID and Client Secret are correct in the NetSuite OAuth Config
* Check that the integration is enabled in NetSuite
* Ensure the redirect URI matches exactly: `https://api.gumloop.com/auth/callback`
### "Access Denied" or permission errors
**Problem:** Connected successfully but NetSuite operations return permission errors
**Solution:**
* Verify the user's role has the required OAuth permissions (Step 2)
* Ensure REST Web Services and RESTlets scopes are enabled on the integration
* Check that the user has been assigned a role with the necessary permissions
### OAuth not working for specific users
**Problem:** Some users can't authenticate via OAuth
**Solution:**
* OAuth is not automatically enabled for all roles
* Verify the user's role has "Log in using OAuth 2.0 Access Tokens" permission
* Check that the role has REST Web Services and RESTlets permissions
### Token expiring too quickly
**Problem:** Users need to re-authenticate frequently
**Solution:**
Increase the refresh token validity in your NetSuite integration record:
1. Go to **Setup > Integration > Manage Integrations**
2. Edit your Gumloop integration
3. Increase **Refresh Token Validity** (up to 720 hours / 30 days)
***
## Security best practices
<CardGroup>
<Card title="Regular credential rotation" icon="key">
Periodically rotate your OAuth client secrets to maintain security
</Card>
<Card title="Principle of least privilege" icon="user-shield">
Grant users only the minimum NetSuite roles needed for their work
</Card>
<Card title="Monitor OAuth activity" icon="chart-line">
Regularly review OAuth token usage in NetSuite audit logs
</Card>
<Card title="Role-based access" icon="users-gear">
Use NetSuite roles to control what data users can access through Gumloop
</Card>
</CardGroup>
<Info>
For comprehensive security guidance and advanced configuration options, refer to the [official NetSuite OAuth 2.0 documentation](https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/section_157771733782.html).
</Info>
***
## Additional resources
* [NetSuite OAuth 2.0 Documentation](https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/section_157771733782.html)
* [NetSuite REST Web Services](https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/section_1558708800.html)
* [NetSuite SuiteQL](https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/section_156257770590.html)
* [Connectors](/core-concepts/credentials)
* [Okta Integration Guide](/core-concepts/okta-integration)
***
## Need help?
If you encounter issues not covered in this guide:
1. Check the [NetSuite OAuth 2.0 documentation](https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/section_157771733782.html) for detailed technical information
2. Contact your NetSuite administrator for account-specific issues
3. [Reach out to us](https://portal.usepylon.com/gumloop/forms/help) for integration assistance
# Snowflake key-pair configuration
Source: https://docs.gumloop.com/nodes/integrations/snowflake-keypair-config
This guide walks you through connecting Gumloop to Snowflake using **RSA key-pair (JWT) authentication**. Key-pair auth uses a private/public key pair instead of a password or browser login, which makes it ideal for service users and for accounts where multi-factor authentication (MFA) is enforced.
<Note>
**When to use Key-Pair:** Key-pair authentication is the best fit for **service (non-human) users** and for **accounts with MFA enforced**, since JWT-based connections are not prompted for an interactive MFA challenge. If you prefer browser-based login with automatic token refresh, use [Snowflake OAuth](/nodes/integrations/snowflake-oauth-config) instead.
</Note>
## What this guide covers
<CardGroup>
<Card title="Generate a key pair" icon="key">
Create an RSA private/public key pair in PEM (PKCS#8) format.
</Card>
<Card title="Register the public key" icon="snowflake">
Assign the public key to your Snowflake user with `ALTER USER`.
</Card>
<Card title="Configure Gumloop" icon="plug">
Add your Snowflake Key-Pair credential in the Connectors page.
</Card>
<Card title="Verify & troubleshoot" icon="circle-check">
Confirm the connection and resolve common errors.
</Card>
</CardGroup>
***
## Which authentication method should you use?
Gumloop supports three ways to authenticate to Snowflake. You only need **one**.
<CardGroup>
<Card title="OAuth (Recommended)" icon="shield-check">
Browser-based login with automatic token refresh and centralized control.
[Set up OAuth →](/nodes/integrations/snowflake-oauth-config)
</Card>
<Card title="Key-Pair" icon="key">
RSA JWT auth. Best for service users and MFA-enforced accounts. **You are here.**
</Card>
<Card title="PAT" icon="lock">
Programmatic Access Token (username + token).
[Set up PAT →](/nodes/integrations/snowflake-pat-config)
</Card>
</CardGroup>
<Info>
When multiple Snowflake credentials exist, Gumloop resolves them in this order: **OAuth → Key-Pair → PAT**. For a clean setup, configure just the one method you intend to use.
</Info>
***
## Prerequisites
Before you begin, ensure you have:
* **Snowflake account access** — a user account you can run `ALTER USER` on (or a Snowflake admin who can do it for you)
* **Account identifier** — the first part of your Snowflake URL, e.g. `myorg-account123` from `https://myorg-account123.snowflakecomputing.com`
* **OpenSSL** (or any tool that can generate an RSA key in PKCS#8 format) available on your machine
* **Public internet access to Snowflake** — Gumloop connects to your account over the public internet (see the [PrivateLink note](#privatelink-and-network-policies) below)
<Warning>
**PrivateLink accounts are not supported with Gumloop's standard (cloud-hosted) deployment** unless you whitelist Gumloop's [static egress IPs](/enterprise-features/static_egress_ips) in your Snowflake network policy. Key-pair authentication requires Gumloop to reach your Snowflake account over the public internet. If your account is behind AWS PrivateLink, Azure Private Link, or Google Cloud Private Service Connect and you cannot whitelist Gumloop's IPs, connections will fail.
**The solution is a VPC deployment**, where Gumloop runs inside your network perimeter. Contact [support@gumloop.com](mailto:support@gumloop.com) to explore VPC deployment options.
</Warning>
***
## Step 1: Generate an RSA key pair
Run these commands locally to create the key pair. Gumloop requires the **private key** in PEM (PKCS#8) format.
### 1.1 Generate the private key
<CodeGroup>
```bash Encrypted (recommended) theme={"dark"}
# Prompts for a passphrase — you'll enter this same passphrase in Gumloop
openssl genrsa 2048 | openssl pkcs8 -topk8 -inform PEM -out rsa_key.p8
```
```bash Unencrypted theme={"dark"}
openssl genrsa 2048 | openssl pkcs8 -topk8 -inform PEM -out rsa_key.p8 -nocrypt
```
</CodeGroup>
This creates `rsa_key.p8`, a PEM file that begins with `-----BEGIN PRIVATE KEY-----` (unencrypted) or `-----BEGIN ENCRYPTED PRIVATE KEY-----` (encrypted).
### 1.2 Generate the matching public key
```bash theme={"dark"}
openssl rsa -in rsa_key.p8 -pubout -out rsa_key.pub
```
This creates `rsa_key.pub`, which begins with `-----BEGIN PUBLIC KEY-----`.
<Tip>
Store `rsa_key.p8` securely and never commit it to version control. You'll paste its contents into Gumloop in Step 3.
</Tip>
***
## Step 2: Register the public key in Snowflake
Assign the **public** key to the Snowflake user Gumloop will connect as.
### 2.1 Assign the public key
In a Snowflake worksheet, run `ALTER USER` with the contents of `rsa_key.pub` — **excluding** the `-----BEGIN PUBLIC KEY-----` / `-----END PUBLIC KEY-----` header lines:
```sql theme={"dark"}
ALTER USER my_service_user SET RSA_PUBLIC_KEY='MIIBIjANBgkqh...rest of key body...';
```
<Info>
Assigning a public key requires the `SECURITYADMIN` role (or higher), or the `OWNERSHIP`/`ALTER` privilege on the user. If you don't have this, ask your Snowflake administrator to run the command for you.
</Info>
### 2.2 Verify the key was registered
```sql theme={"dark"}
DESC USER my_service_user;
```
Check that the `RSA_PUBLIC_KEY_FP` property (the key fingerprint) is populated.
***
## Step 3: Configure Gumloop
### 3.1 Add the Snowflake key-pair credential
1. Go to the [Connectors page (Snowflake Key-Pair)](https://www.gumloop.com/settings/profile/connectors?view=connected+key-pair) — this link pre-filters the list to Snowflake Key-Pair
2. Click **Add credential** on the **Snowflake Key-Pair** option
### 3.2 Fill in the credential fields
<Frame>
<img />
</Frame>
| Field | Required | What to enter |
| - | - | - |
| **Account Identifier** | Yes | The first part of your instance URL, e.g. `myorg-account123` from `https://myorg-account123.snowflakecomputing.com` |
| **Username** | Yes | The Snowflake user that has the matching RSA public key registered (from Step 2) |
| **Private Key** | Yes | The full contents of your `rsa_key.p8` file, in PEM (PKCS#8) format. Line breaks are optional when pasting. |
| **Private Key Passphrase** | Only if encrypted | The passphrase you set when generating an encrypted key. Leave blank for unencrypted keys. |
4. Click **Save**.
<Tip>
Paste the entire private key including the `-----BEGIN PRIVATE KEY-----` and `-----END PRIVATE KEY-----` lines. Gumloop normalizes the formatting automatically, so it's fine if line breaks are lost when copying.
</Tip>
<Note>
Only **one** Snowflake Key-Pair credential can be configured per account.
</Note>
***
## Step 4: Verify your connection
The quickest way to confirm the key-pair connection works is with an agent:
1. Create a new [agent](https://www.gumloop.com/agents)
2. In the agent's **Connectors** section, click **Add**, search for **Snowflake**, add it, and click **Save**
3. Ask it to run a simple query, for example:
```text theme={"dark"}
Run this query on Snowflake and show me the result: SELECT CURRENT_USER()
```
4. Confirm the agent returns your Snowflake username
Once verified, key-pair credentials work anywhere Snowflake authentication is used in Gumloop, including the [Snowflake MCP integration](https://www.gumloop.com/mcp/snowflake).
***
## PrivateLink and network policies
Snowflake network policies restrict which IP addresses can connect. If your account has network policies enabled, key-pair connections from Gumloop may be blocked unless Gumloop's [static egress IPs](/enterprise-features/static_egress_ips) are added to your allowed list.
* **Production:** Whitelist Gumloop's [static egress IPs](/enterprise-features/static_egress_ips) in your Snowflake network policy.
* **PrivateLink:** Not supported on the standard cloud-hosted deployment unless the static egress IPs are whitelisted — otherwise a [VPC deployment](mailto:support@gumloop.com) is required.
***
## Troubleshooting
<AccordionGroup>
<Accordion title="Could not parse the Snowflake private key" icon="triangle-exclamation">
* Make sure you pasted the **private** key (`rsa_key.p8`), not the public key (`rsa_key.pub`).
* The key must be in **PEM (PKCS#8)** format — it should start with `-----BEGIN PRIVATE KEY-----` or `-----BEGIN ENCRYPTED PRIVATE KEY-----`.
* If the key is encrypted, confirm the **Private Key Passphrase** field matches the passphrase you set during generation.
</Accordion>
<Accordion title="JWT token is invalid / public key mismatch" icon="key">
* The public key registered on the Snowflake user must be the pair of the private key you added to Gumloop. Re-run Step 2 with the `rsa_key.pub` that matches your `rsa_key.p8`.
* Verify the fingerprint is set with `DESC USER my_service_user;` and check `RSA_PUBLIC_KEY_FP`.
* Confirm the **Username** in Gumloop exactly matches the Snowflake user the key is registered on.
</Accordion>
<Accordion title="Connection refused or network policy error" icon="network-wired">
* Whitelist Gumloop's [static egress IPs](/enterprise-features/static_egress_ips) in your Snowflake network policy.
* PrivateLink accounts require the static egress IPs to be whitelisted, or a VPC deployment.
</Accordion>
<Accordion title="Queries fail with a warehouse error" icon="warehouse">
* Ensure your user's role has the `USAGE` privilege on the warehouse.
* Specify the warehouse explicitly in the Snowflake Reader step, or set a default warehouse for the user.
</Accordion>
</AccordionGroup>
***
## FAQs
<AccordionGroup>
<Accordion title="How is Key-Pair different from PAT and OAuth?">
All three authenticate Gumloop to Snowflake, but differ in mechanism:
* **OAuth** — browser-based login with short-lived, auto-refreshed tokens. Best for interactive/human users.
* **Key-Pair** — RSA JWT authentication using a private key. Best for service users and MFA-enforced accounts, since it isn't subject to an interactive MFA prompt.
* **PAT** — a Programmatic Access Token used like a password. Simple, but tied to token expiry and network-policy rules.
</Accordion>
<Accordion title="Does key-pair auth bypass MFA?">
Key-pair (JWT) authentication does not trigger an interactive MFA challenge, which is exactly why it's recommended for service users and accounts where MFA is enforced for interactive logins. Restrict the associated Snowflake user to least-privilege roles.
</Accordion>
<Accordion title="What key format does Gumloop require?">
An RSA private key in **PEM (PKCS#8)** format — the output of `openssl pkcs8 -topk8`. Both encrypted and unencrypted keys are supported. Line breaks are optional when pasting; Gumloop normalizes the formatting.
</Accordion>
<Accordion title="Do I need the passphrase field?">
Only if you generated an **encrypted** private key (without `-nocrypt`). For unencrypted keys, leave the passphrase blank.
</Accordion>
<Accordion title="Can I use more than one key-pair credential?">
No — only one Snowflake Key-Pair credential can be configured per account.
</Accordion>
<Accordion title="How do I rotate my key?">
Generate a new key pair, register the new public key on your Snowflake user with `ALTER USER ... SET RSA_PUBLIC_KEY`, then update the **Private Key** (and passphrase, if any) in your Gumloop credential. Snowflake also supports `RSA_PUBLIC_KEY_2` for zero-downtime rotation.
</Accordion>
</AccordionGroup>
***
## Security best practices
<CardGroup>
<Card title="Least privilege" icon="user-shield">
Connect as a Snowflake user with only the minimum roles and warehouse access your workflows need.
</Card>
<Card title="Encrypt the private key" icon="lock">
Prefer an encrypted key with a passphrase over an unencrypted one.
</Card>
<Card title="Rotate keys regularly" icon="arrows-rotate">
Periodically rotate the key pair, using `RSA_PUBLIC_KEY_2` for zero-downtime rotation.
</Card>
<Card title="Secure storage" icon="shield-check">
Never share the private key in plain text. Gumloop encrypts stored credentials.
</Card>
</CardGroup>
***
## Additional resources
* [Snowflake OAuth Configuration](/nodes/integrations/snowflake-oauth-config) — recommended for interactive users
* [Snowflake PAT Configuration](/nodes/integrations/snowflake-pat-config) — token-based alternative
* [Snowflake MCP integration](https://www.gumloop.com/mcp/snowflake)
* [Snowflake Key-Pair Authentication docs](https://docs.snowflake.com/en/user-guide/key-pair-auth)
* [How to find your account identifier](https://docs.snowflake.com/en/user-guide/admin-account-identifier)
* [Connectors](/core-concepts/credentials)
***
## Need help?
If you encounter issues not covered here:
1. Review the [Snowflake key-pair authentication documentation](https://docs.snowflake.com/en/user-guide/key-pair-auth)
2. Contact your Snowflake administrator for account-specific issues
3. Reach out to [Gumloop Support](mailto:support@gumloop.com) for integration assistance
# Snowflake OAuth configuration
Source: https://docs.gumloop.com/nodes/integrations/snowflake-oauth-config
This guide walks you through setting up Snowflake OAuth authentication for Gumloop. By following these steps, you'll configure a secure OAuth integration that allows Gumloop to connect to your Snowflake account on behalf of your users.
<Note>
**Intended Audience:** Snowflake administrators with ACCOUNTADMIN role or users with CREATE INTEGRATION privilege. This setup is performed once and enables OAuth authentication for your organization's Snowflake connection.
</Note>
<Tip>
**Alternative Authentication:** If setting up OAuth is not feasible for your organization, you can use [Snowflake Key-Pair (RSA JWT)](/nodes/integrations/snowflake-keypair-config) — best for service users and MFA-enforced accounts — or [Snowflake PAT (Programmatic Access Token)](/nodes/integrations/snowflake-pat-config). OAuth remains the recommended approach for interactive users thanks to enhanced security and automatic token refresh.
</Tip>
<Warning>
This guide provides basic setup instructions for integrating Snowflake with Gumloop. For production environments and security best practices, please refer to the [official Snowflake OAuth documentation](https://docs.snowflake.com/en/user-guide/oauth-custom) to ensure your configuration meets your organization's security requirements.
</Warning>
## What this guide covers
This documentation will help you:
1. **Create a Snowflake OAuth Integration** - Register Gumloop as a custom OAuth client in Snowflake
2. **Retrieve OAuth Credentials** - Get the Client ID and Client Secret needed for Gumloop
3. **Configure Gumloop (Administrator)** - Add the Snowflake OAuth Config to your organization
4. **User Authentication** - Connect individual user accounts with proper scopes
Once complete, your team will be able to authenticate Snowflake connections through OAuth in Gumloop.
## Overview
Snowflake OAuth integration enables secure authentication between Gumloop and your Snowflake account. Instead of sharing static credentials, OAuth allows users to authorize Gumloop to access Snowflake on their behalf with automatic token refresh and better security controls.
### Why use Snowflake OAuth with Gumloop?
<CardGroup>
<Card title="Enhanced security" icon="shield-halved">
OAuth tokens are temporary and can be revoked, reducing the risk of credential exposure
</Card>
<Card title="Automatic token refresh" icon="arrows-rotate">
Refresh tokens keep your connection active without manual re-authentication
</Card>
<Card title="Centralized control" icon="sliders">
Manage access and permissions directly in Snowflake
</Card>
<Card title="Audit trail" icon="list-check">
Track OAuth authentication events in Snowflake's audit logs
</Card>
</CardGroup>
***
## Prerequisites
Before you begin, ensure you have:
* **Snowflake Account Access** - You need the ACCOUNTADMIN role or a role with CREATE INTEGRATION privilege
* **Snowflake Account URL** - Your Snowflake account URL (e.g., `https://myorg-account123.snowflakecomputing.com`)
***
## Step 1: Create the Snowflake OAuth integration
You'll run SQL commands in Snowflake to create a custom OAuth integration for Gumloop.
### 1.1 Connect to Snowflake
1. Log in to your [Snowflake account](https://app.snowflake.com)
2. Open a new SQL worksheet
3. Ensure you're using a role with sufficient privileges:
```sql theme={"dark"}
USE ROLE ACCOUNTADMIN;
```
<Info>
If you don't have the ACCOUNTADMIN role, ask your Snowflake administrator to either grant you this role temporarily or execute these commands on your behalf.
</Info>
### 1.2 Create the OAuth integration
Copy and execute the following SQL command to create the OAuth integration:
```sql theme={"dark"}
CREATE OR REPLACE SECURITY INTEGRATION GUMLOOP
TYPE = OAUTH
ENABLED = TRUE
OAUTH_CLIENT = CUSTOM
OAUTH_CLIENT_TYPE = 'CONFIDENTIAL'
OAUTH_REDIRECT_URI = 'https://api.gumloop.com/auth/callback'
OAUTH_ISSUE_REFRESH_TOKENS = TRUE
OAUTH_REFRESH_TOKEN_VALIDITY = 7776000;
```
<Accordion title="Understanding the configuration parameters">
* **TYPE = OAUTH** - Specifies this is an OAuth integration
* **ENABLED = TRUE** - Activates the integration immediately
* **OAUTH\_CLIENT = CUSTOM** - Indicates this is a custom OAuth client (not a pre-built partner integration)
* **OAUTH\_CLIENT\_TYPE = 'CONFIDENTIAL'** - Marks this as a confidential client that can securely store secrets
* **OAUTH\_REDIRECT\_URI** - The Gumloop callback URL where users are redirected after authentication
* **OAUTH\_ISSUE\_REFRESH\_TOKENS = TRUE** - Enables automatic token refresh for persistent connections
* **OAUTH\_REFRESH\_TOKEN\_VALIDITY = 7776000** - Sets refresh token validity to 90 days (7,776,000 seconds)
</Accordion>
<Warning>
**Important:** Snowflake automatically adds certain administrative roles to the OAuth blocked roles list: **ACCOUNTADMIN**, **ORGADMIN**, **SECURITYADMIN**, and **GLOBALORGADMIN**. If you need to use these roles with OAuth, you must either:
* Remove them from the blocked roles list (if your organization's security policy allows), or
* Switch to a different role that is not blocked
For more information, see the [Blocking Specific Roles](#blocking-specific-roles) section below.
</Warning>
<Info>
For custom OAuth integrations (`OAUTH_CLIENT = CUSTOM`), scopes are not configured on the security integration itself. Instead, scopes are specified during the OAuth authorization request. Gumloop handles this automatically when users connect their accounts.
To control which roles can be used with this integration, use `BLOCKED_ROLES_LIST` to deny specific roles or `PRE_AUTHORIZED_ROLES_LIST` to skip the user consent step for specific roles. Refer to the [Snowflake OAuth documentation](https://docs.snowflake.com/en/user-guide/oauth-custom) for details.
</Info>
### 1.3 Verify the integration
Confirm the integration was created successfully:
```sql theme={"dark"}
SHOW SECURITY INTEGRATIONS LIKE 'GUMLOOP';
```
You should see `GUMLOOP` in the results.
### 1.4 View integration details
To see all configuration details:
```sql theme={"dark"}
DESC SECURITY INTEGRATION GUMLOOP;
```
This displays all properties of your OAuth integration, including the OAuth endpoints.
***
## Step 2: Retrieve OAuth credentials
Now you need to get the Client ID and Client Secret that Gumloop will use to authenticate.
### 2.1 Get client credentials
Execute the following command:
```sql theme={"dark"}
SELECT SYSTEM$SHOW_OAUTH_CLIENT_SECRETS('GUMLOOP');
```
This returns a JSON object containing your credentials. The output will look like:
```json theme={"dark"}
{
"OAUTH_CLIENT_ID": "ABC123XYZ456...",
"OAUTH_CLIENT_SECRET": "def789ghi012...",
"OAUTH_CLIENT_SECRET_2": ""
}
```
<Warning>
**Keep these credentials secure!** Treat the Client ID and Client Secret like passwords. Do not share them publicly or commit them to version control.
</Warning>
### 2.2 Save the credentials
Copy and save the following values from the JSON response:
* **OAUTH\_CLIENT\_ID** - You'll need this for Gumloop
* **OAUTH\_CLIENT\_SECRET** - You'll need this for Gumloop
<Tip>
Store these credentials in a secure password manager until you're ready to add them to Gumloop.
</Tip>
***
## Step 3: Configure Gumloop (administrator setup)
Now that you have your Snowflake OAuth credentials, you'll add them to Gumloop as an administrator.
### 3.1 Add Snowflake OAuth config to Gumloop
1. Navigate to [Settings → Organization → OAuth Configuration](https://www.gumloop.com/settings/organization/oauth-configuration)
2. Find **Snowflake OAuth Config** in the **Available** list
3. Click **Add**
<Frame>
<img alt="OAuth Configuration page with Snowflake OAuth Config highlighted in the Available list" />
</Frame>
4. Enter the following information:
* **Client ID**: The `OAUTH_CLIENT_ID` from Step 2.1
* **Client Secret**: The `OAUTH_CLIENT_SECRET` from Step 2.1
<Frame>
<img />
</Frame>
5. Save the configuration
This sets up the OAuth integration at the organization level. Individual users will now be able to connect using this configuration.
***
## Step 4: User authentication
Once the Gumloop administrator has completed Step 3, individual users can connect their Snowflake accounts.
### 4.1 Connect your Snowflake account
1. Navigate to [Connectors page](https://www.gumloop.com/settings/profile/connectors?view=connected)
2. Search for **Snowflake** and click **Add**
3. Choose the first Snowflake option as the authentication method
<Frame>
<img alt="Personal Connectors page with Snowflake in the search results and an Add button" />
</Frame>
4. Select **Snowflake OAuth Config** (the configuration added by your administrator or Okta if that is setup)
5. Enter the following information:
* **Workspace ID**: Your Snowflake account identifier (e.g., `myorg-account123`)
* **Scopes**: Space-separated list of OAuth scopes (see warning below)
### PrivateLink and Private Service Connect
<Warning>
**PrivateLink accounts are not supported with Gumloop's standard (cloud-hosted) deployment** unless you whitelist Gumloop's [static egress IPs](/enterprise-features/static_egress_ips) in your Snowflake network policy. The OAuth handshake requires Gumloop to reach your Snowflake account over the public internet. If your Snowflake account is behind AWS PrivateLink, Azure Private Link, or Google Cloud Private Service Connect and you are unable to whitelist Gumloop's IPs, connections will fail because Gumloop's servers cannot reach the private endpoint.
**The solution is a VPC deployment**, where Gumloop runs inside your network perimeter so the OAuth handshake stays private. Contact [support@gumloop.com](mailto:support@gumloop.com) to explore VPC deployment options for your organization.
</Warning>
If your Snowflake account uses PrivateLink **and** you have a Gumloop VPC deployment, include `.privatelink` in the Workspace ID. For example, if your Snowflake URL is `https://myorg-account123.privatelink.snowflakecomputing.com`, enter `myorg-account123.privatelink`.
Snowflake admins can find the private account URL by running `SYSTEM$GET_PRIVATELINK_CONFIG()` and checking the `regionless-privatelink-account-url` field (or `privatelink-account-url` for the region-specific locator format).
<Warning>
**Critical: Scopes Configuration**
If you leave scopes empty, most Snowflake operations will fail. You must specify the role(s) you want to use with this connection.
**Required format:**
```text theme={"dark"}
session:role:YOUR_ROLE_NAME
```
Replace `YOUR_ROLE_NAME` with your actual Snowflake role (e.g., `PUBLIC`, `ANALYST`, etc.). The role name is case-sensitive and must be in uppercase unless the role was created with quotes.
<Info>
**Note:** Gumloop automatically handles the `refresh_token` scope internally. You only need to specify the role scope(s).
</Info>
**Examples:**
* Basic access: `session:role:PUBLIC`
* Analyst role: `session:role:ANALYST`
* Custom role: `session:role:DATA_ENGINEER`
* Multiple roles: `session:role:ANALYST,session:role:DATA_ENGINEER`
For detailed scope configuration, refer to the [Snowflake OAuth scope documentation](https://docs.snowflake.com/en/user-guide/oauth-custom#label-oauth-scope).
</Warning>
### 4.2 Authorize the connection
After entering your information:
1. Click **Connect** or **Authorize**
2. You'll be redirected to Snowflake's authorization page
3. Log in with your Snowflake credentials
4. Review the requested permissions and role
5. Click **Authorize** to grant Gumloop access
6. You'll be redirected back to Gumloop with a successful connection
### 4.3 Verify your connection
To confirm your OAuth connection is working correctly:
1. Go to [Connectors page](https://www.gumloop.com/settings/profile/connectors?view=connected)
2. Search for **Snowflake**
3. If the connection is successful, you should see your **Snowflake username** displayed instead of "Snowflake Account"
<Frame>
<img alt="Snowflake OAuth verification showing username instead of account name" />
</Frame>
<Tip>
If you see your username listed (as shown in the image above), your OAuth connection is properly configured and ready to use!
</Tip>
***
## Blocking specific roles
Snowflake automatically blocks certain administrative roles from being used with OAuth for security reasons. These blocked roles include:
* **ACCOUNTADMIN**
* **ORGADMIN**
* **SECURITYADMIN**
* **GLOBALORGADMIN**
These roles are blocked by default and cannot be removed from the block list without contacting Snowflake Support and obtaining approval from your security team.
### Adding additional blocked roles
To block additional custom roles from being used with OAuth:
```sql theme={"dark"}
ALTER SECURITY INTEGRATION GUMLOOP
SET BLOCKED_ROLES_LIST = ('SYSADMIN', 'CUSTOM_ADMIN_ROLE');
```
<Info>
If users need to access Snowflake with OAuth using a role that's currently blocked, they have two options:
1. Request removal from the blocked roles list (requires Snowflake Support approval)
2. Switch to a different, non-blocked role that has the necessary permissions
</Info>
***
## Troubleshooting
### "Invalid Client" Error
**Problem:** Getting an "invalid\_client" error when connecting
**Solution:**
* Verify the Client ID and Client Secret are correct in the Snowflake OAuth Config
* Check that the integration is enabled: `DESC SECURITY INTEGRATION GUMLOOP;`
* Ensure the redirect URI matches exactly: `https://api.gumloop.com/auth/callback`
### Most operations are failing
**Problem:** Connected successfully but Snowflake operations return permission errors
**Solution:**
This usually means scopes are not configured correctly. Ensure you specified a valid role scope when connecting your Snowflake account.
Update your credential with a proper role scope, for example: `session:role:PUBLIC`
Gumloop automatically handles the `refresh_token` scope, so you only need to specify the role.
### Role access issues
**Problem:** Users can't access certain Snowflake resources or specific role
**Solution:**
* Verify the role name in your scope is spelled correctly and in uppercase
* Check if the desired role is blocked: `DESC SECURITY INTEGRATION GUMLOOP;`
* Ensure the user has been granted the role in Snowflake: `SHOW GRANTS TO USER your_username;`
* If using an administrative role (ACCOUNTADMIN, SECURITYADMIN, etc.), these are blocked by default
### Username not showing in Gumloop
**Problem:** Still seeing "Snowflake Account" instead of username in credentials page
**Solution:**
* The OAuth authorization may not have completed successfully
* Try removing the credential and re-connecting
* Verify scopes are configured correctly with a valid role (e.g., `session:role:PUBLIC`)
* Check Snowflake audit logs to confirm the OAuth authorization was successful
### Tokens expiring too quickly
**Problem:** Users need to re-authenticate frequently
**Solution:**
Increase the refresh token validity in Snowflake:
```sql theme={"dark"}
ALTER SECURITY INTEGRATION GUMLOOP
SET OAUTH_REFRESH_TOKEN_VALIDITY = 15552000; -- 180 days
```
***
## Security best practices
<CardGroup>
<Card title="Regular credential rotation" icon="key">
Periodically rotate your OAuth client secrets to maintain security
</Card>
<Card title="Principle of least privilege" icon="user-shield">
Grant users only the minimum Snowflake roles needed for their work
</Card>
<Card title="Monitor OAuth activity" icon="chart-line">
Regularly review OAuth token usage in Snowflake audit logs
</Card>
<Card title="Network policies" icon="network-wired">
Configure Snowflake network policies to restrict OAuth access by IP
</Card>
</CardGroup>
<Info>
For comprehensive security guidance and advanced configuration options, refer to the [official Snowflake OAuth documentation](https://docs.snowflake.com/en/user-guide/oauth-custom).
</Info>
***
## Additional resources
* [Snowflake OAuth Custom Clients Documentation](https://docs.snowflake.com/en/user-guide/oauth-custom)
* [Snowflake OAuth Error Codes](https://docs.snowflake.com/en/user-guide/oauth-error-codes)
* [Snowflake Network Policies](https://docs.snowflake.com/en/user-guide/network-policies)
* [Connectors](/core-concepts/credentials)
***
## Need help?
If you encounter issues not covered in this guide:
1. Check the [Snowflake OAuth documentation](https://docs.snowflake.com/en/user-guide/oauth-custom) for detailed technical information
2. Contact your Snowflake administrator for account-specific issues
3. [Reach out to us](https://portal.usepylon.com/gumloop/forms/help) for integration assistance
# Snowflake PAT configuration
Source: https://docs.gumloop.com/nodes/integrations/snowflake-pat-config
This guide walks you through setting up Snowflake PAT (Programmatic Access Token) authentication for Gumloop. PAT provides an alternative authentication method to OAuth, using username and password-based authentication.
<Note>
**When to Use PAT vs OAuth vs Key-Pair:** For most interactive users, we recommend [Snowflake OAuth](/nodes/integrations/snowflake-oauth-config). For service users or accounts with MFA enforced, use [Snowflake Key-Pair (RSA JWT)](/nodes/integrations/snowflake-keypair-config). PAT is an alternative for users who cannot set up OAuth integrations or need a simpler authentication approach.
</Note>
## What this guide covers
This documentation will help you:
1. **Understand when PAT is appropriate** - Learn when to use PAT vs OAuth
2. **Generate a Snowflake PAT** - Create a programmatic access token in Snowflake
3. **Configure Gumloop** - Add your PAT credentials to connect Gumloop to Snowflake
4. **Handle Network Policies** - Understand and configure network policy requirements
***
## OAuth vs PAT: Which should you use?
<CardGroup>
<Card title="Use OAuth (Recommended)" icon="shield-check">
* Enhanced security with temporary tokens
* Automatic token refresh
* Centralized access control
* Better audit trail
* [Set up OAuth →](/nodes/integrations/snowflake-oauth-config)
</Card>
<Card title="Use PAT when" icon="key">
* OAuth integration setup is not feasible
* You need a simpler authentication method
* Your organization restricts OAuth integrations
* You need quick access for testing
</Card>
</CardGroup>
<Warning>
**Important:** Snowflake OAuth and Snowflake PAT are **either/or** authentication methods. While you can technically have both configured, most users should choose one method.
</Warning>
***
## Prerequisites
Before you begin, ensure you have:
* **Snowflake Account Access** - A Snowflake user account with permissions to generate PATs
* **Account Identifier** - Your Snowflake account identifier (e.g., `myorg-account123`)
* **Network Policy Considerations** - Understanding of your organization's network policies (see [Network Policy Requirements](#network-policy-requirements) below)
* **Public Internet Access** - Your Snowflake account must be reachable over the public internet (see note below)
<Warning>
**PrivateLink accounts are not supported with Gumloop's standard (cloud-hosted) deployment** unless you whitelist Gumloop's [static egress IPs](/enterprise-features/static_egress_ips) in your Snowflake network policy. PAT authentication requires Gumloop to reach your Snowflake account over the public internet. If your Snowflake account is behind AWS PrivateLink, Azure Private Link, or Google Cloud Private Service Connect and you are unable to whitelist Gumloop's IPs, PAT connections will fail because Gumloop's servers cannot reach the private endpoint.
**The solution is a VPC deployment**, where Gumloop runs inside your network perimeter. Contact [support@gumloop.com](mailto:support@gumloop.com) to explore VPC deployment options for your organization.
</Warning>
***
## Step 1: Generate a Snowflake PAT
### 1.1 Access the PAT settings
1. Log in to your [Snowflake account](https://app.snowflake.com)
2. Click on your profile icon in the bottom-left corner
3. Select **My Profile**
4. Navigate to the **Authentication** section
5. Find **Programmatic access tokens**
### 1.2 Generate a new token
1. Click **Generate new token**
2. Enter a descriptive name for the token (e.g., "Gumloop")
3. Set an appropriate expiration date
4. Click **Generate**
<Frame>
<img />
</Frame>
<Warning>
**Save Your Token Immediately!** The token value is only shown once. Copy and store it securely before closing the dialog.
</Warning>
### 1.3 Token management options
After creating your token, you can manage it through the menu (three dots):
* **Edit** - Modify token settings
* **Rotate** - Generate a new token value while keeping the same configuration
* **Bypass requirement for network policy** - Temporarily bypass network restrictions (see below)
* **Delete** - Remove the token
***
## Step 2: Configure Gumloop
### 2.1 Add Snowflake PAT credentials
1. Navigate to [Connectors page](https://www.gumloop.com/settings/profile/connectors?view=connected)
2. Click **Add Credential**
3. Search for **"Snowflake PAT"** in the Snowflake PAT tab
<Frame>
<img />
</Frame>
4. Click **Add credential** on the Snowflake PAT option
5. Enter the following information:
* **Username**: Your Snowflake username
* **Password**: The PAT token you generated in Step 1
* **Account Identifier**: Your Snowflake account identifier (e.g., `myorg-account123`)
6. Click **Save** to store your credentials
### 2.2 Verify your connection
To confirm your PAT connection is working:
1. Add the Snowflake connector to an agent.
2. Ask the agent to run `SELECT CURRENT_USER()` and show the result.
3. Confirm the agent returns your Snowflake username.
***
## Network policy requirements
Snowflake network policies can restrict which IP addresses are allowed to connect. When using PAT authentication, you may encounter network policy restrictions that block connections from Gumloop's servers.
### Understanding network policies
Network policies in Snowflake control access based on IP addresses. If your organization has network policies configured, PAT connections from Gumloop may be blocked unless:
1. Gumloop's [static egress IPs](/enterprise-features/static_egress_ips) are whitelisted in your network policy, **OR**
2. You temporarily bypass the network policy requirement for your PAT
### Option 1: Whitelist Gumloop's IP range (recommended for production)
For production use, add Gumloop's [static egress IPs](/enterprise-features/static_egress_ips) to your Snowflake network policy's allowed list. This provides permanent access without requiring repeated bypasses.
### Option 2: Temporary network policy bypass (for testing)
For testing purposes, you can temporarily bypass the network policy requirement:
1. Go to your Snowflake profile → **Authentication** → **Programmatic access tokens**
2. Click the menu (three dots) next to your token
3. Select **Bypass requirement for network policy**
4. Set the bypass duration (maximum 24 hours)
<Warning>
**Temporary Bypass Limitations:**
* Maximum bypass duration is **24 hours**
* After the bypass expires, you'll need to either renew it or whitelist Gumloop's [static egress IPs](/enterprise-features/static_egress_ips)
* This option is intended for testing, not production use
</Warning>
### When network policy bypass is needed
You may need to bypass or whitelist if:
* Your Snowflake account has network policies restricting access to specific IP ranges
* You receive connection errors mentioning "network policy" or "IP not allowed"
* PAT authentication fails even with correct credentials
***
## Troubleshooting
### Connection refused or network policy error
**Problem:** Getting a network policy error when connecting
**Solution:**
* Use the temporary bypass option for testing (see [Option 2](#option-2-temporary-network-policy-bypass-for-testing) above)
* For production, whitelist Gumloop's [static egress IPs](/enterprise-features/static_egress_ips) in your Snowflake network policy
### Invalid credentials error
**Problem:** Authentication fails with invalid credentials
**Solution:**
* Verify your username is correct
* Ensure you're using the PAT token (not your regular password) in the Password field
* Check that the Account Identifier matches your Snowflake account URL
* Confirm the PAT hasn't expired
### Token expired
**Problem:** Previously working connection now fails
**Solution:**
* Check if your PAT has expired in Snowflake
* Generate a new token and update your Gumloop credentials
* Consider setting a longer expiration when creating new tokens
### Warehouse access issues
**Problem:** Connected but queries fail with warehouse errors
**Solution:**
* Ensure your user has USAGE privilege on the warehouse
* Specify the warehouse explicitly in the Snowflake Reader step
* Check if a default warehouse is configured for your user
***
## Security best practices
<CardGroup>
<Card title="Token expiration" icon="clock">
Set appropriate expiration dates for your PATs. Shorter durations are more secure but require more frequent rotation.
</Card>
<Card title="Least privilege" icon="user-shield">
Use a Snowflake user with only the minimum permissions needed for your workflows.
</Card>
<Card title="Regular rotation" icon="arrows-rotate">
Periodically rotate your PAT tokens to maintain security, even before they expire.
</Card>
<Card title="Secure storage" icon="lock">
Never share PAT tokens in plain text. Gumloop encrypts your credentials securely.
</Card>
</CardGroup>
***
## Additional resources
* [Snowflake OAuth Configuration](/nodes/integrations/snowflake-oauth-config) - Recommended authentication method
* [Snowflake Programmatic Access Tokens Documentation](https://docs.snowflake.com/en/user-guide/programmatic-access-tokens)
* [Snowflake Network Policies](https://docs.snowflake.com/en/user-guide/network-policies)
* [Connectors](/core-concepts/credentials)
***
## Need help?
If you encounter issues not covered in this guide:
1. Check the [Snowflake PAT documentation](https://docs.snowflake.com/en/user-guide/programmatic-access-tokens) for detailed technical information
2. Contact your Snowflake administrator for account-specific issues
3. Reach out to [Gumloop Support](support@gumloop.com) for integration assistance
# Custom MCP servers
Source: https://docs.gumloop.com/nodes/mcp/custom_mcp_servers
Connect your own MCP servers to Gumloop for extended AI capabilities.
Gumloop supports connecting to any [Model Context Protocol (MCP)](https://www.gumloop.com/blog/what-is-mcp-model-context-protocol-a-simple-guide) server. This lets you extend your agents with specialized tools, internal services, or any MCP-compatible API.
<Info>
Gumloop already has **50+ pre-built MCP servers** for popular services like GitHub, Slack, Notion, HubSpot, and more. These work out of the box with agents. [Browse available integrations](/nodes/mcp) before setting up a custom server.
</Info>
## Adding a custom MCP server
Setting up a custom MCP server takes just a few steps.
<Steps>
<Step title="Go to Connectors">
Navigate to **Settings > [Connectors](https://www.gumloop.com/settings/profile/connectors?view=connected%20server)**, click the arrow next to **Add Connector**, and choose **Add MCP Connector**.
<Frame>
<img alt="Add Connector dropdown with the Add MCP Connector option" />
</Frame>
</Step>
<Step title="Enter the server URL">
Pick a **Connection type** and enter your MCP server's URL, then click **Connect**.
| Connection type | When to use |
| - | - |
| **Public URL** | A publicly reachable MCP server. The URL must use HTTPS. |
| **Private (via tunnel)** | A server inside your network, routed through a [Managed Tunnel](/enterprise-features/managed_tunnels) (Enterprise). |
<Frame>
<img alt="Connect MCP Server dialog with connection type and server URL" />
</Frame>
</Step>
<Step title="Configure authentication">
Gumloop probes the server and shows the **Detected Auth** method. If the server supports OAuth, click **Authenticate** and sign in to connect your account. Otherwise, open the **Authentication** dropdown to supply a token, API key, or custom header instead.
<Frame>
<img alt="Configure dialog showing detected OAuth 2.0 authentication" />
</Frame>
</Step>
<Step title="Add it to your agent">
Go back to your agent, open the **Connectors** section, and click **Add Connector**. Search for the server you just added and select it to give the agent access to its tools.
<Frame>
<img alt="Connectors section of an agent with the Add Connector button" />
</Frame>
</Step>
</Steps>
<Tip>
**Team vs Personal credentials**: Credentials can be stored at the personal level (only you can use them) or team level (shared with your team). Choose the appropriate scope when setting up. [Learn more about credentials here](/core-concepts/credentials#personal-vs-team-connectors)
</Tip>
## Requirements
Custom MCP servers must meet these requirements:
| Requirement | Details |
| - | - |
| **Protocol** | HTTPS only (HTTP not supported) |
| **Accessibility** | Must be publicly accessible on the internet |
| **Transport** | Streamable HTTP or Server-Sent Events (SSE) |
| **Local servers** | Not supported (no STDIO or localhost connections) |
<Warning>
**Local MCP servers won't work.** Your server must be deployed to a publicly accessible URL. Services like [Cloudflare Tunnels](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/) or [ngrok](https://ngrok.com/) can expose local servers if needed.
</Warning>
<Tip>
**On Enterprise?** [Managed Tunnels](/enterprise-features/managed_tunnels) reaches MCP servers inside your network without opening inbound ports or running your own tunnel. Each becomes an organization-wide [Proxied MCP](/enterprise-features/proxied_mcps) rather than a personal credential.
</Tip>
### Authentication options
Gumloop supports multiple authentication methods:
* **Bearer tokens**: Standard OAuth/API key authentication. When you provide an **Access Token / API Key**, Gumloop sends it as an `Authorization: Bearer <token>` header with every request to your MCP server.
* **Custom headers**: For services requiring specific header formats. The **Additional Header** field accepts a single header in `Header-Name: value` format (e.g., `X-API-Key: my-secret-key`). This is useful for MCP servers that expect authentication in a non-standard header.
* **OAuth discovery**: Automatic OAuth flow discovery (RFC 8414) for compatible servers
## Using custom MCP servers with agents
Once configured, your custom MCP servers can be added to any agent. The agent can discover all available tools and use them naturally in conversation.
<Steps>
<Step title="Open Agent Configuration">
Go to your agent's settings and find the **Connectors** section.
</Step>
<Step title="Select MCP server">
Click **Add Connector** and search for your configured MCP server.
<Frame>
<img alt="Connectors section of an agent with the Add Connector button" />
</Frame>
</Step>
<Step title="Use your agent">
Your agent now has access to all tools from the MCP server. It will automatically discover and use them based on conversation context.
</Step>
</Steps>
**What agents give you:**
* **Conversational context**: The agent maintains conversation history and can use tools across multiple turns
* **Automatic tool selection**: The agent chooses the right tool based on your request
* **Multi-server support**: Connect multiple MCP servers and let the agent orchestrate between them
* **Available everywhere**: Use immediately in chat, Slack, or embedded pages
## Model-specific differences
Custom MCP servers work across all models in Gumloop, but how they run depends on the provider:
| Model | Provider | How MCP Tools Run |
| - | - | - |
| GPT-5.5 | OpenAI | Native MCP |
| GPT-5.4 | OpenAI | Native MCP |
| Claude 4.6 Sonnet | Anthropic | Native MCP |
| Claude 4.5 Sonnet | Anthropic | Native MCP |
| Gemini | Google | Backend connector (Gumloop executes tool calls) |
| Groq models | Groq | Backend connector (Gumloop executes tool calls) |
* **Native MCP**: The provider (OpenAI/Anthropic) connects directly to your MCP server and executes tools.
* **Backend connector (Gumloop executes tool calls)**: Gumloop connects to your server and presents tools as regular function calls; when invoked, Gumloop executes them and returns results to the model.
### Header handling by model
| Execution Method | Bearer Token | Additional Header |
| - | - | - |
| **OpenAI (Native MCP)** | Sent as `Authorization: Bearer <token>` | Sent as-is |
| **Anthropic (Native MCP)** | Sent as authorization token | Not forwarded |
| **Gemini/Groq (backend connector)** | Sent as `Authorization: Bearer <token>` | Sent as-is |
<Warning>
Anthropic models do not forward custom headers. If your MCP server relies on a custom header (e.g., `X-API-Key`), use the **Access Token / API Key** field with a Bearer token instead, or choose OpenAI, Gemini, or Groq.
</Warning>
## Security considerations
<AccordionGroup>
<Accordion title="Data sharing">
Information in your prompts may be sent to your MCP server. Be mindful of sensitive data and review your server's data handling policies.
</Accordion>
<Accordion title="Direct tool access">
All tools exposed by your MCP server are immediately available to the AI. There are no approval prompts before tool execution. Use appropriate authorization scopes to limit access.
</Accordion>
<Accordion title="Multi-server implications">
When using multiple MCP servers, consider that data retrieved from one server could be passed to another. Design your prompts accordingly.
</Accordion>
</AccordionGroup>
## Troubleshooting
| Issue | Solution |
| - | - |
| Cannot connect | Verify URL is HTTPS and publicly accessible |
| Authentication failed | Check token validity and expiration |
| Tools not appearing | Ensure the server implements MCP tool discovery |
| AI ignoring tools | Be more explicit in your prompt about which tools to use |
| Timeout errors | Server may be slow or unreachable. Check server status. |
<Tip>
**Test with discovery first.** Ask your agent to "list available tools" to verify the connection is working before relying on it.
</Tip>
## Further reading
* [What is MCP? A Simple Guide](https://www.gumloop.com/blog/what-is-mcp-model-context-protocol-a-simple-guide)
# No-auth connectors
Source: https://docs.gumloop.com/nodes/mcp/no_auth_connectors
Most connectors need you to link your own account before an agent can use them. The connectors below do not — add one to an agent and it works on the first run, either because the data is public or because Gumloop supplies a managed API key behind the scenes.
<Info>
Every connector on this page is available to agents out of the box. Everything else in the [MCP catalog](https://www.gumloop.com/mcp) requires a connected account on your [Connectors page](https://www.gumloop.com/settings/profile/connectors?view=connected).
</Info>
## Research and web data
| Connector | What it does | Bring your own key? |
| - | - | - |
| [Exa](https://www.gumloop.com/mcp/exa) | Neural web search, content extraction, and deep research with citations | Optional |
| [Parallel](https://www.gumloop.com/mcp/parallel) | Web search and content extraction for research tasks | Optional |
| [Firecrawl](https://www.gumloop.com/mcp/firecrawl) | Search, scrape, map, and crawl websites | Optional — interactive browser tools need your own key |
| [Apify](https://www.gumloop.com/mcp/apify) | Discover and run web scraping Actors | Optional — full-permission Actors, async runs, and dataset reads need your own key |
| [Reducto](https://www.gumloop.com/mcp/reducto) | Parse, extract, split, and edit documents | Optional |
## Sales and company data
| Connector | What it does | Bring your own key? |
| - | - | - |
| [Apollo](https://www.gumloop.com/mcp/apollo) | B2B people and company search, enrichment, and hiring signals | Optional |
| [Brandfetch](https://www.gumloop.com/mcp/brandfetch) | Logos, colors, fonts, and company details for any domain | Optional |
| [TasteLabs](https://www.gumloop.com/mcp/tastelabs) | Extract design systems from any website, search brands by aesthetic, and score brand adherence | Optional |
## Marketing, SEO, and ads
| Connector | What it does | Bring your own key? |
| - | - | - |
| [DataForSEO](https://www.gumloop.com/mcp/dataforseo) | Keyword research, competitor analysis, backlink audits, AI mention tracking | Optional — your own account runs on your API balance and costs no Gumloop credits |
| [Google PageSpeed](https://www.gumloop.com/mcp/gpagespeed) | Performance, accessibility, SEO, and Core Web Vitals audits | Optional |
| [Foreplay](https://www.gumloop.com/mcp/foreplay) | Ad and competitor creative research | Optional |
## Social and public content
| Connector | What it does | Bring your own key? |
| - | - | - |
| [YouTube](https://www.gumloop.com/mcp/youtube) | Search and analyze public YouTube content | Not accepted — public data only |
| [Instagram](https://www.gumloop.com/mcp/instagram) | Scrape public Instagram data | Not accepted — public data only |
| [TikTok](https://www.gumloop.com/mcp/tiktok) | Scrape public TikTok data | Not accepted — public data only |
| [Google Maps](https://www.gumloop.com/mcp/gmaps) | Find and enrich place and location data | Not accepted — public data only |
## Generation
| Connector | What it does | Bring your own key? |
| - | - | - |
| [Fal](https://www.gumloop.com/mcp/fal) | Run AI models for image, video, audio, speech, and 3D generation | Optional |
## How credits work
Tool calls on a Gumloop-managed key are billed in [credits](/core-concepts/credits) — each connector's page in the [MCP directory](https://www.gumloop.com/mcp) lists its tools and per-tool pricing. Connecting your own key for one of these services routes calls through your account instead, so you pay that vendor directly; DataForSEO additionally drops to zero Gumloop credits when you use your own account.
<Tip>
Connect your own key when you need higher rate limits, tools the managed key doesn't cover (Firecrawl's interactive browser tools, Apify's full-permission Actors), or billing on your own vendor account. Add it on your [Connectors page](https://www.gumloop.com/settings/profile/connectors?view=connected).
</Tip>
## Need help?
<CardGroup>
<Card title="Agents" icon="compass" href="/core-concepts/agents">
Add connectors to an agent
</Card>
<Card title="Connectors" icon="puzzle-piece" href="/core-concepts/credentials">
Connect your own accounts
</Card>
<Card title="Support" icon="life-ring" href="https://portal.usepylon.com/gumloop/forms/help">
Reach out to us
</Card>
</CardGroup>