Agentic Workflow Data Model
Audience: Administrators, Developers, and Solution Architects
Purpose: Explains how Agentic Workflows, executions, and step history are structured, related, and persisted, so you can design reliable integrations, interpret execution data correctly, and build API-driven workflows with a robust understanding of the underlying data.
Overview
Agentic Workflows are backed by a structured data model that governs how workflow configurations, execution Records, and step history are stored and related. Understanding this model is essential when you build integrations, work with the API, or need to trace how execution data relates back to its source entities.
The model spans the core entities that define an Agentic Workflow, as well as the execution and step history Records those entities produce at runtime. The model also frames the guarantees and boundaries that govern that data, and the encoding applied when that data crosses system boundaries through APIs and webhooks.
Use the Agentic Workflow data model if you are:
Building integrations that read execution or step history data
Working with Agentic Workflows executions through the API
Interpreting execution Records and step history to debug a run or to trace which steps ran and what data they produced
The data model builds on the Agentic Workflow Core Concepts and the Agentic Workflow Execution & Process Model.
How Agentic Workflow Data Is Organized
The data model is built from a small set of core entities in a nested hierarchy. Each level contains the next: an Agentic Workflow can have many executions, and each execution can generate many step history Records.
Record-scoped configurations sit under an Object, which can have many Agentic Workflows. Global configurations have no Object above them, so their hierarchy starts at the Agentic Workflow.
Core Components
Agentic Workflow configuration: The Agentic Workflow definition itself, along with its triggers and steps. A configuration is either Record-scoped, tied to a specific Object and running in the context of one Record, or else it's global, running without a Record context for platform-wide logic.
Execution: A single run of an Agentic Workflow, created when a trigger fires. Record-scoped executions runs against a specific Record. One Agentic Workflow configuration can have many executions over time, each as an independent run.
Step history: The step-level events within an execution. Each Record identifies the step, when it was created, when it was last updated, a detailed log, and its current status (Pending, Pending Retry, Completed, and so on). A single step can produce multiple step history Records within one execution if it runs more than once.
The components form a navigable hierarchy. Use it to move between a configuration, its executions, and the step history within a given execution, whether you're troubleshooting in the UI or working with the API directly.
Step History vs. Execution Records
An execution Record and its step history Records offer two different levels of detail:
The execution record is the summary of the overall run: its status, its start and end times, and its association with the Agentic Workflow and the Record.
The step history records are the details, the individual step-level events within that run.
To debug a run, start from the execution Record for the summary, then use step history for the moment-to-moment analysis.
Agentic Workflow Execution
An Agentic Workflow execution has a defined data model, covering the data it holds, the guarantees the platform makes about that data, and how deleted steps appear in the historical record.
Execution Status
An execution tracks its current status, not a history of the transitions it has moved through. Its key fields are:
status
String (enum)
The execution's current state: Active, Paused, Canceled, Completed or Failed.
priority
String (enum)
Which queue lane the execution runs in, Standard Processing for low-latency operational runs or Low / Data Seeding for bulk/migration work. Child executions inherit the parent's priority.
in_queue
Boolean
True when the execution is queued but hasn't started running yet.
debug_mode
Boolean
Whether the execution pauses at each step for manual advance.
created
Timestamp (date-time)
When the execution was created.
updated
Timestamp (date-time)
When the execution was last updated.
For the operational meaning of each state and how to interpret it in the UI, see Agentic Workflow Status & Lifecycle.
Data Guarantees & Boundaries
Execution Records guarantee certain data unconditionally, and they bound other data by scope or by configuration changes made after the run.
Guarantees: Every execution has a start timestamp, and every step that has started has a step history record (not only those steps that complete or fail). The state of variables is captured at the execution level. Each step history record carries an
is_pendingflag. Once it's set to false, the record is frozen and won't be modified again. Once an execution reaches a terminal state (Canceled, Failed, or Completed), it can't be resumed or modified, except in debug mode, where you can restart an execution from any previous step.Boundaries: Only variable values are scoped to a single execution. Record changes are visible immediately to any other automation running against that Record. Most steps run sequentially, but condition, code, and HTTP request steps can execute in parallel across branches, and step history covers every branch in that run.
Delete Steps
When a step is deleted from an Agentic Workflow configuration after it's already run, Kizen retains the history of its executions. The API returns that history, with the deleted step marked [Deleted]. In the product, that history shows in the list view, though not in the canvas view.
The step's own configuration isn't retained. You can't view a deleted step in the product or through the API. Don't rely on resolving a historical step history record back to the configuration that produced it.
How the Data Model Maps to APIs and Webhooks
The Agentic Workflow data model is exposed through APIs and webhooks, and through the encoding model used to represent variable values as they cross system boundaries.
Mapping to APIs
The Agentic Workflow configuration maps to an API resource, allowing you to list and filter configurations through the API. The response includes the configuration's identity (id, name, api_name) and its type (record_based or global) and active state.
It also carries a revision number, live counts of active, paused, and completed executions, and the custom object and folder it belongs to. Audit fields track who created and last updated it.
For endpoint-level detail on what's currently available, see the Kizen API Reference.
Mapping to Webhooks
Before the execution starts, Kizen checks that the caller has permission to start Agentic Workflows on the Record's Object, plus View access to the Record itself. A call that fails either check is rejected with a 403 and no execution is created. The Record reference also determines whether the run executes in Record context, since global Agentic Workflows don't require one.
One webhook call produces one execution, tied to the Agentic Workflow and Record named in the request. That's what lets you trace a webhook call forward to the execution it produced, or trace an execution Record back to the webhook that triggered it.
Variable Encoding Model
Agentic Workflow variable values are encoded as type/value (T/V) pairs when they are passed across system boundaries, such as in API responses, webhook payloads, and execution history. For example, a String value encodes as:
Each value is encoded as a pair where the type code identifies the Kizen data type and the value contains the serialized content. This encoding exists because Kizen's type system is richer than native JSON, so a custom encoding is needed to preserve type fidelity.
For the full list of type codes and more examples, review the Kizen Data Types and Data Encoding in Agentic Workflow Code Steps.
What's Next
Continue to Agentic Workflow Code Steps to see how the data model is applied in practice. Code steps build directly on the model described here:
How Kizen variable values are encoded and passed into code step execution
How typed Objects are provided for working with complex field types
How execution history captures code step inputs, outputs, and logs
Continue in sequence through the developer documentation for a complete understanding of how to build advanced Agentic Workflow logic programmatically.
Last updated
Was this helpful?