Complete field-level documentation for pipeline steps, agents, tools, KB entries, and message context — plus a full glossary of ZaronAI terminology.
Each step in a Workflow is a pipelineSteps record.
These fields control how the step runs, what it calls, and
where control goes next.
| Field | Type | Description |
|---|---|---|
| pkey | Long | Primary key. Auto-assigned. |
| stepOrder | Decimal | Display and load order within the workflow. Lower numbers run first. |
| stepLabel | String | Unique name for this step within the workflow.
Used as the routing target by nextStepOnSuccess,
nextStepOnFailure, and Router outcomes.
Required |
| stepType | String | Controls special execution behavior.
ROUTER — reads outcomeFieldName
and jumps to the matching step label.
GOTO — immediately advances to
nextStepOnSuccess without calling the AI.
Leave blank for a normal agent step. |
| targetAgentPkey | Long | The agent this step invokes. Links to the chatDefs
(agent) record. Required for non-GOTO steps. |
| isFinalAnswer | Boolean | When true, the pipeline stops after this step
and returns the agent’s output as the user-facing reply.
Set this on the Finalizer step. |
| useTools | Boolean | When true, the step’s agent is given access
to its configured tools during the tools pass. |
| useSchema | Boolean | When true, the step enforces its agent’s
response schema. Set both useTools and
useSchema to enable two-phase execution. |
| toolsMode | String | Passed directly to OpenAI as the tool availability setting.
Typical values: auto, none. |
| toolChoiceMode | String | Controls how OpenAI selects a tool.
auto — model decides.
required — model must call a tool.
none — no tools.
Note: required automatically switches to
auto after the first round to prevent
infinite calling loops. |
| toolChoiceFunctionName | String | When set, forces the model to call this specific tool
function by name (OpenAI force_function mode).
Switches to auto after the first round. |
| resultMode | Integer | 0 Replace — this step’s output
replaces the prior step’s output envelope.
1 Overlay — this step’s output
is merged onto the prior envelope, preserving any fields
not returned by this step. Useful for agents that
progressively fill a shared data structure. |
| advanceCriteria | JSON Array | Zero or more field-equality expressions that must all be
satisfied in the agent’s JSON response before the
pipeline advances. Example:
["issue_ok=true","identity_ok=true"].
If not met, the pipeline holds at this step and
returns the agent’s reply to the user. |
| preventEarlyExit | Boolean | When true, ZaronAI watches for departure
phrases in the user’s message. If advance criteria
are not yet met and departure intent is detected, a
reminder is appended to the agent’s reply listing
what is still required. |
| outcomeFieldName | String | For ROUTER steps: the field in the agent’s JSON
response that contains the route label.
For normal steps: the outcome field used to choose
between nextStepOnSuccess and
nextStepOnFailure. |
| successValues | String | Comma-separated values of outcomeFieldName
that are considered a success. Anything else routes to
nextStepOnFailure. |
| nextStepOnSuccess | String | Step label to jump to when the outcome is successful or advance criteria are met. |
| nextStepOnFailure | String | Step label to jump to on failure. Leave blank to hold at the current step. |
| stopOnError | Boolean | When true, an unhandled exception in this
step halts the pipeline and surfaces the error rather
than attempting to continue. |
| stepNotes | String | Developer notes. Not used at runtime. |
| recordactive | Boolean | Soft-delete flag. Set to 0 (false) to
disable a step without deleting it. |
When both useTools = true and
useSchema = true, ZaronAI runs the step twice:
Phase 1 with tools enabled (no schema), Phase 2 with schema
enforced (no tools). Tool results from Phase 1 are persisted to
the conversation history before Phase 2 runs.
An agent is a chatDefs record. It defines the AI
model, system prompt, and response schema for one role in
the pipeline.
| Field | Type | Description |
|---|---|---|
| modelName | String | OpenAI model identifier. Examples: gpt-4o,
gpt-4o-mini, gpt-4.1-nano.
Note: GPT-4.1 series does not support the Responses API. |
| systemPrompt | String (long) | The agent’s instruction set. Sent as the
system message before every conversation.
Changes take effect immediately on the next call —
no restart required. |
| responseSchema | JSON String | JSON Schema definition the agent must conform to when
useSchema = true on the calling step. Each
agent should have its own exclusive schema rather than
sharing one across agents. |
| temperature | Double | Controls response randomness. Range 0.0–2.0. default 0.7 Note: not supported by all models (e.g. o-series). |
| maxTokens | Integer | Maximum tokens in the model’s response. Passed as
max_tokens or max_completion_tokens
depending on the model. |
| useResponsesAPI | Boolean | When true, calls are routed to the OpenAI
Responses API instead of Chat Completions. Only compatible
with supported models. |
Tools are server-side functions an agent can call during its execution. The AI decides when to call them. ZaronAI executes them and returns the result to the AI in the next message.
Saves or updates contact fields for the current visitor session. Any field not passed is left unchanged. Call it incrementally — the AI can call it multiple times as the user provides more information across turns.
| Parameter | Type | Description |
|---|---|---|
| firstName | String | Visitor’s first name. |
| lastName | String | Visitor’s last name. |
| String | Email address. | |
| phone | String | Phone number. Normalized to E.164 format for SMS compatibility. |
| streetAddress | String | Street address line. |
| city | String | City. |
| state | String | State or province. |
| zip | String | Postal code. |
Searches the agent’s Knowledge Base JSON array using lexical scoring. No embeddings or external services required. Returns the top matching entries with confidence scores.
| Parameter | Type | Description |
|---|---|---|
| query | String | Search query. The tool tokenizes this into words and phrases and scores against each KB entry. Required |
| category | String | Optional. Filter to entries with this category value.
Matching entries also receive a confidence boost of
+2. |
| max_results | Integer | Maximum entries to return. Range 1–10. default 5 |
| min_confidence | Number | Minimum normalized confidence score (0–1) for an entry to be included. Range 0–1. default 0.35 |
| include_excerpt_chars | Integer | Character length of the content excerpt
returned per entry. Range 50–1500.
default 350 |
Title match: +5 per token •
Keyword match: +2 per token •
Content match: +1 per token •
Phrase bonus in title: +3 •
Phrase bonus in content: +1 •
Category match: +2
Called by the Finalizer agent to close the conversation and create the ticket record. Copies the saved visitor contact info into the output queue, assigns the ticket type, and triggers email and SMS dispatch via the client’s configured notification settings.
| Parameter | Type | Description |
|---|---|---|
| ticket_type | String | Classifies the ticket for routing and notification
labeling. Example values: Service,
Sales, General.
default "Service" |
After the ticket record is created,
cOutputQ.ProcessQ() dispatches notifications.
Email is sent via the ZaronAI.com hosting account.
SMS is sent via the client’s own Twilio credentials
(Twilio_SID, Twilio_Token,
Twilio_From) stored in the client’s
key bundle.
Each KB entry is a flat JSON object in the agent’s
referenceData array. All fields are siblings at
the top level — nothing is nested inside
content.
| Field | Type | Description |
|---|---|---|
| id | String | Unique identifier for this entry. Required |
| title | String | Entry title. Carries the highest scoring weight in
retrieval (+5 per token).
Required |
| category | String | Optional grouping label. Used for category-filter queries and scoring boost. |
| keywords | String Array | Additional terms that should trigger this entry.
Scoring weight +2 per match. |
| content | String | Plain prose description. Used for search excerpts and content-token scoring. Do not nest data fields inside this string. Required |
| price | Number / String | Product or service price. Sibling of
content, not inside it. |
| instock | Boolean | Inventory availability flag. |
| locations | String Array | Service area or store locations where this item applies. |
| weight | Number | Physical weight (product entries). |
| width / length / depth | Number | Physical dimensions (product entries). |
| shape | String | Shape descriptor (e.g. round, rectangular). |
| style | String | Style or finish descriptor. |
| recordActive | Boolean | Soft-delete flag. Inactive entries are excluded from retrieval. default true |
| updatedUTC | DateTime | ISO 8601 UTC timestamp of last update. |
Every turn in a conversation is stored as a
chatMessages record. ZaronAI builds each OpenAI
API request by loading only the messages where
includeInContext = true, in pkey order.
| Field | Type | Description |
|---|---|---|
| pkey | Long | Primary key. Defines message order within the conversation. |
| chatHdrPkey | Long | Session key. Links all messages for one visitor conversation. Required |
| role | String | OpenAI message role. One of:
system, user,
assistant, tool.
See role table below. |
| content | String | Message body text. |
| tool_call_id | String | OpenAI tool call ID. Required on tool role
messages to link the result back to the call. |
| tool_calls | JSON Array | Present on assistant messages when the model
requested tool calls. Stored as returned by OpenAI. |
| includeInContext | Boolean | When true, this message is included in the
next API request. Set to false to suppress
a message without deleting it. Pipeline user messages
are always set to true to preserve
conversation history across agents. |
| persistToolOutput | Boolean | When true on a tool definition, the tool’s
result is saved back into the message history as an
assistant message. This allows later agents to read
what an earlier tool returned — for example, the
contact info saved by save_user_info. |
| recordactive | Boolean | Soft-delete flag. Inactive messages are excluded from all context builds and queries. |
| Role | Purpose |
|---|---|
| system | The agent’s instruction set. Always the first message sent to OpenAI. Contains the system prompt from the agent record. |
| user | A message from the visitor, or an injected pipeline message passing context between steps. |
| assistant | A message from the AI model. Also used to persist tool output summaries back into conversation memory. |
| tool | The result returned by a tool call. Must include the
matching tool_call_id. |
OpenAI requires a strict message ordering:
system first, then alternating
user / assistant pairs, with
tool results immediately following the
assistant message that requested them.
ZaronAI assembles this ordering automatically from the
chatMessages table on every API call.
Every term used across ZaronAI documentation, in one place.
chatDefs record.pipelineSteps.stepType = "ROUTER". Reads the outcome field from the agent’s response and jumps to the matching step label. Supports any number of routes.stepType = "GOTO". Immediately advances to nextStepOnSuccess without calling the AI. Used for conditional branching logic.isFinalAnswer = true. Produces the user-facing reply and calls finalize_send_ticket to create the ticket record.system message before every conversation. Editable at any time without redeployment.issue_ok=true) stored on a pipeline step. All must be satisfied in the agent’s JSON response before the pipeline advances to the next step.preventEarlyExit = true. Detects departure phrases in the user’s message and appends a reminder of what is still needed before the conversation can close.useTools and useSchema are true.chatMessages record. When true, the message is included in the next OpenAI API call. Setting it to false suppresses the message without deleting it.true, the tool’s result is saved back into the conversation history as an assistant message, making it readable by later agents in the pipeline.save_user_info, retrieve_kb_entries, finalize_send_ticket.referenceData. Searched by the retrieve_kb_entries tool using lexical scoring. Domain-agnostic — works for any business type.finalize_send_ticket. Captures visitor contact info and conversation context. Queued for email and SMS dispatch via cOutputQ.ProcessQ().finalize_send_ticket that classifies the ticket (e.g. Service, Sales). Drives notification labels and routing. Defaults to "Service" if omitted.
recordActive = 0. All queries filter on this flag. Deleted records remain in the database for audit and recovery.+16155550100). ZaronAI normalizes phone numbers to this format when saved via save_user_info.