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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-framework-core
-Version: 1.14.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.14.0 → agent_framework_core-1.16.0}/agent_framework/__init__.py

@@ -185,6 +185,7 @@ _LAZY_MODULE_EXPORTS: Final[Mapping[str, tuple[str, ...]]] = {
         "FunctionMiddleware",
         "FunctionMiddlewareTypes",
         "MiddlewareBundle",
+        "MiddlewareFailure",
         "MiddlewareTermination",
         "MiddlewareType",
         "MiddlewareTypes",
@@ -293,6 +294,7 @@ _LAZY_MODULE_EXPORTS: Final[Mapping[str, tuple[str, ...]]] = {
         "InMemoryCheckpointStorage",
         "WorkflowCheckpoint",
     ),
+    "._workflows._checkpoint_encoding": ("register_checkpoint_type",),
     "._workflows._const": (
         "DEFAULT_MAX_ITERATIONS",
         "INTERNAL_SOURCE_ID",
@@ -509,6 +511,7 @@ __all__ = [
     "MessageInjectionMiddleware",
     "MiddlewareBundle",
     "MiddlewareException",
+    "MiddlewareFailure",
     "MiddlewareTermination",
     "MiddlewareType",
     "MiddlewareTypes",
@@ -631,6 +634,7 @@ __all__ = [
     "normalize_tools",
     "prepend_agent_framework_to_user_agent",
     "prepend_instructions_to_messages",
+    "register_checkpoint_type",
     "register_state_type",
     "resolve_agent_id",
     "response_handler",

{agent_framework_core-1.14.0 → agent_framework_core-1.16.0}/agent_framework/__init__.pyi

@@ -144,6 +144,7 @@ from ._middleware import (
     FunctionMiddleware,
     FunctionMiddlewareTypes,
     MiddlewareBundle,
+    MiddlewareFailure,
     MiddlewareTermination,
     MiddlewareType,
     MiddlewareTypes,
@@ -259,6 +260,7 @@ from ._workflows._checkpoint import (
     InMemoryCheckpointStorage,
     WorkflowCheckpoint,
 )
+from ._workflows._checkpoint_encoding import register_checkpoint_type
 from ._workflows._const import DEFAULT_MAX_ITERATIONS, INTERNAL_SOURCE_ID
 from ._workflows._edge import (
     Case,
@@ -473,6 +475,7 @@ __all__ = [
     "MessageInjectionMiddleware",
     "MiddlewareBundle",
     "MiddlewareException",
+    "MiddlewareFailure",
     "MiddlewareTermination",
     "MiddlewareType",
     "MiddlewareTypes",
@@ -595,6 +598,7 @@ __all__ = [
     "normalize_tools",
     "prepend_agent_framework_to_user_agent",
     "prepend_instructions_to_messages",
+    "register_checkpoint_type",
     "register_state_type",
     "resolve_agent_id",
     "response_handler",

{agent_framework_core-1.14.0 → agent_framework_core-1.16.0}/agent_framework/_agent_hooks.py

@@ -37,7 +37,13 @@ Enforcement semantics (``mode="enforce"``):
   not executed (or its result is discarded) and a tool-error payload is surfaced to the
   model so the agent loop can continue, per the spec's block-propagation rules. A
   ``host_error:*`` deny at the tool seam additionally halts the run (the enforcement
-  layer itself failed, so continuing would be unreliable).
+  layer itself failed, so continuing would be unreliable): the run is aborted through
+  the function-invocation loop's fail-closed escape
+  (:class:`~agent_framework.MiddlewareFailure`) and the
+  :class:`agent_hooks.InterceptionBlocked` propagates to the caller, exactly like a
+  run-level deny. Other unexpected failures inside the enforcement layer (projection
+  bug, emitter fault) abort the run the same way and surface as
+  :class:`~agent_framework.MiddlewareFailure`.
 - Framework middleware short-circuits (``MiddlewareTermination``) are guarded: a result
   substituted by another middleware still passes ``output`` / ``post_model_call`` /
   ``post_tool_call`` before it egresses or enters the transcript.
@@ -113,6 +119,7 @@ from ._middleware import (
     FunctionInvocationContext,
     FunctionMiddleware,
     MiddlewareBundle,
+    MiddlewareFailure,
     MiddlewareTermination,
 )
 from ._serialization import make_json_safe
@@ -231,7 +238,6 @@ class _RunState:
     builder: AgentContextBuilder
     session_scoped: bool
     config: _AgentHooksConfig
-    halted: BaseException | None = None
 
 
 _RUN_STATE: ContextVar[_RunState | None] = ContextVar("agent_framework_agent_hooks_run_state", default=None)
@@ -895,27 +901,63 @@ def _is_approval_request(result: Any) -> bool:
     return isinstance(result, Content) and result.type == "function_approval_request"
 
 
-def _halt_on_enforcement_failure(
-    state: _RunState, context: FunctionInvocationContext, exc: BaseException, point: str
-) -> NoReturn:
-    """Route an unexpected failure inside the enforcement layer through the fail-closed halt path.
+def _halt_on_enforcement_failure(exc: BaseException, point: str) -> NoReturn:
+    """Abort the run fail-closed on an unexpected failure inside the enforcement layer.
 
     The function-invocation loop converts arbitrary exceptions raised by function
     middleware into tool-error results and keeps running; for a failure of the
     enforcement layer itself (projection bug, emitter fault) that would fail open —
     the failure would vanish from the audit trail and the run would continue unguarded.
-    Instead the loop is stopped via ``MiddlewareTermination`` (its only loud escape) and
-    the agent middleware re-raises the failure to the caller at the run boundary.
+    :class:`MiddlewareFailure` is the loop's explicit fail-closed escape: it propagates
+    to the caller at the run boundary, with the underlying failure chained as its cause.
     """
-    message = f"agent-hooks {point} enforcement failed: {type(exc).__name__}"
-    context.result = {"error": message}
     if isinstance(exc, MiddlewareException):
-        failure: BaseException = exc
-    else:
-        failure = MiddlewareException(message)
-        failure.__cause__ = exc
-    state.halted = failure
-    raise MiddlewareTermination(message) from exc
+        raise MiddlewareFailure(str(exc)) from exc
+    raise MiddlewareFailure(f"agent-hooks {point} enforcement failed: {type(exc).__name__}") from exc
+
+
+class _ToolSeamBlockFailure(MiddlewareFailure):
+    """Private tag for this feature's own tool-seam ``host_error`` halts.
+
+    Only failures raised by :meth:`_AgentHooksFunctionMiddleware._maybe_halt` carry
+    this type, which is what authorizes :func:`_reraise_tool_seam_block` to unwrap
+    the chained :class:`agent_hooks.InterceptionBlocked` at the run boundary. A plain
+    ``MiddlewareFailure`` raised by third-party middleware is never unwrapped — even
+    when its ``__cause__`` happens to be an ``InterceptionBlocked`` — so untrusted
+    code cannot launder a crafted interception record into this feature's deny
+    surface.
+    """
+
+
+def _reraise_tool_seam_block(failure: MiddlewareFailure) -> NoReturn:
+    """Surface a tool-seam ``host_error`` block as the block itself at the run boundary.
+
+    The tool seam sits behind the function-invocation loop, so its fail-closed halts
+    travel as :class:`MiddlewareFailure` (the loop's loud escape) with the triggering
+    exception chained as the cause. When the failure is this feature's own tagged
+    :class:`_ToolSeamBlockFailure`, re-raise its :class:`agent_hooks.InterceptionBlocked`
+    cause so callers see the same deny surface — ``InterceptionBlocked`` carrying the
+    interception record — at every seam (run-, model-, and tool-level). Any other
+    failure (including a third-party ``MiddlewareFailure`` with a crafted
+    ``InterceptionBlocked`` cause) propagates exactly as raised.
+    """
+    from agent_hooks import InterceptionBlocked
+
+    block = failure.__cause__
+    if isinstance(failure, _ToolSeamBlockFailure) and isinstance(block, InterceptionBlocked):
+        # Detach the transport wrapper's back-links (both were set to the block when
+        # _maybe_halt raised the wrapper from it) before re-raising: re-raising the
+        # block while they are intact would make the two exceptions each other's
+        # cause/context — a chain cycle that every consumer walking
+        # __cause__/__context__ would have to guard against. The bare raise below
+        # records the wrapper as the block's __context__ instead (truthful: the block
+        # is re-raised while the wrapper is being handled), keeping both exceptions
+        # visible in tracebacks, acyclically.
+        failure.__cause__ = None
+        if failure.__context__ is block:
+            failure.__context__ = None
+        raise block
+    raise failure
 
 
 # endregion
@@ -1025,8 +1067,6 @@ class _AgentHooksAgentMiddleware(_AgentHooksMiddlewareBase, AgentMiddleware):
                         # A middleware short-circuited the run; any substituted result
                         # still egresses to the caller, so it passes the output point.
                         termination = exc
-                if state.halted is not None:
-                    raise state.halted
                 result = context.result
                 if isinstance(result, AgentResponse):
                     await self._emit_output(state, result)
@@ -1046,6 +1086,14 @@ class _AgentHooksAgentMiddleware(_AgentHooksMiddlewareBase, AgentMiddleware):
                 shutdown_reason = "error"
                 context.result = None
                 raise
+            except MiddlewareFailure as failure:
+                # A fail-closed abort from behind the function-invocation loop: the
+                # gated persistence is dropped and, for a tool-seam host_error block,
+                # the block itself is surfaced (one deny surface at every seam).
+                gate.drop()
+                shutdown_reason = "error"
+                context.result = None
+                _reraise_tool_seam_block(failure)
             except asyncio.CancelledError:
                 shutdown_reason = "cancelled"
                 raise
@@ -1093,10 +1141,6 @@ class _AgentHooksAgentMiddleware(_AgentHooksMiddlewareBase, AgentMiddleware):
                     termination = exc
             inner = context.result
             if inner is None and termination is not None:
-                if state.halted is not None:
-                    # The enforcement layer itself failed: strand the deferred
-                    # persistence (fail-closed) and surface the halt.
-                    raise state.halted
                 # Terminated without a result: nothing will egress, so the no-egress
                 # termination is a permitted outcome. Release the persistence the
                 # drained in-pipeline work deferred — history of model calls that
@@ -1119,6 +1163,12 @@ class _AgentHooksAgentMiddleware(_AgentHooksMiddlewareBase, AgentMiddleware):
                 # A middleware substituted its own stream: it is guarded, and the
                 # termination still short-circuits the rest of the pipeline.
                 raise termination
+        except MiddlewareFailure as failure:
+            # A fail-closed abort during the pipeline descent (e.g. a retry middleware
+            # drained an attempt whose tool seam hit a host_error block): surface the
+            # block itself for tool-seam blocks (one deny surface at every seam). The
+            # deferred persistence is stranded un-flushed — fail-closed.
+            _reraise_tool_seam_block(failure)
         except asyncio.CancelledError:
             shutdown_reason = "cancelled"
             raise
@@ -1151,6 +1201,14 @@ class _AgentHooksAgentMiddleware(_AgentHooksMiddlewareBase, AgentMiddleware):
             except asyncio.CancelledError:
                 await self._emit_shutdown(state, "cancelled")
                 raise
+            except MiddlewareFailure as failure:
+                # A fail-closed abort from behind the function-invocation loop: close
+                # the trail and, for a tool-seam host_error block, surface the block
+                # itself (one deny surface at every seam). The deferred persistence
+                # is dropped — denied content never becomes durable.
+                gate_handle.drop()
+                await self._emit_shutdown(state, "error")
+                _reraise_tool_seam_block(failure)
             except BaseException:
                 await self._emit_shutdown(state, "error")
                 raise
@@ -1164,8 +1222,6 @@ class _AgentHooksAgentMiddleware(_AgentHooksMiddlewareBase, AgentMiddleware):
             from agent_hooks import InterceptionBlocked
 
             try:
-                if state.halted is not None:
-                    raise state.halted
                 if not isinstance(final, AgentResponse):
                     raise MiddlewareException(
                         f"agent-hooks cannot guard a streamed run result of type {type(final).__name__}; "
@@ -1323,21 +1379,20 @@ class _AgentHooksChatMiddleware(_AgentHooksMiddlewareBase, ChatMiddleware):
 class _AgentHooksFunctionMiddleware(_AgentHooksMiddlewareBase, FunctionMiddleware):
     """Tool bracket: ``pre_tool_call`` and ``post_tool_call``."""
 
-    def _block(
-        self, state: _RunState, context: FunctionInvocationContext, exc: InterceptionBlocked, point: str
-    ) -> None:
+    def _block(self, context: FunctionInvocationContext, exc: InterceptionBlocked, point: str) -> None:
         """Enforce a tool-seam deny: surface a tool error and, on host errors, halt the run."""
         context.result = _blocked_tool_result(point, exc.result)
-        self._maybe_halt(state, exc, point)
+        self._maybe_halt(exc, point)
 
-    def _maybe_halt(self, state: _RunState, exc: InterceptionBlocked, point: str) -> None:
+    def _maybe_halt(self, exc: InterceptionBlocked, point: str) -> None:
         record: InterceptionRecord = exc.result
         if _is_host_error(record):
             # The enforcement layer itself failed (interceptor crash/timeout, invalid
-            # context): continuing the loop would run unguarded. Halt the run; the
-            # agent middleware re-raises the block to the caller.
-            state.halted = exc
-            raise MiddlewareTermination(
+            # context): continuing the loop would run unguarded. Abort the run through
+            # the loop's fail-closed escape; the agent middleware re-raises the block
+            # itself to the caller (the private tag is what authorizes the unwrap —
+            # see _reraise_tool_seam_block).
+            raise _ToolSeamBlockFailure(
                 f"agent-hooks {point} failed closed: {record.verdict.reason}",
             ) from exc
 
@@ -1346,21 +1401,15 @@ class _AgentHooksFunctionMiddleware(_AgentHooksMiddlewareBase, FunctionMiddlewar
 
         state = _RUN_STATE.get()
         if state is None:
-            # No run state means the bundle's agent middleware never ran. A plain
-            # exception raised here would be converted into a tool error by the
-            # function-invocation loop and the run would continue unguarded (fail
-            # open); MiddlewareTermination is the only loud escape: the tool is never
-            # dispatched and the loop stops.
-            message = _TRIO_REQUIRED_MESSAGE.format(seam="function")
-            context.result = {"error": message}
-            raise MiddlewareTermination(message)
+            # No run state means the bundle's agent middleware never ran (a partial
+            # install the public API makes impossible). The tool must never be
+            # dispatched: abort the run through the loop's fail-closed escape.
+            raise MiddlewareFailure(_TRIO_REQUIRED_MESSAGE.format(seam="function"))
         if not self._shares_config(state.config):
             # A different bundle owns the innermost run state (stacked bundles):
-            # binding to it would silently misroute emissions. Halt the run
-            # fail-closed (the loop swallows plain exceptions, so route through the
-            # halt path).
+            # binding to it would silently misroute emissions. Abort fail-closed.
             _halt_on_enforcement_failure(
-                state, context, MiddlewareException(_FOREIGN_TRIO_MESSAGE.format(seam="function")), "pre_tool_call"
+                MiddlewareException(_FOREIGN_TRIO_MESSAGE.format(seam="function")), "pre_tool_call"
             )
 
         try:
@@ -1379,23 +1428,20 @@ class _AgentHooksFunctionMiddleware(_AgentHooksMiddlewareBase, FunctionMiddlewar
             args = effective
         except InterceptionBlocked as exc:
             # §6.2: the tool is not dispatched and no post_tool_call is emitted.
-            self._block(state, context, exc, "pre_tool_call")
+            self._block(context, exc, "pre_tool_call")
             return
-        except (MiddlewareTermination, asyncio.CancelledError):
+        except (MiddlewareTermination, MiddlewareFailure, asyncio.CancelledError):
             raise
         except BaseException as exc:
-            _halt_on_enforcement_failure(state, context, exc, "pre_tool_call")
+            _halt_on_enforcement_failure(exc, "pre_tool_call")
 
         termination: MiddlewareTermination | None = None
         try:
             await call_next()
         except MiddlewareTermination as exc:
-            if state.halted is not None or _is_approval_request(context.result):
-                # Our own halt path, or framework approval control flow (the tool did
-                # not run; an approved replay re-enters through pre_tool_call).
-                raise
             # A middleware short-circuited with a substituted result; that result
-            # still enters the transcript, so it is bracketed below.
+            # still enters the transcript, so it is bracketed below (approval-request
+            # control flow is passed through un-emitted further down instead).
             termination = exc
         except asyncio.CancelledError:
             raise
@@ -1411,19 +1457,21 @@ class _AgentHooksFunctionMiddleware(_AgentHooksMiddlewareBase, FunctionMiddlewar
             except InterceptionBlocked as blocked:
                 # A policy deny over an already-errored call changes nothing (the
                 # result is discarded either way); a host error still halts the run.
-                self._maybe_halt(state, blocked, "post_tool_call")
-            except asyncio.CancelledError:
+                self._maybe_halt(blocked, "post_tool_call")
+            except (MiddlewareTermination, MiddlewareFailure, asyncio.CancelledError):
                 raise
             except BaseException as emit_exc:
-                _halt_on_enforcement_failure(state, context, emit_exc, "post_tool_call")
+                _halt_on_enforcement_failure(emit_exc, "post_tool_call")
             raise
 
         if _is_approval_request(context.result):
-            # Framework approval control flow on the normal return path (a middleware
-            # set an approval request and returned): the tool has not run, so there is
-            # no result to bracket — pass the control object through un-emitted, exactly
-            # like the termination branch above. The approved replay re-enters through
-            # pre_tool_call.
+            # Framework approval control flow (a middleware set an approval request,
+            # whether it returned or short-circuited): the tool has not run, so there
+            # is no result to bracket — pass the control object through un-emitted.
+            # The approved replay re-enters through pre_tool_call. A short-circuit is
+            # re-raised so the loop still stops and surfaces the request.
+            if termination is not None:
+                raise termination
             return
 
         try:
@@ -1434,11 +1482,11 @@ class _AgentHooksFunctionMiddleware(_AgentHooksMiddlewareBase, FunctionMiddlewar
             context.result = _ToolResultCodec.write_back(context.result, value, outcome.target)
         except InterceptionBlocked as exc:
             # §6.1: the result must be discarded as if the call had errored.
-            self._block(state, context, exc, "post_tool_call")
-        except (MiddlewareTermination, asyncio.CancelledError):
+            self._block(context, exc, "post_tool_call")
+        except (MiddlewareTermination, MiddlewareFailure, asyncio.CancelledError):
             raise
         except BaseException as exc:
-            _halt_on_enforcement_failure(state, context, exc, "post_tool_call")
+            _halt_on_enforcement_failure(exc, "post_tool_call")
         if termination is not None:
             raise termination
 

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

@@ -56,6 +56,7 @@ from ._types import (
     ChatResponseUpdate,
     Message,
     ResponseStream,
+    _append_instructions,  # pyright: ignore[reportPrivateUsage]
     _build_agent_response_from_chat_response,  # pyright: ignore[reportPrivateUsage]
     map_chat_to_agent_update,
     normalize_messages,
@@ -84,6 +85,15 @@ if TYPE_CHECKING:
 
 logger = logging.getLogger("agent_framework")
 
+# AgentLoopMiddleware stamps this key into the run options while a loop
+# iteration is running, so providers scoped to the whole user turn
+# (``after_run_once_per_turn``) skip their per-iteration ``after_run`` and only
+# fire once at the loop boundary. It rides the run's options rather than a
+# context variable: options reach only the runs the loop itself drives, so a
+# nested ``agent.run()`` (fresh options, its own session) keeps its own turn,
+# and nothing leaks into the caller's context while a stream is paused.
+_LOOP_ITERATION_TOKEN_KEY = "_agent_loop_iteration"  # nosec B105 - a context-options key, not a credential  # ruff: ignore[hardcoded-password-string]
+
 if TYPE_CHECKING:
     ResponseModelBoundT = TypeVar("ResponseModelBoundT", bound=BaseModel)
 else:
@@ -159,8 +169,8 @@ def _merge_options(base: dict[str, Any], override: dict[str, Any]) -> dict[str,
             # Merge metadata dicts
             result["metadata"] = {**result["metadata"], **value}
         elif key == "instructions" and result.get("instructions"):
-            # Concatenate instructions
-            result["instructions"] = f"{result['instructions']}\n{value}"
+            # Concatenate instructions, preserving provider-native structured values
+            result["instructions"] = _append_instructions(result["instructions"], value)
         else:
             result[key] = value
     return {key: value for key, value in result.items() if value is not None}
@@ -545,6 +555,7 @@ class BaseAgent(SerializationMixin):
         *,
         session: AgentSession | None,
         context: SessionContext,
+        only_per_turn: bool = False,
     ) -> None:
         """Run after_run on all context providers in reverse order.
 
@@ -557,6 +568,10 @@ class BaseAgent(SerializationMixin):
         Keyword Args:
             session: The conversation session.
             context: The invocation context with response populated.
+            only_per_turn: When True, run only providers that opted into
+                once-per-turn semantics (``after_run_once_per_turn``); used by
+                AgentLoopMiddleware when a loop ends. When False, those
+                providers are skipped while a loop iteration is in progress.
         """
         if _defer_run_persistence(partial(self._run_after_providers, session=session, context=context)):
             return
@@ -570,9 +585,17 @@ class BaseAgent(SerializationMixin):
         per_service_call_history_required = self.require_per_service_call_history_persistence and any(
             isinstance(provider, HistoryProvider) for provider in self.context_providers
         )
+        # The loop stamps the runs it drives via their options; anything else
+        # (nested run, caller-side run while a stream is paused) is its own turn.
+        in_loop_iteration = context.options.get(_LOOP_ITERATION_TOKEN_KEY) is not None
         for provider in reversed(self.context_providers):
             if per_service_call_history_required and isinstance(provider, HistoryProvider):
                 continue
+            once_per_turn = getattr(provider, "after_run_once_per_turn", False)
+            if only_per_turn and not once_per_turn:
+                continue
+            if in_loop_iteration and once_per_turn:
+                continue
             if provider_session is None:
                 raise RuntimeError("Provider session must be available when context providers are configured.")
             await provider.after_run(
@@ -1489,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)
@@ -1623,10 +1649,7 @@ class RawAgent(BaseAgent, Generic[OptionsCoT]):
         # Merge provider-contributed instructions into chat_options
         if session_context.instructions:
             combined_instructions = "\n".join(session_context.instructions)
-            if "instructions" in chat_options:
-                chat_options["instructions"] = f"{chat_options['instructions']}\n{combined_instructions}"
-            else:
-                chat_options["instructions"] = combined_instructions
+            chat_options["instructions"] = _append_instructions(chat_options.get("instructions"), combined_instructions)
 
         return session_context, chat_options
 

{agent_framework_core-1.14.0 → agent_framework_core-1.16.0}/agent_framework/_compaction.py

@@ -1529,6 +1529,10 @@ class CompactionProvider(ContextProvider):
             await agent.run("Hello", session=session)
     """
 
+    # Compacting persisted history mid-task rewrites the transcript the loop
+    # still works from, so defer it to the end of the user turn.
+    after_run_once_per_turn = True
+
     def __init__(
         self,
         *,

{agent_framework_core-1.14.0 → agent_framework_core-1.16.0}/agent_framework/_evaluation.py

@@ -797,8 +797,7 @@ class AgentEvalConverter:
                     "tool_call_id": c.call_id or "",
                     "name": c.name or "",
                 }
-                if args:
-                    tc["arguments"] = args
+                tc["arguments"] = args if args is not None else {}
                 content_items.append(tc)
             elif c.type == "function_result":
                 result_val = c.result

{agent_framework_core-1.14.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.14.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,