DEV Community: ByteChef

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.

Share What You Built: Project & Workflow Templates

ByteChef — Tue, 08 Sep 2026 19:01:59 +0000

TL;DR: Templates let you start from a working automation instead of a blank canvas - and let you share your own. Browse the gallery of pre-built project and workflow templates and import one into your workspace, or turn something you built into a private import link that you can disable at any time. Connections never travel with a template, so sharing an automation never shares your credentials.

The best automation you'll ever build is one you don't have to build - because someone already did, and shared it. We wrote about import and export as the foundation for this a while back, and promised template support on top of it. This is that.

Start From a Working Automation

There are two granularities, and both live behind a gallery:

Project templates - open Projects → Templates to browse pre-built projects. Selecting one imports it as a regular project you can edit, publish, and deploy.
Workflow templates - inside a project, browse workflow templates and import one as a new workflow.

Each gallery has a search box and a category filter, and every card shows the components the template uses as icons - so you can tell at a glance whether a template touches Slack, Postgres, or an LLM before you commit to it.

Picking a card takes you to an import page rather than importing blind. That page lists every component the template contains, which is your shopping list: those are the apps you'll need connections for once the automation is in your workspace. When it looks right, Import now drops a copy into your current workspace.

Share What You Built

The other half is publishing. Open the three-dot menu next to a project - or an individual workflow, from its own menu - and choose Share.

The dialog asks for one thing before it will do anything: a description. It's required, and the export button stays disabled until you write one. That constraint is doing real work - a template with no explanation is a template nobody imports.

Then click Export and generate template link. The dialog turns into a link card with a Copy link button, and the link looks like this:

https://your-instance/import/shared/projects/{uuid}

Workflows get the same shape at /import/shared/workflows/{uuid}. Anyone you hand that link to lands on the same import page described above - the component list, then Import now. They do need an account on a ByteChef instance and a workspace to import into; this is a link for colleagues and collaborators, not an anonymous public download.

The Link Stays Yours

Three details make this comfortable to actually use.

You can turn it off. A toggle at the top of the dialog disables the link at any time - the existing URL stops working immediately. Flip it back on later and ByteChef generates a fresh export.

It won't drift behind your project silently. Keep editing after you've shared, and the dialog tells you that an older version is the one being handed out, and offers Update template based on the current version. The link keeps pointing at whatever you last decided it should.

ByteChef doesn't distribute it for you. The dialog says so directly: template links are not distributed by the app. Generating a link does not list your project anywhere, does not surface it in the gallery, and does not make it discoverable. You decide who gets the URL.

What Travels, and What Doesn't

A shared template is a small zip: a manifest with your description and the project version, the project metadata, and one JSON file per workflow definition. That's the whole payload.

What is conspicuously not in there: connections. No API keys, no OAuth tokens, no credentials of any kind. The importer wires up their own accounts against the component list on the import page. This is why sharing an automation is a low-stakes act - you're sharing the shape of the work, never the keys to your systems.

Listing in the Public Gallery

Private links are one route. If you want a template listed in ByteChef's official gallery for anyone to browse, that's a separate action: Share with Community, which opens the public template submission form. The two are genuinely different - one hands a URL to people you choose, the other proposes an addition to a curated catalog.

Self-hosted instances behind a firewall can point the gallery at a mirror rather than reaching ByteChef's catalog directly; the GitHub proxy configuration in the docs covers it.

Why Sharing Compounds

A workflow you keep to yourself helps one team once. A workflow you template helps everyone who imports it - and they can adapt it, re-share it, and improve on it:

Onboarding - new users start from proven automations instead of a tutorial.
Standardization - a team's "the right way to do X" becomes a template everyone imports.
Community - the best patterns rise to the top and spread.

Wrapping Up

Every automation you build is either a one-off or a starting point, and the difference is a description and a click. Templates let the good ones travel - built once, imported wherever they're needed, improved by whoever needs them next - without ever putting your credentials on the move.

Built something worth reusing? Share it as a template - or browse the gallery and start from one instead of a blank canvas.

Somewhere to Keep the Records: Data Tables in ByteChef

ByteChef — Sun, 30 Aug 2026 09:59:22 +0000

TL;DR: Data Tables are ByteChef's built-in place to keep records. Create a table with typed columns (string, number, integer, date, date-time, boolean), fill it in a spreadsheet-like grid or import a CSV, and use it from your workflows through six actions (create, get, find, update, delete, clear) and three triggers that start a workflow whenever a row is created, updated, or deleted. Those same six actions are available to AI agents as tools, so an agent can look things up and write rows for you. Your Development, Staging, and Production rows stay in separate tables, so test data never leaks into live automations. No database to set up, no spreadsheet to babysit.

There's a question every automation project runs into by week two: "where do we keep the records?" The leads the workflow has already processed. The subscriptions to check against. The running list of approvals, orders, escalations. Workflow steps don't remember anything between runs; the data has to live somewhere, and the classic answers are both awkward. A spreadsheet bolted onto the side is easy but fragile: no real types, no stable way to point at a row, rate limits, and an API that was never meant to be your database. An actual database is solid but heavy: someone has to provision it, design it, secure it, and write the plumbing for every read and write.

Data Tables are ByteChef's answer to that gap: tables that live inside the platform, as easy as a spreadsheet from the front, as dependable as a database underneath, and already connected to everything else your workflows do.

Set One Up in a Minute

A Data Table starts the way you'd hope. Open Data Tables in the Automation workspace, click New Table, give it a name, and add your columns; each one gets a type: string, number, integer, date, date-time, or boolean.

From there you get a familiar grid. Add a row by typing into the empty one at the bottom. Click a cell to edit it, and you get the right editor for the column: a checkbox for booleans, a date picker for dates, a number field for numbers. Select rows with checkboxes to delete them. Longer tables load more rows as you scroll.

Already have the data in a spreadsheet? Import a CSV from the table's ⋮ menu and the rows land in the matching columns. The same menu exports a CSV back out, so nothing you put in is trapped. Once you've got a few tables, tags keep the list organized.

Picking a type per column sounds like a small chore, and it pays for itself almost immediately: a date column is a real date rather than text that usually parses, numbers sort like numbers instead of alphabetically, and a boolean is true or false rather than "yes", "Y", and "TRUE" all living in the same column. Every row also gets its own id that never changes, so you can hold onto a specific row and come back to it later, something row numbers in a spreadsheet can never promise you.

Test Data Stays Test Data

Here's the part people are usually surprised by. A Data Table isn't one shared pile of rows; ByteChef keeps a separate set of rows for each environment. The table you filled with junk while building in Development is genuinely not the table your Production workflow reads from.

That means you can test a workflow that inserts, updates, and deletes records without a moment's worry about what it's touching, then promote it and watch it run against real data. No "_TEST" prefix conventions, no second copy of a spreadsheet that drifts out of sync, no accidentally emailing your actual customers because a test row was sitting in the live sheet.

Six Actions: Tables in Your Workflows

Add the Data Table component to a workflow and you can read and write any of your tables. There's no connection to set up and nothing to authenticate against; the tables are part of the platform, so they're just there:

Create Records - add one row or many at once.
Get Record - fetch a specific row by its id.
Find Records - list rows from a table, with limit and offset so you can page through them.
Update Record - change the values on a row.
Delete Records - remove rows.
Clear Table - empty a table in one step.

Pick your table and the action's inputs reshape themselves around that table's columns, so you're filling in Email and Status, not guessing at field names.

That covers the patterns automations lean on constantly: accumulate ("append every order this workflow processed"), enrich later ("store the record now, update it when the webhook finally lands"), hand off ("one workflow writes the row, another picks it up"), and keep a log ("record what this run did, so there's something to look at on Monday").

Three Triggers: Tables That Start Workflows

This is where Data Tables stop being just storage. Most built-in tables in other tools are passive: you read and write them, and that's the end of it. ByteChef's tables can start a workflow. The component ships three triggers:

Record Created - a new row was added.
Record Updated - a row changed.
Record Deleted - a row was removed.

Which quietly changes the shape of what you can build. A table stops being a filing cabinet at the edge of your automations and becomes the thing they're organized around. One workflow adds a row; three other workflows react to it, and the one doing the writing doesn't need to know they exist.

Say an intake workflow drops a new order into a table. A fulfillment workflow, a customer-notification workflow, and a reporting workflow each start themselves on Record Created, independently. Want to add a fourth later? Build it and switch it on. Nothing else needs touching.

Agents Can Use Them Too

Data Tables aren't only for workflows you draw by hand. Every one of those six actions is also available to AI agents as a tool, so an agent can look up a record, add one, update one, or clear a table, using exactly the same operations your workflows use.

That means a table can be shared ground between the two ways of working. A scheduled workflow keeps a table of open tickets up to date; an agent you're chatting with reads that same table to answer "what's still unresolved?" and writes a row back when it takes something on. Same data, same rules, no separate copy to keep in sync.

Where It Fits

Data Tables aren't trying to replace your production database; they're for the working data of your automations. A rough guide:

Data Tables are a good fit when…

Your workflows need to share data or remember state between runs.
You’re tracking processed items, queues, lookups, or workflow logs.
You want one workflow to react when data changes.
Your dataset is relatively small and primarily written by workflows. Consider something else when…
You need a system of record for your product → use a real database.
People need to collaboratively edit free-form content → use a spreadsheet or document.
You’re moving or syncing large datasets between systems → DataStream (coming soon).
Your knowledge is stored in documents rather than rows → use a Knowledge Base.

Two things worth knowing before you commit. A Data Table is not a transactional system of record: there's no cross-row transaction or multi-writer locking, so if several outside systems are writing the same data at the same time, point your workflow at a real database instead. And it's sized for small datasets, not warehouses: think lookup tables, queues, flags, and processed-item lists rather than millions of rows.

That right-hand column is really a tour of ByteChef's storage story: Data Tables for structured rows, the Knowledge Base for searchable documents, and DataStream (coming soon) for moving bulk data between systems. Three shapes of data, three purpose-built homes.

Wrapping Up

Remembering things is the unglamorous half of automation. Every workflow beyond the trivial needs to keep track of something, and how well it remembers (real types or everything-as-text, stable ids or shifting row numbers, reacting to changes or polling for them) quietly decides how far that automation can grow before it starts to hurt.

Data Tables give that job a proper home: tables you fill in like a spreadsheet, with types that hold, ids that stay put, test data kept away from live data, six actions to read and write them from your workflows or hand to an agent, and three triggers so a change to a row can set the next workflow going. No database to provision, no sheet to babysit, just somewhere real for your workflows to keep what they know.

Got a workflow juggling state in a spreadsheet? Open ByteChef, create a **Data Table, and give your records somewhere better to live.

Agent Skills in ByteChef: Package Know-How Once, Give It to Every Agent

ByteChef — Thu, 27 Aug 2026 16:19:30 +0000

TL;DR: Agent Skills are self-contained packages of instructions, scripts, and resources - built around a SKILL.md file - that agents discover and load on demand. The Spring AI team just added generic support for them in Java. ByteChef, which runs on Spring AI under the hood, goes a step further: a built-in Skills workspace for creating, editing, and sharing skills; isolated GraalVM execution for bundled scripts; and a Skills Tool that plugs any skill into any AI Agent. Write the know-how once, reuse it everywhere - no code, no redeploys.

There's a moment every agent builder hits: your AI Agent works, but making it good at your job means feeding it more and more instructions. The refund policy. The report format. The naming conventions. The seventeen edge cases finance cares about. Everything lands in the system prompt, which grows into an unmaintainable wall of text that every request pays for in tokens - whether it's relevant or not.

Agent Skills are the answer to that problem, and they're having a moment. Anthropic introduced the pattern and its SKILL.md convention; it quickly spread across the ecosystem. In January, the Spring AI team published Agent Skills in Spring AI - the first post in their agentic patterns series - showing how to wire skills into any Java application with SkillsTool, file-system tools, and shell tools.

If you've read our previous posts on the AI Agent component and agentic workflow patterns, you know where this is going: ByteChef is built on top of Spring AI, and skills are no exception. But where Spring AI gives Java developers the building blocks, ByteChef ships the whole thing as a product - skills management, a visual editor, and one-click attachment to any agent.

Let's dig in.

What Is an Agent Skill?

A skill is a folder. That's genuinely the whole format - and it's why the pattern is spreading so fast.

At the root sits a SKILL.md file: YAML frontmatter with metadata on top, Markdown instructions below. Around it, optional supporting files:

email-digest/
├── SKILL.md          ← metadata + instructions (required)
├── scripts/          ← executable helpers
│   └── run_digest.py
├── references/       ← extra documentation, loaded on demand
└── assets/           ← templates and other resources

Here's what a real SKILL.md looks like - this is the email-digest skill we'll use as the running example:

---
name: email-digest
description:
    Fetches unread emails from Gmail, summarizes key points using AI,
    and sends the digest back to the user's Gmail inbox. Use when the
    user asks to summarize their unread emails or get an email digest.
---

# Email Digest Skill

## What It Does

1. Fetches unread emails from Gmail (up to a configurable limit)
2. Uses an LLM to summarize key points per email
3. Sends a formatted digest email back to the user's Gmail

## How to Run

Call the `email_digest_run_digest` tool. It runs the bundled
`scripts/run_digest.py`, which fetches the unread mail, summarizes
it, and sends the digest.

## Output

A single HTML email sent to the recipient containing a summary
of every unread message, grouped by sender.

Two things to notice. First, the description does double duty: it tells humans what the skill is for, and it tells the agent when to reach for it - that last sentence ("Use when the user asks to…") is discovery guidance, not documentation fluff. Second, the instructions are written for the agent, in imperative, unambiguous language. A skill is essentially an onboarding document for a very fast, very literal new hire.

Because the format is plain Markdown in a folder, skills are portable. The same convention is used by Claude Code, by Spring AI's implementation, and by ByteChef - a skill you write in one place can travel to the others.

Progressive Disclosure: Why Skills Scale Where System Prompts Don't

The clever part of the skills pattern isn't the file format - it's when the content gets loaded. Skills use progressive disclosure, revealing themselves to the agent in three phases:

Discovery. By default, the agent only sees each skill's name and description - a few dozen tokens per skill. This is what lets an agent carry dozens of skills without drowning its context window.
Activation. When a request matches a skill's description, the full SKILL.md instructions load into context - only then, and only for that skill.
Execution. Referenced Markdown files and script outputs enter the picture on demand, while the skill runs, and not a moment earlier.

Compare that with the stuff-everything-into-the-system-prompt approach, where the refund policy is in context while the user asks about the weather. Progressive disclosure means you pay for know-how only when it's being used - which is exactly what makes a library of specialized skills economically viable.

Skills at Runtime: The Skills Tool

On the ByteChef side, an agent gets access to skills through the Skills Tool - one of the tool options in the AI Agent's Tools slot, alongside component actions, MCP tools, and sub-agents. Attach it, and the agent can discover and invoke any skill in your workspace.

The runtime flow looks like this:

Note what's absent from that picture: routing logic. You don't configure which requests trigger which skill - the agent matches the user's intent against skill descriptions on its own. Add a new skill to the workspace and every agent with the Skills Tool can start using it immediately.

When a skill bundles scripts, ByteChef doesn't hand the agent a shell. It walks the skill's scripts/ folder and turns every script that exports a perform function into a tool of its own - so scripts/run_digest.py inside the email-digest skill becomes a callable tool named email_digest_run_digest. JavaScript, Python, Ruby, and Java all work, and each one is executed by a GraalVM polyglot engine rather than a subprocess. The agent sees a named tool it can call, not a command line it can compose.

That distinction matters, because the Spring AI post is refreshingly honest about its own trade-off here: in the DIY setup, "scripts execute directly on your local machine without sandboxing," and the recommended mitigation is to containerize your whole application. A ByteChef skill script runs in a polyglot context with no host filesystem, no network sockets, and no native access - it reaches the outside world only through context.component, the same action layer the rest of the platform runs on. It is not a resource sandbox: there are no CPU or memory ceilings on guest code, so skill scripts remain code worth reading before you attach them. But the ambient authority a loose python3 would inherit simply isn't there. Combined with Guardrails on the agent itself, you get a controlled execution story without building any of it.

There's a neat side effect. Because those scripts are just files, ByteChef reads them before the workflow ever runs: it scans each one for context.component.<name>.<action>(…) calls and surfaces a connection field for every component it recognizes. Bundle a script that calls context.component.gmail.* and the Skills Tool node asks you for a Gmail connection. The skill declares its own dependencies in code, rather than in metadata you have to remember to keep in sync.

And because model access goes through Spring AI's provider abstraction, skills are model-portable: the same skill works whether the agent runs on GPT-4o, Claude, Gemini, or a local Ollama model. Define once, run anywhere - swap the model from a dropdown later.

Built-In Skills Management

In Spring AI, skills live in folders on the classpath or filesystem, next to your application code. ByteChef gives them a home in the product instead: the Skills area, right in the AI section of the workspace.

Every skill in the list shows its name, its description (the same one agents use for discovery), and when it was last modified. From here you can search, create, and manage the whole library. Two ways to create a skill are available today, with a third on the way:

Write instructions. Give it a name and a description, write what it should do in plain text, and ByteChef packages it into the SKILL.md structure for you.
Upload. Drag in a .skill archive, a .zip, or a bare .md file. This is the import path for skills built elsewhere - including skills from the wider SKILL.md ecosystem.
Create with AI (coming soon). Describe the capability ("a skill that summarizes my unread Gmail every morning") and let ByteChef's Copilot draft the skill's structure, metadata, and instructions. This path rides on the AI Copilot, which is on the upcoming release track rather than in the current release.

Once created, a skill opens in the built-in editor:

That's the email-digest skill from earlier, as it actually looks in ByteChef. On the left, the file tree - SKILL.md plus a scripts/ folder holding the Python helper. The main pane renders the frontmatter as a metadata table above the formatted instructions - ByteChef validates and stores name and description, and displays whatever other keys the file carries verbatim, so a skill imported from another tool keeps its own metadata intact. A toggle switches between this preview and a full source editor that picks its syntax highlighting from the file extension - Markdown, Python, JavaScript, TypeScript, Java, JSON, YAML, HTML, CSS, SQL - so you can edit any file in the package. Save, and the change is live - every agent using the skill picks it up on its next run, no rebuild, no redeploy.

Need to move a skill between workspaces, share it with a teammate, or keep a snapshot before a big edit? Download it as a .skill archive and it becomes a file you can version, review, and re-upload anywhere.

The Payoff: One Skill, Many Agents

Here's where the managed approach compounds. Because skills are decoupled from any single agent, they form a shared capability library for your whole workspace:

The support agent, the sales agent, and the internal helpdesk agent can all carry the same refund-policy skill. Update the policy once; all three agents follow the new rules on their next conversation.
A release-notes skill encodes your changelog format and tone. Attach it to the engineering agent that drafts notes from merged PRs and to the marketing agent that turns them into announcement posts.
The email-digest skill above doesn't care which agent invokes it - any agent with the Skills Tool and a Gmail connection can produce the digest.

This is the same "build once, reuse everywhere" argument the Spring AI post makes with the composability of skills - except the unit of reuse isn't a folder you copy between codebases; it's a managed object every agent in the workspace can already see.

And you can verify all of it before it touches production: open the agent in the editor, and the Agent Playbook lets you chat with your in-progress configuration. Ask something that should trigger the skill, and the expandable tool-call cards show the skill being discovered and invoked - which tool ran, with what inputs, returning what output. If the agent picks the wrong skill (usually a sign your description is too vague), you'll see it in seconds.

Skills, System Prompts, or RAG?

Skills join two other ways of shaping agent behavior, and it's worth being deliberate about which knowledge goes where:

Mechanism	What it's for	Loaded
System prompt	Identity and ground rules: who the agent is, tone, hard constraints	Always
RAG	Facts: your documents, tickets, product data - what is true	Per query, by similarity
Skills	Procedures: how to perform a task, step by step - how it's done	On demand, by intent

A useful rule of thumb: if you're writing "always" or "never," it belongs in the system prompt. If you're writing "our Q3 pricing is…," that's a document - put it in RAG or the Knowledge Base. If you're writing "first do this, then that, format the result like so," you're writing a skill.

The three compose naturally on one agent: a lean system prompt for identity, RAG for grounding, and a library of skills for the procedures - each loaded at the moment it earns its context cost.

What You Inherit from Spring AI - and What ByteChef Adds

The Spring AI team closes their post with the pattern's strengths, and being built on Spring AI, ByteChef inherits all of them: LLM portability (define a skill once, run it on any supported provider), reusability and composability (share skills across projects, version them, extend them), and no vendor lock-in (the common SKILL.md convention travels).

They're equally upfront about the limitations. Their list runs to four items, and ByteChef's managed layer closes two of them:

Scripts execute directly on the local machine without sandboxing → in ByteChef, each script becomes a tool running inside a GraalVM polyglot context with no host filesystem, network, or native access.
Script execution requires pre-installed runtimes → the polyglot engine ships in the platform; JavaScript, Python, Ruby, and Java run with nothing to install.

The other two are honest gaps in both. There's still no built-in human approval step before a skill's script runs, and skill versioning is whatever you make of it - download a .skill archive and commit it alongside your code, but nothing versions skills for you in-product.

Two further differences don't appear on their list at all, because they're product concerns rather than framework ones: skills live in a managed workspace with search and a visual editor instead of on the filesystem next to your code, and wiring is one Skills Tool attached to an agent instead of dependencies and configuration code.

Same foundation, same format, same portability - minus most of the infrastructure work.

Best Practices for Writing Skills

A few habits that separate skills agents reliably pick up from skills that gather dust:

Treat the description as an API. It's the only thing the agent sees at discovery time. State what the skill does and when to use it: "…Use when the user asks to summarize their unread emails." Vague descriptions are the number-one cause of skills never firing.
One job per skill. "Handle refunds" and "write release notes" are two skills, not one. Small skills are easier for the agent to match and for you to maintain.
Keep SKILL.md lean. The instructions load in full at activation, so they should carry the workflow - push long reference material into references/ files the agent reads only when needed. Progressive disclosure only saves tokens if you let it.
Prefer scripts for deterministic work. If a step is exact - parsing, formatting, calling an API in a precise way - a bundled script beats prose instructions. The model decides when; the script guarantees how. Give each script under scripts/ a perform function: that's what ByteChef looks for when deciding which files to expose as tools, and a script without one is quietly skipped.
Test in the Playbook first. Phrase requests the way real users would, watch which skill activates, and tune descriptions until discovery is reliable.

Wrapping Up

Agent Skills solve an unglamorous but decisive problem: where does an agent's know-how live? Not in a bloated system prompt, not scattered across duplicated agent configs - in small, portable, on-demand packages that any agent can pick up.

Spring AI brought that pattern to the Java world as a library. ByteChef, standing on Spring AI's shoulders, turns it into infrastructure you don't have to build: managed storage, a visual editor, isolated script execution, and one-click attachment to any agent - with the Agent Playbook to prove it all works before you ship, and AI-assisted authoring on the way.

Got a procedure your team explains over and over? That's your first skill. Open ByteChef, head to the Skills area, and teach it once.

DEV Community: ByteChef

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

What the user gets

From draft to running

Copy or reference?

Server-to-server variants

Production checklist

Who owns what

The series so far

ByteChef Embedded, Part 7: New from Custom Workflow Builder

Why not just embed the full editor?

The builder in three files

1. The catalog is your product surface

2. Keep state in your shape

3. Render the workflow definition

Gotcha: node names must be stable

4. Let users pick their connections

5. Save and bind

What ByteChef sees

From draft to running

Before you ship it

Who owns what

Try it

ByteChef Embedded, Part 6: The MCP Chat

Set Up the MCP Server in ByteChef

1. Publish an Integration First

2. Create the Server

3. Add Components and Pick Their Tools

4. Add Workflows as Tools (Optional)

5. Enable It and Copy the Server URL

6. Per-User Control

Tools by Discovery

Authorization on Demand

Why the Protocol Matters

Six Parts In

Gotcha: `--workflow` is not a path

The Star of Part One: `useConnectDialog`