agent-framework-core 1.15.0__tar.gz → 1.16.0__tar.gz

{agent_framework_core-1.15.0 → agent_framework_core-1.16.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-framework-core
-Version: 1.15.0
+Version: 1.16.0
 Summary: Microsoft Agent Framework for building AI Agents with Python. This is the core package that has all the core abstractions and implementations.
 Author-email: Microsoft <af-support@microsoft.com>
 Requires-Python: >=3.10

{agent_framework_core-1.15.0 → agent_framework_core-1.16.0}/agent_framework/_agents.py

@@ -1512,6 +1512,9 @@ class RawAgent(BaseAgent, Generic[OptionsCoT]):
         # _merge_options strips unset (None) options, so e.g. an unset `store` is not forwarded
         # and the service decides its own default.
         co = _merge_options(chat_options, run_opts)
+        # The loop marker must remain on SessionContext.options for after_run provider
+        # scoping, but it is framework-private metadata and must not reach the client.
+        co.pop(_LOOP_ITERATION_TOKEN_KEY, None)
 
         # Build session_messages from session context: context messages + input messages
         session_messages: list[Message] = session_context.get_messages(include_input=True)

{agent_framework_core-1.15.0 → agent_framework_core-1.16.0}/agent_framework/_harness/_agent.py

@@ -24,7 +24,7 @@ from .._sessions import ContextProvider, HistoryProvider, InMemoryHistoryProvide
 from .._skills import SkillsProvider
 from .._telemetry import FeatureIndex, mark_feature_used
 from .._types import ChatOptions
-from ._background_agents import BackgroundAgentsProvider
+from ._background_agents import DEFAULT_BACKGROUND_AGENTS_WAIT_TIMEOUT_SECONDS, BackgroundAgentsProvider
 from ._file_access import AgentFileStore, FileAccessProvider, FileSystemAgentFileStore
 from ._file_memory import FileMemoryProvider
 from ._loop import DEFAULT_MAX_ITERATIONS, AgentLoopMiddleware
@@ -160,6 +160,7 @@ def _assemble_context_providers(
     skills_paths: str | Path | Sequence[str | Path] | None,
     background_agents: Sequence[SupportsAgentRun] | None,
     background_agents_instructions: str | None,
+    background_agents_wait_timeout_seconds: int,
     shell_context_provider: ContextProvider | None,
     extra_context_providers: Sequence[ContextProvider] | None,
 ) -> list[ContextProvider]:
@@ -205,7 +206,13 @@ def _assemble_context_providers(
 
     # Background agents are opt-in: only added when agents are provided.
     if background_agents:
-        providers.append(BackgroundAgentsProvider(background_agents, instructions=background_agents_instructions))
+        providers.append(
+            BackgroundAgentsProvider(
+                background_agents,
+                instructions=background_agents_instructions,
+                wait_timeout_seconds=background_agents_wait_timeout_seconds,
+            )
+        )
 
     # Shell environment provider is opt-in: only added when a shell tool was wired.
     if shell_context_provider is not None:
@@ -329,6 +336,7 @@ def create_harness_agent(
     skills_paths: str | Path | Sequence[str | Path] | None = None,
     background_agents: Sequence[SupportsAgentRun] | None = None,
     background_agents_instructions: str | None = None,
+    background_agents_wait_timeout_seconds: int = DEFAULT_BACKGROUND_AGENTS_WAIT_TIMEOUT_SECONDS,
     shell_executor: ShellExecutor | None = None,
     shell_environment_provider_options: ShellEnvironmentProviderOptions | None = None,
     disable_web_search: bool = False,
@@ -478,6 +486,10 @@ def create_harness_agent(
         background_agents_instructions: Optional instruction override for the
             ``BackgroundAgentsProvider``. May include ``{background_agents}`` placeholder
             which will be replaced with the agent listing.
+        background_agents_wait_timeout_seconds: Maximum seconds the background-agent wait
+            tool blocks for a task to complete. Must be a positive integer.
+            Defaults to 300 seconds. On expiry, the tool returns normally and leaves the
+            background tasks running. Only used when ``background_agents`` is provided.
         shell_executor: Optional shell tool that enables shell command execution. When
             provided, the shell tool and a ``ShellEnvironmentProvider`` are automatically
             added (provided the client supports shell tools; otherwise a warning is logged
@@ -525,7 +537,8 @@ def create_harness_agent(
     Raises:
         ValueError: If max_context_window_tokens is provided and <= 0, or
             max_output_tokens is provided and <= 0, or max_output_tokens >=
-            max_context_window_tokens when both are provided.
+            max_context_window_tokens when both are provided, or
+            background_agents_wait_timeout_seconds is invalid when background agents are provided.
     """
     if max_context_window_tokens is not None and max_context_window_tokens <= 0:
         raise ValueError("max_context_window_tokens must be positive.")
@@ -601,6 +614,7 @@ def create_harness_agent(
         skills_paths=skills_paths,
         background_agents=background_agents,
         background_agents_instructions=background_agents_instructions,
+        background_agents_wait_timeout_seconds=background_agents_wait_timeout_seconds,
         shell_context_provider=shell_provider,
         extra_context_providers=context_providers,
     )

{agent_framework_core-1.15.0 → agent_framework_core-1.16.0}/agent_framework/_harness/_agent.pyi

@@ -14,6 +14,7 @@ from .._sessions import ContextProvider, HistoryProvider
 from .._skills import SkillsProvider
 from .._tools import ToolTypes
 from .._types import ChatOptions
+from ._background_agents import DEFAULT_BACKGROUND_AGENTS_WAIT_TIMEOUT_SECONDS
 from ._file_access import AgentFileStore
 from ._loop import DEFAULT_MAX_ITERATIONS, NextMessageCallable, ShouldContinueCallable
 from ._mode import AgentModeProvider
@@ -77,6 +78,7 @@ def create_harness_agent(
     skills_paths: str | Path | Sequence[str | Path] | None = None,
     background_agents: Sequence[SupportsAgentRun] | None = None,
     background_agents_instructions: str | None = None,
+    background_agents_wait_timeout_seconds: int = DEFAULT_BACKGROUND_AGENTS_WAIT_TIMEOUT_SECONDS,
     shell_executor: _ShellExecutorLike | None = None,
     shell_environment_provider_options: _ShellEnvironmentProviderOptionsLike | None = None,
     disable_web_search: bool = False,

{agent_framework_core-1.15.0 → agent_framework_core-1.16.0}/agent_framework/_harness/_background_agents.py

@@ -27,6 +27,7 @@ from .._types import AgentResponse, Message
 logger = logging.getLogger(__name__)
 
 DEFAULT_BACKGROUND_AGENTS_SOURCE_ID = "background_agents"
+DEFAULT_BACKGROUND_AGENTS_WAIT_TIMEOUT_SECONDS = 300
 
 DEFAULT_BACKGROUND_AGENTS_INSTRUCTIONS = """\
 ## Background Agents
@@ -275,7 +276,8 @@ class BackgroundAgentsProvider(ContextProvider):
     This provider exposes the following tools to the agent:
 
     - ``background_agents_start_task`` — Start a background task on a named agent with text input.
-    - ``background_agents_wait_for_first_completion`` — Block until the first of the specified tasks completes.
+    - ``background_agents_wait_for_first_completion`` — Wait until the first specified task completes or the
+      configured timeout expires. A timeout leaves the tasks running so the tool can be called again.
     - ``background_agents_get_task_results`` — Retrieve the text output of a completed background task.
     - ``background_agents_get_all_tasks`` — List all background tasks with their IDs, statuses, and descriptions.
     - ``background_agents_continue_task`` — Send follow-up input to a completed task's session to resume work.
@@ -297,6 +299,7 @@ class BackgroundAgentsProvider(ContextProvider):
         *,
         source_id: str = DEFAULT_BACKGROUND_AGENTS_SOURCE_ID,
         instructions: str | None = None,
+        wait_timeout_seconds: int = DEFAULT_BACKGROUND_AGENTS_WAIT_TIMEOUT_SECONDS,
     ) -> None:
         """Initialize the background agents provider.
 
@@ -312,13 +315,23 @@ class BackgroundAgentsProvider(ContextProvider):
             source_id: Unique source ID for serializable task state in session.
             instructions: Optional instruction override. May include ``{background_agents}``
                 placeholder which will be replaced with the agent listing.
+            wait_timeout_seconds: Maximum seconds the wait tool blocks for a task to complete.
+                Must be a positive integer. Defaults to 300 seconds.
 
         Raises:
-            ValueError: If agents is empty, an agent has no name, or names are not unique.
+            ValueError: If agents is empty, an agent has no name, names are not unique, or
+                wait_timeout_seconds is not a positive integer.
         """
         super().__init__(source_id)
 
         self._agents = _validate_and_build_agent_dict(agents)
+        if (
+            isinstance(wait_timeout_seconds, bool)
+            or not isinstance(wait_timeout_seconds, int)
+            or wait_timeout_seconds <= 0
+        ):
+            raise ValueError("wait_timeout_seconds must be a positive integer.")
+        self._wait_timeout_seconds = wait_timeout_seconds
 
         # Build instructions with agent listing.
         base_instructions = instructions if instructions is not None else DEFAULT_BACKGROUND_AGENTS_INSTRUCTIONS
@@ -502,7 +515,11 @@ class BackgroundAgentsProvider(ContextProvider):
 
         @tool(name="background_agents_wait_for_first_completion", approval_mode="never_require")
         async def background_agents_wait_for_first_completion(task_ids: list[int]) -> str:
-            """Block until the first of the specified background tasks completes. Returns the completed task's ID."""
+            """Wait until the first of the specified tasks completes or the configured timeout expires.
+
+            Returns the completed task's ID. On timeout, the tasks remain running and this tool
+            can be called again to continue waiting.
+            """
             if runtime.closed:
                 return "Error: Session is being released; cannot wait for background tasks."
 
@@ -531,8 +548,14 @@ class BackgroundAgentsProvider(ContextProvider):
             # Wait for the first one to complete.
             done, _ = await asyncio.wait(
                 [t for _, t in waitable],
+                timeout=self._wait_timeout_seconds,
                 return_when=asyncio.FIRST_COMPLETED,
             )
+            if not done:
+                return (
+                    f"No background task completed within {self._wait_timeout_seconds} seconds. "
+                    "The tasks are still running; call this tool again if you wish to continue waiting."
+                )
 
             # Find which ID completed.
             completed_id: int | None = None

{agent_framework_core-1.15.0 → agent_framework_core-1.16.0}/agent_framework/_harness/_loop.py

@@ -34,7 +34,9 @@ from typing import TYPE_CHECKING, Any, TypeAlias
 from pydantic import BaseModel, Field
 from typing_extensions import Self
 
-from .._agents import _LOOP_ITERATION_TOKEN_KEY  # pyright: ignore[reportPrivateUsage] -- shared loop-turn marker, see _agents.py
+from .._agents import (
+    _LOOP_ITERATION_TOKEN_KEY,  # pyright: ignore[reportPrivateUsage] -- shared loop-turn marker, see _agents.py
+)
 from .._feature_stage import ExperimentalFeature, experimental
 from .._middleware import AgentContext, AgentMiddleware, MiddlewareTermination
 from .._sessions import SessionContext
@@ -490,8 +492,7 @@ class AgentLoopMiddleware(AgentMiddleware):
         if response is None or run_after is None:
             return
         if not any(
-            getattr(provider, "after_run_once_per_turn", False)
-            for provider in getattr(agent, "context_providers", [])
+            getattr(provider, "after_run_once_per_turn", False) for provider in getattr(agent, "context_providers", [])
         ):
             return
         session_context = SessionContext(

{agent_framework_core-1.15.0 → agent_framework_core-1.16.0}/agent_framework/_serialization.py

@@ -569,7 +569,7 @@ class SerializationMixin:
                             and param_name in kwargs
                             and isinstance(kwargs[param_name], dict)
                         ):
-                            kwargs[param_name].update(param_value)
+                            kwargs[param_name] = {**kwargs[param_name], **param_value}
                         else:
                             kwargs[param_name] = param_value
             else:
@@ -581,7 +581,7 @@ class SerializationMixin:
                     )
                 # Handle dict parameters - merge if both are dicts
                 if isinstance(dep_value, dict) and dep_key in kwargs and isinstance(kwargs[dep_key], dict):
-                    kwargs[dep_key].update(dep_value)
+                    kwargs[dep_key] = {**kwargs[dep_key], **dep_value}
                 else:
                     kwargs[dep_key] = dep_value
 

{agent_framework_core-1.15.0 → agent_framework_core-1.16.0}/agent_framework/_types.py

@@ -589,10 +589,10 @@ class Content:
         self.consent_link = consent_link
 
     def __deepcopy__(self, memo: dict[int, Any]) -> Content:
-        """Create a deep copy, preserving ``_SHALLOW_COPY_FIELDS`` by reference.
+        """Create a deep copy, discarding non-``None`` ``_SHALLOW_COPY_FIELDS``.
 
         Fields listed in ``_SHALLOW_COPY_FIELDS`` may contain LLM SDK objects
-        (e.g., proto/gRPC responses) that are not safe to deep-copy.
+        (e.g., proto/gRPC responses) that are not safe to deep-copy or share.
         """
         cls = type(self)
         result = cls.__new__(cls)
@@ -600,7 +600,9 @@ class Content:
         shallow = cls._SHALLOW_COPY_FIELDS
         for k, v in self.__dict__.items():
             if k in shallow:
-                object.__setattr__(result, k, v)
+                if v is not None:
+                    logger.debug("Discarding field '%s' while deep-copying Content.", k)
+                object.__setattr__(result, k, None)
             else:
                 object.__setattr__(result, k, deepcopy(v, memo))
         return result

{agent_framework_core-1.15.0 → agent_framework_core-1.16.0}/agent_framework/_workflows/_agent.py

@@ -713,11 +713,7 @@ class WorkflowAgent(BaseAgent):
         Note:
             Text requests use the function-call envelope so callers can reply with a matching function result.
         """
-        if (
-            isinstance(event.data, Content)
-            and event.data.user_input_request
-            and event.data.type != "text"
-        ):
+        if isinstance(event.data, Content) and event.data.user_input_request and event.data.type != "text":
             # Preserve specialized requests that callers already understand how to present.
             return event.data
 

{agent_framework_core-1.15.0 → agent_framework_core-1.16.0}/agent_framework/_workflows/_checkpoint.py

@@ -130,7 +130,7 @@ class CheckpointStorage(Protocol):
     """Protocol for checkpoint storage backends."""
 
     async def save(self, checkpoint: WorkflowCheckpoint) -> CheckpointID:
-        """Save a checkpoint and return its ID.
+        """Create a copy of the given checkpoint and store it, returning its ID.
 
         Args:
             checkpoint: The WorkflowCheckpoint object to save.
@@ -147,7 +147,7 @@ class CheckpointStorage(Protocol):
             checkpoint_id: The unique ID of the checkpoint to load.
 
         Returns:
-            The WorkflowCheckpoint object corresponding to the given ID.
+            A copy of the WorkflowCheckpoint object corresponding to the given ID.
 
         Raises:
             WorkflowCheckpointException: If no checkpoint with the given ID exists.
@@ -161,7 +161,7 @@ class CheckpointStorage(Protocol):
             workflow_name: The name of the workflow to list checkpoints for.
 
         Returns:
-            A list of WorkflowCheckpoint objects for the specified workflow name.
+            A list of copies of WorkflowCheckpoint objects for the specified workflow name.
         """
         ...
 
@@ -183,7 +183,8 @@ class CheckpointStorage(Protocol):
             workflow_name: The name of the workflow to get the latest checkpoint for.
 
         Returns:
-            The latest WorkflowCheckpoint object for the specified workflow name, or None if no checkpoints exist.
+            A copy of the latest WorkflowCheckpoint object for the specified workflow name,
+            or None if no checkpoints exist.
         """
         ...
 
@@ -207,7 +208,7 @@ class InMemoryCheckpointStorage:
         self._checkpoints: dict[CheckpointID, WorkflowCheckpoint] = {}
 
     async def save(self, checkpoint: WorkflowCheckpoint) -> CheckpointID:
-        """Save a checkpoint and return its ID."""
+        """Create a copy of the given checkpoint and store it, returning its ID."""
         self._checkpoints[checkpoint.checkpoint_id] = copy.deepcopy(checkpoint)
         logger.debug(f"Saved checkpoint {checkpoint.checkpoint_id} to memory")
         return checkpoint.checkpoint_id
@@ -217,12 +218,12 @@ class InMemoryCheckpointStorage:
         checkpoint = self._checkpoints.get(checkpoint_id)
         if checkpoint:
             logger.debug(f"Loaded checkpoint {checkpoint_id} from memory")
-            return checkpoint
+            return copy.deepcopy(checkpoint)
         raise WorkflowCheckpointException(f"No checkpoint found with ID {checkpoint_id}")
 
     async def list_checkpoints(self, *, workflow_name: str) -> list[WorkflowCheckpoint]:
         """List checkpoint objects for a given workflow name."""
-        return [cp for cp in self._checkpoints.values() if cp.workflow_name == workflow_name]
+        return [copy.deepcopy(cp) for cp in self._checkpoints.values() if cp.workflow_name == workflow_name]
 
     async def delete(self, checkpoint_id: CheckpointID) -> bool:
         """Delete a checkpoint by ID."""
@@ -239,7 +240,7 @@ class InMemoryCheckpointStorage:
             return None
         latest_checkpoint = max(checkpoints, key=lambda cp: datetime.fromisoformat(cp.timestamp))
         logger.debug(f"Latest checkpoint for workflow {workflow_name} is {latest_checkpoint.checkpoint_id}")
-        return latest_checkpoint
+        return copy.deepcopy(latest_checkpoint)
 
     async def list_checkpoint_ids(self, *, workflow_name: str) -> list[CheckpointID]:
         """List checkpoint IDs. If workflow_id is provided, filter by that workflow."""

{agent_framework_core-1.15.0 → agent_framework_core-1.16.0}/agent_framework/_workflows/_state.py

@@ -1,5 +1,6 @@
 # Copyright (c) Microsoft. All rights reserved.
 
+import copy
 from typing import Any
 
 
@@ -31,7 +32,8 @@ class State:
         """Set a value in the pending state buffer.
 
         The value will be visible to subsequent `get()` calls but won't be
-        committed to the actual state until `commit()` is called.
+        committed to the actual state until `commit()` is called. A deep copy is
+        stored so later caller mutations do not change pending state.
 
         Note:
             When multiple executors run concurrently within the same superstep,
@@ -40,7 +42,7 @@ class State:
             the .NET behavior and the superstep execution model where all executors
             in a superstep see the same committed state at the start.
         """
-        self._pending[key] = value
+        self._pending[key] = copy.deepcopy(value)
 
     def get(self, key: str, default: Any = None) -> Any:
         """Get a value from state, checking pending first then committed.
@@ -50,14 +52,17 @@ class State:
             default: Value to return if key is not found. Defaults to None.
 
         Returns:
-            The value if found, otherwise the default value.
+            A deep copy of the value if found, otherwise the default value. Mutate
+            the returned value and pass it to :meth:`set` to update workflow state.
         """
         if key in self._pending:
             value = self._pending[key]
             if value is _DeleteSentinel:
                 return default
-            return value
-        return self._committed.get(key, default)
+            return copy.deepcopy(value)
+        if key in self._committed:
+            return copy.deepcopy(self._committed[key])
+        return default
 
     def has(self, key: str) -> bool:
         """Check if a key exists in pending or committed state."""
@@ -104,18 +109,20 @@ class State:
         self._pending.clear()
 
     def export_state(self) -> dict[str, Any]:
-        """Export a serialized copy of the committed state.
+        """Export a deepcopy of the committed state.
 
-        Note: Does not include pending changes.
+        Note:
+            Does not include pending changes. Values must support :func:`copy.deepcopy`.
         """
-        return dict(self._committed)
+        return copy.deepcopy(self._committed)
 
     def import_state(self, state: dict[str, Any]) -> None:
         """Import state from a serialized dictionary.
 
-        Merges into committed state. Does not affect pending changes.
+        Merges a deepcopy into committed state. Does not affect pending changes.
+        Values must support :func:`copy.deepcopy`.
         """
-        self._committed.update(state)
+        self._committed.update(copy.deepcopy(state))
 
 
 class _DeleteSentinelType: