feat: Add OnPipelineErrorCallback lifecycle hook to Plugin Config
- Dominant language
- Go
- Stars
- 8.8k
- Forks
- 1k
- Avg merge
- 3d 18h
- Merged PRs (30d)
- 88
Description
# Feature Request: `OnPipelineErrorCallback` Lifecycle Hook
---
## 🔴 Required Information
### Is your feature request related to a specific problem?
Currently, the `plugin.Config` struct provides precise, granular hooks for structural runtime failures like `OnModelErrorCallback` and `OnToolErrorCallback`. However, there is a visibility and control gap for errors encountered during orchestrator lifecycles.
If an error occurs during runtime execution setups-such as within an `OnUserMessageCallback` or a `BeforeRunCallback`-the underlying framework immediately propagates the error up the call stack, halting execution. Independent plugin developers lack a native mechanism to intercept these orchestrator-level failures to perform telemetry logging, clean up transient states, or implement custom retry/fallback behaviors globally for the agent pipeline.
---
## Proposed Solution
Introduce an `OnPipelineErrorCallback` lifecycle hook to the `plugin.Config` and `plugin.Plugin` structures. This callback will capture any pipeline-level error that escapes granular tool/model loops, allowing plugins to inspect the error context, log telemetry data, gracefully transform or wrap the error before propagation, or return a fallback response payload.
---
## Impact on your work
This feature significantly improves the design of enterprise-grade telemetry and resilience plugins. Without it, our global error tracking wrappers cannot safely intercept lifecycle anomalies without risking unhandled pipeline failures or losing context from the `agent.InvocationContext`.
---
## 🟡 Recommended Information
### Alternatives Considered
Writing custom boilerplate code inside every individual agent implementation to wrap the runner call in a `recover()` or manual try-catch style pattern defeats the modularity and design pattern of the ADK plugin infrastructure.
---
### Willingness to contribute
Yes, I am interested in implementing this feature and submitting a PR.
---
## Proposed API / Implementation
### 1. Extend `plugin.Config` and `plugin.Plugin`
```go
type OnPipelineErrorCallback func(agent.InvocationContext, error) error
type Config struct {
Name string
// Existing fields...
OnUserMessageCallback OnUserMessageCallback
BeforeRunCallback BeforeRunCallback
// OnPipelineErrorCallback intercepts errors occurring during orchestration lifecycles.
OnPipelineErrorCallback OnPipelineErrorCallback
}
```
---
### 2. Expose an accessor on the `Plugin` struct
```go
func (p *Plugin) OnPipelineErrorCallback() OnPipelineErrorCallback {
return p.onPipelineErrorCallback
}
```
---
### 3. Integrate into Runtime Orchestration Engine
The runner component executing the lifecycle callbacks will pass unresolved lifecycle errors into the active plugin stack’s `OnPipelineErrorCallback` loop before aborting execution entirely.
---
## Additional Context
Completes the parity lifecycle symmetry alongside `OnModelError` and `OnToolError` blocks already present in `plugin.go`.
Contributor guide
Research direction
Start in plugin.go by reviewing the existing OnModelError and OnToolError handling and the plugin.Config and plugin.Plugin structures. Then trace the runner component that executes lifecycle callbacks to identify where unresolved orchestration errors are propagated. Done means the new callback is exposed and invoked for those errors before execution aborts, with behavior covered by the relevant runtime tests.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- go
- Domain
- backend, backend-api-design
- Issue type
- Feature
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 55/100