# Agents Agents are AI assistants specialized for specific tasks and domains. --- ## What Are Agents? An agent is an AI assistant with defined instructions, model configuration, optional integration access, optional skills, and optional knowledge bases. Each agent is tuned for a particular domain — from writing code to managing CRM data to analyzing revenue. The default **Insulin** agent acts as your chief of staff: a general-purpose assistant that can help with a wide range of marketplace operations. It is built in and cannot be edited or deleted, unlike the catalog and custom agents you install or create. ![An installed agent (Code Reviewer) — its welcome message and conversation starters shown in a fresh conversation; the sidebar lists your installed agents with ownership badges (system / org / user)](images/08-insulin-agents.png) ## Agent Catalog Insulin includes a catalog of pre-built agents organized by category. Install a catalog agent from [Marketplace](./7.marketplace.md) to add it to your workspace. ### Development | Agent | Description | |-------|-------------| | **API Designer** | Design and review API schemas and contracts | | **Code Reviewer** | Review code for quality, security, and best practices | | **Debug Detective** | Diagnose and troubleshoot bugs and errors | | **DevOps Assistant** | Help with CI/CD pipelines, infrastructure, and deployments | | **GitHub Engineer** | Work with GitHub repositories, pull requests, issues, and code reviews | ### Productivity | Agent | Description | |-------|-------------| | **ClickUp Project Manager** | Manage ClickUp tasks, projects, and workflows | | **Gmail Assistant** | Read, draft, and manage Gmail messages | | **Google Calendar Assistant** | Manage Google Calendar events and scheduling | | **Google Drive Assistant** | Search, organize, and manage Google Drive files | | **Outlook Assistant** | Read, draft, and manage Outlook email and calendar | | **Teams Coordinator** | Coordinate across Microsoft Teams channels and conversations | | **Technical Writer** | Draft and improve technical documentation | ### Data | Agent | Description | |-------|-------------| | **BigQuery Analyst** | Query and analyze data in Google BigQuery | | **GCS Curator** | Manage files and data in Google Cloud Storage | ### Analytics | Agent | Description | |-------|-------------| | **Data Analyst** | Analyze datasets, generate insights, and create visualizations | ### Sales | Agent | Description | |-------|-------------| | **Gong Sales Coach** | Review sales calls and get coaching recommendations | | **HubSpot CRM Assistant** | Manage contacts, deals, and pipelines in HubSpot | | **Salesforce CRM Assistant** | Manage leads, opportunities, and accounts in Salesforce | ### Business | Agent | Description | |-------|-------------| | **Product Strategist** | Help with product planning, prioritization, and roadmap decisions | ### Security | Agent | Description | |-------|-------------| | **Security Auditor** | Identify security vulnerabilities and recommend fixes | ## Selecting an Agent To start a conversation with a specific agent: 1. Click **New Conversation** or click the agent name at the top of the current chat 2. Browse or search your installed and shared agent list 3. Select the agent to start the conversation You can switch agents mid-conversation if needed. ## Creating a Custom Agent Build your own agent tailored to your team's needs: 1. Navigate to the **Agents** section in the sidebar 2. Click **Create Agent** 3. Configure the following: | Field | Description | |-------|-------------| | **Icon** | An avatar image that identifies the agent in lists and chat | | **Name** | A descriptive name for the agent | | **Ownership** | Choose **Personal (only you)** or **Organization (shareable)**. The Organization option is disabled for members who are not org admins | | **Default model** | The model the agent uses by default, chosen from the models your connected LLM providers make available (see below) | | **Knowledge bases** | Optional knowledge bases the agent can search, each attached in **Read** or **Edit** mode (see [Integrations and Knowledge Bases](#integrations-and-knowledge-bases)) | | **Integrations** | Optional allowlist of connected systems the agent can use | | **System prompt** | Instructions that define the agent's behavior, personality, and constraints | The **Default model** dropdown is populated from the LLM providers your workspace has connected — bring-your-own-key (BYOK) providers such as Anthropic, OpenAI, DeepSeek, Kimi, MiniMax, Qwen, and Antigravity. You can also connect **open-source model aggregators** — [OpenRouter](../../integrations/openrouter/), [Baseten](../../integrations/baseten/), [DeepInfra](../../integrations/deepinfra-byok/), [Fireworks AI](../../integrations/fireworks/), and [Together AI](../../integrations/together/) — each of which serves a large catalog of models. Because an aggregator can expose hundreds of models, the Default model picker is **searchable and grouped by provider**, with **verified** models listed first. The **Ownership** you choose controls whether Suger's hosted models are offered too: an **Organization** agent can use the Suger-hosted default, but a **Personal (only you)** agent must pick one of your own connected BYOK providers — the Suger-hosted models are not listed for it. If you switch an agent's Ownership to Personal, a saved default that is no longer available is cleared, and a Personal agent can't be saved with a Suger-hosted default until you choose a BYOK model. If a saved default later becomes **unavailable** — its provider was disconnected or the model was retired — the picker marks it **" — unavailable"** with a hint to reconnect the provider or choose another model; the agent never silently switches to a different model. :::info You do not type a description. When you save, Insulin auto-generates the agent's description by summarizing its system prompt — so an empty system prompt yields an empty description. Write a clear, complete prompt and the description follows. ::: :::tip Write system prompts that are specific and actionable. Instead of "Be helpful," try "You are a marketplace operations assistant. Help users create and manage private offers across AWS, Azure, and GCP. Always confirm pricing details before finalizing." ::: ### User-Level vs Org-Level Agents When creating an agent, you choose the ownership level: - **User-level** — Private to you. Any user can create user-level agents. - **Org-level** — Belongs to the organization. **Only org admins** can create org-level agents. :::warning Org-level agents can only use **org-level integrations** (MCP servers, API keys, etc.). They cannot access user-level integrations. Make sure the integrations your agent needs are configured at the organization level before creating an org-level agent. ::: ## Integrations and Knowledge Bases Agents do not automatically receive every connection your organization has configured. Their runtime access depends on the agent's ownership level: | Agent type | Integration access | |------------|--------------------| | **User-level** | Uses user-level integrations selected for that agent. | | **Org-level** | Uses organization-level integrations selected for that agent. | | **System** | Uses allowed user-scope integrations for the current user. | Custom agents can also attach knowledge bases. A custom agent searches the knowledge bases configured on it, while the built-in Insulin assistant searches the ones you own by default and lets you narrow that to an explicit set — including organization knowledge bases shared with you — from its own panel. See [Knowledge Bases](./4.knowledge-base.md) to create one and fill it with files, websites, or synced connectors, and [Choosing which knowledge bases Insulin uses](./4.knowledge-base.md#choosing-which-knowledge-bases-insulin-uses) for the Insulin selection. Each attached knowledge base has an **access mode**: | Mode | What the agent can do | |------|-----------------------| | **Read** | Retrieve and search the knowledge base for grounded context only | | **Edit** | Retrieve, plus create, update, and deprecate files in the knowledge base (never delete) | :::info For organization-level agents, editing integrations requires organization administrator access. This prevents a shared agent from being quietly granted new organization-level tool access by someone without admin privileges. ::: ### Asking an agent about its own integrations An agent can inspect the connections it has been given, so you can ask about them in plain language instead of opening Settings and guessing. There is no control to switch on — every agent has these abilities automatically: - **List its integrations** — which connected systems it can reach, whether each one is user- or organization-level, and when it was connected. - **Get the details of one integration** — the same record for a single connection, read from what the agent already has loaded rather than by calling the provider. - **Check whether an integration is working** — a live probe that refreshes an expired OAuth sign-in if it can, then reports the connection healthy or unhealthy along with the reason it failed. - **List the actions an integration supports** — the provider actions it exposes, each with a description and whether it is read-only, plus non-secret connection details such as an account id or base URL. Credentials are never returned. Because "is it attached?" and "does it still work?" are answered separately, an agent now tells **not connected** apart from **connected but failing**. Ask *"why can't you update Salesforce?"* and it can distinguish an integration that was never added to its allowlist from one that is on the allowlist but whose credential has stopped working — instead of reporting a live-but-erroring connection as disconnected and sending you to reconnect something that is already connected. ## Sharing Agents Only **Organization** agents can be shared. Personal (user-level) agents are private to you, and their **Share** button is disabled. Share an Organization agent with specific teammates using role-based access control. Each shared user is assigned one of the following roles (see [Roles and Permissions](./1.getting-started.md#roles-and-permissions) for the full model): | Role | Permissions | |------|-------------| | **ADMIN** | Edit agent configuration and manage sharing (invite/revoke members, assign roles) | | **EDITOR** | Edit the agent's configuration (system prompt, default model, knowledge bases, and — for org admins — the integration allowlist) | | **USER** | Use the agent in conversations | To share an agent: 1. Open the agent's settings 2. Click **Share** 3. Add team members and assign roles :::info Managing shares (inviting or revoking members, assigning roles, transferring ownership) requires the **ADMIN** role on the agent itself — the owner, or a teammate explicitly granted ADMIN — not merely being an org admin. ::: When a teammate opens an agent shared with them, its settings show an owner-and-role banner, and anyone below **Editor** (a **USER**/Member) sees the configuration **read-only**. See [Working with a Shared Resource](./1.getting-started.md#working-with-a-shared-resource). ### Org-Wide Sharing Instead of inviting people one at a time, you can share an Organization agent with your **entire organization**. Org-wide sharing grants either **EDITOR** or **USER** (never ADMIN); everyone in the organization then gets that role automatically without an individual invite. ![The Share Agent dialog on an organization agent — the Owner row with Transfer ownership beside it, the Org-wide Share toggle, and the "Share with a user" picker with its role selector open on ADMIN, EDITOR and USER](images/28-agent-share.png) ## Transferring Ownership If you need to hand off an agent to another team member, you can transfer ownership from the agent's settings. The new owner receives full ownership and control of the agent. ## Agents in Channels and Jobs Agents can be reused across Insulin: - Add agents to [Channels](./5.channels.md) when multiple people and agents need to collaborate in a shared thread. - Assign agents to [Jobs](./6.jobs.md) when work should run manually, on a schedule, or from an event. - Use agents with [Custom Apps](./8.custom-apps.md) when a workflow needs both an AI builder and an interactive UI.