agent-framework-declarative 1.0.4__tar.gz → 1.1.0__tar.gz

agent_framework_declarative-1.1.0/PKG-INFO

@@ -0,0 +1,90 @@
+Metadata-Version: 2.4
+Name: agent-framework-declarative
+Version: 1.1.0
+Summary: Declarative specification support for Microsoft Agent Framework.
+Author-email: Microsoft <af-support@microsoft.com>
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+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.19.0,<2
+Requires-Dist: httpx>=0.27,<1
+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
+Project-URL: issues, https://github.com/microsoft/agent-framework/issues
+Project-URL: release_notes, https://github.com/microsoft/agent-framework/releases?q=tag%3Apython-1&expanded=true
+Project-URL: source, https://github.com/microsoft/agent-framework/tree/main/python
+
+# Get Started with Microsoft Agent Framework Declarative
+
+Please install this package via pip:
+
+```bash
+pip install agent-framework-declarative
+```
+
+## Release stage
+
+This package ships at two different stability levels:
+
+- **Declarative workflows** (`WorkflowFactory`, executors, handlers, and the
+  `_workflows` surface) are **stable**.
+- **Declarative agents** (`AgentFactory` and the YAML agent loading/parsing path:
+  `DeclarativeLoaderError`, `ProviderLookupError`, `ProviderTypeMapping`) are
+  **experimental** and may change or be removed in future versions without notice.
+  Using any of these symbols emits an `ExperimentalWarning` on first use.
+
+## Declarative features
+
+The declarative packages provides support for building agents based on a declarative yaml specification.
+
+## HTTP request client ownership and cookies
+
+**Breaking change:** The HTTP client created by `DefaultHttpRequestHandler` no longer
+persists response cookies. The handler still creates its client lazily, reuses it across
+requests and workflows, and closes it on `aclose()` or async context-manager exit.
+Timeout and redirect defaults are unchanged.
+
+Applications requiring cookies for authentication, session continuity, or load-balancer
+affinity must supply an `httpx.AsyncClient` through `client=` or `client_provider=`.
+Supplied and provider-returned clients retain their configuration and cookie behavior
+and must be closed by the caller. Scope cookie-bearing clients to one authenticated
+principal; sharing a handler across workflows does not partition a client's cookies.
+A provider returning `None` falls back to `client=`, if supplied, then to the internally
+owned client with the default cookie policy.
+
+Explicit `Cookie` request headers remain supported. Response `Set-Cookie` headers
+remain available in `HttpRequestResult.headers`; disabling persistence does not redact
+the response.
+
+## MCP handler session lifetime
+
+`DefaultMCPToolHandler()` reuses MCP sessions through a bounded LRU cache.
+When configured with `client_provider`, it instead invokes the provider and
+creates a fresh MCP tool/session for every invocation, including `tools/list`.
+Sessions are never reused in this mode, even if the provider returns `None`
+or the same `httpx.AsyncClient` instance.
+
+Each invocation closes its tool/session on success, failure, or cancellation.
+Internally created fallback HTTP clients are also closed; caller-supplied HTTP
+clients remain caller-owned and are never closed by the handler. Calling
+`aclose()` rejects new invocations and waits for active provider-backed
+invocations to finish cleaning up. Calling it from an active invocation's
+context (including provider callbacks, inherited child tasks, and cleanup)
+raises `RuntimeError` before changing handler state, rather than waiting on
+itself. Close the handler outside that context or after the invocation completes.
+
+This intentionally incurs connection and initialization overhead and does not
+retain server session state between provider-backed invocations. Applications
+that require shared session ownership must implement an explicitly scoped
+custom `MCPToolHandler`; there is no provider-backed session-cache opt-in.
+

agent_framework_declarative-1.1.0/README.md

@@ -0,0 +1,63 @@
+# Get Started with Microsoft Agent Framework Declarative
+
+Please install this package via pip:
+
+```bash
+pip install agent-framework-declarative
+```
+
+## Release stage
+
+This package ships at two different stability levels:
+
+- **Declarative workflows** (`WorkflowFactory`, executors, handlers, and the
+  `_workflows` surface) are **stable**.
+- **Declarative agents** (`AgentFactory` and the YAML agent loading/parsing path:
+  `DeclarativeLoaderError`, `ProviderLookupError`, `ProviderTypeMapping`) are
+  **experimental** and may change or be removed in future versions without notice.
+  Using any of these symbols emits an `ExperimentalWarning` on first use.
+
+## Declarative features
+
+The declarative packages provides support for building agents based on a declarative yaml specification.
+
+## HTTP request client ownership and cookies
+
+**Breaking change:** The HTTP client created by `DefaultHttpRequestHandler` no longer
+persists response cookies. The handler still creates its client lazily, reuses it across
+requests and workflows, and closes it on `aclose()` or async context-manager exit.
+Timeout and redirect defaults are unchanged.
+
+Applications requiring cookies for authentication, session continuity, or load-balancer
+affinity must supply an `httpx.AsyncClient` through `client=` or `client_provider=`.
+Supplied and provider-returned clients retain their configuration and cookie behavior
+and must be closed by the caller. Scope cookie-bearing clients to one authenticated
+principal; sharing a handler across workflows does not partition a client's cookies.
+A provider returning `None` falls back to `client=`, if supplied, then to the internally
+owned client with the default cookie policy.
+
+Explicit `Cookie` request headers remain supported. Response `Set-Cookie` headers
+remain available in `HttpRequestResult.headers`; disabling persistence does not redact
+the response.
+
+## MCP handler session lifetime
+
+`DefaultMCPToolHandler()` reuses MCP sessions through a bounded LRU cache.
+When configured with `client_provider`, it instead invokes the provider and
+creates a fresh MCP tool/session for every invocation, including `tools/list`.
+Sessions are never reused in this mode, even if the provider returns `None`
+or the same `httpx.AsyncClient` instance.
+
+Each invocation closes its tool/session on success, failure, or cancellation.
+Internally created fallback HTTP clients are also closed; caller-supplied HTTP
+clients remain caller-owned and are never closed by the handler. Calling
+`aclose()` rejects new invocations and waits for active provider-backed
+invocations to finish cleaning up. Calling it from an active invocation's
+context (including provider callbacks, inherited child tasks, and cleanup)
+raises `RuntimeError` before changing handler state, rather than waiting on
+itself. Close the handler outside that context or after the invocation completes.
+
+This intentionally incurs connection and initialization overhead and does not
+retain server session state between provider-backed invocations. Applications
+that require shared session ownership must implement an explicitly scoped
+custom `MCPToolHandler`; there is no provider-backed session-cache opt-in.

{agent_framework_declarative-1.0.4 → agent_framework_declarative-1.1.0}/agent_framework_declarative/_loader.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import asyncio
 import sys
 from collections.abc import Callable, Mapping
 from pathlib import Path
@@ -338,7 +339,7 @@ class AgentFactory:
             yaml_path = Path(yaml_path)
         if not yaml_path.exists():
             raise DeclarativeLoaderError(f"YAML file not found at path: {yaml_path}")
-        with open(yaml_path) as f:
+        with open(yaml_path, encoding="utf-8") as f:
             yaml_str = f.read()
         return self.create_agent_from_yaml(yaml_str)
 
@@ -508,9 +509,10 @@ class AgentFactory:
         """
         if not isinstance(yaml_path, Path):
             yaml_path = Path(yaml_path)
-        if not yaml_path.exists():
-            raise DeclarativeLoaderError(f"YAML file not found at path: {yaml_path}")
-        yaml_str = yaml_path.read_text()
+        try:
+            yaml_str = await asyncio.to_thread(yaml_path.read_text, encoding="utf-8")
+        except FileNotFoundError as exc:
+            raise DeclarativeLoaderError(f"YAML file not found at path: {yaml_path}") from exc
         return await self.create_agent_from_yaml_async(yaml_str)
 
     async def create_agent_from_yaml_async(self, yaml_str: str) -> Agent:

{agent_framework_declarative-1.0.4 → agent_framework_declarative-1.1.0}/agent_framework_declarative/_workflows/_declarative_base.py

@@ -31,7 +31,7 @@ import os
 import re
 import sys
 import uuid
-from collections.abc import Mapping
+from collections.abc import Iterator, Mapping
 from dataclasses import dataclass, field
 from decimal import Decimal as _Decimal
 from enum import Enum
@@ -67,6 +67,73 @@ _ENV_REFERENCE_RE = re.compile(r"\bEnv\.([A-Za-z_][A-Za-z0-9_]*)")
 _SAFE_PATH_SEGMENT_RE = re.compile(r"^[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.
@@ -667,11 +734,11 @@ class DeclarativeWorkflowState:
         When they appear nested inside other functions (e.g., Upper(MessageText(...))),
         we need to evaluate them first and replace with the result.
 
-        For long strings (>500 chars), the result is stored in a temporary state variable
-        to avoid exceeding PowerFx's 1000 character expression limit. This is a limitation
-        of the Python PowerFx wrapper (powerfx package), which doesn't expose the
-        MaximumExpressionLength configuration that the .NET PowerFxConfig provides.
-        The .NET implementation defaults to 10,000 characters, while Python defaults to 1,000.
+        Results are stored in temporary state variables so untrusted message text is
+        passed to PowerFx as data rather than inserted into formula source.
+        Temporary names avoid existing Local keys and references in the original formula.
+        Literal text, quoted identifiers, and comments are left untouched; expression
+        sections inside PowerFx interpolated strings are preprocessed as code.
 
         Args:
             formula: The PowerFx formula to pre-process
@@ -684,90 +751,53 @@ class DeclarativeWorkflowState:
         Returns:
             The rewritten formula.
         """
-        import re
-
-        # Threshold for storing in state vs embedding as literal.
-        # The Python PowerFx wrapper defaults to a 1000 char expression limit (vs 10,000 in .NET).
-        # We use 500 to leave room for the rest of the expression around the replaced value.
-        MAX_INLINE_LENGTH = 500
-
         temp_var_counter = 0
-
-        # Custom functions that need pre-processing: (regex pattern, handler)
-        custom_functions = [
-            (r"MessageText\(", self._eval_and_replace_message_text),
-        ]
-
-        for pattern, handler in custom_functions:
-            # Find all occurrences of the custom function
-            while True:
-                match = re.search(pattern, formula)
-                if not match:
+        reserved_names = {name.casefold() for name in self.get_state_data().get("Local", {})}
+        # Reserve formula references too, so previously undefined names stay undefined.
+        folded_formula = formula.casefold()
+        function_name = "MessageText"
+        call_prefix = f"{function_name}("
+        result: list[str] = []
+        copied_until = 0
+        positions = _iter_powerfx_expression_indices(formula)
+
+        for cursor in positions:
+            if not formula.startswith(call_prefix, cursor):
+                continue
+
+            paren_start = cursor + len(function_name)
+            depth = 1
+            for pos in positions:
+                if pos <= paren_start:
+                    continue
+                char = formula[pos]
+                if char == "(":
+                    depth += 1
+                elif char == ")":
+                    depth -= 1
+                if depth == 0:
                     break
+            else:
+                break
 
-                # Find the matching closing parenthesis
-                start = match.start()
-                paren_start = match.end() - 1  # Position of opening (
-                depth = 1
-                pos = paren_start + 1
-                in_string = False
-                escape_next = False
-
-                while pos < len(formula) and depth > 0:
-                    char = formula[pos]
-                    if escape_next:
-                        escape_next = False
-                        pos += 1
-                        continue
-                    if char == "\\":
-                        escape_next = True
-                        pos += 1
-                        continue
-                    if char == '"' and not escape_next:
-                        in_string = not in_string
-                    elif not in_string:
-                        if char == "(":
-                            depth += 1
-                        elif char == ")":
-                            depth -= 1
-                    pos += 1
-
-                if depth != 0:
-                    # Malformed expression, skip
+            inner_expr = formula[paren_start + 1 : pos]
+            replacement = self._eval_and_replace_message_text(inner_expr)
+            while True:
+                temp_var_name = f"_TempMessageText{temp_var_counter}"
+                temp_var_counter += 1
+                folded_name = temp_var_name.casefold()
+                if folded_name not in reserved_names and folded_name not in folded_formula:
                     break
-
-                # Extract the inner expression (between parentheses)
-                end = pos
-                inner_expr = formula[paren_start + 1 : end - 1]
-
-                # Evaluate and get replacement
-                replacement = handler(inner_expr)
-
-                # Replace in formula
-                if isinstance(replacement, str):
-                    if len(replacement) > MAX_INLINE_LENGTH:
-                        # Store long results in an underscore-prefixed temp key;
-                        # record the prior value so eval() can restore it.
-                        temp_var_name = f"_TempMessageText{temp_var_counter}"
-                        temp_var_counter += 1
-                        temp_var_path = f"Local.{temp_var_name}"
-                        temp_writes.append((temp_var_path, self.get(temp_var_path, default=self._MISSING)))
-                        self.set(temp_var_path, replacement)
-                        replacement_str = temp_var_path
-                        logger.debug(
-                            f"Stored long MessageText result ({len(replacement)} chars) "
-                            f"in temp variable {temp_var_name}"
-                        )
-                    else:
-                        # Short strings can be embedded directly
-                        escaped = replacement.replace('"', '""')
-                        replacement_str = f'"{escaped}"'
-                else:
-                    replacement_str = str(replacement) if replacement is not None else '""'
-
-                formula = formula[:start] + replacement_str + formula[end:]
-
-        return formula
+            temp_var_path = f"Local.{temp_var_name}"
+            temp_writes.append((temp_var_path, self.get(temp_var_path, default=self._MISSING)))
+            self.set(temp_var_path, replacement)
+            result.append(formula[copied_until:cursor])
+            result.append(temp_var_path)
+            logger.debug(f"Stored MessageText result ({len(replacement)} chars) in temp variable {temp_var_name}")
+            copied_until = pos + 1
+
+        result.append(formula[copied_until:])
+        return "".join(result)
 
     def _eval_and_replace_message_text(self, inner_expr: str) -> str:
         """Evaluate MessageText() and return the text result.

{agent_framework_declarative-1.0.4 → agent_framework_declarative-1.1.0}/agent_framework_declarative/_workflows/_executors_agents.py

@@ -788,16 +788,28 @@ class InvokeAzureAgentExecutor(DeclarativeActionExecutor):
             _validate_conversation_history(messages_for_agent, agent_name)
 
         # Retrieve kwargs passed to workflow.run() so they propagate to agent tools
-        from agent_framework._workflows._const import WORKFLOW_RUN_KWARGS_KEY
-
-        run_kwargs: dict[str, Any] = ctx.get_state(WORKFLOW_RUN_KWARGS_KEY, {})
+        from agent_framework._workflows import _agent_utils as workflow_agent_utils
+        from agent_framework._workflows import _const as workflow_const
+
+        run_kwargs: dict[str, Any] = ctx.get_state(workflow_const.WORKFLOW_RUN_KWARGS_KEY, {})
+        prepare_run_kwargs = getattr(workflow_agent_utils, "prepare_executor_run_kwargs", None)
+        resolved_state_key = getattr(workflow_const, "RESOLVED_WORKFLOW_RUN_KWARGS_KEY", None)
+        if callable(prepare_run_kwargs) and isinstance(resolved_state_key, str):
+            missing_resolved_state = object()
+            resolved_run_kwargs: Any = ctx.get_state(resolved_state_key, missing_resolved_state)
+            if resolved_run_kwargs is not missing_resolved_state:
+                if not isinstance(resolved_run_kwargs, dict):
+                    raise TypeError("Resolved workflow run kwargs state must be a dict.")
+                run_kwargs = cast(Any, prepare_run_kwargs)(self.id, run_kwargs, resolved_run_kwargs)
         options: dict[str, Any] | None = None
         if run_kwargs:
             # Merge caller-provided options to avoid duplicate keyword argument
             options = dict(run_kwargs.get("options") or {})
             options["additional_function_arguments"] = run_kwargs
-            # Exclude 'options' from splat to avoid TypeError on duplicate keyword
-            run_kwargs = {k: v for k, v in run_kwargs.items() if k != "options"}
+            # Exclude 'options' from splat to avoid TypeError on duplicate keyword,
+            # and keep internal workflow-routing copies (stored under underscore
+            # keys for nested executors) out of the public Agent.run signature
+            run_kwargs = {k: v for k, v in run_kwargs.items() if k != "options" and not k.startswith("_")}
 
         # Use run() method to get properly structured messages (including tool calls and results)
         # This is critical for multi-turn conversations where tool calls must be followed

{agent_framework_declarative-1.0.4 → agent_framework_declarative-1.1.0}/agent_framework_declarative/_workflows/_executors_http.py

@@ -6,9 +6,8 @@ Mirrors the .NET ``HttpRequestExecutor``: dispatches an HTTP request through the
 configured :class:`HttpRequestHandler`, parses the response body, and assigns
 the parsed body and response headers to the declared state paths.
 
-Security note: response bodies can echo secrets and may be very large. Diagnostic
-messages produced for non-2xx responses truncate the body to 256 characters and
-collapse CR/LF/TAB to spaces (parity with .NET ``FormatBodyForDiagnostics``).
+Response bodies are excluded from non-2xx exceptions because they may contain
+private backend data. Request URLs and status codes remain available for diagnostics.
 """
 
 from __future__ import annotations
@@ -40,10 +39,6 @@ __all__ = [
 
 logger = logging.getLogger(__name__)
 
-_MAX_BODY_DIAGNOSTIC_LENGTH = 256
-_BODY_TRUNCATION_SUFFIX = " \u2026 [truncated]"
-
-
 # Body discriminator aliases. Long forms match the .NET object-model type
 # names so YAML produced by .NET round-trips. Short forms are the .NET YAML
 # convention used in test fixtures.
@@ -69,24 +64,6 @@ def _get_path(action_def: Mapping[str, Any], key: str) -> str | None:
     return None
 
 
-def _format_body_for_diagnostics(body: str | None) -> str:
-    """Truncate and sanitise a response body for inclusion in error messages.
-
-    Mirrors the .NET ``FormatBodyForDiagnostics`` helper:
-
-    - Empty/None -> empty string.
-    - Replaces CR/LF/TAB with spaces.
-    - Truncates to 256 chars with a unicode-ellipsis ``[truncated]`` suffix.
-    """
-    if not body:
-        return ""
-
-    truncated = len(body) > _MAX_BODY_DIAGNOSTIC_LENGTH
-    head = body[:_MAX_BODY_DIAGNOSTIC_LENGTH] if truncated else body
-    sanitized = head.replace("\r", " ").replace("\n", " ").replace("\t", " ")
-    return sanitized + _BODY_TRUNCATION_SUFFIX if truncated else sanitized
-
-
 def _parse_response_body(body: str | None) -> Any:
     """Parse an HTTP response body the same way the .NET executor does.
 
@@ -148,8 +125,8 @@ class HttpRequestActionExecutor(DeclarativeActionExecutor):
       an Assistant :class:`agent_framework.Message` to
       ``System.conversations.{id}.messages``.
     - On non-2xx, still publishes ``responseHeaders`` (diagnostic) and raises
-      :class:`DeclarativeActionError` with a status-coded message containing a
-      truncated/sanitised body preview.
+      :class:`DeclarativeActionError` with the request URL and status code,
+      without including the response body.
 
     Transport errors (``httpx.TimeoutException``, ``TimeoutError``,
     ``httpx.HTTPError``) become :class:`DeclarativeActionError`. ``CancelledError``
@@ -229,12 +206,7 @@ class HttpRequestActionExecutor(DeclarativeActionExecutor):
 
         # Non-success path: still publish headers diagnostically, then raise.
         self._assign_response_headers(state, result)
-        body_preview = _format_body_for_diagnostics(result.body)
-        if body_preview:
-            message = f"HTTP request to '{url}' failed with status code {result.status_code}. Body: '{body_preview}'"
-        else:
-            message = f"HTTP request to '{url}' failed with status code {result.status_code}."
-        raise DeclarativeActionError(message)
+        raise DeclarativeActionError(f"HTTP request to '{url}' failed with status code {result.status_code}.")
 
     # ----- Field resolution ----------------------------------------------------
 

{agent_framework_declarative-1.0.4 → agent_framework_declarative-1.1.0}/agent_framework_declarative/_workflows/_factory.py

@@ -241,7 +241,7 @@ class WorkflowFactory:
         if not yaml_path.exists():
             raise FileNotFoundError(f"Workflow YAML file not found: {yaml_path}")
 
-        with open(yaml_path) as f:
+        with open(yaml_path, encoding="utf-8") as f:
             yaml_content = f.read()
 
         return self.create_workflow_from_yaml(yaml_content, base_path=yaml_path.parent)

{agent_framework_declarative-1.0.4 → agent_framework_declarative-1.1.0}/agent_framework_declarative/_workflows/_http_handler.py

@@ -23,6 +23,7 @@ from __future__ import annotations
 import asyncio
 from collections.abc import Awaitable, Callable, Mapping
 from dataclasses import dataclass, field
+from http.cookiejar import CookieJar, DefaultCookiePolicy
 from typing import Any, Protocol, runtime_checkable
 from urllib.parse import parse_qsl, quote, urlencode, urlsplit, urlunsplit
 
@@ -122,12 +123,18 @@ class DefaultHttpRequestHandler:
     Construction modes:
 
     1. ``DefaultHttpRequestHandler()`` — owns an internal client created lazily
-       on first ``send()``. Closed by :meth:`aclose`.
+       on first ``send()`` without response-cookie persistence. Closed by :meth:`aclose`.
     2. ``DefaultHttpRequestHandler(client=existing)`` — caller-owned client.
-       Not closed by :meth:`aclose`.
+       Retains its cookie behavior and is not closed by :meth:`aclose`.
     3. ``DefaultHttpRequestHandler(client_provider=cb)`` — per-request client
        lookup (parity with .NET's ``httpClientProvider`` callback). The
-       provider may return ``None`` to fall back to the owned/default client.
+       provider's clients retain their cookie behavior and are not closed by :meth:`aclose`.
+       Returning ``None`` falls back to ``client``, if supplied, then to the owned client.
+
+    Applications requiring persistent cookies must supply a client through ``client``
+    or ``client_provider`` scoped to one authenticated principal and manage its lifetime.
+    Explicit outbound ``Cookie`` headers and response ``Set-Cookie`` headers are preserved;
+    the owned-client policy only prevents automatic cookie persistence.
 
     .. warning::
 
@@ -262,7 +269,9 @@ class DefaultHttpRequestHandler:
             # one of them.
             async with self._owned_client_lock:
                 if self._owned_client is None:
-                    self._owned_client = httpx.AsyncClient()
+                    self._owned_client = httpx.AsyncClient(
+                        cookies=CookieJar(policy=DefaultCookiePolicy(allowed_domains=[])),
+                    )
         return self._owned_client
 
     async def __aenter__(self) -> DefaultHttpRequestHandler:

{agent_framework_declarative-1.0.4 → agent_framework_declarative-1.1.0}/agent_framework_declarative/_workflows/_mcp_handler.py

@@ -32,6 +32,7 @@ import json
 import logging
 from collections import OrderedDict
 from collections.abc import Awaitable, Callable
+from contextvars import ContextVar, Token
 from dataclasses import dataclass, field
 from typing import TYPE_CHECKING, Any, ClassVar, Protocol, cast, runtime_checkable
 
@@ -157,14 +158,14 @@ class _CacheEntry:
 class DefaultMCPToolHandler:
     """Default :class:`MCPToolHandler` backed by :class:`agent_framework.MCPStreamableHTTPTool`.
 
-    Caches one :class:`agent_framework.MCPStreamableHTTPTool` instance per
-    ``(server_url, server_label, connection_name, headers_hash)`` in a
-    bounded LRU. The cache prevents re-establishing an MCP session for every
+    Without a ``client_provider``, caches one
+    :class:`agent_framework.MCPStreamableHTTPTool` instance per
+    ``(server_url, server_label, connection_name, headers_hash)`` in a bounded
+    LRU. The cache prevents re-establishing an MCP session for every
     invocation while ensuring different header sets (auth tokens) cannot
     share a session — matches the .NET design intent while bounding
-    cardinality. ``server_label`` and ``connection_name`` participate in
-    the key so that callers using ``client_provider`` to dispatch on those
-    fields receive a fresh client per logical connection (see below).
+    cardinality. ``server_label`` and ``connection_name`` also participate
+    in the key to distinguish logical connections.
     Header *names* are lower-cased inside the hash payload only — the
     headers passed on the wire keep the caller's original casing — so two
     YAML actions that spell ``Authorization`` differently still share a
@@ -174,12 +175,20 @@ class DefaultMCPToolHandler:
 
     1. ``DefaultMCPToolHandler()`` — owns its own ``httpx.AsyncClient``
        instances created lazily per cache entry. Closed by :meth:`aclose`.
-    2. ``DefaultMCPToolHandler(client_provider=cb)`` — per-server client
+    2. ``DefaultMCPToolHandler(client_provider=cb)`` — per-invocation client
        lookup (parity with .NET ``httpClientProvider`` callback). The
        callback receives the full :class:`MCPToolInvocation` so it can
        dispatch on ``server_url`` / ``connection_name`` / ``server_label``.
-       Returning ``None`` falls back to an internally-created client. Caller
-       supplied clients are NOT closed by :meth:`aclose`.
+       The callback is invoked for every call, including ``tools/list``.
+       Each call creates and closes its own MCP tool/session, even when the
+       callback returns ``None`` or the same client object. Returning ``None``
+       falls back to an internally-created client, closed with the invocation.
+       Caller-supplied clients are never closed by this handler.
+
+       This intentionally trades connection/session reuse for invocation
+       isolation. Server session state is not retained across invocations;
+       callers needing shared session ownership must implement an explicitly
+       scoped custom :class:`MCPToolHandler`.
 
     .. warning::
 
@@ -187,11 +196,11 @@ class DefaultMCPToolHandler:
        or replace it with a custom handler in production deployments.
 
     Args:
-        client_provider: Optional per-server ``httpx.AsyncClient`` provider.
-        cache_max_size: Maximum number of cached MCP clients. When exceeded,
-            the least-recently-used entry is evicted and its client closed
-            (only owned clients are closed; caller-supplied ones are not).
-            Defaults to ``32``.
+        client_provider: Optional per-invocation ``httpx.AsyncClient`` provider.
+        cache_max_size: Maximum number of cached MCP clients in no-provider mode.
+            When exceeded, the least-recently-used entry is evicted and its
+            owned client closed. Defaults to ``32``. Does not enable session
+            caching when a provider is configured.
     """
 
     LIST_TOOLS_TOOL_NAME: ClassVar[str] = "tools/list"
@@ -227,12 +236,19 @@ class DefaultMCPToolHandler:
         # tasks awaiting the same key will await the same future and share
         # the resulting cache entry.
         self._inflight: dict[tuple[str, str, str, str], asyncio.Future[_CacheEntry]] = {}
+        # Completion signals only: provider-backed calls never share entries.
+        self._active_invocations: set[asyncio.Future[None]] = set()
+        # Keep ancestry so a completed nested call cannot hide an active parent
+        # in the context inherited by child tasks, including cleanup tasks.
+        self._invocation_context: ContextVar[tuple[asyncio.Future[None], ...]] = ContextVar(
+            f"default_mcp_tool_handler_invocations_{id(self)}", default=()
+        )
         # Set by ``aclose`` to prevent post-close cache insertions and to
         # reject new ``invoke_tool`` calls. Once set, never cleared.
         self._closed = False
 
     async def invoke_tool(self, invocation: MCPToolInvocation) -> MCPToolResult:
-        """Invoke ``invocation.tool_name`` on the cached MCP client for the server.
+        """Invoke ``invocation.tool_name`` on an MCP client for the server.
 
         The reserved name :attr:`LIST_TOOLS_TOOL_NAME` (``"tools/list"``) is
         intercepted client-side: instead of being forwarded as a tool call,
@@ -241,7 +257,6 @@ class DefaultMCPToolHandler:
         ``TextContent`` containing a JSON tool catalog.
         """
         from agent_framework import Content
-        from agent_framework.exceptions import ToolExecutionException
 
         # Reserved-name args validation runs before connect: rejecting bad
         # input shouldn't require establishing an MCP session.
@@ -253,23 +268,55 @@ class DefaultMCPToolHandler:
                 error_message=message,
             )
 
+        entry: _CacheEntry | None = None
+        completion: asyncio.Future[None] | None = None
+        context_token: Token[tuple[asyncio.Future[None], ...]] | None = None
         try:
-            entry = await self._get_or_create_entry(invocation)
-        except Exception as exc:
-            # Connect / cache lookup failures surface as tool errors so the
-            # workflow can store them at output.result without crashing.
-            logger.warning(
-                "DefaultMCPToolHandler: failed to obtain MCP client for url=%s tool=%s: %s",
-                invocation.server_url,
-                invocation.tool_name,
-                exc,
-            )
-            message = f"Failed to connect to MCP server: {type(exc).__name__}: {exc}".rstrip(": ")
-            return MCPToolResult(
-                outputs=[Content.from_text(f"Error: {message}")],
-                is_error=True,
-                error_message=message,
-            )
+            try:
+                if self._client_provider is None:
+                    entry = await self._get_or_create_entry(invocation)
+                else:
+                    async with self._cache_lock:
+                        if self._closed:
+                            raise RuntimeError("DefaultMCPToolHandler is closed")
+                        completion = asyncio.get_running_loop().create_future()
+                        self._active_invocations.add(completion)
+                    context_token = self._invocation_context.set((*self._invocation_context.get(), completion))
+                    entry = await self._create_entry(invocation)
+                    if self._closed:
+                        raise RuntimeError("DefaultMCPToolHandler is closed")
+            except Exception as exc:
+                # Connect / cache lookup failures surface as tool errors so the
+                # workflow can store them at output.result without crashing.
+                logger.warning(
+                    "DefaultMCPToolHandler: failed to obtain MCP client for url=%s tool=%s: %s",
+                    invocation.server_url,
+                    invocation.tool_name,
+                    exc,
+                )
+                message = f"Failed to connect to MCP server: {type(exc).__name__}: {exc}".rstrip(": ")
+                return MCPToolResult(
+                    outputs=[Content.from_text(f"Error: {message}")],
+                    is_error=True,
+                    error_message=message,
+                )
+
+            return await self._invoke_entry(entry, invocation)
+        finally:
+            if completion is not None:
+                try:
+                    if entry is not None:
+                        await self._close_invocation_entry(entry)
+                finally:
+                    if context_token is not None:
+                        self._invocation_context.reset(context_token)
+                    self._active_invocations.discard(completion)
+                    completion.set_result(None)
+
+    async def _invoke_entry(self, entry: _CacheEntry, invocation: MCPToolInvocation) -> MCPToolResult:
+        """Dispatch a connected invocation and preserve tool error mapping."""
+        from agent_framework import Content
+        from agent_framework.exceptions import ToolExecutionException
 
         try:
             if invocation.tool_name == self.LIST_TOOLS_TOOL_NAME:
@@ -372,24 +419,42 @@ class DefaultMCPToolHandler:
         return MCPToolResult(outputs=[Content.from_text(json.dumps(payload, indent=2, allow_nan=False))])
 
     async def aclose(self) -> None:
-        """Close all cached MCP clients and the owned httpx clients.
+        """Close cached clients and wait for provider-backed invocations to clean up.
 
         Caller-supplied :class:`httpx.AsyncClient` instances (returned by the
         ``client_provider`` callback) are NOT closed.
 
-        Idempotent — a second call returns immediately. Drains any in-flight
-        ``_create_entry`` tasks before returning so their resources are
+        Provider-backed calls already executing may finish; pending connections
+        are rejected after connecting and cleaned up by their invocation.
+        Concurrent shutdown calls wait for those invocations as well.
+
+        Idempotent. In no-provider mode, a second call returns immediately.
+        Drains any in-flight ``_create_entry`` tasks before returning so their resources are
         cleaned up; the in-flight tasks see ``self._closed`` in phase 3 of
         :meth:`_get_or_create_entry`, close their own entry, and resolve
         their future with ``RuntimeError("DefaultMCPToolHandler is closed")``.
+
+        Raises:
+            RuntimeError: If called from an active provider-backed invocation's
+                context, including inherited child tasks and cleanup. Rejected
+                before changing handler state to avoid waiting on itself.
         """
+        if any(not completion.done() for completion in self._invocation_context.get()):
+            raise RuntimeError(
+                "DefaultMCPToolHandler.aclose() cannot be called from an active provider-backed invocation"
+            )
         async with self._cache_lock:
-            if self._closed:
+            if self._closed and self._client_provider is None:
                 return
             self._closed = True
             entries = list(self._cache.values())
             self._cache.clear()
             inflight_futures = list(self._inflight.values())
+            active_invocations = list(self._active_invocations)
+
+        for completion in active_invocations:
+            # Cancelling shutdown must not cancel an invocation's completion signal.
+            await asyncio.shield(completion)
 
         # Wait for in-flight creations to finish their self-cleanup. Each
         # in-flight task self-closes its entry under the closed-flag branch
@@ -509,7 +574,9 @@ class DefaultMCPToolHandler:
         provided_client: httpx.AsyncClient | None = None
         if self._client_provider is not None:
             provided_client = await self._client_provider(invocation)
-        # Capture headers for this cache entry so the header_provider closure
+            if self._closed:
+                raise RuntimeError("DefaultMCPToolHandler is closed")
+        # Capture headers for this entry so the header_provider closure
         # always returns the same set, regardless of the runtime kwargs.
         captured_headers = dict(invocation.headers)
 
@@ -526,10 +593,18 @@ class DefaultMCPToolHandler:
         try:
             await tool.connect()
         except BaseException:
-            try:
-                await tool.close()
-            except Exception:  # pragma: no cover - best effort
-                logger.debug("DefaultMCPToolHandler: error closing tool after failed connect", exc_info=True)
+            failed_entry = _CacheEntry(
+                tool=tool,
+                owned_httpx_client=(
+                    cast("httpx.AsyncClient | None", getattr(tool, "_httpx_client", None))
+                    if provided_client is None
+                    else None
+                ),
+            )
+            if self._client_provider is not None:
+                await self._close_invocation_entry(failed_entry)
+            else:
+                await self._close_entry(failed_entry)
             raise
 
         # ``MCPStreamableHTTPTool.get_mcp_client`` lazily creates an
@@ -542,17 +617,34 @@ class DefaultMCPToolHandler:
             owned_client = cast("httpx.AsyncClient | None", getattr(tool, "_httpx_client", None))
         return _CacheEntry(tool=tool, owned_httpx_client=owned_client)
 
+    async def _close_invocation_entry(self, entry: _CacheEntry) -> None:
+        """Finish invocation cleanup even if the caller is cancelled again."""
+        # MCPStreamableHTTPTool dispatches connect/close to its lifecycle owner,
+        # keeping the SDK's cancel-scope entry and exit on that same task.
+        cleanup = asyncio.create_task(self._close_entry(entry))
+        cancelled = False
+        while not cleanup.done():
+            try:
+                await asyncio.shield(cleanup)
+            except asyncio.CancelledError:
+                cancelled = True
+        cleanup.result()  # Propagate cancellation/errors from cleanup itself.
+        if cancelled:
+            raise asyncio.CancelledError
+
     async def _close_entry(self, entry: _CacheEntry) -> None:
         """Close the MCP tool and any owned httpx client."""
         try:
-            await entry.tool.close()
-        except Exception:  # pragma: no cover - best effort
-            logger.debug("DefaultMCPToolHandler: error closing MCP tool", exc_info=True)
-        if entry.owned_httpx_client is not None:
             try:
-                await entry.owned_httpx_client.aclose()
+                await entry.tool.close()
             except Exception:  # pragma: no cover - best effort
-                logger.debug("DefaultMCPToolHandler: error closing owned httpx client", exc_info=True)
+                logger.debug("DefaultMCPToolHandler: error closing MCP tool", exc_info=True)
+        finally:
+            if entry.owned_httpx_client is not None and not entry.owned_httpx_client.is_closed:
+                try:
+                    await entry.owned_httpx_client.aclose()
+                except Exception:  # pragma: no cover - best effort
+                    logger.debug("DefaultMCPToolHandler: error closing owned httpx client", exc_info=True)
 
     @staticmethod
     def _cache_key(
@@ -563,10 +655,9 @@ class DefaultMCPToolHandler:
     ) -> tuple[str, str, str, str]:
         """Build an order-independent cache key for the invocation identity.
 
-        The key includes ``server_label`` and ``connection_name`` so that
-        callers using ``client_provider`` to dispatch on those fields
-        receive a fresh client per logical connection (matches the
-        documented dispatch contract).
+        Used only without a ``client_provider``. The key includes
+        ``server_label`` and ``connection_name`` to distinguish logical
+        connections.
 
         Header *names* are lower-cased inside the hash payload only so
         that ``Authorization`` and ``authorization`` map to the same

{agent_framework_declarative-1.0.4 → agent_framework_declarative-1.1.0}/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.0.4"
+version = "1.1.0"
 license-files = ["LICENSE"]
 urls.homepage = "https://aka.ms/agent-framework"
 urls.source = "https://github.com/microsoft/agent-framework/tree/main/python"
@@ -22,14 +22,14 @@ classifiers = [
   "Typing :: Typed",
 ]
 dependencies = [
-    "agent-framework-core>=1.15.0,<2",
+    "agent-framework-core>=1.19.0,<2",
     "httpx>=0.27,<1",
     "powerfx>=0.0.32,<0.0.35; python_version < '3.14'",
     "pyyaml>=6.0,<7.0",
 ]
 [dependency-groups]
 dev = [
-    "types-PyYaml==6.0.12.20260518"
+    "types-PyYaml==6.0.12.20260906"
 ]
 
 [tool.uv]

agent_framework_declarative-1.0.4/PKG-INFO

@@ -1,49 +0,0 @@
-Metadata-Version: 2.4
-Name: agent-framework-declarative
-Version: 1.0.4
-Summary: Declarative specification support for Microsoft Agent Framework.
-Author-email: Microsoft <af-support@microsoft.com>
-Requires-Python: >=3.10
-Description-Content-Type: text/markdown
-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.15.0,<2
-Requires-Dist: httpx>=0.27,<1
-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
-Project-URL: issues, https://github.com/microsoft/agent-framework/issues
-Project-URL: release_notes, https://github.com/microsoft/agent-framework/releases?q=tag%3Apython-1&expanded=true
-Project-URL: source, https://github.com/microsoft/agent-framework/tree/main/python
-
-# Get Started with Microsoft Agent Framework Declarative
-
-Please install this package via pip:
-
-```bash
-pip install agent-framework-declarative
-```
-
-## Release stage
-
-This package ships at two different stability levels:
-
-- **Declarative workflows** (`WorkflowFactory`, executors, handlers, and the
-  `_workflows` surface) are **stable**.
-- **Declarative agents** (`AgentFactory` and the YAML agent loading/parsing path:
-  `DeclarativeLoaderError`, `ProviderLookupError`, `ProviderTypeMapping`) are
-  **experimental** and may change or be removed in future versions without notice.
-  Using any of these symbols emits an `ExperimentalWarning` on first use.
-
-## Declarative features
-
-The declarative packages provides support for building agents based on a declarative yaml specification.
-

agent_framework_declarative-1.0.4/README.md

@@ -1,22 +0,0 @@
-# Get Started with Microsoft Agent Framework Declarative
-
-Please install this package via pip:
-
-```bash
-pip install agent-framework-declarative
-```
-
-## Release stage
-
-This package ships at two different stability levels:
-
-- **Declarative workflows** (`WorkflowFactory`, executors, handlers, and the
-  `_workflows` surface) are **stable**.
-- **Declarative agents** (`AgentFactory` and the YAML agent loading/parsing path:
-  `DeclarativeLoaderError`, `ProviderLookupError`, `ProviderTypeMapping`) are
-  **experimental** and may change or be removed in future versions without notice.
-  Using any of these symbols emits an `ExperimentalWarning` on first use.
-
-## Declarative features
-
-The declarative packages provides support for building agents based on a declarative yaml specification.