DEV Community: Mehmet Burak Akgün

What We Learned Building Heym for Production AI Workflows

Mehmet Burak Akgün — Wed, 02 Sep 2026 17:47:27 +0000

AI workflow demos are easy.

Connect a model to a prompt, add a tool, run it once, and the result looks impressive.

Production is where the harder questions begin.

What happens when a document changes in your knowledge base? Can a second machine take over the heavy workflows? Can your team use its existing identity provider? When something fails after three retries, can you see what actually happened?

These are the questions shaping Heym, a source-available and self-hostable platform for building AI workflows on a visual canvas.

The latest set of releases make that direction clearer. We have been working on RAG synchronization, multi-instance execution, OIDC single sign-on, execution inspection, and more practical browser automation.

At the same time, our recent writing has focused on the less comfortable side of AI agents: governance, sandboxing, specifications, and the difference between having a feature and having evidence that it works.

What is Heym?

Heym is an AI-native workflow automation platform built around LLMs, agents, RAG, browser automation, and MCP.

You can connect nodes on a visual canvas, generate workflows with an AI assistant, attach tools and skills to agents, and run independent branches in parallel.

The same workflow can then be called from:

The visual editor
A REST endpoint
An SSE streaming endpoint
An MCP client
A scheduled trigger
A public chat portal
Integrations such as Slack, Telegram, Discord, RabbitMQ, or email

The important part is not only building the graph. Heym also keeps the execution history, LLM traces, token usage, costs, logs, evaluations, and outputs around that graph.

We think an AI workflow should be inspectable after it leaves the demo environment.

Keeping RAG indexes synchronized

The newest RAG release adds Upsert and Delete operations to the RAG and Vector Store node.

A workflow can now address a document using an identifier from the source system, such as:

A CRM record ID
A product SKU
A page slug
An internal document key

This is different from depending on the vector database's internal point ID.

When an upsert runs, Heym removes the existing chunks associated with that document ID before writing the new version. This prevents an updated document from appearing beside its outdated chunks.

Delete uses the same external identifier and returns a normal result even when the document does not exist.

Metadata also supports expressions. A workflow can store values such as a source URL, customer ID, or category directly from an earlier node while preserving the original data type.

Both operations work with Qdrant and PostgreSQL with pgvector.

This turns RAG from a one-time ingestion task into a synchronization workflow.

You can read the RAG node documentation for the complete configuration.

Distributing workflows across worker instances

AI workflows tend to be uneven.

A webhook that transforms JSON may finish in milliseconds. A browser automation or multi-agent workflow can occupy a machine for much longer.

Heym can now distribute background executions across multiple instances connected to the same PostgreSQL database.

You can start another instance as a worker and assign execution weights from the settings panel. PostgreSQL carries the work, so workers do not need to expose a port or communicate directly with the main instance.

Placement is also explicit.

Workflows that depend on local files, installed plugins, coding-agent workspaces, or a fixed outbound IP remain on the main instance. Compute-heavy work that does not depend on local state can move to workers.

Execution history records which instance ran each workflow, and the history interface can filter runs by instance.

That makes horizontal scaling visible instead of turning it into infrastructure hidden behind the application.

More details are available in the load distribution documentation.

Signing in with an existing identity provider

Teams can now connect Heym to any OpenID Connect provider.

An administrator enters the issuer URL, and Heym discovers the provider's authorization, token, and signing-key endpoints.

The same configuration works with providers such as:

Keycloak
Okta
Microsoft Entra ID
Auth0
Google

Administrators can restrict automatic account creation to approved email domains and test the connection before disabling password login.

We also keep workforce identity separate from agent credentials.

OIDC answers how a person signs in to Heym. It does not answer which credentials a workflow should use when calling a database, CRM, or external API. Those are separate security boundaries and should be managed separately.

The SSO documentation covers the setup and safety checks.

Inspecting executions without leaving the timeline

When a workflow fails, a red node is not enough.

The execution timeline now includes a span details inspector. Selecting a span shows:

Status and duration
Start and completion times
Retry attempts
Trace information
The last error
Node output

This keeps the investigation connected to the timeline. You can identify the slow or failed step, inspect its output, and follow its trace without reopening several different panels.

For AI workflows, observability is not an optional dashboard. Model calls are probabilistic, tool calls touch external systems, and retries can change both latency and cost.

The details are described in the execution history documentation.

Browser automation that explains itself

Heym's Playwright node supports deterministic steps and AI-generated browser actions.

Recent additions make those AI steps easier to operate:

Plain-language browser instructions can be converted into Playwright actions
Failed runs identify the step that was attempted
Screenshots open in a full-size gallery
Generated actions can be saved for future runs
Failed selectors can be repaired through auto-healing

The design we prefer is hybrid.

Use deterministic browser steps for navigation and stable selectors. Use an AI step only for the part of the page that genuinely changes. Save the generated action, replay it, and validate the extracted result.

This idea is explored in our article, AI Web Scraping: Read the Page Once, Not Every Run.

The engineering lessons behind the features

Our recent blog posts are not release announcements. They document the questions that appeared while building the product.

Enterprise AI needs evidence

Every enterprise platform can say that it supports SSO, audit logs, and horizontal scaling.

The more useful questions are concrete:

Which identity claims are rejected?
What does one real audit record contain?
Which workflows cannot leave the main machine?
Which instance executed a specific run?
Can an administrator recover from a broken SSO configuration?

In Enterprise AI Agents: Everyone Passes the Checklist, we applied that checklist to Heym and published the gaps as well as the capabilities.

Governance is more than counting agents

An agent inventory tells you how many agents exist. It does not tell you whether they are controlled.

Our AI Agent Governance article reduces the problem to four questions:

Who owns the agent?
What is its purpose?
What is it allowed to touch?
How can someone stop it?

The first two produce records. The last two require enforceable controls.

That distinction matters because a policy saying an agent should not delete production data is not the same as a system refusing the delete operation.

Specifications need enforcement points

We also reviewed how coding agents followed our own repository instructions across more than a thousand commits.

The result was not simply that longer specifications worked or failed.

Rules naming a specific file, a destination, and a forbidden pattern were followed much more consistently than broad rules such as keeping every component below a certain size.

The lesson from Spec Driven Development: What Our Agents Ignored was simple: if a rule cannot be evaluated during one edit, it probably needs an automated check.

A sandbox should be tested from the inside

Our article AI Agent Sandbox: We Shipped the Bug First came from an uncomfortable place.

After discovering that one code execution path did not use the isolation we expected, we stopped treating sandbox configuration as evidence.

For the Code node, we ran a probe through the real execution path and checked what the container could actually see:

No backend secrets
No Docker socket
No application source
A read-only filesystem
No network access by default
An unprivileged user

A sandbox controls where code can reach. It does not decide whether the action should have been allowed in the first place. Isolation, authorization, and human approval remain separate mechanisms.

Where Heym is heading

The direction is straightforward.

We want building an AI workflow to feel visual and fast, while operating it remains explicit.

That means combining:

Natural-language workflow creation
Visual multi-agent orchestration
RAG and MCP
Human review checkpoints
Sandboxed code execution
Execution history and traces
Evaluations and cost tracking
Identity, auditability, and workload placement

The goal is not to hide complexity behind an agent.

The goal is to make that complexity visible at the points where a developer or operator needs to make a decision.

Heym is self-hostable, and the repository is available on GitHub.

You can try it locally with:


bash
git clone https://github.com/heymrun/heym.git
cd heym
./run.sh

Multi-Agent Systems Need More Than a Prompt

Mehmet Burak Akgün — Tue, 14 Jul 2026 20:34:42 +0000

Most multi-agent demos look simple.

An agent receives a request, delegates a few tasks, calls some tools, and returns an answer.

Then you try to use the same system for real work.

Suddenly, the important questions are not about the prompt:

What context did each agent receive?
Which workflow or tool ran?
Where is the output from the previous step?
Why did the process stop?
Is the system waiting for a person?
Can we continue without starting again?
How much time and money did each step consume?

If the answers are scattered across chat sessions, terminal logs, and database records, the system becomes difficult to trust.

This is the problem we are working on with Heym.

A board where cards do the work

In a traditional Kanban board, cards describe work that people need to complete.

In Heym's Agentic Kanban Board, a card is the work.

Each column can contain an ordered chain of AI workflows. Moving a card into a column starts that chain automatically.

Moving a card from Backlog to Planning is no longer just a status change. It is an execution event.

The Planning column might:

Analyze the request.
Retrieve relevant context.
Ask clarifying questions.
Produce an implementation plan.
Wait for human feedback.

The Development column can then receive the same card, including the plan and the human's answers, and start a different workflow chain.

The card becomes the handoff between agents, workflows, models, and people.

Persistent context instead of repeated prompts

One of the hardest parts of building multi-agent systems is preserving context across steps.

A Heym card carries:

The original request
Comments and human responses
File attachments
Previous workflow outputs
Movement and activity history
Execution results
Error states

Every new workflow receives the accumulated context.

This means you do not need to copy the same information into another prompt or invent a custom protocol for every agent handoff. The card acts as shared memory for the process.

Different columns can use different models, tools, and workflows while operating on the same persistent job.

Build with small, inspectable workflows

A production agent system is easier to understand when it is composed of small workflows with clear responsibilities.

For example, a feature development board could use:

A planning workflow that asks clarifying questions
A research workflow that retrieves technical context
A specification workflow that creates acceptance criteria
A coding workflow powered by Codex
A review workflow that checks the result
A publishing workflow that creates a pull request

Each workflow can be opened and inspected on Heym's visual canvas.

The control flow is explicit. You can see which workflow runs in each column, which tools are available, where approvals happen, and how outputs move into the next step.

This is what we mean by visible decisions. It is not hidden model reasoning. It is visible workflow routing, tool activity, retrieval results, approvals, and execution state.

Run the system by moving work forward

When a card enters a column, the workflows attached to that column run sequentially.

Each successful workflow appends its output to the card before the next workflow starts.

The card communicates its current state visually:

Pulsing amber means the workflow is running.
Static amber means the workflow is waiting for human input.
Green means the chain completed successfully.
Red means a workflow failed and the remaining steps were stopped.

This makes the board useful for both technical and non-technical team members.

A developer can inspect the execution details, while someone from product or operations can understand whether a job is running, blocked, completed, or failed.

Keep humans at the right points

Full autonomy is not always the goal.

Some decisions need context that only a person can provide. Others need explicit approval because they affect customers, production systems, or external services.

Heym workflows can pause for:

Human-in-the-loop reviews
Agent tool approvals
Clarifying questions
Codex follow-up questions

The execution state is persisted while the card waits.

Once someone answers or approves the request, the workflow resumes from the same point. The rest of the column's workflow chain continues automatically.

This is especially useful during planning.

A planning workflow can enrich a request and ask questions. The card stays in Planning until someone responds in the comment thread. That response becomes part of the card's context and releases it to the next stage.

If the plan needs more work, you can run another follow-up round without losing the previous discussion.

Debug the workflow, not just the final answer

When an agent produces the wrong result, the final response rarely tells you enough.

You need to inspect the execution.

Board runs in Heym are connected to the same execution history and tracing system used by other workflows. You can inspect:

Per-workflow inputs and outputs
Agent and tool calls
Errors and failed steps
Execution timing
Token usage
Estimated model cost
Human approval states
Previous attempts

This makes it possible to understand where the system failed without replaying the entire process from memory.

The board shows the operational state. The execution traces show the technical details behind it.

A simple planning loop

A useful first workflow looks like this:

Create a card containing a feature request.
Move the card into Planning.
The planning workflow analyzes the request and writes clarifying questions.
A human answers those questions in the card's comments.
The card moves into Development with the answers included in its context.
Development workflows run automatically.
Successful steps move the card toward Done.
Failures and approval requests remain visible on the board.

This is a small loop, but it contains the important parts of a production agent system:

Work intake
Context assembly
Agent execution
Human feedback
Persistent memory
Failure handling
Observable results

You can expand the system by adding new workflows to the chain instead of turning one prompt into an increasingly complicated block of instructions.

Agents need an operating surface

Prompts are part of an agent system, but they are not the system.

A reliable multi-agent workflow also needs memory, control flow, approvals, execution state, and observability.

That is what we want the Agentic Kanban Board to provide: a shared surface where people can see what agents are doing, understand what happened, and step in when needed.

You can read the complete technical walkthrough and import the starter planning workflow here:

Agentic Kanban Board: Loop Engineering for AI Agents

Heym is source-available and self-hostable. You can also explore the repository on GitHub.

Build, run, and debug multi-agent systems with visible decisions, memory, approvals, and execution traces.

heym

Launching AI Convert: a free workflow migrator for Heym

Mehmet Burak Akgün — Fri, 12 Jun 2026 20:00:37 +0000

We are launching AI Convert, a free migrator for Heym.

The idea is simple: if you already have a workflow export, or even just a plain English description of the automation you want, AI Convert turns it into a Heym workflow.

You can:

Paste an existing workflow export
Describe a workflow in natural language
Preview the generated workflow on a canvas
Click nodes to inspect details
Copy or download the generated JSON
Import it into Heym

This is meant to make migration and experimentation faster, without manually rebuilding every node from scratch.

Try it here: https://heym.run/convert

ai #automation #workflowautomation #developertools #opensource #heym

Heym just crossed 200 GitHub stars: self-hosted AI workflow automation with agents, RAG, MCP, and observability

Mehmet Burak Akgün — Mon, 11 May 2026 16:44:18 +0000

We just crossed 200 GitHub stars for Heym. Thanks to everyone who checked it out, starred it, opened issues, shared feedback, or tried building workflows with it.

Heym is a source-available, self-hosted AI workflow automation platform. It gives you a visual canvas for building production AI workflows with LLM nodes, Agent nodes, multi-agent orchestration, RAG pipelines, MCP client/server support, human-in-the-loop approvals, guardrails, execution history, LLM traces, evals, and reusable templates.

The goal is simple: make AI automation inspectable and self-hostable, instead of spreading prompts, tools, vector search, approvals, and logs across a pile of scripts and SaaS dashboards.

If you want to try one workflow first, this multi-agent template is a good starting point:
https://heym.run/templates/research-writer-pipeline

GitHub repo:
https://github.com/heymrun/heym

Would love feedback from people building agent workflows, self-hosted automation, or internal AI tools. Issues, stars, template ideas, and tough questions are all welcome.