# Plugin Tools Configuration

## 🔌 **What are Plugin Tools?**

Plugin tools enable your AI agent to execute individual workflow nodes as tools during conversations. Unlike workflow tools that run entire multi-step workflows, plugin tools give your agent access to specific node capabilities like:

* **LLM nodes**: Call other AI models for specialized tasks
* **API nodes**: Make HTTP requests to external services
* **Data transformation nodes**: Convert formats, extract structured data
* **Integration nodes**: Execute actions in connected services (Telegram, Google Sheets, etc.)
* **Utility nodes**: Perform calculations, string operations, and more

**Key Differences from Workflow Tools:**

* **Workflow Tools**: Execute complete multi-step workflows with complex logic
* **Plugin Tools**: Execute single workflow nodes for specific, atomic operations
* **Use Plugin Tools When**: You need fine-grained control over individual operations
* **Use Workflow Tools When**: You need to execute complex, multi-step processes

***

## ⚙️ **Plugin Tool Configuration**

Each plugin tool requires the following configuration:

### **Required Fields**

| Field              | Description                   | Example                              |
| ------------------ | ----------------------------- | ------------------------------------ |
| **Plugin ID**      | The workflow node type to use | `echo`, `llm`, `openai_ask_chat_gpt` |
| **Plugin Version** | Version of the node           | `1.0.0` (standard for all nodes)     |

### **Optional Fields**

| Field            | Description                                      | When to Use                                                                                                                                                                                          |
| ---------------- | ------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Connection**   | Connection ID for nodes requiring authentication | Some nodes require a connection to external services. Check the specific node's documentation in the [Node Library](https://docs.agenticflow.ai/reference/nodes) to see if a connection is required. |
| **Input Config** | Pre-configure specific input fields              | When you want to fix certain parameters and hide them from the agent                                                                                                                                 |

***

## 🔧 **Input Configuration (Advanced)**

The `input_config` feature allows you to pre-configure specific input fields for a plugin tool. This is useful when:

1. **You want to fix certain parameters**: Set a specific model, temperature, or other settings
2. **Simplify the agent's decision-making**: Remove fields the agent doesn't need to decide
3. **Enforce consistency**: Ensure certain values are always used
4. **Hide complexity**: Pre-configure technical details from the agent

### **How It Works**

When you configure an input field:

1. The field is **removed from the tool's schema** presented to the agent
2. The agent **cannot override** this value
3. The pre-configured value is **automatically merged** during execution
4. The field becomes **invisible** to the AI model

### **Configuration Format**

Each input field configuration consists of:

```json
{
  "field_name": {
    "value": "the_actual_value",
    "description": "Optional: why this value is set"
  }
}
```

### **Example 1: Pre-configure LLM Model**

Configure an LLM plugin with a fixed model and temperature:

```json
{
  "plugin_id": "llm",
  "plugin_version": "1.0.0",
  "input_config": {
    "model": {
      "value": "google-gemini-2.0-flash-lite",
      "description": "Fixed model for cost control"
    },
    "temperature": {
      "value": 0.7,
      "description": "Balanced creativity"
    }
  }
}
```

**Result**: The agent can use the LLM tool but only needs to provide the `prompt`. The model and temperature are automatically set to your configured values.

### **Example 2: Pre-configure Message Template**

Configure an echo plugin with a pre-configured greeting:

```json
{
  "plugin_id": "echo",
  "plugin_version": "1.0.0",
  "input_config": {
    "data": {
      "value": "Hello, World!",
      "description": "Pre-configured greeting message"
    }
  }
}
```

### **Example 3: Pre-configure ChatGPT with Fixed Prompt**

Configure OpenAI ChatGPT with a fixed system behavior:

```json
{
  "plugin_id": "openai_ask_chat_gpt",
  "plugin_version": "1.0.0",
  "connection": "openai_connection_id",
  "input_config": {
    "prompt": {
      "value": "Repeat the following value: {{user_input}}"
    },
    "model": {
      "value": "google-gemini-2.0-flash-lite"
    },
    "temperature": {
      "value": 0.7
    }
  }
}
```

**Note**: You can use template variables like `{{user_input}}` in pre-configured values if the node supports templating.

***

## 📋 **Common Plugin Tool Configurations**

### **1. Add LLM Plugin Tool**

Give your agent access to another AI model for specialized tasks:

**Configuration:**

```json
{
  "plugin_id": "llm",
  "plugin_version": "1.0.0",
  "input_config": {
    "model": {
      "value": "google-gemini-2.0-flash-lite"
    }
  }
}
```

**Use Cases:**

* Use a reasoning model for complex logic
* Use a vision model for image analysis
* Use a fast model for simple tasks

***

### **2. Add API Call Plugin Tool**

Allow your agent to make HTTP requests:

**Configuration:**

```json
{
  "plugin_id": "api_call",
  "plugin_version": "1.0.0"
}
```

**Use Cases:**

* Fetch data from external APIs
* Send data to third-party services
* Integrate with custom backends

***

### **3. Add String to JSON Plugin Tool**

Parse JSON strings into structured data:

**Configuration:**

```json
{
  "plugin_id": "string_to_json",
  "plugin_version": "1.0.0"
}
```

**Use Cases:**

* Parse API responses
* Convert string data to structured format
* Handle JSON in conversations

***

### **4. Add Telegram Send Message Plugin**

Send Telegram messages:

**Configuration:**

```json
{
  "plugin_id": "telegram_send_message",
  "plugin_version": "1.0.0",
  "connection": "telegram_connection_id"
}
```

**Use Cases:**

* Send notifications to Telegram
* Alert users via Telegram
* Automated messaging

***

### **5. Add OpenAI ChatGPT Plugin**

Use OpenAI's ChatGPT as a specialized tool:

**Configuration:**

```json
{
  "plugin_id": "openai_ask_chat_gpt",
  "plugin_version": "1.0.0",
  "connection": "openai_connection_id",
  "input_config": {
    "model": {
      "value": "gpt-4o"
    },
    "temperature": {
      "value": 0.7
    }
  }
}
```

**Use Cases:**

* Use GPT-4o for specific reasoning tasks
* Delegate complex analysis to a specialized model
* Use vision capabilities for image understanding

***

## 🔍 **Available Plugins**

You can configure **any of the 193+ workflow nodes** as a plugin tool for your agent. Each node becomes available as a tool that your agent can execute during conversations.

### **Browse Available Nodes**

To find the right plugin for your use case:

1. [**Node Library**](https://docs.agenticflow.ai/reference/nodes) - Complete reference of all 193+ workflow nodes organized by category
2. [**Nodes by Category**](https://github.com/PixelML/agenticflow-docs/blob/main/docs/11-reference/nodes/by-category/README.md) - Browse nodes by functionality (AI & LLM, Utilities, Integrations, etc.)

### **What You'll Find in Node Documentation**

Each node's documentation page includes:

* **Description**: What the node does and its capabilities
* **Input Parameters**: Required and optional fields you can configure
* **Connection Requirements**: Whether the node needs a connection to external services
* **Output Schema**: What data the node returns
* **Examples**: Usage examples and common configurations

### **Finding the Plugin ID**

The **Plugin ID** is the node's technical name shown in the node documentation. For example:

* `echo` - Echo node
* `llm` - LLM node
* `openai_ask_chat_gpt` - OpenAI ChatGPT node
* `telegram_send_message` - Telegram Send Message node
* `api_call` - API Call node

**Tip**: Use the search function in the Node Library to quickly find nodes by keyword or functionality.

***

## ⚠️ **Important Considerations**

### **Connection Requirements**

Some plugins require a **connection** to external services. To check if a specific node requires a connection:

1. **Check Node Documentation**: Navigate to the [Node Library](https://docs.agenticflow.ai/reference/nodes) and find the specific node
2. **Review Requirements**: The node documentation will specify if a connection is required
3. **Configure Connection**: If required:
   * Navigate to: Project Settings → Connections
   * Add Connection: For the required service (OpenAI, Telegram, etc.)
   * Get Connection ID: Copy the connection ID from the connection settings
   * Configure Plugin: Set the `connection` field to the connection ID

**Note**: Each node's documentation page in the Node Library specifies its connection requirements. Always refer to the specific node documentation for accurate connection information.

### **Cost Considerations**

Plugin tools consume credits when executed:

* **LLM plugins**: Cost varies by model (see [Model Selection](https://docs.agenticflow.ai/ai-agents/model-selection))
* **API plugins**: May incur external API costs
* **Media plugins**: Generation/processing costs apply

**Best Practice**: Use `input_config` to set cost-effective models for budget control.

### **Security Best Practices**

1. **Pre-configure sensitive parameters** using `input_config`:
   * API endpoints that should remain fixed
   * Rate limits
   * Safety parameters
   * Model selection for consistent behavior
2. **Use connections securely**:
   * Store API keys and credentials in connection settings
   * Never expose credentials in input\_config values
   * Reference connections by ID only
3. **Monitor plugin usage**:
   * Review conversation logs regularly
   * Track which plugins are being executed
   * Monitor credit consumption
   * Check for unexpected behavior

***

## 💡 **Best Practices**

### **1. Start Simple**

Begin with basic utility plugins like `echo` or `string_to_json` to understand the behavior before adding complex integrations.

### **2. Use Input Config Strategically**

Pre-configure fields that should remain constant:

* Model selection for consistent behavior
* Temperature for predictable outputs
* API endpoints that shouldn't change

### **3. Combine with System Prompt**

Guide your agent on when to use specific plugins:

```
System Prompt Example:
"You have access to the following tools:
- Use the 'llm' plugin for complex reasoning tasks
- Use the 'api_call' plugin to fetch external data
- Use the 'string_to_json' plugin when parsing JSON responses

Always explain which tool you're using and why."
```

### **4. Check Node Documentation**

Before configuring a plugin:

* Review the node's documentation in the [Node Library](https://docs.agenticflow.ai/reference/nodes)
* Check connection requirements
* Understand required vs. optional input fields
* Review examples and use cases

### **5. Monitor Plugin Usage**

Review conversation logs to see:

* Which plugins are being used
* How often they're executed
* Success/failure rates
* Credit consumption

### **6. Layer Multiple Plugins**

Create specialized workflows by combining plugins:

* Fetch data with `api_call`
* Parse with `string_to_json`
* Analyze with `llm`
* Notify with `telegram_send_message`

***

## 🔄 **Updating Plugin Configuration**

You can modify plugin tool configuration at any time:

### **Add New Plugins**

Simply add new plugin configurations to the `plugins` array.

### **Modify Existing Plugins**

Update the configuration fields:

* Update `input_config` values
* Change connection IDs
* Modify plugin version if needed

### **Remove Plugins**

Remove plugin configurations from the `plugins` array to disable them.

**Note**: Changes take effect immediately for new conversations. Existing conversations may need to be refreshed.

***

## 📖 **Related Documentation**

* [**Workflow Tools Configuration**](https://docs.agenticflow.ai/ai-agents/workflows) - Configure complete workflows as tools
* [**MCP Tools Configuration**](https://docs.agenticflow.ai/ai-agents/mcp-tools) - Configure MCP protocol integrations
* [**Node Library**](https://docs.agenticflow.ai/reference/nodes) - Complete reference of all 193+ nodes
* [**System Prompt Configuration**](https://docs.agenticflow.ai/ai-agents/system-prompt) - Guide your agent's tool usage
* [**Model Selection**](https://docs.agenticflow.ai/ai-agents/model-selection) - Choose the right AI model for your agent

***

## 🆘 **Troubleshooting**

### **Plugin Tool Not Appearing**

**Possible Causes:**

1. Invalid `plugin_id` - Verify the node type exists
2. Missing connection for nodes that require it
3. Configuration validation errors

**Solution**: Check the browser console for validation errors.

### **Plugin Execution Fails**

**Possible Causes:**

1. Missing required input fields
2. Invalid connection credentials
3. Node-specific errors (rate limits, API failures)

**Solution**: Review the execution logs and verify all required inputs are provided or pre-configured.

### **Agent Not Using Plugin**

**Possible Causes:**

1. System prompt doesn't guide plugin usage
2. Plugin not relevant to conversation context
3. Agent chose alternative approach

**Solution**: Update system prompt with clear guidance on when to use specific plugins.

### **Input Config Not Working**

**Possible Causes:**

1. Field name doesn't match node schema
2. Invalid value type for the field
3. Field is required but not configured

**Solution**: Verify field names match the node's input schema exactly.

***

**For detailed node-specific configuration, see:** [Node Library Reference](https://docs.agenticflow.ai/reference/nodes)