DEV Community: ByteChef

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.

ByteChef Embedded, Part 5: The Request Playground

ByteChef — Wed, 30 Sep 2026 15:28:59 +0000

TL;DR: In part four, App Events triggered whoever's listening. Sometimes you instead want to invoke one specific workflow and get its output back. The Request Playground does exactly that: POST /api/embedded/v1/workflows/{workflowUuid} with a JSON body runs that workflow for the current connected user, passing the body as trigger input and returning the result. It turns any automation into a synchronous API endpoint your app can call like a function. This is part five of the series.

App Events are fire-and-fan-out: you emit, everyone listening runs, you don't wait for a result. But plenty of use cases are request/response: "run this enrichment workflow on this record and give me back the answer." For that you don't want an event; you want to call a workflow directly.

Set Up the Request Trigger

A workflow becomes callable once it starts with the Request trigger. In the workflow editor, add a trigger (or right-click an existing one and choose Replace), search for Request, and pick one of its two triggers:

Auto Respond with HTTP 200 Status - accepts the call, replies 200 right away, and runs the workflow in the background. Fire-and-forget.
Await Workflow and Respond - holds the request open until the workflow finishes, then returns its result. This is the one that makes a workflow behave like a function.

Await Workflow and Respond has one property, Timeout (ms): how long the caller waits before the request times out, with a maximum of five minutes. Set it lower if your app shouldn't block that long.

Add the steps that do the work below the trigger. The request body is available to them as the trigger's output. Then Publish the workflow; once a connected user has the integration enabled, it's ready to call.

Finding the Workflow UUID

Every integration workflow has a stable workflowUuid, and that's what the call needs. You get it from the Embedded API with the same connected-user JWT, in two calls. GET /api/embedded/v1/integrations lists the user's active integrations. GET /api/embedded/v1/integrations/{id} returns one of them with its workflows, and each workflow has a label and a workflowUuid:

async function fetchWorkflowUuid(
  jwt: string,
  integrationName: string,
  workflowLabel: string,
): Promise<string> {
  const headers = { Authorization: `Bearer ${jwt}` };

  // GET /api/embedded/v1/integrations   (bearer JWT)
  const integrations = await fetch('/api/embedded/v1/integrations', { headers })
    .then((res) => res.json());

  const integrationId = integrations
    .find((integration) => integration.name === integrationName)
    ?.id;

  if (integrationId === undefined) {
    throw new Error(`No active integration named "${integrationName}"`);
  }

  // GET /api/embedded/v1/integrations/{id}   (bearer JWT)
  const integration = await fetch(`/api/embedded/v1/integrations/${integrationId}`, { headers })
    .then((res) => res.json());

  const workflowUuid = integration.workflows
    ?.find((workflow) => workflow.label === workflowLabel)
    ?.workflowUuid;

  if (!workflowUuid) {
    throw new Error(`Integration "${integrationName}" has no workflow labeled "${workflowLabel}"`);
  }

  return workflowUuid;
}

const workflowUuid = await fetchWorkflowUuid(jwt, 'HubSpot', 'Enrich contact');

The list only includes integrations the connected user has active, so enable the integration for that user first. The UUID stays the same across published versions, so you can look it up once and keep it in your app's config.

In the sample app, the Request Playground's Find the Workflow UUID card makes the same two calls. Pick an integration, then click Use next to a workflow to fill in its UUID.

A Workflow, Callable Like a Function

The playground takes that workflow UUID and a body, and invokes it:

// POST /api/embedded/v1/workflows/{workflowUuid}   (bearer JWT)
const res = await fetch(`/api/request/${workflowUuid}`, {
  method: 'POST',
  body: JSON.stringify({ message: 'Hello from the Request Playground' }),
});

ByteChef runs that specific workflow for the current connected user, feeding your body in as the trigger's input, and returns the workflow's output in the response. From your app's perspective, a whole multi-step automation (connectors, branches, the works) behaves like a single API call: request in, result out.

This is the pattern behind request-triggered workflows: your customer builds an automation with a request-style trigger, and you (or they) invoke it on demand. The workflow becomes a named, versioned, connection-backed function, one your app can call synchronously wherever it needs the result.

Where It Fits Among the Triggers

The sample app now shows all three ways work enters a workflow, and they're complementary:

Entry	How	When
Native triggers	a schedule fires, a webhook lands, a poll finds new data	the automation reacts to the outside world
App Events (part 4)	your product emits an event, fanned to all listeners	your product's events drive automations
Request (this part)	your app calls one workflow by UUID and awaits its result	you need a specific automation's output, now

Together they mean a workflow can be scheduled, event-driven, or called like an API: the same automation reachable three ways, all scoped by the same JWT.

What You Didn't Build

For one POST:

Synchronous invocation of a specific workflow by id, per connected user.
Input delivery and output collection through the execution engine.
A stable "automation as an endpoint" contract your app can depend on.

No queue to manage, no polling for results. Call it, await it, use the answer.

What's Next

Five parts in, the pieces fit together: the ConnectDialog links your customer's accounts, the ComponentKit and its AI Chat act on those apps, App Events let your product start workflows, and the Request Playground turns a workflow into an endpoint you call and await. Next up is the sample app's MCP Chat, which exposes the same tools through the Model Context Protocol, so clients like Claude and Cursor can use them too.

Following along? POST a payload to a workflow UUID and read the response - you've turned an automation into a callable function.

ByteChef Embedded, Part 4: The App Event Playground

ByteChef — Mon, 28 Sep 2026 15:25:58 +0000

TL;DR: In part two and part three your app called into connected apps, one action at a time or through an AI assistant. App Events are the opposite direction: your product emits an event and ByteChef triggers your customers' workflows from it. POST /api/embedded/v1/app-events with a free-form JSON body fans that payload out to every enabled workflow's app-event trigger for the current connected user. It's how "something happened in my SaaS" becomes "run the automations my customer built around it." This is part four of the series.

Half of embedded automation is your customers reacting to external apps (a new row in their Google Sheet). The other half, the half that makes your product the center of their automations, is reacting to events in your app. When a user upgrades their plan, closes a deal, or gets a new signup in your product, they'll want to automate what happens next. App Events are the inbound trigger that makes your product a first-class event source.

Emit an Event, Trigger Their Workflows

The playground is a single POST with a free-form body:

// POST /api/embedded/v1/app-events   (bearer JWT)
await fetch('/api/app-events', { method: 'POST', body: JSON.stringify(eventPayload) });

On the ByteChef side, that call iterates every enabled integration the current user has, finds each workflow with an app-event trigger, and forwards your body as the event payload. One emit, fanned out to all the automations listening for it. The body shape is yours. It should match the JSON schema you defined for the event, so the workflows can map fields off it.

Put that in your product's backend, and every meaningful thing that happens becomes a potential automation trigger for your customers: subscription.upgraded, lead.created, ticket.resolved. You emit once; ByteChef routes it to whoever built a workflow around it.

See Every Run

Each workflow an event starts is a normal workflow execution, so it shows up on the Workflow Executions page under Embedded in ByteChef. You can filter by integration, workflow, status, and date range, and open any run to see the trigger payload your product sent and what each step did with it. When a customer asks "why didn't my automation fire?", that's where you look.

Why This Closes the Loop

Together, the ComponentKit and App Events make your product a full node in your customers' automation graph. Data flows both ways:

App Events (in): your product's events start their workflows.
ComponentKit (out): your app, or an AI assistant inside it, acts on connected services.

That bidirectionality is what turns "we have some integrations" into "our product is the hub." An event in your product can trigger a workflow that updates your customer's CRM, posts to their Slack, or calls back into your own API. ByteChef is the router in the middle, and App Events are your product's on-ramp to it.

What You Didn't Build

For one POST:

An event ingestion endpoint that authenticates and scopes to a connected user.
Fan-out routing to every matching workflow trigger across all the user's integrations.
Payload delivery into the execution engine as trigger input.
Execution history for every run the event started, on the Workflow Executions page.

No event bus, no subscription registry, no per-workflow dispatch. You emit; ByteChef routes.

What's Next

App Events start workflows implicitly: whoever's listening runs. Sometimes you want to invoke a specific workflow directly and get its result back. That's the next part, the Request Playground, where a workflow behaves like a synchronous API endpoint.

Following along? POST an event body to /app-events from your product's backend - every workflow your customers built around that event fires.

ByteChef Embedded, Part 2: The ComponentKit Playground

ByteChef — Thu, 17 Sep 2026 13:08:17 +0000

TL;DR: Not everything needs a workflow. The ComponentKit lets your app call any connector action directly on a connected user's account: POST /api/embedded/v1/{externalUserId}/components/{component}/versions/{version}/actions/{action} with an { input } body runs, say, slack / sendChannelMessage or openai / ask with the user's stored credentials and returns the result. The embedded sample app's ComponentKit Playground is a form over that one endpoint. This is part two of the series.

In part one your users connected their apps. An embedded platform is more than a workflow engine, though. It is also a pre-authenticated API client for 280+ services, and sometimes you want that directly. Your app needs to post one Slack message, enrich one contact, or run one OpenAI completion, as your customer, without authoring or running a workflow for it. That's the ComponentKit.

The Playground Page

The page is a form with four fields and a result panel. Pick a component, a version, an action, and a JSON input, and it posts them to the app's own API route:

export default function ComponentKitPage() {
  const [componentName, setComponentName] = useState("openai");
  const [componentVersion, setComponentVersion] = useState(1);
  const [actionName, setActionName] = useState("ask");
  const [inputJson, setInputJson] = useState(JSON.stringify(input, null, 2));
  const [result, setResult] = useState<string | null>(null);

  const handleSubmit = async (event: React.FormEvent) => {
    event.preventDefault();

    const response = await fetch("/api/component-kit", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ actionName, componentName, componentVersion, input: JSON.parse(inputJson) }),
    });

    setResult(JSON.stringify(await response.json(), null, 2));
  };

  // ...a Card with the four inputs, and a Card that renders `result` in a <pre>
}

The defaults are openai / version 1 / ask, and the input textarea is pre-filled with a chat request:

{
  "model": "gpt-4o",
  "format": "ADVANCED",
  "messages": [{ "role": "USER", "content": "Say hello" }],
  "response": { "responseFormat": "TEXT" }
}

Click Execute Action and the response lands in the right-hand card, as JSON. Errors from ByteChef land there too, so a wrong action name or a missing required input shows you exactly what the server complained about.

The Route: One POST to ByteChef

The route adds the connected user's JWT and forwards the call to the ComponentKit endpoint:

const response = await fetch(
  `${BYTECHEF_APP_BASE_URL}/api/embedded/v1/${BYTECHEF_EXTERNAL_USER_ID}/components/${componentName}/versions/${componentVersion}/actions/${actionName}`,
  {
    method: "POST",
    headers: { Authorization: `Bearer ${jwtToken}`, "Content-Type": "application/json", "X-Environment": BYTECHEF_ENVIRONMENT },
    body: JSON.stringify({ input }),
  }
);

ByteChef finds the integration this user connected for that component, takes the connection behind it, and runs the action with those credentials. The response comes back as-is. No workflow, no trigger, no execution history, just a synchronous "do this thing in their account."

The shape is universal. Swap in slack / sendChannelMessage, googleSheets / insertRow, or hubspot / createContact and nothing else changes. The action's input schema is the same one the workflow editor uses, so if you know what a field looks like in a workflow, you know what to put in input.

If a user has connected the same app more than once, pass the X-Instance-Id header to say which integration instance you mean. Without it, ByteChef picks the user's instance for that component.

Why This Matters

The ComponentKit turns ByteChef Embedded from "a workflow feature" into "an integration layer for your whole product." Anywhere in your app where you'd otherwise hand-roll an API client, with OAuth, token refresh, request signing, and response parsing, times 280 services, you make one call instead:

In-product actions. A "Send to Slack" button that just works, on the user's connection.
AI tool calls. Give an LLM the ability to act in the user's apps, which is exactly what part three builds.
Backend glue. Server-side enrichment, sync, or notification without standing up a workflow.

Because it rides the same connection and JWT as everything else in this series, it's automatically scoped, authenticated, and refreshed. You send one POST; ByteChef is the API client you didn't write.

What You Didn't Build

For one POST:

A typed action invocation across 280+ connectors.
Credential resolution and refresh, per connected user, per environment.
The auth handshake and request for whichever provider you named.
A uniform response shape instead of hundreds of bespoke API clients.

Running It Yourself

On top of the setup from part one:

Connect the integration you want to call. The playground defaults to OpenAI, so connect an OpenAI integration for your demo user through the connect dialog first. The API key lives in that connection, not in the sample app's .env.local.
Try another app. Connect Slack, change the form to slack / 1 / sendChannelMessage, and give it a channel and text. Same page, same route, different account.

What's Next

The ComponentKit is your app calling one action at a time. Hand those same actions to a model and it can pick which one to call, fill in the input, and read the result. That's part three: the ComponentKit Chat.

Following along? Connect an integration, open the ComponentKit Playground, and execute one action on a connected account. It's the simplest possible embedded integration.

ByteChef Embedded, Part 1: Let Your Users Connect Their Apps

ByteChef — Tue, 15 Sep 2026 09:50:21 +0000

TL;DR: Before a customer can automate anything in your product, they have to connect their own accounts. ByteChef Embedded makes that a two-piece job: (1) your backend signs a JWT identifying one of your users as a ByteChef connected user, and (2) your frontend calls one hook - useConnectDialog from @bytechef/embedded - which mounts a hosted ConnectDialog that runs the whole OAuth/API-key handshake, stores and refreshes the credentials, and doubles as the manage surface once a connection exists. This is part one of a hands-on series that walks the embedded sample app feature by feature. We start where every embedded integration starts: connecting an app.

If you're embedding automation inside your own SaaS product, the very first wall you hit isn't workflows - it's connections. Before your customer can "sync new leads to their CRM," they have to connect their CRM, with their OAuth grant, stored securely, refreshed forever. Do that yourself and you've signed up to build and maintain OAuth for Salesforce, and HubSpot, and Slack, and the next hundred apps your customers ask for. That's not a feature; it's a department.

ByteChef Embedded exists to delete that work, and this series shows exactly how - using the real embedded sample app (a Next.js frontend + a small Node backend) as our guide. Over the coming parts we'll build out each way your users can create automations. But all of it rests on this first step, so that's where we begin: letting your users connect their apps.

The Auth Model: Connected Users, Not ByteChef Accounts

Here's the crucial idea that makes embedded work: your end users never get a ByteChef account. They're your users. ByteChef knows them only as connected users, identified by a token your backend signs.

The sample app's backend does exactly this - one endpoint that mints a JWT:

const payload = {
  sub: externalUserId,          // your app's user id
  name: name || externalUserId,
  iat: Math.floor(Date.now() / 1000),
};

const token = jwt.sign(payload, BYTECHEF_PRIVATE_KEY, {
  algorithm: 'RS256',
  expiresIn: TOKEN_EXPIRY,
  keyid: BYTECHEF_KID,
});

You hold the private key; ByteChef verifies with the matching public key. The sub claim is your user id (externalUserId) - so a token says, in effect, "this is my user #1234, acting as themselves." Your frontend fetches that token from your backend and never touches the key:

const token = await getToken();   // POSTs to your /api/token

That's the entire identity story. Every embedded call the frontend makes carries this JWT (plus an X-ENVIRONMENT header), and ByteChef scopes everything - connections, workflows, executions - to that connected user.

Listing the Integrations You Offer

Your users can only connect what you've published. The sample app fetches your catalog straight from the embedded API with the bearer token:

const res = await fetch(`${BYTECHEF_APP_BASE_URL}/api/embedded/v1/integrations`, {
  headers: { Authorization: `Bearer ${token}`, 'X-ENVIRONMENT': BYTECHEF_ENVIRONMENT },
});

Back comes the list of integrations you've defined - title, icon, category, and whether this user already has an instance connected. Render them as a grid of cards, and you've got an "Integrations" page with zero bespoke per-app code.

The Star of Part One: `useConnectDialog`

Now the actual connecting. It's one hook:

import { useConnectDialog } from '@bytechef/embedded';

const { openDialog, closeDialog } = useConnectDialog({
  baseUrl,
  environment,        // DEVELOPMENT | STAGING | PRODUCTION
  integrationId,      // which integration the user clicked
  jwtToken,           // the connected-user token
});

// ...
openDialog();         // mounts the hosted connect flow

Call openDialog() and ByteChef mounts its ConnectDialog into a portal in your page. From the user's side it's a clean, hosted modal: pick the account, get bounced through the provider's OAuth consent (or enter an API key), and land back connected. From your side, the authorize URL, the callback, the code exchange and the scope handling all run inside that portal - per provider - and the tokens that come back are stored encrypted against this connected user, in this environment, then refreshed for as long as the connection lives. You never see or hold a credential.

The dialog owns its own lifecycle, so its closing is something you observe rather than subscribe to: the hook hands back openDialog and closeDialog, and the sample app watches the #connect-dialog-portal node empty out to know when to refresh its list. That's it - that's a production-grade "Connect your Salesforce" button, for any of ByteChef's 280+ connectors, without you writing a single OAuth line.

After the Connect: the Same Dialog Manages It

A connection is not a one-time event. Users come back to change what is switched on, or to revoke it altogether, and that does not need a second UI: openDialog() already covers both cases.

When the dialog opens it looks for an existing instance, the one named by integrationInstanceId if you passed it, otherwise the first this connected user already has. Find one and it opens in manage mode instead of the auth flow:

const {openDialog} = useConnectDialog({
  baseUrl,
  environment,
  integrationId,
  jwtToken,
  integrationInstanceId,   // optional: manage one specific connection
});

From there the user can toggle which of your published workflows run for their account, edit the inputs a workflow asks them for, or disconnect. Each is a call ByteChef makes against /api/embedded/v1/integration-instances/... on their behalf. Disconnecting deletes the instance and closes the dialog, so the next openDialog() starts the auth flow again.

That fallback to the first instance is why the sample app's integration card can stay so simple: it flips its label between "Connect" and "Connected" purely on whether integrationInstances is empty, and calls the same hook either way.

What You Didn't Build

Step back and total up what the ConnectDialog absorbed:

Per-provider OAuth flows (×280), callbacks, scope handling.
Encrypted credential storage, scoped per user and environment.
Token refresh, forever.
A manage-connection UI: toggle workflows, edit their inputs, disconnect.
Environment separation (Development / Staging / Production) out of the box.

Your side of the contract was two small pieces: sign a JWT in your backend, call one hook in your frontend. That's the whole promise of embedded - the integration surface your customers see is yours; the integration machinery is ByteChef's.

What's Next in This Series

Connecting an app is the foundation. Everything else is about turning that connection into automation - and the sample app's Automations page offers five different front doors to do it, each of which gets its own part:

New from Template - start from a pre-built workflow you've published.
New from Embedded Workflow Builder - drop ByteChef's full visual builder into your app.
New from Prompt - generate a workflow from a natural-language description.
New from Chat - build one conversationally.
New from Custom Workflow Builder - craft your own builder UI on ByteChef's APIs.

We'll take them one at a time. But every one of them assumes the user has already connected the apps their automation touches - which is exactly what you just shipped.

Running the Sample App Yourself

The sample app needs to know two things: where your ByteChef instance lives, and which Signing Key your backend signs with.

Point the frontend at ByteChef. In front-end/.env.local, set NEXT_PUBLIC_BYTECHEF_APP_BASE_URL. On ByteChef Cloud that's https://app.bytechef.io. On a self-hosted instance it's your own URL, and the default http://localhost:8080 already matches a local install, so you can leave it unset.
Give the backend a Signing Key. In ByteChef, open Embedded → Settings → Signing Keys, create a key, and copy it into back-end/.env as BYTECHEF_PRIVATE_KEY (shown once) and BYTECHEF_KID. Create it on the same instance the frontend points at - a Cloud key won't verify against a self-hosted server.

Everything else (environment, demo user id) has a working default. The sample app docs list every variable.

DEV Community: ByteChef

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

Why agents drop steps

The TodoWrite tool

Why writing it down works

Spring AI vs. ByteChef setup

Try it: a Spring Boot 4 migration planner

Why it earns its place

Wrapping up

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

The example: an offsite planner that asks first

What the model actually sees

What happens when the agent asks

Try it in 4 steps

Why asking first matters

Spring AI vs. ByteChef: what you get for free

Wrapping up

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

TL;DR

Where it fits

The dialog

One call

Four shapes of the same endpoint

What happens on the server

Autonomous mode

Your house rules: the system prompt

Security boundaries

Handing off to the editor

Draft to running

Prompt vs. Chat

Prerequisites

Before you ship it

Who owns what

Try it

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

Same engine, different packaging

A real example

The flags

Gotcha: --workflow is not a path

Connections

Exit codes are the API

Getting results out

Docker

Kubernetes CronJob

CI

What's in, what's out

Quick troubleshooting

Server or Runtime Job?

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

Where chat fits

The page

Mounting the component

Props

It's source, not a package

On mount: a skeleton workflow

On each turn: AG-UI streaming

Errors users can act on

The controls users expect

Interactive cards: when the agent needs the user

Connect, right in the conversation

Your house rules: the system prompt

What the agent can and can't do

Handing off the result

From draft to running

Prerequisites

Hardening the demo for production

Who owns what

The series so far

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

Why templates get the big button

What the user sees

Step 1: Build a template in ByteChef

Open Automation Workflows

Create a project

Add a workflow

Publish

Step 2: Fetch the catalog

Who sees which template

Step 3: Render the gallery

Step 4: One click, one copy

Gotcha: `--workflow` is not a path

The Star of Part One: `useConnectDialog`