% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/Workflow.R
\name{Workflow}
\alias{Workflow}
\title{Workflow}
\description{
An R6 class for building sequential multi-agent pipelines. A `Workflow`
is composed of **Stations** (processing units - an `Agent`, a
`WorkflowAgent`, or any plain R function) connected by **Routes** (directed
links, optionally gated by a condition function). Execution is always
sequential: the output of one Station becomes the input of the next.

Stations whose results have already been computed can be retrieved from an
internal cache instead of being re-executed, which is useful when iterating
on later parts of the pipeline without paying the cost (or latency) of
earlier LLM calls.

A finished `Workflow` can be wrapped as a `WorkflowAgent` via
\code{$as_agent()}, making it composable with `LeadAgent` or embeddable as
a Station inside another `Workflow`.
}
\section{Public fields}{
\if{html}{\out{<div class="r6-fields">}}
\describe{
\item{\code{name}}{Workflow identifier.}

\item{\code{description}}{Optional human-readable description.}

\item{\code{use_cache}}{Whether to cache and reuse Station results.}

\item{\code{cache}}{Environment used as a hash-map for cached Station outputs.}

\item{\code{run_history}}{List of records from every \code{$run()} call.}

\item{\code{hitl_steps}}{Integer vector of step numbers at which execution pauses
for human review. Set via \code{$set_hitl()}.}
}
\if{html}{\out{</div>}}
}
\section{Methods}{
\subsection{Public methods}{
\itemize{
\item \href{#method-Workflow-new}{\code{Workflow$new()}}
\item \href{#method-Workflow-add_station}{\code{Workflow$add_station()}}
\item \href{#method-Workflow-add_route}{\code{Workflow$add_route()}}
\item \href{#method-Workflow-set_entry}{\code{Workflow$set_entry()}}
\item \href{#method-Workflow-run}{\code{Workflow$run()}}
\item \href{#method-Workflow-set_hitl}{\code{Workflow$set_hitl()}}
\item \href{#method-Workflow-clear_cache}{\code{Workflow$clear_cache()}}
\item \href{#method-Workflow-as_agent}{\code{Workflow$as_agent()}}
\item \href{#method-Workflow-visualize}{\code{Workflow$visualize()}}
}
}
\if{html}{\out{<hr>}}
\if{html}{\out{<a id="method-Workflow-new"></a>}}
\if{latex}{\out{\hypertarget{method-Workflow-new}{}}}
\subsection{Method \code{new()}}{
Create a new `Workflow`.
\subsection{Usage}{
\if{html}{\out{<div class="r">}}\preformatted{Workflow$new(name, description = NULL, use_cache = TRUE)}\if{html}{\out{</div>}}
}

\subsection{Arguments}{
\if{html}{\out{<div class="arguments">}}
\describe{
\item{\code{name}}{`[character(1)]` Workflow name.}

\item{\code{description}}{`[character(1)]` Optional description.}

\item{\code{use_cache}}{`[logical(1)]` Enable result caching (default `TRUE`).}
}
\if{html}{\out{</div>}}
}
}
\if{html}{\out{<hr>}}
\if{html}{\out{<a id="method-Workflow-add_station"></a>}}
\if{latex}{\out{\hypertarget{method-Workflow-add_station}{}}}
\subsection{Method \code{add_station()}}{
Add a Station to the workflow.

A Station is a named processing unit. Its `handler` can be:
\itemize{
  \item An `Agent` or `WorkflowAgent` - the Station calls
        \code{handler$invoke(input)}.
  \item A plain R `function(input)` - the Station calls
        \code{handler(input)} and coerces the return value to
        `character`.
}
\subsection{Usage}{
\if{html}{\out{<div class="r">}}\preformatted{Workflow$add_station(name, handler, description = NULL)}\if{html}{\out{</div>}}
}

\subsection{Arguments}{
\if{html}{\out{<div class="arguments">}}
\describe{
\item{\code{name}}{`[character(1)]` Unique Station name within this workflow.}

\item{\code{handler}}{An `Agent`, `WorkflowAgent`, or `function`.}

\item{\code{description}}{`[character(1)]` Optional human-readable description
(shown in \code{$visualize()}).}
}
\if{html}{\out{</div>}}
}
\subsection{Returns}{
Invisibly returns `self` for method chaining.
}
}
\if{html}{\out{<hr>}}
\if{html}{\out{<a id="method-Workflow-add_route"></a>}}
\if{latex}{\out{\hypertarget{method-Workflow-add_route}{}}}
\subsection{Method \code{add_route()}}{
Add a Route between two Stations.

Routes define the execution order. An optional `condition` function
receives the output of the `from` Station and must return `TRUE` or
`FALSE`. Conditional routes are evaluated first (in insertion order);
the first matching one is followed. If none match, the first
unconditional route from that Station is used as a default.
\subsection{Usage}{
\if{html}{\out{<div class="r">}}\preformatted{Workflow$add_route(from, to, condition = NULL)}\if{html}{\out{</div>}}
}

\subsection{Arguments}{
\if{html}{\out{<div class="arguments">}}
\describe{
\item{\code{from}}{`[character(1)]` Name of the source Station.}

\item{\code{to}}{`[character(1)]` Name of the destination Station.}

\item{\code{condition}}{`[function | NULL]` A function \code{function(output)}
returning a single logical value. `NULL` means "always follow this
route" (i.e., unconditional).}
}
\if{html}{\out{</div>}}
}
\subsection{Returns}{
Invisibly returns `self` for method chaining.
}
}
\if{html}{\out{<hr>}}
\if{html}{\out{<a id="method-Workflow-set_entry"></a>}}
\if{latex}{\out{\hypertarget{method-Workflow-set_entry}{}}}
\subsection{Method \code{set_entry()}}{
Set the entry Station where execution begins.

If not called, \code{$run()} defaults to the first Station added.
\subsection{Usage}{
\if{html}{\out{<div class="r">}}\preformatted{Workflow$set_entry(station_name)}\if{html}{\out{</div>}}
}

\subsection{Arguments}{
\if{html}{\out{<div class="arguments">}}
\describe{
\item{\code{station_name}}{`[character(1)]` Name of the entry Station.}
}
\if{html}{\out{</div>}}
}
\subsection{Returns}{
Invisibly returns `self` for method chaining.
}
}
\if{html}{\out{<hr>}}
\if{html}{\out{<a id="method-Workflow-run"></a>}}
\if{latex}{\out{\hypertarget{method-Workflow-run}{}}}
\subsection{Method \code{run()}}{
Execute the workflow sequentially.

The `input` string is passed to the entry Station. Each Station's
output becomes the next Station's input. Execution stops when a Station
has no outgoing Route (or no Route whose condition evaluates to `TRUE`).

When \code{use_cache = TRUE}, a Station whose (name, input) pair has
been seen before returns the cached output without re-invoking the
handler. Use \code{$clear_cache()} to force re-execution.
\subsection{Usage}{
\if{html}{\out{<div class="r">}}\preformatted{Workflow$run(input)}\if{html}{\out{</div>}}
}

\subsection{Arguments}{
\if{html}{\out{<div class="arguments">}}
\describe{
\item{\code{input}}{`[character(1)]` The initial prompt / payload.}
}
\if{html}{\out{</div>}}
}
\subsection{Returns}{
`[character(1)]` The output of the last Station executed.
}
}
\if{html}{\out{<hr>}}
\if{html}{\out{<a id="method-Workflow-set_hitl"></a>}}
\if{latex}{\out{\hypertarget{method-Workflow-set_hitl}{}}}
\subsection{Method \code{set_hitl()}}{
Set Human-In-The-Loop (HITL) pause points.

When execution reaches a step whose number is listed in `steps`, it
pauses and presents the human with three choices:
\enumerate{
  \item Continue with the Station's original output.
  \item Edit the output manually before the next Station receives it.
  \item Stop the workflow immediately (raises an error).
}
HITL only fires on fresh Station executions - cache hits are skipped.
Steps are numbered from 1 in execution order, matching the step counter
shown in \code{$run()} output. You can set multiple steps at once:
\code{wf$set_hitl(c(1, 3))}.
\subsection{Usage}{
\if{html}{\out{<div class="r">}}\preformatted{Workflow$set_hitl(steps)}\if{html}{\out{</div>}}
}

\subsection{Arguments}{
\if{html}{\out{<div class="arguments">}}
\describe{
\item{\code{steps}}{`[integerish]` One or more step numbers (>= 1).}
}
\if{html}{\out{</div>}}
}
\subsection{Returns}{
Invisibly returns `self` for method chaining.
}
}
\if{html}{\out{<hr>}}
\if{html}{\out{<a id="method-Workflow-clear_cache"></a>}}
\if{latex}{\out{\hypertarget{method-Workflow-clear_cache}{}}}
\subsection{Method \code{clear_cache()}}{
Remove all cached Station results.
\subsection{Usage}{
\if{html}{\out{<div class="r">}}\preformatted{Workflow$clear_cache()}\if{html}{\out{</div>}}
}

\subsection{Returns}{
Invisibly returns `self`.
}
}
\if{html}{\out{<hr>}}
\if{html}{\out{<a id="method-Workflow-as_agent"></a>}}
\if{latex}{\out{\hypertarget{method-Workflow-as_agent}{}}}
\subsection{Method \code{as_agent()}}{
Wrap this Workflow as a `WorkflowAgent`.

The returned `WorkflowAgent` exposes \code{$invoke(prompt)} and holds an
`agent_id`, making it compatible with `LeadAgent$register_agents()` and
usable as a Station handler inside another `Workflow`.
\subsection{Usage}{
\if{html}{\out{<div class="r">}}\preformatted{Workflow$as_agent(name = NULL, instruction = NULL)}\if{html}{\out{</div>}}
}

\subsection{Arguments}{
\if{html}{\out{<div class="arguments">}}
\describe{
\item{\code{name}}{`[character(1)]` Name for the `WorkflowAgent`. Defaults to
\code{"\{workflow name\} (agent)"}.}

\item{\code{instruction}}{`[character(1)]` Instruction string describing the
agent's role. Used by `LeadAgent` for task-agent matching.}
}
\if{html}{\out{</div>}}
}
\subsection{Returns}{
A `WorkflowAgent` object.
}
}
\if{html}{\out{<hr>}}
\if{html}{\out{<a id="method-Workflow-visualize"></a>}}
\if{latex}{\out{\hypertarget{method-Workflow-visualize}{}}}
\subsection{Method \code{visualize()}}{
Render the workflow as a directed graph via DiagrammeR.

Stations are shown as rounded boxes. Conditional Routes are shown as
dashed arrows labelled "cond". The entry Station is marked with a filled
circle labelled "START".
\subsection{Usage}{
\if{html}{\out{<div class="r">}}\preformatted{Workflow$visualize()}\if{html}{\out{</div>}}
}

\subsection{Returns}{
A `DiagrammeR` / `htmlwidget` object.
}
}
}
