google / google/adk-python

Built-in Resilience Support for AgentTool

オープン
#4,087 コメント 2 件 リアクション 0 件 担当者 1 名 @xuanyang15 が担当を希望しています GitHub で見る
core needs review
主要言語
Python
スター
21.5k
フォーク
4k
平均マージ
1日 14時間
マージ済み PR(30日)
37

説明

**Is your feature request related to a problem? Please describe.**
Yes. Currently, building resilient multi-agent systems with `AgentTool` requires significant custom code:

1. **No built-in timeout mechanism** - Developers must create custom wrappers to add timeout protection
2. **No automatic fallback** - Requires LLM reasoning and prompt engineering to route to alternative agents
3. **No result validation** - No way to verify that sub-agent results are complete
4. **Complexity leakage** - All sub-agent events are exposed, making it hard to hide internal complexity from users

**Example Problem:**
When a sub-agent times out or fails, the parent agent must manually handle the error, decide whether to retry, choose an alternative agent, and format user-friendly error messages. This requires:
- Custom `TimeoutAgentTool` wrapper
- Complex prompt engineering for routing
- Manual error handling logic
- Additional agents for error recovery

**Impact:**
- High barrier to entry for building resilient multi-agent systems
- Inconsistent error handling across different implementations
- Difficult to test timeout and failure scenarios
- Poor user experience when errors occur

**Describe the solution you'd like**
Add built-in resilience features to `AgentTool`:

### 1. Built-in Timeout Support

```python
AgentTool(
agent=sub_agent,
timeout=30.0, # Timeout in seconds
timeout_handler='error' | 'fallback' | 'retry', # How to handle timeout
)
```

### 2. Automatic Fallback Configuration

```python
AgentTool(
agent=primary_agent,
fallback_agent=fallback_agent,
fallback_on_timeout=True,
fallback_on_error=True,
fallback_on_partial_result=False,
)
```

### 3. Result Validation

```python
AgentTool(
agent=sub_agent,
validate_result=True,
required_fields=['summary', 'sources'], # For structured output
result_validator=lambda r: len(r.get('summary', '')) > 100,
)
```

### 4. Event Filtering

```python
AgentTool(
agent=sub_agent,
stream_events=True, # Stream all events
stream_events=False, # Only stream final result
hide_intermediate_steps=True, # Hide tool calls, show only results
)
```

### 5. Partial Result Handling

```python
AgentTool(
agent=sub_agent,
handle_partial_results='error' | 'retry' | 'return', # How to handle
partial_result_threshold=0.8, # 80% complete = valid
)
```

**Describe alternatives you've considered**
### Alternative 1: Custom Wrappers (Current Approach)

**Pros:**
- Works today without ADK changes
- Flexible and customizable
- Non-breaking

**Cons:**
- Requires significant custom code
- Inconsistent across implementations
- Hard to maintain
- High barrier to entry

### Alternative 2: Plugin-Based Solution

**Pros:**
- Extensible
- Doesn't require ADK core changes

**Cons:**
- Still requires custom code
- Less discoverable
- More complex API

### Alternative 3: Built-in Support (Proposed)

**Pros:**
- Simple, consistent API
- Low barrier to entry
- Better developer experience
- Easier to test

**Cons:**
- Requires ADK core changes
- Need to maintain backward compatibility

**Recommendation:** Built-in support is the best long-term solution, as it makes resilience patterns a first-class feature.
**Additional context**
### Sample Implementation

I've created a **working sample** (https://github.com/google/adk-python/pull/4086) that demonstrates:
- Custom `TimeoutAgentTool` wrapper
- Integration with `ReflectAndRetryToolPlugin`
- Prompt-based dynamic routing
- Error recovery patterns

コントリビューションガイド

コントリビューションガイドを開く

評価

この issue はまだ評価されていません。

新しい issue をメールで受け取る

初心者向けの GitHub issue を短くまとめたダイジェスト。