[Feature Request]: Expose current callback hook metadata in Context
- 主要言語
- Python
- スター
- 21.5k
- フォーク
- 4k
- 平均マージ
- 1日 14時間
- マージ済み PR(30日)
- 37
説明
## 🔴 Required Information
### Is your feature request related to a specific problem?
`Context` exposes useful execution metadata such as `agent_name`, `node`,
`node_path`, `run_id`, and `function_call_id`, but it does not expose which
lifecycle hook is currently being executed.
This makes reusable cross-cutting code harder to implement. A shared security,
audit, or telemetry component invoked from several plugin and agent callbacks
must receive a manually maintained string or enum from every callback in order
to distinguish `before_agent`, `before_model`, `after_tool`, and other stages.
The existing fields cannot be used as a reliable substitute:
- `agent_name` identifies the active agent, not the callback hook.
- `node` and `node_path` identify the workflow node.
- `function_call_id` identifies a tool call, but not the lifecycle callback.
- Introspecting `__name__` is unreliable for decorators, partials, callable
objects, callback lists, and plugin methods.
This is especially relevant now that callback fields support callback lists
(#5583), because generic wrappers may run from several hook families.
### Describe the Solution You'd Like
Expose stable, read-only callback invocation metadata while a callback or
plugin hook is running. At minimum, the context should expose the lifecycle
hook kind. Optionally, it could also expose the owner and callable identity.
For example:
```python
class CallbackHook(StrEnum):
BEFORE_AGENT = "before_agent"
AFTER_AGENT = "after_agent"
BEFORE_MODEL = "before_model"
AFTER_MODEL = "after_model"
BEFORE_TOOL = "before_tool"
AFTER_TOOL = "after_tool"
ON_MODEL_ERROR = "on_model_error"
ON_TOOL_ERROR = "on_tool_error"
@dataclass(frozen=True)
class CallbackInvocationInfo:
hook: CallbackHook
owner: Literal["plugin", "agent", "model", "tool"]
callback_name: str | None = None
context.callback_info # CallbackInvocationInfo | None
```
The exact API is open for discussion. A stable `hook` value alone would solve
the primary use case; `callback_name` can remain optional because not every
callable has a meaningful name.
The metadata should describe the callback that is currently executing. It
should not describe a future Agent-level callback while a Plugin-level hook is
running, and it should not alter the documented plugin/callback execution
order.
### Impact on your work
This would make shared safety-policy, audit, and telemetry services easier to
reuse without manually propagating lifecycle-stage strings through every
callback adapter. It would also reduce the risk of recording or applying the
wrong policy stage after callbacks are reordered or composed.
There is no hard delivery deadline.
### Willingness to contribute
No current commitment, but I can help validate the proposed behavior and test
cases.
---
## 🟡 Recommended Information
### Describe Alternatives You've Considered
1. Pass a hook enum explicitly from every callback to shared code. This works,
but duplicates framework metadata and can drift from the actual hook.
2. Infer the stage from `agent_name`, `node`, or `function_call_id`. These fields
identify other execution concepts and are ambiguous.
3. Inspect the Python call stack or callable `__name__`. This is brittle with
decorators, callback lists, partials, callable objects, and plugin methods.
4. Create one dedicated service method per callback hook. This avoids the
ambiguity but adds repetitive adapters for cross-cutting concerns.
### Proposed API / Implementation
Set callback metadata immediately before invoking each plugin or object-level
callback, and restore or clear it afterwards. If mutating the shared `Context`
would be unsafe for nested execution, an immutable callback-scoped context view
or an additional callback invocation argument would provide the same contract.
Tests should cover:
- Plugin-level and object-level hooks.
- Callback lists and short-circuiting.
- Nested agent/workflow execution.
- Async callbacks and concurrent invocations.
- Decorated functions, partials, and callable objects.
### Additional Context
Related but distinct issues:
- #5583 added callback-list composition.
- #6779 asks for node-level Workflow hooks. This request is only about exposing
the identity of an already executing callback/plugin hook.
コントリビューションガイド
評価
この issue はまだ評価されていません。