Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 15 additions & 0 deletions python/packages/declarative/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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"]
Expand Down
7 changes: 7 additions & 0 deletions python/packages/declarative/tests/conftest.py
Original file line number Diff line number Diff line change
Expand Up @@ -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):
Expand Down
97 changes: 95 additions & 2 deletions python/packages/declarative/tests/test_workflow_factory.py
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down
Loading