# WorkflowDefinition

> Tracon documentation. Tracon is a .NET package family that adds a control
> plane on Microsoft Agent Framework, published as NuGet packages that run
> inside your own ASP.NET Core application.
>
> Page: https://tracon.dev/http-api/schemas/workflowdefinition/
> Summary: OpenAPI request or response schema for WorkflowDefinition, including required fields, defaults, constraints, and linked nested types.

[← All HTTP schemas](/http-api/schemas/)

Represents the full definition of a workflow, whether defined through the
UI or in code.

**Shape:** `object`

| Property | Required | Type | Description | Rules |
|---|---|---|---|---|
| `name` | yes | `string` | Gets the workflow's unique name. Serves as the key in the catalog and in API routes. | — |
| `displayName` | no | `string` | Gets the display name shown in the UI. `Name` is used if left empty. | — |
| `description` | no | `string` | Gets the short description of what the workflow does. | — |
| `kind` | yes | [`WorkflowKind`](/http-api/schemas/workflowkind/) | Gets the built-in pattern to use. | — |
| `agentNames` | no | array of `string` | Gets the agent names to enter the graph. Order is meaningful for WorkflowKind.Sequential; for other kinds it defines the participant set. | — |
| `managerAgentName` | no | `string` | Gets the manager agent's name. Required for WorkflowKind.Magentic, unused in other patterns. | — |
| `nodes` | no | array of [`WorkflowNodeReference`](/http-api/schemas/workflownodereference/) | Gets the ordered node list for a WorkflowKind.Sequential workflow that mixes agent and function nodes. | — |
| `maxIterations` | no | `integer (int32)` | Gets the maximum number of turns. The only guard against an infinite loop in the WorkflowKind.GroupChat, WorkflowKind.Handoff, and WorkflowKind.Magentic patterns. | pattern `^-?(?:0\\|[1-9]\d*)$` |
| `handoffInstructions` | no | `string` | Gets the extra instruction that tells the model how to decide on a handoff. Used only for WorkflowKind.Handoff. | — |
| `requirePlanApproval` | no | `boolean` | Gets whether the plan the manager agent builds must be approved by a human before execution starts. Applies only to WorkflowKind.Magentic. | — |
| `parameters` | no | array of [`AgentParameter`](/http-api/schemas/agentparameter/) | Gets the run parameters the workflow accepts. Empty for a workflow that takes none. | — |
| `runTimeout` | no | `string` | Gets the longest time one run of this workflow may take. `null` (the default) uses the installation's `Tracon:Workflows:RunTimeout`. | pattern `^-?(\d+\.)?\d{2}:\d{2}:\d{2}(\.\d{1,7})?$` |
| `responseMode` | no | [`WorkflowResponseMode`](/http-api/schemas/workflowresponsemode/) | Gets how the workflow treats more than one answer to the same pending human request. WorkflowResponseMode.Branch (the default) opens a new run for every answer; WorkflowResponseMode.SingleAnswer allows one answer per request. | — |
| `requestTimeout` | no | `string` | Gets how long a human request of this workflow may wait for an answer before the run that waits on it is closed. `null` (the default) means it waits without limit. | pattern `^-?(\d+\.)?\d{2}:\d{2}:\d{2}(\.\d{1,7})?$` |
| `tenantId` | no | `string` | Gets the tenant the definition belongs to. `null` for workflows defined in code. | — |
| `version` | no | `integer (int32)` | Gets the definition version. Increments by one on every save and is never reused: the store keeps every version (see IWorkflowDefinitionStore). | pattern `^-?(?:0\\|[1-9]\d*)$` |
| `updatedAt` | no | `string (date-time)` | Gets the last modification time (UTC). | — |