Add comprehensive documentation comments to all example agents

[slvnperron]

Summary

This PR adds extensive inline documentation to all example agents in the repository. Each agent, conversation handler, workflow, and tool now includes detailed comments explaining the architectural decisions, design patterns, and implementation rationale.

Key Changes

Agent Configuration Files

• Added @agent JSDoc headers with pattern descriptions
• Documented why each agent exists and its core use case
• Explained architectural decisions (model choices, integration selections, state management)
• Examples: Approval Agent, Brand Extractor, Clause Extraction, Deep Research, Guardrails, Subagents

Conversation Handlers

• Added @conversation JSDoc headers explaining the handler's role
• Documented key patterns: workflow monitoring, file upload handling, dynamic tools, topic refinement
• Explained state management strategies and why certain patterns were chosen
• Included security considerations (e.g., userId scoping in clause-extraction)

Workflows

• Added @workflow JSDoc headers with multi-phase pipeline documentation
• Explained why each workflow phase exists and what it accomplishes
• Documented design decisions: parallel processing (step.map), batch sizing, timeout values
• Explained why certain tasks use specific LLM models (e.g., "best" model for synthesis)

Tools and Utilities

• Added @tools and @class JSDoc headers
• Documented tool factory patterns and dependency injection
• Explained security models (e.g., userId closure capture in query tools)
• Clarified retrieve-then-analyze patterns and why tools are separated

Notable Implementation Details

• Pattern Documentation: Each file now explains not just what the code does, but why that pattern was chosen (e.g., why ToolWithApproval throws errors instead of using a separate approval tool)
• Decision Rationale: Comments explain trade-offs and alternatives considered (e.g., why section-based batching in clause extraction vs. arbitrary fixed-size batching)
• Security Callouts: Explicit documentation of security patterns like userId injection and approval state management
• Architecture Diagrams: State machine diagrams and pipeline phase descriptions in comments for complex flows
• Production Guidance: Notes on what would change in production (e.g., mock tool handlers → real API calls)

Benefits

• Onboarding: New developers can understand each agent's purpose and architecture without external documentation
• Reusability: Clear pattern documentation makes it easier to apply these patterns to new agents
• Maintainability: Future changes are easier to make when the original design intent is documented
• Learning Resource: The examples now serve as a comprehensive guide to ADK patterns and best practices

https://claude.ai/code/session_01T3JektKdv293bQKWTRLb7o

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
adk-demo-brand-extractor	Ready	Preview, Comment	Feb 10, 2026 2:13am
adk-demo-clause	Ready	Preview, Comment	Feb 10, 2026 2:13am
adk-demo-deep-research	Ready	Preview, Comment	Feb 10, 2026 2:13am
adk-demo-guardrails	Ready	Preview, Comment	Feb 10, 2026 2:13am
adk-demo-trivia	Ready	Preview, Comment	Feb 10, 2026 2:13am