# How To

This section provides comprehensive, step-by-step instructions for configuring and using tools from the Tools module.

# How to Use the Tool Directory

This guide explains how to browse and view details for the ready-made tools available in the Tools directory. This directory serves as a catalog of available capabilities and their required configurations.

Follow these steps to browse the Tool Directory:

1. Navigate to Purple Fabric → Tools to open the Tools interface. The Directory view is presented by default.
2. Browse available prebuilt tools on the Directory page
3. You can search for a specific tool or browse by category.
4. Click on any tool card to open a detailed view. In this view, you can review its features across three tabs:
   Details: This panel serves as the primary source of information for a tool, providing developers with a comprehensive guide to its purpose, prerequisites, and configuration.
   Operations: This panel lists all the available actions the tool can perform, along with a description of the actions.
   Accounts: This panel lists the pre-configured accounts that are available to be used for this tool's authentication.

# How to Build a Custom Function

Custom Functions allow you to define reusable, business-specific logic. Follow these steps to create, test, and publish a Custom Function.

Step 1: Navigate to Custom Functions

1. From the Purple Fabric interface, navigate to Tools.
2. Select the Custom Function tab from the left sidebar
3. Click + Custom Function to open the function builder
   

   

Step 2: Configure Function Metadata

In the configuration panel on the right side of the screen, provide the following metadata:

Step 3: Define Input Parameters

Input Parameters define the data your function will accept when executed.

1. In the Input Parameters section, click + Parameter.
2. For each parameter, provide: Parameter Name: A meaningful identifier (e.g., salary).
   Data Type: Select from available types such as Number, String, Boolean, or File.
   Description: (Optional) A brief explanation of the parameter's purpose.

Step 4: Define Output Parameters Output Parameters define the structure of the data your function will return after execution.

1. In the Output Parameters section, click + Parameter
2. For each output, provide:
   Parameter Name: A meaningful identifier (e.g., output, file).
   Data Type: Select from String, Number, File, Boolean, etc.
   Description: (Optional) A brief explanation of what this output contains.

Step 5: Add Access Providers (Optional)
If your function requires authentication to external services (e.g., Google, AWS, database connections), link an Access Provider.

1. In the Access Providers section, click + Access
2. Select a pre-configured credential from the dropdown (e.g., "Google Service", "AWS Service").
3. These credentials can be accessed in your code using context.get_access_details('credential_name').

Step 6: Write Your Custom Function Logic
In the code editor on the left side of the screen, write your business logic inside the main(inputs, context) function.
inputs: An object containing values from the Input Parameters you defined. Access them using inputs.parameter_name.
context: An object providing utilities for logging, file handling, and credential access.
return: A dictionary containing the output values. The keys in this dictionary must exactly match the Parameter Names you defined in the Output Parameters.
Available Python Libraries
Custom Functions support a curated set of Python libraries for data processing, cloud integration, and business logic implementation. These libraries are pre-installed and ready to use—simply import them using standard Python syntax at the beginning of your function code (e.g., import pandas as pd).
Supported Libraries
The following table lists all available Python packages:

Handling Outputs The function’s return statement is a Python dictionary. The keys in this dictionary must exactly match the Parameter Names you configured in the Output Parameters section.

• For simple data types (String, Number,Boolean): Assign the value directly.
• For File types:
  1. Generate your file's content in memory as bytes.
  2. Upload it using context.upload_file(file_name, content_bytes), which returns a file reference object or the address of the object.
  3. Assign this file reference object to the appropriate key in your return dictionary.

Step 7: Test Your Function

1. Click the Test button in the top-right corner of the screen.
2. In the test panel that appears, provide sample values for each required Input Parameter.
3. Click Run to execute your function.
4. Review the console output and verify that:
   • The function executes without errors.
   • The returned output matches your expected Output Parameters.
   • Log messages appear as expected.

Step 8: Submit and Publish

1. Once testing is complete and you're satisfied with the function's behavior, click Submit in the top-right corner.
2. The system will validate your code and configuration.
3. Upon successful validation, your Custom Function will be published and become available for use in:
   • Automated Workflows
   • Team of Agents

# How to Create a New API Tool

This section walks you through the process of creating a custom API tool using the Tools module. These tools can be used in Team Of Agents.

1. Select "API": After clicking Create Tool, choose the API option.
   

   

2. Enter Tool Details: Provide a Name and Description for your API tool.
   

   

3. Configure API Details:
   

   

   API URL: Enter the complete endpoint URL.
   HTTP Method: Select the appropriate HTTP method (e.g., GET, POST) from the dropdown.
   Configure request Headers tab:
   • Add header rows as needed:
     • Key: e.g., Authorization, key, Content-Type
     • Value: Enter the token or value (use the secure/locked field for secrets)
     • Description: Optional note

   Body tab

   • Body type:
     • None: No body is sent
     • JSON: Paste/compose the JSON payload
     • form-data: Add rows:
       • Key: field name
       • Type: Text/File
       • Value: enter text or choose a file field
       • Description: optional notes

   Parameters tab

   • Add URL query parameters:
     • Key: e.g., key, appid, q
     • Value: e.g., your_api_key or a sample token
     • Description: optional notes

4. Test: Click the Test button to validate your configuration and ensure the API call is successful.

5. Submit: Once satisfied with the test results, click Submit to create and save your API tool.

# How to Create and Manage an Account

Follow these steps to create a secure, reusable account for authenticating with external services.

• Step 1: Navigate to the Accounts Tab
  From the Purple Fabric main interface, navigate to Tools and select the Accounts tab. This will display a list of all existing accounts in your workspace.
  

  

• Step 2: Select a Service
  

  

  1. Click the + Account button in the top right corner. A Select Service dialog will appear.
  2. Choose the service you wish to connect to (e.g., IMAP Service, Amazon Web Service, Google Service).
• Step 3: Provide Basic Information
  

  

  1. In the creation form that appears, fill in the "Basic Information" section:
     • Credential Name: A unique and descriptive name for this account.
     • Description: A brief summary of the account's purpose.
     • Set Visibility: Choose between Private (visible only to you) or Public (visible to everyone in your workspace).
• Step 4: Provide Authentication Details
  1. In the "Authentication" section, enter the specific credentials required by the selected service. For an IMAP service, this would include:
     • Email Address
     • APP Password
     • IMAP Host
• Step 5: Submit and Verify
  1. Click Submit to save the new account. It will now appear in the list on the Accounts tab.
  2. You can search for existing accounts using the search bar and manage them via the Actions menu.

# Managing Connectivity and Reauthentication

Once an account is linked to a tool or agent, the platform actively monitors its connection status across the agents, workflows and the modules. Use the following features to ensure your tasks remains uninterrupted.

1. Automatic Token Refresh (Self-Healing)
For services using OAuth (such as Google, Gmail, etc.), the system includes a self-healing mechanism. It will automatically attempt to refresh access tokens in the background before they expire. This ensures that your agents can continue accessing external tools without requiring you to manually log in repeatedly.

2. Monitoring Connection Status
You can view the health of your tool connections directly within the Agent Configuration in Tools panel:

• Active (Toggle On): The credential is valid and the tool is ready for use
• Token Expired Alert: If a token cannot be refreshed automatically, an orange warning icon will appear next to the credential name
  

  

3. Reauthenticating Expired Credentials If a connection is interrupted due to an expired or revoked token, you can restore it directly from the tools section:

• Manual Fix: Click Token expired - Reauthenticate > is tool’s credential settings. This will launch the external service's login screen to securely grant new permissions.
  

  

• Unified Fix: If multiple tools use the same account, reauthenticating once will automatically fix the connection for all associated tools across your workspace.

4. Handling Locked Credentials To maintain security, reauthentication permissions are based on ownership:

• Owned Credentials: You can freely reauthenticate accounts you created.
• Shared/Admin Credentials: If a credential is marked "Owner action required," it has been locked by the original creator or an admin. In this case, you cannot initiate the reauthentication flow yourself and must contact the asset owner to refresh the connection.

5. Error Feedback in Testing When testing an agent in the Test and Debug panel, the system provides specific feedback if a tool fails due to authentication:

• Execution Interrupted: The agent will perform a "graceful halt" to prevent data errors.
• Detailed Trace: The debug sidebar will display a "Credentials Expired" card, identifying exactly which tool requires attention so you can resolve the issue without guessing which connection failed.

# How to Configure Tool Schemas in an Agent

This section explains how to view and understand the technical requirements of the tools you add to your agents. Detailed schemas allow you to see exactly what information a tool needs (Inputs) and what information it provides back (Outputs).

Step 1: Add a Tool to Your Agent

• Open an existing agent or create a new one from Purple Fabric → Agents
• In the tool directory, click Add next to the desired tool (e.g., Jira - Create). The tool will now appear in the Tools section of your agent configuration

Step 2: Access the Tool Schema

• Locate the tool in the Tools panel on the main configuration screen
• Click the Variables dropdown or hover over the tool name to trigger the schema overlay
• The schema window will appear, displaying two primary tabs: Input and Output

Step 3: Review Input Parameters
The Input tab defines what the agent must send to the tool.

• Required Fields (): Any parameter marked with an asterisk () is mandatory. The agent cannot execute the tool without this data
• Data Types: Each field specifies its expected format (e.g., string, object, boolean, array)
• Field Description: Read the inline description to understand the purpose of the field (e.g., assignee - the user ID the task is assigned to)

Step 4: Review Output Parameters Click the Output tab to see what data the tool returns after a successful run.

• Understanding the output schema is critical if you want the agent to use specific data points (like an issue_id or status) in its final response to a user
• This view shows the structure of the JSON object the agent will receive back from the tool

Step 5: Define Parameter Values
You can choose how these parameters are filled during an interaction:

• Manual Configuration: You can hard-code specific values directly in the UI if the parameter should always be the same
• Dynamic Prompting: If left blank, the LLM will use the user's query and the field descriptions in the schema to "fill in the blanks" dynamically during the conversation