DEV Community: ByteChef

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.

Your Documents, Chunked and Searchable: The Knowledge Base in ByteChef

ByteChef — Tue, 25 Aug 2026 19:46:33 +0000

TL;DR: A Knowledge Base in ByteChef is a managed RAG store: drop in documents (PDF, Markdown, Word, JSON, plain text - and scanned PDFs or images, through an OCR path) and ByteChef parses, chunks (with size and overlap you pick per knowledge base), embeds, and indexes them in a pgvector-backed Spring AI VectorStore. Retrieval is everywhere you'd want it: a Knowledge Base Search tool for AI Agents (with tag filtering), Load/Search/Update/Delete actions for workflows, and a built-in search interface for testing. Keeping the index current is yours to drive - re-run an ingestion workflow on whatever schedule you like - and the part to plan for deliberately is upstream deletes, which no refresh can spot on your behalf.

Every team building with agents arrives at the same sentence: "It should know our stuff." The product docs. The runbooks. The policy PDFs. And the standard answer - RAG, retrieval-augmented generation - is conceptually simple: chunk the documents, embed the chunks, search by similarity, hand the best matches to the model.

The concept is a weekend. The operation is a project. Someone has to parse five file formats, pick chunk sizes, run an embedding model, host a vector database, keep the index in sync when the source-of-truth changes - and notice when a document is deleted upstream, because a knowledge base that confidently serves stale policy is worse than none at all. That's the gap between a RAG demo and a RAG system. ByteChef's Knowledge Base closes most of it for you - and this post is honest about the part it leaves to you.

What a Knowledge Base Is

In ByteChef, a Knowledge Base is a first-class object with its own home in the workspace: a named store of documents, each broken into chunks, each chunk embedded and indexed for semantic search. The layering is straightforward:

Documents are what you put in - files you upload, or records a workflow or an agent writes in, organizable with tags.
Chunks are what retrieval actually works with. You pick the chunking when you create a knowledge base - maximum chunk size (default 1024 tokens), the minimum chunk size in characters used to find a clean break point (default 100), and how many tokens neighboring chunks overlap (default 200) - so a KB full of dense legal prose can chunk differently than one full of short FAQ entries. The splitter counts tokens with CL100K_BASE, the same encoding GPT-4 uses, and prefers to break on sentence punctuation rather than mid-thought.
Embeddings live in pgvector - a Spring AI PgVectorStore over a pgvector-enabled PostgreSQL database, built with the platform's configured EmbeddingModel and indexed with HNSW over cosine distance. There's no proprietary vector service to sign up for and no new operational vocabulary to learn: it's Postgres, backed up and monitored like the rest of your Postgres, and ByteChef creates and maintains the schema, the index, and the per-knowledge-base partitioning for you.

And in the Knowledge Base workspace, none of this is a black box. You can open any document and inspect its individual chunks - and edit them, because sometimes the fix for a bad retrieval is one badly split paragraph - watch a document's indexing status, and, before any agent ever touches it, try queries against the KB in a built-in search interface to see exactly what retrieval returns.

Getting Documents In

There are three doors in, matched to three situations:

Upload. Drag files into the workspace. The ingestion pipeline picks the right parser per format - a dedicated PDF reader (page- or paragraph-oriented), a Markdown reader, JSON and plain-text readers, and an Apache Tika-based reader as the catch-all for Word documents and other office formats. All of these are Spring AI's document readers; ByteChef orchestrates them into one pipeline that ends in chunks and vectors. With OCR enabled, PDFs and images take a different route entirely - straight through an OCR service - so the scanned contract and the photographed whiteboard land in the index like everything else.
From a workflow. The Load Data action writes into a knowledge base from anywhere a workflow can reach. Attach a document reader (plus any transformers you want), point the action at the target KB, and every run pushes documents through the same chunk-and-embed pipeline the uploader uses. Put that workflow behind a schedule, a webhook, or a file-landed trigger and ingestion runs without you.
From an agent. The Knowledge Base Update tool is a cluster element you attach to an AI Agent, so an agent can contribute what it learns rather than only consume it - useful when the thing worth keeping is something the agent worked out mid-conversation.

Whichever door you use, everything downstream is identical - parse, chunk, embed, index. What differs is who pushes the button, and how often.

Keeping It Current - and the Deletes Nobody Plans For

An index is a snapshot, and snapshots rot. Re-running ingestion is the easy half: put the Load Data workflow on a schedule and new and changed documents flow in on whatever cadence suits the material - nightly for a handbook, hourly for a status page.

The hard half is the one that quietly poisons RAG systems: deletions. A refresh that asks the upstream for "everything that changed since Tuesday" gets back the records that still exist - never the ones that vanished. Left alone, a document deleted at the source lives on in your knowledge base indefinitely, still retrieved, still quoted by your agent, long after somebody retracted it.

That half is yours to own today - ByteChef has no "connect a source and forget it" option that derives deletions for you. It's worth owning deliberately rather than discovering later, and the shape of the fix is simple enough: tag each ingested document with its upstream id, and on the runs where you can enumerate the full current upstream set, use the Delete Documents action - it removes documents by metadata filter - to drop whatever is no longer in it. Unglamorous, and far cheaper than the alternative, which is an agent confidently citing a policy that was withdrawn a month ago.

Getting Knowledge Out

A knowledge base earns its keep at retrieval time, and ByteChef exposes it on every surface:

As an AI Agent tool. The Knowledge Base Search tool is a cluster element - attach it to any AI Agent (the same way as every tool in our agentic patterns series), pick which KB it searches, and optionally scope it by tags (documents matching any selected tag are eligible). From then on, the agent decides when to reach into the knowledge base, mid-conversation, on its own. There's a Knowledge Base Update tool too - for agents that should be able to contribute knowledge, not just consume it.
As workflow actions. The Knowledge Base component ships Load Data, Search Data, Update Documents, and Delete Documents actions, so ordinary workflows can query or maintain a KB with no agent involved - "on new support ticket, search the KB and attach the top three matches" is three nodes.

One store, several ways in and out - and because retrieval is tag-filterable, a single knowledge base can serve multiple audiences ("customer-facing" vs. "internal-only") without maintaining parallel copies.

If you want to tune retrieval itself - query rewriting, expansion, custom joins over several stores - that's a different layer: ByteChef's RAG cluster elements, which work over any vector store you like. The Knowledge Base is the batteries-included end of the same spectrum: you don't configure retrieval, you just ask it questions.

What You Inherit from Spring AI - and What ByteChef Adds

By now you know the shape of this section. The primitives are Spring AI's; the product around them is ByteChef's:

Document readers exist as library classes (PDF, Markdown, JSON, text, Tika) → ByteChef auto-selects the parser per file in one managed ingestion pipeline.
Spring AI has no OCR reader at all → ByteChef adds one, and routes scanned PDFs and images through it before any other parser gets a look.
PgVectorStore + EmbeddingModel are yours to configure and operate → ByteChef owns the schema, the HNSW index, and the per-knowledge-base partitioning.
Chunking is a splitter you instantiate with magic numbers → chunk size, minimum, and overlap are fields on the create-knowledge-base form.
Ingestion is a pipeline you assemble, wire, and run yourself → it's one action with a reader attached, on any trigger - or no workflow at all, if you just upload.
Retrieval is code you write → it's a tool on any agent, actions in any workflow, and a search UI for humans.

Same foundation as everything in this series - Spring AI under the hood - with the operational half of RAG, the half that actually hurts, absorbed into the platform.

Running It Yourself

If you're self-hosting, the Knowledge Base ships disabled - two switches turn it on:

bytechef:
  ai:
    knowledge-base:
      enabled: true
    vectorstore:
      provider: pgvector
      pgvector:
        url: jdbc:postgresql://localhost:5433/bytechef_vectorstore
        username: postgres
        password: postgres

That second block is the part worth planning for. The vector index lives in its own pgvector-enabled PostgreSQL database, separate from ByteChef's application database - the development compose file runs one for you alongside the main Postgres, and in production it's a second database to provision, monitor, and back up. Still Postgres, still nothing exotic, but not the same Postgres. ByteChef creates the schema and the index inside it on first use.

One more prerequisite, easy to miss: an embedding model has to be active for the environment. Without one there's nothing to turn chunks into vectors with, and the Knowledge Base page says so outright rather than quietly indexing nothing.

Wrapping Up

The distance between "agents are impressive" and "agents are useful here" is almost always knowledge - your documents, your data, your vocabulary. RAG closes that distance in principle; in practice it comes bundled with a parsing zoo, a vector database, an embedding budget, sync jobs, and the deletion problem nobody budgets for.

ByteChef's Knowledge Base packages most of it: documents in through upload, a workflow action, or an agent; chunks and vectors in pgvector; retrieval exposed as agent tools, workflow actions, and a human search box. What stays with you is the refresh policy - how often to re-run ingestion, and what to do about the deletes. Your agents get something to know, and you skip almost all of the machinery of knowing.

Have a folder of PDFs your agent should be quoting? Open ByteChef, create a **Knowledge Base, drop them in, and attach the **Knowledge Base Search* tool to your agent.*

Agentic Workflow Patterns in ByteChef: The Five Patterns, No Code Required

ByteChef — Fri, 21 Aug 2026 21:21:45 +0000

TL;DR: Anthropic's Building Effective Agents research identified five workflow patterns behind most successful LLM systems: chain, parallelization, routing, orchestrator-workers, and evaluator-optimizer. The Spring AI team implemented them in Java. ByteChef - which uses Spring AI under the hood - lets you build every one of them visually, on a workflow canvas, without writing code. This post shows you how, pattern by pattern.

In late 2024, Anthropic published Building Effective Agents, a piece of research that has aged remarkably well. Its central claim: the most successful LLM systems in production aren't built on complex frameworks - they're built from simple, composable patterns.

The Spring AI team followed up with an excellent blog post implementing those patterns in plain Java. If you're a Java developer, it's a great read.

But here's the thing: ByteChef is built on top of Spring AI. Every model integration, every structured-output call, every RAG pipeline in ByteChef runs on the same Spring AI foundation described in that post. Which means the same five agentic patterns are available to you - except instead of writing Java classes, you drag components onto a canvas.

Anthropic draws a useful distinction between two kinds of agentic systems:

Workflows - systems where LLMs and tools are orchestrated through predefined paths. You decide the structure; the LLM fills in the intelligence.
Agents - systems where the LLM dynamically directs its own process and tool usage.

Most production use cases are best served by workflows: they're predictable, debuggable, and cheaper to run. And a visual workflow builder is arguably the most natural way to express them - the pattern diagrams in Anthropic's paper practically are ByteChef canvases.

Let's build all five.

The Building Blocks

Before diving into the patterns, a quick inventory of the ByteChef pieces we'll compose them from:

AI model steps - every AI provider component (OpenAI, Anthropic, Vertex Gemini, Mistral, Ollama, and many more) exposes an Ask action: prompt in, response out. Crucially, you can set the Response Format to Structured data and define a Response Schema, so the model returns typed JSON instead of free text - the visual equivalent of Spring AI's structured output converter.
The AI Agent component - ByteChef's full agent building block, with pluggable Model, RAG, Memory, Tools, and Guardrails cluster elements. We covered it in depth in Building Intelligent Automation with ByteChef and AI Agents.
Flow controls - the visual control-flow primitives that give workflows the same expressive power as code: Condition, Branch, and Loop for choice and repetition, plus Parallel, Fork/Join, Each, and Map for fanning out. Loop Break, which ends a loop early from inside its body, pairs with Loop.
Data pills - ByteChef's way of wiring one step's output into another step's input. Wherever you see "pass the result to the next step" below, that's a drag-and-drop data pill.

That's the whole toolbox. Now the patterns.

1. Chain Workflow

The simplest pattern, and the one to reach for first: decompose a task into sequential steps, where each LLM call processes the output of the previous one.

Why bother with three small prompts instead of one big one? Because each step gets a focused, simple instruction - and focused instructions produce dramatically more reliable results than one prompt trying to do everything at once. You're trading a little latency for a lot of accuracy.

Building it in ByteChef

Add an AI model step (say, OpenAI Ask) with a prompt that handles only the first transformation - e.g. "Extract every numerical value and its metric from this text."
Add a second model step whose prompt performs the next transformation, and reference the first step's output as a data pill: "Convert all values to percentages: ${openai_1}". (In text mode an Ask step outputs its response string directly - field references like ${openai_1.category} become available once you switch it to Structured data.)
Keep chaining. Each step sees only what the previous step produced.

You can also insert a Condition between steps as a gate - Anthropic's recommended addition - to verify an intermediate result before continuing (for example, checking that step one actually produced a number before running the expensive formatting step).

Use it when: the task has clear sequential stages, each stage builds on the last, and you'd rather wait an extra second than get a sloppy answer. A typical example: extract data → normalize it → sort it → format it as a Markdown table.

2. Parallelization Workflow

Some tasks aren't sequential - they're several independent subtasks that can run at the same time, with the results aggregated at the end.

Anthropic describes two flavors:

Sectioning - split the task into independent subtasks (analyze the same document from a legal, financial, and technical perspective).
Voting - run the same prompt several times and compare answers for consensus (useful for high-stakes classification).

Building it in ByteChef

Add a Fork/Join flow control. Each branch runs in parallel as an isolated sub-flow.
In each branch, add an AI model step with its own perspective-specific prompt. All branches can reference the same input via data pills.
After the join, add one final model step that receives all branch outputs and synthesizes them: "Combine these three analyses into a single executive summary."

For list-shaped work - "run this same LLM analysis over 50 support tickets" - use the Each flow control instead: it iterates over the items in parallel, applying the same steps to every one. And with the Parallel flow control you can fire off a set of independent tasks without waiting for each other.

Use it when: subtasks are genuinely independent, you need multiple perspectives on the same input, or you're processing volumes where sequential execution would be painfully slow.

3. Routing Workflow

Routing classifies the input first, then sends it down a specialized path. Instead of one generalist prompt trying to handle billing questions, technical issues, and small talk equally badly, each category gets a handler tuned for exactly its kind of input.

Building it in ByteChef

Add an AI model step as the classifier. Set its Response Format to Structured data and define a Response Schema with a single string field restricted to your categories (billing, technical, general). Constraining the output through the schema is what makes routing dependable - instead of a free-text answer the Branch can't act on, you get one of your category strings back.
Add a Branch flow control keyed on the classifier's output. Branch executes exactly one path based on the expression value - a visual switch statement. Add a default branch as well: the schema constrains the shape of the answer, not its judgment, so a classifier can still misfire or return something you didn't plan for.
In each branch, add the specialized handler: a model step with a category-specific system prompt, a full AI Agent with category-specific tools, or no LLM at all (some routes just need a Slack notification).

This isn't hypothetical - it's exactly the architecture of our AI Email Classifier tutorial, which routes incoming emails to Sales, Support, Finance, Operations, and HR using OpenAI structured output plus branching - default branch included. Routing is arguably the most production-proven agentic pattern there is.

Use it when: inputs fall into distinct categories that benefit from separate handling, and classification is reliable. Bonus: you can route easy categories to a small, cheap model and reserve the expensive one for the hard cases.

4. Orchestrator-Workers

The patterns so far have fixed structure - you know at design time which steps run. Orchestrator-workers is for tasks where the required subtasks can't be predicted in advance. A central LLM analyzes the request, breaks it into subtasks dynamically, delegates each one to a specialized worker, and synthesizes the results.

Building it in ByteChef

This is where ByteChef's AI Agent component shines, because an AI Agent can use another AI Agent as a tool:

Add an AI Agent as the orchestrator. Its system prompt describes its job: analyze the request, decide which specialists to involve, and combine their answers.
Under its Tools cluster element, add sub-agents - a research agent, a drafting agent, a data-lookup agent - each with its own model, system prompt, and tools. Give each a clear description so the orchestrator knows when to delegate to it.
The orchestrator now decides at runtime which workers to call, in what order, and how to merge their outputs. The composition is recursive: sub-agents can have sub-agents of their own.

Prefer to keep the orchestration explicit on the canvas? There's a workflow-level variant: have an orchestrator model step emit a structured list of subtasks, feed that list into an Each flow control that runs a worker step per subtask in parallel, then aggregate with a final LLM step. You get dynamic decomposition while every execution stays visible in the workflow history, step by step.

We covered agent composition, the Agent Playbook for testing, and the full cluster-element architecture in the AI Agent deep dive.

Use it when: you can't enumerate the subtasks up front - complex research questions, multi-file code changes, requests that span several domains at once.

5. Evaluator-Optimizer

The last pattern adds something the others lack: self-correction. One LLM generates a response; a second LLM evaluates it against explicit criteria. If the evaluation fails, the feedback goes back to the generator for another attempt - a draft-and-review loop, automated.

Building it in ByteChef

Add a Loop flow control and set its List of Items to a fixed three-element list. That caps the attempts at three - if it isn't converging by then, more laps rarely help.
Inside the loop, add the generator model step. Its prompt includes the task plus, via data pills, the previous attempt and the evaluator's feedback when they exist.
Add the evaluator model step with structured output: a schema with an evaluation field constrained to PASS / NEEDS_IMPROVEMENT and a feedback string. Give it concrete criteria - "evaluate for correctness, completeness, and tone" beats "is this good?".
Add a Condition on the evaluation. On PASS, put a Loop Break in that branch - it ends the enclosing loop immediately and you carry on with the accepted result. Otherwise the loop runs again, and the generator sees the fresh feedback.

Two different prompts - or even two different models - playing generator and critic consistently outperforms a single model trying to self-assess in one call.

Use it when: you have clear evaluation criteria and the output is worth iterating on - customer-facing copy, generated code, translations, anything with a quality bar. Skip it for cheap, low-stakes outputs; the extra LLM calls should buy you measurable quality.

Why Spring AI Under the Hood Matters

The Spring AI post closes by highlighting what the framework contributes to these patterns. Because ByteChef is built on Spring AI, you inherit every one of those advantages - plus a few that only a visual platform can add:

Model portability. Spring AI's ChatModel abstraction normalizes providers, so in ByteChef swapping OpenAI for Claude, Gemini, or a local Ollama model is a dropdown change, not a refactor. Build the pattern once, A/B the model later.
Structured output. Every response schema you define in a ByteChef AI step rides on Spring AI's structured-output machinery. Routing and evaluator-optimizer depend on this - patterns fall apart when the classifier answers with an essay.
A consistent, maintained foundation. New providers, new vector stores, and new capabilities land in Spring AI continuously, and ByteChef picks them up - without you rewriting workflows.

And what ByteChef adds on top:

Observability for free. Every pattern above produces a step-by-step execution history: every prompt, every intermediate output, every branch decision, inspectable per run. No logging code required.
Tools without glue code. Any action from ByteChef's 280+ connectors can be handed to an agent as a tool - the orchestrator pattern gets Slack, Salesforce, and Google Sheets access in a few clicks.
Guardrails and testing built in. Wrap any agent in content and topic guardrails, and test it live in the Agent Playbook while you build.

Choosing the Right Pattern

Chain - Fixed, sequential - The task has clear stages that build on each other
Parallelization - Fixed, concurrent -Subtasks are independent, or you want multiple perspectives
Routing - Fixed paths, dynamic choice - Inputs fall into categories needing different handling
Orchestrator-workers - Dynamic - Subtasks can't be predicted at design time
Evaluator-optimizer - Iterative - Clear quality criteria exist, and iteration measurably helps |

Anthropic's guidance - echoed by the Spring AI team, and just as true on a canvas as in Java - is worth repeating: start with the simplest pattern that could work. A well-prompted single LLM step beats a five-agent system that nobody can debug. Add parallelization when latency hurts, routing when one prompt stops fitting all inputs, and orchestration only when the task genuinely demands dynamic decomposition. Complexity should be earned.

The nice thing about building these patterns visually is that upgrading between them is cheap: a chain becomes a routing workflow by dropping in one classifier step and a Branch; a single agent becomes an orchestrator by adding sub-agents to its Tools. Your architecture can grow exactly as fast as your use case does.

One Workflow, Many Lanes: Completing ByteChef's Flow Controls

ByteChef — Fri, 14 Aug 2026 18:36:57 +0000

TL;DR: ByteChef's workflow editor now exposes the full set of flow controls: alongside the familiar Condition, Branch, and Loop, you can drop Parallel, Fork/Join, Each, Map, and Subflow onto the canvas. That means workflows that fan out over lists, run independent steps concurrently, and call other workflows as reusable building blocks - all visually, no custom code. This closes out issue #1057, one of the longest-running feature checklists in the ByteChef repository.

Some GitHub issues are essays. Issue #1057 is a checklist:

[x] condition

[x] loop

[x] each

[x] branch

[x] map

[x] parallel

[x] fork-join

[x] subflow

Each of those checkboxes is a flow control - what the workflow engine internally calls a task dispatcher. A regular component does work: it sends the email, queries the database, calls the API. A task dispatcher never does work itself. It decides which tasks run, when, how many times, and with what data - it directs traffic.

We wrote about the first half of that checklist in our guide to flow controls: Condition routes on true/false, Branch picks one of several paths based on an expression, and Loop repeats steps over a list. Those cover decisions and repetition.

This post is about the second half - the controls that cover concurrency and composition. They've been running behind a feature flag while we hardened them one checkbox at a time; with the list complete, the flag is going away and the full set is available to everyone.

Why Sequential Isn't Always Enough

Every workflow starts as a straight line: trigger, then step one, then step two. That's the right default - it's easy to reason about, and each step can use the output of the one before it.

But real processes aren't always lines:

Onboarding a customer means creating a CRM record, provisioning an account, and notifying the sales channel - three things that don't depend on each other, so why wait?
Enriching 200 leads one at a time takes 200× as long as enriching them all at once.
Five different workflows all end with the same "notify the team" sequence, and you're tired of rebuilding it five times.

The first two are concurrency problems. The third is a composition problem. Here's the control for each.

Parallel: Independent Steps, All at Once

Parallel is the simplest of the new controls: give it a collection of tasks, and it runs them all concurrently without waiting for any of them to finish first.

{
    "name": "parallel_1",
    "type": "parallel/v1",
    "parameters": {
        "tasks": [
            {
                "name": "createCrmRecord",
                "type": "pipedrive/v1/createOrganization",
                "parameters": { "...": "..." }
            },
            {
                "name": "notifySales",
                "type": "slack/v2/sendMessage",
                "parameters": { "...": "..." }
            }
        ]
    }
}

Use it when you have a fixed set of different steps that don't depend on each other. The three-things-at-customer-onboarding case is exactly this.

Fork/Join: Parallel Branches, Sequential Inside

Fork/Join is Parallel's bigger sibling. Instead of a flat set of tasks, you define branches - each branch is a sequence of tasks that runs in order, but the branches themselves run in parallel to each other, each as its own isolated sub-flow:

{
    "name": "forkJoin_1",
    "type": "fork-join/v1",
    "parameters": {
        "branches": [
            [
                { "name": "fetchInvoices", "type": "..." },
                { "name": "summarizeInvoices", "type": "..." }
            ],
            [
                { "name": "fetchTickets", "type": "..." },
                { "name": "summarizeTickets", "type": "..." }
            ]
        ]
    }
}

The rule of thumb: reach for Parallel when each concurrent piece is a single step, and for Fork/Join when each concurrent piece is itself a pipeline. The "join" part means the workflow waits for every branch to finish before moving on, so the step after a Fork/Join can safely use results from all branches.

Each and Map: Fan Out Over a List

Loop already iterates over a list - but sequentially, one item at a time, in order. Each and Map iterate over a list in parallel: every item gets its own execution of the inner task at the same time.

The difference between the two is what you get back.

Each is for side effects. It runs the task for every item and returns nothing. Order of completion isn't guaranteed - and for firing off 200 notification emails, it doesn't need to be:

{
    "name": "each_1",
    "type": "each/v1",
    "parameters": {
        "items": "=leads",
        "iteratee": {
            "name": "sendFollowUp",
            "type": "gmail/v1/sendEmail",
            "parameters": { "to": "=each_1.item.email" }
        }
    }
}

Map is for transformations. It also runs in parallel, but it collects each item's result and returns them as a list - in an order that matches the source list, no matter which items finished first:

{
    "name": "map_1",
    "type": "map/v1",
    "parameters": {
        "items": "=range(1, 10)",
        "iteratee": [
            {
                "name": "enrich",
                "type": "...",
                "parameters": { "input": "=map_1.item" }
            }
        ]
    }
}

Inside the iteration, the current element is available as a data pill on the dispatcher itself - each_1.item, map_1.item - so inner steps can reference it like any other output.

So the lead-enrichment case from earlier: 200 leads, enriched concurrently, results back in the original order, ready for the next step. That's Map.

One honest footnote on the checklist: the infinite loop variant (loop until a break condition, with no list at all) is the one box still open on #1057. Loop already supports a Loop Break statement; the fully unbounded mode is still on the list.

Subflow: Workflows Calling Workflows

The controls above change how tasks run. Subflow changes what counts as a task: it starts another workflow as a child job of the current one, passes it inputs, and hands the child's output back as the step's output.

{
    "name": "subflow_1",
    "type": "subflow/v1",
    "parameters": {
        "workflowUuid": "notify-the-team",
        "inputs": {
            "channel": "#ops",
            "summary": "=map_1"
        }
    }
}

That's the composition problem solved: build "notify the team" once, with its own inputs, and call it from all five workflows. When it changes, it changes everywhere. Subflows show up in execution history as their own jobs, and the editor knows how to navigate into them so you can follow the chain.

Which One Do I Reach For?

You want to…	Use
Repeat steps over a list, one at a time, in order	Loop
Run a task for every item at once, no results needed	Each
Transform every item at once and keep the results, in order	Map
Run a fixed set of independent single steps concurrently	Parallel
Run several multi-step pipelines concurrently, then continue	Fork/Join
Reuse another workflow as a step	Subflow
Take one of two paths based on true/false	Condition
Take one of many paths based on a value	Branch

Two quick heuristics cover most decisions: per-item vs. fixed set (Each/Map/Loop iterate over data; Parallel/Fork-Join run a structure you defined), and results vs. side effects (Map collects, Each doesn't).

Why a Feature Flag, and Why It's Leaving

The workflow engine has been able to dispatch all of these for a while - the engine side of a task dispatcher is comparatively contained. The long tail was the editor. Every flow control is a nested structure on the canvas: it owns child tasks, those children need placeholders, drag-and-drop targets, correct auto-layout, and data pills that respect iteration scope. Getting Condition right taught us how much surface area each control adds, so we didn't ship the rest as one big drop.

Instead, the remaining controls went in behind a feature flag (ff-1057, named after the issue), which let us enable them incrementally, polish the rough edges. With every control now holding up in real workflows, the flag is being removed and the complete set becomes the default for every ByteChef instance - cloud and self-hosted.

If your workflows have been running in a single lane, give the new controls a try - the fastest way to feel the difference is to take an existing Loop over an independent list of items and swap it for a Map.

Stop the Workflow, Ask a Human: Human-in-the-Loop Approvals in ByteChef

ByteChef — Thu, 13 Aug 2026 15:20:34 +0000

TL;DR: ByteChef's Approval component pauses a running workflow until a person approves or rejects, optionally filling in a form whose answers flow straight into the next steps. Delivery is pluggable: Slack (with inline Approve/Discard buttons), Gmail, Outlook, Discord, Telegram, WhatsApp, and more - or ByteChef's new in-app Approval Tasks inbox. The approver clicks a signed link and needs no ByteChef account, and the workflow waits up to 60 days without holding a thread - human-in-the-loop (HITL), with no infrastructure of your own.

You build a workflow, and it runs beautifully - right up to the step you don't actually want it to run on its own. Issue the refund? Create the customer account? Book the leave?

Some steps shouldn't happen without a human's yes. What you want is simple to say: the workflow pauses, the right person gets pinged where they already work, they approve - maybe fill in a couple of fields - and the workflow picks up exactly where it stopped, with their answer in hand.

That pattern has a name - human-in-the-loop (HITL) - and in ByteChef it's the Approval component.

If you've read our use-case tutorials, you've already met it without an introduction. The KYC compliance workflow gates onboarding on a compliance officer's review. The Liferay onboarding workflow waits for a manager to fill in account details. PTO Elf holds leave requests for sign-off.

In each of those, approval was a supporting actor: "add an approval task here" and the tutorial moved on. This post is the missing introduction - what you configure, what your approver sees, and what the platform quietly does for you in between.

Adding an Approval Step

In the workflow editor, Approval is one component with one action: Request Approval. The minimal setup is no setup at all - leave everything blank and your approver simply gets Approve and Reject buttons.

Usually, you'll give it a form title, a description, and a list of form inputs. The form builder supports thirteen field types: text, textarea, number, email, password, checkbox, radio, select, date and datetime pickers, file upload, hidden fields, and raw custom HTML for anything else.

Each field carries the knobs you'd expect from a form builder: a label and description, a placeholder, a default value, and a required flag. Radio and select fields take label/value options, and a select can allow multiple choices with a minimum and maximum selection count.

Your Approver's Answers Become Data Pills

Here's the part that makes forms genuinely useful downstream: the approval step's output schema is generated from the fields you configure.

Add an accountName text field and a creditLimit number field, and the step's output is {approved: boolean, accountName: string, creditLimit: number}. Every one of those shows up as a data pill for the steps that follow.

That's how the Liferay tutorial creates an account "from the information received from the onboarding approval task" - the approver's answers are just the step's output, referenced like any other: ${approval_1.accountName}.

How the Approver Finds Out

A paused workflow is useless if nobody knows it's waiting. That's what approval channels are for - delivery mechanisms you attach to the approval step, right under the node's Channels port.

Most channels deliver the approval link to people outside ByteChef - a manager who has never opened the app and never will. Pick where your approvers already live: Slack, Gmail, Outlook 365, plain Email (SMTP), Discord, Telegram, WhatsApp, Twilio (SMS), Mattermost, Rocket.Chat, Infobip, or the embeddable Chat widget. Each uses its own connection.

The Slack channel has my favorite detail. If your approval has no form fields, there's no reason to send anyone to a web page, so it doesn't. Approvers get Approve and Discard buttons right in the Slack message, and the approval resolves without leaving the chat. If there is a form, the message carries a single "Open Approval Form" button instead.

One channel is different: Approval Task. Instead of sending the link out, it creates a task inside ByteChef, on the new Approval Tasks page - an approval inbox for teams that live in the app.

Each task has a status (open, in progress, completed), a priority, an assignee, and a due date, and the page supports filtering, search, and sorting. If your approvers are ByteChef users, their pending approvals queue up in one place instead of scattering across inboxes.

One small courtesy across all channels: they're skipped when the step runs inside the workflow editor's test mode, so testing a workflow doesn't spam your approvers.

And because channels are plug-ins (cluster elements) rather than baked-in integrations, the delivery list can grow without touching the Approval component itself.

What the Approver Experiences

Your approver clicks a link and lands on a form page: title, description, fields, and environment badge. No login, no account, no "first, install ByteChef" - which is the point, because the person approving is often exactly the person who'd never log in.

That works because the link itself is the credential. The token in the URL wraps the approval's identity in an HMAC signature, so it can't be guessed or forged - the same trust model as any webhook callback. Possessing the link is the authorization.

A link is good for exactly one decision. Once the approval is submitted - or the 60-day window passes - the link answers 410 Gone, so a stale email can't resurrect a settled question.

Meanwhile, the Workflow Waits

While your approver takes their time, what is the workflow doing? Nothing - and that's the engineering trick worth knowing about.

The approval action doesn't block a thread, poll a flag, or sleep. It registers a suspension with the engine and returns; the engine parks the execution, persists everything, and releases the worker. The workflow can stay parked for up to 60 days; the server can restart, redeploy, or scale to zero in the meantime. Nothing waits in memory.

When the approver submits, the engine re-enters the action through a second entry point with the submitted data, and the workflow resumes exactly where it stopped - the form answers flattened into the output schema those data pills promised.

Long-time users might remember the old ways of doing this: a dedicated wait-for-approval flow control and a Create Approval Links action that handed out bare approve/reject URLs. Both are now deprecated, because a flow control can pause but it can't be a component - with a form builder, a typed output, delivery channels, and one more trick below.

Coming Next: The Same Step, Inside an AI Agent

Human-in-the-loop matters most where the human is easiest to lose: AI agents. An autonomous agent is exactly as trustworthy as its worst tool call, and "pause and ask a person" is the simplest guardrail there is.

The suspend-and-resume machinery above is exactly what an agent needs, so we're working on exposing Approval as a tool you can hand to a ByteChef AI agent: the agent decides it needs sign-off, composes the form, calls the tool, and the whole agent conversation parks until a human answers. From the model's perspective, it asked a tool a question and the tool answered - it just took a day and a half.

It's not in today's build - we'd rather ship it solid than early - but it's close, and it lands in one of the next releases.

When You'd Reach for It

The use-case posts each show one pattern, and they generalize:

Gate: Nothing proceeds without a yes/no compliance review before account creation (KYC) or manager sign-off before booking PTO. No form fields needed; Slack buttons suffice.
Gate with input: the approver doesn't just consent; they contribute - the Liferay onboarding manager supplies the account name and description the next step uses to create the account.
Threshold escalation: the workflow handles the routine cases on its own and branches into an approval only for the consequential ones - refunds over a limit, contract changes, anything you'd want a human to see before it happens.

If you want to see approval in a full workflow, the KYC compliance and Liferay onboarding posts both build one end-to-end, and now you know what's happening under the pause.

See What Your Workflow Was Thinking: Surfacing Component Logs in ByteChef

ByteChef — Fri, 07 Aug 2026 19:55:03 +0000

TL;DR: ByteChef's Logger component could always write log messages - but they vanished into the server console, where workflow builders could never see them. We fixed that by capturing log calls at the layer every component passes through, storing them per execution, and exposing them in a new Logs tab in both the workflow builder and the execution history. Every component's logs - not just Logger's - now show up next to the step's Input and Output, with level badges, JSON pretty-printing, and expandable stack traces.

Every automation platform eventually gets this ticket. Ours was issue #2896, and it was refreshingly short:

As a Workflow Developer, I want to see logs from the Logger component in the workflow builder and workflow executions, so that I can see details of how my workflows are executing.

ByteChef has had a Logger component for a long time. You drop it between two steps, give it a message - usually with a few data pills in it - and pick a level: Debug, Info, Warn, or Error. That's the whole component.

The problem: the message went to the server log and nowhere else. If you self-hosted ByteChef and had shell access, you could tail the server log and find it. If you were a workflow builder working in the UI - the person the Logger component exists for - it went into a void. The component technically worked and was practically useless.

Deciding Where to Capture

The obvious fix would have been to special-case the Logger component: make it return its message as step output, or write to some Logger-specific store. We went a different way, and it's the decision the whole feature hangs on.

Every component action in ByteChef receives an execution context, and that context's logging method is the sanctioned way for any component to log - the HTTP client logs request failures, Script components log from user code, AI components log token usage warnings. All of those messages were equally invisible.

So instead of touching the Logger component at all, we instrumented the logging implementation inside the component context - the single funnel that every log call in every component already passes through. Each message still goes to the server log like before, but now it also becomes a structured entry: timestamp, level, component name, operation, the step it came from, the message, and - when there is one - the exception type, message, and stack trace.

Because the capture point sits below every component, the feature ships for all 180+ components at once. The Logger component didn't change by a single line. It just became visible.

Storing Logs: One File per Execution

Logs are append-heavy, read-rarely data with an obvious partition key: the job - a single workflow execution. That ruled out a database table. We didn't want every workflow run inserting rows into PostgreSQL for data that's mostly never queried.

Instead, each job gets one file in ByteChef's existing file-storage abstraction, which means logs land wherever your deployment already puts files - the filesystem, a database blob, or S3-compatible storage. The format is JSON Lines: one JSON object per line, so appending an entry is just serialize-and-append.

Two properties of the writer matter more than they look.

First, writes are asynchronous. Logging must never slow down the workflow itself - a component that logs five times shouldn't pay five rounds of storage I/O on the execution path. Java 25's virtual threads make that fire-and-forget pattern nearly free.

Second, the read path is guarded by the same permission model as everything else that touches executions. Logs frequently contain payload data - that's the point of logging them - so they inherit the exact visibility rules of the execution they belong to. If you can't see the run, you can't see its logs.

Two Environments, Two Pipelines

There's a wrinkle: ByteChef has two kinds of "execution". There are production runs of deployed workflows, and there are test runs you trigger with the Test button while building a workflow in the editor. Test runs are ephemeral - their logs shouldn't accumulate in long-term storage next to production history.

So the feature is split down the middle. Production runs write to the long-term log area and are served to the execution history view. Editor runs write to a separate area with their own cleanup, served by a parallel query. The context factory decides which writer a component gets based on which environment it's running in, and the client picks the matching query. Same UI, same log format, different lifecycle.

The Read API

The read API is GraphQL, matching where the rest of ByteChef's newer client-server surface has been heading. It supports pagination and filtering from day one: minimum level, component name, a specific step, a time range, and free-text search.

The per-step filter is what powers the most-used view: click a node in the execution panel, and you see only that step's logs. Look at the job as a whole, and you see everything, with a small component-name chip on each row so you can tell who said what.

The Logs Tab

On the client, the execution detail panel - the one with Input and Output tabs you get when you click a step - gains a third tab: Logs.

That's a real run above - and it's worth noting whose log you're looking at. The workflow has a Logger component in it, sitting right there in the graph on the right. But the entry on screen came from the OpenAI step, which logged its outgoing request without anyone asking it to. That's the capture-one-layer-down decision paying off in a screenshot: the component that made the ticket necessary isn't even the one being shown.

Each row shows a timestamp, a colored level badge (blue INFO, purple DEBUG, yellow WARN, red ERROR), and the message. Two small touches make it feel finished rather than bolted on:

JSON detection. People constantly log entire objects - dumping a payload into a log line is a very common debugging move. If a message parses as JSON, the tab renders it with the same collapsible tree viewer we use for step outputs, instead of an unreadable one-liner.

Expandable errors. When an entry carries exception details, the row becomes clickable and expands into the exception type, message, and full stack trace - so a failed step's story is readable in place, without asking an operator to grep the server log for you.

And because the editor pipeline exists, the same tab appears in the workflow builder's test output panel. Run a workflow with the Test button, click a step, open Logs - the feedback loop that issue #2896 asked for, closed.

One Layer Down

The lesson we're taking from this one: when a ticket says "make the Logger component's output visible", the right fix might be one layer down. By instrumenting the context instead of the component, a request about one component became execution-level observability for every component in the platform - including the ones we haven't built yet.

DEV Community: ByteChef

ByteChef Embedded, Part 5: The Request Playground

Set Up the Request Trigger

Finding the Workflow UUID

A Workflow, Callable Like a Function

Where It Fits Among the Triggers

What You Didn't Build

What's Next

ByteChef Embedded, Part 4: The App Event Playground

Emit an Event, Trigger Their Workflows

See Every Run

Why This Closes the Loop

What You Didn't Build

What's Next

ByteChef Embedded, Part 2: The ComponentKit Playground

The Playground Page

The Route: One POST to ByteChef

Why This Matters

What You Didn't Build

Running It Yourself

What's Next

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

The Auth Model: Connected Users, Not ByteChef Accounts

Listing the Integrations You Offer

The Star of Part One: useConnectDialog

After the Connect: the Same Dialog Manages It

What You Didn't Build

What's Next in This Series

Running the Sample App Yourself

Share What You Built: Project & Workflow Templates

Start From a Working Automation

Share What You Built

The Link Stays Yours

What Travels, and What Doesn't

Listing in the Public Gallery

Why Sharing Compounds

Wrapping Up

Somewhere to Keep the Records: Data Tables in ByteChef

Set One Up in a Minute

Test Data Stays Test Data

Six Actions: Tables in Your Workflows

Three Triggers: Tables That Start Workflows

Agents Can Use Them Too

Where It Fits

Wrapping Up

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

What Is an Agent Skill?

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

Skills at Runtime: The Skills Tool

Built-In Skills Management

The Payoff: One Skill, Many Agents

Skills, System Prompts, or RAG?

What You Inherit from Spring AI - and What ByteChef Adds

Best Practices for Writing Skills

Wrapping Up

Your Documents, Chunked and Searchable: The Knowledge Base in ByteChef

What a Knowledge Base Is

Getting Documents In

Keeping It Current - and the Deletes Nobody Plans For

Getting Knowledge Out

What You Inherit from Spring AI - and What ByteChef Adds

Running It Yourself

Wrapping Up

Agentic Workflow Patterns in ByteChef: The Five Patterns, No Code Required

The Building Blocks

1. Chain Workflow

Building it in ByteChef

2. Parallelization Workflow

Building it in ByteChef

3. Routing Workflow

Building it in ByteChef

4. Orchestrator-Workers

Building it in ByteChef

5. Evaluator-Optimizer

Building it in ByteChef

Why Spring AI Under the Hood Matters

Choosing the Right Pattern

One Workflow, Many Lanes: Completing ByteChef's Flow Controls

Why Sequential Isn't Always Enough

Parallel: Independent Steps, All at Once

The Star of Part One: `useConnectDialog`