Backup n8n Workflows to Gitea (So You Never Lose a Flow Again)

Imagine this: you finally perfect that beautiful n8n workflow that glues half your tech stack together. It runs like a dream, you feel like an automation wizard… and then an accidental delete, a broken instance, or a bad edit turns it into a distant memory. Rebuilding from scratch is not just annoying, it is the kind of repetitive task that automation was supposed to save you from.

This is where backing up your n8n workflows to Gitea comes in. With a simple n8n workflow template, you can automatically export all your workflows into a Gitea Git repository on a schedule. It checks what is already there, only updates files when something really changed, and keeps everything in neat JSON files that you can version, review, and restore whenever needed.

In other words: set it up once, let it quietly back up your automation brain, and stop worrying about “oops” moments.

Why back up n8n workflows to Gitea instead of “hoping for the best”?

Storing n8n workflows in a Gitea Git repository gives you all the good stuff developers enjoy, without you having to manually export anything every week.

• Version history for changes and rollbacks – See what changed, when, and by whom, and roll back if a “quick tweak” goes badly.
• Secure, centralized storage – Gitea is self-hosted, which means your workflow JSON lives in your own infrastructure, not on someone else’s laptop.
• Automated, scheduled snapshots – No more “I will export this later” promises that never happen. The workflow runs for you at a set interval.
• Easy collaboration and review – Use Git features like diffs, pull requests, and code review to track and discuss workflow changes.

So instead of manually exporting JSON files like it is 2009, you let n8n and Gitea do the boring work on repeat.

What this n8n backup workflow actually does

The template is a fully automated backup pipeline for your n8n instance. At a high level, it:

1. Runs on a schedule (for example, every 45 minutes).
2. Fetches all workflows from your n8n instance through the n8n API.
3. Loops through each workflow one by one.
4. Checks in Gitea if a JSON file already exists for that workflow.
5. If the file exists, it compares contents and only updates the file if something actually changed.
6. If the file does not exist, it creates a brand new JSON file in the repository.

The end result is a clean, versioned collection of .json files in Gitea that mirror your n8n workflows, updated on a schedule without you lifting a finger.

How the backup flow is structured (high-level logic)

Here is the general flow from start to finish:

1. Schedule Trigger wakes up the workflow at your chosen interval.
2. Globals stores handy variables like Gitea URL, repo owner, and repo name so you do not repeat them everywhere.
3. n8n API node fetches all workflows from your n8n instance.
4. splitInBatches / ForEach processes each workflow as an individual item.
5. GetGitea checks if the corresponding JSON file already exists in Gitea.
6. Exist (If node) branches into “file exists” or “file does not exist.”
7. Base64EncodeCreate / Base64EncodeUpdate encode the workflow JSON into base64, ready for the Gitea API.
8. Changed (If node) compares the new base64 content with what is already in the repo.
9. PostGitea creates new files, and PutGitea updates existing ones when there are actual changes.

It is basically a polite robot that checks “Do I need to change anything?” before touching your Git history.

Key n8n nodes in this template (and what they do)

Schedule Trigger: the “set and forget” starter

The Schedule Trigger node is what kicks off the backup at regular intervals. In the example template, it is configured to run every 45 minutes, but you can tweak that based on how often your workflows change and how much history you want.

You might choose:

• Every few minutes for very active environments.
• Once or twice a day for more stable setups.

Pick a schedule that matches your recovery needs and storage comfort level.

Globals: one place for all your Gitea settings

The Globals node keeps your repository details in one tidy location so you do not repeat them across nodes or risk typos.

It typically stores values like:

• repo.url – for example, https://git.example.com
• repo.owner – your Gitea user or organization
• repo.name – the repository where workflow backups are stored, such as workflows

These variables are then referenced by the HTTP request nodes that interact with Gitea.

n8n API node: collecting all your workflows

The n8n (API node) queries the n8n API to list all workflows in your instance. You will need to configure authentication, using either an API key or Basic Auth, so the node has permission to access workflow data.

This step is what turns “whatever is in n8n right now” into a list of items the rest of the workflow can process.

splitInBatches / ForEach: processing workflows one at a time

The splitInBatches and ForEach nodes take the list of workflows and handle them individually. This is useful for:

• Avoiding API rate limits.
• Handling errors gracefully without breaking the whole backup run.
• Keeping everything predictable and per-workflow.

Each workflow goes through the same “do you exist in Gitea yet?” check.

GetGitea: checking if a workflow file already exists

The GetGitea node calls the Gitea API to see if there is already a JSON file for the workflow.

GET /api/v1/repos/{owner}/{repo}/contents/{workflowName}.json

This node is configured to continue on error. That is important because a 404 from Gitea simply means “this file does not exist yet,” which is a perfectly normal situation for new workflows. Instead of failing, the workflow treats 404 as a signal to go down the “create file” path.

Exist (If node): deciding between create vs update

The Exist If node inspects the result from GetGitea. It checks whether the file is present or whether Gitea responded with an error like 404.

Based on that, it branches into:

• File exists – go to the “update” logic.
• File does not exist – go to the “create” logic.

That way, the workflow uses the same pattern for every workflow, but chooses the right Git action automatically.

Base64EncodeCreate and Base64EncodeUpdate: preparing JSON for Gitea

The Base64EncodeCreate and Base64EncodeUpdate nodes are Code nodes (using Python) that take the workflow object, format it nicely, and convert it to base64.

Gitea’s contents API expects file content to be base64-encoded, so this step is essential. The code follows a pattern like this:

# simplified steps used in the code nodes
json_string = json.dumps(workflow_object, indent=4)
json_bytes = json_string.encode('utf-8')
base64_string = base64.b64encode(json_bytes).decode('utf-8')

The result is a clean, human-readable JSON structure, encoded in a way Gitea understands.

Changed (If node): avoiding noisy commits

The Changed If node compares the newly encoded base64 content with the base64 content that is already stored in Gitea.

If the two match, nothing has changed in the workflow, so there is no reason to create a new commit. If they differ, the workflow proceeds to update the file using the PutGitea node.

This keeps your commit history from turning into a wall of “no-op” updates and makes it easier to see real changes.

PutGitea and PostGitea: writing files into Gitea

Finally, the PutGitea and PostGitea nodes talk to the Gitea API to create or update files.

• Create – use POST /api/v1/repos/{owner}/{repo}/contents/{name} to create a new file.
• Update – use PUT on the same endpoint, including the current file’s sha to tell Gitea which version you are updating.

Between these two, every workflow ends up with a matching JSON file in your repo, updated only when needed.

Authentication and security: making Gitea and n8n trust each other

To let n8n talk to Gitea securely, you will use a Personal Access Token (PAT) with repository read/write permissions.

Steps:

1. Create a Personal Access Token in Gitea with the necessary repo scopes.
2. Store this token as a credential in n8n, typically as an HTTP header credential.
3. Use that credential in your GetGitea, PostGitea, and PutGitea nodes.

In the HTTP header, use the following format:

Authorization: Bearer YOUR_PERSONAL_ACCESS_TOKEN

Pay attention to the space after Bearer. Forgetting that tiny space is a surprisingly common source of “why is this not working” frustration.

Configuration checklist (before you hit “activate”)

To get this n8n backup workflow template running smoothly, walk through this quick list:

• Set the Globals node values:
  • Gitea URL (for example, https://git.example.com)
  • Repository owner
  • Repository name (for example, workflows)
• Create a Gitea Personal Access Token with repository read/write permissions.
• Add that token to n8n credentials as an HTTP header credential.
• Make sure the n8n API node has permission to list workflows in your n8n instance.
• Assign the Gitea credential to:
  • GetGitea
  • PostGitea
  • PutGitea
• Run the workflow manually at least once before enabling the schedule.

Once everything checks out, you can hand the job off to the scheduler and focus on more interesting problems than “did I remember to export that workflow.”

Testing the backup workflow (before you trust it with your future)

1. Run it manually from within n8n and watch the execution logs to confirm each node behaves as expected.
2. Open your Gitea repository and verify that JSON files have been created for each workflow.
3. Edit one of your n8n workflows slightly, then run the backup workflow again to confirm that the update path triggers and the corresponding file is updated via PutGitea.
4. Once you are happy with the behavior, enable the Schedule Trigger to automate everything.

Troubleshooting and practical tips

404 on GetGitea

Seeing a 404 from the GetGitea node is not always a problem. In this context, it usually means:

• The JSON file for that workflow does not exist yet.

The workflow is intentionally built to treat 404 as “file not found, please create it” and then continue down the create path. As long as the node is set to continue on error, this is expected behavior.

Authorization errors that make no sense

If you are getting authorization errors from Gitea:

• Double check the Authorization header format:
  • It must be Bearer YOUR_PERSONAL_ACCESS_TOKEN with a space after Bearer.
• Confirm that the token has the correct repository scopes.
• Verify that you pasted the token into the right credential field in n8n.

Most auth issues come down to a small formatting mistake or missing permission.

Large workflow files and repo limits

If your workflows are huge (lots of nodes, heavy data), keep in mind that Gitea can have file size limits depending on how your server is configured.

In those cases, you might consider:

• Compressing older snapshots.
• Storing bulk archives as release artifacts instead of individual content files.

For normal sized workflows, the template should work just fine out of the box.

Keeping Git history clean

The workflow’s comparison step using base64 content is there to avoid unnecessary commits. If nothing changed in a workflow, the file stays untouched and your commit history stays readable instead of “backed up again, nothing changed” on repeat.

File naming strategy for workflow backups

By default, a simple and predictable naming scheme keeps things organized. A common approach is:

{workflowName}.json

If you have workflows with the same name across multiple environments, you can prevent collisions by including extra details, for example:

• prod_ping_check_12345.json

Using environment names or workflow IDs in the file name makes it easier to tell them apart at a glance.

Next steps: turn on the automation and relax

Once this backup workflow is in place, your n8n setup becomes much safer and easier to manage. You get:

• Versioned, auditable backups in your self-hosted Gitea server.
• A repeatable pattern: fetch workflows, check repo state, encode, compare, and create or update only when needed.
• Less manual exporting, more time for building new automations.

To recap your action plan:

• Import or open the template in n8n.
• Configure your Gitea URL, repo owner, and repo name in the Globals node.
• Set up and secure your Personal Access Token.
• Test the workflow manually and verify JSON files in Gitea.
• Enable the schedule so backups run automatically.

If you want a downloadable workflow JSON

Build an n8n Developer Agent: Step-by-Step Guide

Imagine turning a rough idea for an automation into a working n8n workflow in just a few minutes. No more staring at blank canvases, wiring nodes from scratch, or rewriting the same patterns again and again. With the right setup, you can describe what you want in plain language and let an “n8n Developer Agent” design the workflow for you.

This guide walks you through that journey. You will move from manual, repetitive workflow building to a more focused, automated way of working. Along the way, you will see how this n8n workflow template can become a powerful stepping stone toward a more scalable, efficient, and creative automation practice.

From manual workflows to an automation mindset

Most teams, consultants, and developers start with n8n the same way: opening the editor, dragging in nodes, testing, adjusting, and repeating. It works, but it does not always scale. As requests pile up, you might notice:

• Time lost building similar workflows from scratch
• Inconsistent naming or structure across workflows
• Colleagues who want automations but lack deep n8n knowledge
• Difficulty maintaining or reusing patterns at scale

The opportunity is not just to go faster. It is to change how you think about building automations. Instead of “I have to build this workflow,” you can shift to “I will describe what I need, and my system will build the first version for me.”

The n8n Developer Agent pattern helps you make that shift. It gives you a reliable way to convert natural language requests into importable n8n workflow JSON, so you can spend more time refining and less time wiring the basics.

What is the n8n Developer Agent?

The n8n Developer Agent is an automation pattern built around a single idea: you describe the automation, and the system generates the workflow.

Technically, it is a workflow that combines:

• A trigger (such as a chat interface or an execute-workflow trigger)
• A main agent node powered by a language model
• Optional “thinker” models for deeper reasoning
• A Developer Tool that produces valid n8n workflow JSON
• The n8n API to create workflows directly in your instance
• Supporting services like Google Drive and memory utilities

For example, you might say: “Create a workflow that listens for new Google Drive files and posts a summary to Slack.” The Developer Agent interprets the request, chooses the right nodes, assembles the connections, and outputs a complete workflow JSON that you can import or have created automatically.

In practice, this means you can go from idea to runnable workflow in minutes, while still keeping control over standards, safety, and governance.

Why this pattern is worth adopting

When you invest a bit of time in setting up an n8n Developer Agent, you unlock benefits that compound over time:

• Speed: Turn ideas into runnable workflows in minutes instead of hours.
• Consistency: Apply naming conventions and node standards automatically.
• Scalability: Let non-experts request workflows without needing deep n8n skills.
• Repeatability: Build and refine a growing library of generated workflows.

Each new request becomes less about manual construction and more about guiding and improving a system that works for you. The template in this guide is not just a one-off workflow, it is a foundation you can extend, customize, and govern as your automation needs grow.

How the n8n Developer Agent works behind the scenes

To feel confident using and extending this pattern, it helps to understand how the core components interact. At a high level, the template is made of these logical parts, each represented by one or more n8n nodes:

• Trigger: A chat input, webhook, or execute-workflow trigger that starts the process.
• Main agent: A chat or agent node that receives the user request and orchestrates tools and models.
• Language models: A primary LLM (for example OpenRouter / GPT 4.1 mini) and an optional thinker model (such as Claude Opus 4) for multi-step reasoning.
• Developer Tool: A sub-workflow or node that turns the natural language prompt into valid n8n workflow JSON, including nodes, connections, and settings.
• n8n API node: A node that creates the new workflow in your n8n instance and returns a link to it.
• Supporting services: Google Drive for docs and templates, extract-from-file utilities, and memory buffers to retain conversational state.

Together, these components form a pipeline: from a human-friendly prompt to a machine-usable workflow definition, and finally to a live workflow ready for review and execution.

What you need before you start

Before you begin configuring the template, make sure you have:

• An n8n instance with API access and credentials set up
• API keys for your chosen LLM providers (for example OpenRouter, and Anthropic if you plan to use Claude Opus)
• Access to Google Drive if you want to use documents as templates or references
• Basic familiarity with n8n nodes and importing workflows

With these in place, you are ready to turn the template into a working n8n Developer Agent that fits your environment.

Step-by-step: turning the template into your Developer Agent

1. Decide how people will talk to the agent

Your first choice is how users will trigger the Developer Agent. This decision shapes how accessible and secure the system will be:

• For quick experiments: Use a chat trigger or manual execution. This keeps the feedback loop tight while you learn.
• For production use: Consider a secure, authenticated webhook or an internal tool interface that only approved users can access.

Start simple. You can always upgrade the trigger later as adoption grows.

2. Connect and configure your primary LLM

The main agent node is the brain of the Developer Agent. Connect your OpenRouter (or other LLM) API key to the chat or agent node that will handle user prompts.

Then, carefully design the system prompt. This is where you set expectations for the model. Be clear that the agent must:

• Output a complete, importable n8n workflow JSON
• Follow a specific JSON schema that your Developer Tool expects
• Respect any naming conventions or structural rules you want to enforce

A precise system prompt reduces ambiguity and leads to more reliable workflows on the first try.

3. Add an optional thinker model for deeper reasoning

If your workflows tend to be complex or multi-step, you can enhance the main agent with a secondary “thinker” model such as Claude Opus 4. This model does not replace the primary LLM, it supports it.

Use the thinker model to:

• Refine the architecture of the workflow
• Check compatibility between nodes
• Plan multi-step logic before the final JSON is generated

The main agent can consult this reasoning assistant, then translate the refined plan into the final workflow JSON. This is optional, but powerful when you want higher quality on more advanced automations.

4. Link or build the Developer Tool

The Developer Tool is where your natural language request becomes a real n8n workflow object. It constructs the JSON with top-level properties such as:

• name
• nodes
• connections
• settings
• staticData

To keep it robust and reliable, design the Developer Tool to:

• Break the user request into logical steps
• Choose appropriate nodes, for example Webhook, Google Drive, HTTP Request, Function, Set, and others as needed
• Produce a fully valid JSON object that n8n can import or your API can accept

A best practice is to require the Developer Tool to return only the JSON, with no commentary or extra text. Then, add a validation step before sending it to the n8n API node. This combination gives you both flexibility and control.

5. Create the workflow through the n8n API

Once the JSON is ready and validated, the next step is to create the workflow in your n8n instance using the n8n API node.

Configure the node with your n8n API credentials and use it to POST the workflow JSON to your instance. After a successful request, capture the workflow ID from the response and build a direct link for the user.

This gives people a smooth experience: they describe the workflow, then immediately receive a clickable link to review, test, or edit the result.

6. Use Google Drive and file extraction as your knowledge base

As you mature your Developer Agent, you can feed it more context about your standards. If you keep templates or documentation in Google Drive, connect:

• A Google Drive node to fetch the relevant document
• An extract-from-file node to convert the file into plain text

The agent can then reference this text to:

• Enforce naming conventions
• Follow internal standards for error handling or logging
• Reuse approved patterns across new workflows

This turns your existing documentation into a live guide that shapes each generated workflow.

Keeping your Developer Agent safe, stable, and trustworthy

As you rely more on automated workflow generation, good safeguards become essential. Build these into your template from the start so you can scale with confidence.

Validation and safety best practices

• JSON validation: Always validate the JSON before creating a workflow. Check the nodes array, connections object, and top-level settings to avoid malformed imports.
• Credential placeholders: Never embed real credentials in generated workflows. Use placeholders and add production credentials manually afterward.
• Access control: Restrict who can request workflows. Secure your chat or webhook triggers with authentication or internal-only access.
• Audit trail: Store generated workflows and request metadata in a database or drive so you can review, roll back, or learn from past generations.
• Rate limits and cost management: Monitor LLM usage, apply sensible rate limits, and keep an eye on cost as adoption grows.

Troubleshooting common issues

As you experiment, you might run into a few predictable problems. Use these quick checks to stay in flow:

• Workflow fails to import: Inspect the JSON for missing commas, duplicate node IDs, or invalid node types.
• API errors when creating workflows: Confirm that your n8n API key has the right permissions and that the instance URL is correct and reachable.
• Inconsistent outputs: Tighten the Developer Tool’s constraints. Provide explicit node lists and fixed parameter templates to reduce unnecessary creativity from the LLM.

Each issue you solve makes your Developer Agent more robust. Over time, you build not just a workflow, but a reliable automation partner.

Growing into team-wide automation: scaling and governance

Once the Developer Agent proves valuable for you, it is natural to share it with your team. At that point, governance becomes key. You can extend the template with structures that keep quality high as usage grows.

• Approval workflow: Have generated workflows stored as drafts that require human approval before going into production.
• Template library: Maintain a curated set of approved templates for common use cases such as file processing, CRM sync, or Slack notifications.
• Monitoring and observability: Connect your workflows to logging and alerting systems so you can track failures and performance metrics.

This is where the Developer Agent evolves from a personal helper into a shared automation platform that supports your entire organization.

Quick reference: who does what in the template

As you work with the template and customize it, this quick reference can help you keep each node’s role clear:

• Chat trigger / Execute Workflow trigger: Accepts user input and starts the pipeline.
• Main agent node: Orchestrates LLM calls and tools, and composes system prompts.
• Developer Tool node: Returns the final n8n workflow JSON object ready to import.
• n8n API node: Creates the workflow in your n8n instance and provides a direct link.
• Memory and sticky notes: Store conversational context and human-facing setup instructions.

Once you are familiar with these responsibilities, adjusting or extending the template becomes much easier.

Your next step: start small, then expand

The n8n Developer Agent pattern is powerful, but you do not need to implement everything at once. The most important step is the first one: getting a basic version running so you can see the impact for yourself.

Here is a simple path to follow:

1. Spin up a sandbox n8n instance where you can experiment safely.
2. Connect a single LLM provider via the main agent node.
3. Set up a simple trigger, such as a chat trigger or manual execution.
4. Run a basic prompt like “Create a workflow that watches a Google Drive folder and emails new file details.”
5. Review the generated workflow, refine your prompts and validation, and repeat.

As your confidence grows, you can layer in more features: templates from Google Drive, approval gates, stronger validation, and team-level access controls.

Ready to try it? Use the workflow template included with this guide as your starting point. Import it, connect your credentials, and begin shaping an automation system that builds workflows for you.

Get the template & request expert help

If you would like a customized workflow tailored to your exact use case, reach out. We can convert your specification into a validated n8n workflow JSON that is ready to import and run, so you can focus on strategy while your automations handle the execution.

How One Automation Failure Pushed Alex To Back Up n8n Workflows To Gitea

Alex stared at the n8n dashboard, heart sinking. A production workflow that handled hundreds of customer records had vanished after a misconfigured update. No JSON export, no backup, no Git history. Just an empty space where a mission-critical workflow used to be.

Like many developers and automation builders, Alex always meant to set up a proper backup strategy “later.” Now, with stakeholders asking what went wrong, “later” had arrived.

This is the story of how Alex discovered an automated n8n workflow template that backs up every workflow to a Gitea repository, keeps a versioned history, and only commits when something actually changes. By the end, Alex had a safe, auditable backup system that quietly ran in the background, and never had to fear losing another workflow again.

The Problem: Fragile Automations Without a Safety Net

Alex was responsible for maintaining dozens of n8n workflows. Some synced data between tools, others triggered customer notifications, and a few glued together critical backend processes. Everything worked, until it did not.

One day, a small change to the n8n instance caused a workflow to corrupt and disappear. Alex had no recent export and no Git history to roll back to. Rebuilding from memory took hours, and Alex knew this was a warning shot.

Alex wrote down the real pain points:

• No versioned, auditable history of workflow changes.
• No easy way to recover lost or corrupted workflows.
• Backups were ad hoc, manual exports that never happened on time.
• No integration with the team’s Git-based backup strategy.

Alex needed an automated way to back up every n8n workflow into Git, preferably into the team’s self-hosted Gitea instance. It had to be scheduled, reliable, and smart enough not to spam the repo with useless commits.

The Discovery: An n8n Template That Talks To Gitea

After some searching, Alex found exactly what was needed: an n8n workflow template built to back up workflows into a Gitea repository through the Gitea API. No extra scripts, no external cron jobs, just n8n talking directly to Gitea.

The template promised to:

• Export all workflows from the n8n instance.
• Check if each workflow already exists as a JSON file in Gitea.
• Pretty-print and Base64-encode the JSON content.
• Compare with the existing file in Gitea to detect changes.
• Create or update files only when something actually changed.
• Run automatically on a schedule.

It sounded perfect. But Alex knew that templates only help if they are configured correctly. So the real journey started: wiring up n8n, Gitea, and the template into a smooth, automated backup pipeline.

Rising Action: Wiring Up Gitea And n8n

Step 1 – Preparing Gitea: The Backup Home

First, Alex needed a place to store the backups. That meant setting up a dedicated repository in Gitea.

• Alex created a repository named workflows in Gitea.
• Under Settings → Applications, Alex generated a Personal Access Token.
• The token was granted repository read and write permissions, but nothing more, to keep the blast radius small.

Inside n8n, Alex added a new HTTP header credential for Gitea that looked like this:

• Header name: Authorization
• Header value: Bearer YOUR_PERSONAL_ACCESS_TOKEN

Alex double checked that there was a space after Bearer. Missing that space is a classic cause of 401 errors.

Step 2 – Setting Global Repo Details In n8n

The template included a Globals node, which acts as a small configuration hub. Instead of hardcoding URLs and repo names in multiple places, Alex could define them once.

In the Globals node, Alex filled in:

• repo.url – for example https://git.example.com, the Gitea base URL.
• repo.owner – the user or organization that owns the repo.
• repo.name – in this case workflows.

With this, any node that needed to call Gitea could reuse these values. Less duplication, fewer mistakes.

Step 3 – Giving n8n Permission To Read Its Own Workflows

The whole point of this template was to export workflows from n8n itself. That required an authenticated n8n API node.

Alex configured the n8n API node with the appropriate authentication:

• Either an API token or Basic Auth.
• Enough permission to list and export all workflow objects.

Once configured, the node could fetch all workflows from the instance. The template would then iterate over each one and back it up to Gitea.

The Engine: How The Workflow Template Actually Works

Curious about what was happening under the hood, Alex walked through the main nodes in the template. Understanding the flow would make troubleshooting and tweaking much easier.

Controlling Time: The Schedule Trigger

At the top of the workflow sat the Schedule Trigger node. It controlled how often backups would run.

Alex set it to run every 45 minutes, but any interval could work, from hourly to once a day, depending on how frequently workflows change.

Fetching Workflows: The n8n API Node

Next, the n8n (API) node pulled in all workflows from the n8n instance. It returned a list of workflow objects, each containing the JSON definition that needed to be backed up.

Scaling Safely: ForEach And splitInBatches

Since Alex’s instance had a growing number of workflows, processing them all at once could lead to memory spikes or API throttling. The template solved this by using a combination of ForEach and splitInBatches nodes.

These nodes:

• Iterate over each workflow item individually or in small batches.
• Prevent overloading the system with too many operations at once.

This design choice meant the template would scale gracefully as the number of workflows grew.

Talking To Gitea: Get, Post, And Put

For each workflow, the template needed to know whether a corresponding JSON file already existed in Gitea. That is where the Gitea API nodes came in.

• GetGitea used an HTTP GET to check for an existing file:

GET /api/v1/repos/{owner}/{repo}/contents/{path}

If the file existed, Gitea returned its metadata and Base64-encoded content. If it did not, the API responded with a 404, which the workflow treated as a signal to create a new file.

• PostGitea created new files:

POST /api/v1/repos/{owner}/{repo}/contents/{path}

• PutGitea updated existing files:

PUT /api/v1/repos/{owner}/{repo}/contents/{path}

These nodes all hit the same Gitea REST API, but with different HTTP methods. The workflow passed parameters like:

• content – Base64-encoded JSON.
• message – the commit message.
• branch – usually main or a dedicated backup branch.
• sha – required for updates, taken from the GET response.

The Smart Part: Change Detection With Base64

Alex did not want a new commit every time the schedule ran if nothing had changed. That would clutter the Git history and make it harder to spot real changes.

The template solved this with a simple but effective approach:

• First, it pretty-printed the workflow JSON to keep formatting consistent.
• Then it used Base64EncodeCreate and Base64EncodeUpdate nodes to encode the JSON into Base64, which is what Gitea expects.
• Next, the Changed IF node compared the encoded content from n8n with the encoded content returned from Gitea.
• If the values matched, the workflow skipped any update. No commit was made.
• If the values differed, the workflow sent a PUT request using PutGitea, including the current file sha to update the file.
• If the file did not exist at all (404 from GetGitea), the workflow used PostGitea to create it.

This logic meant that the repo only recorded meaningful changes, keeping history clean and storage efficient.

The Turning Point: First Successful Backup Run

After wiring everything up, Alex was both excited and nervous. It was time to test.

Template Bodies For Gitea Requests

Alex inspected the request bodies used to create and update files, to be sure nothing was missing.

For new files, the template used a body like this:

{  "content": "BASE64_ENCODED_CONTENT",  "message": "Add workflow: My Workflow",  "branch": "main"
}

For updates, the body included the existing sha so Gitea knew which version to update:

{  "content": "BASE64_ENCODED_CONTENT",  "sha": "EXISTING_FILE_SHA",  "message": "Update workflow: My Workflow",  "branch": "main"
}

Everything looked correct. Alex hit the manual run button in n8n.

After a few seconds, the Gitea repo started to fill with JSON files, one per workflow. Commit messages showed which workflows were added. On the next manual run, no new commits appeared, confirming that the change detection logic was working perfectly.

For the first time, Alex had a reliable, automated backup of every n8n workflow, safely versioned in Git.

Refining The Setup: Best Practices Alex Adopted

Once the basic backup pipeline was running, Alex started to refine it using some best practices.

• Dedicated token – Alex used a dedicated Personal Access Token with minimal permissions, restricted to the backup repository where possible.
• Informative commit messages – The commit messages were updated to include timestamps, workflow IDs, and sometimes the author, making the Git history more useful.
• Separate backup branch – To keep production branches clean, Alex configured the workflow to commit to a dedicated backup branch.
• Secret storage – Tokens were stored as n8n credentials, never hardcoded in nodes or visible in logs.
• Error handling and retries – Alex added basic error handling and backoff in case of API rate limits or transient network issues.
• Large instances – With many workflows, splitInBatches ensured that backups stayed stable and did not cause spikes.
• Testing before scheduling – Alex always ran the workflow manually and inspected the Gitea repo before enabling the schedule trigger.

When Things Go Wrong: Troubleshooting Lessons

Not everything worked perfectly on the first try. Alex hit a few common issues that are worth knowing about.

• 401 Unauthorized – The culprit was usually the Authorization header. Either the token was wrong, or there was no space after Bearer. Fixing the header and verifying token permissions solved it.
• 404 Not Found from GetGitea – At first this looked like an error, but it was actually expected for new workflows. The template treated 404 as a signal that the file did not exist yet and should be created.
• Encoding mismatches – If the workflow kept committing on every run, it often meant the JSON was not consistently pretty-printed before encoding. Once Alex ensured that formatting was stable, comparisons became reliable.
• Missing SHA on PUT – Gitea requires the correct sha value when updating a file. If PUT failed, it usually meant the workflow was not passing the sha from the GET response correctly. Fixing that field resolved the issue.

Security Considerations Alex Did Not Ignore

Because this setup involves tokens and repository access, Alex took security seriously:

• Tokens were stored in n8n credentials, never in plain text fields.
• Logs were checked to ensure no tokens were accidentally printed.
• Tokens were rotated periodically as part of regular security hygiene.
• Scopes and repository access were kept as narrow as possible.

This way, even if something went wrong, the potential damage was limited.

The Resolution: Peace Of Mind With Automated n8n Backups

Weeks after setting up the backup workflow, another teammate accidentally broke a production workflow. This time, Alex did not panic.

Instead, Alex opened the Gitea repository, browsed to the correct JSON file, and restored the previous version. Within minutes, the workflow was back in n8n, running as if nothing had happened.

The automated backup template had quietly done its job, exporting workflows, encoding them, checking for changes, and only committing when something was different. The Git history told a clear story of how workflows evolved over time.

Alex also started to build on top of this foundation:

• Adding commit metadata such as timestamps or “exported by” information to messages.
• Pushing backups to a secondary remote or mirror for extra redundancy.
• Using notification nodes like Slack or Email to alert the team when new backups or updates were created.

To keep environments clean, Alex followed one last pro tip: maintain a separate backup repository for each environment (dev, stage, prod) so workflow changes can be tracked independently.

Your Turn: Put A Safety Net Under Your n8n Workflows

If you are where Alex once was, relying on manual exports or no backups at all, you do not have to stay there.

With this n8n template, you can:

• Automatically back up all n8n workflows to a Gitea repository.
• Use the Gitea API to create and update JSON files on a schedule.
• Keep a clean, versioned history of your automations.
• Recover quickly when something breaks or disappears.

All it takes is importing the template, configuring your Gitea credentials and repository details, running a manual test, and then enabling the schedule.

If you run into questions, share your setup on the n8n community forum or talk to your platform admin. There is no need to wait for a painful incident before putting a safety net under your automations.

n8n AI Agent: Code Tool for Random Color Selection

On a late Tuesday afternoon, Maya, a marketing automation specialist, stared at yet another confusing chatbot transcript.

The bot had replied, “I suggest the color green” right after the user clearly wrote, “Anything but green or blue, please.”

Maya sighed. She had wired a powerful OpenAI chat model into her n8n workflows, but every time she asked it to make a simple, deterministic choice, it occasionally ignored rules, hallucinated options, or gave inconsistent answers. All she wanted was a predictable way to select a random color while excluding certain colors, and to do it as part of a friendly, conversational chatbot.

That small problem turned into a bigger question: how could she combine the flexibility of AI with the reliability of code inside n8n?

The problem: powerful AI, unreliable logic

Maya’s team was building an interactive color picker experience for their website. Visitors could type messages like:

• “Give me a random color, but not green or blue.”
• “Pick a bright color that is not black or brown.”

The OpenAI chat model handled natural language beautifully. It understood what users meant, but when it came to actually choosing a color and respecting exclusions, it sometimes slipped. A language model is not optimized for strict logic, and Maya needed:

• Predictable, reproducible results every time.
• A simple way to test and debug the selection logic.
• Less risk of the model “inventing” options that were not allowed.

She wanted AI to understand what the user was asking, but she wanted code to make the final decision.

The discovery: an n8n AI Agent with a Code Tool

While exploring n8n’s documentation, Maya found exactly what she needed: the n8n AI Agent node, combined with a custom Code Tool. The idea was simple but powerful:

• Let the AI Agent handle the conversation and interpret user intent.
• Let a JavaScript Code Tool handle the deterministic logic of filtering and randomly selecting a color.

This pattern meant she could keep the “brain” of the interaction in the AI model while delegating strict rules to code she fully controlled. It was also reusable for many other automation tasks, not just colors.

How Maya’s workflow came together

Maya opened n8n and started sketching her workflow. Instead of thinking in isolated nodes, she imagined the conversation flow:

1. A user sends a chat message, or she tests the workflow manually.
2. The AI Agent reads the message, understands which colors to exclude, and decides to call a custom tool.
3. The Code Tool receives the list of colors to ignore, runs a clean JavaScript function, and returns one random color.
4. The AI Agent wraps that result into a friendly response and sends it back to the user or the next workflow step.

To make that happen, she added the following nodes:

• When clicking ‘Test workflow’ – a manual trigger for local testing.
• When chat message received – a webhook or chat trigger to receive live messages from users.
• Debug Input – a Set node to simulate chat input during development.
• AI Agent – the orchestrator that uses a chat model and can call tools.
• OpenAI Chat Model – the language model (for example, gpt-4o-mini) that understands user messages.
• Code Tool (my_color_selector) – the JavaScript function that returns a random color while excluding specified colors.

The heart of the story: the my_color_selector Code Tool

The key to making the workflow reliable was the Code Tool. Maya created a new n8n Code Tool node, set its Tool Type to Code, and named it my_color_selector. Inside, she pasted the following JavaScript:

const colors = [  'red',  'green',  'blue',  'yellow',  'pink',  'white',  'black',  'orange',  'brown',
];

const ignoreColors = query.split(',').map((text) => text.trim());

// remove all the colors that should be ignored
const availableColors = colors.filter((color) => {  return !ignoreColors.includes(color);
});

// Select a random color
return availableColors[Math.floor(Math.random() * availableColors.length)];

She liked how transparent this logic was. No guessing, no hidden behavior. Just a clear sequence:

• colors – the base list of allowed colors.
• ignoreColors – the colors to exclude, parsed from the incoming query string and trimmed.
• availableColors – the filtered list after removing ignored colors.
• Return – a single random color from the remaining options.

In the AI Agent configuration, she attached this Code Tool so the agent could call it whenever a user asked for a color with exclusions. The tool’s input would be a simple string, for example "green, blue", representing the colors to ignore.

Rising action: wiring the AI and automation together

With the core logic in place, Maya focused on the full workflow. She wanted to test quickly, iterate safely, and then go live.

1. Setting up triggers for testing and chat

First, she added two different entry points:

• Manual trigger using When clicking ‘Test workflow’ so she could run the flow from the editor.
• Chat trigger using When chat message received to handle real-time messages from users via a webhook or chat integration.

This gave her a smooth path from development to production. She could iterate with the manual trigger, then switch to the chat trigger when ready.

2. Creating the Debug Input

Next, she added a Set node called Debug Input. During development, this node would simulate what a user might say. For example, she defined a simple field like:

Return a random color but not green or blue

She mapped this field to the AI Agent’s input parameter, which she called something like chatInput. This way, each time she clicked “Test workflow,” the AI Agent would receive the same test message and she could see exactly how the flow behaved.

3. Configuring the AI Agent

Now came the orchestration layer. In the AI Agent node, Maya:

• Set the promptType to an appropriate value for her use case, for example define.
• Connected the AI Agent’s Chat Model input to an OpenAI Chat Model node.
• Attached the my_color_selector Code Tool so the agent could call it as needed.

The AI Agent’s role was to analyze the text, decide when the Code Tool should run, pass the right input string (like "green, blue"), and then format the final answer in natural language.

4. Adding and tuning the OpenAI Chat Model

In the OpenAI Chat Model node, she:

• Provided her OpenAI credentials.
• Selected the model gpt-4o-mini as a compact yet capable choice.
• Configured options like temperature and max tokens to match the tone and length she wanted.

The model did not need to generate long essays. Its main job was to understand queries like “anything except green or blue” and to converse around the tool’s output.

5. Connecting the Code Tool

Finally, she made sure the AI Agent was configured to call my_color_selector whenever the user requested a random color with exclusions. The tool expected a comma-separated string of colors to ignore, so the agent would pass something like "green, blue" after parsing the user’s message.

At this point, the workflow chain was complete: trigger, debug input or chat, AI Agent, chat model, Code Tool, and back again.

The turning point: testing the workflow

With everything wired up, Maya clicked “Test workflow”.

The flow started at the manual trigger, moved to Debug Input, and sent the text “Return a random color but not green or blue” to the AI Agent.

Behind the scenes, the AI Agent:

1. Parsed the message and identified that “green” and “blue” should be excluded.
2. Called the my_color_selector Code Tool with the input "green, blue".
3. Received a random color from the tool, for example "red".
4. Wrapped that result into a friendly response and passed it on to the next node or back to the chat trigger.

On her screen, Maya saw an answer like:

“Your random color is red.”

She ran the test again. The workflow returned a different allowed color, but never green or blue. The behavior was now both conversational and deterministic, exactly what she needed.

Making the workflow robust: edge cases and improvements

Once the basic flow worked, Maya started thinking like a production engineer. What could go wrong, and how could she harden the system?

• Input validation She added checks to ensure the query string passed to the Code Tool was defined and not empty before splitting it. This avoided unexpected errors when the AI Agent did not need to exclude any colors.
• Case normalization To avoid mismatches like “Blue” vs “blue,” she considered lower-casing the input before splitting and comparing, so user capitalization would not break the logic.
• Fallback handling She planned for the scenario where a user excluded every available color. In that case, the Code Tool could return a friendly error or a default list instead of failing silently.
• Extended logic Over time, she could expand the Code Tool to handle categories like warm or cool colors, prioritize colors that had not been used recently, or even implement weighted probabilities.
• Security and safety She made sure any inputs were sanitized, and that no secrets or API keys were exposed in logs or responses.

These small improvements turned a demo into a production-ready workflow.

Best practices Maya learned about AI and code tools

Building this workflow taught Maya a broader lesson about combining AI and deterministic code inside n8n:

• Keep strict logic in your Code Tools, and use the AI Agent for language understanding and orchestration.
• Limit the model’s role in computations or rule-based decisions to avoid inconsistent outputs.
• Monitor and log tool calls so you can track failures and unusual inputs.
• Use environment variables and secure credentials for any API keys or secrets.

This separation of concerns gave her the best of both worlds: predictable code and flexible AI.

Beyond colors: how the same pattern scales

After the success of the color picker, Maya started seeing this pattern everywhere. The combination of an n8n AI Agent with a Code Tool was not just about colors. It was a reusable blueprint for AI-driven automation with deterministic decision steps.

She could apply the same structure to:

• Product recommendation filters Let the AI understand user preferences, then use a Code Tool to exclude out-of-stock items and select a product.
• Appointment scheduling Have the AI interpret natural language like “next Tuesday afternoon,” then let code select the next available slot while excluding conflicts.
• Content generation pipelines Use AI to draft content, then run deterministic checks or filters in a Code Tool before publishing.
• Chatbots with utility scripts Allow the AI Agent to call microservices or utility scripts for calculations, lookups, or other strict logic.

What started as a “random color” experiment became a foundation for more advanced, reliable automations.

Resolution: from frustration to a reliable n8n AI workflow

The next time Maya checked the chatbot transcripts, she smiled. Users were asking for “anything but green or blue,” and the bot was respecting their preferences every time. The AI Agent handled the conversation, the Code Tool handled the logic, and the workflow was both smart and trustworthy.

If you want to follow the same path, you can replicate Maya’s setup inside your own n8n instance:

1. Import or create the workflow with:
   • When clicking ‘Test workflow’ and/or When chat message received triggers.
   • A Debug Input Set node for easy testing.
   • An AI Agent node connected to an OpenAI Chat Model (for example gpt-4o-mini).
   • A Code Tool node named my_color_selector with the JavaScript shown above.
2. Set your OpenAI credentials and adjust model settings like temperature and max tokens.
3. Attach the my_color_selector tool to the AI Agent and pass a comma-separated string of colors to exclude.
4. Click “Test workflow” and watch the AI Agent call the Code Tool and return a valid random color.

You can keep the color list as is, or replace it with domain-specific data that fits your product, schedule, or content.

Next steps: build your own AI + code automations

Using the n8n AI Agent with a Code Tool is a practical way to blend conversational AI with strict, testable logic. Start with a simple example like my_color_selector, then evolve your tools as your automation needs grow.

Try it now: Import the template into n8n, configure your OpenAI credentials, paste the Code Tool JavaScript, and run a test. Then adapt the logic to your own use case, whether that is product selection, scheduling, or content workflows.

Stay in the loop

If this story helped you see how n8n, AI Agents, and Code Tools can work together, consider subscribing for more guides on n8n automation and AI integrations. If you would like help designing or scaling a custom workflow, reach out or leave a comment. We can walk through setup, performance tuning, and best practices tailored to your stack.

Research Agent Demo – n8n + LangChain Workflow

On a rainy Tuesday afternoon, Lena, a content strategist at a fast-growing startup, stared at her screen in frustration. Her editor had just pinged her again: “Can you get me 3 solid articles about the election for tomorrow’s briefing?”

It was not a hard request, but it was the tenth one that week. Each time, Lena bounced between Wikipedia tabs, Hacker News threads, and generic web searches, trying to find credible, relevant links fast enough to keep up with the pace of her team. She knew there had to be a better way to automate this research without losing quality.

That was the day she discovered the Research Agent demo template built with n8n and LangChain.

The problem: manual research in a multi-source world

Lena’s job was to curate reliable information from multiple sources. She needed:

• Background context from Wikipedia
• Tech and community perspectives from Hacker News
• Fresh, broad coverage from the wider web via SerpAPI

Every time she received a question like “can you get me 3 articles about the election,” she had to decide:

• Which source to check first
• How many tabs to open
• How to avoid wasting time and API credits on redundant searches

The mental overhead was small per request, but it added up. She wanted something that could:

• Choose the right research tool automatically
• Return concise, usable results
• Be predictable and cost-efficient

A colleague suggested she try n8n and showed her a workflow template that sounded exactly like what she needed: a Research Agent powered by LangChain and an OpenAI chat model.

Discovery: an intelligent research agent in n8n

Lena opened the template page labeled “Research Agent Demo – n8n + LangChain Workflow.” The description promised a smart research automation that could query Wikipedia, Hacker News, and SerpAPI, then decide which one to use based on the question.

At a high level, the workflow contained:

• Execute Workflow Trigger to start the automation with a query like “can you get me 3 articles about the election”
• Research Agent, a LangChain agent node that interprets the query and chooses the most suitable tool
• Tools registered as LangChain tools:
  • Wikipedia
  • Hacker News API
  • SerpAPI
• An OpenAI Chat Model that gives the agent reasoning and formatting abilities
• A Response (Set) node that shapes the final output for sending to Slack, email, or a database

It was not just a collection of nodes. It was a small research assistant, ready to be trained.

Rising action: building the workflow into her daily routine

Importing the template

Lena started by importing the provided JSON template into her n8n instance. In seconds, the structure appeared on her canvas:

Execute Workflow Trigger → Research Agent → Response, with the Wikipedia, Hacker News, and SerpAPI integrations wired into the agent node as tools.

She realized that instead of manually clicking around the web, she could trigger this workflow with a simple JSON payload containing a query field and let the agent handle the rest.

Connecting the right credentials

To bring the agent to life, she needed to supply a few keys and credentials:

• OpenAI API key for the OpenAI Chat Model node
• SerpAPI key for the SerpAPI tool node, which the agent would only use as a fallback
• Hacker News access, configured in the Hacker News node according to her environment

She made sure each of these tool nodes was:

• Properly authenticated using n8n credentials (not plain text)
• Exposed to the Research Agent in the node’s AI tool configuration

Once connected, the workflow had everything it needed to query real data sources.

The secret sauce: how the agent decides what to do

The turning point in Lena’s understanding came when she opened the Research Agent node and read the system instruction. This prompt was the rulebook the agent followed.

The instruction told the agent to:

1. Search Wikipedia first.
2. If the answer was not found there, search for relevant articles using the Hacker News API.
3. If both failed, use SerpAPI for a broader web search.

Most importantly, it enforced a strict single-tool policy. The agent was reminded:

You are a research assistant agent. You have Wikipedia, Hacker News API, and Serp API at your disposal.

To answer the user's question, first search wikipedia. If you can't find your answer there, then search articles using Hacker News API. If that doesn't work either, then use Serp API to answer the user's question.

*REMINDER*
You should only be calling one tool. Never call all three tools if you can get an answer with just one: Wikipedia, Hacker News API, and Serp API

This single-tool rule mattered. It kept Lena’s workflow:

• Efficient, by avoiding unnecessary API calls
• Predictable, since the agent used one source per query
• Cost-conscious, staying within rate limits and budgets

She realized she could customize this behavior. For developer-heavy topics, she could prioritize Hacker News. For fast-moving news, she could prefer SerpAPI first. The prompt was her control panel.

Mapping inputs and outputs into a smooth flow

Next, Lena checked how the query moved through the workflow. The template used a simple payload mapping pattern:

• The Execute Workflow Trigger node held the initial JSON payload, for example:

  { "query": "can you get me 3 articles about the election" }

• The Research Agent node read that query using expressions like {{ $json.query }}
• Tool nodes used expressions like {{ $fromAI("keyword") }} or {{ $fromAI("limit") }} to receive dynamic parameters from the agent

This meant the agent could decide not only which tool to use but also how to shape the search, for example:

• What keyword to send
• How many articles to request

At the end, the Response node collected the agent’s final answer and formatted it into a compact list of article titles, descriptions, and URLs, ready to be used by other workflows.

The turning point: testing “3 articles about the election”

With everything wired up, Lena pinned a test query to the trigger:

“can you get me 3 articles about the election”

She hit execute and watched the agent in action.

Following its instruction, the agent:

• First tried Wikipedia, looking for pages or references related to the election that contained useful links or summaries
• If Wikipedia did not provide specific article links, the agent switched to the Hacker News API, searching for related posts and selecting the top 3 results
• Only if both of those failed would it call SerpAPI to perform a broad web search and choose the top 3 articles

The result that landed in the Response node was exactly what she needed: a short, curated list of articles, each with a title, a brief description, and a URL. From there, she could send it to Slack, email it to her editor, or store it in a database for later reporting.

For the first time that day, Lena felt ahead of her research queue instead of behind it.

Resolution: turning a demo into a powerful research system

Once the initial test worked, Lena started thinking about how to adapt the workflow to her team’s needs.

Customizing the Research Agent for different priorities

She experimented with the system prompt and node settings to create variations of the agent:

• Source prioritization She changed the search order in the agent prompt for different use cases:
  • For breaking news, she told the agent to check SerpAPI first
  • For developer-focused content, she made Hacker News the primary source
• Result filtering She added post-processing nodes that:
  • Filtered articles by date
  • Excluded certain domains
  • Kept only results that matched specific keywords
• Summarization For longer briefs, she added another OpenAI model call to summarize each article snippet before returning results, so stakeholders could skim quickly.
• Automatic publishing She extended the workflow to send output directly to:
  • A CMS for content drafts
  • A newsletter system for scheduled digests
  • Internal Slack channels for daily research drops

Best practices she learned along the way

Costs and rate limits

Lena quickly understood why the single-tool rule in the prompt was so important. Every tool call had a cost, and APIs like OpenAI and SerpAPI had rate limits. By instructing the agent to use only one tool per query when possible, she kept:

• API usage under control
• Costs predictable
• Performance stable, even as the team scaled up requests

Accuracy and freshness

She also learned to choose tools based on the type of information needed:

• Wikipedia for stable background context and high-level overviews
• Hacker News for developer and tech community discussions, trends, and commentary
• SerpAPI for the most current web coverage, especially for time-sensitive or rapidly changing topics

When using SerpAPI, she added checks to validate domains and links to keep quality high.

Security and privacy

As she integrated the workflow into more internal systems, she made sure to:

• Store all API keys in n8n credentials, not in plain text fields
• Mask or redact any personal or confidential data before sending it to external APIs
• Limit who could edit the workflow in n8n to avoid accidental exposure of keys or sensitive logic

When things went wrong: quick troubleshooting wins

Not every test went smoothly. A few early runs taught her how to debug effectively:

• Agent chose the wrong tool She tightened the system prompt, making the single-tool requirement more explicit and clarifying the conditions under which each tool should be used.
• Wikipedia returned no results She verified the Wikipedia tool configuration and tested manual queries in the node to confirm connectivity and query formatting.
• Hacker News returned too many or too few items She adjusted the limit parameter, mapped from the agent using expressions like {{ $fromAI("limit") }}, and added logic to select the top N results by score or recency.

Key configuration details she kept an eye on

Over time, Lena developed a checklist of node settings to review whenever she cloned or modified the template:

• Execute Workflow Trigger Ensured the initial JSON payload contained the query field, for example:

  { "query": "can you get me 3 articles about the election" }

• Research Agent Verified the systemMessage string, tool attachments, and that the ai_languageModel was correctly set to the OpenAI Chat node.
• Hacker News node Checked that:
  • resource: all was selected
  • The limit field was mapped from agent inputs, for example {{ $fromAI("limit") }}

What changed for Lena and her team

Within a week, Lena’s workflow had shifted from frantic tab juggling to calm automation. The Research Agent handled routine questions, delivered consistent results, and scaled effortlessly as her team’s demands grew.

The Research Agent demo had become more than a tutorial. It was a practical example of how n8n, LangChain agents, and external tools like Wikipedia, Hacker News, and SerpAPI could work together to create a reliable research assistant.

Her team now used it for:

• Curated article lists for newsletters
• Regular internal briefings
• Quick background research for new topics

Your next step: put the Research Agent to work

If you recognize yourself in Lena’s story, you can follow a similar path:

1. Import the Research Agent template into your n8n instance.
2. Connect your OpenAI and SerpAPI credentials, and configure any required access for the Hacker News node.
3. Review and adjust the agent’s system prompt to match your priorities for Wikipedia, Hacker News, and SerpAPI.
4. Trigger the workflow with a query like “can you get me 3 articles about the election” and inspect the output.
5. Extend the workflow with filters, summaries, or publishing steps tailored to your content sources and channels.

If you want a faster start, you can adapt the template to your own stack: internal knowledge bases, different news APIs, or custom dashboards.

Call to action: Import the Research Agent template into n8n, wire up your OpenAI and SerpAPI credentials, and run your first research query. From there, refine the prompt, add post-processing, and turn it into the research assistant your team has been missing.

Create a Research Agent in n8n with LangChain

Automating research workflows in n8n lets you delegate time-consuming tasks like source discovery, content summarization, and article curation to a repeatable, deterministic pipeline. This documentation-style guide explains how to implement a LangChain-powered Research Agent in n8n that uses OpenAI, Wikipedia, Hacker News, and SerpAPI in a prioritized order to answer user queries.

The focus is on predictable tool selection, minimal unnecessary API calls, and structured outputs that can be consumed by downstream systems such as Slack, email, or a CMS.

1. Workflow Overview

The Research Agent workflow is designed to accept a natural language query, route it through a LangChain Agent with multiple tools, and return a curated response. A typical input might look like:

{  "query": "can you get me 3 articles about the election"
}

The workflow then executes a deterministic sequence of lookups:

• Attempt to answer using Wikipedia first for authoritative summaries.
• If Wikipedia is insufficient, query Hacker News for recent, developer-centric or tech-focused articles.
• If both fail to produce a suitable answer, fall back to SerpAPI for a broader web search.

This ordered strategy keeps responses focused, reduces latency, and avoids unnecessary calls to external APIs where possible.

2. High-Level Architecture

The workflow is composed of several key n8n nodes wired together to implement the research logic:

1. Execute Workflow Trigger – Receives the initial query payload and starts execution.
2. Research Agent (LangChain Agent) – Central orchestration node that chooses and invokes a single tool based on the system prompt.
3. LangChain Tools – Configured within the agent:
   • Wikipedia Tool
   • Hacker News API Tool
   • SerpAPI Tool
4. Response (Set node) – Normalizes and formats the agent output into a structured response.

The data flow is straightforward:

1. Trigger node injects a JSON object with a query field.
2. The LangChain Agent reads this query, applies the system prompt, and selects exactly one tool.
3. The selected tool queries its respective external API and returns results to the agent.
4. The agent composes a final answer, which is then shaped by the Response node into your preferred output schema.

3. Node-by-Node Breakdown

3.1 Execute Workflow Trigger

Purpose: Entry point for the Research Agent workflow.

Typical usage patterns:

• Manual execution from the n8n editor with a test payload.
• Triggered via another workflow using the Execute Workflow node.
• Invoked indirectly through a Webhook or a scheduled trigger in a parent workflow.

Expected input: A JSON object that includes at least a query field, for example:

{  "query": "can you get me 3 articles about the election"
}

Configuration notes:

• Ensure that the field name used for the research prompt (query) is consistent with how the LangChain Agent node expects to read it.
• If the trigger is part of a larger pipeline, validate that upstream nodes always provide a non-empty query string.

3.2 Research Agent (LangChain Agent Node)

Purpose: Core decision-making component that uses LangChain with an OpenAI Chat Model and multiple tools. It decides which tool to call and composes the final answer.

Key configuration aspects:

• Language Model: OpenAI Chat Model (configured via n8n credentials).
• Tools:
  • Wikipedia
  • Hacker News API
  • SerpAPI
• System prompt: Enforces the tool ordering and the single-tool rule.

The system prompt used in the template is:

You are a research assistant agent. You have Wikipedia, Hacker News API, and Serp API at your disposal.

To answer the user's question, first search wikipedia. If you can't find your answer there, then search articles using Hacker News API. If that doesn't work either, then use Serp API to answer the user's question.

*REMINDER*
You should only be calling one tool. Never call all three tools if you can get an answer with just one: Wikipedia, Hacker News API, and Serp API

Behavior:

• The agent reads the user query from the input data.
• Based on the system instructions, it evaluates which tool is most appropriate starting with Wikipedia, then Hacker News, then SerpAPI.
• It must call exactly one tool per query, which helps control API usage and keeps the behavior predictable.

Edge considerations:

• If the model attempts to call multiple tools, verify that the system prompt above is applied exactly and that no other conflicting instructions are present.
• If the agent returns an empty or low-quality answer, you can tighten the instructions in the system prompt to encourage more detailed responses or stricter adherence to the tool order.

3.3 Wikipedia Tool

Purpose: Primary lookup tool for quick factual summaries and background information.

Typical use cases:

• High-level overviews of events, concepts, or entities.
• Authoritative background context before moving to news or opinion sources.

Behavior in this workflow:

• The agent will attempt a Wikipedia search first, in line with the system prompt.
• If Wikipedia returns relevant content, the agent can answer using only those results.

Configuration notes:

• Adjust search parameters such as language or result limits if supported by the node.
• If you see frequent “no results” scenarios, consider instructing the agent to broaden the phrasing of queries in the system prompt.

3.4 Hacker News Tool

Purpose: Secondary lookup tool for developer-centric and technology-related discussions and articles.

Typical use cases:

• Recent technical news and community discussions.
• Links to blog posts, tutorials, and opinion pieces that may not be in Wikipedia.

Behavior in this workflow:

• Invoked by the agent only when Wikipedia does not provide sufficient information.
• Used to surface up-to-date content or niche technical topics that are better covered in community sources.

Configuration notes:

• Provide any required credentials or API configuration for the Hacker News node, if applicable in your n8n setup.
• Use filters such as score, time, or domain (when available) to reduce noise and irrelevant results.

3.5 SerpAPI Tool

Purpose: Final fallback tool for broad web search when Wikipedia and Hacker News are not sufficient.

Typical use cases:

• General web research across multiple domains.
• Topics that are not well covered on Wikipedia or Hacker News.

Behavior in this workflow:

• Only used if the first two tools cannot answer the question adequately.
• Provides wide coverage at the cost of potentially higher API usage.

Configuration notes:

• Requires a valid SerpAPI API key configured as n8n credentials.
• Consider setting result limits and safe search or localization parameters, depending on your use case.
• To control costs, you may want to cache results or restrict SerpAPI calls to only when strictly necessary, which is already encouraged by the system prompt.

3.6 Response Node (Set Node)

Purpose: Final formatting step that transforms the agent’s raw output into a structured, predictable schema for downstream systems.

Typical output formats:

• JSON with fields like title, link, summary, and source.
• HTML snippet for direct embedding into a CMS or newsletter.
• Plain text summaries for email, chat, or logging.

Example JSON structure:

{  "query": "can you get me 3 articles about the election",  "results": [  {  "title": "Election coverage - Example",  "link": "https://...",  "summary": "...",  "source": "Hacker News"  },  {  "title": "Election background - Wikipedia",  "link": "https://...",  "summary": "...",  "source": "Wikipedia"  }  ]
}

Configuration notes:

• Map fields from the agent’s output to a consistent schema so downstream consumers do not need to handle variable structures.
• Add default values or fallbacks in case some fields are missing from the tool response.
• If you plan to send data to multiple destinations (Slack, email, database), consider including both a machine-readable JSON object and a human-friendly summary string.

4. System Prompt and Tool Selection Strategy

The system prompt is central to how the LangChain Agent behaves. In this template, it encodes two key rules:

1. Ordered tool preference: Always try Wikipedia first, then Hacker News, then SerpAPI.
2. Single-tool rule: The agent should call exactly one tool for each query.

This approach:

• Reduces latency by avoiding unnecessary multi-tool calls.
• Controls costs for APIs like SerpAPI and OpenAI.
• Makes behavior easier to reason about and debug.

If you need different behavior, you can modify the system prompt. For example, to prioritize recent news, you might instruct the agent to check Hacker News before Wikipedia. Always keep the single-tool reminder if you want to maintain the deterministic, cost-efficient behavior.

5. Step-by-Step Setup

1. Provision an n8n instance
   Use n8n Cloud or deploy a self-hosted instance. Ensure it has outbound internet access to reach OpenAI, SerpAPI, and any other APIs you plan to use.
2. Configure LangChain and OpenAI credentials
   In n8n, enable the LangChain integration and create OpenAI credentials. The OpenAI Chat Model will be used by the LangChain Agent node.
3. Add external API credentials
   
   • Configure SerpAPI credentials for the SerpAPI tool.
   • Configure Hacker News credentials or parameters if required by your specific node configuration.

   Store all keys in n8n’s credentials store, not directly in node parameters.

4. Import the Research Agent template
   Import the “Research Agent Demo” workflow template into your n8n instance. This provides a ready-made configuration of the nodes described above.
5. Adjust system prompt and tool parameters
   Edit the LangChain Agent node to:
   • Refine the system prompt for your domain or tone.
   • Set any tool-specific options, such as result limits or filters for Wikipedia, Hacker News, or SerpAPI.
6. Test with sample queries
   Use the Execute Workflow Trigger node to run the workflow with various queries. Validate:
   • Which tool is selected for different query types.
   • That the agent respects the single-tool rule.
   • That the Response node returns data in the expected format.
7. Connect downstream integrations
   Once the output is stable, connect the Response node to:
   • Slack, for posting curated research updates.
   • Email, for sending research digests.
   • A CMS or database, for storing citations and summaries.

6. Configuration Tips and Best Practices

6.1 API Keys and Security

• Store all API keys (OpenAI, SerpAPI, Hacker News, etc.) in n8n credentials.
• Avoid hardcoding secrets directly in node parameters or expressions.
• Use environment variables or n8n’s built-in credential encryption for secure deployments.

6.2 Rate Limits and Reliability

• Check rate limits for OpenAI, SerpAPI, and any other APIs used.
• Where possible, add retry or backoff logic around nodes that call external services, especially SerpAPI and OpenAI.
• Consider caching frequent queries if your use case involves repeated research on similar topics.

6.3 Tool Selection Logic

• Modify the system prompt if your priority changes, for example:
  • Prefer recent news (Hacker News, then SerpAPI) before static background (Wikipedia).
  • Skip SerpAPI entirely for cost-sensitive environments.
• Keep the instructions explicit and concise so the model reliably follows them.

6.4 Result Limits and Response Size

• Limit the number of results returned by Hacker News or SerpAPI to avoid overly long or noisy responses.
• In the Response node, cap the number of items in the results array if your downstream consumers expect a fixed or small list.

6.5 Memory and Context

• For repeated queries on similar topics, consider adding a lightweight memory or cache layer to store previous results.
• This can reduce repeated API calls and improve response times, especially for SerpAPI.

6.6 Error Handling

• Check for empty or error responses from each tool and provide a fallback message.
• In the Response node, you can include a field such as status or error to signal when no suitable sources were found.
• Log failures or unexpected outputs for later analysis and prompt refinement.

7. Customizing Output

The Response (Set) node is where you control exactly what the workflow returns. Some common patterns:

7.1 JSON Output

• Ideal for APIs, webhooks, or other workflows.
• Include fields like:
  • query
  • results[] with title, link, summary, source

7.2 HTML Output

• Useful for CMS, newsletters, or dashboards.
• Generate an HTML list (for example, <ul> with <li> entries) containing links and short summaries.

7.3 Plain Text Output

• Suitable for Slack, email, or logging.
• Return short summaries followed by links for human review.

You can combine these approaches, for example returning a JSON object that includes both a structured