diff --git a/python/packages/declarative/README.md b/python/packages/declarative/README.md index 0a4b28549d1..525dcd3176e 100644 --- a/python/packages/declarative/README.md +++ b/python/packages/declarative/README.md @@ -22,6 +22,21 @@ 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. 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 +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..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 @@ -102,11 +103,14 @@ 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. + 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. @@ -186,7 +190,10 @@ def __init__( }, ) """ - self._agent_factory = agent_factory or AgentFactory(env_file_path=env_file) + 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 @@ -563,6 +570,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..3cb737fde6d 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,96 @@ 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"]) + @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, + 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": "=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 result.get_outputs() == ["loaded" if use_env_file else "Hello"] + 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)) + 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"): + 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