.NET API
IWorkflowRunner
Tracon.Abstractions.dllReads the workflow catalog and runs workflows.
public interface IWorkflowRunnerRemarks
Section titled “Remarks”The abstraction lives in Tracon.Abstractions because the HTTP
layer runs workflows but does not depend on the
Tracon.Workflows package. This is the same pattern the MCP
package follows: the workflow engine stays an
optional package, and a consumer who does not use it does not pull in a
130-type execution engine.
Call this interface to run a workflow in process; the Tracon.Workflows package
supplies the implementation, so do not implement or replace it.
The contract carries no Microsoft Agent Framework type. Events flow
through Tracon’s own RunEvent type; the conversion from
MAF events happens inside Tracon.Workflows.
Delivery guarantee — AT-LEAST-ONCE, on IWorkflowRunner.ResumeStreamingAsync
specifically. Resuming from a run’s LATEST checkpoint after it has
already completed does not re-run anything — there is nothing left to do. But
resuming from an EARLIER checkpoint (the shape a real crash recovery takes)
replays every super-step from that point forward, including any
AddWorkflowFunction<T> handler node in them, with the SAME
input — this is exactly the reason a workflow function handler with a real
side effect must be idempotent (see AddWorkflowFunction<T>’s
own remarks, where this was originally documented). IWorkflowRunner.RunStreamingAsync
and IWorkflowRunner.RespondStreamingAsync carry no such guarantee of their own:
each opens a fresh run and does not replay prior work.
Methods
Section titled “Methods”GetAsync(string, CancellationToken)
Section titled “ GetAsync(string, CancellationToken)”Fetches a single workflow’s summary.
ValueTask<WorkflowDescriptor?> GetAsync(string name, CancellationToken cancellationToken = default)Parameters
Section titled “Parameters”name string
The workflow name.
cancellationToken CancellationToken
The cancellation token.
Returns
Section titled “Returns”ValueTask<WorkflowDescriptor?>
The summary; null if it does not exist.
GetGraphAsync(string, CancellationToken)
Section titled “ GetGraphAsync(string, CancellationToken)”Compiles a workflow and extracts its graph.
ValueTask<WorkflowGraph?> GetGraphAsync(string name, CancellationToken cancellationToken = default)Parameters
Section titled “Parameters”name string
The workflow name.
cancellationToken CancellationToken
The cancellation token.
Returns
Section titled “Returns”The graph; null if the workflow is not in the catalog.
Remarks
Section titled “Remarks”The graph is actually compiled: the helper nodes added by prebuilt patterns are visible only after compilation, and the executor identifiers in run events come from there too. Compilation makes no agent call, it only wires up the wrappers.
ListAsync(CancellationToken)
Section titled “ ListAsync(CancellationToken)”Lists the workflows in the catalog (defined in code + database).
ValueTask<IReadOnlyList<WorkflowDescriptor>> ListAsync(CancellationToken cancellationToken = default)Parameters
Section titled “Parameters”cancellationToken CancellationToken
The cancellation token.
Returns
Section titled “Returns”ValueTask<IReadOnlyList<WorkflowDescriptor>>
The summaries.
ListPendingRequestsAsync(Guid, CancellationToken)
Section titled “ ListPendingRequestsAsync(Guid, CancellationToken)”Lists a run’s pending human-input requests.
ValueTask<IReadOnlyList<WorkflowPendingRequest>> ListPendingRequestsAsync(Guid runId, CancellationToken cancellationToken = default)Parameters
Section titled “Parameters”runId Guid
The run identifier.
cancellationToken CancellationToken
The cancellation token.
Returns
Section titled “Returns”ValueTask<IReadOnlyList<WorkflowPendingRequest>>
The pending requests; an empty list if none.
Exceptions
Section titled “Exceptions”The run does not exist or belongs to another tenant.
ListRequestsAsync(WorkflowRequestQuery, CancellationToken)
Section titled “ ListRequestsAsync(WorkflowRequestQuery, CancellationToken)”Lists the human requests the caller’s tenant is waiting on, across runs.
ValueTask<IReadOnlyList<WorkflowPendingRequest>> ListRequestsAsync(WorkflowRequestQuery query, CancellationToken cancellationToken = default)Parameters
Section titled “Parameters”query WorkflowRequestQuery
Which requests, and which page.
cancellationToken CancellationToken
The cancellation token.
Returns
Section titled “Returns”ValueTask<IReadOnlyList<WorkflowPendingRequest>>
The requests, oldest first, one per logical request: the same request id in the same session is listed once, under the newest run that still waits on it.
Remarks
Section titled “Remarks”Each item carries what IWorkflowRunner.ListPendingRequestsAsync returns and the workflow name, the session, the expiry and whether the request was answered.
The default implementation returns an empty list. An implementation written before this member existed keeps compiling; it lists nothing here.
RespondStreamingAsync(WorkflowRespondRequest, CancellationToken)
Section titled “ RespondStreamingAsync(WorkflowRespondRequest, CancellationToken)”Responds to a pending request and resumes the run from its checkpoint.
IAsyncEnumerable<RunEvent> RespondStreamingAsync(WorkflowRespondRequest request, CancellationToken cancellationToken = default)Parameters
Section titled “Parameters”request WorkflowRespondRequest
The response.
cancellationToken CancellationToken
The cancellation token.
Returns
Section titled “Returns”The ordered event stream.
Remarks
Section titled “Remarks”Resuming opens a new run record; the same rule as IWorkflowRunner.ResumeStreamingAsync. The response is matched to the request republished from the checkpoint by identifier.
ResumeStreamingAsync(WorkflowResumeRequest, CancellationToken)
Section titled “ ResumeStreamingAsync(WorkflowResumeRequest, CancellationToken)”Resumes from a checkpoint and streams its events.
IAsyncEnumerable<RunEvent> ResumeStreamingAsync(WorkflowResumeRequest request, CancellationToken cancellationToken = default)Parameters
Section titled “Parameters”request WorkflowResumeRequest
The resume request.
cancellationToken CancellationToken
The cancellation token.
Returns
Section titled “Returns”The ordered event stream.
Remarks
Section titled “Remarks”Resuming opens a new run record. Reopening the same row would break the event stream’s append-only rule and would leave “when did this run end” unanswered.
RunStreamingAsync(WorkflowRunRequest, CancellationToken)
Section titled “ RunStreamingAsync(WorkflowRunRequest, CancellationToken)”Runs a workflow and streams its events.
IAsyncEnumerable<RunEvent> RunStreamingAsync(WorkflowRunRequest request, CancellationToken cancellationToken = default)Parameters
Section titled “Parameters”request WorkflowRunRequest
The run request.
cancellationToken CancellationToken
The cancellation token.
Returns
Section titled “Returns”The ordered event stream.
Remarks
Section titled “Remarks”The first event is always RunEventType.RunStarted, and its RunEvent.RunId field carries the run identifier; the caller learns the identifier from the stream’s first frame.
ValidateResponseAsync(WorkflowRespondRequest, CancellationToken)
Section titled “ ValidateResponseAsync(WorkflowRespondRequest, CancellationToken)”Checks a response against the pending request it answers, without starting a run.
ValueTask<string?> ValidateResponseAsync(WorkflowRespondRequest request, CancellationToken cancellationToken = default)Parameters
Section titled “Parameters”request WorkflowRespondRequest
The response to check.
cancellationToken CancellationToken
The cancellation token.
Returns
Section titled “Returns”A sentence that names the missing or unreadable field when the response cannot be translated to the type the request’s port expects; otherwise null. It is also null when the check cannot be made before a run starts: the run or the request is not found, or the run is not waiting for input. IWorkflowRunner.RespondStreamingAsync reports those.
Remarks
Section titled “Remarks”The HTTP layer calls this before the event stream opens, so a response of the wrong
shape is refused with 400 and no run row is opened.
IWorkflowRunner.RespondStreamingAsync applies the same rule when the request is
republished and fails the run it opened: a caller that skips this check is refused
too, but only after a run has started.
The default implementation returns null. An implementation written before this member keeps compiling and keeps reporting a wrong response on the stream.