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

# Agents Overview

> Build intelligent AI agents with visual flow builder, toolsets, and collections

<div className="max-w-2xl mx-auto mt-12">
  <div className="p-6 border border-gray-200 dark:border-gray-700 rounded-lg bg-purple-50 dark:bg-gray-800">
    <div className="flex items-center mb-4">
      <span className="text-4xl mr-3">🤖</span>
      <h2 className="text-2xl font-semibold m-0">PipesHub Agents</h2>
    </div>

    <p className="text-lg text-gray-700 dark:text-gray-300 mb-4">Create custom AI agents that can perform actions across your connected applications</p>

    <div className="flex items-center gap-2">
      <span className="px-3 py-1 bg-green-100 dark:bg-green-900 text-green-800 dark:text-green-200 rounded-full text-sm font-medium">
        Beta
      </span>

      <span className="px-3 py-1 bg-blue-100 dark:bg-blue-900 text-blue-800 dark:text-blue-200 rounded-full text-sm font-medium">
        Visual Builder
      </span>
    </div>
  </div>
</div>

## What are Agents?

Agents are customizable AI assistants that can interact with your connected applications, search collections, and perform actions on your behalf. Unlike the standard chatbot assistant, agents are purpose-built for specific workflows and can be configured with:

* **Reasoning Models** - Choose the AI model with reasoning capabilities that powers your agent
* **Toolsets** - Connect to external services like Slack, Jira, Confluence, and more
* **Knowledge sources** - Access indexed documents and collections
* **Custom system prompts** - Define the agent's personality and behavior

<Note>
  **When you want to use both Connector and Toolset:** In the Agent Builder add nodes from **Knowledge** (Collections, API Apps) for document search and context retrieval, and add nodes from **Tools** for performing actions. Connect both to your Agent Core so the agent can search context and take action in the same conversation.
</Note>

## Key Concepts

### Visual Flow Builder

Agents are built using a visual drag-and-drop flow builder powered by ReactFlow. You create agents by:

1. Adding an **Agent Core** node that defines the agent's basic configuration
2. Connecting **Reasoning Model** nodes (LLM with reasoning enabled) to power the agent's intelligence
3. Adding **Toolset** nodes to give the agent access to external applications
4. Connecting **Collection** nodes for indexed document search
5. Configuring edges to connect all components together

### Agent Core

The Agent Core is the central configuration for your agent:

| Field             | Description                                                     |
| ----------------- | --------------------------------------------------------------- |
| **Name**          | Display name for your agent                                     |
| **Description**   | Brief description of what the agent does                        |
| **Start Message** | Initial greeting when users start a conversation                |
| **Instruction**   | Detailed instructions for the agent's behavior and capabilities |
| **System Prompt** | Instructions that define the agent's behavior and personality   |

### Toolsets

Toolsets are collections of tools that allow agents to interact with external applications. Each toolset provides specific actions:

* **Jira Toolset** - Create issues, search tickets, add comments, etc.
* **Slack Toolset** - Send messages, search channels, manage conversations, etc.
* **Confluence Toolset** - Create/update pages, search content, etc.
* **Gmail Toolset** - Send emails, read messages, search, etc.
* **Calendar Toolset** - Create events, update events, check availability, etc.
* **Drive Toolset** - List files, manage folders, search documents, etc.

<Info>
  Toolsets must be configured and authenticated before they can be used in agents. See [Toolsets Overview](/toolsets/overview) for setup instructions.
</Info>

### Collections

Agents can access your indexed knowledge sources:

* **Connectors** - Data synced and indexed from connected applications for querying and search (Google Drive, SharePoint, etc.)
* **Collections** - Custom document collections you've uploaded

## Agent Capabilities

### What Agents Can Do

| Capability                  | Description                                              |
| --------------------------- | -------------------------------------------------------- |
| **Search Knowledge**        | Query indexed documents and return relevant information  |
| **Perform Actions**         | Create tickets, send messages, update pages via toolsets |
| **Multi-tool Workflows**    | Combine multiple toolsets in a single conversation       |
| **Context-Aware Responses** | Use system prompts to maintain consistent behavior       |

## Getting Started

1. **Configure Toolsets** - Set up the toolsets your agent will use ([Toolsets Overview](/toolsets/overview))
2. **Create an Agent** - Use the visual builder to create your agent ([Setup Guide](/agent-guide/setup-guide))
3. **Test and Iterate** - Chat with your agent and refine its configuration

***

## Frequently Asked Questions

<AccordionGroup>
  <Accordion title="What's the difference between Connectors and Toolsets?">
    | Aspect          | Connectors                          | Toolsets                         |
    | --------------- | ----------------------------------- | -------------------------------- |
    | **Purpose**     | Sync and index data for search      | Enable agents to perform actions |
    | **Data Flow**   | One-way (import data into PipesHub) | Two-way (read and write via API) |
    | **When to Use** | Query/search data                   | Perform actions on data          |

    **Example:** Use a **Gmail Connector** to index and search your email history. Use a **Gmail Toolset** to send new emails through an agent.
  </Accordion>

  <Accordion title="When should I use a Connector vs a Toolset?">
    **Connector** — Use when you need document context search: connectors sync and index your documents, emails, and pages so your assistant can find and use that context.

    **Toolset** — When you need **actions**: create or update content, send messages, or run analytical queries (e.g. JQL, CQL, reports).

    **Quick takeaway:** Search & context → **Connector**. Actions → **Toolset**.
  </Accordion>

  <Accordion title="Can I use one OAuth app for both Connector and Toolset?">
    Yes! You can create a single OAuth app in the service's developer console and use it for both:

    **What you need to add in your OAuth app:**

    1. **Both redirect URLs:**
       * Connector callback URL (e.g., `/connectors/oauth/callback/Gmail`)
       * Toolset callback URL (e.g., `/api/oauth/callback/Gmail`)

    2. **Both scope types:**
       * Read-only scopes for the Connector (to index data)
       * Read/write/delete scopes for the Toolset (to perform actions)

    **Benefits:**

    * Simpler setup - One OAuth app instead of two
    * Same Client ID and Client Secret for both configurations
    * Easier management in the service's developer console
  </Accordion>

  <Accordion title="How do I know which nodes to connect in Agent Builder?">
    Follow this pattern:

    1. **Agent Core** (required) - The center of your agent
    2. **Reasoning Model** (required) - Connect at least one AI model
    3. **Toolset nodes** (optional) - For actions like sending emails, creating tickets
    4. **Collection nodes** (optional) - For searching indexed data from Connectors

    All nodes must connect to the Agent Core. The agent will have access to all connected toolsets and collections.
  </Accordion>

  <Accordion title="Can I choose what knowledge source or tool the agent uses during chat?">
    Yes! While chatting with an agent, you can select:

    * **Specific Collections** - Query data from particular Connectors (e.g., search only Confluence or only Drive)
    * **Specific Toolsets** - Use particular tools (e.g., send via Gmail or create Jira ticket)
    * **Reasoning Model** - Choose which AI model to use for the query

    This gives you control at any time during the conversation to specify where the agent should search or which action to perform.
  </Accordion>

  <Accordion title="Can I connect multiple Reasoning Models to one agent?">
    Yes! You can connect multiple Reasoning Model nodes to the Agent Core.

    When chatting with the agent, users can select which model to use for specific queries from the chat interface. This allows:

    * Using different models for different complexity levels
    * Flexibility to choose the best model for each task
  </Accordion>
</AccordionGroup>

***

## Next Steps

<div className="grid grid-cols-1 md:grid-cols-2 gap-4 mt-6">
  <a href="/agent-guide/setup-guide" className="block p-4 border rounded-lg hover:bg-gray-50 dark:hover:bg-gray-800 transition-colors">
    <h3 className="text-lg font-semibold mb-2">Setup Guide</h3>
    <p className="text-gray-600 dark:text-gray-400">Step-by-step instructions for creating your first agent</p>
  </a>

  <a href="/toolsets/overview" className="block p-4 border rounded-lg hover:bg-gray-50 dark:hover:bg-gray-800 transition-colors">
    <h3 className="text-lg font-semibold mb-2">Toolsets Overview</h3>
    <p className="text-gray-600 dark:text-gray-400">Learn about available toolsets and how to configure them</p>
  </a>
</div>