.NET: [Bug]: outdated and not relevant declarative workflow documentation

[dsslight]

Description

The Declarative workflow documentation does not reflect the current behavior, which is misleading and confusing for developers.
For example:

1. compare the documented Question and SendActivity descriptions with the usage samples in the repository.
2. SendMessage is not documented at all.
3. InvokeFunctionTool mentioned as supposed to provide result to Local.* env variable, but if you use it - declarative.dll throws error that variable not defined/found. Answer here - Topic.* variable needs to be used and value available over Local.* namespace.

related references with more up to date info found

https://github.com/microsoft/agent-framework/blob/main/dotnet/samples/03-workflows/Declarative/ConfirmInput/ConfirmInput.yaml
documentation defined contract for Question action simply doesn't work and contains bunch of errors. Refer dev samples

additional samples
https://github.com/microsoft/agent-framework/blob/main/dotnet/samples/03-workflows/Declarative/FileInput/FileInput.yaml
https://github.com/microsoft/agent-framework/blob/main/dotnet/samples/03-workflows/Declarative/InvokeFunctionTool/InvokeFunctionTool.yaml
https://github.com/microsoft/agent-framework/blob/main/dotnet/samples/03-workflows/Declarative/AotCheckpointing/AotCheckpointing.yaml

Code Sample

Error Messages / Stack Traces

Package Versions

Microsoft.Agents.AI.Workflows.Declarative

.NET Version

.NET 10.0.300

Additional Context

documentation related issue

[baywet]

Hi dsslight
Thank you for using the SDK and for reaching out.

I've started a few pull requests to address your feedback, you won't be able to access those for now, but I'll keep you posted here

• https://github.com/MicrosoftDocs/azure-ai-docs-pr/pull/14233 (updates the question YAML examples)
• https://github.com/MicrosoftDocs/azure-ai-docs-pr/pull/14236 (updates a lot of invalid YAML syntax in the same page snippets)
• https://github.com/MicrosoftDocs/azure-ai-docs-pr/pull/14237 (adds snippet for send message)

For the invoke function tool, I'm not sure I'm following what the issue is? would you mind explaining things in more details please?

Let me know if you have any additional comments or questions.

[dsslight]

hi, documentation clearly says that output from InvokeFunctionTool goes to Local.* env variable. If I will do like that - declarative.dll fails with exception, something like "variable not defined". I can define variable with SetVariable or SetMultipleVariables - it doesn't help. I assume declarative.dll simply doesn't see this namespace for output for InvokeFunctionTool.

But, If I will use Topic.* as output - it works perfectly.
Then, how to read this output in next action?

If I will use Topic.* - it fails, saying "variable not defined". So I tried to use Local.* and surprisingly it worked.
So I assume you guys have some problems with mixing namespaces. This behavior quite not obvious and absolutely undocumented.

It just few hours of experiments, copilot and guessing allowed to find how to make it workable.

BTW:

• Topic.* namespace not defined at all in original manual. Only System.* and Local.*
• InvokeFunctionTool .NET: [Bug]: not working declarative workflow InvokeFunctionTool as expected #7978 you guys do not fully support under StreamingRun, so I did my own implementation on catching event, execution and publishing event on completion.

[baywet]

Thank you for the additional information.

As an update, all the pull requests I was mentioning in my previous reply got merged and published.

Can you confirm which version of the package you're using ? This aspect seems to have already been patched by #5905 and made available in version 1.6.2 and above. And a quick unit test added in https://github.com/microsoft/agent-framework/pull/new/tests/variables-workflow-declarative-dotnet does not seem to reproduce the issue.

[dsslight]

as I see Microsoft.Agents.AI.Workflows.Declarative=1.19.0, so looks like fresh
from the updated learn page:

dotnet add package Microsoft.Agents.AI.Workflows.Declarative --prerelease

are there milestones available for release version?

[baywet]

Microsoft.Agents.AI.Workflows.Declarative is stable (no pre-release switch required) for both 1.19.0 and 1.20.0.

I think all the questions / issues have been addressed on this thread, so I'm going to go ahead and close it.

Let us know if you have any additional comments or questions.

[dsslight]

Vincent Biret (@baywet) so what conclusion was about Topic.* and Local.* after my messages?
I reproduced this issue on newer version then patch #5905 target.
Non reproducing issue by tests might be a signal that not all use cases covered