google / google/adk-go

feat: Add OnPipelineErrorCallback lifecycle hook to Plugin Config

Open
#886 2 comments 0 reactions 0 assignees View on GitHub
enhancement
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.