Heuristic:Microsoft Agent framework PowerFx Python Version Limit
| Knowledge Sources | |
|---|---|
| Domains | AI_Agents, Declarative_Workflows |
| Last Updated | 2026-02-11 16:45 GMT |
Overview
PowerFx expression evaluation is unavailable on Python 3.14+, causing declarative workflow expressions starting with `=` to be treated as literal strings instead of being evaluated.
Description
The declarative workflow engine uses PowerFx as its expression language for evaluating dynamic values in YAML workflow definitions. Expressions prefixed with `=` (e.g., `=Env.API_KEY`, `=Add(1, 2)`) are evaluated by the PowerFx engine at runtime. However, the `powerfx` Python package is not available for Python 3.14+. When running on Python 3.14+, the framework falls back to treating these expressions as literal strings, which silently breaks dynamic workflow behavior.
Usage
Apply this heuristic when choosing a Python version for declarative workflow deployments. If your workflows use PowerFx expressions (`=` prefix in YAML values), you must use Python 3.13 or lower. If you need Python 3.14+, replace all PowerFx expressions with static strings or environment variable references.
The Insight (Rule of Thumb)
- Action: Use Python <= 3.13 for declarative workflows with PowerFx expressions.
- Value: On Python 3.14+, replace all `=Expression` values in YAML with literal strings.
- Trade-off: Staying on 3.13 limits access to newer Python features. Moving to 3.14 requires removing dynamic expressions.
Reasoning
Dependency constraint from `python/packages/declarative/pyproject.toml:26`:
"powerfx>=0.0.31; python_version < '3.14'"
Runtime fallback warning from `python/packages/declarative/agent_framework_declarative/_models.py:51-54`:
logger.warning(
"PowerFx engine not available for evaluating values starting with '='. "
"Ensure you are on python 3.13 or less and have the powerfx package installed. "
"Otherwise replace all powerfx statements in your yaml with strings."
)
Test skipping from `python/packages/declarative/tests/test_declarative_loader.py`:
pytestmark = pytest.mark.skipif(
sys.version_info >= (3, 14),
reason="Skipping on Python 3.14+"
)