Context, DTOs & Variables

During a workflow run, state and step outputs are tracked using three Data Transfer Objects (DTOs). When testing a workflow inside the Visual Workflow Editor, the test runner automatically constructs these DTOs and returns their state in the execution log panel.

1. WorkflowContextDto

Tokomono\AiSuite\Workflows\Data\WorkflowContextDto holds the state and execution history of a single workflow run. You pass this object to $engine->run($definition, $context).

Property / Method	Type	Default	Description
$workflowRecord	?Workflow	null	Optional Eloquent Workflow model associated with this run.
$globalVariables	array<string, mixed>	[]	Global key-value store for input and intermediate state. StartModule reads $globalVariables['question'] as the initial output by default. Custom PHP modules can read and mutate this array.
$clearConversation	bool	false	Controls whether an AgentModule continues the authenticated user's last conversation (false) or starts a new conversation (true).
$currentStepNodeId	string	''	Updated by the engine with the id of the node currently being executed.
$error	?string	null	Stores the error message if a module (e.g., Agent, PHP Code, or If/Else) fails. Remains null when execution succeeds.
$steps	WorkflowStepDto[]	[]	Chronological list of all steps executed during the run.
getPreviousStepOutput()	?WorkflowPayloadDto	—	Returns the WorkflowPayloadDto produced by the immediately preceding step.
getHistory(?string $id = null)	mixed	—	Without arguments: returns an associative array ['node_id' => WorkflowPayloadDto] of all executed nodes. With $id: returns the WorkflowPayloadDto for that specific node ID.
addToHistory(string $id, mixed $output)	void	—	Stores a node's output in history under its node ID.

How clearConversation Works

When a workflow reaches an AgentModule and a user is authenticated (auth()->check()):

• clearConversation: false (default): Calls $agent->continueLastConversation(auth()->user()). The agent remembers previous messages from this user across earlier runs or steps and continues in the same conversation thread.
• clearConversation: true: Calls $agent->forUser(auth()->user()) without loading previous conversation history, starting a clean conversation thread. Immediately afterward, AgentModule resets $context->clearConversation = false so that any subsequent agent nodes within the same workflow run continue inside that newly started conversation.

---

2. WorkflowPayloadDto

Every node output is wrapped by the WorkflowEngine in a Tokomono\AiSuite\Workflows\Data\WorkflowPayloadDto. This object implements Stringable (__toString()) and JsonSerializable.

Property / Method	Type	Description
$content	mixed (?string)	Text representation of the output. If a module returns an array or object without a 'content' or 'value' key, $content automatically contains its pretty-printed JSON string.
$data	array	Structured array data (e.g., from a HasStructuredOutput AI agent or a custom PHP module returning an array).
(string) $payload	string	Returns (string) $payload->content.
toArray()	array	Returns ['content' => $this->content, 'data' => $this->data].

---

3. WorkflowStepDto

Each entry in $context->steps is an instance of Tokomono\AiSuite\Workflows\Data\WorkflowStepDto:

Property	Type	Description
$nodeName	string	The id of the executed node (e.g., 'node_start', 'node_php').
$outputData	WorkflowPayloadDto	The output of this step wrapped in a WorkflowPayloadDto.
$meta	array	Metadata about the step: ['module_type' => string, 'next_route' => mixed].
$thinking	?string	Optional reasoning/thinking output.
$cost	?float	Optional step execution cost.
$processingTimeMs	?float	Optional processing time in milliseconds.
$confidenceScore	?float	Optional confidence score.

---

4. Using Variables in Prompts ({{...}})

Inside an AgentModule, you can use dynamic placeholders in the prompt configuration:

1. Global variables ($context->globalVariables): Use {{variable_name}}. For example, if $context->globalVariables['customer_name'] = 'Jane', Hello {{customer_name}} resolves to Hello Jane.
2. Outputs from previous nodes ($context->getHistory()): Use {{node_id}} to inject the output of a specific earlier node. For example, in Claim Handler, Answer nicely based on: {{node_php}} injects the string output (WorkflowPayloadDto::$content) of node_php.
3. Empty prompt: If you leave prompt empty in AgentModule, the agent automatically uses the output of the immediately preceding step ((string) $context->getPreviousStepOutput()).