docs: add Declarative Workflow YAML schema reference

[LEDazzio01]

Motivation and Context

Addresses #4188 — the request to document the Declarative Workflow YAML schema.

Currently, the YAML schema for declarative workflows is only documented implicitly through the sample YAML files and the action table in the Microsoft.Agents.AI.Workflows.Declarative package README. There is no standalone, comprehensive schema reference that users can consult when authoring workflows.

Description

Adds docs/declarative-workflow-yaml-schema.md — a comprehensive reference document covering:

• Top-Level Structure — kind: Workflow, trigger
• Triggers — OnConversationStart with property tables
• Actions Reference — All 23 action types organized by category:
  • ⚙️ Foundry Actions (7): InvokeAzureAgent, CreateConversation, DeleteConversation, AddConversationMessage, CopyConversationMessages, RetrieveConversationMessage, RetrieveConversationMessages
  • 🧑‍💼 Human Input (1): Question
  • 🧩 State Management (8): SetVariable, SetTextVariable, SetMultipleVariables, ResetVariable, ClearAllVariables, ParseValue, EditTableV2, SendActivity
  • 🧭 Control Flow (7): ConditionGroup/ConditionItem, Foreach, GotoAction, EndWorkflow, EndConversation, BreakLoop, ContinueLoop
• Expressions — PowerFx syntax with = prefix, string interpolation, and common function reference
• Variables — Local.* and System.* scoping
• Input/Output Configuration — messages, arguments, externalLoop, responseObject, autoSend
• Complete Examples — Minimal, looping, and links to existing workflow samples

The documentation was derived from analyzing:

• All workflow samples in workflow-samples/
• The action catalog in dotnet/src/Microsoft.Agents.AI.Workflows.Declarative/README.md
• The source code structure in Microsoft.Agents.AI.Workflows.Declarative

Contribution Checklist

• The code builds clean without any errors or warnings
• The PR follows the Contribution Guidelines
• All unit tests pass, and I have added new tests where possible
• Is this a breaking change? No — documentation only.

[LEDazzio01]

I have sole ownership of intellectual property rights to my Submissions and I am not making Submissions in the course of work for my employer.

[Copilot]

Pull request overview

This PR adds comprehensive schema reference documentation for Declarative Workflows in response to issue #4188. The document provides a complete guide for authoring declarative workflow YAML files in the Microsoft Agent Framework.

Changes:

• Added docs/declarative-workflow-yaml-schema.md with detailed schema reference covering all workflow elements
• Documented 23 action types organized by category (Foundry Actions, Human Input, State Management, Control Flow)
• Included PowerFx expression syntax, variable scoping, input/output configuration, and complete examples

[Copilot]

The externalLoop configuration is missing documentation for the maxIterations property. According to the Python implementation (python/packages/declarative/agent_framework_declarative/_workflows/_executors_agents.py:463-471), the externalLoop supports an optional maxIterations property with a default value of 100 to prevent infinite loops. The documentation should include a property table showing both when (required) and maxIterations (optional, default: 100) properties to provide complete reference information.

Suggested change

	**Properties**
	| Property | Type | Required | Default | Description |
	| -------------- | --------- | -------- | ------- | --------------------------------------------------------------------------- |
	| `when` | Expression| Yes | N/A | Condition to continue invoking the agent. Loop stops when this becomes false. |
	| `maxIterations`| Integer | No | `100` | Maximum number of times to invoke the agent to prevent infinite or runaway loops. |

[moonbox3]

Thanks for your help with this. This should really be a part of our Learn Site docs and not specifically in this docs dir as the discoverability isn't as good.

https://learn.microsoft.com/en-us/agent-framework/workflows/declarative?pivots=programming-language-python

We will handle this update internally.

[LEDazzio01]

Thanks for the feedback, @moonbox3! That makes total sense — the Learn site is definitely the right home for this kind of reference documentation where users will actually discover it.

Feel free to reference any of the content from this PR when updating the Learn docs. Happy to help if there's anything else I can contribute!

Closing this in favor of the internal Learn site update. 🙂