DEV Community: ByteChef

Chat memory that compacts by turns, so your agent never loses half a tool call

ByteChef — Mon, 09 Nov 2026 21:39:08 +0000

Cross-posted from the ByteChef blog. Part 7 of the AI Agentic Patterns in ByteChef series.

Every chat agent has the same slow leak. Each message grows the history, and the whole history goes into the next prompt. Long chats get slower, cost more and eventually hit the model's context limit.

The usual fix is "keep the last N messages". It works fine until the agent uses tools.

The problem with "last N messages"

A tool call and its result are two separate messages. Trim the history between them and the model gets one without the other: a result with no call, or a call with no result.

user:       What's the status of order 4512?
assistant:  [tool call] getOrder(4512)      <- window cuts here
tool:       { "status": "shipped" }         <- this survives
assistant:  It shipped yesterday.

Nothing throws. The agent just starts answering strangely, and you spend an afternoon figuring out why.

Chat Memory v2 in ByteChef fixes this by compacting the conversation in whole turns instead of loose messages.

Turns, not messages

Chat Memory v2 is built on the Spring AI community Session library. It stores a conversation as an ordered log of events. Each user message, assistant reply, tool call and tool result is one event.

A turn is one user message plus everything that follows it (replies, tool calls, tool results) up to the next user message. Compaction only ever removes whole turns. A tool call and its result stay together or leave together.

With the Turn window strategy:

When to compact: as soon as the history has more turns than Max turns.
How to compact: archive the oldest turns until only Max turns remain. The system prompt is always kept.

Archived, not deleted

Compacted events leave the prompt, but they stay in storage.

Turn on Enable conversation search tool and the agent gets a conversation_search tool. It passes a keyword, and the tool searches the whole conversation, including archived events that are still kept. Results come back in pages (Search page size, 10 by default).

So the agent's view is short, but its reach is long.

Two limits to know:

Summaries are not searched. If you use Recursive summarization (below), the summaries the model writes don't show up in search. The original messages do, while they're kept.
The archive is capped on some storage. Redis and S3 keep the 1000 most recent archived events. The built-in Chat Memory keeps the number set by bytechef.ai.memory.session-max-archived-events.

Try it: the template

The fastest way to see this is the Chat that compacts its history template.

Three steps:

New Chat Request - a message arrives in the workflow chat.
AI Agent - Claude Sonnet as the model, Chat Memory (version 2) in its Memory slot.
Reply - the answer goes back to the chat.

Chat Memory is configured like this:

Field	Value
Conversation ID	`${chat_1.conversationId}`
Compaction Strategy	Turn window (by turns)
Max turns	3
Enable conversation search tool	on

The system prompt tells the agent what to expect:

Your visible history is short. If the user asks about something said earlier that you no longer see, use the conversation search tool to find it, and say that you searched.

Three turns is far too small for real use. It's set that low so compaction shows up after a few messages.

To run it:

Import Chat that compacts its history and add it to a project.
Add your Anthropic connection to both models: the agent's and the one on Chat Memory. That's the only setup.
Send four or five messages on different topics. Put something specific in the first one, like a name or a number.
Ask the agent what you said at the start.

By then the first turn is archived. The agent can't see it, so it calls conversation_search and tells you it searched.

That's a real test run. The code name was in the first message, which had already left the three-turn window, so the agent searched the archive to answer.

To watch it happen, open the Agent Playbook in the editor. Its tool-call cards show conversation_search running, with the keyword the agent picked and the messages it found.

Past the demo, raise Max turns to 10-20, or switch to Token count or Recursive summarization. The search tool works the same with any strategy.

Why there's a second model

Look at the template again. The Chat Memory element has its own model, Claude Haiku, separate from the agent's Claude Sonnet.

Only Recursive summarization uses it. With Turn window, old turns are archived and no model is called. Haiku is there so you can flip the dropdown to Recursive summarization without adding anything, and summaries come from a smaller, cheaper model than the one talking to your users.

Pick Recursive summarization with no model on Chat Memory and the run fails with a clear error.

Four ways to compact

Compaction Strategy is a dropdown. Each option shows only the fields it needs.

Strategy	Fields	What it does
None	-	Never compacts. The default.
Sliding window (by events)	Max events	Keeps the most recent `Max events` once the history exceeds it.
Turn window (by turns)	Max turns	Keeps the most recent `Max turns` once the history exceeds it.
Token count	Max tokens	Keeps the history within an estimated token budget.
Recursive summarization (LLM)	Max events, Max events to keep, Overlap size	Over `Max events`, a model summarizes older events and the most recent `Max events to keep` stay in full.

For Recursive summarization, ByteChef checks two rules when the run starts:

Max events must be greater than Max events to keep.
Overlap size must be less than Max events to keep.

Overlap size is how many of the kept events the summarizer also sees, so the summary connects to what comes after it.

Where the history lives

Chat Memory v2 ships as several components with the same fields. Only the storage differs:

Chat Memory - built-in. Storage follows bytechef.ai.memory.provider: JDBC, Redis, AWS S3 or in-memory.
JDBC Chat Memory - a relational database.
Redis Chat Memory - Redis, with its own connection.
AWS S3 Chat Memory - JSON objects in an S3 bucket, with its own connection.
In Memory Chat Memory - server memory, gone after a restart.

The template uses the built-in one, so it needs no extra connection.

The S3 backend is ByteChef's own implementation of the Session library's storage interface. Each session is one JSON object, and writes use S3 conditional writes (If-Match on the ETag), so two writers can't silently overwrite each other's events.

What Spring AI gives you, and what ByteChef adds

The compaction strategies, triggers and conversation_search come from the Spring AI community Session library. In plain Java you build the memory advisor, pick a trigger and a strategy, and register the search tool yourself. ByteChef runs the library directly and adds:

Fields instead of code. One dropdown, a few numbers and a toggle.
A model picker for summaries. The summarizer is a child element on Chat Memory, so it can be any model ByteChef supports.
Clear errors. Invalid Recursive summarization settings, or a missing summarizer model, stop the run with a message that names the problem.
Storage choices. JDBC, Redis, in-memory and ByteChef's own S3 backend, as separate components with the same fields.
A search tool Claude will actually call. The library's conversation_search also asks the model for a private "inner monologue", and Claude refuses the whole turn rather than fill it in. ByteChef registers the tool with only a keyword and a page number.

Short-term vs long-term memory

Chat Memory keeps one conversation coherent. It doesn't carry facts into the next one. For that, ByteChef has the Auto Memory Tool: the agent writes down what's worth keeping and reads it back in later chats. It works in deployed runs, not editor test runs.

Both can sit on the same agent: Chat Memory in the Memory slot, the Auto Memory Tool in the Tools slot.

Same rule as Part 1 of the series: load each kind of knowledge only when it's needed. Skills load procedures on demand. Compaction keeps old turns out of the prompt until the agent searches for them.

Wrapping up

Dropping old messages one at a time can cut a tool call in half. Chat Memory v2 compacts by whole turns, archives what it removes and lets the agent search the archive. You pick the strategy and the storage on the canvas.

Try it: import Chat that compacts its history, connect Anthropic, send five messages and ask what you said first.

ByteChef is open source (Apache 2.0) and built on Java and Spring. If this was useful, a star on GitHub helps a lot.

Long-Term Memory for AI Agents: Teaching a ByteChef Coding Buddy to Remember You

ByteChef — Fri, 06 Nov 2026 16:03:57 +0000

TL;DR: Chat memory only covers the conversation you're in. Spring AI's AutoMemoryTools add a second layer: the agent deliberately writes down facts worth keeping and reads them back in later chats. ByteChef ships the same six memory tools as the Auto Memory Tool, stores memories in its database, and keeps a separate memory per project deployment and environment. Want to see it? Deploy the Remember coding preferences across chats template, tell it your build tool once, then open a new chat.

This is Part 6 of the AI Agentic Patterns in ByteChef series.

The problem: agents with amnesia

You tell your assistant you use Gradle. Next conversation, it hands you a Maven pom.xml. You mention you're on Java 25. A week later it suggests a workaround for Java 17.

The reason is simple: chat memory is a sliding window. It keeps the recent turns of one conversation and drops the oldest when it fills up. Great for the task at hand, useless for something you want the agent to know next month.

For that you need a second layer: a place where the agent writes facts down on purpose and reads them back in future conversations. Let's build one in ByteChef with a single template.

The template: a coding buddy that remembers

Remember coding preferences across chats has three steps:

New Chat Request – a message arrives in the workflow chat.
AI Agent – an Anthropic model with two kinds of memory: Chat Memory for the current conversation and the Auto Memory Tool (in the Tools slot) for long-term memory.
Reply – the answer goes back to the chat.

The system prompt tells the agent how to use its memory:

You are a coding buddy for a Java developer. At the start of every
conversation, read your memory index and any relevant memory files.
When the user states a lasting preference (build tool, Java version,
testing style, answer length), save it as a memory right away and say
that you saved it. Apply remembered preferences without being asked.

The Auto Memory Tool itself needs no configuration. The one thing that matters is in the green note on the canvas: long-term memory only works in a deployed run (more on that below).

Two kinds of memory

The Spring AI team sums it up well: use ChatMemory for the current task, and AutoMemoryTools for facts that should still be there next week.

	Chat Memory	Auto Memory Tool
Holds	Turns of one conversation	Facts the agent chose to keep
Written by	The platform, every turn	The agent, on purpose, via a tool call
Lasts	That conversation	Until edited or deleted
In the template	What you said a minute ago	Your build tool in next week's chat

The template uses both: Chat Memory lets you say "now add a test" without repeating context, and the Auto Memory Tool lets a brand-new conversation start from what the agent already knows about you.

How the agent remembers

Long-term memory is a small set of entries plus an index:

Entries – short Markdown files with frontmatter (title, optional description, type) followed by the fact.
The index – MEMORY.md lists every entry on one line, newest first. The agent reads it at the start of a conversation and opens only what it needs. ByteChef keeps it in sync automatically, so the agent never edits it by hand.
Four types that guide what's worth saving:
- USER – facts about the user: role, preferences
- FEEDBACK – corrections, or approaches the user confirmed
- PROJECT – decisions and constraints of the ongoing work
- REFERENCE – pointers to external systems

Tell the buddy "I always use Gradle with the Kotlin DSL and Java 25" and it might save something like this (illustrative):

---
title: Build setup
description: Gradle with the Kotlin DSL, Java 25
type: USER
---

Always use Gradle with the Kotlin DSL and target Java 25.

The agent manages memory through six tools, with names and behavior straight from Spring AI:

Tool	What it does
`MemoryView`	Lists the index, or shows one entry with line numbers
`MemoryCreate`	Creates a new entry
`MemoryStrReplace`	Replaces an exact piece of text in an entry
`MemoryInsert`	Inserts text at a line in an entry
`MemoryDelete`	Deletes an entry
`MemoryRename`	Renames an entry

Entry names are flat (e.g. build_setup.md) – no folders.

Where ByteChef differs: database storage, scoped per deployment

In Spring AI, memory is a folder of Markdown files on disk. Perfect for one agent on one machine, but a platform has harder questions: Whose memory is this? Does it survive moving to another server? Can someone inspect it and fix a wrong fact?

Spring AI keeps storage behind two small interfaces, and ByteChef plugs its own implementation in there. The agent still sees the same six tools and the same format, but entries go through ByteChef's memory service – the database by default. Self-hosted installs can set bytechef.ai.auto-memory.provider to use file storage instead.

Whose memory is it?

ByteChef works out the owner from the run itself – nothing to configure:

Automation projects: memory belongs to the project deployment + environment. All workflows and runs in that deployment share it; another deployment (or the same one in another environment) has its own.
Embedded integrations: memory belongs to the integration instance, so each of your customers gets a separate memory.

When memory is unavailable

If a run has no owner, the tool still loads, but every call returns a short "memory is unavailable" message with the reason, so the agent can tell the user instead of failing. That happens for:

Editor test runs – a test run isn't a deployment. Bonus: experiments in the editor never pollute a real deployment's memory.
Microservices installs – memory requires the ByteChef server application.
Runs without a workflow context – e.g. when the agent is invoked from somewhere that doesn't identify the running workflow.

Hence the canvas note: deploy first.

Try it yourself

Import the template – open Remember coding preferences across chats and add it to a project.
Connect the model – add your Anthropic connection.
Deploy – deploy the project and enable the workflow in the deployment.
State a preference – in the deployed workflow's chat, say something lasting, like "I always use Gradle with the Kotlin DSL and Java 25." The agent saves it and tells you so.
Check it in a new conversation – start a fresh chat and ask for a build file.

Here's step 5 in a real deployed chat. The request mentions neither Gradle nor Java, yet the agent checks its memory first and produces a Gradle Kotlin DSL build with a Java 25 toolchain:

Try step 4 in an editor test run instead and the agent will tell you memory is unavailable – that's expected.

See and fix what it remembers

Stored memories live under Settings → AI → Memories. You can search by title or description, filter by type or owner (deployment or integration instance), and open, edit, or delete any entry. When a preference changes, fix it there – or just tell the agent and let it update the entry itself.

What you get from Spring AI vs. what ByteChef adds

ByteChef keeps the Spring AI design – the curated memory layer, six purpose-named tools, index plus typed entries, and the short-term/long-term split – and changes what's underneath:

Storage: files on disk become database entries that survive restarts and server moves.
Ownership: memory is scoped to a project deployment + environment, or to an integration instance.
Visibility: review, edit, and delete memories in Settings → AI → Memories.
Wiring: no advisors or directories to set up in code – just drop the Auto Memory Tool into an AI Agent's Tools slot.
Safe testing: editor test runs have no memory owner, so testing never writes into real memory.

Memory also pairs nicely with the other patterns in this series: Agent Skills give an agent know-how that's the same for everyone; long-term memory gives it what it has learned about your users and project.

Wrapping up

Chat memory answers "what did we just talk about?" Long-term memory answers "what do I already know about you?" Spring AI packaged the second as six tools and a simple file format. ByteChef keeps both and adds a database and per-deployment ownership, so memory lasts, stays separate per deployment or customer, and is there for you to inspect.

The fastest way to get it is to run it: import Remember coding preferences across chats, deploy, tell it your build tool once, and open a new chat.

Originally published on the ByteChef blog. If you found this useful, give ByteChef a ⭐ on GitHub!

Your AI agent can't know everything. Let it ask another agent.

ByteChef — Wed, 04 Nov 2026 15:24:44 +0000

You're building an agent that helps a team plan Java upgrades. Someone asks it which Spring Boot version first required Java 17.

It doesn't know. Another agent does.

That agent belongs to another team. It runs on another server. Maybe it was built with another framework.

Skills won't help here. Neither will subagents. Both live inside your agent, in your workflow, on your server.

You need a protocol neither side owns. That's A2A (Agent2Agent): an open protocol for agents to find each other and hand over work, across frameworks and vendors.

Here's how it works, and how we run both sides of it in ByteChef, an open-source workflow automation and AI agent platform built on Java and Spring.

A2A in three ideas

The Spring AI team covers agents working across system boundaries in their A2A post. The protocol comes down to three things:

The agent card. Every A2A agent publishes a small JSON document at /.well-known/agent-card.json with its name, description, and skills. A client reads it to learn what the agent can do and where to send messages.
The protocol. Agents talk over HTTP with JSON-RPC. A client sends a message. The agent answers with a message or a task.
Two roles. A server publishes a card and answers messages. A client reads a card and sends work. Any agent can take either role.

The whole contract is a JSON card and an HTTP endpoint. That's why a Spring AI agent can call one built with another framework, and the other way round. Neither side needs to know how the other works.

The example: a tech lead asks a release expert

We built two templates, one for each side of the protocol.

The server: Java release expert

The Java release expert is three steps:

New Workflow Call starts the workflow with one input, message. Behind an A2A Server, the text of the incoming A2A message lands here.
AI Agent answers with an Anthropic model and no tools.
Reply returns the answer to the caller as message.

Its system prompt:

You are the Java Release Expert. You answer questions about Java and Spring
release history: versions, release dates, headline features and migration
notes. Answer in at most 6 short bullets. If you are not sure of a date, say so.

Nothing in this workflow mentions A2A. It's an ordinary callable workflow. The A2A Server does the protocol work around it.

The client: Tech lead agent

The Tech lead agent is a chat agent:

New Chat Request starts the workflow when you send a message in the workflow chat.
AI Agent uses an Anthropic model, Chat Memory for follow-up questions, and the A2A Agent Tool in its Tools slot.
Reply sends the answer back to the chat.

Its system prompt:

You are a tech lead helping a team plan upgrades. For any question about Java
or Spring versions, release dates or features, delegate to the remote Java
Release Expert with the agent client tool and build your answer on its reply.
Say that you asked the remote agent.

The tech lead doesn't know Java release history. It knows who to ask.

Serving an agent is configuration

An A2A Server in ByteChef turns one or more workflows into a remote agent. You find it under Servers → A2A Servers.

Each server has:

A name and a description. These become the name and description on the agent card.
Workflows. Every workflow you add becomes a skill on the card. The skill's name and description default to the workflow's label and description, and you can change them under Workflow Skills. Only workflows that start with a New Workflow Call trigger are exposed, and adding a workflow deploys it.
A URL. The address contains a secret key. The Connect tab shows two URLs, the Agent Card URL and the Endpoint URL.
An optional API key check. With Require authentication on, callers also need an API key created under Settings, sent as an Authorization: Bearer header. With it off, the secret in the URL is enough.

https://<your-bytechef-host>/api/automation/a2a/<server key>

When a message arrives, the server starts the workflow and passes the message text as its message input. When the run finishes, the workflow's response goes back to the caller.

The server answers message/send and message/stream, and supports tasks/get and tasks/cancel for runs that take longer.

The agent card advertises text in and text out. If your server sits behind a proxy, set ByteChef's public URL so the card points to an address other agents can reach.

Calling an agent is one tool

The A2A Agent Tool goes in an AI Agent's Tools slot. It has one property, Agent URL. For a ByteChef A2A Server, that's the Endpoint URL from the Connect tab.

When the agent decides to delegate, the tool:

Reads the card from <Agent URL>/.well-known/agent-card.json.
Sends the task as an A2A message over JSON-RPC.
Waits up to 60 seconds for the reply.
Returns the text of that reply to the agent.

The reply can be a plain message or a task with artifacts. The tool pulls the text out of either.

If the remote agent can't be reached, returns an error, or takes longer than 60 seconds, the tool fails with an error that names the agent URL. It doesn't hang.

The model sees a tool called sendTaskToRemoteAgent, and the system prompt tells it when to use it. To reach several remote agents, add one A2A Agent Tool per URL.

If the remote server requires authentication, add an A2A connection to the tool. It has one field, Token, sent as an Authorization: Bearer header. For a ByteChef A2A Server, that's the API key.

One limit to know: when a server exposes several workflows, a caller has to say which skill it wants. The A2A Agent Tool doesn't choose a skill, so point it at a server that exposes one workflow. The template pair is set up that way.

Try it

Set up the server first. The client needs its URL.

The server:

Import Java release expert into a project.
Add your Anthropic connection to the model and save the project.
Open A2A Servers, click New A2A Server, name it Java Release Expert, and give it a description. The description goes on the agent card.
Leave Require authentication off for a local demo. Turn it on for anything reachable from outside, and give callers an API key.
Click Add Workflows, pick the project and version, and select the workflow. This deploys it.
Open the Connect tab and copy the Endpoint URL.

The client:

Import Tech lead agent into a project.
Open the A2A Agent Tool under the AI Agent and paste the Endpoint URL into Agent URL.
If the server has Require authentication on, add an A2A connection with the API key.
Add your Anthropic connection to the model.
Open the chat and ask: Which Spring Boot version first required Java 17?

The tech lead should call sendTaskToRemoteAgent. The server starts the release expert workflow, and the expert's answer comes back as the tool result. The tech lead builds its own answer on that reply and says it asked the remote agent.

Chat Memory lets you follow up with What would we need to change to move from Boot 2.7? without repeating the context.

Both templates run on the same ByteChef here, but nothing depends on that. The client only needs the Endpoint URL. The server could be another ByteChef instance, and the client could be any A2A client.

Subagents or A2A?

Both answer the same need: hand this to a specialist. The difference is distance.

	Subagents	A2A
The specialist is	An agent you define on this agent	Any A2A agent, anywhere
It runs	In the same workflow run	On its own server, reached over HTTP
It's built with	ByteChef	Anything that speaks A2A
The caller learns about it from	The subagent's definition	The remote agent's card
Use it when	The specialist is part of this agent	The specialist belongs to someone else, or serves many callers

The Java release expert fits A2A because many agents could use it. Serve it once, and every agent that needs release facts can call the same URL.

Spring AI vs. ByteChef setup

ByteChef uses the same A2A Java SDK as the Spring AI post: the same agent card, the same JSON-RPC transport, the same message types. A ByteChef agent can call any A2A agent, and any A2A client can call a ByteChef A2A Server.

What ByteChef adds is the product around it:

Serving an agent is configuration. Add a workflow to an A2A Server, and ByteChef builds the agent card, handles the JSON-RPC methods, and runs the workflow for each message.
Calling an agent is one tool. Paste a URL into the A2A Agent Tool. ByteChef reads the card, sends the message, and unwraps the reply.
Access is managed in the app. Turn on Require authentication and give callers an API key, without writing security code.

Wrapping up

Skills, questions, todo lists, and subagents all make one agent more capable. A2A lets it use agents it doesn't own, built on frameworks it has never seen.

Have a specialist other agents should be able to ask? Import the Java release expert and the Tech lead agent, connect them, and ask your first question across the wire.

This is Part 5 of our AI Agentic Patterns series. Part 1 covered Agent Skills, Part 2 covered asking the user, Part 3 covered todo lists, and Part 4 covered subagents. If you like where ByteChef is going, a star on GitHub helps a lot.

Originally published on the ByteChef blog.

Your AI agent is drowning in its own context. Give it a team.

ByteChef — Tue, 03 Nov 2026 10:37:25 +0000

You ask an agent to research three options and recommend one.

It gathers facts. Compares notes. Second-guesses itself. All of that lands in its context window.

Then it has to write the answer, with its attention split across everything it tried along the way.

The agent isn't too dumb. It's too cluttered.

If you've built anything agentic, you've hit this ceiling. Here's how subagents fix it, and how we run them in ByteChef, an open-source workflow automation and AI agent platform built on Java and Spring.

Two problems, one fix

The Spring AI team names both problems in their subagent post:

Context pollution. Intermediate steps cloud the main agent's reasoning.
The generalist bottleneck. One prompt tries to be good at every kind of work.

The fix is delegation. The main agent becomes an orchestrator. It hands focused jobs to subagents and keeps only what they report back.

Each subagent works in its own context, with its own instructions, model and tools. Its mess stays with it.

The example: research, then write

The Research and write with subagents template has three steps, with a small team inside the agent:

New Chat Request: a message arrives in the workflow chat.
AI Agent: the orchestrator. It runs on Claude Sonnet with Chat Memory for follow-up questions. Its Tools slot holds a Task Tool, and the Task Tool holds two Subagents.
Reply: the answer goes back to the chat.

The orchestrator's system prompt tells it not to do the work itself:

You are an orchestrator. Do not answer research questions yourself.
Delegate fact gathering to the researcher subagent, then pass its
findings to the writer subagent, and return the writer's answer.

The two subagents split the work by cost and quality:

Subagent	Model	When the orchestrator calls it
`researcher`	Claude Haiku 4.5	To gather facts and compare options before anything is written. Returns findings only, as short bullets.
`writer`	Claude Sonnet	After research is done, to turn findings into the final answer for the user.

Their system prompts are just as short:

# researcher
You are a fast, precise researcher. Collect the key facts needed to
answer the task. Return 5 to 10 short bullets with no introduction
and no conclusion. If you are unsure of a fact, say so.

# writer
You turn research findings into a clear answer for Java developers.
Short sentences, concrete, no marketing language. End with a one-line
recommendation.

Research is many small, factual steps, so it runs on a fast, cheap model. The answer is what the user reads, so it gets the stronger one. The orchestrator only coordinates.

How delegation works

The Task tool comes from the spring-ai-agent-utils library, which ByteChef ships. When a message arrives:

The orchestrator sees a catalog. The model gets a tool called Task. Its description lists every subagent by name and description. That's all the orchestrator knows about them, so the description decides who gets which job.
It delegates. The orchestrator calls Task with a subagent name and a prompt it writes for that job, for example "Compare Java 21 and Java 25 for a Spring Boot service".
The subagent works alone. ByteChef builds a fresh chat client with the subagent's own model and tools. Its instructions become the system prompt, and the orchestrator's prompt becomes the user message. It doesn't see the chat history or the orchestrator's other work.
Only the result comes back. The subagent's final text is the tool result. Whatever it did along the way stays in its own context.

In this template that means two calls:

orchestrator
  -> Task(researcher, research prompt)        returns short bullets
  -> Task(writer, prompt with those bullets)  returns the final answer

The orchestrator's context holds two short tool results, not the work behind them.

Here's the first Task call from a real test run, in the AI Agent's Logs tab. The orchestrator wrote a research-only prompt, and the researcher's findings came back as the tool's output.

There's a second tool too, TaskOutput. The library lets the orchestrator start a subagent in the background and collect its result later, so independent jobs can run at the same time.

Spring AI vs. ByteChef setup

ByteChef runs Spring AI's TaskTool and TaskOutputTool, so the delegation model is the same. What changes is where you define the team:

Spring AI	ByteChef
Register the Task tool and subagent types in code	One Task Tool on the agent
Write subagents as Markdown files or Java classes	Each subagent is a node with Name, Description and Instructions
Wire per-subagent models in Java	Attach a model to the subagent, or one to the Task Tool for all of them
Choose each subagent's tools in configuration	Attach tools to the subagent's Tools slot

On the canvas, you add the Task Tool to the AI Agent's Tools slot from the AI Agent Utils component, then add one Subagent per team member. Each subagent has three fields:

Name: the identifier the orchestrator uses, such as researcher.
Description: when to delegate to it. Write it like a job posting.
Instructions: its system prompt.

Two rules are worth knowing:

Models fall back, then fail. A model on the Task Tool is the default for every subagent without its own. If neither has one, the run stops with an error telling you to attach one.
Tools don't fall back at all. A subagent can't borrow the orchestrator's tools. It gets exactly what you attach. The template's subagents have none, so they work from their model's knowledge.

Workflow or subagents?

We've built orchestrator-workers before as a workflow pattern. There you lay out each step and wire the flow yourself. The Task Tool is the in-agent version: you define the team, and the agent decides at run time who does what, and in what order.

Use a workflow when the steps are fixed. Use subagents when the agent should plan the split itself.

Try it

You need an Anthropic API key.

Open the template and add it to a project.
Add your Anthropic connection to all three models: the orchestrator's and one on each subagent.
Open the chat and ask something that needs research first:

Should our Spring Boot service move from Java 21 to Java 25 this year?

The orchestrator should call researcher first and writer second. Ask a follow-up and Chat Memory keeps the conversation going, while each subagent call still starts from a clean context.

To watch the delegation, test the agent in the editor and open the tool-call cards. Each Task call shows which subagent ran, the prompt it got and what it returned.

If the orchestrator skips a subagent or calls the wrong one, its description is usually too vague.

Where to take it

Give the researcher real sources. Attach a web search or HTTP tool to it. Only the researcher can browse, and the pages it reads never reach the orchestrator.
Add a reviewer. A third subagent on a strong model checks the writer's answer against the research bullets and lists problems only.
Use one default model. Put a model on the Task Tool and remove the subagents' models. Keep one on a subagent only when it needs something different.
Mix with skills. One orchestrator can have both a Task Tool and the Skills Tool: skills for procedures, subagents for focused work in a clean context.

Wrapping up

An agent gets better by doing less itself.

Delegation isn't mainly about speed. It keeps each context clean and each prompt focused. The messy middle of every job happens somewhere else, and only the answer comes back.

Got an agent struggling with a job that's really three jobs? Import the template, ask it a question that needs research, and watch it hand the work out.

This is Part 4 of our AI Agentic Patterns series. Part 1 covered Agent Skills, Part 2 covered asking the user, and Part 3 covered todo lists. If you like where ByteChef is going, a star on GitHub helps a lot.

Originally published on the ByteChef blog.

Your AI agent skips steps. Give it a todo list.

ByteChef — Fri, 30 Oct 2026 13:28:26 +0000

You give an agent a real job: "audit these ten endpoints, fix the auth bug in each, run the tests, write up what changed."

It starts well. Six endpoints fixed, some tests run, a tidy summary. The last four endpoints? Never touched.

No crash. No error. It just lost track.

If you've built anything agentic, you've seen this. Here's a small tool that fixes most of it, and how we run it in ByteChef, an open-source workflow automation and AI agent platform built on Java and Spring.

Why agents drop steps

Language models pay less attention to whatever sits in the middle of a long context. As an agent works, its context fills with tool calls and results, and the original plan drifts into that middle zone.

The Spring AI team covered this in their TodoWrite post and borrowed the fix from Claude Code: don't keep the plan in your head. Write it down as a checklist and keep it current.

The TodoWrite tool

TodoWriteTool lives in the spring-ai-agent-utils library. The model sees a tool called TodoWrite. Every call sends the whole list, and each item has three fields:

content - the task as an instruction: "Update the Spring Boot version"
activeForm - the same task while it runs: "Updating the Spring Boot version"
status - pending, in_progress or completed

One rule does most of the work: only one task can be in_progress at a time. The tool rejects a list with two tasks in progress and tells the model to finish the current one first. That forces the agent to work in order instead of starting everything at once.

A few more details from the tool's instructions:

Use it for jobs with 3+ distinct steps, not for single simple requests. The agent decides when a job needs a plan.
Only mark a task completed when it's fully done. If tests fail or the work is partial, keep it in_progress.
If something blocks a task, add a new task for the blocker.

Why writing it down works

A checklist only helps if the agent keeps reading it. That's the real trick.

Each TodoWrite call carries the full current list in its arguments. During a run, the agent's tool-calling loop keeps every tool call and result in the conversation. So whenever the model picks its next step, the latest list is right there: three done, one in progress, six pending.

The plan can't fall out of attention because it gets written again on every update.

Spring AI vs. ByteChef setup

In plain Spring AI, you wire this up yourself: add the tool to a ChatClient, configure MessageChatMemoryAdvisor and ToolCallAdvisor so tool messages actually reach the model, and add chat memory if you want follow-ups.

In ByteChef, the AI Agent component already runs the tool-calling loop and keeps tool messages in the conversation. The Todo Write Tool is one element you drop into the agent's Tools slot. Here's the entire wrapper:

TodoWriteTool todoWriteTool = TodoWriteTool.builder()
    .build();

return ToolCallbackProvider.from(ToolCallbacks.from(todoWriteTool));

That's it. The library does the work, the AI Agent provides the loop.

	Spring AI	ByteChef
Add the tool	In code, on a `ChatClient`	Todo Write Tool element on an AI Agent
Tool messages reach the model	Configure advisors	Built into the agent loop
Chat memory	Add it yourself	Add a Chat Memory element

Same tool, same three statuses, same one-in-progress rule.

Try it: a Spring Boot 4 migration planner

Spring Boot 4 migrations are a good stress test. Lots of small steps (Java version, dependencies, Jakarta changes, config properties, tests), and skipping one is easy.

The Spring Boot 4 migration planner template is three steps:

New Chat Request - a message arrives in the workflow chat.
AI Agent - an Anthropic model, Chat Memory for follow-ups, and the Todo Write Tool.
Reply - the answer goes back to the chat.

The system prompt does the rest:

You are a senior Java engineer. For any request with 3 or more distinct
steps, first create a todo list with the TodoWrite tool. Keep exactly one
task in_progress at a time, mark each task completed as soon as it is done,
and update the list after every step. Finish with a short summary.

To run it:

Import the template into a project.
Add your Anthropic connection to the model under the AI Agent.
Open the workflow chat and ask for something multi-step, like: "Plan and walk me through migrating a Spring Boot 3.5 service on Java 17 to Spring Boot 4."

Before answering, the agent calls TodoWrite with a plan. Exact tasks depend on the model, but expect something like:

[ ] Upgrade the service to a supported Java version
[ ] Update the Spring Boot version and the dependency BOM
[ ] Fix renamed and removed configuration properties
[ ] Update tests and run the build
[ ] Summarize the changes

Here's the first TodoWrite call from a real test run, from the AI Agent's Logs tab. One task in progress, the rest pending:

Then it works through the list one task at a time, calls TodoWrite after each step, and ends with a summary. The Agent Playbook in the editor shows every update as a tool-call card, so you can watch the list change.

If the agent skips the list on a big job, make the request more explicit about its steps or tighten the system prompt.

Why it earns its place

It looks almost too simple to matter. On long tasks it's one of the most useful tools you can give an agent:

It fights lost-in-the-middle by design. The plan is rewritten on every update, so no step quietly disappears.
One task in progress keeps the agent focused. It finishes what it started instead of leaving half-done work.
It makes the work visible. You see what's done and what's next. That's the fastest way to check the agent understood the job.

It also pairs well with the other agent utils: File System, Shell, Grep and Glob tools give an agent hands. The todo list gives it a plan to use them on.

Wrapping up

The tools that make agents reliable are rarely the flashy ones. TodoWrite is a checklist, but one the agent writes itself and re-reads at every step. That's exactly what a long task needs.

Got an agent that drops steps on long jobs? Import the migration planner template, add your Anthropic connection, and give it a ten-step job.

This is Part 3 of our AI Agentic Patterns series. Part 1 covered Agent Skills. If you like where ByteChef is going, a star on GitHub helps a lot.

Originally published on the ByteChef blog.

Ask the User Before You Act: Human-in-the-Loop Questions for AI Agents with Spring AI

ByteChef — Fri, 30 Oct 2026 13:17:44 +0000

Every agent builder knows this failure mode. You give the agent a task, "plan our team offsite", and it just runs. It picks a city. It picks a budget. It picks the one week half the team is on holiday. Now you're not reviewing a plan. You're undoing one.

The Spring AI team put it well in their AskUserQuestionTool post: the AI makes assumptions, and each assumption creates rework. Their fix is a tool that flips the default. The agent asks first, and acts only once it has real answers.

ByteChef is an open-source workflow automation and AI agent platform built on Spring AI, so it runs the same tool. In Part 1 we gave agents know-how with skills. In this part we teach them to ask.

TL;DR: The Ask User Question Tool lets a ByteChef AI Agent stop and ask the user 1 to 4 multiple-choice questions before it acts. In a deployed chat, the workflow suspends for up to 30 days and resumes when the answers arrive. No thread is held while it waits. Try it with the offsite planner template.

The example: an offsite planner that asks first

The template has three steps:

New Chat Request - a message arrives in the workflow chat.
AI Agent - the Chat (stream) action with an Anthropic model, Chat Memory, and the Ask User Question Tool in its Tools slot.
Reply - the plan goes back to the chat.

The system prompt does the real work:

You plan team events. Never guess requirements. Before you plan anything,
call the AskUserQuestionTool once with three or four multiple-choice
questions covering budget, dates, team size and location. Offer 3 or 4
concrete options per question. After the answers arrive, produce a
one-page plan.

Two rules matter here:

"Never guess requirements" tells the model that asking is expected, not a failure.
"Call the tool once" stops it from asking one question at a time and dragging the conversation out.

What the model actually sees

The tool comes from Spring AI's spring-ai-agent-utils toolkit. The model sees a tool named AskUserQuestionTool that takes 1 to 4 questions. Each question has:

header - a short label, 12 characters max, like "Budget"
question - the question itself
options - 2 to 4 choices, each with a label and a description
multiSelect - for questions where more than one answer fits

For the offsite planner, a call looks roughly like this:

{
  "questions": [
    {
      "header": "Budget",
      "question": "What's the total budget for the offsite?",
      "multiSelect": false,
      "options": [
        { "label": "Under $5k", "description": "Local venue, day trips" },
        { "label": "$5k to $15k", "description": "Nearby city, one night" },
        { "label": "$15k+", "description": "Travel, multiple nights" }
      ]
    },
    {
      "header": "Dates",
      "question": "Which week works best?",
      "multiSelect": true,
      "options": [
        { "label": "Mid May", "description": "Before summer holidays" },
        { "label": "Early June", "description": "Good weather, busier venues" },
        { "label": "September", "description": "After holidays, everyone back" }
      ]
    }
  ]
}

The model writes these itself, from the user's request and your system prompt.

In plain Spring AI you'd also write a question handler: the code that shows the questions and collects the answers. On a console, that's reading a line from stdin. In a real product, the user might answer in ten seconds or tomorrow, from a different device. That gap is what ByteChef fills.

What happens when the agent asks

When the agent calls the tool, ByteChef sends the questions to the chat as an ask_user_question event. The chat renders each question with its header and a numbered list of options. You answer by typing, so you can pick an option or write your own answer.

Here's a real test run. Asked to plan a two-day offsite, the agent sent four questions instead of a plan:

What happens next depends on where the chat runs.

In a deployed workflow, the questions come with a resume URL and the workflow suspends. It isn't holding a thread. The run is persisted and can wait up to 30 days. When you answer, the chat posts to the resume URL, and the AI Agent picks up exactly where it stopped, with your answers as the tool result, and streams the plan back.

In the editor's test chat, there's no resume URL. The questions still show, but the agent is told to end its turn and read the answers from your next message. Because the template has Chat Memory, the agent still sees its own questions when your answer arrives, so it behaves the same.

This suspend/resume mechanism is the same one behind ByteChef's Approval component. Waiting for someone to approve and waiting for someone to answer are the same problem: a run that has to stop, wait for days, survive a restart, and continue on an outside signal.

Two limits worth knowing:

The tool needs the Chat (stream) action. With the non-streaming Chat action there's no way to deliver the questions, so the agent is told to proceed on its best judgment and state its assumptions.
If the questions can't be delivered, the agent gets the same instruction. It never waits for answers nobody can see.

Try it in 4 steps

The template needs only an Anthropic connection.

Import the template. Open Plan a team offsite with an agent that asks before it plans and add it to a project.
Connect the model. Add your Anthropic connection to the model under the AI Agent.
Test it in the editor. Open the chat and write "Plan an offsite for my team." You should get 3 or 4 questions back instead of a plan. Reply with your choices in one message and the agent writes the plan.
Deploy it. Deploy the project, open Chats in the Automation sidebar, and pick the workflow. Now the run really pauses while it waits for you.

Thanks to Chat Memory, you can ask for changes afterwards, like "move it to September", without starting over.

Why asking first matters

It's tempting to treat clarifying questions as polite extras. For agents, they're closer to a correctness tool:

They prevent rework. A wrong guess costs the failed step, the tokens spent getting there, and the turns you spend correcting it. One round of questions is cheaper.
They're a natural human-in-the-loop gate. For anything that matters, like spending money, emailing a customer, or deleting records, "ask before acting" is the safe default.
They don't tie anything up. A deployed run actually suspends. The agent can wait days without holding a worker.

Spring AI vs. ByteChef: what you get for free

The Spring AI post ends where a library ends: here's the tool, write a handler. Here's what ByteChef adds on top:

Plain Spring AI	ByteChef
You implement the question handler	Built in
A console handler blocks the current thread	Deployed workflow suspends up to 30 days and frees the worker
Getting questions to a UI is your job	Streamed to the chat, run resumes when the answer is posted back
Adding the tool means code and config	One tool on the AI Agent

The question format, the library, and model portability stay the same. The template uses Claude, but the tool works with any model provider ByteChef supports.

Wrapping up

The most useful agent behaviors are often the boring ones. "Ask before you assume" isn't flashy, but it's the difference between an agent whose work you undo and one whose work you can trust.

Import the offsite planner template, add your Anthropic connection, and ask it to plan your next offsite. Then add the Ask User Question Tool to your own agents wherever a guess would be expensive.

If you like where this is going, a star on GitHub helps a lot.

Originally published on the ByteChef blog.

Turn One Sentence Into a Working Automation: Prompt-to-Workflow in Your SaaS

ByteChef — Fri, 30 Oct 2026 12:51:44 +0000

Originally published on the ByteChef blog. Part 10 of the ByteChef Embedded series.

Some automation requests are fuzzy. Those deserve a conversation. But a lot of them aren't:

"When a lead comes in, post it to #sales and email them a welcome note."

That's already a full spec. A chat would only slow the user down.

So we built New from Prompt: the user writes a sentence, clicks Generate, and gets a finished, validated workflow back. Your app makes one HTTP call. No streaming, no transcript, no client-side AI code.

Here's how it works and what it takes to ship it in your own product.

TL;DR

One request: POST /api/embedded/v1/automation/workflows/generate with {prompt, systemPrompt?}, signed with the connected user's JWT.
ByteChef creates a draft workflow in the user's own project, runs its workflow agent in autonomous mode, and returns the new workflow's UUID once it's built and validated.
The agent only uses integrations you enabled plus connection-free components (webhooks, schedules, conditions, loops).
The result is a draft. Nothing runs until the user reviews and publishes it.

Where it fits

ByteChef Embedded gives your users five ways to create a workflow:

Option	The user...	Best when
New from Template	Picks a workflow you built	You know the common automations up front
New from Embedded Workflow Builder	Drags nodes on ByteChef's canvas	The user is comfortable with visual builders
New from Prompt	Writes one description, gets one workflow	The request is short and clear
New from Chat	Talks it through with an agent	The request is fuzzy
New from Custom Workflow Builder	Fills in a UI you designed	You want full control

Prompt is the lowest-effort AI option, for the user and for you.

The dialog

Two fields: what the user wants, and an optional system prompt with your house rules.

The form rejects anything under ten characters, so "Slack" alone doesn't hit the server:

While ByteChef works, the button reads "Generating...". When the UUID comes back, the dialog closes and the list reloads. Our lead workflow took 47 seconds.

The component is a plain react-hook-form dialog:

const formSchema = z.object({
    prompt: z.string().min(10, 'Please describe the workflow in a sentence or two.'),
    systemPrompt: z.string().optional(),
});

const handleSubmit = async (values: FormValues) => {
    setError(null);
    setIsSubmitting(true);

    try {
        const workflowUuid = await generateWorkflow(values.prompt, values.systemPrompt);

        form.reset();
        onClose();
        onWorkflowGenerated(workflowUuid);
    } catch (e) {
        setError(e instanceof Error ? e.message : 'Failed to generate workflow. Please try again.');
    } finally {
        setIsSubmitting(false);
    }
};

All the AI lives on the server. The browser collects two strings and waits.

One call

export async function generateWorkflow(prompt: string, systemPrompt?: string): Promise<string> {
    const trimmed = systemPrompt?.trim();

    const response = await fetchWithAuth('/api/embedded/v1/automation/workflows/generate', {
        method: 'POST',
        headers: {'Content-Type': 'application/json'},
        body: JSON.stringify(trimmed ? {prompt, systemPrompt: trimmed} : {prompt}),
    });

    if (!response.ok) {
        throw new Error(`Failed to generate workflow: ${response.status}`);
    }

    const uuid = (await response.text()).trim();

    return uuid.startsWith('"') && uuid.endsWith('"') ? uuid.slice(1, -1) : uuid;
}

On the wire:

POST /api/embedded/v1/automation/workflows/generate
Authorization: Bearer <connected user's JWT>
X-Environment: DEVELOPMENT
Content-Type: application/json

{
  "prompt": "When a new lead arrives on a webhook with name, email and company, post it to the #sales Slack channel and send the lead a short welcome email from Gmail.",
  "systemPrompt": "Always notify the team in Slack, never by email. Keep workflows under five steps."
}

HTTP/1.1 200 OK
Content-Type: application/json

"8b0c5d1e-..."

Two things to know:

It's synchronous. ByteChef answers when the agent is done. Small workflows take under a minute, big ones several. The server waits up to ten minutes.
Send X-Environment. It defaults to PRODUCTION, which is rarely what you want while developing.

Four shapes of the same endpoint

Called from	Create new	Rebuild existing
Browser (user's JWT)	`POST /automation/workflows/generate`	`POST /automation/workflows/{uuid}/generate`
Your backend (API key)	`POST /{externalUserId}/automation/workflows/generate`	`POST /{externalUserId}/automation/workflows/{uuid}/generate`

The rebuild form powers a "Change it with AI" button: same UUID, rewritten definition. The backend form lets your server generate a starter automation right after onboarding, so the user's Automations page isn't empty on day one.

What happens on the server

Resolve user and project. ByteChef reads the external user ID from the JWT and finds (or creates) their personal project for that environment.
Create a draft. An empty workflow is saved first, labeled with the user's prompt (cut to 80 chars).
Build the allow-list. Every component with an enabled integration in this environment, plus every connection-free component.
Run the agent autonomously. The same BUILD agent behind New from Chat and ByteChef's Copilot, with autonomous: true.
Return the UUID. On failure or timeout, the draft is deleted. A failed generation leaves nothing behind.

Autonomous mode

In autonomous mode the agent:

never asks follow-up questions; it picks the most common, sensible default
never pauses to show a plan
keeps the label it was given
saves once, at the end, after the full workflow validates

Otherwise it's the same agent: it searches the catalog (searchTask, listTasks), reads definitions (getTaskDefinition, getTaskProperties), validates each task (validateTask), then validates the whole workflow before saving. What you get back isn't a guess at JSON. It passed the same validator as a hand-built workflow.

Where the chat agent would stop and show a channel picker or a "Connect Slack" card, the prompt agent picks a value, builds the step, and leaves the connection for the user to choose in the editor.

Your house rules: the system prompt

The user decides what the workflow does. You decide how it's built:

Always notify the team in Slack, never by email.
Keep workflows under five steps.
Use the Europe/Berlin time zone for every schedule unless the user names another.
Never delete records in the CRM; update a status field instead.

Note how this plays with our example. The user asked for a welcome email to the lead; the rule says "never by email". The agent read the rule the way a colleague would: it's about notifying the team. It built three steps: webhook trigger, Slack message to #sales, Gmail welcome email to the lead.

How ByteChef treats it:

Trimmed and capped at 4,000 characters.
Applies to one generation only. Nothing is stored, so send it every time.
Appended under a heading marking it as integrator instructions, applied only where it doesn't conflict with build rules, the workflow contract or safety constraints. It steers the agent; it can't hijack it.

In the sample it's a text box so you can play with it. In production, generate it in your code from your conventions and what you know about the user. Don't hand it to end users.

Security boundaries

Anyone with a connected user's JWT can call this with any text. So ByteChef trusts nothing in the request except the two strings:

The workflow is always the user's. Rebuild looks the UUID up inside the user's project only.
Agent state is built server-side. Mode, workflow ID, project and environment don't come from the request.
The agent stays in the user's project. No touching other workflows, no project-level changes.
The allow-list is enforced everywhere. Components outside it don't show up in search, can't be looked up, and are rejected on validation, including inside conditions, loops and AI agent nodes.

That last one matters more here than in chat. A chat agent asked for "Salesforce deals to Slack" when you don't offer Salesforce can ask what to do instead. A prompt agent can't ask, so it never produces nodes for apps your users can't connect.

Handing off to the editor

The generated workflow is a real ByteChef workflow, so send the user straight to the editor:

const router = useRouter();

<GenerateWorkflowDialog
    // ...
    onWorkflowGenerated={(workflowUuid) => router.push(`/automations/${workflowUuid}`)}
/>

Here's what the agent built from the lead prompt:

It set the Slack channel to sales, wrote a message referencing the webhook payload (${autoRespondWithHTTP200_1.body.name} and friends), addressed the Gmail step to the lead, and even added a workflow description.

The editor shows what's left:

2 errors: the Slack and Gmail connections. The agent can't pick accounts for the user. With connectionDialogAllowed={true}, they connect right there.
5 warnings: webhook fields. A webhook payload has no fixed shape, so the editor reminds you to check body.name, body.email and body.company.

Draft to running

Generated workflows are drafts. Nothing runs until published and enabled, which is the right default for something an AI just wrote:

await fetchWithAuth(`/api/embedded/v1/automation/workflows/${workflowUuid}/publish`, {
    method: 'POST',
    headers: {'Content-Type': 'application/json'},
    body: JSON.stringify({description: 'Generated from prompt'}),
});

await fetchWithAuth(`/api/embedded/v1/automation/workflows/${workflowUuid}/enable`, {method: 'POST'});

Prompt vs. Chat

	New from Prompt	New from Chat
Requests	One POST, one JSON response	One AG-UI stream per turn
Agent mode	Autonomous, picks defaults	Interactive, asks questions
Missing connection	Builds the step, user connects in editor	Shows a Connect card in the thread
Code in your app	A form and a fetch	A chat component and its deps
Best for	Clear, short requests	Fuzzy requests

They combine well: generate a first version from a prompt, then offer "Change it with AI" via the rebuild endpoint.

Prerequisites

bytechef.ai.copilot.enabled=true
An AI provider configured for the environment
Integrations enabled for the environment (without them, the agent can still build schedules, webhooks and logic)

Embedded workflows and workflow generation are Enterprise Edition features.

Before you ship it

Raise timeouts on every proxy, load balancer and serverless function in the path (many stop at 30 or 60 seconds), or call the backend endpoint from a job and notify the user.
Show real progress. "Generating..." is fine for ten seconds, not two minutes.
Map errors to messages users can act on.
Redirect to the editor with the returned UUID.
Own the system prompt in code.
Send X-Environment explicitly.
Rate-limit generation. Every request burns model tokens on your AI provider account.
Seed better examples. Use your own integrations in the placeholder, or offer clickable starter prompts.

Who owns what

You: the button, the form, the system prompt, which integrations are enabled, the waiting experience, what happens with the UUID.

ByteChef: the per-user project and draft, the agent and its tools, catalog search and validation, the allow-list and security boundary, the editor, ConnectDialog and credential storage, and the engine that runs the result.

Your code is a form, one fetch and a redirect. Behind it is an agent that knows every action in your catalog.

Try it

Enable the copilot and an AI provider in ByteChef, run the embedded sample app, and open Automations → New from Prompt. Describe something small with one of your connected apps and click Generate.

ByteChef is open source (Apache 2.0). If this was useful, a ⭐ on GitHub helps a lot.

The full series: connect apps, ComponentKit, AI chat assistant, event triggers, workflows as APIs, MCP agents, custom builder, templates, New from Chat, and New from Prompt. All on the ByteChef blog.

Run a ByteChef workflow like a CLI command (no server, no database)

ByteChef — Tue, 20 Oct 2026 20:15:17 +0000

Most automation platforms are built to stay up. ByteChef is no exception: the server stores your projects, fires triggers, listens for webhooks, and records every execution in PostgreSQL.

That's great until you look at where a lot of real work runs:

a nightly batch sitting in a Kubernetes CronJob next to twenty others, with alerting on failed pods
a CI step that should go red when something breaks
one task inside an Airflow DAG
a product with its own job runner that just wants to execute a workflow

In each of those, a standing server plus a database plus a message broker is overhead. You need the engine for the length of one run, and then you want it gone.

That's what the Runtime Job app does. You pass it a workflow name, inputs as JSON, and credentials as JSON. It boots the full Atlas engine in one JVM, runs the workflow to completion, and exits 0 or 1. Nothing to provision, nothing to clean up.

The Runtime Job app is part of ByteChef's Enterprise Edition. Source: server/ee/apps/runtime-job-app.

Same engine, different packaging

This isn't a lightweight interpreter. The coordinator, workers and task dispatchers are all there. What changes is everything around them:

	ByteChef server	Runtime Job app
Execution state	PostgreSQL	In memory, gone on exit
Message broker	Redis, Kafka, SQS, RabbitMQ, JMS…	In-process
Connections	Encrypted store in the DB	JSON passed at launch
Triggers	Scheduler, polling, webhooks	None. The run starts with the process
UI / API	Yes	No
Record of a run	Execution history	Exit code + log

The workflow JSON is identical in both, so the loop is: build and test in ByteChef, export, hand the file to the Runtime Job app.

A real example

A daily sales report: take a date, total the paid orders for that day from PostgreSQL, log a summary.

{
  "label": "Daily Sales Report",
  "inputs": [
    { "name": "reportDate", "label": "Report date", "type": "string", "required": true }
  ],
  "triggers": [
    { "label": "Manual", "name": "trigger_1", "type": "manual/v1/manual" }
  ],
  "tasks": [
    {
      "label": "Sum paid orders",
      "name": "postgresql_1",
      "type": "postgresql/v1/query",
      "parameters": {
        "query": "SELECT count(*) AS orders, coalesce(sum(total), 0) AS revenue FROM orders WHERE status = 'PAID' AND created_at = CAST(:reportDate AS date)",
        "parameters": { "reportDate": "${reportDate}" }
      }
    },
    {
      "label": "Log summary",
      "name": "logger_1",
      "type": "logger/v1/info",
      "parameters": {
        "text": "Sales for ${reportDate}: ${postgresql_1[0].orders} paid orders, revenue ${postgresql_1[0].revenue}"
      }
    }
  ]
}

Save it as ~/bytechef/data/workflows/daily-sales.json (the default lookup location). Note the task name postgresql_1 and component name postgresql; both matter for connections later.

Build and run:

./gradlew :server:ee:apps:runtime-job-app:bootJar

CONNECTIONS='{"postgresql": {"host": "localhost", "port": 5432, "database": "shop", "username": "etl", "password": "..."}}'

java -jar runtime-job-app.jar \
  --workflow=daily-sales.json \
  --parameters='{"reportDate": "2026-10-14"}' \
  --connections="$CONNECTIONS"

echo $?   # 0

On a laptop the whole thing took about 10 seconds, roughly one of which was the workflow itself. That's the trade: a few seconds of boot for zero standing infrastructure. Fine for a nightly batch; for a thousand calls a minute, use the server.

The flags

Flag	Required	What it does
`--workflow=<file>`	yes	File name, e.g. `daily-sales.json`. A lookup key, not a path.
`--parameters=<json>`	no	Workflow inputs as a JSON object.
`--connections=<json>`	no	Connection name → parameters. Repeatable; objects are merged.
`--timeout=<duration>`	no	`30s`, `15m`, `1h`. Exit `1` if exceeded.
`--outputs-file=<path>`	no	Write the workflow's outputs as JSON on success.

Any Spring Boot property works too, e.g. --logging.level.com.bytechef=DEBUG.

Gotcha: `--workflow` is not a path

The app drops the directory, strips the extension, and Base64-encodes the rest into an id (daily-sales → ZGFpbHktc2FsZXM=). At startup it indexes every file in the enabled workflow repositories the same way, then looks the id up. So these are identical:

--workflow=daily-sales.json
--workflow=/anything/at/all/daily-sales.json

…and pointing at a file outside the repositories won't work. Repositories available: filesystem (default, ~/bytechef/data/workflows), classpath (workflows/ inside the JAR), and Git (off by default).

# read workflows from somewhere else
BYTECHEF_WORKFLOW_REPOSITORY_FILESYSTEM_LOCATION_PATTERN='/opt/workflows/*.json'

# or straight from Git, so a merge to main is a deploy
BYTECHEF_WORKFLOW_REPOSITORY_GIT_ENABLED=true
BYTECHEF_WORKFLOW_REPOSITORY_GIT_URL=https://github.com/acme/workflows.git
BYTECHEF_WORKFLOW_REPOSITORY_GIT_BRANCH=main

Tip: export workflows from the editor rather than hand-writing them. Component defaults are written into the JSON when you add a node, not at runtime, so a hand-written file can fail mid-run with Unknown value for : <property>.

Connections

No credential store means credentials arrive as JSON. Keys are connection names; values use the same property names as the component's connection form in the UI.

Before each task runs, its connection is resolved like this:

By task name (postgresql_1) — applies to that task only.
By component name (postgresql) — shared by every task of that component.
No match — the task runs without one (fine for logger, fatal for a database).

Task-name keys let two tasks of the same component use different credentials, say a read replica and a primary. And you can split credentials across secrets by repeating the flag:

java -jar runtime-job-app.jar \
  --workflow=daily-sales.json \
  --connections="$OPENAI_CONNECTION" \
  --connections="$POSTGRES_CONNECTION"

Two caveats worth knowing up front:

Connection JSON is logged at INFO on startup. Treat the log as credential-bearing: restrict access and set retention.
Not every connector works this way yet. Database components (PostgreSQL, MySQL) and LLM providers that take an API key work. SaaS connectors whose auth is applied as an HTTP header by the platform (bearer, API key, OAuth2) don't get that header from --connections. Test before relying on them.

Exit codes are the API

Code	Meaning
`0`	Job `COMPLETED`
`1`	Job `FAILED` or `STOPPED`, or `--timeout` hit
other non-zero	Couldn't start: missing flag, bad JSON, unknown workflow
`143`	Killed by SIGTERM (eviction, drain, `docker stop`)

That's all a scheduler needs. A Kubernetes Job retries per backoffLimit, Airflow marks the task failed, CI goes red. Nobody parses logs.

Always set --timeout. Without it the app waits forever, and a stuck process is never retried because it never fails. This matters doubly for JavaScript/Python script tasks, which have no CPU or heap cap of their own.

Make writes idempotent. A 143 leaves no trace in the log, and a retry starts from scratch. Prefer upserts or check for an existing result.

Getting results out

Declare outputs in the workflow as usual:

"outputs": [
  { "name": "orders",  "value": "${postgresql_1[0].orders}" },
  { "name": "revenue", "value": "${postgresql_1[0].revenue}" }
]

They're logged as one JSON line on completion. For programs, use --outputs-file:

java -jar runtime-job-app.jar ... --outputs-file=/tmp/daily-sales.json
jq .revenue /tmp/daily-sales.json   # 1540.50

The file is only written for a completed job, so check the exit code first. Keep outputs small (counts, ids, a status); write anything big to where it's used and return a pointer.

Docker

docker build -t registry.example.com/bytechef-runtime-job:2026-10-16 server/ee/apps/runtime-job-app/

docker run --rm \
  -v "$(pwd)/workflows:/workflows" \
  -e SPRING_PROFILES_ACTIVE=prod \
  -e BYTECHEF_WORKFLOW_REPOSITORY_FILESYSTEM_LOCATION_PATTERN='/workflows/*.json' \
  registry.example.com/bytechef-runtime-job:2026-10-16 \
  --workflow=daily-sales.json \
  --parameters='{"reportDate": "2026-10-14"}' \
  --connections="$CONNECTIONS"

The image is about 2 GB (GraalVM base + a ~770 MB JAR with ~100 components and the polyglot runtime). Use immutable tags with imagePullPolicy: IfNotPresent so each node pulls it once. Use the prod profile; local builds default to dev, which logs at DEBUG.

Kubernetes CronJob

This is where it fits best: a pod starts, runs one workflow, exits, and the exit code decides whether Kubernetes retries.

apiVersion: batch/v1
kind: CronJob
metadata:
  name: daily-sales
spec:
  schedule: "15 6 * * *"
  concurrencyPolicy: Forbid
  jobTemplate:
    spec:
      backoffLimit: 2
      template:
        spec:
          restartPolicy: Never
          containers:
            - name: runtime-job
              image: registry.example.com/bytechef-runtime-job:2026-10-16
              imagePullPolicy: IfNotPresent
              command: ["/bin/sh", "-c"]
              args:
                - >-
                  exec java -jar /opt/bytechef/runtime-job/runtime-job-app.jar
                  --workflow=daily-sales.json
                  --parameters="{\"reportDate\": \"$(date -d yesterday +%F)\"}"
                  --connections="$POSTGRES_CONNECTION"
                  --timeout=20m
              env:
                - name: SPRING_PROFILES_ACTIVE
                  value: prod
                - name: BYTECHEF_WORKFLOW_REPOSITORY_FILESYSTEM_LOCATION_PATTERN
                  value: /workflows/*.json
                - name: POSTGRES_CONNECTION
                  valueFrom:
                    secretKeyRef:
                      name: daily-sales-connections
                      key: postgresql.json
              resources:
                requests: { cpu: 500m, memory: 768Mi }
                limits:   { memory: 1Gi }
              volumeMounts:
                - name: workflows
                  mountPath: /workflows
          volumes:
            - name: workflows
              configMap:
                name: daily-sales-workflow

Why it looks like this:

restartPolicy: Never + backoffLimit — exit 1 fails the pod; each retry is a clean process.
--timeout — backoffLimit only retries failed pods, not stuck ones. (activeDeadlineSeconds works too, but it kills the pod with a silent 143.)
Memory — a small workflow used ~370 MiB. Measure a real run and size from that; OOMKilled exits 137.
sh -c + exec — computes yesterday's date, and exec keeps the JVM's exit code as the pod's.
Secret + ConfigMap — credentials stay out of the manifest; updating the workflow is a kubectl apply, not an image rebuild.

CI

Exit codes make it a normal CI step. GitHub Actions, generating release notes on every tag:

name: Release notes
on:
  push:
    tags: ['v*']

jobs:
  notes:
    runs-on: ubuntu-latest
    container:
      image: registry.example.com/bytechef-runtime-job:2026-10-16
    steps:
      - uses: actions/checkout@v4
      - name: Generate and publish release notes
        env:
          SPRING_PROFILES_ACTIVE: prod
          BYTECHEF_WORKFLOW_REPOSITORY_FILESYSTEM_LOCATION_PATTERN: ${{ github.workspace }}/.bytechef/*.json
          OPENAI_CONNECTION: ${{ secrets.BYTECHEF_OPENAI_CONNECTION }}
        run: |
          java -jar /opt/bytechef/runtime-job/runtime-job-app.jar \
            --workflow=release-notes.json \
            --parameters="{\"tag\": \"${GITHUB_REF_NAME}\"}" \
            --connections="$OPENAI_CONNECTION" \
            --timeout=10m

The workflow lives in .bytechef/ in the repo it automates and gets code-reviewed like everything else. Same idea works in GitLab CI, Jenkins, or Airflow's KubernetesPodOperator.

What's in, what's out

In: ~100 components — HTTP client, script and Bash, helpers, CSV/JSON/XML/XLSX, PostgreSQL and MySQL, the major LLM providers, Google Workspace and Microsoft 365 basics, Slack, GitHub, Jira, HubSpot, Shopify — plus control flow (branch, condition, each, loop, map, parallel, fork-join, subflow, approval). Check the app's build.gradle.kts before depending on a specific one.

Out, on purpose: triggers, the UI and REST API, execution history (ship your logs somewhere), and scaling within a run (launch more processes instead).

Quick troubleshooting

Symptom	Fix
`Workflow with id: <base64> does not exist`	File isn't in a configured repository (or the volume isn't mounted). The directory in `--workflow` is ignored.
`Unknown value for : <property>`	Re-export the workflow from the editor.
Auth error on a task	Connection key doesn't match task/component name, or property names are wrong.
Process never exits	Add `--timeout`.
Exit `143`, nothing in log	SIGTERM from outside. Check pod events.
Exit `137` / OOMKilled	Raise the memory limit (and `-Xmx`).
No outputs file	The job didn't complete. Check the exit code.

Server or Runtime Job?

Use the server when you need triggers, webhooks, a UI, run history, RBAC, a central credential store, or always-on/high-frequency processing.

Use the Runtime Job app for nightly batches, CI steps, and anything whose schedule already lives in Kubernetes, Airflow or GitHub Actions.

They're not competitors. A common setup: people build and test on a ByteChef server, and CronJobs run the exported, reviewed versions in production. Same JSON, unchanged.

Full reference: Runtime Job Runner docs. Originally published on the ByteChef blog.

Let Your Users Talk a Workflow Into Existence (ByteChef Embedded, Part 9)

ByteChef — Fri, 16 Oct 2026 19:34:07 +0000

Your users rarely know their automation up front. They discover it while they describe it: "when a deal closes... actually only enterprise deals... and loop in the account manager... and skip weekends."

A template can't handle that. A drag-and-drop canvas scares half of them off. So in part nine of the ByteChef Embedded series, we give them a chat: they describe what they want, and ByteChef's workflow agent builds it in their account while they watch.

On your side, it's one React component, one callback and a button.

TL;DR

EmbeddedWorkflowChat takes the connected user's JWT, starter suggestions, an optional system prompt, and an onWorkflowReady callback.
On mount it creates an empty draft workflow. The agent edits that draft directly, turn by turn.
Every turn streams over AG-UI from POST /automation/workflows/{uuid}/copilot/chat.
When the agent needs something, it renders a card in the thread: a question, an option picker, a connection picker, or a Connect button.
After the first turn, onWorkflowReady(uuid) fires and you can send the user to the editor.

Where chat fits

In the embedded sample app, open Automations. The split button lists every way to start a workflow:

Option	The user...	Best when
New from Template (part 8)	Picks a workflow you built	You know the common automations
New from Embedded Workflow Builder	Drags nodes on ByteChef's canvas	The user likes visual builders
New from Prompt	Writes one description, gets one result	The request is short and clear
New from Chat (this part)	Talks it through with an agent	The request is fuzzy, or the user doesn't know the apps' vocabulary
New from Custom Workflow Builder (part 7)	Fills in a UI you designed	You want full control

Chat is the most forgiving option. Your users don't need to know Slack's action is called Send Channel Message or that a schedule trigger has a dayOfWeek property. The agent knows. When it isn't sure what they mean, it asks.

The page

Click New from Chat and you land on /automations/chat:

Three parts:

A collapsed System prompt (optional) field where you, the integrator, add house rules.
The chat, centered while empty.
Suggestion chips. Clicking one sends it as the first message, so a blank chat isn't intimidating.

Once the conversation starts, the composer docks to the bottom. After the first turn, an Open workflow button appears top right.

Mounting the component

Here's app/automations/chat/page.tsx, trimmed:

export default function GenerateFromChatPage() {
    const [jwtToken, setJwtToken] = useState<string | null>(null);
    const [systemPrompt, setSystemPrompt] = useState('');
    const [workflowUuid, setWorkflowUuid] = useState<string | null>(null);

    const router = useRouter();

    useEffect(() => {
        getToken().then(setJwtToken);
    }, []);

    return (
        <div className="flex h-screen w-full flex-col p-4">
            <div className="mb-3 flex items-center justify-between gap-4">
                <details className="flex-1 text-sm">
                    <summary>System prompt (optional)</summary>

                    <Textarea
                        onChange={(event) => setSystemPrompt(event.target.value)}
                        placeholder="e.g. Always prefer Slack over email; keep workflows under five steps."
                        value={systemPrompt}
                    />
                </details>

                {workflowUuid && (
                    <Button onClick={() => router.push(`/automations/${workflowUuid}`)}>Open workflow</Button>
                )}
            </div>

            <div className="min-h-0 flex-1">
                {jwtToken && (
                    <EmbeddedWorkflowChat
                        baseUrl={BYTECHEF_APP_BASE_URL}
                        environment={BYTECHEF_ENVIRONMENT}
                        jwtToken={jwtToken}
                        onWorkflowReady={setWorkflowUuid}
                        suggestions={[
                            {
                                title: 'Search for an action',
                                label: 'that can send an email',
                                action: 'Search for an action that can send an email',
                            },
                            // ...
                        ]}
                        systemPrompt={systemPrompt}
                    />
                )}
            </div>
        </div>
    );
}

getToken() asks the sample's back-end to sign a connected-user JWT, the same as in part one. The chat waits for the token, because everything it does is on behalf of that user.

Props

Prop	Type	What it does
`jwtToken`	`string` (required)	The connected user's JWT, sent as `Authorization: Bearer ...`
`baseUrl`	`string`	Your ByteChef instance. Defaults to `https://app.bytechef.io`
`environment`	`'DEVELOPMENT' \	'STAGING' \
{% raw %}`suggestions`	`{title, label, action}[]`	Starter chips. `action` is the message that gets sent
`systemPrompt`	`string`	Your house rules, applied to every turn
`onWorkflowReady`	`(workflowUuid: string) => void`	Called once, after the first turn
`className`	`string`	Extra classes for the container

The component fills its parent's height, so give the parent one (the sample uses min-h-0 flex-1 inside an h-screen column).

It's source, not a package

Unlike useConnectDialog or EmbeddedWorkflowBuilder, the chat isn't an npm export. It lives in the sample app under front-end/src/components/embedded-workflow-chat/, and you copy the folder:

embedded-workflow-chat/
├── index.ts
├── EmbeddedWorkflowChat.tsx           # the public component
├── EmbeddedCopilotRuntimeProvider.tsx # AG-UI agent and event handling
├── workflow-chat-thread.tsx           # messages, composer, chips
├── dataComponents.tsx                 # interactive cards
├── store.ts                           # zustand transcript store
├── api.ts, constants.ts               # skeleton workflow, endpoints
├── chat-config-context.tsx            # JWT, base URL, environment for cards
├── EmbeddedChatBoundary.tsx           # error boundary
└── assistant-ui/                      # markdown, tool card, reasoning renderers

That's on purpose. A chat is the most visible thing in your product, so it should look like your product, not ours. It's built on assistant-ui primitives with Tailwind, so restyling is ordinary React work.

Dependencies: @ag-ui/client, @assistant-ui/react, @assistant-ui/react-markdown, zustand, lucide-react, tailwind-merge, and @bytechef/embedded for the ConnectDialog.

On mount: a skeleton workflow

The agent doesn't generate a workflow and hand it back at the end. It edits a real one, in place, during the conversation. So before the user types anything, the component creates it:

export const SKELETON_WORKFLOW_DEFINITION = JSON.stringify({
    description: '',
    inputs: [],
    label: 'New Workflow',
    tasks: [],
    triggers: [],
});

const response = await fetch(`${baseUrl}/api/embedded/v1/automation/workflows`, {
    method: 'POST',
    headers: {
        Authorization: `Bearer ${jwtToken}`,
        'Content-Type': 'application/json',
        'X-Environment': environment,
    },
    body: JSON.stringify({definition: SKELETON_WORKFLOW_DEFINITION}),
});

const workflowUuid = (await response.text()).replace(/"/g, '').trim();

The draft lands in the connected user's personal project for that environment. While the request runs, the component shows Starting.... If it fails (expired JWT, wrong baseUrl), the error shows in red instead of the chat.

That UUID anchors the whole conversation. A ref latch makes sure only one skeleton is created, even under React StrictMode.

One thing to plan for: every visit creates a draft, even if the user leaves without typing. More on that in Hardening.

On each turn: AG-UI streaming

When the user sends a message, the component posts the conversation with an AG-UI HttpAgent:

const agent = new HttpAgent({
    agentId: 'workflow_editor',
    url: `${baseUrl}/api/embedded/v1/automation/workflows/${workflowUuid}/copilot/chat`,
    headers: {
        Authorization: `Bearer ${jwtToken}`,
        'X-Environment': environment,
    },
    threadId: conversationId,
});

agent.setState(
    trimmedSystemPrompt
        ? {additionalSystemPrompt: trimmedSystemPrompt, mode: 'BUILD', workflowUuid}
        : {mode: 'BUILD', workflowUuid}
);

await agent.runAgent({runId: randomUUID()}, subscriber);

Of that state, the server uses only the system prompt. It rebuilds everything else itself (see What the agent can and can't do).

The response is a text/event-stream. The subscriber turns events into UI:

AG-UI event	What the user sees
`TEXT_MESSAGE_START`, `_CONTENT`, `_END`	An assistant message, streamed token by token
`TOOL_CALL_START`, `_ARGS`, `_END`	A tool card (e.g. `searchTasks`, `updateWorkflow`) with its arguments filling in live
`TOOL_CALL_RESULT`	The card gets its result and a success or error icon. Interactive results add a card below
`RUN_ERROR`	A red callout, e.g. The copilot run failed. Reference: 3f2b...
`RUN_FINISHED`	The turn is over. The first time, `onWorkflowReady` fires

The server closes the open text message whenever the agent calls a tool, so a turn reads in the order it happened: "Let me find the right trigger", the tool cards, then the next message.

Errors users can act on

When a run fails for a reason the user can do something about, ByteChef sends a fixed sentence plus the run ID:

Cause	What the user reads
No AI provider for the environment	No AI provider is set up for this environment, so the chat can't answer.
Rate limiting	The AI provider is rate limiting requests right now. Try again in a minute.
Overloaded	The AI provider is overloaded right now. Try again in a minute.
Bad API key	The AI provider rejected its API key. Ask an administrator to check it.
Context too long	This conversation is too long for the AI model. Start a new chat.

Anything else reads The copilot run failed. Reference: .... The text is fixed, never the exception message, because exceptions can name tables, internal hosts or keys. The full cause goes to the server log under the same run ID. When a user reports a failure, ask for the reference and grep for it.

The controls users expect

Stop aborts the run.
Edit on a user message rewinds and reruns from there.
Refresh regenerates the last assistant message.
Copy and Export as Markdown under assistant messages.

Edit and Refresh rewind the agent too, not just the screen. The agent's memory lives on the server, keyed to the user, the workflow and the conversation. Before each run, ByteChef trims that memory back to the last user message both sides agree on. The server only ever removes messages this way. It never takes the client's word for what was said.

Interactive cards: when the agent needs the user

A text-only agent would ask "which channel? please type its exact name" and hope. Instead, some tools return a small JSON envelope with a kind, and the chat renders a card for it:

{
    "kind": "create-connection",
    "componentName": "slack",
    "componentLabel": "Slack"
}

Here the agent looked up the trigger, then stopped to ask which time zone "9am" means:

The sample maps four kinds in dataComponents.tsx:

`kind`	Card	On click
`ask-user-question`	Multiple-choice questions, one at a time (Question 1 of 3, Previous)	Answers go back as "User picked: ..."
`select-property-option`	Searchable list of valid values, like Slack channels or Google Sheets	The label and real value go back, and the agent writes the value into the workflow
`select-connection`	Searchable list of the user's connections for an app	Name and ID go back. With one connection, it's picked automatically
`create-connection`	A Connect Slack button	Opens the ConnectDialog. When done, the card shows Connected Slack

Three of them do nothing on the server except hand the question to the browser. The property picker does a bit more: it fetches the property's real options first, using a connection the user may use.

When the agent shows a card, its turn ends. It doesn't guess and carry on. It waits. The user's pick goes back as an ordinary message, which starts the next turn with exactly what the agent asked for. Answered cards collapse to a short summary with a green check (Picked: #standup), so the thread stays readable.

Connect, right in the conversation

This is where the whole series comes together. The user asks for a Slack reminder but hasn't connected Slack. The agent calls createConnection, and the chat shows Connect Slack. Clicking it:

Calls GET /api/embedded/v1/integrations with the user's JWT and finds the integration whose componentName is slack.
Opens the ConnectDialog from part one via useConnectDialog.
Watches the dialog's portal and marks the card connected when it closes.

The user goes through the same OAuth or API-key flow as on your Integrations page, without leaving the chat. Then the agent picks the new connection with select-connection.

createConnection is signaling only. The agent never sees or stores credentials, and the tool call creates nothing on the server. If the app isn't one of your integrations, the card says No integration is available for Slack.

Your house rules: the system prompt

The user decides what the workflow does. You decide how it's built.

Good system prompts encode decisions your users shouldn't have to make:

Always notify the team in Slack, never by email.
Keep workflows under five steps.
Use the Europe/Berlin time zone for every schedule unless the user names another.
Never delete CRM records; update a status field instead.

How ByteChef treats it:

Read every turn. Change it mid-conversation and the next turn picks it up.
Trimmed and capped at 4,000 characters on the server.
Can't override the core rules. It's appended under a heading that marks it as additional instructions from the integrating application, applied only where it doesn't conflict with the build rules, the workflow-definition contract or safety constraints. Your rules steer the agent. They can't turn it into something else.

In the sample it's a text box so you can experiment. In production it belongs in your code: build it from your product's conventions and what you know about the user (plan, time zone, approved apps).

What the agent can and can't do

The chat is a public surface. It runs with the connected user's JWT, and the browser controls the request body. So the copilot endpoint trusts none of the AG-UI state it receives. On every turn, ByteChef:

Checks the workflow belongs to the user. The {workflowUuid} must be in the user's own project for that environment.
Rebuilds the agent state from scratch. It keeps only the additional system prompt, then sets the rest itself: BUILD mode, non-autonomous, the verified workflow ID, the user's project, the environment from X-Environment (PRODUCTION if missing), and a conversation key built from tenant, user and workflow. Editing the request can't switch modes, change workspaces or read someone else's conversation.
Keeps the agent inside the user's project. Every workflow tool checks ownership, and project-level changes are off limits. Talk the model into opening another workflow and the tool refuses: "This chat can only work with the projects and workflows of its own project."
Allows only the user's own connections. The agent sees only connections the user owns or was given, and every connection ID it binds or queries is checked against that list: "This chat can only use connections its user is entitled to use." No borrowing another customer's Slack.
Limits the agent to your catalog. It can use only enabled integrations for that environment, plus connection-free components (schedules, conditions, loops, data mappers). Anything else doesn't show up in search, can't be looked up, and is rejected anywhere in a saved workflow, including inside conditions, loops and AI agent nodes.

That last one is easy to miss. If you offer HubSpot and Slack but not Salesforce, a user asking for "Salesforce to Airtable" gets a conversation about what's possible, not a workflow that could never run:

Handing off the result

The chat produces a real ByteChef workflow, so it's not a dead end. After the first turn, the component calls onWorkflowReady with the UUID from mount:

<EmbeddedWorkflowChat
    // ...
    onWorkflowReady={setWorkflowUuid}
/>

{workflowUuid && (
    <Button onClick={() => router.push(`/automations/${workflowUuid}`)}>Open workflow</Button>
)}

When the build is done, the agent says what it made:

Two things about the callback:

It fires once, after the first turn, not when the workflow is "done". That turn may have built three steps or only asked a question. The UUID never changes and the agent keeps updating the same workflow, so opening it later always shows the latest. Read it as "there's a workflow worth linking to now".
It's a callback, so you decide what it means. A button, a live preview next to the chat, a Save button, an analytics event.

/automations/{uuid} renders the same EmbeddedWorkflowBuilder from part eight. Chat to draft, canvas to polish.

From draft to running

A chat-built workflow is a draft. Nothing runs until it's published and enabled, which is the right default for something an AI just wrote. The calls from part seven take it live:

// Freeze the current definition as the first version
await fetchWithAuth(`/api/embedded/v1/automation/workflows/${workflowUuid}/publish`, {
    method: 'POST',
    headers: {'Content-Type': 'application/json'},
    body: JSON.stringify({description: 'Created from chat'}),
});

// Turn it on (DELETE to turn it off)
await fetchWithAuth(`/api/embedded/v1/automation/workflows/${workflowUuid}/enable`, {method: 'POST'});

In the sample the user does this by hand: Publish in the editor, then the toggle on the Automations list. A more guided product could add an Activate button under the chat.

Prerequisites

Your ByteChef instance needs:

The copilot enabled: bytechef.ai.copilot.enabled=true. Without it, /copilot/chat doesn't exist.
An AI provider configured. The run's environment decides which settings apply.
Integrations enabled for the environment. With none, the agent can still build schedules and logic, but nothing that talks to an app.

Embedded workflows and the copilot endpoint are Enterprise Edition features.

Hardening the demo for production

The sample is intentionally small. Before you ship:

Clean up abandoned drafts. Create the skeleton on the first message, or DELETE /automation/workflows/{uuid} untouched drafts when the user leaves.
Write suggestions for building. The sample's chips come from ByteChef's editor copilot, where a workflow already exists. On an empty one, try "Post a Slack message every Monday at 9:00" or "When a HubSpot deal closes, create a Jira ticket".
Own the system prompt. Generate it in code. Don't hand end users a text box.
Pass environment explicitly. It defaults to PRODUCTION, and a JWT signed for another environment is rejected when the skeleton is created.
Decide what "ready" means. For a stricter signal (a trigger exists, no open issues), fetch the workflow when the callback fires and check.
Support multi-select questions. The sample renders every question as single-select and ignores the multiSelect flag for now.
Fix the error boundary. EmbeddedChatBoundary hides a harmless assistant-ui unmount error, but renders nothing for any other crash. Replace that null with a fallback and report the error.
Add a New chat button. Remount the component (change its key) to get a fresh skeleton, a new conversation and an empty agent memory.
Surface the error reference. Make the run ID easy to copy and teach support to search logs for it.

Who owns what

You own where the chat appears, how it looks (it's your source code), the suggestions, the system prompt, which integrations exist, and what happens when a workflow is ready.
ByteChef owns the agent and its tools, the AG-UI stream, component search and property lookups, validation, per-user storage, the security boundary around every turn, the ConnectDialog and credentials, and the engine that runs the result.

Your code is one component, one callback and a button. Behind it is an agent that knows every action in your catalog and can turn "remind my team about standup every weekday" into a scheduled Slack workflow on the user's own account.

The series so far

Connect your users' apps (the JWT and ConnectDialog everything rests on)
Act on connected apps directly with the ComponentKit
Chat with an AI assistant that uses the ComponentKit's tools
Trigger workflows from your product's events
Call a workflow like a synchronous API
Agent over MCP: the same tools, discovered through an open protocol
Author workflows in a builder you designed
Start from a template you curated
Talk a workflow into existence (this part)

Parts three and nine both put an AI chat in your product, but they do opposite jobs. The ComponentKit chat acts on the user's apps right now: it sends the email, creates the ticket. New from Chat builds something that acts later, on its own, every time the trigger fires. One is an assistant. The other is an automation author.

Try it: enable the copilot and an AI provider in ByteChef, run the embedded sample app, and open Automations → New from Chat. Ask for a weekday Slack reminder and watch it build.

Originally published on the ByteChef blog. ByteChef is an open-source workflow automation and AI agent platform: github.com/bytechefhq/bytechef.

Add a "New from Template" Gallery to Your SaaS in Two API Calls

ByteChef — Sun, 11 Oct 2026 15:44:35 +0000

TL;DR — A "New from Template" gallery in your SaaS takes two REST calls with ByteChef Embedded: GET /automation/projects returns your curated catalog, and POST /automation/workflow-templates/{uuid}/copy clones a template into the user's own workspace. The copy is a normal, editable workflow that starts as a draft. This is part 8 of the ByteChef Embedded series.

Most users don't want a blank canvas. In part 7 we let users build workflows from scratch in a UI we designed — flexible, but slow. What users actually want to hear is: "Here's an automation we already built for you. Want it?"

That's what templates are. You design a few great workflows once, in ByteChef, and every customer gets them as a one-click starting point inside your product.

Why templates get the big button

In the embedded sample app, New from Template is the primary action on the Automations page. Every other option lives in the split menu:

The reason is simple: every other option asks the user to describe an automation (on a canvas, in a prompt, in a form). A template only asks them to pick one. For onboarding, that's the shortest path from "I just signed up" to "something is running for me."

What the user sees

Clicking the button opens /automations/templates: one section per project, one card per template.

Everything on a card comes from ByteChef:

the template's label (Daily standup reminder),
the description you wrote,
a row of component icons for the apps it uses (here: Slack).

Click a card → the template is copied → the user lands in their new workflow. The rest of this post is what happens on each side of that click.

Step 1: Build a template in ByteChef

Templates live in ByteChef, not in your app. Let's build Daily standup reminder: every weekday at 9:00, post a reminder to Slack.

Open Automation Workflows

In ByteChef go to Embedded → Automations. You'll see your catalog projects, each with a version badge:

This page only exists in the Development environment, so you author templates in one place. The published catalog, however, is served to connected users in every environment.

Create a project

A project is a shelf in your gallery. Click New Project:

Name and Description become the section heading and subheading — write them for customers.
Category and Tags only organize this admin page; they're not in the API response.
Permission Expression limits who sees the whole project (more below).
Show in Automation Hub controls ByteChef's own embeddable Hub. Turn it off for flows you only expose through the API.

Save, and the project shows up with a DRAFT badge.

Add a workflow

Each workflow = one template card. Click + Workflow on the project row:

Label and Description become the card's title and text. Workflows have their own Permission Expression too, so you can hide one template inside an otherwise public project.

Now build it — on the canvas, or by pasting a definition into the Workflow Code Editor (the </> button):

It's a schedule/v1/everyDay trigger (9:00, dayOfWeek 2–6) plus one Slack Send Channel Message task. Close the editor and ByteChef flags two issues:

Leave them. You can't know which Slack workspace or channel each customer uses. A good template fills in everything that's the same for every customer (schedule, message, structure) and leaves the account-specific bits blank.

Publish

Templates are invisible until the project is published. Open the project's ⋮ menu and click Publish:

No confirmation, no validation gate — the badge just flips from DRAFT to V1 PUBLISHED. A few things worth knowing:

Users always get the latest published version, never your work in progress. Edit freely; nothing changes until you publish V2.
An unpublished project still appears in the API, but empty — so publish before you tell customers to look.
Copies don't follow new versions. V2 only affects new copies. (References behave differently — see below.)

Step 2: Fetch the catalog

The gallery loads everything with one call:

export async function fetchAutomationWorkflowProjects(): Promise<AutomationWorkflowProject[]> {
  const response = await fetchWithAuth('/api/embedded/v1/automation/projects', {
    method: 'GET',
  });

  if (!response.ok) {
    throw new Error(`Failed to fetch automation workflow projects: ${response.status}`);
  }

  return response.json();
}

fetchWithAuth sends the connected user's JWT (from part 1) plus an X-Environment header (defaults to PRODUCTION). The JWT matters here because the catalog is filtered per user.

The response looks like this (icon shortened):

[
  {
    "id": 1128,
    "name": "Team productivity",
    "description": "Ready-made workflows that keep your team in sync",
    "automationHubVisible": true,
    "kind": "COPY",
    "workflowTemplates": [
      {
        "id": "6a62a705-2225-445d-a91a-048607332571",
        "label": "Daily standup reminder",
        "description": "Every weekday at 9:00, remind your team in Slack that standup is about to start",
        "components": [
          { "name": "slack", "title": "Slack", "icon": "<svg ...>...</svg>" }
        ],
        "inputs": []
      }
    ]
  }
]

Field	Meaning
`name`, `description`	Section heading + subheading
`automationHubVisible`	The Hub switch. Not used for filtering — a hint for your UI
`kind`	`COPY` (normal projects) or `REFERENCE` (code-native projects)
`workflowTemplates[].id`	The UUID you pass to the copy call
`workflowTemplates[].components`	Apps used: `name`, `title`, SVG `icon`
`workflowTemplates[].inputs`	Declared workflow inputs

Two gotchas:

components lists tasks, not the trigger. A "New HubSpot deal → Slack" template would only show Slack. If the trigger app matters, mention it in the label or description.

icon is raw SVG, not a URL. No hosting or proxying needed:

<img
  src={`data:image/svg+xml;utf8,${encodeURIComponent(component.icon)}`}
  alt={component.title || component.name}
  className="size-full"
/>

Who sees which template

Projects and workflows can each carry a Permission Expression — a SpEL condition evaluated against the connected user:

metadata['plan'] == 'pro'
metadata['tier'] == 'enterprise'

Expressions can read the user's metadata, externalId, email, name and environment. That gives you tiered catalogs with zero app code.

The rules are fail-closed: empty means everyone; otherwise it must evaluate to true. A false or a broken expression hides the item, so a typo hides a template instead of leaking it. The same check runs on copy, so guessing a UUID doesn't help — ByteChef answers as if the template doesn't exist.

Step 3: Render the gallery

This part is plain React. The sample's app/automations/templates/page.tsx keeps four bits of state:

const [projects, setProjects] = useState<AutomationWorkflowProject[] | undefined>();
const [isLoading, setLoading] = useState(true);
const [error, setError] = useState<string | null>(null);
const [creatingWorkflowId, setCreatingWorkflowId] = useState<string | null>(null);

One <section> per project, one shadcn/ui Card per template, in a 1–3 column grid. While a copy is in flight, the clicked card reads Creating workflow... and every card gets aria-disabled, so a double click can't start two copies.

Nothing here is ByteChef-specific. Cards, a searchable list, an onboarding checklist — the API gives you data, not UI.

Step 4: One click, one copy

const handleSelectWorkflowTemplate = (workflowTemplateUuid: string) => {
  setCreatingWorkflowId(workflowTemplateUuid);
  setError(null);

  copyWorkflowTemplate(workflowTemplateUuid)
    .then((workflowUuid) => router.push(`/automations/${workflowUuid}`))
    .catch(() => {
      setError('Failed to create a workflow from the selected template');
      setCreatingWorkflowId(null);
    });
};

export async function copyWorkflowTemplate(workflowUuid: string): Promise<string> {
  const response = await fetchWithAuth(
    `/api/embedded/v1/automation/workflow-templates/${workflowUuid}/copy`,
    {method: 'POST'}
  );

  if (!response.ok) {
    throw new Error(`Failed to copy workflow template: ${response.status}`);
  }

  const newWorkflowUuid = (await response.text()).trim();

  // The endpoint may return the uuid as a JSON string or as plain text.
  return newWorkflowUuid.startsWith('"') && newWorkflowUuid.endsWith('"')
    ? newWorkflowUuid.slice(1, -1)
    : newWorkflowUuid;
}

That one POST does a lot:

Copies the latest published version from the user's permission-filtered catalog. Drafts never leak.
Keeps the label and description — no "(Copy)" suffix. To the user, it's just their automation.
Lands in the user's own project, auto-created per user and environment. Your app never manages projects.
Remembers its origin and allows one copy per template per user. A second click fails — in production, show an Added badge that opens the existing copy instead.

What the user gets

The sample routes to /automations/{uuid}, which renders ByteChef's embedded editor:

<EmbeddedWorkflowBuilder
  baseUrl={BYTECHEF_APP_BASE_URL}
  connectionDialogAllowed={true}
  environment={BYTECHEF_ENVIRONMENT}
  jwtToken={jwtToken}
  workflowUuid={workflowUuid}
/>

Here's a copy of the Greeting Reference template, now in the user's workspace:

Note the V1 DRAFT badge. A copy is never live on arrival — a template might post to Slack or send email, and nothing should run on a customer's accounts until they've reviewed it and picked which accounts to use. (A copy of Daily standup reminder arrives with the two open issues we left in, so the user's first job is choosing their Slack connection and channel.)

Back on the Automations list, the new copy sits at the top as DRAFT:

The row at the bottom came from the same template — but as a reference, not a copy. More on that in a second.

From draft to running

Same three calls as part 7, authenticated with the user's JWT:

// 1. Bind the user's connection to each node that needs one
await fetchWithAuth(
  `/api/embedded/v1/automation/workflows/${workflowUuid}/workflow-nodes/slack_1/connection/slack`,
  {
    method: 'PUT',
    headers: {'Content-Type': 'application/json'},
    body: JSON.stringify({connectionId}),
  }
);

// 2. Freeze the current definition as V1
await fetchWithAuth(`/api/embedded/v1/automation/workflows/${workflowUuid}/publish`, {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({description: 'Created from template'}),
});

// 3. Turn it on (DELETE to turn it off)
await fetchWithAuth(`/api/embedded/v1/automation/workflows/${workflowUuid}/enable`, {method: 'POST'});

The sample leaves these to the user (Create Connection in the editor, Publish, then the enable toggle). But you can also wrap them in a short "Activate" wizard: pick a Slack account from GET /components/slack/connections, fill any inputs, then bind → publish → enable. That's exactly what ByteChef's own Automation Hub does.

Copy or reference?

There are two ways to hand a user a catalog workflow. The difference is who owns it afterwards.

	Copy	Reference
Call	`POST .../{uuid}/copy`	`POST .../{uuid}/provision`
User gets	A new, independent workflow	A per-user deployment of your workflow
Editable?	Yes, it's theirs	No, it runs your definition
You publish V2	Nothing changes (snapshot)	Every reference rolls forward
Connections	Bound per node after copy	Auto-wired or passed in the request
Initial state	Draft	Enabled once connections/inputs resolve

Copy when the template is a starting point users will customize. Reference when the workflow is really part of your product and you want to ship fixes once to everyone.

Check kind: COPY projects support both; REFERENCE (code-native) projects can only be provisioned — copying returns 409 with {"reason": "CODE_WORKFLOW_NOT_COPYABLE"}.

Server-to-server variants

Every call has a backend form authenticated with your environment's API secret key:

Browser (JWT)	Backend (API key)
`GET /automation/projects`	`GET /{externalUserId}/automation/projects`
`POST /automation/workflow-templates/{uuid}/copy`	`POST /{externalUserId}/automation/workflow-templates/{uuid}/copy`

Use these when the decision isn't the user's — e.g. drop a "Welcome" template into every new account at signup. Permission expressions still apply to the user in the path.

Production checklist

[ ] Respect kind — hide REFERENCE templates or route them to /provision.
[ ] Track what the user already has — show Added / Open instead of letting a second copy fail.
[ ] Surface the trigger's app — components only lists tasks.
[ ] Decide on automationHubVisible — the API returns hidden projects too.
[ ] Distinguish errors — "template no longer available" (404) vs. transient failures.
[ ] Offer activation, not just a copy — a two-step wizard gets users to a running automation in under a minute.

Who owns what

You own curation: which workflows exist, how they're grouped, who sees them, when they change, and how the gallery looks.
ByteChef owns the machinery: the editor, versioning, per-user filtering, tenant-isolated copies, component metadata and icons, connection storage, and the engine that runs it all.

Your code for the entire feature: two API calls and a grid of cards.

The series so far

Connect your users' apps (JWT + ConnectDialog)
Act on connected apps with the ComponentKit
Chat with an AI assistant using ComponentKit tools
Trigger workflows from your product's events
Call a workflow like a synchronous API
Agents over MCP
Author workflows in your own custom builder
Start from a curated template (this post)

Parts 7 and 8 are two ends of the same spectrum: a custom builder gives full control and asks a lot; a template asks almost nothing and gets users to value fastest. Most products want both — and both produce the same thing: a real ByteChef workflow in the user's own project.

Try it: in ByteChef, open Embedded → Automations, create a project with a workflow or two, and Publish. Then run the embedded sample app, open Automations → New from Template, and click a card.

Originally published on the ByteChef blog.

ByteChef Embedded, Part 7: New from Custom Workflow Builder

ByteChef — Fri, 09 Oct 2026 14:34:39 +0000

Most embedded workflow tools give you two choices: embed their editor, or don't offer automations at all. There's a third option. Build the editor yourself, and let the platform run whatever it produces.

This post walks through the Custom Workflow Builder in the ByteChef embedded sample app. It's a small React page that lets users build "when X happens, if Y, do Z" rules in your own UI. ByteChef never draws a pixel of it. It only sees the JSON the page produces.

TL;DR

Builder state lives in plain React useState.
A pure function renders that state into ByteChef's workflow-definition JSON on every keystroke.
POST /automation/workflows creates the workflow in the connected user's project.
PUT .../workflow-nodes/{node}/connection/{component} binds each node to the user's own connection.
The result is an ordinary ByteChef workflow. You can open it in ByteChef's editor, publish it, enable it, and it runs on ByteChef's engine.

Why not just embed the full editor?

ByteChef's own editor can be embedded, and it's powerful: canvas, hundreds of components, data pills, loops, branches, a test runner.

That's exactly what some products don't want. If your users are "set up a rule" people rather than "build a flow" people, you want a narrow, opinionated form in your design system:

When an email arrives, if the subject says invoice, post to #finance.

The Custom Workflow Builder shows how small that layer can be.

The builder in three files

No graph library, no drag and drop, no canvas. Just form cards stacked top to bottom: a Trigger card, then steps you add with Add Action and Add Condition. A live panel on the right shows the exact JSON the page will send.

File	Job
`catalog.ts`	Which components, triggers, actions and fields your builder offers
`definition.ts`	Builder state types, plus a pure function that renders state into ByteChef JSON
`page.tsx`	The UI, plus the save flow that calls the embedded API

Let's follow the data through each one.

1. The catalog is your product surface

ByteChef has hundreds of components. Your builder doesn't have to offer them. catalog.ts is a hardcoded list of exactly what this product supports, Gmail and Slack, with only the fields worth asking for:

export const COMPONENTS: CatalogComponent[] = [
  {
    name: 'googleMail',
    label: 'Gmail',
    triggers: [{name: 'newEmail', label: 'New Email', fields: []}],
    actions: [
      {
        name: 'sendEmail',
        label: 'Send Email',
        fields: [
          {key: 'to', label: 'To (comma-separated)', kind: 'stringArray', required: true},
          {key: 'subject', label: 'Subject', kind: 'string', required: true},
          {key: 'bodyType', label: '', kind: 'hidden', defaultValue: 'TEXT'},
          {key: 'body', label: 'Body', kind: 'string', required: true},
        ],
      },
    ],
  },
  {
    name: 'slack',
    label: 'Slack',
    triggers: [{name: 'anyEvent', label: 'Any Event', fields: []}],
    actions: [/* sendChannelMessage, sendDirectMessage, addReaction */],
  },
];

Three things make this more than a list:

name values are ByteChef's. googleMail, newEmail, sendEmail end up in each node's type. Labels can say anything. Names must match.
key values are ByteChef property names. to, subject, body are Send Email's real inputs.
kind controls serialization. stringArray turns "a@x.com, b@x.com" into an array. hidden never shows in the form and always sends a fixed value, like bodyType: "TEXT".

This is where your product's opinions live. Hide delete actions. Fix the email format. Rename "Send Channel Message" to "Notify the team". ByteChef doesn't need to know.

2. Keep state in your shape

The example workflow: Route invoice emails. When a new Gmail message arrives, post it to Slack if the subject mentions an invoice, otherwise send an auto-reply.

The condition compares ${trigger_1.subject} against invoice with contains. That ${...} is ByteChef's reference syntax. trigger_1 is the trigger node's name, subject is a field the Gmail trigger outputs. The builder doesn't evaluate any of it. It passes strings through, and ByteChef resolves them at run time.

All of it lives in one useState:

interface BuilderState {
  label: string;
  description: string;
  trigger?: TriggerState; // componentName, operation, parameters, connectionId
  steps: StepState[];     // ActionStepState | ConditionStepState (caseTrue / caseFalse)
}

The state is your shape, not ByteChef's. Connection IDs sit next to parameters, steps have client-side IDs for React keys, branches are plain arrays. You convert only at the edge.

3. Render the workflow definition

buildWorkflowDefinition(state) in definition.ts is a pure function with no I/O. The page runs it through useMemo on every change, which is why the JSON panel updates as you type. For our example:

{
  "label": "Route invoice emails",
  "description": "Post invoice emails to #finance, auto-reply to everything else",
  "triggers": [
    {"name": "trigger_1", "label": "New Email", "type": "googleMail/v1/newEmail", "parameters": {}}
  ],
  "tasks": [
    {
      "name": "condition_1",
      "label": "Condition",
      "type": "condition/v1",
      "parameters": {
        "rawExpression": false,
        "conditions": [[
          {"type": "string", "value1": "${trigger_1.subject}", "operation": "CONTAINS", "value2": "invoice"}
        ]],
        "caseTrue": [
          {
            "name": "slack_1",
            "label": "Send Channel Message",
            "type": "slack/v1/sendChannelMessage",
            "parameters": {
              "channel": "C07FINANCE1",
              "text": "New invoice from ${trigger_1.from}: ${trigger_1.subject}"
            }
          }
        ],
        "caseFalse": [
          {
            "name": "googleMail_1",
            "label": "Send Email",
            "type": "googleMail/v1/sendEmail",
            "parameters": {
              "to": ["${trigger_1.from}"],
              "subject": "Re: ${trigger_1.subject}",
              "bodyType": "TEXT",
              "body": "Thanks, we got your message and will reply within one business day."
            }
          }
        ]
      }
    }
  ]
}

That's the whole contract. Read it once and you can generate it from any UI:

triggers and tasks are arrays of nodes with a unique name, a label, a type and parameters.
type is component/version/operation. Flow controls drop the operation: condition/v1.
Flow controls nest. caseTrue and caseFalse are task arrays, so the JSON mirrors your UI's branches. conditions is a list of OR groups, each a list of AND comparisons.
Parameters are typed. to is an array because the field was stringArray. Blank optional fields are omitted.

Gotcha: node names must be stable

Nodes get a per-component counter: slack_1, googleMail_1, condition_1. The condition is named last, after its branch actions, because the code builds branches first.

That order matters. Connection binding (step 5) uses node names from a second function, collectConnectionBindings, which walks state in the same order. If the two ever disagree, a connection lands on the wrong node. In production, assign the node name when the step is created and store it in state.

4. Let users pick their connections

Each card has a Connection dropdown, filled by one call per component:

// GET /api/embedded/v1/components/{componentName}/connections
const connections = await fetchComponentConnections('googleMail'); // [{id, name}, ...]

The user's JWT scopes the call, so each user only sees their own accounts.

Connections are not part of the definition. The definition says what to do. Which account to do it with is stored per node. That separation is what lets one definition run against thousands of users' accounts.

5. Save and bind

const workflowUuid = await createBuilderWorkflow(buildWorkflowDefinition(state));

for (const binding of collectConnectionBindings(state)) {
  const response = await bindWorkflowNodeConnection(
    workflowUuid,
    binding.nodeName,      // e.g. "googleMail_1"
    binding.componentName, // e.g. "googleMail"
    binding.connectionId
  );

  if (!response.ok) {
    failedBindings.push(binding.nodeName);
  }
}

Both helpers are thin wrappers around the embedded API. Every request carries the user's JWT in Authorization and the target environment in X-Environment.

Call	Endpoint	What it does
`createBuilderWorkflow`	`POST /api/embedded/v1/automation/workflows` with `{definition}`	Creates the workflow in the user's project, returns its UUID
`bindWorkflowNodeConnection`	`PUT /api/embedded/v1/automation/workflows/{uuid}/workflow-nodes/{nodeName}/connection/{connectionKey}` with `{connectionId}`	Attaches one connection to one node

Worth knowing:

Each user gets a project automatically. ByteChef creates it the first time it's needed. Your app never manages projects.
definition is a string. Stringified JSON, the same format ByteChef's editor stores.
The connection key is the component name for single-connection components like Gmail and Slack.
Binding is best-effort. The workflow is already saved, so report which nodes failed instead of failing the whole save.

What ByteChef sees

Click View workflow and ByteChef's own editor opens your JSON as a regular graph: Gmail trigger, condition with TRUE and FALSE branches, Slack and Gmail actions, with your node names.

It's also your safety net. In the demo, the Slack node is left without a connection on purpose. ByteChef flags it with a required-connection warning and a Create Connection button. Same for Gmail's New Email trigger, which needs a Pub/Sub Topic Name the catalog never asks for. ByteChef doesn't guess. It marks it required. Your UI can be as forgiving as you like, and ByteChef still validates the result.

From draft to running

Saving creates a DRAFT. Two more calls make it run:

// 1. Freeze the current definition as a version (V1, V2, ...)
await fetchWithAuth(`/api/embedded/v1/automation/workflows/${workflowUuid}/publish`, {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({description: 'First version'}),
});

// 2. Turn it on (DELETE to turn it off)
await fetchWithAuth(`/api/embedded/v1/automation/workflows/${workflowUuid}/enable`, {method: 'POST'});

A custom builder can fold both into one Activate button. Once enabled, new mail starts runs on the user's bound connections.

The rest of the lifecycle:

GET /automation/workflows/{uuid} and PUT /automation/workflows/{uuid} for editing. Re-bind connections after structural edits.
DELETE /automation/workflows/{uuid} to remove.
GET /automation/workflows to list.

Every endpoint also has a server-to-server form under /{externalUserId}/automation/workflows/..., authenticated by your backend. Use it to provision default automations when a customer signs up.

Before you ship it

The sample is a teaching tool. Close these gaps first:

Validate before saving, including required fields the catalog skips.
Store node names on steps so bindings and edits stay stable.
Offer data pills, not expressions. Generate ${trigger_1.subject} from a field picker.
Handle missing connections in your UI by opening the ConnectDialog right there.
Grow the catalog on purpose. Start with the few actions your users really need.

Who owns what

You own the authoring experience: catalog, forms, branching UI, connection picker, wording, and the state-to-JSON function.
ByteChef owns everything after the JSON: validation, storage, versioning, per-user projects, connection storage and OAuth refresh, trigger registration, and execution.

Even at maximum control, you're not building an iPaaS. You're building a front end. The moment you save, it's a real ByteChef workflow, indistinguishable from one built in ByteChef's editor, copied from a template or generated from a prompt.

Try it

Run the embedded sample app, connect Gmail under Integrations, then open Automations → New from Custom Workflow Builder. Add a step or two, watch the JSON update, save, and click View workflow.

This is part 7 of the ByteChef Embedded series. It was originally published on the ByteChef blog. ByteChef is open source (Apache 2.0) on GitHub.

ByteChef Embedded, Part 6: The MCP Chat

ByteChef — Tue, 06 Oct 2026 20:31:48 +0000

TL;DR: In part three, your own route fetched the user's tools from ByteChef and adapted each one to the AI SDK. The MCP Chat lets a standard do that work: its backend route (/api/chat-mcp) opens an MCP client to ByteChef's embedded MCP server over streamable HTTP, calls mcpClient.tools() to discover the connected user's tools, and hands them straight to the model. It's the same Model Context Protocol that Claude and Cursor speak, consumed inside your own chat. This is part six of the series.

The ComponentKit Chat gave an assistant real tools, but your route had to know ByteChef's tools API: fetch the list, parse each schema, wrap it with tool(), and POST every call back for execution. The MCP Chat gets the same kind of toolbox through a protocol instead, so discovery and execution are standardized rather than hand-written per app.

Set Up the MCP Server in ByteChef

Before the chat can discover anything, ByteChef needs an MCP server that says which tools to expose. You build it once, as the vendor, and every connected user gets their own scoped view of it.

1. Publish an Integration First

An embedded MCP server only offers components that one of your published integrations uses. If you followed part one, you already have one. Here it's a Gmail integration, and that's what makes Gmail show up in the steps below.

2. Create the Server

Open Embedded → MCP Servers and click New MCP Server. The only thing it asks for is a name. Pick one that describes what the assistant is for, since you can run several servers with different toolboxes side by side.

3. Add Components and Pick Their Tools

Expand the new server and, on its Component Tools tab, click Add Component. The picker lists the components behind your published integrations, with a count of the tools each one offers.

Choose one and you get its full list of actions. Tick only the ones you want a model to have. Gmail has eleven, including Delete Email, so this is where you decide that the assistant can search and read mail without being able to delete it.

Save, and the component appears on the server with the tools you picked. The gear icon (Configure) next to each tool lets you rename it, rewrite the description the model reads, and pin any input to a fixed value. Inputs you leave alone stay Automatically defined by the model. Pinning Max Results on Search Email, for example, keeps the model from pulling a whole mailbox in one call.

4. Add Workflows as Tools (Optional)

A single action isn't always enough. On the Workflow Tools tab, Add Workflows lets you expose a whole integration workflow as one tool. Pick an integration instance configuration and tick its workflows. Only workflows that start with the Workflow › New Workflow Call trigger qualify, because that trigger defines the input schema the model fills in.

Here a Send Email workflow from the Gmail integration becomes a tool next to the raw Gmail actions. A workflow tool can enforce your rules (a fixed sender, a template, a log step) that a bare action can't.

5. Enable It and Copy the Server URL

Switch the server's toggle on, then open the Connect tab. The Server URL has the form https://<your-bytechef>/api/embedded/{secretKey}/mcp. It's marked Sensitive because the secret key in the path identifies your server. The copy icon copies it, and the refresh icon rotates the secret if it ever leaks.

That URL is the only server-side setting the sample app needs. Put it in front-end/.env.local:

NEXT_PUBLIC_BYTECHEF_MCP_SERVER_URL=https://your-bytechef/api/embedded/{secretKey}/mcp

The URL picks the server; the connected-user JWT your route sends picks whose tools and connections to use. Every user shares one URL and still gets their own toolbox.

6. Per-User Control

Once a connected user has connected an integration whose component is on the server, the server shows up in their record. Open Embedded → Connected Users, click the user, and switch to the MCP Servers tab. Each server lists that user's tools in two groups, Component Tools and Workflow Tools, under the integration they come from, with its connection status and version. Workflow tools like Send Email sit there next to plain actions like Search Email. You can turn the whole server off for that one user, or switch off individual tools.

Your users get the same control. When they open the ConnectDialog for a connected integration, its Tools tab lists the integration's tools with a toggle for each. Workflow tools like Send Email sit next to plain actions, with any inputs the workflow asks for.

Note the default: when a user connects (or reconnects) an integration, its tools start switched off. Until the user turns them on, the assistant can't use them. That's a sensible opt-in for anything that acts in someone's mailbox, but it means your UI should point users at this tab after they connect.

Tools by Discovery

The chat page is the same assistant-ui thread as part three. The difference is entirely in the backend route:

import { createMCPClient } from '@ai-sdk/mcp';
import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';

const jwtToken = await getToken();

const mcpClient = await createMCPClient({
    transport: new StreamableHTTPClientTransport(new URL(BYTECHEF_MCP_SERVER_URL), {
        requestInit: {
            headers: {
                Authorization: `Bearer ${jwtToken}`,
                'X-Environment': BYTECHEF_ENVIRONMENT,
            },
        },
    }),
});

const tools = await mcpClient.tools(); // discover the connected user's tools

const result = streamText({
    model: openai.chat('gpt-5'),
    messages: await convertToModelMessages(messages),
    tools: { ...tools, ...frontendTools(clientTools ?? {}) },
    stopWhen: stepCountIs(8),
    onFinish: async () => {
        await mcpClient.close();
    },
});

Instead of enumerating and wrapping actions yourself, you open an MCP connection to ByteChef's embedded MCP server and ask it for the tools available to this connected user. The same JWT from part one rides along in the Authorization header, so the user's integrations (the ones you configured for them as a vendor) arrive as ready-to-call tools, already scoped to their connections. There's no execute function to write: when the model calls a tool, the MCP client sends the call back to the server for you.

A few details worth noticing in the route:

stopWhen: stepCountIs(8) lets the agent loop continue past tool calls, so the model can read a tool's result and act again (or answer) instead of stopping after one step.
frontendTools(...) merges in any tools the assistant-ui page registers on the client, so server tools from MCP and browser-side tools live in one toolbox.
mcpClient.close() runs in onFinish, so each request opens and closes its own MCP session.

Add a tool to the MCP server on the ByteChef side, and it shows up in the chat on the next request. No client change.

Here's one turn in the sample app. The model finds GOOGLEMAIL_SEARCH_EMAIL among the discovered tools, fills in the subject, and answers from the result:

Tool names follow a COMPONENT_ACTION pattern, so the Gmail Search Email action becomes GOOGLEMAIL_SEARCH_EMAIL. A workflow tool is named after its workflow, so the Send Email workflow from step 4 arrives as Send_Email.

Authorization on Demand

The user doesn't have to connect every app up front. If the model calls a tool whose integration isn't connected yet, the embedded MCP server doesn't fail the call. It returns a result that tells the model what to do:

{
    "error": "connection_required",
    "message": "The googleMail integration is not connected for this user. To connect, visit: https://your-bytechef/connect.html?token=... . Instruct the user to visit this link to connect their account. Present it as a markdown link labelled \"Connect googleMail\" instead of printing the raw URL.",
    "setupUrl": "https://your-bytechef/connect.html?token=..."
}

The message is written for the model, not the user: it says what went wrong, where to send the user, and even how to format the link. Here's the same Gmail search from above, asked by a user who hasn't connected Gmail yet:

There are two buttons, and they come from different places. The model wrote Connect googleMail into its answer because the message asked it to. Connect account under the tool result comes from the sample app's chat UI, which spots error: "connection_required" and renders setupUrl as a button, so the link is there even if a model ignores the instruction.

The model passes the link on in the chat. The link opens ByteChef's hosted connect page, which carries a short-lived token (valid for 10 minutes) scoped to that user and integration. The page opens the same ConnectDialog from part one: an OAuth2 popup for OAuth2 apps, or a form for API keys and other credential types.

Once the user connects, nothing else is needed. The server checks for a connection on every tool call, so when the model tries the tool again, it runs on the user's new connection.

That turns onboarding into part of the conversation: the user asks for something, the assistant finds it needs Slack, hands over a link, and carries on once Slack is connected. Connections only get created for the apps people actually use.

Why the Protocol Matters

Doing this over MCP rather than through a custom adapter buys you three things:

One definition, many clients. The tools your MCP Chat uses are the same ones an external Claude or Cursor gets from the embedded MCP server. You define an integration's tool surface once, and every AI (yours and your customers') consumes it the same way.
Central governance. Which tools exist, their input schemas, and the per-connected-user identity are all resolved server-side. The chat just discovers and calls.
Future-proofing. MCP is the emerging standard for giving models tools. Building on it means your "AI that acts" feature speaks the same language as the rest of the industry.

Same outcome as the ComponentKit Chat (an agent that operates the user's apps), but the tools flow through an open, discoverable protocol instead of bespoke wiring.

Six Parts In

The pieces so far compose into one story about what "embedded automation" takes:

Connect your users' apps (the JWT and ConnectDialog everything rests on).
Act on those connected apps directly with the ComponentKit.
Chat with an AI assistant that uses the ComponentKit's tools.
Trigger their workflows from your product's events.
Call a workflow like a synchronous API.
Agent over MCP: the same tools, discovered through an open protocol (this part).

Every one of them was a component or a couple of API calls, all scoped by a single JWT and all riding the same connections. That's the promise of embedded: the integration surface is yours (your UI, your brand, your product) and the integration machinery is ByteChef's.

Following along? Create an MCP server under **Embedded → MCP Servers, paste its URL into NEXT_PUBLIC_BYTECHEF_MCP_SERVER_URL, set OPENAI_API_KEY, connect the integration in the embedded sample app, and open MCP Chat. Your assistant now finds its tools on its own.