docs(deploy): add deployment strategy decision guide

Author: jpantsjoha

docs/deploy/decision-guide.md

@@ -0,0 +1,62 @@
+# Deployment Strategy Guide
+
+Choosing the right deployment target for your ADK agents is critical for success. The ADK supports multiple deployment targets, ranging from fully managed serverless environments to custom containerized infrastructure.
+
+This guide helps you choose the right path based on your specific needs.
+
+## Decision Matrix
+
+Use this matrix to quickly identify the best deployment target for your project.
+
+| Feature | **Agent Engine** (Vertex AI) | **Cloud Run** (Serverless Container) | **GKE / Custom VM** |
+| :--- | :--- | :--- | :--- |
+| **Primary Use Case** | Pure agent logic, rapid prototyping, no-ops | Custom UIs, complex networking, specialized libraries | Enterprise compliance, existing K8s ecosystem |
+| **Management Overhead** | **Low** (Fully Managed) | **Medium** (Container configuration) | **High** (Cluster management) |
+| **State Management** | Built-in (Sessions API) | External (Redis/SQL required) | External (Redis/SQL required) |
+| **Scaling** | Auto-scaling (per request) | Auto-scaling (0 to N instances) | Manual or Cluster Autoscaling |
+| **Networking** | Public API Endpoint | VPC connectivity, Custom Domains | Full VPC Control, Service Mesh |
+| **Cost Model** | Pay-per-use (Token/Request) | Compute-based (vCPU/Memory/Time) | Instance-based (Always on) |
+
+## Deployment Paths
+
+### Path A: Vertex AI Agent Engine (Recommended for most)
+**"I just want my agent to run."**
+
+This is the "Accelerated" path. You write code, and Google runs it.
+- **Pros**: No Dockerfile needed. No infrastructure config. Built-in conversation history.
+- **Cons**: Less control over the runtime environment.
+- **Command**: `adk deploy agent_engine`
+
+### Path B: Cloud Run (Native Deployment)
+**"I need a custom UI or specific libraries."**
+
+This acts like "Vercel for Agents". The ADK handles the containerization, but you get a standard Cloud Run service.
+- **Pros**: You can deploy a React frontend alongside your agent. You can install system dependencies (like `poppler` for PDF parsing).
+- **Cons**: You must manage session state (if you need persistence beyond memory).
+- **Command**: `adk deploy cloud_run` (See [Cloud Run Guide](./cloud-run.md))
+
+### Path C: Container / GKE
+**"I have strict enterprise compliance requirements."**
+
+You package the agent as a Docker container yourself and deploy it to your existing infrastructure.
+- **Pros**: Complete control. Meets strict IT/Security policies.
+- **Cons**: You own the build pipeline, security patching, and orchestration.
+- **Guide**: See [Container Deployment](./container.md)
+
+## Common Deployment Gotchas
+
+### Environment Variables
+- **Agent Engine**: Variables in your local `.env` are **not** automatically uploaded for security reasons. You must specify an env file during deploy:
+  ```bash
+  adk deploy agent_engine --env_file .env.prod
+  ```
+- **Cloud Run**: Variables must be set on the service after deployment or passed via flags:
+  ```bash
+  adk deploy cloud_run --service_name my-agent
+  gcloud run services update my-agent --set-env-vars KEY=VALUE
+  ```
+
+### File Uploads
+If your agent processes files (PDFs, Images):
+- **Agent Engine**: Handles file storage automatically within the session context.
+- **Cloud Run**: You must implement a mechanism to accept file uploads (e.g., multipart/form-data) and store them (e.g., in Google Cloud Storage) before passing the URI to the agent.

mkdocs.yml

@@ -250,6 +250,7 @@ nav:
       - Resume Agents: runtime/resume.md
     - Deployment:
       - deploy/index.md
+      - Strategy Guide: deploy/decision-guide.md
       - Agent Engine: deploy/agent-engine.md
       - Cloud Run: deploy/cloud-run.md
       - GKE: deploy/gke.md