Skip to content

Python: agent-hooks interception contract as a first-class experimental core feature #7515

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
MohammadHaroonAbuomar wants to merge 9 commits into from
Open

Python: agent-hooks interception contract as a first-class experimental core feature #7515

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
0a85dd3
feat(python): add agent-hooks middleware as experimental core feature
MohammadHaroonAbuomar Aug 3, 2026
deeaa0e
Merge branch 'main' into mhabuomar/agent-hooks-first-class
MohammadHaroonAbuomar Aug 4, 2026
2cd37fc
style(python): unquote ResponseStream annotation per pyupgrade
MohammadHaroonAbuomar Aug 4, 2026
a80b5f3
refactor(python): address agent-hooks review feedback
MohammadHaroonAbuomar Aug 5, 2026
c1cfa83
refactor(python): second review round for agent-hooks
MohammadHaroonAbuomar Aug 5, 2026
2c66d61
docs(python): drop previous-behavior notes from middleware docstrings
MohammadHaroonAbuomar Aug 5, 2026
863ff03
fix(python): gate ownership survives retrying middleware
MohammadHaroonAbuomar Aug 6, 2026
84671f1
fix(python): streaming seam runs pipeline descent inside the gate
MohammadHaroonAbuomar Aug 6, 2026
be51015
fix(python): flush deferred persistence on streaming no-result termin…
MohammadHaroonAbuomar Aug 6, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 13 additions & 0 deletions python/PACKAGE_STATUS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -64,6 +64,19 @@ listed below.

### Experimental features

#### `AGENT_HOOKS`

- `agent-framework-core`: `create_agent_hooks_middleware` and
`create_agent_hooks_middleware_from_emitter` from `agent_framework/_agent_hooks.py`,
the AGENT-HOOKS-0.1 enforcement middleware bundle, and the `MiddlewareBundle`
container from `agent_framework/_middleware.py` that both factories produce
(`MiddlewareBundle` itself needs no extra). Requires the opt-in
`agent-framework-core[agent-hooks]` extra (`agent-hooks-sdk`), which is deliberately
not part of `agent-framework-core[all]`. Known limitation: service-side (hosted) tool
execution never passes through the framework's function-invocation seam, so the
`pre_tool_call`/`post_tool_call` points cannot intercept it; hosted tool calls and
outputs are surfaced in the `post_model_call` content projection instead.

#### `DECLARATIVE_AGENTS`

- `agent-framework-declarative`: declarative agent loading APIs from
Expand Down
5 changes: 5 additions & 0 deletions python/packages/core/agent_framework/__init__.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -41,6 +41,7 @@
)

_LAZY_MODULE_EXPORTS: Final[Mapping[str, tuple[str, ...]]] = {
"._agent_hooks": ("create_agent_hooks_middleware", "create_agent_hooks_middleware_from_emitter"),
"._agents": ("Agent", "BaseAgent", "RawAgent", "SupportsAgentRun"),
"._clients": (
"BaseChatClient",
Expand Down Expand Up @@ -183,6 +184,7 @@
"FunctionInvocationContext",
"FunctionMiddleware",
"FunctionMiddlewareTypes",
"MiddlewareBundle",
"MiddlewareTermination",
"MiddlewareType",
"MiddlewareTypes",
Expand Down Expand Up @@ -503,6 +505,7 @@
"MemoryTopicRecord",
"Message",
"MessageInjectionMiddleware",
"MiddlewareBundle",
"MiddlewareException",
"MiddlewareTermination",
"MiddlewareType",
Expand Down Expand Up @@ -599,6 +602,8 @@
"background_tasks_running",
"background_tasks_running_message",
"chat_middleware",
"create_agent_hooks_middleware",
"create_agent_hooks_middleware_from_emitter",
"create_always_approve_tool_response",
"create_always_approve_tool_with_arguments_response",
"create_edge_runner",
Expand Down
5 changes: 5 additions & 0 deletions python/packages/core/agent_framework/__init__.pyi
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,7 @@ from typing import Final

__version__: Final[str]

from ._agent_hooks import create_agent_hooks_middleware, create_agent_hooks_middleware_from_emitter
from ._agents import Agent, BaseAgent, RawAgent, SupportsAgentRun
from ._clients import (
BaseChatClient,
Expand Down Expand Up @@ -142,6 +143,7 @@ from ._middleware import (
FunctionInvocationContext,
FunctionMiddleware,
FunctionMiddlewareTypes,
MiddlewareBundle,
MiddlewareTermination,
MiddlewareType,
MiddlewareTypes,
Expand Down Expand Up @@ -467,6 +469,7 @@ __all__ = [
"MemoryTopicRecord",
"Message",
"MessageInjectionMiddleware",
"MiddlewareBundle",
"MiddlewareException",
"MiddlewareTermination",
"MiddlewareType",
Expand Down Expand Up @@ -563,6 +566,8 @@ __all__ = [
"background_tasks_running",
"background_tasks_running_message",
"chat_middleware",
"create_agent_hooks_middleware",
"create_agent_hooks_middleware_from_emitter",
"create_always_approve_tool_response",
"create_always_approve_tool_with_arguments_response",
"create_edge_runner",
Expand Down
Loading
Loading