Merge branch 'main' into new-agent-card

Author: racinmat

.github/workflows/discussion_answering.yml

@@ -41,6 +41,5 @@ jobs:
           OWNER: 'google'
           REPO: 'adk-python'
           INTERACTIVE: 0
-          DISCUSSION_NUMBER: ${{ github.event.discussion.number }}
           PYTHONPATH: contributing/samples
-        run: python -m adk_answering_agent.main
+        run: python -m adk_answering_agent.main --discussion '${{ toJson(github.event.discussion) }}'

README.md

@@ -64,7 +64,7 @@ You can install the latest stable version of ADK using `pip`:
 pip install google-adk
 ```
 
-The release cadence is weekly.
+The release cadence is roughly bi-weekly.
 
 This version is recommended for most users as it represents the most recent official release.
 

contributing/samples/adk_agent_builder_assistant/instruction_embedded.template

@@ -26,7 +26,10 @@ Always reference this schema when creating configurations to ensure compliance.
 ## Workflow Guidelines
 
 ### 1. Discovery Phase
-- **ASK FOR ROOT DIRECTORY** upfront to establish working context
+- **ROOT DIRECTORY ESTABLISHMENT**:
+  * **FIRST**: Check SESSION CONTEXT section below for "Established Root Directory"
+  * **IF ESTABLISHED**: Use the existing session root directory - DO NOT ask again
+  * **IF NOT ESTABLISHED**: Ask user for root directory to establish working context
 - **MODEL PREFERENCE**: Always ask for explicit model confirmation when LlmAgent(s) will be needed
   * **When to ask**: After analyzing requirements and deciding that LlmAgent is needed for the solution
   * **MANDATORY CONFIRMATION**: Say "Please confirm what model you want to use" - do NOT assume or suggest defaults
@@ -159,8 +162,8 @@ Always reference this schema when creating configurations to ensure compliance.
 ### ADK Knowledge and Research Tools
 
 #### Web-based Research
-- **google_search_agent**: Search web for ADK examples, patterns, and documentation (built-in tool via sub-agent)
-- **url_context_agent**: Fetch and analyze content from URLs - GitHub, docs, examples (built-in tool via sub-agent)
+- **google_search_agent**: Search web for ADK examples, patterns, and documentation (returns full page content as results)
+- **url_context_agent**: Fetch content from specific URLs when mentioned in search results or user queries (use only when specific URLs need additional fetching)
 
 #### Local ADK Source Search
 - **search_adk_source**: Search ADK source code using regex patterns for precise code lookups
@@ -200,15 +203,17 @@ Always reference this schema when creating configurations to ensure compliance.
    * Analyze class relationships and usage patterns
 
 **For External Examples and Documentation:**
-- **google_search_agent**: Search to FIND relevant content and examples
+- **google_search_agent**: Search and analyze web content (returns full page content, not just URLs)
   * Search within key repositories: "site:github.com/google/adk-python ADK SequentialAgent examples"
   * Search documentation: "site:github.com/google/adk-docs agent configuration patterns"
   * Search sample repository: "site:github.com/google/adk-samples multi-agent workflow"
   * General searches: "ADK workflow patterns", "ADK tool integration patterns", "ADK project structure"
-- **url_context_agent**: Fetch and analyze FULL CONTENT of specific URLs identified through search
-  * Use after google_search_agent finds relevant URLs
-  * Fetch specific GitHub files, documentation pages, or examples
-  * Analyze complete implementation details and extract patterns
+  * Returns complete page content as search results - no need for additional URL fetching
+- **url_context_agent**: Fetch specific URLs only when:
+  * Specific URLs are mentioned in search results that need additional content
+  * User provides specific URLs in their query
+  * You need to fetch content from URLs found within google_search results
+  * NOT needed for general searches - google_search_agent already provides page content
 
 **Research for Agent Building:**
 - When user requests complex multi-agent systems: Search for similar patterns in samples

contributing/samples/adk_agent_builder_assistant/instruction_query.template

@@ -29,7 +29,10 @@ Always use the query_schema tool when you need specific ADK AgentConfig schema i
 ## Workflow Guidelines
 
 ### 1. Discovery Phase
-- **ASK FOR ROOT DIRECTORY** upfront to establish working context
+- **ROOT DIRECTORY ESTABLISHMENT**:
+  * **FIRST**: Check SESSION CONTEXT section below for "Established Root Directory"
+  * **IF ESTABLISHED**: Use the existing session root directory - DO NOT ask again
+  * **IF NOT ESTABLISHED**: Ask user for root directory to establish working context
 - **MODEL PREFERENCE**: Only ask for model preference when you determine that LlmAgent(s) will be needed
   * **When to ask**: After analyzing requirements and deciding that LlmAgent is needed for the solution
   * **DEFAULT**: Use "{default_model}" (your current model) if user doesn't specify
@@ -159,11 +162,16 @@ You have access to comprehensive tools for:
 3. **query_schema** - Query AgentConfig schema for field definitions
 
 **For External Examples and Documentation:**
-- **google_search_agent**: Search to FIND relevant content and examples
+- **google_search_agent**: Search and analyze web content (returns full page content, not just URLs)
   * Search within key repositories: "site:github.com/google/adk-python ADK SequentialAgent examples"
   * Search documentation: "site:github.com/google/adk-docs agent configuration patterns"
   * General searches: "ADK workflow patterns", "ADK tool integration patterns"
-- **url_context_agent**: Fetch and analyze FULL CONTENT of specific URLs identified through search
+  * Returns complete page content as search results - no need for additional URL fetching
+- **url_context_agent**: Fetch specific URLs only when:
+  * Specific URLs are mentioned in search results that need additional content
+  * User provides specific URLs in their query
+  * You need to fetch content from URLs found within google_search results
+  * NOT needed for general searches - google_search_agent already provides page content
 
 **Research for Agent Building:**
 - When user requests complex multi-agent systems: Search for similar patterns in samples
@@ -175,7 +183,7 @@ You have access to comprehensive tools for:
 
 ### When Creating Python Tools or Callbacks:
 1. **Always search for current examples first**: Use google_search_agent to find "ADK tool_context examples" or "ADK callback_context examples"
-2. **Reference contributing/samples**: Use url_context_agent to fetch specific examples from https://github.com/google/adk-python/tree/main/contributing/samples
+2. **Reference contributing/samples**: Use google_search_agent to find examples, or url_context_agent only if specific URLs are identified that need additional content
 3. **Look for similar patterns**: Search for tools or callbacks that match your use case
 4. **Use snake_case**: Function names should be snake_case (e.g., `check_prime`, `roll_dice`)
 5. **Remove tool suffix**: Don't add "_tool" to function names
@@ -184,12 +192,14 @@ You have access to comprehensive tools for:
 8. **Follow current ADK patterns**: Always search for and reference the latest examples from contributing/samples
 
 ### Research and Examples:
-- Use google_search_agent to find "ADK [use-case] examples" or "ADK [pattern] configuration"
-- Use url_context_agent to fetch examples from:
-  * GitHub repositories: https://github.com/google/adk-samples/
-  * Contributing examples: https://github.com/google/adk-python/tree/main/contributing
-  * Documentation: https://github.com/google/adk-docs
-  * Community examples and patterns
+- Use google_search_agent to find "ADK [use-case] examples" or "ADK [pattern] configuration" (returns full content)
+- Use url_context_agent only when:
+  * Specific URLs are found in search results that need additional content
+  * User provides specific URLs to analyze
+  * You need to fetch specific examples from identified URLs:
+    * GitHub repositories: https://github.com/google/adk-samples/
+    * Contributing examples: https://github.com/google/adk-python/tree/main/contributing
+    * Documentation: https://github.com/google/adk-docs
 - Adapt existing patterns to user requirements while maintaining compliance
 
 ## Important ADK Requirements

contributing/samples/adk_answering_agent/README.md

@@ -6,7 +6,7 @@ This agent can be operated in three distinct modes:
 
 - An interactive mode for local use.
 - A batch script mode for oncall use.
-- A fully automated GitHub Actions workflow (TBD).
+- A fully automated GitHub Actions workflow.
 
 ---
 
@@ -31,26 +31,37 @@ This will start a local server and provide a URL to access the agent's web inter
 
 ## Batch Script Mode
 
-The `answer_discussions.py` is created for ADK oncall team to batch process discussions.
+The `main.py` script supports batch processing for ADK oncall team to process discussions.
 
 ### Features
-* **Batch Process**: Taken either a number as the count of the recent discussions or a list of discussion numbers, the script will invoke the agent to answer all the specified discussions in one single run.
+* **Single Discussion**: Process a specific discussion by providing its number.
+* **Batch Process**: Process the N most recently updated discussions.
+* **Direct Discussion Data**: Process a discussion using JSON data directly (optimized for GitHub Actions).
 
-### Running in Interactive Mode
-To run the agent in batch script mode, first set the required environment variables. Then, execute the following command in your terminal:
+### Running in Batch Script Mode
+To run the agent in batch script mode, first set the required environment variables. Then, execute one of the following commands:
 
 ```bash
 export PYTHONPATH=contributing/samples
-python -m adk_answering_agent.answer_discussions --numbers 27 36 # Answer specified discussions
-```
 
-Or `python -m adk_answering_agent.answer_discussions --recent 10` to answer the 10 most recent updated discussions.
+# Answer a specific discussion
+python -m adk_answering_agent.main --discussion_number 27
+
+# Answer the 10 most recent updated discussions
+python -m adk_answering_agent.main --recent 10
+
+# Answer a discussion using direct JSON data (saves API calls)
+python -m adk_answering_agent.main --discussion '{"number": 27, "title": "How to...", "body": "I need help with...", "author": {"login": "username"}}'
+```
 
 ---
 
 ## GitHub Workflow Mode
 
-The `main.py` is reserved for the Github Workflow. The detailed setup for the automatic workflow is TBD.
+The `main.py` script is automatically triggered by GitHub Actions when new discussions are created in the Q&A category. The workflow is configured in `.github/workflows/discussion_answering.yml` and automatically processes discussions using the `--discussion` flag with JSON data from the GitHub event payload.
+
+### Optimization
+The GitHub Actions workflow passes discussion data directly from `github.event.discussion` using `toJson()`, eliminating the need for additional API calls to fetch discussion information that's already available in the event payload. This makes the workflow faster and more reliable.
 
 ---