[tommyhutcheson]

This PR adds documentation for the pickle timing issue when deploying ADK agents to Vertex AI Agent Engine, where environment variables specified in AdkApp.env_vars are not available during toolset initialisation at import time.

Problem

google/adk-python#3208

When deploying agents to Agent Engine, toolsets that read configuration at import time (e.g., using Pydantic BaseSettings) will use deployment environment values instead of runtime environment values. This causes production agents to fail with incorrect configuration (e.g., connecting to localhost instead of production APIs).

Solution Documented

Added comprehensive documentation to docs/deploy/agent-engine.md covering:

1. The pickle timing issue - Explains the two-phase deployment lifecycle (import time vs runtime)
2. LazyToolsetWrapper pattern - Complete, production-ready implementation with proper error handling
3. Usage examples - Shows how to implement the pattern in agent definitions and deployment scripts
4. Guidance on when to use - Identifies common scenarios requiring this pattern

Changes

Modified Files

• docs/deploy/agent-engine.md - Added "Advanced deployment considerations" section (~120 lines)
• docs/tools/index.md - Added warning callout with link to solution

Key Features

Explains deployment architecture (import time vs runtime)
Provides complete LazyToolsetWrapper pattern implementation
Includes all necessary imports and helper functions
Error handling for missing environment variables
Custom __reduce__ for proper pickle serialisation
Complete usage examples for agent definition and deployment

Related

As requested by @surajksharma07 in #3208:

"I'd recommend filing a documentation issue on the ADK repository requesting coverage of: (1) the deployment architecture showing when agent code is imported
vs when env_vars are available, (2) the LazyToolsetWrapper pattern as the recommended approach for environment-specific configuration, and (3) best practices for
multi-environment deployments."

This PR addresses all three points with focused, practical documentation integrated into the existing Agent Engine deployment guide.

[yeesian]

Thank you so much!

[tommyhutcheson]

yeesian

Hey @yeesian Do I need to do somethuing else to get this one merged in ?

[hasanali-aa]

Any timeline on this getting merged?