[ZedingZhang (ZedingZhang)]

Motivation & Context

Constructing WorkflowFactory() eagerly creates an experimental AgentFactory, so even a workflow containing only SendActivity emits a DECLARATIVE_AGENTS warning. Applications using the stable workflow APIs should enter the declarative-agent loading path only when their workflow requires it.

Description & Review Guide

• What are the major changes? Lazily initialize and cache the default agent factory when processing an agent definition. Document the warning boundary and the pre-registered agent option. Add nine regression cases covering ordinary workflows with and without an environment file, both registration methods, inline/file-based agent definitions, factory reuse, and an explicitly supplied agent factory.
• What is the impact of these changes? Action-only workflows and workflows using pre-registered agents can be constructed and run with experimental warnings treated as errors. YAML agent loading emits the experimental warning on first use. When no custom agent factory is supplied, WorkflowFactory loads env_file during initialization independently of agent creation, preserving =Env.NAME values for workflows that enable process-environment fallback with restrict_env_to_configuration=False. Subsequent agent definitions reuse the default agent factory.
• What do you want reviewers to focus on? The lazy initialization boundary, registered-agent precedence, preserved environment-file loading, and the isolated once-per-feature warning state in the regression tests.

Related Issue

Fixes #10092.

The issue has the ready-for-implementation label. No competing open PR referencing #10092 was found before submission.

AI Assistance

• No material AI assistance was used.
• This is an AI-assisted contribution.

Codex assisted with issue analysis, implementation, regression tests, documentation, and this PR description. I have reviewed all submitted content and take resonsibility for it.

Contribution Checklist

• The code builds clean without any errors or warnings
• All unit tests pass, and I have added new tests where possible
  • Declarative package on Python 3.13 with the Power Fx runtime available — 1677 passed, 4 skipped, 94% coverage. The suite reports eight existing MCP deprecation warnings.
  • Ruff lint/format, strict source Pyright, and all five configured type checkers for the changed test files passed.
  • The new regression cases reproduced five failures before the implementation change.
• The PR follows the Contribution Guidelines
• This PR links to an agreed issue with no competing open PR, or the Related Issue section documents a trivial-change or repository-automation exception.
• This is not a breaking change. If it is a breaking change, add the breaking change label (or add "[BREAKING]" to the title prefix, before or after any language prefix) — a workflow keeps the label and title prefix in sync automatically.

[Copilot]

🟢 Approval recommended

There are no active review issues requiring changes.

No open issues 🎉

What changed in this PR

This PR addresses #10092 by deferring experimental agent-factory creation until a workflow loads an agent definition. Action-only workflows and workflows using pre-registered agents can therefore avoid the experimental warning.

Changes:

• Lazily create and cache the default AgentFactory, deferring environment-file loading until first use.
• Document the warning boundary and how pre-registered agents bypass declarative-agent loading.
• Add six regression cases covering warning behavior, registration precedence, factory reuse, and explicit factories.

File	Description
python/​packages/​declarative/​tests/​test_workflow_factory.py	Adds regression coverage for lazy initialization and warning behavior.
python/​packages/​declarative/​tests/​conftest.py	Adds a fixture isolating once-per-feature warning state.
python/​packages/​declarative/​README.md	Explains deferred loading and the pre-registered-agent option.
python/​packages/​declarative/​agent_framework_declarative/​_workflows/​_factory.py	Defers default factory creation and documents initialization timing.

_{Review effort: Balanced}

[Eduard van Valkenburg (eavanvalkenburg)]

ZedingZhang (@ZedingZhang), I found one material issue on the current head:

• python/packages/declarative/agent_framework_declarative/_workflows/_factory.py:191: deferring AgentFactory creation also prevents env_file loading for action-only workflows and workflows that use registered agents. Expressions such as =Env.NAME silently lose values that previously loaded. Please load the environment file independently of experimental agent creation and add an action-only environment regression.

[ZedingZhang (ZedingZhang)]

Thanks, Eduard van Valkenburg (@eavanvalkenburg) ! Fixed in 5254e80: environment loading now happens independently of lazy AgentFactory creation. Added regression coverage for action-only workflows and both agent registration paths. All declarative tests pass.