# Connect Your Agent to n8n Workflows

> Connect your AI agent to n8n to trigger automation workflows, pass structured data and files, and ingest results — step by step in under 15 minutes.

Content type: documentation
Source URL: https://www.agentpmt.com/docs/tutorials/connect-agent-to-n8n
Markdown URL: https://www.agentpmt.com/docs/tutorials/connect-agent-to-n8n?format=agent-md
Category: Tutorials

---

# Connect Your Agent to n8n Workflows

n8n is a visual workflow automation platform used for multi-step automations across APIs, databases, and internal tools. The **n8n Workflow Connector** lets your AgentPMT agent list your n8n workflows, trigger them with structured data and file attachments, and ingest their output — all from a conversation.

By the end of this tutorial, you will have an active n8n workflow that your AgentPMT agent triggers with structured data, attaches files to, and reads results back from. You will also know how to monitor execution status and ingest any files the workflow produces.

> INFO: Tested
>
> Tested with n8n 1.x on n8n Cloud and self-hosted Docker; AgentPMT — April 2026.

---

## What You Will Need

- An **AgentPMT account with a connected agent** — follow [Sign Up And Connect Your Agent](/docs/getting-started/set-up-your-account) if you have not yet
- An **n8n account** — either a paid [n8n Cloud](https://n8n.io/cloud/) plan or a self-hosted instance with a public URL
- About **15 minutes**

---

## Step 1 — Getting Your n8n API Key

An n8n API key lets your AgentPMT agent authenticate REST API calls to your instance — listing workflows, reading execution history, and fetching workflow details. n8n issues API keys from its built-in settings UI with configurable expiration. Webhook triggering uses a separate URL with its own optional auth, so the API key alone is sufficient for most setups.

1. **Open n8n Settings**
   Log in to your n8n instance and click the **gear icon** or navigate to **Settings** in the sidebar.

2. **Go to n8n API**
   In the settings menu, click **n8n API**.

3. **Create an API Key**
   Click **Create an API key**. Give it a descriptive label like `AgentPMT Connector` and set an expiration date.

4. **Copy the key**
   Copy the API key immediately — **it will not be shown again**. Store it somewhere safe until you complete Step 3.

> WARNING: n8n Cloud free trial
>
> The n8n API is not available during the free trial on n8n Cloud. You need a Starter plan or higher. Self-hosted instances have full API access on the free Community Edition.

---

## Step 2 — Finding Your n8n Instance URL

Your instance URL is the base address of your n8n dashboard — the root of every API call and webhook URL your agent will make. n8n Cloud assigns one automatically when you sign up. Self-hosted instances need a publicly reachable domain configured via the `WEBHOOK_URL` environment variable so that outbound webhook URLs resolve correctly from the public internet.

| Deployment | Instance URL example |
|---|---|
| **n8n Cloud** | `https://yourname.app.n8n.cloud` |
| **Self-hosted** | `https://n8n.yourdomain.com` (whatever you configured) |

> INFO: Self-hosted reachability
>
> Your n8n instance must be publicly reachable over the internet. Localhost-only or firewall-gated instances cannot be contacted from AgentPMT.

---

## Step 3 — Connecting n8n in AgentPMT

AgentPMT injects your n8n credentials automatically at runtime so you never paste the API key into a chat. The platform encrypts both the API key and instance URL at rest and binds them to your budget and product. When your agent calls any connector action, AgentPMT pulls the credentials securely and signs the request — no further user action needed.

1. **Open the n8n Workflow Connector**
   Go to the [n8n Workflow Connector](/marketplace/69dc05bbb24df21a86b859af) in the AgentPMT marketplace and click **Add Tool**.

2. **Set up the connection**
   When prompted, enter your two credentials:

       - **API Key** — the key you created in Step 1
       - **Instance URL** — your n8n base URL from Step 2

3. **Save the connection**
   Click **Save**. AgentPMT encrypts the credentials and binds them to your budget. They are injected automatically whenever your agent uses the tool.

---

## Step 4 — Making Your Workflow Triggerable

n8n workflows can only be triggered externally through **Webhook nodes** — the public n8n REST API has no `execute workflow by ID` endpoint. Adding a Webhook node as the first trigger gives the workflow a URL your agent can call. The node configuration controls the HTTP method, the path slug, and whether the HTTP response waits for the workflow to finish or returns immediately.

1. **Open your workflow in n8n**
   Open the workflow you want your agent to trigger, or create a new one named `process-order` to follow along.

2. **Add a Webhook trigger**
   Click the **+** button and search for **Webhook**. Add it as the first node in your workflow.

3. **Configure the Webhook**
   In the Webhook node settings:

       - **HTTP Method** — set to **POST** so your agent can send JSON data
       - **Path** — enter a readable slug like `process-order`, or leave the default UUID
       - **Response Mode** — set to **When Last Node Finishes** so your agent gets the workflow output back

4. **Add your workflow logic**
   Connect whatever nodes you need after the Webhook — data transformation, API calls, database writes, notifications. The data your agent sends arrives in the Webhook node's output.

5. **Activate the workflow**
   Toggle the workflow to **Active** in the top-right corner. Only active workflows respond to production webhook calls.

> TIP: Accessing data inside n8n
>
> Data your agent sends arrives as the Webhook node output. Access it in downstream nodes with expressions like `$json.body.order_id` or `$json.body.customer_email`.

---

## Step 5 — Triggering Your Workflow

With a triggerable workflow active and credentials connected, your agent can list your workflows, discover webhook paths, and fire off a trigger call with structured data. The three-call flow — `list_workflows`, `get_workflow`, `trigger_workflow` — is the standard interaction pattern, and the connector auto-discovers webhook paths from the workflow definition so you never need to hand-copy URLs.

1. **Ask your agent to list workflows**
   ```text
       Show me my n8n workflows
       ```

       The agent calls `list_workflows` and returns a list with IDs, names, active status, and tags:

       ```json title="example response"
       {
         "action": "list_workflows",
         "workflows": [
           {
             "id": "h7SSBY2GM4fo9mqG",
             "name": "process-order",
             "active": true,
             "tags": []
           }
         ],
         "count": 1,
         "next_cursor": null
       }
       ```

2. **Discover the webhook path**
   ```text
       Get the details for workflow h7SSBY2GM4fo9mqG
       ```

       The agent calls `get_workflow`, parses the workflow JSON, and auto-extracts the Webhook node's path:

       ```json title="example response (truncated)"
       {
         "action": "get_workflow",
         "id": "h7SSBY2GM4fo9mqG",
         "name": "process-order",
         "active": true,
         "webhook_triggers": [
           {
             "node_name": "Webhook",
             "path": "process-order",
             "method": "POST",
             "response_mode": "lastNode"
           }
         ],
         "webhook_urls": [
           "https://yourname.app.n8n.cloud/webhook/process-order"
         ]
       }
       ```

3. **Trigger the workflow**
   ```text
       Trigger my process-order workflow with order_id "12345" and customer_email "user@example.com"
       ```

       The agent calls `trigger_workflow`, POSTs the JSON data to the webhook, and returns what your workflow produced:

       ```json title="example response"
       {
         "action": "trigger_workflow",
         "webhook_url": "https://yourname.app.n8n.cloud/webhook/process-order",
         "status_code": 200,
         "response": {
           "status": "processed",
           "order_id": "12345",
           "confirmation_sent": true
         }
       }
       ```

> TIP: Checking execution history
>
> Your agent can check execution status at any time by asking "show me the last 10 executions for workflow h7SSBY2GM4fo9mqG" or "show me all failed n8n executions". These call `list_executions` with optional status filters.

---

## Step 6 — Attaching Files From the File Manager

Your AgentPMT File Manager stores documents, images, and datasets your agent has generated or received. When triggering an n8n workflow, the connector can attach any File Manager file as a signed download URL embedded in the webhook payload under `_agentpmt_files`. The n8n workflow fetches the content via an HTTP Request node — keeping large files out of the webhook body itself.

1. **Ask your agent to trigger with an attachment**
   ```text
       Trigger my process-order workflow with order_id "12345" and attach file f7d2f9d5-2d45-4d41-9d84-0dd5f6de1234
       ```

       The agent resolves the File Manager file to a signed URL and includes it in the payload:

       ```json title="webhook payload sent to n8n"
       {
         "order_id": "12345",
         "_agentpmt_files": [
           {
             "file_id": "f7d2f9d5-2d45-4d41-9d84-0dd5f6de1234",
             "filename": "customer-order.pdf",
             "content_type": "application/pdf",
             "size_bytes": 48291,
             "download_url": "https://storage.googleapis.com/...",
             "expires_in_minutes": 60
           }
         ]
       }
       ```

2. **Download the file in n8n**
   In your n8n workflow, add an **HTTP Request** node after the Webhook node. Set the URL to the expression `{{ $json.body._agentpmt_files[0].download_url }}` and the response format to **File**. The downloaded content is now available as binary data for downstream nodes (Google Drive upload, OCR, email attachment, etc.).

---

## Step 7 — Ingesting Output Files Into the File Manager

When an n8n workflow produces file URLs in its output — generated reports, exported datasets, rendered images — your agent can automatically ingest them into the AgentPMT File Manager. The connector scans the execution output for downloadable URLs, pulls the content, and uploads it with a new `file_id` your agent can reference in follow-up tool calls.

1. **Ask your agent to get an execution with ingestion**
   ```text
       Get execution 456 and save any output files to my File Manager
       ```

       The agent calls `get_execution` with `ingest_output_urls: true`. Any file URLs it finds in the workflow output are downloaded and added to your File Manager:

       ```json title="example response (truncated)"
       {
         "action": "get_execution",
         "id": "456",
         "status": "success",
         "output": [
           {
             "report_url": "https://example.com/reports/q1-2026.pdf"
           }
         ],
         "ingested_files": [
           {
             "source_url": "https://example.com/reports/q1-2026.pdf",
             "file_id": "b94c8f2a-17de-4fa8-b3b8-2c9e0f1a5b42",
             "filename": "q1-2026.pdf",
             "size_bytes": 204819,
             "signed_url": "https://storage.googleapis.com/..."
           }
         ]
       }
       ```

2. **Use the new file_id**
   Your agent now has a File Manager `file_id` it can pass to any other AgentPMT tool — send it via email, attach it to a Telegram message, store it in a database, or feed it back into another n8n workflow.

---

## What is the difference between sync and async n8n workflows?

The difference is whether your agent waits for the n8n workflow to finish before continuing. Sync mode — Webhook response mode **When Last Node Finishes** — keeps the HTTP connection open and returns the workflow output directly, best for workflows under 60 seconds. Async mode — response mode **Immediately** — returns a 200 acknowledgment instantly while the workflow runs in the background; your agent polls `list_executions` or `get_execution` to retrieve results when the workflow finishes.

> INFO: Timeout
>
> The default webhook timeout is 60 seconds. For longer workflows, increase `webhook_timeout` up to 300 seconds in the trigger request, or switch to async mode.

---

## Troubleshooting

### 'n8n API key is invalid or expired'

Your API key may have expired or been revoked. Create a new one at **Settings > n8n API** and update the connection in AgentPMT.

### 'Failed to connect to n8n instance'

The instance URL is unreachable. Verify it is correct and publicly accessible. For self-hosted, confirm `WEBHOOK_URL` is set in your n8n environment and that inbound HTTPS traffic is allowed.

### 'This webhook is not registered for POST requests'

The Webhook node HTTP method is set to GET (or another method), but the agent sent POST. Open the Webhook node in n8n and change the method to POST, or explicitly set `webhook_method: "GET"` in the trigger call.

### Webhook returns 404

The workflow is not active. Toggle the workflow to **Active** in the top-right corner. Test webhook URLs (`/webhook-test/...`) only work while the editor is open — production needs an active workflow.

### 'Webhook request timed out'

The workflow ran longer than 60 seconds. Increase `webhook_timeout` up to 300 seconds in the trigger call, switch to async mode by setting `wait_for_result: false`, or optimize the workflow.

### Workflow triggers but returns empty result

The Webhook node response mode is set to **Immediately** — n8n returns a generic 200 acknowledgment instead of the workflow output. Change the response mode to **When Last Node Finishes** or add a **Respond to Webhook** node to control what gets returned.

---

## Frequently Asked Questions

### Does this work with self-hosted n8n Community Edition?

Yes. The n8n public REST API and webhook system are available on all editions, including the free self-hosted Community Edition. The only requirement is that your instance is publicly reachable from the internet. Localhost-only installations or instances behind a firewall without inbound rules cannot be contacted from AgentPMT.

### Do I need a paid n8n Cloud plan to use this connector?

Yes, for n8n Cloud users. The n8n public API is not available during the free trial on n8n Cloud — you need a Starter plan or higher for API key creation. Self-hosted Community Edition users have full API access for free.

### Can I trigger workflows that do not have a Webhook node?

No. n8n's public REST API has no endpoint to execute an arbitrary workflow by ID — Webhook nodes are the only supported external trigger. Any workflow you want your agent to trigger must have a Webhook as its first node. Existing cron-triggered or event-triggered workflows can be duplicated with a Webhook trigger added if needed.

### What happens if my workflow takes longer than 60 seconds?

Increase `webhook_timeout` in the trigger call up to 300 seconds, or switch the Webhook node's response mode to **Immediately** for async mode. In async mode, your agent gets an instant 200 and then polls `get_execution` or `list_executions` to retrieve results when the workflow finishes.

### Are my n8n credentials stored securely?

Yes. AgentPMT encrypts both your API key and instance URL at rest and injects them at runtime, scoped to your budget and product. Your agent never sees the raw credentials in a chat. See [How Credentials Work](/docs/core-concepts/how-credentials-work) for the full security model.

### Can I connect more than one n8n instance?

Each n8n Workflow Connector instance binds one API key and one instance URL. To use multiple n8n instances — for example, staging and production — add the connector as separate tool connections, each with its own credentials.

---

## Related Docs