DeclarativeWorkflowAgentFactoryExtensions
NexusLabs.Foundry.MicrosoftAgentFramework.Workflows.Declarative¶
DeclarativeWorkflowAgentFactoryExtensions Class¶
Builds executable workflows from declarative YAML documents, resolving the agents they name against Foundry's declared agents.
Inheritance System.Object 🡒 DeclarativeWorkflowAgentFactoryExtensions
Remarks¶
The result is an ordinary Microsoft.Agents.AI.Workflows.Workflow, identical in kind to one produced by
IWorkflowFactory from attribute-declared topology, and it runs through the same execution,
checkpointing, and event surfaces. Only the declaration source differs: a YAML document instead
of attributes.
These are extension methods on NexusLabs.Foundry.MicrosoftAgentFramework.IAgentFactory rather than members of
IWorkflowFactory because agent resolution is the only thing declarative composition needs
from Foundry, and because IWorkflowFactory lives in the core package, which cannot take a
dependency on this one without pulling an interpreted expression engine into every consumer and
breaking the NativeAOT profile.
Workflow input is converted to a user message before the document sees it, matching how a
declarative document reads input through System.LastMessage rather than a typed input
namespace.
Methods¶
DeclarativeWorkflowAgentFactoryExtensions.CreateDeclarativeWorkflow(this IAgentFactory, string) Method¶
Builds a workflow from a declarative YAML document.
public static Microsoft.Agents.AI.Workflows.Workflow CreateDeclarativeWorkflow(this NexusLabs.Foundry.MicrosoftAgentFramework.IAgentFactory agentFactory, string workflowYaml);
Parameters¶
agentFactory NexusLabs.Foundry.MicrosoftAgentFramework.IAgentFactory
Resolves the agents the document names by their published name.
workflowYaml System.String
The complete document text.
Returns¶
Microsoft.Agents.AI.Workflows.Workflow
An executable workflow accepting a string input.
Exceptions¶
System.ArgumentNullException
agentFactory is null.
System.ArgumentException
workflowYaml is empty or whitespace-only.
DeclarativeWorkflowParseException
The document could not be parsed.
Remarks¶
A document that invokes an MCP tool or an HTTP endpoint fails at that action, because no handler is wired. Use the overload taking DeclarativeWorkflowHandlers to wire them.
DeclarativeWorkflowAgentFactoryExtensions.CreateDeclarativeWorkflow(this IAgentFactory, string, DeclarativeWorkflowHandlers) Method¶
Builds a workflow from a declarative YAML document, wiring the handlers it may call out through.
public static Microsoft.Agents.AI.Workflows.Workflow CreateDeclarativeWorkflow(this NexusLabs.Foundry.MicrosoftAgentFramework.IAgentFactory agentFactory, string workflowYaml, NexusLabs.Foundry.MicrosoftAgentFramework.Workflows.Declarative.DeclarativeWorkflowHandlers handlers);
Parameters¶
agentFactory NexusLabs.Foundry.MicrosoftAgentFramework.IAgentFactory
Resolves the agents the document names by their published name.
workflowYaml System.String
The complete document text.
handlers DeclarativeWorkflowHandlers
The MCP and HTTP handlers the document may invoke.
Returns¶
Microsoft.Agents.AI.Workflows.Workflow
An executable workflow accepting a string input.
Exceptions¶
System.ArgumentNullException
agentFactory or handlers is null.
System.ArgumentException
workflowYaml is empty or whitespace-only.
DeclarativeWorkflowParseException
The document could not be parsed.
DeclarativeWorkflowAgentFactoryExtensions.CreateDeclarativeWorkflow(this IAgentFactory, TextReader) Method¶
Builds a workflow from a declarative YAML document.
public static Microsoft.Agents.AI.Workflows.Workflow CreateDeclarativeWorkflow(this NexusLabs.Foundry.MicrosoftAgentFramework.IAgentFactory agentFactory, System.IO.TextReader workflowYaml);
Parameters¶
agentFactory NexusLabs.Foundry.MicrosoftAgentFramework.IAgentFactory
Resolves the agents the document names by their published name.
workflowYaml System.IO.TextReader
A reader positioned at the start of the document.
Returns¶
Microsoft.Agents.AI.Workflows.Workflow
An executable workflow accepting a string input.
Exceptions¶
System.ArgumentNullException
Either argument is null.
DeclarativeWorkflowParseException
The document could not be parsed.
Remarks¶
A document that invokes an MCP tool or an HTTP endpoint fails at that action, because no handler is wired. Use the overload taking DeclarativeWorkflowHandlers to wire them.
DeclarativeWorkflowAgentFactoryExtensions.CreateDeclarativeWorkflow(this IAgentFactory, TextReader, DeclarativeWorkflowHandlers) Method¶
Builds a workflow from a declarative YAML document, wiring the handlers it may call out through.
public static Microsoft.Agents.AI.Workflows.Workflow CreateDeclarativeWorkflow(this NexusLabs.Foundry.MicrosoftAgentFramework.IAgentFactory agentFactory, System.IO.TextReader workflowYaml, NexusLabs.Foundry.MicrosoftAgentFramework.Workflows.Declarative.DeclarativeWorkflowHandlers handlers);
Parameters¶
agentFactory NexusLabs.Foundry.MicrosoftAgentFramework.IAgentFactory
Resolves the agents the document names by their published name.
workflowYaml System.IO.TextReader
A reader positioned at the start of the document.
handlers DeclarativeWorkflowHandlers
The MCP and HTTP handlers the document may invoke.
Returns¶
Microsoft.Agents.AI.Workflows.Workflow
An executable workflow accepting a string input.
Exceptions¶
System.ArgumentNullException
Any argument is null.
DeclarativeWorkflowParseException
The document could not be parsed.
DeclarativeWorkflowAgentFactoryExtensions.ValidateDeclarativeWorkflow(this IAgentFactory, string) Method¶
Parses a declarative YAML document and reports whether it is well-formed, without executing it.
public static NexusLabs.Foundry.MicrosoftAgentFramework.Workflows.Declarative.DeclarativeWorkflowValidationResult ValidateDeclarativeWorkflow(this NexusLabs.Foundry.MicrosoftAgentFramework.IAgentFactory agentFactory, string workflowYaml);
Parameters¶
agentFactory NexusLabs.Foundry.MicrosoftAgentFramework.IAgentFactory
Resolves the agents the document names by their published name.
workflowYaml System.String
The complete document text.
Returns¶
DeclarativeWorkflowValidationResult
The validation outcome, including parse failure detail when invalid.
Exceptions¶
System.ArgumentNullException
agentFactory is null.
System.ArgumentException
workflowYaml is empty or whitespace-only.
Remarks¶
Declarative workflows have no published JSON Schema, so parsing is the only validation available. This method exists so a host can perform it deliberately — at startup, in a test, or in a lint step — rather than discovering an authoring error partway through a run.
It reports what upstream's builder rejects, which is structural malformation — including an
InvokeMcpTool action missing a required property, and one present in a document built
without an McpToolHandler. Both are rejected at
build rather than at invocation. It does not catch every authoring mistake: upstream
accepts an action kind it does not recognize, and it cannot detect an expression that
will fail to evaluate or an agent name that is not declared, because neither is knowable
until the action runs.