DEV Community: Paton Wong

Subgraphs and Iteration: Once more, from the top

Paton Wong — Mon, 13 Apr 2026 16:34:26 +0000

In the previous example we explored how to use an LLM to extract factual claims and how to check an individual claim against the rest of the context.

To check all claims there are two options:

Ask the LLM to check all claims in one shot
Check each claim individually and combine the responses

In the first option, many LLMs end up skipping claims or mixing up evidence. This is often as effective as asking someone to glance over the material and use their intuition to "feel" if the claims are grounded. Reasoning models can perform better in this regard by breaking down the list during reasoning, but this still lacks rigor.

To check claims individually, however, we need to overcome a particular hurdle. By design, each node in a workflow is executed at most, once per run. This ensures workflows complete within a finite amount of time, bounded by the total number of nodes.

Rather than adding control structures analogous to for/while loops, workflows use a special node that acts on entire lists: Iterative Subgraph.

From an outside perspective, this node takes a list as input and is executed once during the run, producing a new list. Internally, it repeats a subtask over every item in the list and gathers the results into an output list.

You determine the subtask it performs on the list items by creating a nested graph -- a subgraph.

Aerie supports two kinds of subgraphs: simple and iterative. Simple graphs do little more than hold nodes to simplify the parent workflow. Even without additional behavior they are useful for organization. Iterative subgraphs execute their contents on each item of a list.

Subgraphs

There are some common rules governing all types of subgraph nodes. To edit the contents of a subgraph, double-click the icon in the body of the node.

This will open the subgraph editor which has a modified control palette. The top part shows the subgraph stack. Subgraphs can contain their own subgraphs. Each button in the stack shows a different level in this hierarchy. Clicking on one of switches the editor to the corresponding ancestor graph.

Inside the subgraphs, the editor contains a set of nodes and wires, including a Start and Finish node.

The inputs and outputs to the subgraph node are determined by the pins on its internal Start and Finish nodes. You can customize these pins within the subgraph editor, unlike the Start and Finish nodes of top-level workflows.

📢 important
During a workflow run, when a subgraph node is executed, the entirety of its contents is executed before the parent resumes. When a subgraph node is finished, none of its internal nodes will run in the future. The execution of nodes inside the subgraph does not interleave with nodes of the parent.

ℹ️ note
At the moment, subgraphs do not run incrementally. Any changes inside the subgraph reset the entire node.

Continuing the claims checking example, let's create a Subgraph › Simple node to hold the first agent. This isn't necessary for the small number of nodes, but it will allow us to get familiar with the subgraph editor.

Select the nodes containing the agent, schema and structured output and copy them into the subgraph.

The default text input can be wired directly into the prompt pin.

The output needs to be JSON, however. We must replace the output. First double-click on the label to edit the pin on the Finish node. Clicking on the trash icon will remove this value.

Then add a JSON output using the +new button.

Connect it to the Structured Output node to complete the subgraph.

Now we can replace the nodes in the parent with the subgraph, by rewiring the upstream and downstream nodes. You can rename it by double clicking on the title to document the purpose of the subgraph.

What did that buy us? Instead of a tangle of nodes near each other, we have a single node that represents a logical unit of work. The agent and schema are neatly hidden away.

On the flip-side, if you want to compare and modify the agents, for instance, now you have to navigate into a subgraph. Alternatively, you could add an input pin for the agent and pass it in from the top-level workflow.

Deciding what to put inside the subgraph vs what to pass as inputs is a balancing act that will change depending on the situation.

Iteration

Iterative subgraphs operate on list items. This leads to changes in how inputs and outputs are handled.

Node	Subgraph

Inside the subgraph, the Start node exposes individual values (i.e. text, message, number, etc). On the Iterative Subgraph node in the parent, however, these are represented as lists. The parent sends in a list of text strings, for instance, and the subgraph runs once for every text.

ℹ️ note
You can distinguish between single item (circle) and list (square) pins by shape.

Similarly, the Finish node inside the subgraph can receive individual values which the subgraph node collects and presents to the parent as a list of values.

Create a Subgraph › Iterative node. Copy the agent, context, schema and structured nodes from the workflow and paste them into the subgraph editor. Connect the input to the Structured node.

Similarly to the Simple Subgraph, replace the text output pin with a JSON output.

You may have noticed that the context is now blank. Add a new text field to the Start node and rename it "document". Connect it to the context.

💡 tip
You could also reorder pins to minimize crossing wires if you wish. We'll leave them as is during this workflow, however.

Back in the parent workflow, we can connect the Wikipedia article to the document pin, even though it is a single item, while the subgraph takes a list. In this instance, the subgraph will broadcast the item into every iteration such that all executions of the subgraph will see the same value for that pin.

On the other hand, the claims are currently wrapped inside JSON and automatic conversion isn't supported yet. We can use a JSON › Unwrap JSON node, however. Changing the Transform filter to [ .claims[1] ] will extract the second claim but place it inside a new list. This allows us to test the single value as a list.

💡 tip
Developing the workflow against a single item saves a lot of time and API credits.

Adjust the agent settings and run the workflow until you are satisfied that the new subgraph works correctly using only one or two list items before expanding it to the full list.

Once everything is in order, change the filter to just .claims to iterate over the whole list. Now when you run the workflow, notice the progress bar on the Subgraph node tracks.

Once it finishes, you should have a list of JSON values, or an error, depending on how well the grounding agent behaves.

You might have to go back and adjust the agent settings again until it produces satisfactory results.

⚠️ You may have noticed the parallel option on the Iterative Subgraph. This will speed up the workflow, but might cause issues with rate limiting. Hold off on using it until we cover rate-limiting via tools.

Conclusion

With iteration in place, the claims checking workflow is complete. Given an article, the workflow will systematically verify that the most important claims are supported by citations in the text. More broadly, this pattern of extracting, iterating then combining will be a useful building block for solving many tasks.

However, there are still ways to improve this workflow. One issue is that its results are only visible when running in the editor application. Another problem can occur if we try to process larger collections: the workflow can overwhelm the LLM provider and get blocked.

In the next installments, we'll see how to overcome these limitations by rate limiting via tool calls and creating outputs.

Citation Needed: Structured data extraction workflows

Paton Wong — Fri, 10 Apr 2026 19:04:13 +0000

In the previous article we explored how to generate and use structured data in a workflow. Now, let's take it a step further.

We'll build a workflow that checks whether an article provides evidence to support its claims (but not whether the evidence itself is valid). Rather than using this to fact check articles in the wild, this might be useful for critiquing your own writing before submission or checking generated text for hallucinations.

This task is impractical to automate without generative language models. Natural language processing pipelines might be able to extract or categorize entities and phrases from a text, but this task requires a degree of reading comprehension not available without larger language models.

Furthermore, while many language models are capable of performing individual steps, the overall process requires more rigor and discipline than they are trained for. Frontier models might handle moderately complex tasks, but verifying that they haven't hallucinated the results requires additional work on par with this workflow.

What we can do instead is split the task into distinct steps: extracting claims then checking each of them. In this article we'll look into the first part using our old friend the LLM › Structured node.

Claims Schema

In the Structured Generation tutorial we saw how to generate a single structured entry from scratch. LLMs are capable of handling much more complexity. This time we will ask the model to determine which phrases in a text are factual claims and place them into a list. Furthermore, we ask the model to rank the importance of each claim, holistically, when deciding whether to include it.

Like before, create a new workflow and swap out the normal Chat for a Structured node.

Create a Parse JSON node and connect it to the schema input of the Structured node. Fill it with this schema conveniently generated by an LLM:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "ClaimsList",
  "type": "object",
  "properties": {
    "claims": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "minItems": 1,
      "maxItems": 5,
      "description": "A list of claim strings. The list must contain at least one and at most five items."
    }
  },
  "required": [
    "claims"
  ],
  "additionalProperties": false
}

📢 important
Technically, an array at the top-level would be a valid schema.

However, many models have trouble generating data with that format. To ensure compatibility between providers, wrap the array in an object. Then extract the list later using JSON transformations.

Instructions

In the previous example we combined instructions with dynamic data into the prompt. This time we'll reserve the system message for instructions and inject the data in a separate step.

By partitioning the instructions and the data it becomes much easier to reuse the workflow on new inputs. We can use the system message field of the Agent node for instructions:

Follow these instructions exactly.
Do not respond directly to the user.
Do not hallucinate the final answer.

## Instructions

Extract the key factual claims in the user's statement and format them into a list (5 items or fewer).
Ensure that each claim can stand alone without additional context to make sense of it.

💡 tip
You should experiment with variations on the instructions, particularly the preamble to optimize it for your preferred language model. I find this combination effective with the nemotron family and various other open models.

The system message is sent once at the beginning of each request. Theoretically, the LLM should pay special attention to it. Regardless, this avoids sending repeat instructions with every prompt of a conversation, even when the entire conversation is sent with every request. ¹

Input Document

The input document for a workflow will typically be supplied by the runner. While developing a workflow, however, it's convenient to create a node for a predefined text to take advantage of iterative execution. In the final version of the workflow we can delete this node and connect to the input of the Start node.

Create a Value › Plain Text node to hold the article content.

Connect it to the prompt input of the Structured node.

Paste the contents of an article into the text field. I'm using a Wikipedia article about apiaries (artificial beehives).

Claim Checking

We now have a workflow that generates a list of claims from a text. Our eventual goal is to have each claim checked individually against the original text, which will be supplied to the language model in a context document.

However, before learning how to check every item, we should first explore how to check a single item.

First, let's pull a single claim out of the structured generation using JSON › Transform JSON. This node uses a jq filter to manipulate JSON.

The filter .claims[1] tells it to access the "claims" field and return the second element (0-indexed).

💡 tip
Ask your favorite frontier LLM for help writing jq filters from sample data.

Add a second Agent node with these instructions:

Follow these instructions exactly.
Do not respond directly to the user.
Do not hallucinate the final answer.

## Instructions

Help the user analyze the article in the context file.
The user is examining individual claims that the article makes.

Determine whether the context provides supporting evidence for the claim stated by the user.
List the reference or citation provided by the article.

DO NOT interpret the article as evidence for a claim made by the user.
The user is simply examining a claim made by the article.

How can we provide the article as context for the LLM? There are several ways:

Inject it into the system message using templating
Provide it as a user message in the conversation
Use a LLM › Context node

The third option is cleanest since it provides a clear demarcation between instructions, context and prompt. The Context node sits between the agent and a chat node, augmenting the agent by injecting its contents into requests made by the agent.

Connect the Plain Text node containing the article to the context input. In the final version of the workflow, this should be connected to the input pin of the Start node.

We can use a simple Chat node to do a quick spot check on how the context affects the language model response. However, to facilitate checking the entire collection, the responses for each item should be structured.

Structured Check

Replace the Chat node with a Structured node, connecting it to the Context and Transform nodes.

Use this schema for the claims checking Structured node:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "description": "A factual claim with evidence from citations or references",
  "type": "object",
  "required": [
    "claim",
    "grounding"
  ],
  "properties": {
    "claim": {
      "type": "string",
      "description": "the original claim made by the article"
    },
    "grounding": {
      "enum": [
        "not a claim",
        "unsupported",
        "fully supported"
      ],
      "description": "The level of support for the claim provided by citations and references. If the provided text is actually a definition or something other than a claim, then \"not a claim\""
    },
    "evidence": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "The citations and references that support the claim. Empty if the claim is not supported."
    }
  }
}

Connect the unwrapped claim to the prompt and run.

By changing the claim index we can see how it handles different claims and statements.

Conclusion

In this tutorial we've explored using language models to extract structured data from plain text, then transforming data for further processing. The workflow is still incomplete since we've only checked one claim.

Before we can go any further, we'll need to learn about iterating over lists using subgraphs. This will allow us to check every claim individually, then draw a conclusion by combining all results.

Some LLM providers support caching portions of the request. However, since this behavior isn't standardized across providers yet, aerie does not support it. ↩

Agentic tool use in Aerie workflows

Paton Wong — Thu, 09 Apr 2026 19:21:12 +0000

A key defining feature of agents is the ability to use tools to interact with its surrounding environment. Interaction can include gathering information from external sources or triggering actions.

With respect to software agents, the environment does not necessarily refer to a physical environment or the entire world. Rather, it often refers to the host computer or a set of remote services like reservation systems, knowledge bases, e-commerce platforms.

An agent uses some kind of program logic to automatically decide which tools to use and how to call them. In the case of AI agents, we use language models as the decision mechanism.

In workflows, we can expose tools to language models through Chat and Structured nodes. Agent nodes supply a set of tools, along with other parameters that are relevant to the specific subtask.

In this example, we will create simple weather agents using live weather services over the Internet.

Tool Providers

AI applications can implement and expose tools directly to language models. However, translating between program functions to tool calls, invoking implementations then transforming results can be tedious and error prone.

Instead, modern agentic systems use tools via a Model Context Protocol interoperability layer. AI applications employ client libraries to connect to MCP servers.

MCP servers bundle related tools and provide a model/language agnostic interface. They can be run locally or hosted by remote services. Client applications can connect to them through a local STDIO transport, or over an HTTP connection to internal network resources or to the Internet.

A wide variety of existing MCP servers can be found online[^mcp-lists]. The majority of them are focused on wrapping a particular application or service but many general-purpose utility-centric servers exist.

[^mcp-lists]: Some MCP server directories: https://github.com/modelcontextprotocol/servers https://mcpservers.com/ https://mcpindex.net/en https://mcpserverdirectory.org/

In aerie, tool providers are managed from the Tool tab.

You can create or import tool providers using the buttons at the top.

💡 tip
There are many tool provider configurations in examples/tools/nix that might be of use. Use the import button to add them.

STDIO servers are local executables that are launched and closed with the host application. Multiple copies in different applications are independent instances, but may use shared files or services. For instance, most database MCP servers would connect to a running database engine, rather than launching an embedded database instance.

HTTP servers are typically remote services hosted by a SaaS company or cloud platform. You will need individual credentials to use these services, usually in the form of an API key.

Select the provider from the list to edit its configuration.

Using the context menu on a provider you can remove or export the provider settings.

⚠️ warning
Do not include API keys, passwords and other personal information in the tool provider configuration since those will be included in the export. Set environment variables and reference them in the configuration.

In a sensitive environment or with high-value credentials, do not set environment variables globally. Rather, use a secrets manager to decrypt them from a vault and set them only for the process.

Select one of its tools to inspect its schema.

Weather Tools

For these example workflows, we will fetch weather data from open-meteo, since it does not require API keys. Since there is no official MCP server, we will use a third-party server: MCP Weather Server.

In the Tools tab, import examples/tools/nix/open-meteo.mcp. By default this will use the nix package manager to load and run uvx. Alternatively, you can invoke uvx directly with the sole argument mcp_weather_server.

💡 tip
For other capabilities, explore other included example tools like tavily for web search (requires an account) or qdrant for vector indexing/search.

Weather Chat

When an agent supplies tools to a Chat node, the language model must decide if a tool is necessary to complete a particular request. If it is, it must also decide which tool to call and what arguments to pass to it.

The results of the tool call are sent back to the model for a follow-up request to interpret the results. This generally happens behind the scenes automatically. Based on the results, the model might decide to call additional tools or finish its response to the user.

For example, in planning a short trip for a user, an LLM might first look up the current date, search for activities and events in a certain city, then check the weather for that city to ensure that conditions will be favorable.

ℹ️ note
The ability to break down a prompt into distinct steps and execute them in sequence largely depends on the model's complexity and training. There is no guarantee the model will complete the task on its own. Codifying these steps is the primary use case of workflows.

For the workflow, we'll only focus on checking the weather. Let's start with current conditions.

Create a new workflow and update the Agent node's system message, replacing the blank with your city:

You are a personal assistant for someone living in ______

Disconnect the prompt input of the Chat node and override it with a question requiring knowledge of the current weather.

Even though we added tool providers to the application, earlier, we need to tell individual agents which tools they are allowed to use.

Add Tools › Select Tools and check get_current_weather under open-meteo. Wire it into the Agent node.

💡 tip
You can select other tools too to check whether the language model can select the correct one on its own.

Add a Preview node and run the workflow.

Between the user's question and the final answer, there are extra messages. The LLM first responds in JSON, with parameters for a tool call. It does not call the tool directly, by itself. Rather the host application is responsible for calling the tool and supplying the results back to the LLM, which we can see as the follow-up message.

This isolates the responsibility of dealing with third-party accounts, permissions, security, etc away from the LLM. All it needs to deal with is language and logic.

Multi-step

So far so good, but what about getting forecasts for upcoming days?

open-meteo has get_weather_details that can return hourly forecasts over the next day. To get something further out, we'll need to use get_weather_byDateTimeRange.

The latter call requires knowing the current date and time to calculate a range in the future (API does not provide historical data). That might seem trivial at first glance, however language models have no information about the current state of the world, including the current date or time.

Fortunately, the weather MCP server provides get_current_datetime which the agent can call before checking the forecast (however, it does not include day-of-week labels).

💡 tip
Transform JSON can also inject date-time information into a request, though zone handling is limited.

When a language model behaves as expected, it queries the current data before fetching the forecast and the overall workflow succeeds.

On the other hand, some smaller models that are capable of planning or using tools may refuse to do both simultaneously.

Even if you explain the steps using instructions, they will still fail to call the correct (or any) tool. In many cases, they will hallucinate the current date or even the entire forecast, rather than failing in an obvious manner (i.e. refusing to generate an incorrect answer or returning an error response).

📢 important
You cannot rely on a successful Chat response to determine that the model has actually executed the necessary steps. When it matters, you will need to check the message history using another agent or conditional logic.

The more tools an agent has to choose from, the more potential for it to get confused. A universal catch-all agent using a small model to route between dozens of tools is likely to fail or hallucinate frequently.

Structured

Rather than a general purpose chat agent, if the specific purpose of a workflow is known, we can specify a sequence of steps to complete the task. We can also be more selective about the tools exposed to an agent.

💡 tip
You can use language models to route general prompts to task-specific branches within a workflow or route between workflows. See the examples and tutorials for more information.

Let's assume that we know answering a prompt requires knowing the current date for a location and the weather forecast.

With that knowledge, we can break down the workflow into phases:

getting the current time for the city
calculating a future date range
getting the forecast
answering the original prompt

To get the current time for step 1, we use a language model to extract the zone in much the same way we generated data from a schema in the previous chapter: using the Structured node.

Instead of passing in a schema, we pass in an agent that has tools. The LLM will understand that it has to find a city in the input and infer the time zone.

Unlike the Chat node, the Structured does not automatically call the tool --- it only returns the tool name and arguments. To call the tool in a workflow, use Tools › Invoke Tool. This allows the workflow to modify or transform the tool arguments before the tool implementation is executed.

With the results in hand, we have several options for sending the date-time to the LLM for additional steps. One option is to emulate the prompt/tool call/tool results loop used by the Chat node by simply passing the conversation to a new agent.

If we determine, during testing that the model does not perform steps 2 & 3 reliably, we can add them to the workflow similarly to the first step. Here, we've used a model to calculate the date range as a structured object, leaving the forecast call to the Chat node.

Chat History

To finish, we need to reconnect the Start and Finish nodes so that the workflow acts on the user prompt and displays messages in the Chat tab. However, there are multiple ways to organize messages in the final history.

If the Chat node extends the conversation, then all intermediate messages will appear as a flattened sequence in the history. We might not necessarily want to see messages in between the original question and the final answer.

One option is to take only the user prompt and final response and add them manually using History › Extend History.

The resulting session is now very simple and clean. However, we lose all the intermediate information that was used to arrive at the conclusion.

An alternative that preserves the data without cluttering the session is to use History › Side Chat. The wiring is less complex than using an Extend History node.

collapsed	expanded

The chat view still shows just the first and last messages by default, but now the intermediate data is accessible from the expanding "details" section.

Once you are satisfied with the workflow, remember to reconnect the input pin of the Start node to the Chat node.

Conclusion

In this article we've developed some contrived examples to demonstrate basic tool integration.

While these are too narrow in scope for a general-purpose chat bot, workflows are a perfect fit for specialist tasks. Larger systems can be built by composing smaller workflows using subgraphs and chaining.

In the following set of tutorials we will explore using subgraphs to organize more complex workflows before covering chained workflows.

Structured Generation: teaching AI agents to color inside the lines

Paton Wong — Wed, 08 Apr 2026 16:23:08 +0000

In the previous article, we explored generating free-form text in a workflow, as well as dividing responsibility for different parts of a task among agents. This time, let's look into generating machine-readable structured data.

💡 tip
Skip to the action if you're already familiar with structured data and schemas.

Motivation

Why would we want data to be structured? First, it is easier to filter, transform and combine documents with automated tools when we know ahead of time the shape of responses and what properties they can contain.

For instance, if we had to sort and organize thousands of profiles in unstructured text:

"John was born twenty five years ago and programs Python"

"Alice is a cryptography expert born in 1998"

etc.

Using traditional text-based tools there are an uncountable number of permutations, phrasings, exceptions and edge cases to consider. Instead, by using a language model to transform texts into structured data, we could use simple operations to fill in missing data and categorize each entry:

[
  {"name": "John", "age": 25, "occupation": "software engineer", "skills": ["python"]},
  {"name": "Alice", "dob": "1998", "occupation": "cryptographer"}
]

Second, many external applications and services require structured inputs. If we can construct structured data, our agents will be able to interact with these systems, bridging natural language and programmatic logic. In the parlance of AI agents, these are referred to as "tools" or "functions".

Generative language models are exceptionally good at translating between unstructured and structured data. Even many small models can extract structured data from paragraphs reliably. Medium-sized models with long context windows can often handle larger documents while following specific instructions about what to find.

JSON Schema

JSON (JavaScript Object Notation) is the de-facto standard for structured data across modern services and applications. Not only can programs easily parse JSON, but since it is a self-describing format, even an untrained human user can glean meaning from a JSON document without needing a deep understanding of its syntax. Most modern LLMs can generate JSON reliably when creating examples for a user or for invoking remote tools.

To instruct language models on the specific structure desired, we can use JSON Schema.

Schemas themselves are written as JSON documents. They dictate what fields are required in the target documents, along with type restrictions and more. It provides a way to describe a JSON document with strict precision, maximum flexibility or anywhere in between.

💡 tip
While you can write schemas from scratch, it may be quicker to either use a language model to generate one or a specialized schema editing tool (e.g. JSONJoy). By leveraging LLMs you don't need to know the rules for building schemas ¹.

For this tutorial, however, we'll use one of the canonical examples: User Profile.

Generating Data

Start by creating a new workflow from the command palette.

Use the rename button to replace the automatic name.

Remove the Chat node using either the node context menu or Delete key.

Replace it with a LLM › Structured node. Conversation history is not needed this time, but make sure to connect the Agent.

Use a JSON › Parse JSON node to provide the schema to the Structured node. Copy the schema contents from User Profile.

This will force the Structured node to generate data in the specified format. If the model fails to produce JSON or does not follow the schema, we can set the node to retry a number of times.

Set the prompt describing a user or character and tell the model to follow the schema.

Attach a Preview node to the data pin of the Structured node.

Depending on the model and temperature this may work the first time or it may fail.

You can try switching models or adjusting the temperature or experiment with the retry and extract options.

💡 tip
The retry and extract options on the Structured node also provide mechanisms for coping with different failure modes of weaker models. Often when retrying the model will understand its mistake and correct it. Other times, the model will get stuck explaining or apologizing while also producing correct structured data. For the latter case, the extract option will attempt to find structured data embedded within the response.

Together, they can prevent most common errors. Sometimes, however, you will still want to handle failure recovery within the workflow. Refer to the documentation for details.

Templating

Now that we have a JSON document with a known structure, there are many things we can do with it. Some examples are request routing, database updates, and content filtering. However, for this tutorial, we will only use it to generate unstructured text via a template. At a larger scale, this pattern could also be used to generate reports from longer documents or collections of items.

ℹ️ note
This pattern of generating structured data then formatting it immediately is not strictly necessary. LLMs can follow mostly instructions about formatting directly, though they often surround replies with unwanted verbiage. However, this is just a stand-in for more useful transformations.

Add a Value › Template node to the workflow.

ℹ️ note
The Template node uses jinja-like syntax which supports conditionals, filters, iteration and more.

The node takes a template string which may contain variables. On execution, the node substitutes the variables with concrete values provided by a JSON object via the variables input. Variables can be simple strings, arrays or dictionaries.

Attach the variables input to the data output of the Structured node and use this template:

## Profile ##

name: {{ username }}
e-mail: {{ email }}
Interests:
  {% for item in interests -%}
    - {{ item }}
  {% endfor %}

ℹ️ note
If the provided context is not a key-value map (e.g. text value, message, etc.) it will be exposed to the template as the variable value. This can be handy when wrapping a simple value or using a list valued input, without resorting to using a Transform JSON node to wrap the item in a JSON object.

Conclusion

In addition to generating data directly, we can use the Structured node to extract structured data from existing text as we'll see in upcoming articles.

Beyond simple transformations and templating, we could also use structured data to control the flow of execution with conditional branching, iteration or workflow routing which will be covered later.

Before delving into that, however, we will first cover how to work with external tools to create proper AI agents.

Bonus: Transformations

As mentioned in the main article, structured data can be merged and transformed into new structures.

Examples of things you could do include:

exclude or combine fields
merge multiple objects
group elements of a list by field values
exclude list entries based on value
remove duplicate entries from a list
convert a list of entries into a lookup table by name

One popular utility for doing this is the command-line utility jq. The JSON sub-menu contains nodes that can be used together to provide analogous functionality.

For instance, to replicate how Template automatically wraps single values, you can use JSON › Transform JSON with a simple filter:

{ value: . }

You can also combine data from multiple branches of the workflow using JSON › Gather JSON. This node takes multiple inputs and combines them into a single JSON array. The inputs can be existing JSON values, texts, numbers or more. By itself, a heterogeneous list of assorted data can be useful, but confusing to debug. Instead we will transform it into an object with descriptive keys.

ℹ️ note
The JSON › Transform JSON node uses an optimized implementation called jaq.

jq syntax can be difficult to comprehend at first. Fortunately, many LLMs are capable of generating filters from a prompt and/or examples.

With the prompt:

Write a jq filter that takes a list of user entries and creates an object keyed by the username field, removing the username field in the process.

Some models might produce this filter:

reduce .[] as $u ({}; .[$u.username] = $u | del(.username))

While others might produce:

[ .[] 
  | { key: ( .username ), value: ( . | del(.username) ) } 
]  | from_entries

Depending on the complexity of the ask, you may need to iterate with the LLM to fix any problems encountered.

You can describe the desired structure, providing examples and counter-examples, to a language model which will generate a schema. For instance: "Generate a JSON schema for a user containing a name, login, department and an optional role." ↩

Agentic workflows with Aerie

Paton Wong — Tue, 07 Apr 2026 08:06:39 +0000

Introducing Aerie

This is an introduction of a new open-source tool for creating and running AI-powered workflows.

Why use workflows?

You hire a brilliant intern and give them unrestricted access to your company's systems with high-level instructions to complete a complex task. They do a reasonably good job without breaking anything important, the first time. Should it be a surprise when a minor misunderstanding of the next task cascades into complete disaster? Yet this is commonly how we manage AI agents. For all their impressive capabilities, language models do not learn from experience as you "engineer" a prompt ¹.

Software agents are systems that make decisions and operate independently from
human supervision on behalf of users. AI agents replace deterministic program
logic with language models. These models, however, are inherently
probabilistic. The more autonomy we give them, the greater the opportunity for
surprises.

No matter how well-tuned prompts are during development, there are
uncountably many ways for things to go wrong in the wild. The more detailed you
make the prompt to account for pitfalls, the less attention the model can pay
to the core task. Furthermore, failure-retry loops can balloon the context,
confusing the model even further.

AI powered workflows provide a more reliable alternative to purely
agent-driven systems. A workflow breaks a task down to discrete, well-defined
steps. AI plays a specific but limited role in some of those steps allowing it
to concentrate on what it excels at without extraneous distractions.

What is Aerie?

Aerie² is a graphical tool for building agentic workflows. Programming expertise
is helpful, but not necessary. In this instance graphical is an overloaded term:
aside from the user interface of the visual editor, workflows are structured as
node graphs. Each node represents agents, data transformations, decisions, etc.
Outputs of a node can be connected to inputs of other nodes.
Data flows predictably from one node to the next.

With this visual approach it's easier to build, debug, explain and iterate on
workflows -- making aerie appropriate for prototyping and collaboration.

Setup

Aerie can be run from source or a binary AppImage available on the releases page.

The AppImage can be run directly under Linux without installation. However, you
will usually need to set the correct permissions after downloading the file.

$ chmod +rx aerie-x86_64.AppImage

It can also be run under Windows with WSL.

Building and running from source is recommended, however. The development stack
provides a uniform and predictable environment for the application. On the
other hand, it requires far more disk space and time for the initial start. For
instructions on building the source, see the Development Guide.

You can also install from source using the nix tool: Installation.

Getting started

To get a small taste of the potential of this approach, we will start by
building a trivial workflow. It will pass a user's prompt and conversation
history to an LLM and then rewrite its response as a haiku. Almost every modern
language model can handle this in a single step, but we'll use two agents for
didactic purposes.

In later articles we'll explore topics like data extraction, tool use and
iteration.

Click the Create button on the command palette to create a new workflow with
default nodes. Rather than an empty document, it will contain a basic chat
agent which you can choose to integrate into your workflow or discard. We'll do
the former this time.

First, disconnect the conversation pin on the Finish node, for now. You can
do this by right-clicking on the wire itself or the pin on either source or
destination node.

Normally, this would send the completed conversation of the
workflow to the chat session, viewable in the Chat tab. In the meantime, we'll
be working only in the workflow editor.

ℹ️ note
Pins on the right side of a node are output pins while pins on the left side
are inputs. Information flows in only one direction along a wire from the
output pin of a source node to an input pin of the destination node.

Normal Agent

Next, we'll use the existing agent to generate a normal response.
Disconnect the temperature and input wires between the Start and Agent nodes.

The Start node is the entry point into the workflow, gathering settings and
inputs from the execution environment and exposing them to the other nodes in
the workflow. These values are only available from the Start node.

Agent nodes define parameters for invoking LLMs via Chat and Structured
nodes. An Agent node does not generate content by itself. Rather it holds
settings to differentiate itself from other agents and can be re-used in
different stages of the workflow by content generating nodes.

Set the LLM model using the format {provider}/{model}. Examples:
ollama/devstral:latest or openrouter/openrouter/free. Most providers will have a list or database of models they provide (e.g. https://openrouter.ai/models & https://docs.mistral.ai/getting-started/models).

📢 important
Local providers like Ollama don't require authentication, but services like
OpenRouter, Anthropic, etc usually require an API key. See API Keys for details.

Set the temperature low (~0.25).

ℹ️ note
The temperature can be set between 0.0 and 1.0. It controls how words
are selected from a range of possibilities during generation. It is loosely
correlated with creativity. Higher temperatures mean more improbable outputs,
while lower temperatures tend to produce drier generic responses.

Now that the agent is configured let's take a look at the Chat node. This is the node
that actually interacts with the language model provider to generate content.

It takes configuration values from an Agent node and optionally a
conversation history -- an ongoing list of user prompts and agent responses.
In this instance, the conversation is supplied by the Start node, since this
is the first Chat in our workflow.

Finally, it takes a prompt, which you can supply from a text value like the
input pin of the Start node as we saw earlier with the default workflow. In
this instance, however, leave the pin unwired and type the text prompt directly
into the node.

Saving

Before we continue, it's a good idea to enable autosave in the Settings tab.
This will write any changes you make to disk automatically. Alternatively you
will need to click the Save button in the command palette manually for all
changed workflows.

⚠️ warning
If there are unsaved changes to workflows other than the one displayed, they
may be lost. The app will not warn about discarding unsaved changes when
exiting.

Previews

So far we've modified existing nodes, but now let's create a new node for
examining wire values during a run. The Preview node will show intermediate
values when the workflow is run from the editor but has no effect otherwise.

ℹ️ note
The Preview node can accept any wire value and will change its display
format according to the type.

Right click on the canvas in the area you want the new node to appear. A
context menu appears with nodes that can be added to this graph. Select the
Preview item to create a new node.

Running Workflows

Connect the response pin of the Chat node to the Preview's input and Run the
workflow using the button in the command palette.

As the workflow runs, nodes that have finished will be marked with a green
check.

Nodes that are actively running will have a spinning circle in the corner.

Once the workflow has run, the Preview node will show a standard response to
our prompt.

Poetic Agent

Now that We have a first agent generating normal (boring) responses, it's time
to create a second agent to generate poetry. This has a distinct purpose and
personality from the previous agent, so we'll configure it with different
settings.

Create a second agent from the context menu LLM › Agent.

Connect it to the first agent. It will take configuration values from the first
agent unless you override them.

ℹ️ note
Different languages will have differing proficiencies at various tasks. Some
will focus more on generating program code while others will be better at
writing long-form text. It can be beneficial to experiment with different
combinations in a workflow.

Override the temperature and set it higher (>0.75).

You can also override the system message (currently blank) to add personality
or add specific instructions for the current task. Instructions can vary
between formatting requirements, strategies for executing a task or admonitions
about avoiding particular pitfalls.

We won't provide any instructions this time. However, let's give the agent a
role to play, to impart some flavor on the generated result.

Create a second LLM › Chat node and connect it to the new agent.

Since we are asking it to act on prior responses, you will need to connect the
conversation to the previous Chat node NOT the Start node.

📢 important
Connecting it to the Start node would create a parallel conversation that
omits the previous agent's response.

Finally, connect it to another Preview node so we can compare the results
side-by-side.

Incremental Execution

Notice that the new nodes do not have status indicators, yet, in contrast to the
old nodes. This shows which nodes will be executed during an incremental
run. Other nodes with will be skipped, saving time and avoiding
extra API fees. This allows you to quickly try variations on node parameters or
different combinations of nodes without redundant work.

💡 tip
Selected nodes and the node under the cursor are also re-executed during an
incremental run.

You can trigger an incremental run with the shortcut Ctrl+R (see shortcuts
with the ? key).

ℹ️ note
The Run button in the command palette will trigger a full re-run of every
node in the workflow.

Notice that the "normal" Chat node does not rerun incrementally (assuming you
haven't changed, selected or hovered over it).

Try changing the second prompt (e.g. haiku → sonnet) and notice the status
indicator disappears.

Another incremental run should only re-execute that node.

If you change the second Agent node, one of two things will happen, depending
on whether the cascade setting is enabled. When cascade is enabled, a
status reset will propagate from a node to its children and all its
descendants.

💡 tip
Without cascade only the Agent node's status is cleared. To have the Chat
node re-run incrementally, you will need to hover over or select it.

Chat Sessions

We've been using the Workflow tab exclusively so far. If you go to the Chat
tab, notice that none of the messages appear. That's because the workflow
hasn't added anything to the session. The fix is simple: connect the last Chat
node to the Finish node.

Why didn't we do this from the beginning? Try another incremental run. You
should get an error about unrelated histories. This is because the
incremental state has an old copy of the conversation.

ℹ️ note
Internally, replacing it with the current conversation would invalidate the
entire workflow state. Rewinding and using the stale conversation is not
permitted, however, since workflows are not allowed to make destructive
changes to the session. They can only add content, but ignoring new messages
and overwriting them with new ones would remove existing history from the
session.

This restriction only applies to workflows. From the Session tab you can perform
various changes to the conversation history.

📢 important
Why aren't my chats saved?

Conclusion

While what we've seen here isn't particularly groundbreaking or useful, now
you should be comfortable with using the editor to build workflows. Next, we'll
explore generating and manipulating structured data, before moving on to tools,
subgraphs and iteration.

Troubleshooting

Workflow gets stuck on Chat node

API Keys

API keys specific for each provider must be defined in the environment.

Platforms (Windows, Mac, Linux) have different ways of defining variables at the system-level, per account or for a terminal session.

ℹ️ note
Changes to the environment will not take effect until the application restarts.

While it is common practice to use system/account-wide environment variables, there are security concerns stemming from this. One alternative is to use direnv to limit its scope by directory. However, this requires API key to be stored as plain text.

Example using direnv:

$ cd ~/Projects/xyz

$ cat > .envrc
export OPENROUTER_API_KEY=****
^D

$ direnv allow .
direnv: reloading
direnv: loading .envrc
direnv export: +OPENROUTER_API_KEY

$ aerie
...

⚠️ warning
Do not use system/account-wide environment variables for high-value secrets (production/admin/etc tokens/keys/passwords). Session-level variables may also be insecure.

A more secure option is to use a password manager/vault application with console integration, like Bitwarden, vault, pass, etc.

Example using Bitwarden CLI (note is dotenv formatted):

$ aerie --env <(bw get notes "API Keys")
? Master password: *****

Enable streaming

In some cases, providers may actively generate a response, but the response
itself will be large, taking minutes to complete. Most providers support
streaming individual tokens, allowing you to see the response as it is
generated, rather than waiting for it to finish.

Change providers/models

Some providers have high latency or unreliable connections. If one does not
respond in a reasonable amount of time try another.

Be aware that some providers (openrouter for instance) proxy to other providers. Different models may run on different providers.

Even on a single provider, models may be allocated different hardware resources
to handle different requirements or due to popularity.

Workflow gets stuck elsewhere

Check console logs

This application is still under active development. Most errors will trigger an
error dialog, but some may cause the run to fail silently. The console may
provider warnings or other indication about what has failed.

Can't edit node

Workflow is running or frozen

The workflow can't be edited while it is running. Wait for it to complete or
use the Stop button to interrupt it.

The editor can be frozen/unfrozen manually or while examining edit history.
This prevents unintended changes when browsing through the Undo stack.

To unfreeze the workflow, toggle the button on the control palette.

(Dis)connect input pins

Some fields can take values from controls on the node as well as input wires.

The controls will not be visible unless the wire is disconnected.

Toggle optional controls

Some node fields are optional. For example, fields that might override a
previous value will need to be enabled to be edited.

Chat history disappears on restarting app

Set active session

By default no session is active. When no session is active (denoted by an
empty value in the session selection) chats are discarded when the app exits.
To save an ongoing chat, rename the session. The active session is reloaded
the next time you start the app.

Fine tuning models is a different matter, with steep data and resource requirements. ↩
A nest of a bird of prey perched high on a cliff or tree top. ↩