> For the complete documentation index, see [llms.txt](https://doc.wearepatchworks.com/product-documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://doc.wearepatchworks.com/product-documentation/ai/patchworks-ai-studio/custom-agents.md).

# Custom Agents

December 2026

## Introduction

Custom agents are AI agents that your team builds in [AI Studio](https://doc.wearepatchworks.com/product-documentation/ai-studio) to run and operate your integrations. Each agent has a **role**, an ordered list of **tasks**, and a defined set of **tools** and **MCP servers** it's allowed to use. Agents can run on a schedule in the background, or on demand in a chat interface.

A typical custom agent might review failed NetSuite orders every morning, group them by root cause, replay the ones that will now succeed, and post a summary to Slack — using tools you've built once and can reuse across any agent.

{% hint style="info" %}
Custom agents are managed from **AI Studio** in the left-hand navigation, which has four related sections: `custom agents`, `tools`, `external MCP` (MCP servers) and `run history`.
{% endhint %}

### Key concepts

| Concept        | Summary                                                                                                                                                                                                                            |
| -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Agent**      | A role plus an ordered list of tasks. An agent is either **scheduled** (runs in the background with no user in the loop) or **conversational** (runs in chat, on demand).                                                          |
| **Task**       | One step of the agent's work. Each task has its own prompt, tools and MCP servers, and receives the output of the task before it. The output of the last task is the run result.                                                   |
| **Tool**       | A saved action an agent can call — running a process flow, calling a connector endpoint, or calling a Patchworks API endpoint. Tools are built once and shared across every agent in your company.                                 |
| **MCP server** | An external MCP server you connect. Each server brings its own tools, which stay inside the server (they're not added to your Tools list). You choose which of its tools agents may use.                                           |
| **Guardrails** | Filtered words, a blocked message, run limits and notifications that keep an agent secure and on topic.                                                                                                                            |
| **Schedule**   | When and where a scheduled agent runs. An agent can have one or more schedules, each against its own [virtual environment](https://doc.wearepatchworks.com/product-documentation/virtual-environments/about-virtual-environments). |
| **Run**        | A single execution of an agent — scheduled, on request, or triggered from a conversation. Every run is recorded in run history with a task-by-task timeline.                                                                       |

### Accessing custom agents

Select `AI Studio` from the left-hand navigation, then `custom agents`. Any agents your team has built are shown as cards:

<div data-with-frame="true"><figure><img src="https://2440044887-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLYNcUBVQwSkOMG6KjZfz%2Fuploads%2FfbqQO2sFJFBY94WQg8ua%2Fagents_page.png?alt=media&amp;token=bd862831-a420-4200-9fa8-11957c7e4469" alt=""><figcaption></figcaption></figure></div>

Each card shows the agent's status and mode, its schedules (one line per virtual environment), the outcome and duration of its last run, and a `run now` button (or `finish setup` for drafts). Use the search field and `filters` to narrow the list by status, mode or environment.

| Status     | Meaning                                                                                                         |
| ---------- | --------------------------------------------------------------------------------------------------------------- |
| `Deployed` | The agent is live. Scheduled agents run on every enabled schedule; conversational agents are available in chat. |
| `Paused`   | The agent is deployed but none of its schedules are enabled, so it won't run until one is switched on.          |
| `Draft`    | The agent has been saved but not deployed. It never runs.                                                       |

The `⋯` menu on each card gives you `edit agent`, `run now`, `view run history`, `duplicate` and `delete agent`.

### Creating a custom agent

{% hint style="info" %}
Before you start, it's worth having the tools and MCP servers the agent will need already set up — although you can also create them from inside the agent editor.
{% endhint %}

Click the `create agent` button and choose how to start:

| Option            | Summary                                                                    |
| ----------------- | -------------------------------------------------------------------------- |
| **Blank agent**   | Set the role, tasks and guardrails yourself.                               |
| **Build with AI** | Describe the goal and Patchworks drafts the tasks for you. *(Coming soon)* |
| **Import JSON**   | Reuse an exported agent configuration. *(Coming soon)*                     |

The agent editor walks you through four steps: `profile`, `tasks`, `guardrails` and `review and deploy`. Your draft is saved automatically — you can leave and come back at any point, and nothing runs until you deploy.

#### Step 1: Profile

The profile defines who the agent is, which model it uses and how it runs:

<div data-with-frame="true"><figure><img src="https://2440044887-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLYNcUBVQwSkOMG6KjZfz%2Fuploads%2Fvfv72vw9ekwA503reKFw%2Feditor_profile.png?alt=media&amp;token=bee22f11-fc84-4d3f-8713-104a41baf4f5" alt=""><figcaption></figcaption></figure></div>

| Field                        | Summary                                                                                                                                                                                              |
| ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Name**                     | Shown in lists, chat and run logs.                                                                                                                                                                   |
| **Role**                     | The role this agent plays, up to 2,000 characters. It shapes how the agent reasons about every task you give it, so be specific about what the agent is for and what a good outcome looks like.      |
| **Model**                    | `Fast` — low latency, lowest cost; suited to extraction and formatting. `Standard` — higher quality for complex, multi-step work. `Thorough` — deepest reasoning; for ambiguous or high-stakes work. |
| **How does this agent run?** | `Conversational` — runs in chat, on demand. `Scheduled` — runs in the background, with no user in the loop.                                                                                          |

**Schedules**

If the agent is scheduled, add one or more schedules. Each schedule runs against its own virtual environment, so the same agent can run daily in production and hourly in staging, for example.

| Field                                             | Summary                                                                                                                                                                                                                                                |
| ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Virtual environment**                           | The environment this schedule runs in.                                                                                                                                                                                                                 |
| **Occurrence**                                    | `Minutes`, `Hourly`, `Daily`, `Monthly` or `Advanced`.                                                                                                                                                                                                 |
| **Every**                                         | For minute/hourly schedules, the interval. For daily schedules, `Day`, `Weekday`, `Weekend`, `Other day`, `Alternate other day` or `Custom`. For monthly schedules, `Month`, a season, `Every other month`, `Alternate every other month` or `Custom`. |
| **Starting time**                                 | The time of day the run starts (daily and monthly schedules).                                                                                                                                                                                          |
| **Days of the week / days of the month / months** | Fine-tune which days a daily or monthly schedule runs on.                                                                                                                                                                                              |
| **Cron expression**                               | For `Advanced` occurrences, enter a five-field cron expression. A plain-English summary of the expression is shown beneath it.                                                                                                                         |

Each schedule has an `enabled` toggle. A paused schedule is still deployed with the agent, but doesn't run until you enable it. The summary line under each schedule confirms the next run and environment.

Click `continue` to move to tasks.

#### Step 2: Tasks

Tasks break the agent's role into individual steps. Tasks run in order — each one gets its own prompt, tools and MCP servers, and receives the output of the task before it. The output of the last task is the run result.

<div data-with-frame="true"><figure><img src="https://2440044887-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLYNcUBVQwSkOMG6KjZfz%2Fuploads%2FdYwmiHJU4u1STviUqssy%2Feditor_tasks.png?alt=media&amp;token=ddc8d4a1-35ce-4542-b4f9-2202faccc1ac" alt=""><figcaption></figcaption></figure></div>

Click `add task`, then complete the task on the right:

| Field           | Summary                                                                                                                                                                                                                                                              |
| --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Task name**   | A short name, shown in run timelines and logs.                                                                                                                                                                                                                       |
| **Description** | One line describing what this step does.                                                                                                                                                                                                                             |
| **Task**        | The prompt for this step — describe the behaviour you want, what to return and anything to skip. For example: *"Fetch every failed order sync from the last 24 hours. Return the order id, the integration it came from, the error code and the raw error message."* |
| **Tools**       | The tools this task may call. Start typing to search, or choose `create a new tool` to build one without leaving the editor.                                                                                                                                         |
| **MCP servers** | The MCP servers whose enabled tools this task may call. Choose `connect a server` to add a new one.                                                                                                                                                                  |

Drag tasks to reorder them. Use `duplicate` and `delete` at the top of a task to manage it.

{% hint style="warning" %}
Flow tools count towards your operation usage — each call runs the process flow for real, in the virtual environment the agent is running against.
{% endhint %}

#### Step 3: Guardrails

Guardrails are rules that keep the agent secure and on topic. Anything caught here is blocked before it reaches the user.

<div data-with-frame="true"><figure><img src="https://2440044887-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLYNcUBVQwSkOMG6KjZfz%2Fuploads%2FdkmkkTjc0Fr26p0H6D4A%2Feditor_guardrails.png?alt=media&amp;token=19faa548-8db1-40b2-8198-5b981bdeb2fd" alt=""><figcaption></figcaption></figure></div>

**Content filtering**

| Field                   | Summary                                                                                                            |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------ |
| **Filtered words**      | Messages containing any of these terms are blocked automatically. Type a word or phrase and press enter to add it. |
| **Blocked message**     | The message shown whenever a filtered word is caught.                                                              |
| **Notify these people** | Users in your company who are emailed whenever a guardrail blocks a message or a run hits a limit.                 |

**Run limits**

A run stops as soon as any limit is reached, and the people above are notified.

| Field                  | Summary                                                            |
| ---------------------- | ------------------------------------------------------------------ |
| **Max tokens per run** | The total tokens (context and output) a single run may use.        |
| **Max turns per run**  | The maximum number of model turns in a single run.                 |
| **Max time per run**   | In minutes. The run is stopped and marked as timed out after this. |

{% hint style="info" %}
Run limits are the safety net for scheduled agents — because there's no user in the loop, they're what stops a run that gets stuck in a loop from consuming tokens indefinitely.
{% endhint %}

#### Step 4: Review and deploy

The review step summarises the profile, tasks and guardrails you've configured, with an `edit` link on each card to jump back and change something:

<div data-with-frame="true"><figure><img src="https://2440044887-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLYNcUBVQwSkOMG6KjZfz%2Fuploads%2FPFIqWitf29oBHDnOdw1D%2Feditor_review.png?alt=media&amp;token=cde3682a-ccb4-4d58-aec6-dc14cc56b901" alt=""><figcaption></figcaption></figure></div>

**Deployment**

The `deployment` card lists every virtual environment the agent has a schedule for. Deploying makes the agent reachable in every environment it has an enabled schedule for; paused schedules deploy but don't run until you enable them.

**Test agent**

Before deploying, use the `test agent` panel to try the agent out. Choose a virtual environment, type a message and check the responses. The panel shows tokens used in the test against the agent's per-run limit, and `reset` clears the conversation.

{% hint style="warning" %}
Test runs use the agent's real tools against the selected environment — a flow tool runs the flow, and a connector tool calls the connector.
{% endhint %}

When you're happy, click `deploy agent`. Runs start on the next scheduled slot in each enabled environment. Alternatively, `save as draft` keeps everything without deploying.

### Editing a deployed agent

Open an agent from the custom agents list (or choose `edit agent` from its `⋯` menu). The same four steps are available. Changes take effect on the next scheduled run in each environment — click `save changes` to apply them, or `revert` to discard.

### Tools

Tools are saved actions your agents can call. Build a tool once, then attach it to any task in any agent. Tools are shared across every agent in your company.

Select `AI Studio` > `tools`:

<div data-with-frame="true"><figure><img src="https://2440044887-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLYNcUBVQwSkOMG6KjZfz%2Fuploads%2FXeZE77fm37KonO7kkYdT%2Ftools_page.png?alt=media&amp;token=46a44ba7-7e18-4b2c-adea-1c7a7b8a6d00" alt=""><figcaption></figcaption></figure></div>

The list shows each tool's type, how many inputs it takes, how many agents use it and when it was last updated. The `⋯` menu gives you `edit tool`, `duplicate` and `delete tool`.

{% hint style="warning" %}
A tool that's in use by an agent can't be deleted — remove it from those tasks first.
{% endhint %}

#### Tool types

| Type               | Summary                                                                                                                                                                                                                       |
| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Flow**           | Lets the agent run a [process flow](https://doc.wearepatchworks.com/product-documentation/process-flows/managing-process-flows/flow-deployment) you've already built and deployed, on your existing mappings and credentials. |
| **Connector**      | One connector operation, with the request and response mapped for you — the agent only supplies the values it works out.                                                                                                      |
| **Patchworks API** | A single [Patchworks API](https://doc.wearepatchworks.com/product-documentation/developer-hub/patchworks-core-api) endpoint, authenticated with one of your API keys.                                                         |
| **Script**         | Runs one of your saved payload scripts on the data the agent passes in. *(Coming soon)*                                                                                                                                       |

#### Creating a tool

{% stepper %}
{% step %}
**Choose the tool type**

Click `create tool` and choose a type. The configuration section changes depending on what you pick — for example, a flow tool:

<figure><img src="https://2440044887-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLYNcUBVQwSkOMG6KjZfz%2Fuploads%2FClb5chWiDJ1Bc3Nu5ngn%2Ftool_editor_flow.png?alt=media&amp;token=8274830d-76e1-4a8f-8fcc-582f418e1181" alt=""><figcaption></figcaption></figure>
{% endstep %}

{% step %}
**Complete the basics**

Enter a `name` and a `description shown to the agent` (up to 400 characters). The agent chooses tools by name and description, so write both for the agent, not for your team — say what the tool does and when to use it, e.g. *"use this to read an order before replying"*.
{% endstep %}

{% step %}
**Configure what the tool calls**

| Type               | Configuration                                                                                         |
| ------------------ | ----------------------------------------------------------------------------------------------------- |
| **Flow**           | Select the `process flow` (and version) to run.                                                       |
| **Connector**      | Select the `connector`, the `instance` (which holds the credentials) and the `endpoint` to call.      |
| **Patchworks API** | Select the `method`, enter the `path`, and choose the `API key` to authenticate with (or create one). |

<div data-with-frame="true"><figure><img src="https://2440044887-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLYNcUBVQwSkOMG6KjZfz%2Fuploads%2FtUSSi6Li2gPu2r2gGMKC%2Ftool_editor_connector.png?alt=media&amp;token=35e000db-577c-4be8-905b-798990ac1b75" alt=""><figcaption></figcaption></figure></div>
{% endstep %}

{% step %}
**Define the inputs the agent supplies**

Inputs are the values the agent works out at run time and passes in. Anything not listed as an input stays fixed in the configuration above.

* For **flow** tools, inputs are loaded from the flow — its payload and flow variables. Click `reload from flow` if the flow changes.
* For **connector** tools, inputs are the endpoint variables (path, query and body parameters), loaded from the connector. Click `reload from endpoint` if the endpoint changes.
* For **Patchworks API** tools, click `add input` and define each one yourself.

Each input has a `name`, a `type`, a `required` toggle and a description under `what it is, for the agent` — the agent reads this when deciding what to send, so keep it plain and specific.

<div data-with-frame="true"><figure><img src="https://2440044887-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLYNcUBVQwSkOMG6KjZfz%2Fuploads%2FGwf5liTv6sRUe5dLdfSe%2Ftool_editor_api.png?alt=media&amp;token=173cecf4-7a3f-4564-bcff-e6b0030a3f7b" alt=""><figcaption></figcaption></figure></div>
{% endstep %}

{% step %}
**Test the tool**

Use the `test this tool` panel to enter sample values for each input and click `run test`. The result is exactly what the agent will receive back.
{% endstep %}

{% step %}
**Save**

Click `save tool`. The `used by` panel shows which agents and tasks use this tool once it's attached.
{% endstep %}
{% endstepper %}

### MCP servers

MCP servers are external servers you connect so that agents can use the tools they expose. Each server brings its own tools — you enable the ones your agents may use, and they stay inside the server rather than being added to your Tools list.

Select `AI Studio` > `external MCP`:

<div data-with-frame="true"><figure><img src="https://2440044887-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLYNcUBVQwSkOMG6KjZfz%2Fuploads%2FgrDWSulTVryjF2vd7Hb9%2Fsources_page.png?alt=media&amp;token=b37bd3de-c995-4b00-92a1-986f664836d0" alt=""><figcaption></figcaption></figure></div>

The list shows each server's URL, connection status, how many of its tools are enabled and how many agents use it.

| Status        | Meaning                                                                                                       |
| ------------- | ------------------------------------------------------------------------------------------------------------- |
| `Connected`   | The last connection test succeeded.                                                                           |
| `Not tested`  | The connection hasn't been tested yet, so its tools haven't been discovered and can't be used by agents.      |
| `Unreachable` | The last connection test failed. Agents that use this server's tools will fail at that task until it's fixed. |

{% hint style="warning" %}
Disconnecting a server removes its tools from every task that uses them.
{% endhint %}

#### Connecting an MCP server

{% stepper %}
{% step %}
**Add the connection details**

Click `connect server` and complete the `connection` section:

<div data-with-frame="true"><figure><img src="https://2440044887-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLYNcUBVQwSkOMG6KjZfz%2Fuploads%2Fg0Uo5gSsLn4VlQxFaLJD%2Fsource_editor.png?alt=media&amp;token=d1d7d725-7662-4503-b9e2-3540277f4c74" alt=""><figcaption></figcaption></figure></div>

| Field           | Summary                                                                   |
| --------------- | ------------------------------------------------------------------------- |
| **Name**        | Shown in the MCP server picker when someone builds a task.                |
| **URL**         | The server's MCP endpoint.                                                |
| **Description** | For your team — say what this server reaches and how far its access goes. |
| {% endstep %}   |                                                                           |

{% step %}
**Add authentication**

Choose the authentication `method` (e.g. `bearer token`) and enter the credential. Add any `headers` that should be sent with every request the agent makes.

{% hint style="info" %}
Credentials are encrypted and never shown to the agent — it only ever sees tool results.
{% endhint %}
{% endstep %}

{% step %}
**Test the connection**

Click `test`. Nothing is available to agents until the connection succeeds. A successful test shows the server as `reachable` along with the response time, protocol version, authentication result and the number of tools the server advertises.
{% endstep %}

{% step %}
**Choose which tools agents may use**

The `tools from this server` section lists every tool the server advertises. Switch on the ones agents may use — only enabled tools appear in the server picker when someone builds a task. Use `enable all` to switch them all on, or `re-discover` to refresh the list after the server changes.

{% hint style="warning" %}
Turning a tool off removes it from any task that's using it.
{% endhint %}
{% endstep %}

{% step %}
**Save**

Click `save changes`. The `used by` panel shows which agents and tasks use this server.
{% endstep %}
{% endstepper %}

When you edit a server later, changes apply the next time an agent calls one of its tools. Re-test the connection after editing it.

### Run history

Every agent run — scheduled, on request or triggered from a conversation — is recorded in run history. Select `AI Studio` > `run history`:

<div data-with-frame="true"><figure><img src="https://2440044887-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLYNcUBVQwSkOMG6KjZfz%2Fuploads%2FcLFnrytQBz9FR3p9BUpV%2Frun_history.png?alt=media&amp;token=e4a7e8d0-05b6-49bf-9e39-bb70b858e70d" alt=""><figcaption></figcaption></figure></div>

The summary cards show runs today, success rate, failed runs and median duration. Use the search field (agent name or run id), `filters` and the date range (`today`, `last 7 days`, `last 30 days` or `custom`) to narrow the list.

| Column          | Summary                                                                                                       |
| --------------- | ------------------------------------------------------------------------------------------------------------- |
| **Started**     | When the run started, with its run id.                                                                        |
| **Agent**       | The agent that ran.                                                                                           |
| **Trigger**     | `Schedule`, `Manual` (run now) or `Conversation`.                                                             |
| **Environment** | The virtual environment the run used.                                                                         |
| **Duration**    | How long the run took.                                                                                        |
| **Tokens**      | Total tokens used by the run.                                                                                 |
| **Status**      | `Succeeded`, `Failed` (with the task and error), `Halted` (stopped by a guardrail or run limit) or `Retried`. |

#### Viewing a run

Click a run to open its detail page:

<div data-with-frame="true"><figure><img src="https://2440044887-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLYNcUBVQwSkOMG6KjZfz%2Fuploads%2FG3xBdXg2btrWzwFRqBMe%2Frun_detail.png?alt=media&amp;token=d32cb628-63b1-478d-ad13-c4b61cd7bfe3" alt=""><figcaption></figcaption></figure></div>

The `task timeline` tab shows each task in order, with its tool calls, tokens, duration and status. Expand a task to see the tool it used, the instruction it was given, and the input and output for the step. The `raw log` tab shows the full underlying log.

The panel on the right shows the run context (run id, timings, environment, model and who or what initiated the run), a breakdown of token usage by task, and recent runs of the same agent so you can compare.

### Related information

* [AI Studio](https://doc.wearepatchworks.com/product-documentation/ai-studio)
* [Virtual environments](https://doc.wearepatchworks.com/product-documentation/virtual-environments/about-virtual-environments)
* [Flow deployment](https://doc.wearepatchworks.com/product-documentation/process-flows/managing-process-flows/flow-deployment)
* [Patchworks Core API](https://doc.wearepatchworks.com/product-documentation/developer-hub/patchworks-core-api)