> ## Documentation Index
> Fetch the complete documentation index at: https://koreai-ai-for-process-dev.mintlify.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Workflow Tools

Build tools visually with a no-code drag-and-drop interface.

***

## Overview

Workflow tools enable process automation through a visual flow builder. They let you automate multi-step processes, combine AI features with deterministic business logic, integrate with external systems (APIs, cloud services), generate structured outputs (emails, summaries, data responses), and reuse tools across multiple Agentic Apps—no complex coding required.

Every flow consists of a Start node that receives data and an End node that returns results. Other systems access these results through a deployable API endpoint.

<div class="ascii-art">
  ┌─────────┐    ┌──────────┐    ┌─────────────┐    ┌─────────┐
  │  Start  │───▶│ Validate │───▶│  Call API   │───▶│   End   │
  └─────────┘    └──────────┘    └─────────────┘    └─────────┘
</div>

***

### When to Use

Workflow tools are ideal when:

* Business logic is **well-defined and consistent**
* You need **visual traceability** for debugging
* Non-developers need to build or maintain tools
* Processes involve **multiple sequential steps**
* You want **built-in monitoring** and audit logs

### Good Fit Examples

| Use Case             | Why Workflow Works                           |
| -------------------- | -------------------------------------------- |
| Order status lookup  | Clear input → API call → formatted output    |
| Weather retrieval    | Simple API integration with response mapping |
| Database queries     | Structured data fetch with transformation    |
| Notification sending | Multi-channel delivery with conditions       |

***

## Tool Creation and Scope

Workflow Tools can be created in two scopes, depending on whether they are intended for reuse or for app-specific behavior.

### App-Scoped Tools

Created within a specific **Agentic App**, or imported from the library into an app. Any modifications apply only to the local copy and do not affect the library version. Changes take effect only after the tool is deployed within the app.

* Isolated to that app.
* Changes do not affect library versions.
* Best for app-specific logic or experimentation.

App-scoped tools are not shared across other apps.

### Library Tools

Created in the **Tools** module of the platform, independent of any app. Once deployed, library tools are accessible across multiple apps and act as templates—when imported into an app, they generate a local copy that can be customized without altering the original.

* Reusable across multiple apps.
* Importing is restricted to deployed tools from the library.
* Changes to the library version do not affect local copies in apps.

These tools exist independently of any Agentic App and, once built and deployed, function as a shared tools library serving as templates for Agentic Apps.

## Managing App-Scoped Workflow Tools

App-scoped workflow tools are created and managed inside an Agentic App. These tools are available only to the app in which they are created or imported, and they do not appear in the Tools Library. App-scoped tools can use app-level features such as namespaces, environment variables, and PII protection.

The **Tools** page provides a structured view of all tools in an app, with clear visibility into their types, statuses, and linked agents.

### Create an App-Scoped Workflow Tool

To create a workflow tool:

1. Open the **Agentic App** > **Tools.**
2. Select **+ New Tool** and create a new workflow tool.
3. The **Tools** page opens, where you can configure the tool’s metadata and settings, and open the flow canvas to design the workflow.
4. The tool becomes available for use only to the app and is not available in the Tool Library.

*App-scoped tools support the same flow builder features as tools created in the Tools module.*

### Edit an App-Scoped Workflow Tool

After creating the tool, it appears on the app’s **Tools** landing page, where you can edit tool metadata, manage namespaces, and delete the tool.

| **Field**                              | **Description**                                                                                                                      |
| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| **Tool Name**                          | A unique identifier for the tool within the app.                                                                                     |
| **Description**                        | Optional summary of the tool’s purpose.                                                                                              |
| **Input Parameters**                   | Defines the parameters the agent must collect before running the tool. Each parameter includes a name and type.                      |
| **Output Parameters**                  | Defines the values returned when the workflow completes.                                                                             |
| **Include Tool Response in Artifacts** | Adds the tool response to the `artifacts` field in the Execute API response. Affects only the API structure, not execution behavior. |
| **Namespace**                          | Associates the tool with an app namespace to enable access to application-level environment variables.                               |

<Note>App-scoped workflow tools remain isolated to the app they belong to. Changes do not affect the original library tool or other applications.</Note>

### Import an Existing Tool Into an App

You can import a reusable workflow tool from the Tools Library into an Agentic App.

To import an existing tool from the library, the tool must be deployed. When a deployed tool is imported into an Agentic App:

* A local copy of the tool is created inside the app.
* The local copy can be customized or extended, as required.
* Changes made in the app do not affect the original library tool.

To import a tool:

1. In the app, open **Tools**.
2. Select **Import Tool** > **From Library**.

Importing a library tool creates a **local app-scoped copy**.

### Tool Access Control

Permissions for workflow tools are separate from Agentic App permissions.

* Users can view workflow tools associated with an app on the **App → Tools** page.
* To open, edit, or manage a tool, users must be granted tool-level permissions.
* Only the tool owner can assign these permissions.

For more information, see [Roles and Permissions](/agent-platform/administration/role-management).

### Access App Environment Variables

Environment variables defined at the application level can be accessed by workflow tools through namespaces. To make a variable available within a workflow tool:

1. Add the variable to a namespace.
2. Associate the namespace with the workflow agent.

Once associated, reference variables using `context.app.env.<variable-name>`.

For more information, see [Environment Variables](/agent-platform/agents/agentic-apps/settings/variables).

### PII Handling

App-scoped Workflow Tools inherit the application\`s PII protection capabilities, ensuring sensitive data is securely processed without exposure in logs, traces, or model outputs.

* Before execution, input fields are automatically scanned for declared PII patterns in the application config.
* Inputs identified as PII are masked and passed to the tool in redacted form.
* If the Workflow Tool is granted access to the original PII value, it can securely unredact and use it internally—while monitoring, debugging logs, and execution traces continue to show only masked values.

<Note>PII handling applies only to workflow tools associated with Agentic Apps. Tools in the library operate independently and do not apply PII sensitization to inputs.</Note>

***

## Managing Library Workflow Tools

Workflow tools created in the **Tools** module are managed in the Tools page and appear in the Tools Library.

The Tools page provides a central place to view, edit, and manage a workflow tool. It includes the Overview page, workflow canvas access, environment variables, guardrails, versioning, and related operations.

### Create a New Workflow Tool

1. Log in to your account and click **Tools**.
2. On the **Tools** page, click **Create new tool**.
3. Enter a name and a brief description for the tool and click **Create**.
4. The tool is created, and the **Tool Flow** option is displayed. You can start creating your tool flow immediately.

<Tip>You can also add a tool by installing a pre-configured template from the Tools Library marketplace and customizing the flow for your use case.</Tip>

### Tool Templates

Instead of building a tool flow from scratch, Tool Templates give you access to pre-configured flows designed for specific business use cases. These pre-built integrations require minimal setup and can be customized through the visual canvas.

The **Tools Library Marketplace** offers more than 50 prebuilt tool templates across categories including Brand Insights, Brand Monitoring, CRM, Competitive Analysis, Content, Customer Support, Finance, Marketing, Operations, Retail, Sales, Social Media, and Speech to Text. Supported AI tasks include topic analysis, sentiment, summarization, tagging, intent detection, and content generation.

**Template types:**

* **Pre-built templates** — Ready-to-deploy flows with pre-configured integrations (for example, an email auto-replier or automated grading system).
* **Customizable templates** — Node-based flows you can tailor to your business needs using the various node types on the canvas.

**Key benefits:**

* **Quick setup** — Significantly reduces deployment time and costs.
* **Customizable** — Retain essential prebuilt elements and remove unnecessary ones.
* **Seamless integration** — Import directly into existing flows and automate key actions within minutes.
* **Enhanced developer experience** — Eliminate repetitive tasks with minimal coding effort.

#### Install a Tool Template

1. Log in and click **Tools** from the list of modules.
2. Click **Tools** on the top navigation bar.
3. If adding your first tool, click **Tool templates**. Otherwise, on the **All Tools** or **My Tools** tab, click **Tool Templates** to access the Tools Library/Marketplace.
4. Scroll to the **Tools** section. Use the left filter to select **Categories** and **Tasks**.
5. Click the required template to view its information window, which includes the template name, description, compatible LLM model, configuration status, prebuilt flow preview, related templates, and developer details.
6. Click **Install** to connect to the Marketplace and import the template along with its pre-configured flow.

The system redirects you to the **Tool Flow** page. Click **Go to Flow** to view and manage the prebuilt canvas.

**Important:**

* After it is installed, the template shows in **My Tools**.
* A PDF document with key details (input/output, environment variables, usage guide, key components) is displayed for download.
* The first installation retains the original template name and description.
* Reinstalling the same template appends a unique sequential number: `Tool Template Name_<sequential-number>` (for example, `Automatic grading system_1743151769005`).
* Canvas-level errors may appear on fresh installations (for example, unconnected AI nodes or empty API nodes). Click the **warning** icon to view and fix errors.

#### Manage a Tool Template

To modify a template\`s name, description, async configuration, or to delete the template:

1. Open the **Tools** dashboard and click the required tool.
2. Click **Configurations** in the left navigation menu.
3. Make the required changes or proceed to delete the tool.

<Note>Deleting the tool is irreversible and removes all the associated data.</Note>

***

### Import a Tool

Using the import functionality, you can create a new tool or add it as a version to an existing tool. The import process preserves tool configuration—including prompts, properties, linked tools, and external/open-source models—while handling environment variables, errors, and role permissions.

<Note>Users with only **Viewer** permissions can\`t import a tool.</Note>

#### Import to Create a New Tool

Import a `.zip` package from your local system containing the flow definition, app definition, and environment variable JSON files from another environment.

1. Log in and click **Tools** from the list of modules.

2. Click the **Tools** tab on the top navigation bar.

3. Click **Import Tool** (or the **Import tool** icon on the Tools dashboard if tools already exist).

4. In the **Import tool** window, provide:

   **Required:**

   * **Tool Name** — Provide a unique name to avoid conflicts with existing tools.
   * **Flow definition file** — Upload `flow_definition.json`. Includes the tool\`s canvas definitions (node definitions) and AI node configurations, including prompts, hyperparameters, and timeout information.

   **Optional:**

   * **App definition file** — Upload `app_definition.json`. Includes general tool version information and guardrails.
   * **Environment variable file** — Upload `env_variables.json`. Includes environment variables set for the tool.

5. Click **Import**. The system redirects you to the **Tool Flow** page. Click **Go to flow** to access the canvas.

**After import:**

* The tool is listed under **All tools** and **My tools** with status **In Development**.
* Node types, descriptions, input/output variables, scanners, and sync/async setup are preserved.
* If the AI node's model does not match available models in the current account, the model field is left empty but all prompt definitions are imported.
* API keys are not transferred during import.
* The imported tool cannot be shared with other users.

**Failure scenarios:** Import may fail due to an incompatible tool version, corrupt file, internal error, or missing guardrails—triggering an error notification.

#### Import Best Practices

* **Export first** — Always export the current tool version before importing to ensure all configurations are available.
* **Check environment dependencies** — Verify that the correct model is available, linked tools exist by the same name for auto-linking, and environment variables and configuration files are compatible.
* **Import in order** — Import the parent tool and any associated versions in order, and ensure there are no conflicts with existing tools.

***

## Workflow Tools Management Page

Central interface for opening the workflow canvas and configuring, versioning, deploying, and monitoring workflow tools—available when you open a tool from Agentic Apps or the Tools module.

| Section                                                                         | Description                                                                            |
| ------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
| [Overview](/agent-platform/tools/workflow#tool-overview)                        | Displays high-level tool metadata, status, and summary information.                    |
| [Guardrails](/agent-platform/tools/workflow#guardrails)                         | Enable safety and compliance scanners (input/output) for the tool.                     |
| [Environment Variables](/agent-platform/tools/workflow#environment-variables)   | Manage tool-specific values referenced across the workflow.                            |
| [Versions](/agent-platform/tools/workflow#versions)                             | Create, restore, deploy, undeploy, or delete immutable snapshots of the workflow tool. |
| [API Keys](/agent-platform/tools/workflow#api-keys)                             | Generate and manage API keys for calling the tool’s endpoint.                          |
| [Audit Logs](/agent-platform/tools/workflow#audit-logs)                         | View operation logs related to this tool for governance and traceability.              |
| [Tool Monitor](/agent-platform/tools/workflow#tool-monitor)                     | Monitor performance metrics, execution histories, and runtime diagnostics.             |
| [Sharing & Permissions](/agent-platform/tools/workflow#sharing-and-permissions) | Assign or modify user access levels for the tool.                                      |
| [Configurations](/agent-platform/tools/workflow#configurations)                 | Provides import, export, and delete options for the workflow tool draft.               |

To start building workflow logic by using nodes, go to [Designing Workflows](/agent-platform/tools/workflow#designing-workflows).

### Tool Overview

Summary of the workflow tool, including its purpose, ownership details, and development status. The Overview page displays:

* **Tool summary** — what the tool is for and how it is described.
* **Ownership and activity** — who created the tool and when it was last updated.
* **Draft status** — when the workflow canvas was last edited.
* **Access to editing** — open the canvas directly using **Go to Flow**.
* **Version readiness** — confirm that the draft is in a valid state before creating a version.

***

### Guardrails

Enable safety scanning for AI nodes to enforce safety, policy, and compliance checks:

```yaml  theme={null}
guardrails:
  input_scanning: true
  output_scanning: true
  scanners:
    - toxicity
    - pii_detection
    - jailbreak_detection
```

Guardrails scan LLM inputs and outputs, prevent unsafe or non-compliant responses, and apply consistent enforcement across workflows.

***

### Environment Variables

Store reusable values and sensitive configurations that can be referenced by different nodes in the tool flow.

**Add an Environment Variable:**

1. Open the workflow tool and select **Environment Variables** in the left navigation.
2. Click **Add** or **Add variable**.
3. Provide:
   * **Variable name** — Descriptive name.
   * **Secure variable** — Enable the toggle to mark as a secret.
   * **Value** — Desired value.
   * **Notes** (optional) — Usage notes or purpose.
4. Click **Save**.

**Edit or Delete:** Click the three-dots icon next to the variable name and select **Edit** or **Delete**.

**Reference variables in nodes:**

```yaml  theme={null}
url: "{{env.API_BASE_URL}}/endpoint"
headers:
  Authorization: "Bearer {{env.API_KEY}}"
```

***

### Versions

The Versions section provides controls for creating, managing, and maintaining workflow tool versions. Versions help you track changes, ensure reliability, and deploy stable configurations.

*Each version is an immutable snapshot that includes the tool name and description, flow canvas, guardrails, and environment variables at the time it is created.*

#### Create a Tool Version

1. Open the workflow tool and select **Versions** in the left navigation.
2. Choose **New Version**, enter details, review the summary, and confirm.

*Rules:*

* The workflow draft cannot be versioned if the canvas contains errors.
* Versions cannot be modified after creation.
* Snapshots are always created from the current draft.

#### Manage Versions

The Versions list displays all existing versions of a workflow tool, including their name, description, guardrails and environment variables, deployment status, and creation details.

*The Status column is displayed only for App-scoped workflow tools; not for tools in the Tools Library.*

| Action              | Description                                                                                                                                                                                                                                 |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Preview Version** | Displays a read-only summary of the version’s core components, including the flow, guardrails, and environment variables.                                                                                                                   |
| **Go to Flow**      | Opens the versioned flow in the canvas in read-only mode.                                                                                                                                                                                   |
| **Endpoint**        | Displays the API endpoint associated with the version and allows selecting the execution mode (synchronous or asynchronous).<br /><br /> *Available only for workflow tools in the Tools Library; not shown for app-scoped workflow tools*. |
| **Restore Version** | Replaces the current draft with the selected version after confirmation. The restored version becomes the active draft.                                                                                                                     |
| **Delete Version**  | Removes the version after confirmation.                                                                                                                                                                                                     |

<Note>When you create a version, its endpoint becomes active. If the version is deleted, the endpoint is disabled and any calls to that endpoint will fail.</Note>

For more information about workflow tool versions and app versions, see [Workflow tools and App versioning](/agent-platform/tools/workflow-tool-and-app-version).

#### Manage Endpoints

The Endpoint section is accessed from **Versions → View Endpoint**. Endpoint settings define how external applications call the workflow tool and how each version is exposed as an API.

**Execution Modes**

**Synchronous**:

* **Default mode** —the request waits for completion before returning a response. Suitable for real-time operations.
* **Timeout:** Configurable, range 60–300 seconds (default: 180 seconds).

```
Request → Execute all nodes → Return response
```

**Asynchronous**: For long-running workflows. Supports two delivery methods:

* **Push endpoints** — Actively send response data to the client via webhook as soon as it becomes available. Useful when the client needs immediate notification of changes.
* **Poll endpoints** — The client periodically checks to retrieve response data on its own schedule. Useful when the client only needs updates at specific intervals.

**Sync/Async Mode Setup**:

Configure the sync/async mode for the tool endpoint. Changing the mode requires redeployment.

1. Click **Versions** in the left navigation, then click the **Setup sync/async** icon.
2. In the **Sync/Async mode setup** popup:
   * **Synchronous mode timeout** — Range: 60–300 seconds (default: 180 seconds).
   * **Asynchronous mode** — Enable the **Enable async** toggle, provide the external application URL, enter the access token, and set the timeout (60–600 seconds, or No timeout).
3. Click **Save**.
4. Click **Deploy** to redeploy with the new mode.

***

### API Keys

Generate API keys to enable secure access to your deployed tools from external environments. Keys should be shared only with trusted consumers and can be revoked or rotated as needed.

<Warning>The Platform won\`t show the API key again after creation. Keep it secure and never expose it in client-side code or public repositories.</Warning>

#### Create an API Key

1. Open the workflow tool and select **API keys** in the left navigation.
2. Click **Create a new API key**.
3. Provide a descriptive name for the key and click **Generate key**.
4. Click **Copy and close** to save the key to your clipboard. Share this key with authorized users as needed.

All generated API keys are listed in the **API keys** section for easy reference and management.

***

### Audit Logs

Audit Logs provide full visibility into user actions and system interactions—tracking logins, role changes, model updates, and tool changes through timestamped log entries. This empowers admins to ensure compliance with internal policies and proactively mitigate risks.

Each log entry includes:

* **Event Name** — The specific event or action that occurred.
* **Category** — The module or entity affected.
* **User Name** — Who performed the action.
* **Date and Time** — When the event occurred.
* **Description** — Detailed information about the action.

#### Access Audit Logs

1. Open the workflow tool and select **Audit logs** in the left navigation.
2. The Audit logs page is displayed. Click each row to view more details about the event.

Use the time range selector to filter by current or past periods. Apply custom filters by category, event, or user to view only the required logs.

***

### Tool Monitor

Tool Monitor tracks and analyzes tool performance across multiple runs, providing a time-based, comprehensive view of tool activities.

**Key capabilities:**

* **Performance Tracking** — Monitor response times, execution patterns, and overall efficiency.
* **Dual-View Analytics:**
  * **All Runs** — Comprehensive data on all tool run instances (all endpoint calls).
  * **Model Runs** — Focused analytics on AI node executions.
* **Detailed Metrics** — Total runs, average response times (P90 and P99), failure rates.
* **API Key Usage Monitoring** — Track API key utilization across the tool ecosystem.
* **AI Node Analysis** — Performance insights per individual AI node.
* **Advanced Filtering** — Time-based searches and custom filters to drill down into specific scenarios.
* **Detailed Run Information** — Comprehensive logs and debug information per tool run.

#### Access Tool Monitor

1. Log in and click **Tools** from the list of modules.
2. On the **All tools** page, click a deployed tool. Tool monitoring is only available for tools deployed in production.
3. Click **Tool monitor** in the left navigation pane.
4. Click **All runs** or **Model runs** to view the respective data.
5. Click any row for detailed run information in the right panel.

**All Runs Tab**

Displays for each tool run:

| Field              | Description                                           |
| ------------------ | ----------------------------------------------------- |
| **Run ID**         | Unique identifier for the flow run                    |
| **Status**         | In Progress, Waiting, Success, or Failed              |
| **Response time**  | Duration to complete the request and return output    |
| **Nodes executed** | Total number of nodes executed in the run             |
| **Start time**     | When the request was initiated                        |
| **End time**       | When the response was received                        |
| **Source**         | Agentic App name or API Key name used to run the tool |

Summary metrics at the top of the page: **Total Runs**, **Response Time** (P90 and P99), **Failure Rate**. These metrics update when you apply filters or search criteria.

<Note>When there is nested (multi-level) tool calling, the immediate parent tool is displayed as the source.</Note>

**Model Runs Tab**

Each AI node in a tool is recorded as a separate request. If your tool has no AI nodes, this tab remains empty until AI nodes are added.

Displays for each AI node call:

| Field                     | Description                               |
| ------------------------- | ----------------------------------------- |
| **Request ID**            | Unique identifier for the AI node request |
| **Status**                | In Progress, Waiting, Success, or Failed  |
| **Node name**             | Name of the AI node                       |
| **Model name**            | Model used for the AI node                |
| **Response time**         | Time taken by the AI node                 |
| **Start time / End time** | Execution timestamps                      |

Summary metrics: **Total Requests**, **Response Time** (P90 and P99), **Failure Rate**.

#### View Detailed Run Information

Click any row in either tab to open a detailed panel on the right, similar to the Run dialog on the Tool flow canvas. The panel displays:

* **Run ID / Request ID**
* **Response Time**
* **Debug icon** — Click to view debug log details.
* **Input** — Input sent to the tool.
* **Flow log** — Node-level success/failure details, including scanner information for AI nodes.
* **Output** — Tool output for successful runs, with copy option and token view.

#### Timeout Impact on Endpoints

| Scenario                                                                           | Behavior                                                                                   |
| ---------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
| Tool Sync + API node Sync                                                          | Request immediately fulfilled; `In-progress` while running                                 |
| Tool Sync + API node Async (node timeout \< sync timeout)                          | `In-progress` during execution; `Waiting` while paused for external response               |
| Tool Async + API node Sync                                                         | Executes and sends response to callback URL; `In-progress` while running                   |
| Tool Async + API node Async (node timeout \< tool async timeout, or both infinite) | `Waiting` while paused for external response; resumes `In-progress` when response received |

#### Tool Run Errors

Errors that occur via the endpoint are displayed in a separate window for the specified Run ID. Click the corresponding entry in the **Tool Monitor** dashboard to view details.

**Error categories:**

| Error Scenario                    | Description                               | Category        | HTTP Status               |
| :-------------------------------- | :---------------------------------------- | :-------------- | :------------------------ |
| Mandatory input field missing     | A required input field was not provided   | Data Validation | 400 Bad Request           |
| Invalid data type for input field | An incorrect data type was provided       | Data Validation | 400 Bad Request           |
| Empty Input Object                | A field input is missing a value          | Data Validation | 400 Bad Request           |
| Large Request Payload             | Payload exceeds the server\`s size limit  | Data Validation | 413 Payload Too Large     |
| Server-side issues                | Technical issue caused the server to fail | Internal Server | 500 Internal Server Error |
| Request timeout                   | Network or server connection issue        | Network         | 408 Request Timeout       |
| Guardrail Failure                 | Risk score exceeded threshold at AI node  | Content Filter  | 403 Forbidden             |

***

### Sharing and Permissions

Account owners can invite users to collaborate on specific tools. Invited users can access the **Models** and **Data** modules for the invited account but can only see the tools they are invited to.

<Note>You can only invite users who already have access to your account.</Note>

#### Invite Users

1. Log in and click **Tools** from the list of modules.
2. Select the required tool.
3. Click **Sharing & Permission** in the left navigation bar. Existing collaborators are listed.
4. Click **Invite** (visible only to account owners). The **Invite Users** dialog is displayed.
5. Enter users\` email addresses and click **Invite** to grant access.

***

### Configurations

Options for managing the workflow tool. All actions affect only the draft; versioned flows remain unchanged.

| Action                                                                                  | Description                                                                       |
| --------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
| [Import a tool as a version](/agent-platform/tools/workflow#import-a-tool-as-a-version) | Replaces the current draft with the imported version after successful validation. |
| [Export a tool](/agent-platform/tools/workflow#export-a-tool)                           | Exports the current draft workflow.                                               |
| [Delete Tool](/agent-platform/tools/workflow#export-a-tool)                             | Deletes the workflow tool after confirmation.                                     |

#### Import a Tool as a Version

Import a tool as a version of an existing parent tool from the **Configurations** page. Back up the current in-development version before importing to preserve its configuration definitions.

<Note>To import a tool as a version, the parent tool must be deployed in your account.</Note>

**Required files:**

* `flow_definition.json`
* `app_definition.json`
* `env_variables.json`

**Steps to Import a Tool as a Version**:

1. Log in and click **Tools** from the list of modules.
2. Select the parent tool and click **Configurations**.
3. Scroll to the **Import tool** section and click **Import**.
4. (Optional) Select **Back up your current tool** to preserve the data of the version being replaced. The system automatically exports and saves the `.zip` package to the designated location.
5. Click **Import** in the confirmation dialog.
6. In the **Import Tool** window, upload the required JSON files and click **Import**.

After validation, the imported version is added under the parent tool. The parent tool\`s status is set to **In Development**, and **Updated on** reflects the import date.

**Resolving conflicting environment variables**:

When importing, conflicts may arise between the parent tool\`s environment variables and those in the imported version.

1. Select the **Conflicting variables** tab.
2. For each conflict, select **Overwrite** (use the imported value) or **Keep existing** (retain the current value).
3. Click **Proceed** to continue importing.

**To edit variables before resolving**:

1. Click the three-dots icon for the variable and select **Edit**.
2. Update the values and click **Save**.

To cancel during conflict resolution, click **Cancel** in the Edit window, then click **Confirm**.

<Info>Verify environment variables before importing. For conflicting values, existing ones are retained if not changed.</Info>

***

#### Export a Tool

Export specific tool versions as self-contained packages for data preservation and sharing without compromising configuration integrity or security.

The exported `.zip` file is named after the tool (for example, `Banking Assistant.zip`) and can be reimported to create a new tool or add it as a version.

<Note>Users with only **Viewer** permissions cannot export a tool.</Note>

**Exported package contents:**

| File                   | Contents                                                                                         |
| ---------------------- | ------------------------------------------------------------------------------------------------ |
| `flow_definition.json` | Canvas definitions, node definitions, AI node configurations (prompts, hyperparameters, timeout) |
| `app_definition.json`  | General tool version information and guardrails                                                  |
| `env_variables.json`   | Environment variables set for the tool                                                           |

**Excluded:** API keys, sharing permissions, tool endpoint, and audit logs.

**Steps to Export**:

1. Log in and click **Tools** from the list of modules.
2. Select the tool you want to export.
3. Click **Configurations** in the left navigation.
4. Scroll to the **Export tool** section. The currently deployed version is selected by default.
5. To change, select another version from the dropdown.
6. Click **Export**. A success message appears after validation and export complete.

<Note>After the export starts, you can\`t change the selected version.</Note>

***

#### Delete a Tool

The tool must be undeployed before deletion. Deletion removes all associated data and is irreversible.

1. Select the tool you want to delete.
2. Click **Configurations** in the left navigation.
3. Click **Proceed to delete**.
4. Follow the on-screen instructions to confirm deletion.

***

## Designing Workflows

### Overview

The Tool Flow builder is a visual, node-based canvas where you design tool logic by connecting components. Developers can create complex AI-powered automations for use cases such as candidate evaluation, banking applications, content generation, and more.

### Interface

<div class="ascii-art">
  ┌─────────────────────────────────────────────────────────────┐
  │  Workflow: get\_order\_status                  \[Test] \[Deploy]│
  ├─────────────────────────────────────────────────────────────┤
  │                                                             │
  │  ┌─────────┐                                                │
  │  │  START  │                                                │
  │  └────┬────┘                                                │
  │       │                                                     │
  │       ▼                                                     │
  │  ┌─────────────────┐                                        │
  │  │  Validate Input │                                        │
  │  └────────┬────────┘                                        │
  │           │                                                 │
  │       ┌───┴───┐                                             │
  │       ▼       ▼                                             │
  │  ┌────────┐ ┌────────┐                                      │
  │  │ Valid  │ │Invalid │                                      │
  │  └───┬────┘ └───┬────┘                                      │
  │      │          │                                           │
  │      ▼          ▼                                           │
  │  ┌────────┐ ┌────────┐                                      │
  │  │API Call│ │ Error  │                                      │
  │  └───┬────┘ └───┬────┘                                      │
  │      │          │                                           │
  │      └────┬─────┘                                           │
  │           ▼                                                 │
  │      ┌─────────┐                                            │
  │      │   END   │                                            │
  │      └─────────┘                                            │
  │                                                             │
  └─────────────────────────────────────────────────────────────┘
</div>

**Navigation:** **Tools → Select your tool → Overview → Go to Flow**

On the canvas, you can:

* Add, configure, and connect nodes.
* View and modify inputs and outputs
* Build structured logic using conditions, loops, and branches
* Test the workflow.
* Validate and debug execution paths

The canvas represents the editable draft of the workflow tool.

All changes made in the canvas must be saved and validated before the draft can be versioned.

***

## Flow Drafts and Versions

The flow builder automatically saves all changes to the draft as you work.

To save a fixed snapshot of the draft, create a version. A version includes the current flow, guardrails, and environment variables. For more information about version lifecycle, deployment, and endpoints, see [Versions](/agent-platform/tools/workflow#versions).

You can create a version from either location:

* **Flow Builder**: Select the **Flow versions** menu in the canvas header and choose **+**.
* **Versions tab**: Open **Versions** in the left navigation and select **New Version**.

After deploying a flow, the tool appears on the Tools page with the status **Deployed**.

<Note>In the **Flow versions** dialog on the canvas, click the 3-dots icon beside a version name to **restore** or **delete** it. When you restore a version, the current version moves to the bottom of the list and the restored version becomes current. A deployed version can be restored but not deleted.</Note>

***

## Node Types

Workflows are built using different node types, each handling a specific function in the flow. For more information on the different types of nodes, see [Node Types](/agent-platform/tools/nodes).

### Control Nodes

| Node          | Purpose                                |
| ------------- | -------------------------------------- |
| **Start**     | Entry point, receives input parameters |
| **End**       | Exit point, returns output             |
| **Condition** | Branching based on logic               |
| **Loop**      | Iterate over collections               |

### Action Nodes

| Node            | Purpose                                 |
| --------------- | --------------------------------------- |
| **API**         | Make HTTP requests to external services |
| **Function**    | Transform data with expressions         |
| **Integration** | Connect to pre-built connectors         |
| **Human**       | Pause for human input/approval          |

### AI Nodes

| Node              | Purpose                |
| ----------------- | ---------------------- |
| **Text-to-Text**  | Generate text with LLM |
| **Text-to-Image** | Generate images        |
| **Audio-to-Text** | Transcribe audio       |
| **Image-to-Text** | Analyze images         |
| **DocSearch**     | Search knowledge bases |

***

## Managing Nodes

Navigation: **Tools** > **Create new tool** > **Go to flow** > flow canvas opens.

### Add Nodes

Every new flow begins with a **Start** node, automatically placed on the canvas. All nodes must be connected—directly or indirectly—to the Start node for the flow to execute correctly.

| Method           | How                                                         |
| ---------------- | ----------------------------------------------------------- |
| **Plus icon**    | Click `+` on any existing node and select a type            |
| **Assets panel** | Drag a node type onto the canvas                            |
| **Bottom tray**  | Click a node type in the quick-access tray below the canvas |

### Rename Nodes

1. Right-click the node on the canvas.
2. Select **Rename** from the context menu.
3. Enter the new name in the **Node Name** field of the configuration panel.

Use clear, descriptive names (for example, "Validate Email Input" instead of "Function Node 1").

### Delete Nodes

Right-click → **Delete**.

Deleting a node also removes its associated connections. Reconnect any dependent paths afterward.

### Rearrange Nodes

Click and drag any node to move it. Connected lines adjust automatically while other nodes remain fixed.

**Layout options:**

* **Auto Arrange** — Right-click the canvas and select **Auto arrange** to automatically reposition all nodes for a cleaner layout.
* **Show/Hide UI or Grid** — Right-click the canvas to toggle visual elements.

***

## Connecting Nodes

Node connections determine how tasks flow—either sequentially or through parallel branches.

**Connection methods:**

* **Canvas-based (visual)** — Drag and drop to connect nodes directly on the canvas.
* **Node configuration panel** — Define success and failure paths from the node\`s property panel.

### Sequential vs. Parallel Execution

| Feature          | Sequential Execution                                                                             | Parallel Execution                                                                                           |
| :--------------- | :----------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------- |
| **Use When**     | Tasks depend on previous steps and must run in order                                             | Tasks are independent and can run simultaneously                                                             |
| **How It Works** | Each node runs only after the prior node finishes; flows in a top-down or left-to-right sequence | All connected branches from a single node execute at the same time; up to **10 branches** from a single node |
| **Benefits**     | Predictable, controlled execution; easier debugging                                              | Reduces total execution time; boosts performance with simultaneous operations                                |
| **Ideal for**    | Step-by-step logic, ordered linear processing                                                    | Multi-channel actions, concurrent task execution                                                             |

### Designing Sequential Flows

In a sequential structure, nodes execute one after another in a defined order. Each node begins only after the previous one finishes.

**Option 1: Drag-to-Connect**

1. Hover over the blue + icon or grey connector dot on the source node.
2. Click and drag a line to the destination node.

**Option 2: Blue + Icon**

1. Hover over the node, click the blue + icon, and choose **Add New** or **Add Existing**. The node is added and connected in sequence.

**Option 3: Connections Panel**

1. Click the node to open the **Configuration Panel** on the right.
2. Go to the **Connections** tab.
3. Under **On Success** or **On Failure**, use the dropdown to add a new node or connect to an existing, unused node.

**Key considerations:**

* All paths must converge at an End Node.
* Sequential chains are arranged left to right for clarity.
* Logs display outputs in the exact order nodes are triggered, making debugging easier.
* Only one connection can exist per outcome (On Success or On Failure) in a sequential flow—any additional connections are treated as parallel branches.

### Designing Parallel Flows

In a parallel flow, multiple branches run at the same time from the same parent node. Each branch performs an independent task.

**Parallel design patterns:**

* **Simple Parallel** — A single node branches to multiple child nodes running independently. Use when tasks can occur simultaneously without dependencies.
* **Nested Parallel** — A parallel branch contains its own parallel branches. Useful for multi-step logic where each level does independent work.
* **Conditional + Parallel** — Combine condition nodes with parallel execution. Based on logic (for example, if/else), different sets of parallel branches are triggered.

**Option 1: Blue + Icon**

1. Hover over the node and click the blue + icon.
2. Select **Add new** or **Add existing** to add multiple nodes as parallel branches.

**Option 2: Drag-to-Connect**

1. Drag from the source node to another node on the canvas. Repeat from the same parent to form additional parallel branches.

**Option 3: Connections Panel**

1. Click the node and open the **Configuration Panel**.
2. Go to the **Connections** tab.
3. Use the **On Success** or **On Failure** dropdowns and click **+ Parallel Node** to add more branches.

**Key considerations for parallel flows:**

* All branches from a node run at the same time.
* The flow waits for all parallel branches to complete before moving to the next step.
* End node outputs from all branches are combined before passing to the next node.
* The canvas layout expands automatically to fit multiple branches.
* Logs show branch-specific outputs grouped under the parent node, labeled (A, B, C) for each path.

### Manage and Remove Connections

**From the canvas:**

1. Click the arrow/line between two nodes.
2. Click the Delete icon. The nodes remain on the canvas but are no longer linked.

**From the Configuration Panel:**

1. Open the panel by selecting a node.
2. In the **Connections** tab, click the Delete icon next to the connection to remove.

### Constraints

* Maximum **10 outgoing connections** per node.
* No duplicate connections from the same parent.
* No backward loops (prevents cycles).

***

## Debugging

The Debug panel shows:

* Execution status per node.
* Input/output values at each step.
* Error messages.
* Timing metrics.
* Iteration details (for Loop nodes; click the loop icon to drill into individual runs).

***

## Manage Input and Output

Tool flows use input and output variables as context objects throughout execution.

* **Input Variables** — Provide initial data to the flow. Accessible immediately after the Start node using the syntax: `context.steps.Start.inputVariable`
* **Output Variables** — Store and return derived values from the flow. Set in any node; for example, in the End node, assign results using: `{{context.steps.AInode.output}}`

### Add Input Variables

1. Click **Manage I/O** at the top of the Tool flow canvas, or click the **Start** node. The **Manage Input & Output** dialog is displayed.
2. On the **Input** tab, click **+ Add input variable**.
3. Provide a **Name (key)** for the input variable (for example, `Product_ID`).
4. Select a **Type** from the dropdown:
   * **Text**, **Number**, or **Boolean** — An optional **Default value** field appears.
   * **Remote file** — A **File URL timeout** field appears. Set the timeout between 5 minutes and 7 days (default: 5 minutes).
   * **List of values (Enum)** — Add predefined allowed values via **Add Values +**. Enable **Default value** to select from defined values. The system validates input against enum values and displays an error for invalid entries.
   * **JSON** — A schema editor appears. Define the JSON schema and ensure the default value matches the schema. If the JSON is invalid, execution fails with an error.
5. Enable the **Mandatory** toggle if the field is required.
6. Click **Save**. The input variable appears on the **Input** tab.

### Add Output Variables

1. Click **Manage I/O** at the top of the canvas.
2. On the **Output** tab, click **+ Add output variable**.
3. Provide a **Name (key)** and select a **Type**: String, Number, JSON, or Boolean.
4. Click **Save**.

You can also add an output variable in the End node using the **Add a Key** option on the node\`s interface.

If a type mismatch occurs, the endpoint succeeds but includes a warning in the response with the key name and nature of the mismatch. If one or more keys fail validation, the response includes warnings for failed keys and outputs for valid ones.

***

## Building a Workflow

### Step 1: Create the Tool

1. Navigate to **Tools** → **+ New Tool**
2. Select **Workflow Tool**
3. Enter name and description:

```yaml  theme={null}
name: get_weather
description: |
  Retrieves current weather conditions for a specified location.
  Returns temperature, conditions, and forecast summary.
```

### Step 2: Define Input Parameters

Configure what the tool accepts:

```yaml  theme={null}
parameters:
  location:
    type: string
    description: City name or coordinates
    required: true

  units:
    type: string
    enum: [celsius, fahrenheit]
    default: celsius
```

### Step 3: Build the Flow

Drag nodes onto the canvas and connect them:

<div class="ascii-art">
  │           Start
  │             │
  │             ▼
  \| ┌─────────────────────────┐
  \| │ API Node: Weather API   │
  \| │ URL: api.weather.com    │
  \| │ Method: GET             │
  \| │ Params: location, units │
  \| └───────────┬─────────────┘
  │             ▼
  \| ┌─────────────────────────┐
  \| │ Function: Format Output │
  \| │ Transform response to   │
  \| │ user-friendly format    │
  \| └───────────┬─────────────┘
  │             ▼
  │            End
</div>

### Step 4: Configure Nodes

**API Node Example:**

```yaml  theme={null}
url: https://api.weather.com/v1/current
method: GET
headers:
  Authorization: Bearer {{env.WEATHER_API_KEY}}
query_params:
  q: "{{input.location}}"
  units: "{{input.units}}"
```

**Function Node Example:**

```javascript  theme={null}
return {
  temperature: response.main.temp,
  condition: response.weather[0].description,
  humidity: response.main.humidity,
  location: response.name
}
```

### Step 5: Define Output

Specify the return structure:

```yaml  theme={null}
output:
  type: object
  properties:
    temperature:
      type: number
    condition:
      type: string
    humidity:
      type: number
    location:
      type: string
```

### Step 6: Test

1. Click the **Run flow** icon at the upper right corner of the canvas.
2. Provide sample input values in the Run dialog.
3. Click the **Debug** icon to open the debug log and monitor execution.
4. Review the execution trace, output, and any errors.
5. For a successful flow, copy output results using the Copy icon.

You can stop the flow at any point and restart by clicking **Run flow** again.

### Step 7: Deploy

Click **Deploy** to generate API endpoints. (see [Deploy a Tool](/agent-platform/tools/workflow#deploy-a-tool))

***

## Running and Testing Flows

When you run a flow, it generates a context object stored temporarily at the node level, allowing you to monitor progress through the debug log.

**Flow results:**

* **Successful flow** — Copy output using the Copy icon. Overall runtime is displayed.
* **Flow errors** — An error message is displayed; the output key appears empty with JSON-formatted failure output.

### Debug Log

The debug log captures detailed information for each step:

* **Flow input values** — The values provided for input variables.
* **Flow-level log details** — Overview of flow initiation and progress.
* **Node-level information** — Success or failure status per node, with links to additional details.
* **Tool calling details** — Logs of any tools called during execution (AI nodes only), including inputs (JSON), responses, and errors. A separate panel shows detailed tool traces.
* **Node metrics** per node:
  * **Initiated On** — Timestamp when the node was triggered.
  * **Executed On** — Timestamp when execution completed.
  * **Total Time Taken** — Duration of node execution.
  * **Tokens** — Token usage (AI nodes only).

Expand the debug panel to full screen for a cleaner layout. All nodes align left; clicking a node reveals its input, output, and metrics side by side.

### Time Metrics for API and AI Nodes

**API Nodes — Synchronous mode:**

* **Node processing time** — Time to complete execution.
* **API Response time** — Time waiting for the external API response.

**API Nodes — Asynchronous mode:**

* **Node paused at** — Timestamp when the node paused waiting for response.
* **Node resumed at** — Timestamp when the node resumed after receiving response.
* **Total wait time** — Duration between pausing and resuming.
* **Node processing time** — Time spent processing after resuming.

**AI Nodes:**

* **Node processing time** — Time to complete execution.
* **LLM response time** — Time for the connected model to return a response.

***

## Conditions and Branching

Use condition nodes for logic-based branching:

<div class="ascii-art">
  │             ┌─────────────┐
  │             │  Condition  │
  │             │ amount > 100│
  │             └──────┬──────┘
  │                    │
  │       ┌────────────┼────────────┐
  │       ▼            ▼            ▼
  │  ┌────────┐   ┌────────┐   ┌────────┐
  │  │  True  │   │ False  │   │Default │
  │  └────────┘   └────────┘   └────────┘
</div>

**Expression syntax:**

```javascript  theme={null}
// Comparisons
input.amount > 100
response.status === "success"

// Logical operators
input.priority === "high" && input.urgent === true

// String operations
input.email.includes("@company.com")
```

***

## Loops

Iterate over arrays:

<div class="ascii-art">
  ┌──────────────────────────────┐
  │ Loop: for each item in list  │
  ├──────────────────────────────┤
  │  ┌─────────────────────────┐ │
  │  │      Process Item       │ │
  │  └─────────────────────────┘ │
  └──────────────────────────────┘
</div>

**Configuration:**

```yaml  theme={null}
loop:
  collection: "{{response.items}}"
  item_variable: current_item
  max_iterations: 100
```

***

## Error Handling

Configure fallbacks for failures:

```yaml  theme={null}
error_handling:
  on_error: continue  # or: stop, retry
  retry:
    attempts: 3
    delay_ms: 1000
  fallback:
    node: error_handler
```

### Common Node Issues

| Issue                                    | Cause                              | Resolution                                    |
| :--------------------------------------- | :--------------------------------- | :-------------------------------------------- |
| Can\`t add a new connection              | Node has 10 outgoing connections   | Delete a connection to add more               |
| "No available nodes" in the dropdown     | All valid nodes are already linked | Create a new node or unlink existing ones     |
| Flow doesn\`t execute                    | Broken or incomplete connections   | Check for stray nodes or missing End Nodes    |
| Error when connecting to a previous node | Backward looping is not allowed    | Reconnect to a valid forward step in the flow |

## Tool Flow Change Log

The change log lets admins track, audit, and review all changes made to a tool\`s flow over time—including node property updates, user changes, and version-specific modifications.

**Key features:**

* **Event tracking** — Records each change when a user exits a property field in a node, capturing the timestamp, responsible user, and change details.
* **Filters** — Filter by date range, node type, or specific team member for enhanced searchability.

### Access the Change Log

1. Open the tool flow for the tool you want to audit.
2. Click the **History/Log** icon at the top-right corner of the page. The change log panel opens on the right, showing the most recent changes first.

Each log entry displays:

* Timestamp of the change
* Brief description of the change
* Name of the user who made the change

### Filter the Change Log

* **Date filter** — Click the Calendar icon to select a specific date range.
* **Filter By** — Click the Filter icon to filter by **User** or **Node Type**. The log updates dynamically based on the selected filters.

***

## Best Practices

### Keep Workflows Focused

One workflow = one capability. Don\`t combine unrelated logic.

### Use Meaningful Names

```yaml  theme={null}
# Good
get_customer_orders
validate_shipping_address
process_refund_request

# Avoid
workflow_1
helper
do_stuff
```

### Handle Errors Gracefully

Always include error paths and meaningful error messages.

### Test Edge Cases

* Invalid inputs
* API failures
* Empty responses
* Timeout scenarios

### Document Complex Logic

Add comments to condition expressions and complex transformations.

### Flow Design Tips

* Use **parallel** structures to speed up independent tasks.
* Use **sequential** paths when steps depend on the results of prior steps.
* Combine both styles to build hybrid flows for advanced logic.
* Always monitor node limits and watch for visual cues — one line = sequence, branching lines = parallel.
* Regularly use **Auto Arrange** to clean up the canvas.
* Ensure every logical branch concludes at an **End Node**.


Built with [Mintlify](https://mintlify.com).