agent-framework-declarative 1.3.0__tar.gz → 1.4.1__tar.gz

{agent_framework_declarative-1.3.0 → agent_framework_declarative-1.4.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: agent-framework-declarative
-Version: 1.3.0
+Version: 1.4.1
 Summary: Declarative specification support for Microsoft Agent Framework.
 Author-email: Microsoft <af-support@microsoft.com>
 Requires-Python: >=3.10
@@ -9,14 +9,14 @@ Classifier: License :: OSI Approved :: MIT License
 Classifier: Development Status :: 5 - Production/Stable
 Classifier: Intended Audience :: Developers
 Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Typing :: Typed
 License-File: LICENSE
-Requires-Dist: agent-framework-core>=1.20.0,<2
+Requires-Dist: agent-framework-core>=1.23.0,<2
 Requires-Dist: httpx>=0.27,<0.29
+Requires-Dist: httpx2>=2.0.0,<3
 Requires-Dist: powerfx>=0.0.32,<0.0.35; python_version < '3.14'
 Requires-Dist: pyyaml>=6.0,<7.0
 Project-URL: homepage, https://aka.ms/agent-framework
@@ -33,7 +33,8 @@ Please install this package via pip:
 pip install agent-framework-declarative
 ```
 
-The package currently advertises Python 3.10–3.13 support. Python 3.14 and
+The package currently advertises Python 3.11–3.13 support. Python 3.10
+installation remains permitted, but compatibility is not guaranteed. Python 3.14 and
 3.15 can install the package, but Power Fx expressions are unavailable because
 the `powerfx` dependency requires a `pythonnet` build that does not support
 those Python versions.

{agent_framework_declarative-1.3.0 → agent_framework_declarative-1.4.1}/README.md

@@ -6,7 +6,8 @@ Please install this package via pip:
 pip install agent-framework-declarative
 ```
 
-The package currently advertises Python 3.10–3.13 support. Python 3.14 and
+The package currently advertises Python 3.11–3.13 support. Python 3.10
+installation remains permitted, but compatibility is not guaranteed. Python 3.14 and
 3.15 can install the package, but Power Fx expressions are unavailable because
 the `powerfx` dependency requires a `pythonnet` build that does not support
 those Python versions.

{agent_framework_declarative-1.3.0 → agent_framework_declarative-1.4.1}/agent_framework_declarative/_workflows/_declarative_base.py

@@ -46,6 +46,10 @@ from agent_framework import (
 from agent_framework._workflows._state import State
 
 from ._errors import DeclarativeWorkflowError
+from ._powerfx_functions import (
+    _iter_powerfx_expression_indices,  # pyright: ignore[reportPrivateUsage]
+    whole_call_args,
+)
 from ._powerfx_limits import _PowerFxStateBudget, _validate_powerfx_state  # pyright: ignore[reportPrivateUsage]
 from ._state_path import _is_safe_path_segment  # pyright: ignore[reportPrivateUsage]
 
@@ -68,73 +72,6 @@ logger = logging.getLogger(__name__)
 _ENV_REFERENCE_RE = re.compile(r"\bEnv\.([A-Za-z_][A-Za-z0-9_]*)")
 
 
-def _skip_powerfx_opaque_token(formula: str, start: int) -> int:
-    """Return the end of an ordinary quoted token or comment, or start if neither."""
-    quote = formula[start]
-    if quote in ('"', "'"):
-        pos = start + 1
-        while pos < len(formula):
-            if formula[pos] == quote:
-                if pos + 1 < len(formula) and formula[pos + 1] == quote:
-                    pos += 2
-                    continue
-                return pos + 1
-            pos += 1
-        return pos
-    if formula.startswith("//", start):
-        pos = start + 2
-        while pos < len(formula) and formula[pos] not in "\r\n":
-            pos += 1
-        return pos
-    if formula.startswith("/*", start):
-        end = formula.find("*/", start + 2)
-        return len(formula) if end == -1 else end + 2
-    return start
-
-
-def _iter_powerfx_expression_indices(formula: str) -> Iterator[int]:
-    """Yield code positions, excluding literals/comments but including interpolation expressions."""
-    # None denotes interpolated text; integers track record braces in expression sections.
-    scopes: list[int | None] = [0]
-    cursor = 0
-    while cursor < len(formula):
-        depth = scopes[-1]
-        char = formula[cursor]
-        if depth is None:
-            if formula.startswith(('""', "{{", "}}"), cursor):
-                cursor += 2
-                continue
-            if char == "{":
-                scopes.append(0)
-            elif char == '"':
-                scopes.pop()
-            cursor += 1
-            continue
-
-        if formula.startswith('$"', cursor):
-            scopes.append(None)
-            cursor += 2
-            continue
-
-        token_end = _skip_powerfx_opaque_token(formula, cursor)
-        if token_end != cursor:
-            cursor = token_end
-            continue
-
-        if char == "{":
-            scopes[-1] = depth + 1
-        elif char == "}":
-            if depth > 0:
-                scopes[-1] = depth - 1
-            elif len(scopes) > 1:
-                scopes.pop()
-                cursor += 1
-                continue
-
-        yield cursor
-        cursor += 1
-
-
 @dataclass(frozen=True)
 class DeclarativeEnvConfig:
     """Configuration that populates the PowerFx ``Env`` symbol for a workflow.
@@ -721,14 +658,14 @@ class DeclarativeWorkflowState:
 
         Returns None if the formula is not a custom function call.
         """
-        import re
+        formula = formula.strip()
 
         # Concat/Concatenate - string concatenation
         # In standard PowerFx, Concatenate is for strings, Concat is for tables.
         # Copilot Studio uses Concat for strings, so we support both.
-        match = re.match(r"(?:Concat|Concatenate)\((.+)\)$", formula.strip())
-        if match:
-            args_str = match.group(1)
+        args_str = whole_call_args(formula, "Concat", "Concatenate")
+        # Empty arguments fall through so PowerFx reports the arity error.
+        if args_str:
             # Parse comma-separated arguments (handling nested parentheses)
             args = self._parse_function_args(args_str)
             evaluated_args: list[str] = []
@@ -747,24 +684,24 @@ class DeclarativeWorkflowState:
             return "".join(evaluated_args)
 
         # UserMessage(expr) - creates a user message dict
-        match = re.match(r"UserMessage\((.+)\)$", formula.strip())
-        if match:
-            inner_expr = match.group(1).strip()
+        inner_args = whole_call_args(formula, "UserMessage")
+        if inner_args:
+            inner_expr = inner_args.strip()
             # Evaluate the inner expression
             text = self.eval(f"={inner_expr}")
             return {"role": "user", "text": str(text) if text else ""}
 
         # AgentMessage(expr) - creates an assistant message dict
-        match = re.match(r"AgentMessage\((.+)\)$", formula.strip())
-        if match:
-            inner_expr = match.group(1).strip()
+        inner_args = whole_call_args(formula, "AgentMessage")
+        if inner_args:
+            inner_expr = inner_args.strip()
             text = self.eval(f"={inner_expr}")
             return {"role": "assistant", "text": str(text) if text else ""}
 
         # MessageText(expr) - extracts text from the last message
-        match = re.match(r"MessageText\((.+)\)$", formula.strip())
-        if match:
-            inner_expr = match.group(1).strip()
+        inner_args = whole_call_args(formula, "MessageText")
+        if inner_args:
+            inner_expr = inner_args.strip()
             # Reuse the helper method for consistent text extraction
             return self._eval_and_replace_message_text(inner_expr)
 

{agent_framework_declarative-1.3.0 → agent_framework_declarative-1.4.1}/agent_framework_declarative/_workflows/_executors_basic.py

@@ -53,7 +53,8 @@ class SetValueExecutor(DeclarativeActionExecutor):
         """Handle the SetValue action."""
         state = await self._ensure_state_initialized(ctx, trigger)
 
-        path = self._action_def.get("path")
+        # The builder accepts 'variable' in place of 'path' for SetValue
+        path = self._action_def.get("path") or _get_variable_path(self._action_def)
         value = self._action_def.get("value")
 
         if path:

{agent_framework_declarative-1.3.0 → agent_framework_declarative-1.4.1}/agent_framework_declarative/_workflows/_executors_mcp.py

@@ -32,7 +32,7 @@ from collections.abc import Mapping
 from dataclasses import dataclass, field
 from typing import Any
 
-import httpx
+import httpx2 as httpx
 from agent_framework import (
     Content,
     Message,
@@ -503,10 +503,10 @@ class InvokeMcpToolActionExecutor(DeclarativeActionExecutor):
             )
         except Exception as exc:
             try:
-                from mcp.shared.exceptions import McpError
+                from mcp.shared.exceptions import MCPError
             except ImportError:  # pragma: no cover - mcp is a hard dep
                 raise
-            if isinstance(exc, McpError):
+            if isinstance(exc, MCPError):
                 message = str(exc) or type(exc).__name__
                 return MCPToolResult(
                     outputs=[Content.from_text(f"Error: {message}")],

{agent_framework_declarative-1.3.0 → agent_framework_declarative-1.4.1}/agent_framework_declarative/_workflows/_executors_tools.py

@@ -243,6 +243,27 @@ class BaseToolExecutor(DeclarativeActionExecutor):
 
         return None
 
+    def _registered_tool_requires_approval(
+        self,
+        function_name: str,
+        ctx: WorkflowContext[Any, Any],
+    ) -> bool:
+        """Check whether the registered tool requires approval on every invocation.
+
+        A tool registered with ``approval_mode="always_require"`` must not run
+        without approval, even when the action omits ``requireApproval`` or sets
+        it to false.
+
+        Args:
+            function_name: Name of the function
+            ctx: Workflow context
+
+        Returns:
+            True if the registered tool requires approval, False otherwise
+        """
+        tool = self._get_tool(function_name, ctx)
+        return getattr(tool, "approval_mode", None) == "always_require"
+
     def _get_output_config(self) -> tuple[str | None, str | None, Any]:
         """Parse output bindings and the unevaluated autoSend setting.
 
@@ -433,7 +454,8 @@ class BaseToolExecutor(DeclarativeActionExecutor):
     ) -> None:
         """Handle the tool invocation with optional approval flow.
 
-        When requireApproval=true:
+        When requireApproval=true, or the registered tool has
+        approval_mode="always_require":
         1. Saves invocation state to State (keyed by executor ID)
         2. Emits ToolApprovalRequest via ctx.request_info()
         3. Workflow yields (returns without ActionComplete)
@@ -477,10 +499,11 @@ class BaseToolExecutor(DeclarativeActionExecutor):
             for key, value in arguments_def.items():  # type: ignore[reportUnknownVariableType]
                 arguments[key] = state.eval_if_expression(value)
 
-        # Check if approval is required
+        # Check if approval is required. The action's requireApproval cannot
+        # override a registered tool's approval_mode="always_require".
         require_approval = self._action_def.get("requireApproval", False)
 
-        if require_approval:
+        if require_approval or self._registered_tool_requires_approval(function_name, ctx):
             # Emit approval request - the request payload is the source of
             # truth for resumed invocation; no side-channel state is written.
             request_id = str(uuid.uuid4())

{agent_framework_declarative-1.3.0 → agent_framework_declarative-1.4.1}/agent_framework_declarative/_workflows/_mcp_handler.py

@@ -27,6 +27,7 @@ must trust the MCP server they invoke.
 from __future__ import annotations
 
 import asyncio
+import contextlib
 import hashlib
 import json
 import logging
@@ -36,7 +37,7 @@ from contextvars import ContextVar, Token
 from dataclasses import dataclass, field
 from typing import TYPE_CHECKING, Any, ClassVar, Protocol, cast, runtime_checkable
 
-import httpx
+import httpx2 as httpx
 
 if TYPE_CHECKING:
     from agent_framework import Content
@@ -345,10 +346,10 @@ class DefaultMCPToolHandler:
             # Be defensive about MCP errors that may bubble up without being
             # wrapped in ToolExecutionException by custom parsers.
             try:
-                from mcp.shared.exceptions import McpError
+                from mcp.shared.exceptions import MCPError
             except ImportError:  # pragma: no cover - mcp is a hard dep but stay defensive
                 raise
-            if isinstance(exc, McpError):
+            if isinstance(exc, MCPError):
                 message = str(exc) or type(exc).__name__
                 return MCPToolResult(
                     outputs=[Content.from_text(f"Error: {message}")],
@@ -369,7 +370,7 @@ class DefaultMCPToolHandler:
     async def _invoke_list_tools(entry: _CacheEntry) -> MCPToolResult:
         """Handle the reserved :attr:`LIST_TOOLS_TOOL_NAME` invocation.
 
-        Pages through ``session.list_tools()`` (mirroring the pagination loop
+        Pages through the normalized MCP connection (mirroring the pagination loop
         in :meth:`agent_framework.MCPTool.load_tools`) and serialises the
         full catalog as a single ``TextContent`` containing JSON of shape
         ``{"tools": [{name, description, inputSchema, outputSchema}, ...]}``.
@@ -383,8 +384,16 @@ class DefaultMCPToolHandler:
         """
         from agent_framework import Content
 
-        session = getattr(entry.tool, "session", None)
-        if session is None:
+        require_connection: Any = getattr(entry.tool, "_require_connection", None)
+        connection: Any | None = None
+        session: Any | None = None
+        if callable(require_connection):
+            with contextlib.suppress(RuntimeError):
+                connection = require_connection()
+        else:
+            session = getattr(entry.tool, "session", None)
+
+        if connection is None and session is None:
             message = "MCP session is not connected; cannot list tools."
             return MCPToolResult(
                 outputs=[Content.from_text(f"Error: {message}")],
@@ -398,9 +407,14 @@ class DefaultMCPToolHandler:
         collected: list[Any] = []
         params: mcp_types.PaginatedRequestParams | None = None
         while True:
-            tool_list = await session.list_tools(params=params)
+            if connection is not None:
+                tool_list = await connection.list_tools_page(params)
+            elif session is not None:
+                tool_list = await session.list_tools(params=params)
+            else:  # pragma: no cover - guarded before entering the loop
+                raise RuntimeError("MCP connection became unavailable while listing tools.")
             collected.extend(tool_list.tools)
-            next_cursor = getattr(tool_list, "nextCursor", None)
+            next_cursor = getattr(tool_list, "next_cursor", getattr(tool_list, "nextCursor", None))
             if not next_cursor:
                 break
             params = mcp_types.PaginatedRequestParams(cursor=next_cursor)
@@ -410,8 +424,8 @@ class DefaultMCPToolHandler:
                 {
                     "name": tool.name,
                     "description": tool.description,
-                    "inputSchema": tool.inputSchema,
-                    "outputSchema": tool.outputSchema,
+                    "inputSchema": getattr(tool, "input_schema", getattr(tool, "inputSchema", None)),
+                    "outputSchema": getattr(tool, "output_schema", getattr(tool, "outputSchema", None)),
                 }
                 for tool in collected
             ],

{agent_framework_declarative-1.3.0 → agent_framework_declarative-1.4.1}/agent_framework_declarative/_workflows/_powerfx_functions.py

@@ -12,9 +12,156 @@ or registered with the PowerFx engine when it is available.
 
 from __future__ import annotations
 
+from collections.abc import Iterator
 from typing import Any, cast
 
 
+def _skip_powerfx_opaque_token(formula: str, start: int) -> int:
+    """Return the end of an ordinary quoted token or comment, or start if neither."""
+    quote = formula[start]
+    if quote in ('"', "'"):
+        pos = start + 1
+        while pos < len(formula):
+            if formula[pos] == quote:
+                if pos + 1 < len(formula) and formula[pos + 1] == quote:
+                    pos += 2
+                    continue
+                return pos + 1
+            pos += 1
+        return pos
+    if formula.startswith("//", start):
+        pos = start + 2
+        while pos < len(formula) and formula[pos] not in "\r\n":
+            pos += 1
+        return pos
+    if formula.startswith("/*", start):
+        end = formula.find("*/", start + 2)
+        # An unterminated /* is not a complete comment: leave it as code so a
+        # trailing one is not mistaken for trivia following a complete call.
+        return start if end == -1 else end + 2
+    return start
+
+
+def _iter_powerfx_expression_indices(formula: str) -> Iterator[int]:
+    """Yield code positions, excluding literals/comments but including interpolation expressions."""
+    # None denotes interpolated text; integers track record braces in expression sections.
+    scopes: list[int | None] = [0]
+    cursor = 0
+    while cursor < len(formula):
+        depth = scopes[-1]
+        char = formula[cursor]
+        if depth is None:
+            if formula.startswith(('""', "{{", "}}"), cursor):
+                cursor += 2
+                continue
+            if char == "{":
+                scopes.append(0)
+            elif char == '"':
+                scopes.pop()
+            cursor += 1
+            continue
+
+        if formula.startswith('$"', cursor):
+            scopes.append(None)
+            cursor += 2
+            continue
+
+        token_end = _skip_powerfx_opaque_token(formula, cursor)
+        if token_end != cursor:
+            cursor = token_end
+            continue
+
+        if char == "{":
+            scopes[-1] = depth + 1
+        elif char == "}":
+            if depth > 0:
+                scopes[-1] = depth - 1
+            elif len(scopes) > 1:
+                scopes.pop()
+                cursor += 1
+                continue
+
+        yield cursor
+        cursor += 1
+
+
+def _after_trailing_trivia(formula: str, start: int) -> int:
+    """Return the index after trailing whitespace and complete comments.
+
+    Unlike the expression walker, this never skips a string literal: a quoted
+    token after the call's own closing paren is trailing code, not trivia, so it
+    stops the scan and leaves the formula to PowerFx.
+    """
+    index = start
+    while index < len(formula):
+        if formula[index].isspace():
+            index += 1
+            continue
+        if formula.startswith(("//", "/*"), index):
+            token_end = _skip_powerfx_opaque_token(formula, index)
+            if token_end == index:
+                # Unterminated /* is not a complete comment, so real code follows.
+                break
+            index = token_end
+            continue
+        break
+    return index
+
+
+def whole_call_args(formula: str, *names: str) -> str | None:
+    """Return the argument text when ``formula`` is exactly one ``Name(...)`` call.
+
+    A custom-function handler must not fire for a formula that merely *starts*
+    with its name: the closing parenthesis has to be the call's own and nothing
+    but trivia may follow it. Otherwise a trailing operator is swallowed into the
+    argument list and the formula is evaluated as something the author never
+    wrote, instead of being left to PowerFx.
+
+    Parentheses inside string literals and comments are data, not delimiters, so
+    the scan walks the formula with the shared PowerFx expression walker: it
+    skips those tokens whole and counts only parentheses that are real code,
+    including those inside an interpolated string's ``{...}`` expression sections.
+
+    Args:
+        formula: The stripped formula to inspect.
+        *names: Candidate function names, matched case-sensitively.
+
+    Returns:
+        The text between the call's parentheses - an empty string for an
+        argument-less call - or None when ``formula`` is not a single complete
+        call to one of ``names``. Callers that require an argument check the
+        result for emptiness so the call still falls through to PowerFx, which
+        reports the arity error.
+    """
+    for name in names:
+        prefix = f"{name}("
+        if not formula.startswith(prefix):
+            continue
+        positions = _iter_powerfx_expression_indices(formula)
+        depth = 0
+        close_index = -1
+        for index in positions:
+            char = formula[index]
+            if char == "(":
+                depth += 1
+            elif char == ")":
+                depth -= 1
+                if depth == 0:
+                    close_index = index
+                    break
+        if close_index == -1:
+            # Unbalanced: the call never closes, so it is not a whole call.
+            return None
+        # Only whitespace and complete comments may follow the call's own closing
+        # paren. The suffix scan deliberately does not reuse the literal-skipping
+        # walker: a trailing string literal (or any other code) there means the
+        # formula is a larger expression the caller must not claim.
+        if _after_trailing_trivia(formula, close_index + 1) != len(formula):
+            return None
+        return formula[len(prefix) : close_index]
+    return None
+
+
 def message_text(messages: Any) -> str:
     """Extract text content from a message or list of messages.
 

{agent_framework_declarative-1.3.0 → agent_framework_declarative-1.4.1}/agent_framework_declarative/_workflows/_state.py

@@ -441,7 +441,7 @@ class WorkflowState:
         Returns:
             The evaluated result
         """
-        from ._powerfx_functions import CUSTOM_FUNCTIONS
+        from ._powerfx_functions import CUSTOM_FUNCTIONS, whole_call_args
 
         formula = formula.strip()
 
@@ -452,15 +452,15 @@ class WorkflowState:
             return not bool(result)
 
         # Handle Not() function
-        if formula.startswith("Not(") and formula.endswith(")"):
-            inner = formula[4:-1].strip()
-            result = self._eval_simple(inner)
+        not_args = whole_call_args(formula, "Not")
+        if not_args is not None:
+            result = self._eval_simple(not_args.strip())
             return not bool(result)
 
         # Handle function calls
         for func_name, func in CUSTOM_FUNCTIONS.items():
-            if formula.startswith(f"{func_name}(") and formula.endswith(")"):
-                args_str = formula[len(func_name) + 1 : -1]
+            args_str = whole_call_args(formula, func_name)
+            if args_str is not None:
                 # Simple argument parsing (doesn't handle nested calls well)
                 args = self._parse_function_args(args_str)
                 evaluated_args = [self._eval_simple(arg) if isinstance(arg, str) else arg for arg in args]

{agent_framework_declarative-1.3.0 → agent_framework_declarative-1.4.1}/pyproject.toml

@@ -4,7 +4,7 @@ description = "Declarative specification support for Microsoft Agent Framework."
 authors = [{ name = "Microsoft", email = "af-support@microsoft.com"}]
 readme = "README.md"
 requires-python = ">=3.10"
-version = "1.3.0"
+version = "1.4.1"
 license-files = ["LICENSE"]
 urls.homepage = "https://aka.ms/agent-framework"
 urls.source = "https://github.com/microsoft/agent-framework/tree/main/python"
@@ -15,15 +15,15 @@ classifiers = [
   "Development Status :: 5 - Production/Stable",
   "Intended Audience :: Developers",
   "Programming Language :: Python :: 3",
-  "Programming Language :: Python :: 3.10",
   "Programming Language :: Python :: 3.11",
   "Programming Language :: Python :: 3.12",
   "Programming Language :: Python :: 3.13",
   "Typing :: Typed",
 ]
 dependencies = [
-    "agent-framework-core>=1.20.0,<2",
+    "agent-framework-core>=1.23.0,<2",
     "httpx>=0.27,<0.29",
+    "httpx2>=2.0.0,<3",
     "powerfx>=0.0.32,<0.0.35; python_version < '3.14'",
     "pyyaml>=6.0,<7.0",
 ]
@@ -31,6 +31,9 @@ dependencies = [
 dev = [
     "types-PyYaml==6.0.12.20260906"
 ]
+test = [
+    "tenacity>=9.1.4,<9.2.0",
+]
 
 [tool.uv]
 prerelease = "if-necessary"