agent-framework-core 1.22.0__tar.gz → 1.24.0__tar.gz

{agent_framework_core-1.22.0 → agent_framework_core-1.24.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: agent-framework-core
-Version: 1.22.0
+Version: 1.24.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
@@ -9,7 +9,6 @@ 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
@@ -24,36 +23,37 @@ Requires-Dist: python-dotenv>=1,<2
 Requires-Dist: opentelemetry-api>=1.39.0,<2
 Requires-Dist: pyyaml>=6.0,<7.0
 Requires-Dist: regex>=2024.11.6
-Requires-Dist: mcp>=1.24.0,<2 ; extra == "all"
-Requires-Dist: agent-framework-a2a>=1.0.0b261015,<2 ; extra == "all"
-Requires-Dist: agent-framework-ag-ui>=1.6.0,<2 ; extra == "all"
-Requires-Dist: agent-framework-anthropic>=1.0.0b261015,<2 ; extra == "all"
-Requires-Dist: agent-framework-azure-ai-search>=1.0.0b261015,<2 ; extra == "all"
-Requires-Dist: agent-framework-azure-contentunderstanding>=1.0.0b261015,<2 ; extra == "all"
-Requires-Dist: agent-framework-azure-cosmos>=1.0.0b261015,<2 ; extra == "all"
+Requires-Dist: mcp>=2.2.0,<3 ; extra == "all"
+Requires-Dist: tenacity>=9.1.4,<9.2.0 ; extra == "all"
+Requires-Dist: agent-framework-a2a>=1.0.0b261030,<2 ; extra == "all"
+Requires-Dist: agent-framework-ag-ui>=1.7.1,<2 ; extra == "all"
+Requires-Dist: agent-framework-anthropic>=1.0.0b261030,<2 ; extra == "all"
+Requires-Dist: agent-framework-azure-ai-search>=1.0.0b261030,<2 ; extra == "all"
+Requires-Dist: agent-framework-azure-contentunderstanding>=1.0.0b261030,<2 ; extra == "all"
+Requires-Dist: agent-framework-azure-cosmos>=1.0.0b261030,<2 ; extra == "all"
 Requires-Dist: agent-framework-azurefunctions>=1.0.0b260922,<2 ; extra == "all"
-Requires-Dist: agent-framework-bedrock>=1.0.0b261015,<2 ; extra == "all"
-Requires-Dist: agent-framework-chatkit>=1.0.0b261015,<2 ; extra == "all"
-Requires-Dist: agent-framework-claude>=1.0.0b261015,<2 ; extra == "all"
-Requires-Dist: agent-framework-copilotstudio>=1.0.0b261015,<2 ; extra == "all"
-Requires-Dist: agent-framework-declarative>=1.3.0,<2 ; extra == "all"
-Requires-Dist: agent-framework-devui>=1.0.0b261015,<2 ; extra == "all"
+Requires-Dist: agent-framework-bedrock>=1.0.0b261030,<2 ; extra == "all"
+Requires-Dist: agent-framework-chatkit>=1.0.0b261030,<2 ; extra == "all"
+Requires-Dist: agent-framework-claude>=1.0.0b261030,<2 ; extra == "all"
+Requires-Dist: agent-framework-copilotstudio>=1.0.0b261030,<2 ; extra == "all"
+Requires-Dist: agent-framework-declarative>=1.4.1,<2 ; extra == "all"
+Requires-Dist: agent-framework-devui>=1.0.0b261030,<2 ; extra == "all"
 Requires-Dist: agent-framework-durabletask>=1.0.0b260922,<2 ; extra == "all"
-Requires-Dist: agent-framework-foundry>=1.15.0,<2 ; extra == "all"
-Requires-Dist: agent-framework-foundry-hosting>=1.0.0b261015,<2 ; extra == "all"
-Requires-Dist: agent-framework-foundry-local>=1.0.0b261015,<2 ; extra == "all"
-Requires-Dist: agent-framework-gemini>=1.0.0b261015,<2 ; extra == "all"
-Requires-Dist: agent-framework-github-copilot>=2.1.0,<3 ; extra == "all" and ( python_version >= '3.11')
-Requires-Dist: agent-framework-hyperlight>=1.0.0b261015,<2 ; extra == "all" and ( python_version < '3.15' and ((sys_platform == 'linux' and platform_machine == 'x86_64') or (sys_platform == 'win32' and platform_machine == 'AMD64')))
-Requires-Dist: agent-framework-mem0>=1.0.0b261015,<2 ; extra == "all"
-Requires-Dist: agent-framework-mistral>=1.0.0b261015,<2 ; extra == "all"
-Requires-Dist: agent-framework-monty>=1.0.0b261015,<2 ; extra == "all"
-Requires-Dist: agent-framework-ollama>=1.0.0b261015,<2 ; extra == "all"
-Requires-Dist: agent-framework-openai>=1.17.0,<2 ; extra == "all"
-Requires-Dist: agent-framework-orchestrations>=1.3.2,<2 ; extra == "all"
-Requires-Dist: agent-framework-purview>=1.0.0b261015,<2 ; extra == "all"
-Requires-Dist: agent-framework-redis>=1.0.0b261015,<2 ; extra == "all" and ( python_version < '3.15')
-Requires-Dist: agent-framework-tools>=1.0.0b261015,<2 ; extra == "all"
+Requires-Dist: agent-framework-foundry>=1.16.0,<2 ; extra == "all"
+Requires-Dist: agent-framework-foundry-hosting>=1.0.0b261030,<2 ; extra == "all"
+Requires-Dist: agent-framework-foundry-local>=1.0.0b261030,<2 ; extra == "all"
+Requires-Dist: agent-framework-gemini>=1.0.0b261030,<2 ; extra == "all"
+Requires-Dist: agent-framework-github-copilot>=2.1.1,<3 ; extra == "all" and ( python_version >= '3.11')
+Requires-Dist: agent-framework-hyperlight>=1.0.0b261030,<2 ; extra == "all" and ( (sys_platform == 'linux' and platform_machine == 'x86_64') or (sys_platform == 'win32' and platform_machine == 'AMD64'))
+Requires-Dist: agent-framework-mem0>=1.0.0b261030,<2 ; extra == "all"
+Requires-Dist: agent-framework-mistral>=1.0.0b261030,<2 ; extra == "all"
+Requires-Dist: agent-framework-monty>=1.0.0b261030,<2 ; extra == "all"
+Requires-Dist: agent-framework-ollama>=1.0.0b261030,<2 ; extra == "all"
+Requires-Dist: agent-framework-openai>=1.18.0,<2 ; extra == "all"
+Requires-Dist: agent-framework-orchestrations>=1.4.1,<2 ; extra == "all"
+Requires-Dist: agent-framework-purview>=1.0.0b261030,<2 ; extra == "all"
+Requires-Dist: agent-framework-redis>=1.0.0b261030,<2 ; extra == "all" and ( python_version < '3.15')
+Requires-Dist: agent-framework-tools>=1.0.0b261030,<2 ; extra == "all"
 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
@@ -85,13 +85,15 @@ pip install agent-framework-openai
 
 Supported Platforms:
 
-- Python: 3.10–3.15
+- Python: 3.11–3.15
 - OS: Windows, macOS, Linux
 
-Python 3.10 remains supported and tested for this release, but it is deprecated
-because upstream Python 3.10 has reached end of life. New environments should
-use Python 3.11 or later. Removing Python 3.10 support will be handled in a
-future release rather than by this compatibility update.
+Python 3.10 is no longer supported because it has reached upstream end of life.
+Package metadata still permits Python 3.10 installation, but CI no longer runs
+unit or integration tests on it and compatibility is not guaranteed. Use
+Python 3.11–3.15 for supported environments, subject to
+[integration-specific limits](../../README.md#python-315-limitations). Raising
+the installation minimum will be handled separately.
 
 ## 1. Setup API Keys
 
@@ -132,6 +134,14 @@ carry a documented feature-usage token.
 - `AGENT_FRAMEWORK_USER_AGENT_DISABLED=true` disables the entire Agent Framework
   User-Agent contribution, including the feature token.
 
+OpenTelemetry providers configured through `configure_otel_providers()` share a
+resource containing `"microsoft.agent-framework": "True"` (a string) by default. This
+resource attribute applies to logs, traces, and metrics, including other
+instrumentation using those providers. Existing environment and explicit resource
+attribute overrides retain their precedence. If you configure providers yourself,
+use `agent_framework.observability.create_resource()` for each provider or add the
+attribute to your own shared resource.
+
 See the following [getting started samples](https://github.com/microsoft/agent-framework/tree/main/python/samples/01-get-started) for more information.
 
 ## 2. Create a Simple Agent

{agent_framework_core-1.22.0 → agent_framework_core-1.24.0}/README.md

@@ -22,13 +22,15 @@ pip install agent-framework-openai
 
 Supported Platforms:
 
-- Python: 3.10–3.15
+- Python: 3.11–3.15
 - OS: Windows, macOS, Linux
 
-Python 3.10 remains supported and tested for this release, but it is deprecated
-because upstream Python 3.10 has reached end of life. New environments should
-use Python 3.11 or later. Removing Python 3.10 support will be handled in a
-future release rather than by this compatibility update.
+Python 3.10 is no longer supported because it has reached upstream end of life.
+Package metadata still permits Python 3.10 installation, but CI no longer runs
+unit or integration tests on it and compatibility is not guaranteed. Use
+Python 3.11–3.15 for supported environments, subject to
+[integration-specific limits](../../README.md#python-315-limitations). Raising
+the installation minimum will be handled separately.
 
 ## 1. Setup API Keys
 
@@ -69,6 +71,14 @@ carry a documented feature-usage token.
 - `AGENT_FRAMEWORK_USER_AGENT_DISABLED=true` disables the entire Agent Framework
   User-Agent contribution, including the feature token.
 
+OpenTelemetry providers configured through `configure_otel_providers()` share a
+resource containing `"microsoft.agent-framework": "True"` (a string) by default. This
+resource attribute applies to logs, traces, and metrics, including other
+instrumentation using those providers. Existing environment and explicit resource
+attribute overrides retain their precedence. If you configure providers yourself,
+use `agent_framework.observability.create_resource()` for each provider or add the
+attribute to your own shared resource.
+
 See the following [getting started samples](https://github.com/microsoft/agent-framework/tree/main/python/samples/01-get-started) for more information.
 
 ## 2. Create a Simple Agent

{agent_framework_core-1.22.0 → agent_framework_core-1.24.0}/agent_framework/__init__.py

@@ -42,7 +42,11 @@ from .exceptions import (
 )
 
 _LAZY_MODULE_EXPORTS: Final[Mapping[str, tuple[str, ...]]] = {
-    "._agent_hooks": ("create_agent_hooks_middleware", "create_agent_hooks_middleware_from_emitter"),
+    "._agent_hooks": (
+        "create_agent_hooks_middleware",
+        "create_agent_hooks_middleware_from_declaration",
+        "create_agent_hooks_middleware_from_emitter",
+    ),
     "._agents": ("Agent", "BaseAgent", "RawAgent", "SupportsAgentRun"),
     "._clients": (
         "BaseChatClient",
@@ -69,6 +73,7 @@ _LAZY_MODULE_EXPORTS: Final[Mapping[str, tuple[str, ...]]] = {
         "SUMMARIZED_BY_SUMMARY_ID_KEY",
         "SUMMARY_OF_GROUP_IDS_KEY",
         "SUMMARY_OF_MESSAGE_IDS_KEY",
+        "AgentTriggeredCompactionStrategy",
         "CharacterEstimatorTokenizer",
         "CompactionProvider",
         "CompactionStrategy",
@@ -80,6 +85,7 @@ _LAZY_MODULE_EXPORTS: Final[Mapping[str, tuple[str, ...]]] = {
         "TokenizerProtocol",
         "ToolResultCompactionStrategy",
         "TruncationStrategy",
+        "UnloadSkillsCompactionStrategy",
         "annotate_message_groups",
         "apply_compaction",
         "included_messages",
@@ -452,6 +458,7 @@ __all__ = [
     "AgentResponseUpdate",
     "AgentRunInputs",
     "AgentSession",
+    "AgentTriggeredCompactionStrategy",
     "AggregatingSkillsSource",
     "Annotation",
     "BackgroundAgentsProvider",
@@ -645,6 +652,7 @@ __all__ = [
     "ToolTypes",
     "TruncationStrategy",
     "TypeCompatibilityError",
+    "UnloadSkillsCompactionStrategy",
     "UpdateT",
     "UsageDetails",
     "UserInputRequiredException",
@@ -682,6 +690,7 @@ __all__ = [
     "background_tasks_running_message",
     "chat_middleware",
     "create_agent_hooks_middleware",
+    "create_agent_hooks_middleware_from_declaration",
     "create_agent_hooks_middleware_from_emitter",
     "create_always_approve_tool_response",
     "create_always_approve_tool_with_arguments_response",

{agent_framework_core-1.22.0 → agent_framework_core-1.24.0}/agent_framework/__init__.pyi

@@ -4,7 +4,11 @@ from typing import Final
 
 __version__: Final[str]
 
-from ._agent_hooks import create_agent_hooks_middleware, create_agent_hooks_middleware_from_emitter
+from ._agent_hooks import (
+    create_agent_hooks_middleware,
+    create_agent_hooks_middleware_from_declaration,
+    create_agent_hooks_middleware_from_emitter,
+)
 from ._agents import Agent, BaseAgent, RawAgent, SupportsAgentRun
 from ._clients import (
     BaseChatClient,
@@ -31,6 +35,7 @@ from ._compaction import (
     SUMMARIZED_BY_SUMMARY_ID_KEY,
     SUMMARY_OF_GROUP_IDS_KEY,
     SUMMARY_OF_MESSAGE_IDS_KEY,
+    AgentTriggeredCompactionStrategy,
     CharacterEstimatorTokenizer,
     CompactionProvider,
     CompactionStrategy,
@@ -42,6 +47,7 @@ from ._compaction import (
     TokenizerProtocol,
     ToolResultCompactionStrategy,
     TruncationStrategy,
+    UnloadSkillsCompactionStrategy,
     annotate_message_groups,
     apply_compaction,
     included_messages,
@@ -407,6 +413,7 @@ __all__ = [
     "AgentResponseUpdate",
     "AgentRunInputs",
     "AgentSession",
+    "AgentTriggeredCompactionStrategy",
     "AggregatingSkillsSource",
     "Annotation",
     "BackgroundAgentsProvider",
@@ -600,6 +607,7 @@ __all__ = [
     "ToolTypes",
     "TruncationStrategy",
     "TypeCompatibilityError",
+    "UnloadSkillsCompactionStrategy",
     "UpdateT",
     "UsageDetails",
     "UserInputRequiredException",
@@ -637,6 +645,7 @@ __all__ = [
     "background_tasks_running_message",
     "chat_middleware",
     "create_agent_hooks_middleware",
+    "create_agent_hooks_middleware_from_declaration",
     "create_agent_hooks_middleware_from_emitter",
     "create_always_approve_tool_response",
     "create_always_approve_tool_with_arguments_response",

{agent_framework_core-1.22.0 → agent_framework_core-1.24.0}/agent_framework/_agent_hooks.py

@@ -10,14 +10,17 @@ control contract as one coherent feature on the framework's native middleware se
 - ``pre_tool_call`` / ``post_tool_call`` ride the function seam.
 
 The public entry points are :func:`create_agent_hooks_middleware` (one agent-hooks
-session per run) and :func:`create_agent_hooks_middleware_from_emitter` (host-owned
-session). Both return a :class:`~agent_framework.MiddlewareBundle`: the three middleware
-implementations are deliberately private and travel as one indivisible unit, because
-installing only part of them would enforce only part of the control contract. Install
-exactly one bundle per agent, placed first in the middleware list: middleware listed
-before the bundle runs outside the enforcement boundary (outer position is outer trust)
-— e.g. a function middleware placed before the bundle can substitute a tool result that
-the tool seam never brackets; the final ``output`` point still guards whatever egresses.
+session per run), :func:`create_agent_hooks_middleware_from_emitter` (host-owned
+session) and :func:`create_agent_hooks_middleware_from_declaration` (one session per
+run, with the configuration and the interceptor bindings read from a host declaration
+document, spec section 7.7). All return a :class:`~agent_framework.MiddlewareBundle`: the
+three middleware implementations are deliberately private and travel as one indivisible
+unit, because installing only part of them would enforce only part of the control
+contract. Install exactly one bundle per agent, placed first in the middleware list:
+middleware listed before the bundle runs outside the enforcement boundary (outer position
+is outer trust) — e.g. a function middleware placed before the bundle can substitute a
+tool result that the tool seam never brackets; the final ``output`` point still guards
+whatever egresses.
 
 Enforcement semantics (``mode="enforce"``):
 
@@ -101,6 +104,7 @@ import asyncio
 import contextlib
 import json
 import logging
+import os
 import uuid
 from collections.abc import AsyncGenerator, Awaitable, Callable, Mapping, Sequence
 from contextvars import ContextVar
@@ -142,9 +146,13 @@ if TYPE_CHECKING:
     from agent_hooks import (
         AgentContextBuilder,
         ApprovalResolver,
+        BindingContext,
         CompositionConfig,
         EmitOutcome,
         EnforcementMode,
+        HostDeclaration,
+        HostRegistry,
+        HostSurface,
         IdentityProvider,
         InterceptionBlocked,
         InterceptionEmitter,
@@ -164,6 +172,22 @@ _SDK_MISSING_MESSAGE = (
     "Please install it with `pip install agent-hooks-sdk`."
 )
 
+_DECLARATION_SDK_MISSING_MESSAGE = (
+    "Loading a host declaration requires `agent-hooks-sdk` 0.1.0b2 or later (the first release "
+    "that accepts the agent-hooks-declaration/1.0 document). Please upgrade it with "
+    "`pip install --upgrade agent-hooks-sdk`."
+)
+
+# The binding kind this framework registers when a factory receives ``interceptors``:
+# ``{"id": "egress", "kind": "agent_framework.interceptor", "config": {"name": "egress"}}``
+# binds the interceptor supplied under that name (``name`` defaults to the binding id).
+_DECLARATION_KIND = "agent_framework.interceptor"
+# The code surface a declaration is resolved against (spec section 7.7.4): every point, the
+# capabilities the conformance claim lists, and the ``terminate`` posture this module
+# implements at the tool seam.
+_DECLARATION_CAPABILITIES = ("model_calls", "tool_calls", "int64_json", "bigint_json", "host_declaration")
+_DECLARATION_POSTURE = "terminate"
+
 _TRIO_REQUIRED_MESSAGE = (
     "agent-hooks {seam} middleware was invoked without an active agent-hooks run. "
     "The middleware bundle returned by create_agent_hooks_middleware() must be installed "
@@ -211,6 +235,21 @@ def _require_sdk() -> None:
         del AgentContextBuilder, EnforcementMode, InterceptionBlocked, InterceptionEmitter
 
 
+def _require_declaration_sdk() -> None:
+    """Like :func:`_require_sdk`, for the host-declaration loader (``agent-hooks-sdk`` 0.1.0b2+).
+
+    An installed SDK that predates the loader raises ``ImportError`` on these names; that case
+    gets an upgrade hint instead of a bare "cannot import name" message.
+    """
+    _require_sdk()
+    try:
+        from agent_hooks import HostDeclaration, HostRegistry, HostSurface
+    except ImportError as exc:
+        raise ImportError(_DECLARATION_SDK_MISSING_MESSAGE) from exc
+    else:
+        del HostDeclaration, HostRegistry, HostSurface
+
+
 # region Run state
 
 
@@ -227,6 +266,9 @@ class _AgentHooksConfig:
     record_sink: Callable[[InterceptionRecord], None] | None
     emitter: InterceptionEmitter | None
     builder: AgentContextBuilder | None
+    # Set by the host-declaration factory: every run loads a fresh emitter from this pair.
+    declaration: HostDeclaration | None = None
+    registry: HostRegistry | None = None
 
 
 @dataclass
@@ -1036,17 +1078,23 @@ class _AgentHooksAgentMiddleware(_AgentHooksMiddlewareBase, AgentMiddleware):
             session_id=uuid.uuid4().hex,
             agent_name=str(agent_name) if agent_name else None,
         )
-        kwargs: dict[str, Any] = {
-            "resolver": config.resolver,
-            "timeout": config.timeout,
-            "composition": config.composition,
-            "identity_provider": config.identity_provider,
-        }
-        if config.mode is not None:
-            kwargs["mode"] = config.mode
-        emitter = InterceptionEmitter(**kwargs)
-        for name, interceptor in config.interceptors:
-            emitter.register(interceptor, name)
+        if config.declaration is not None and config.registry is not None:
+            # One session per run, configured by the declaration: the loader rebuilds the
+            # sealed emitter from the same document and registry the factory validated, so
+            # every run gets the same resolved declaration and a fresh session (spec 7.7.7).
+            emitter = InterceptionEmitter.from_declaration(config.declaration, config.registry)
+        else:
+            kwargs: dict[str, Any] = {
+                "resolver": config.resolver,
+                "timeout": config.timeout,
+                "composition": config.composition,
+                "identity_provider": config.identity_provider,
+            }
+            if config.mode is not None:
+                kwargs["mode"] = config.mode
+            emitter = InterceptionEmitter(**kwargs)
+            for name, interceptor in config.interceptors:
+                emitter.register(interceptor, name)
         if config.record_sink is not None:
             emitter.set_record_sink(config.record_sink)
         return _RunState(emitter=emitter, builder=builder, session_scoped=False, config=config)
@@ -1698,6 +1746,212 @@ def create_agent_hooks_middleware_from_emitter(
     return _build_bundle(config)
 
 
+def _host_surface() -> HostSurface:
+    from agent_hooks import HostSurface
+
+    return HostSurface.from_capabilities(_DECLARATION_CAPABILITIES, tool_seam_host_error=_DECLARATION_POSTURE)
+
+
+def _host_registry() -> HostRegistry:
+    """A fresh registry over this framework's surface (the declaration factory builds one per call)."""
+    from agent_hooks import HostRegistry
+
+    return HostRegistry(_host_surface())
+
+
+def _interceptor_kind_resolver(interceptors: Mapping[str, Interceptor]) -> Callable[[Any, BindingContext], Interceptor]:
+    """The resolver behind the ``agent_framework.interceptor`` kind.
+
+    ``config`` is ``{}`` or ``{"name": "<key>"}``; the key defaults to the binding id. Anything
+    else refuses the binding (``declaration_error:binding_rejected``). Messages name the binding
+    id (the loader prints ids itself) but never echo the config, as spec section 7.7.5 requires.
+    """
+
+    def resolve(config: Any, binding: BindingContext) -> Interceptor:
+        if not isinstance(config, Mapping):
+            raise ValueError(f"binding {binding.id!r}: config must be an object with an optional 'name' member")
+        members = cast("Mapping[str, Any]", config)  # a JSON object: string keys
+        if set(members) - {"name"}:
+            raise ValueError(f"binding {binding.id!r}: config accepts only the 'name' member")
+        name: Any = members.get("name", binding.id)
+        if not isinstance(name, str):
+            raise ValueError(f"binding {binding.id!r}: config.name must be a string")
+        try:
+            return interceptors[name]
+        except KeyError:
+            raise ValueError(f"binding {binding.id!r}: no interceptor was supplied under the name it binds") from None
+
+    return resolve
+
+
+@experimental(feature_id=ExperimentalFeature.AGENT_HOOKS)
+def create_agent_hooks_middleware_from_declaration(
+    declaration: HostDeclaration | Mapping[str, Any] | str | os.PathLike[str],
+    *,
+    interceptors: Mapping[str, Interceptor] | None = None,
+    configure_registry: Callable[[HostRegistry], object] | None = None,
+    record_sink: Callable[[InterceptionRecord], None] | None = None,
+) -> MiddlewareBundle:
+    """Build the agent-hooks middleware bundle from a host declaration.
+
+    A host declaration (spec section 7.7) is one JSON document that fixes the enforcement
+    configuration (mode, composition, identity provider, approval resolver and redactor,
+    timeouts, record bound), the declared surface and the interceptor bindings. The loader
+    validates it against this framework's code surface and the names registered in code, and
+    refuses anything the framework cannot honour before any emission. Enforcement semantics,
+    the one-session-per-run model and the composition-order requirements are those of
+    :func:`create_agent_hooks_middleware`; every record additionally carries the contract
+    version the emitter was built from (``declaration: "agent-hooks-declaration/1.0"``).
+
+    Bindings name a kind the host registered in code; a kind is a lookup key, never a module
+    or class the loader imports. Passing ``interceptors`` registers the framework's own kind,
+    ``agent_framework.interceptor``: a binding ``{"id": "egress", "kind":
+    "agent_framework.interceptor"}`` runs the interceptor supplied as ``interceptors["egress"]``
+    (``config: {"name": ...}`` picks a different key). Other kinds, custom identity providers,
+    approval resolvers and approval redactors are registered through ``configure_registry``.
+    Every call builds a fresh ``agent_hooks.HostRegistry`` over the surface this middleware
+    implements (all eight points; ``model_calls``, ``tool_calls``, ``int64_json``,
+    ``bigint_json`` and ``host_declaration``; posture ``tool_seam_host_error: terminate``;
+    buffered streaming), registers ``agent_framework.interceptor`` when ``interceptors`` is
+    given, hands the registry to ``configure_registry``, then validates the document against
+    it. The registry never leaves the factory and nothing caller-owned is touched, so a
+    refused document or a raising callback leaves nothing behind for the next call.
+
+    The emitter the loader builds is sealed, so each run loads a fresh one from the same
+    document and registry (kind resolvers run once at construction and once per run); the
+    interceptors bound through ``agent_framework.interceptor`` are the supplied instances and
+    stay shared across runs, exactly as with :func:`create_agent_hooks_middleware`. To scope
+    one declaration-built session across several runs instead, build the emitter yourself
+    with ``agent_hooks.InterceptionEmitter.from_declaration_path`` (or ``_json`` / ``_value``)
+    and pass it to :func:`create_agent_hooks_middleware_from_emitter`.
+
+    Note:
+        A document's ``configuration.posture.tool_seam_host_error`` must equal the posture the
+        code implements, and the spec default is ``continue``, so every document for this
+        framework has to write ``"posture": {"tool_seam_host_error": "terminate"}`` or the
+        loader refuses it with ``declaration_error:surface_unsupported``.
+
+    Args:
+        declaration: The document, in one of three forms. An ``agent_hooks.HostDeclaration``
+            (for example from ``agent_hooks.DeclarationBuilder``, or
+            ``agent_hooks.HostDeclaration.from_json(text)`` for JSON text you already hold) is
+            used as is. A mapping (any ``Mapping``; it is copied into a ``dict`` for the SDK and
+            its members must be JSON values) is the document as a value. A ``str`` or
+            ``os.PathLike`` is the path of the document file, read once through
+            ``agent_hooks.HostDeclaration.from_path`` (a regular UTF-8 file of at most 1 MiB; an
+            unreadable file is ``agent_hooks.DeclarationError`` with class ``unreadable``).
+            JSON text is not accepted directly: a string is always a path.
+
+    Keyword Args:
+        interceptors: Interceptors by name for the ``agent_framework.interceptor`` kind.
+            ``None`` leaves the kind unregistered, so a document that uses it is refused.
+        configure_registry: Called at most once, with the fresh ``agent_hooks.HostRegistry``
+            built for this call, to register the host's own binding kinds, identity providers,
+            approval resolvers and approval redactors (``registry.kind(...)``,
+            ``registry.identity_provider(...)``, ``registry.approval_resolver(...)``,
+            ``registry.approval_redactor(...)``) before the document is validated. A file that
+            cannot be read (class ``unreadable``) or a value that cannot be serialized (class
+            ``malformed``) is refused before the callback runs. ``None`` registers nothing of
+            the host's own. A callback that raises propagates as is; nothing is cached, so the
+            next call starts from a fresh registry.
+        record_sink: Optional callable receiving every interception record.
+
+    Returns:
+        The middleware bundle to pass (as one element) to ``Agent(middleware=...)``.
+
+    Raises:
+        ModuleNotFoundError: If the optional ``agent-hooks-sdk`` package is not installed.
+        ImportError: If the installed ``agent-hooks-sdk`` predates the host-declaration loader.
+        agent_hooks.DeclarationError: If the loader refuses the document (an unreadable file,
+            unsupported version, unknown member, a posture or surface the framework does not
+            implement, an unregistered name or kind, a binding its kind resolver rejects, and
+            so on).
+        ValueError: If ``configure_registry`` registers ``agent_framework.interceptor`` while
+            ``interceptors`` is also given, or registers any other name twice or under the
+            wrong grammar (the SDK's own registry checks, raised as they are); or if the
+            document declares no bindings, since an emitter with zero interceptors fails closed
+            on every emission (the same rule as :func:`create_agent_hooks_middleware`).
+
+    Examples:
+        .. code-block:: python
+
+            from agent_framework import Agent, create_agent_hooks_middleware_from_declaration
+
+            declaration = {
+                "declaration": "agent-hooks-declaration/1.0",
+                "configuration": {"posture": {"tool_seam_host_error": "terminate"}},
+                "bindings": [{"id": "egress", "kind": "agent_framework.interceptor"}],
+            }
+            agent = Agent(
+                client=client,
+                name="assistant",
+                middleware=[
+                    create_agent_hooks_middleware_from_declaration(declaration, interceptors={"egress": EgressGuard()})
+                ],
+            )
+
+        A host kind registered through ``configure_registry``: the document is read once from
+        the file and binds ``{"id": "guard", "kind": "acme.guard", "config": {...}}``. The
+        callback's return value is ignored, so a one-line lambda over the chaining registry
+        methods works:
+
+        .. code-block:: python
+
+            bundle = create_agent_hooks_middleware_from_declaration(
+                "policy/declaration.json",
+                configure_registry=lambda registry: registry.kind("acme.guard", acme_guard),
+            )
+    """
+    _require_declaration_sdk()
+    from agent_hooks import HostDeclaration, InterceptionEmitter
+
+    if isinstance(declaration, HostDeclaration):
+        document = declaration
+    elif isinstance(declaration, (str, os.PathLike)):
+        # A string is a path, never JSON text (``HostDeclaration.from_json`` is the text path).
+        document = HostDeclaration.from_path(declaration)
+    else:
+        # ``HostDeclaration.from_value`` serializes with ``json.dumps``, which takes a ``dict`` but no
+        # other ``Mapping`` (``MappingProxyType``, ``UserDict``). Anything that is not a mapping goes
+        # through as given, so the SDK's own refusal applies (``malformed``: the root is not an object).
+        value: Any = declaration
+        if isinstance(value, Mapping):
+            value = dict(cast("Mapping[str, Any]", value))
+        document = HostDeclaration.from_value(value)
+
+    # A registry for this call only: it is never handed back, so a refused document or a raising
+    # callback cannot poison a later call, and nothing caller-owned is mutated.
+    registry = _host_registry()
+    if interceptors is not None:
+        registry.kind(_DECLARATION_KIND, _interceptor_kind_resolver(dict(interceptors)))
+    if configure_registry is not None:
+        configure_registry(registry)
+    # Load once here so a refused document (every class of spec section 7.7.6, kind resolvers
+    # included) raises ``agent_hooks.DeclarationError`` at construction, before any run.
+    resolved = InterceptionEmitter.from_declaration(document, registry).declaration
+    if resolved is None or not resolved.bindings:
+        # The spec allows an empty-deny host that is written down; for an agent it means every
+        # run is denied at ``input``, so refuse it here like ``create_agent_hooks_middleware``.
+        raise ValueError(
+            "create_agent_hooks_middleware_from_declaration requires at least one binding in the "
+            "declaration (an emitter with zero interceptors fails closed on every emission)."
+        )
+    config = _AgentHooksConfig(
+        interceptors=(),
+        resolver=None,
+        mode=None,
+        composition=None,
+        identity_provider=None,
+        timeout=None,
+        record_sink=record_sink,
+        emitter=None,
+        builder=None,
+        declaration=document,
+        registry=registry,
+    )
+    return _build_bundle(config)
+
+
 def _build_bundle(config: _AgentHooksConfig) -> MiddlewareBundle:
     mark_feature_used(FeatureIndex.CORE_AGENT_HOOKS)
     return MiddlewareBundle([