From 711673fcbdcb9f50727028a9af37c7ebb58446a0 Mon Sep 17 00:00:00 2001 From: Zeding Zhang Date: Thu, 5 Nov 2026 22:07:46 +0800 Subject: [PATCH 1/3] fix: defer declarative agent factory creation in workflows --- python/packages/declarative/README.md | 12 +++ .../_workflows/_factory.py | 10 ++- python/packages/declarative/tests/conftest.py | 7 ++ .../tests/test_workflow_factory.py | 78 ++++++++++++++++++- 4 files changed, 103 insertions(+), 4 deletions(-) diff --git a/python/packages/declarative/README.md b/python/packages/declarative/README.md index 0a4b28549d1..0965563b19a 100644 --- a/python/packages/declarative/README.md +++ b/python/packages/declarative/README.md @@ -22,6 +22,18 @@ This package ships at two different stability levels: **experimental** and may change or be removed in future versions without notice. Using any of these symbols emits an `ExperimentalWarning` on first use. +`WorkflowFactory` creates its default `AgentFactory` lazily when loading an +agent definition from the workflow's `agents` section, including references to +agent YAML files. That path uses the experimental declarative-agent APIs and +emits the corresponding warning. The `env_file` passed to `WorkflowFactory` is +loaded at that point. + +Workflows containing only workflow actions use the stable workflow APIs. To use +agents through that surface, create them with the appropriate client and pass +them through `WorkflowFactory(agents=...)` or `register_agent(...)`. Registered +agents take precedence over matching YAML definitions and bypass declarative +agent loading. + ## Declarative features The declarative packages provides support for building agents based on a declarative yaml specification. diff --git a/python/packages/declarative/agent_framework_declarative/_workflows/_factory.py b/python/packages/declarative/agent_framework_declarative/_workflows/_factory.py index a8329a59734..c81cdc20d7f 100644 --- a/python/packages/declarative/agent_framework_declarative/_workflows/_factory.py +++ b/python/packages/declarative/agent_framework_declarative/_workflows/_factory.py @@ -102,11 +102,13 @@ def __init__( """Initialize the workflow factory. Args: - agent_factory: Optional AgentFactory for creating agents from inline YAML definitions. + agent_factory: Optional AgentFactory for creating agents from inline or file-based YAML definitions. + The default factory is created on first use and emits an experimental warning. agents: Optional pre-created agents by name. These are looked up when processing InvokeAzureAgent actions in the workflow YAML. bindings: Optional function bindings for tool calls within workflow actions. env_file: Optional path to .env file for environment variables used in agent creation. + Loaded when the default agent factory is first needed. checkpoint_storage: Optional checkpoint storage enabling pause/resume functionality. max_iterations: Optional maximum runner supersteps. Overrides the YAML ``maxTurns`` field and the core default (100). Workflows with ``GotoAction`` loops (e.g. @@ -186,7 +188,8 @@ def __init__( }, ) """ - self._agent_factory = agent_factory or AgentFactory(env_file_path=env_file) + self._agent_factory = agent_factory + self._env_file = env_file self._agents: dict[str, SupportsAgentRun | AgentExecutor] = dict(agents) if agents else {} self._bindings: dict[str, Any] = dict(bindings) if bindings else {} self._tools: dict[str, Any] = {} # Tool registry for InvokeFunctionTool actions @@ -563,6 +566,9 @@ def _create_agent_from_def( Returns: An agent instance """ + if self._agent_factory is None: + self._agent_factory = AgentFactory(env_file_path=self._env_file) + # Check if it's a reference to an external file if "file" in agent_def: file_path = agent_def["file"] diff --git a/python/packages/declarative/tests/conftest.py b/python/packages/declarative/tests/conftest.py index 083de75660f..b7e36af64a7 100644 --- a/python/packages/declarative/tests/conftest.py +++ b/python/packages/declarative/tests/conftest.py @@ -5,12 +5,19 @@ import sys import pytest +from agent_framework import _feature_stage # Skip all tests in this directory on Python 3.14+ because powerfx doesn't support it yet if sys.version_info >= (3, 14): collect_ignore_glob = ["test_*.py"] +@pytest.fixture +def fresh_feature_warnings(monkeypatch: pytest.MonkeyPatch) -> None: + """Isolate once-per-feature warnings from other tests.""" + monkeypatch.setattr(_feature_stage, "_WARNED_FEATURES", set()) + + def pytest_collection_modifyitems(config: pytest.Config, items: list[pytest.Item]) -> None: """Skip all declarative tests on Python 3.14+ due to powerfx incompatibility.""" if sys.version_info >= (3, 14): diff --git a/python/packages/declarative/tests/test_workflow_factory.py b/python/packages/declarative/tests/test_workflow_factory.py index 46b3d11a9e1..784a2a27e59 100644 --- a/python/packages/declarative/tests/test_workflow_factory.py +++ b/python/packages/declarative/tests/test_workflow_factory.py @@ -2,25 +2,28 @@ """Unit tests for WorkflowFactory.""" +import os +import warnings from collections import UserDict from collections.abc import Iterator, ValuesView from copy import deepcopy from pathlib import Path from types import MappingProxyType from typing import Any, cast -from unittest.mock import patch +from unittest.mock import MagicMock, patch import pytest import yaml from agent_framework import Message +from agent_framework._feature_stage import ExperimentalWarning +from agent_framework_declarative import AgentFactory, WorkflowFactory from agent_framework_declarative._feature_usage import FeatureIndex from agent_framework_declarative._workflows._declarative_base import ( DeclarativeActionExecutor, discover_env_references, ) from agent_framework_declarative._workflows._errors import DeclarativeWorkflowError -from agent_framework_declarative._workflows._factory import WorkflowFactory try: import powerfx # noqa: F401 @@ -1332,6 +1335,77 @@ def test_trigger_workflow_without_id(self): class TestWorkflowFactoryAgentCreation: """Tests for agent creation from definitions.""" + @pytest.mark.usefixtures("fresh_feature_warnings") + @pytest.mark.parametrize("registration", ["none", "constructor", "register_agent"]) + async def test_workflow_without_agent_loading_emits_no_experimental_warning(self, registration: str) -> None: + agent = MagicMock() + with warnings.catch_warnings(): + warnings.simplefilter("error", ExperimentalWarning) + factory = WorkflowFactory(agents={"TestAgent": agent} if registration == "constructor" else None) + if registration == "register_agent": + factory.register_agent("TestAgent", agent) + definition: dict[str, Any] = { + "name": "hello-workflow", + "actions": [{"kind": "SendActivity", "activity": {"text": "Hello"}}], + } + if registration != "none": + definition["agents"] = {"TestAgent": {"kind": "Prompt", "name": "OverrideAttempt"}} + workflow = factory.create_workflow_from_yaml(yaml.safe_dump(definition)) + result = await workflow.run({}) + + assert any("Hello" in str(output) for output in result.get_outputs()) + if registration != "none": + assert cast(Any, workflow)._declarative_agents["TestAgent"] is agent + + @pytest.mark.usefixtures("fresh_feature_warnings") + @pytest.mark.parametrize("source", ["inline", "file"]) + def test_agent_loading_warns_and_reuses_factory( + self, source: str, tmp_path: Path, monkeypatch: pytest.MonkeyPatch + ) -> None: + monkeypatch.setenv("DECLARATIVE_TEST_ENV", "original") + monkeypatch.delenv("DECLARATIVE_TEST_ENV") + env_file = tmp_path / ".env" + env_file.write_text("DECLARATIVE_TEST_ENV=loaded\n") + agent_def: dict[str, Any] = {"kind": "Prompt", "name": "TestAgent", "instructions": "Be helpful."} + if source == "file": + (tmp_path / "agent.yaml").write_text(yaml.safe_dump(agent_def)) + agent_def = {"file": "agent.yaml"} + definition = { + "agents": {"TestAgent": agent_def}, + "actions": [{"kind": "SendActivity", "activity": "Hello"}], + } + + with warnings.catch_warnings(): + warnings.simplefilter("error", ExperimentalWarning) + factory = WorkflowFactory(env_file=str(env_file)) + + with patch.object(AgentFactory, "_get_client", return_value=MagicMock()): + with pytest.warns(ExperimentalWarning, match=r"\[DECLARATIVE_AGENTS\] AgentFactory"): + workflow = factory.create_workflow_from_definition(definition, base_path=tmp_path) + assert cast(Any, workflow)._declarative_agents["TestAgent"].name == "TestAgent" + assert os.environ["DECLARATIVE_TEST_ENV"] == "loaded" + + # Loading the env file again would restore the deleted value. + monkeypatch.delenv("DECLARATIVE_TEST_ENV") + with warnings.catch_warnings(): + warnings.simplefilter("error", ExperimentalWarning) + factory.create_workflow_from_definition(definition, base_path=tmp_path) + assert "DECLARATIVE_TEST_ENV" not in os.environ + + @pytest.mark.usefixtures("fresh_feature_warnings") + def test_explicit_agent_factory_emits_experimental_warning(self) -> None: + with pytest.warns(ExperimentalWarning, match=r"\[DECLARATIVE_AGENTS\] AgentFactory"): + agent_factory = AgentFactory(client=MagicMock()) + + with warnings.catch_warnings(): + warnings.simplefilter("error", ExperimentalWarning) + factory = WorkflowFactory(agent_factory=agent_factory) + workflow = factory.create_workflow_from_definition({ + "agents": {"TestAgent": {"kind": "Prompt", "name": "TestAgent"}}, + "actions": [{"kind": "SendActivity", "activity": "Hello"}], + }) + assert cast(Any, workflow)._declarative_agents["TestAgent"].client is agent_factory.client + def test_agent_creation_with_file_reference(self, tmp_path): """Test creating agent from file reference.""" from unittest.mock import MagicMock From 5254e801931c6c05c4cf85d76462f1ff7af8324d Mon Sep 17 00:00:00 2001 From: Zeding Zhang Date: Sat, 7 Nov 2026 00:06:55 +0800 Subject: [PATCH 2/3] fix: preserve workflow environment loading with lazy agent factory --- python/packages/declarative/README.md | 7 +++-- .../_workflows/_factory.py | 8 ++++-- .../tests/test_workflow_factory.py | 27 ++++++++++++++++--- 3 files changed, 34 insertions(+), 8 deletions(-) diff --git a/python/packages/declarative/README.md b/python/packages/declarative/README.md index 0965563b19a..525dcd3176e 100644 --- a/python/packages/declarative/README.md +++ b/python/packages/declarative/README.md @@ -25,8 +25,11 @@ This package ships at two different stability levels: `WorkflowFactory` creates its default `AgentFactory` lazily when loading an agent definition from the workflow's `agents` section, including references to agent YAML files. That path uses the experimental declarative-agent APIs and -emits the corresponding warning. The `env_file` passed to `WorkflowFactory` is -loaded at that point. +emits the corresponding warning. When no custom `agent_factory` is supplied, +`WorkflowFactory` loads `env_file` during initialization, independently of agent +creation. Workflow expressions such as `=Env.NAME` can read those variables when +`restrict_env_to_configuration=False`; explicit `configuration` values still +take precedence. Workflows containing only workflow actions use the stable workflow APIs. To use agents through that surface, create them with the appropriate client and pass diff --git a/python/packages/declarative/agent_framework_declarative/_workflows/_factory.py b/python/packages/declarative/agent_framework_declarative/_workflows/_factory.py index c81cdc20d7f..8e40b16b185 100644 --- a/python/packages/declarative/agent_framework_declarative/_workflows/_factory.py +++ b/python/packages/declarative/agent_framework_declarative/_workflows/_factory.py @@ -25,6 +25,7 @@ Workflow, ) from agent_framework._telemetry import mark_feature_used +from dotenv import load_dotenv from .._feature_usage import FeatureIndex from .._loader import AgentFactory @@ -107,8 +108,9 @@ def __init__( agents: Optional pre-created agents by name. These are looked up when processing InvokeAzureAgent actions in the workflow YAML. bindings: Optional function bindings for tool calls within workflow actions. - env_file: Optional path to .env file for environment variables used in agent creation. - Loaded when the default agent factory is first needed. + env_file: Optional path to .env file for environment variables used in agent creation + and workflow expressions. Loaded during initialization when no agent_factory is supplied. + Workflow expressions require restrict_env_to_configuration=False to read these variables. checkpoint_storage: Optional checkpoint storage enabling pause/resume functionality. max_iterations: Optional maximum runner supersteps. Overrides the YAML ``maxTurns`` field and the core default (100). Workflows with ``GotoAction`` loops (e.g. @@ -190,6 +192,8 @@ def __init__( """ self._agent_factory = agent_factory self._env_file = env_file + if agent_factory is None: + load_dotenv(dotenv_path=env_file, encoding=None) self._agents: dict[str, SupportsAgentRun | AgentExecutor] = dict(agents) if agents else {} self._bindings: dict[str, Any] = dict(bindings) if bindings else {} self._tools: dict[str, Any] = {} # Tool registry for InvokeFunctionTool actions diff --git a/python/packages/declarative/tests/test_workflow_factory.py b/python/packages/declarative/tests/test_workflow_factory.py index 784a2a27e59..3cb737fde6d 100644 --- a/python/packages/declarative/tests/test_workflow_factory.py +++ b/python/packages/declarative/tests/test_workflow_factory.py @@ -1337,23 +1337,41 @@ class TestWorkflowFactoryAgentCreation: @pytest.mark.usefixtures("fresh_feature_warnings") @pytest.mark.parametrize("registration", ["none", "constructor", "register_agent"]) - async def test_workflow_without_agent_loading_emits_no_experimental_warning(self, registration: str) -> None: + @pytest.mark.parametrize("use_env_file", [False, pytest.param(True, marks=_requires_powerfx)]) + async def test_workflow_without_agent_loading_emits_no_experimental_warning( + self, registration: str, use_env_file: bool, tmp_path: Path, monkeypatch: pytest.MonkeyPatch + ) -> None: + env_file = None + if use_env_file: + monkeypatch.setenv("DECLARATIVE_TEST_ENV", "original") + monkeypatch.delenv("DECLARATIVE_TEST_ENV") + env_file = tmp_path / ".env" + env_file.write_text("DECLARATIVE_TEST_ENV=loaded\n") agent = MagicMock() with warnings.catch_warnings(): warnings.simplefilter("error", ExperimentalWarning) - factory = WorkflowFactory(agents={"TestAgent": agent} if registration == "constructor" else None) + factory = WorkflowFactory( + agents={"TestAgent": agent} if registration == "constructor" else None, + env_file=str(env_file) if env_file else None, + restrict_env_to_configuration=False, + ) if registration == "register_agent": factory.register_agent("TestAgent", agent) definition: dict[str, Any] = { "name": "hello-workflow", - "actions": [{"kind": "SendActivity", "activity": {"text": "Hello"}}], + "actions": [ + { + "kind": "SendActivity", + "activity": {"text": "=Env.DECLARATIVE_TEST_ENV" if use_env_file else "Hello"}, + } + ], } if registration != "none": definition["agents"] = {"TestAgent": {"kind": "Prompt", "name": "OverrideAttempt"}} workflow = factory.create_workflow_from_yaml(yaml.safe_dump(definition)) result = await workflow.run({}) - assert any("Hello" in str(output) for output in result.get_outputs()) + assert result.get_outputs() == ["loaded" if use_env_file else "Hello"] if registration != "none": assert cast(Any, workflow)._declarative_agents["TestAgent"] is agent @@ -1378,6 +1396,7 @@ def test_agent_loading_warns_and_reuses_factory( with warnings.catch_warnings(): warnings.simplefilter("error", ExperimentalWarning) factory = WorkflowFactory(env_file=str(env_file)) + assert os.environ["DECLARATIVE_TEST_ENV"] == "loaded" with patch.object(AgentFactory, "_get_client", return_value=MagicMock()): with pytest.warns(ExperimentalWarning, match=r"\[DECLARATIVE_AGENTS\] AgentFactory"): From 9c0a35bc141df82bb4f2d3fde36c77ea82f8fd40 Mon Sep 17 00:00:00 2001 From: Zeding Zhang Date: Mon, 9 Nov 2026 16:29:09 +0800 Subject: [PATCH 3/3] ci: retry checks after transient GitHub link timeouts