chore: import upstream snapshot with attribution

2026-07-13 13:25:13 +08:00
commit ec2b666284
2231 changed files with 491535 additions and 0 deletions
@@ -0,0 +1,110 @@
+# Live Tool Callbacks Agent
+
+This sample demonstrates how tool callbacks work in live (bidirectional streaming) mode. It showcases both `before_tool_callback` and `after_tool_callback` functionality with multiple callback chains, async callbacks, and various callback behaviors.
+
+## Features Demonstrated
+
+### Before Tool Callbacks
+
+1. **Audit Callback**: Logs all tool calls before execution
+1. **Security Callback**: Can block tool calls based on security rules (e.g., restricted locations)
+1. **Async Validation Callback**: Performs async validation and can prevent invalid operations
+
+### After Tool Callbacks
+
+1. **Enhancement Callback**: Adds metadata to tool responses
+1. **Async Post-processing Callback**: Performs async post-processing of responses
+
+### Tools Available
+
+- `get_weather`: Get weather information for any location
+- `calculate_async`: Perform mathematical calculations asynchronously
+- `log_activity`: Log activities with timestamps
+
+## Testing Scenarios
+
+### 1. Basic Callback Flow
+
+```
+"What's the weather in New York?"
+```
+
+Watch the console output to see:
+
+- Audit logging before the tool call
+- Security check (will pass for New York)
+- Response enhancement after the tool call
+
+### 2. Security Blocking
+
+```
+"What's the weather in classified?"
+```
+
+The security callback will block this request and return an error response.
+
+### 3. Validation Prevention
+
+```
+"Calculate 10 divided by 0"
+```
+
+The async validation callback will prevent division by zero.
+
+### 4. Multiple Tool Calls
+
+```
+"Get weather for London and calculate 5 + 3"
+```
+
+See how callbacks work with multiple parallel tool calls.
+
+### 5. Callback Chain Testing
+
+```
+"Log this activity: Testing callback chains"
+```
+
+Observe how multiple callbacks in the chain are processed.
+
+## Getting Started
+
+1. **Start the ADK Web Server**
+
+   ```bash
+   adk web
+   ```
+
+1. **Access the ADK Web UI**
+   Navigate to `http://localhost:8000`
+
+1. **Select the Agent**
+   Choose "tool_callbacks_agent" from the dropdown in the top-left corner
+
+1. **Start Streaming**
+   Click the **Audio** or **Video** icon to begin streaming
+
+1. **Test Callbacks**
+   Try the testing scenarios above and watch both the chat responses and the console output to see callbacks in action
+
+## What to Observe
+
+- **Console Output**: Watch for callback logs with emojis:
+
+  - 🔍 AUDIT: Audit callback logging
+  - 🚫 SECURITY: Security callback blocking
+  - ⚡ ASYNC BEFORE: Async preprocessing
+  - ✨ ENHANCE: Response enhancement
+  - 🔄 ASYNC AFTER: Async post-processing
+
+- **Enhanced Responses**: Tool responses will include additional metadata added by after callbacks
+
+- **Error Handling**: Security blocks and validation errors will be returned as proper error responses
+
+## Technical Notes
+
+- This sample demonstrates that tool callbacks now work identically in both regular and live streaming modes
+- Multiple callbacks are supported and processed in order
+- Both sync and async callbacks are supported
+- Callbacks can modify, enhance, or block tool execution
+- The callback system provides full control over the tool execution pipeline