docs: add file upload handling pattern guide

[jpantsjoha]

Summary

Adds a new contributing/common_patterns.md guide with best practices for handling file uploads in agent tools.

Motivation

While building multi-agent solution architectures, discovered that handling both uploaded files and file path strings is a common pattern that isn't documented. This pattern helps agents gracefully process files regardless of upload method.

Without explicit instructions, agents may:

• Ask for file paths even when files are already uploaded
• Fail to recognize uploaded files as attachments
• Pass incorrect parameters to parsing tools

Changes

• New file: contributing/common_patterns.md with file upload pattern
• Updated: contributing/README.md to reference common patterns guide

Code Example

The pattern demonstrates flexible file path handling:

def parse_document(doc_path: str = "uploaded_document") -> str:
  """Parses a document (uploaded file or file path)."""
  # Handle both uploaded file identifiers and full paths
  if '/' in doc_path:
    run_id = os.path.basename(os.path.dirname(doc_path))
  else:
    run_id = doc_path.replace('.', '_')
  # ... parsing logic

And corresponding agent instructions:

agent = Agent(
  instruction="""
  When the user provides files:
  1. If files are uploaded directly in chat:
     - Call parsing tools with their display names
  2. If file paths are provided in text:
     - Call parsing tools with the exact paths
  """
)

Testing Plan

• Markdown formatting verified
• Links in README.md work correctly
• Code examples use correct Python syntax
• Pattern tested in customer solution architecture development work

Questions for Reviewers

• Should this live in adk-docs repo instead for better end-user visibility?
• Are there other common patterns we should document here?

Type

• Documentation
• Bug fix
• Feature
• Breaking change

Related

This pattern was discovered while building enterprise multi-agent solution architectures using A2A protocol and has proven valuable for file processing workflows.

---

Tags: #non-breaking

[gemini-code-assist]

Summary of Changes

Hello @jpantsjoha, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request introduces a new documentation guide aimed at standardizing and improving how ADK agents handle file uploads. The guide provides best practices for tools to accept both directly uploaded files and file paths, along with explicit agent instructions to prevent common pitfalls such as redundant path requests or failure to recognize attachments. This enhancement ensures agents can gracefully process files regardless of the upload method, contributing to more robust multi-agent solution architectures.

Highlights

• New Documentation Guide: A new guide, contributing/common_patterns.md, has been added to document best practices for handling file uploads in agent tools.
• README Update: The contributing/README.md file has been updated to include a new section and a link to the common_patterns.md guide.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request adds a valuable new guide for common development patterns, starting with file upload handling. The documentation is well-structured and the addition to the main contributing README improves discoverability. I've identified an issue in the Python code example within common_patterns.md where the logic for generating a run_id from a file path is incorrect and could lead to unexpected behavior. I've provided a suggestion to make it more robust and intuitive. Overall, this is a great addition to the project's documentation.

[gemini-code-assist]

The logic for generating run_id seems incorrect and could lead to unexpected behavior for a few reasons:

1. The check if '/' in doc_path: is not portable and will not work correctly on Windows systems, which use \ as a path separator.
2. For a full file path, os.path.basename(os.path.dirname(doc_path)) extracts the parent directory's name instead of the file's name. For example, with /path/to/reports/quarterly_report.pdf, run_id would become reports, which is likely not the intended behavior.

A more robust and intuitive approach is to extract the file's base name and then remove the extension. This works consistently for both full paths and simple display names, across different operating systems.

Suggested change

	if '/' in doc_path:
	# Full path provided
	run_id = os.path.basename(os.path.dirname(doc_path))
	else:
	# Uploaded file display name or simple identifier
	run_id = doc_path.replace('.', '_')
	# Get the base name, which is the final component of the path (e.g., "file.pdf").
	base_name = os.path.basename(doc_path)
	# Use the name without extension as the run_id (e.g., "file").
	run_id, _ = os.path.splitext(base_name)

[jpantsjoha]

Thank you @gemini-code-assist for the thorough review! I've applied the suggested fix using os.path.basename() and os.path.splitext() for robust cross-platform file path handling. This addresses all three issues:

1. ✅ Platform compatibility (Windows backslash support)
2. ✅ Correct filename extraction (not parent directory)
3. ✅ Cleaner run_id generation

The pattern now works consistently across all operating systems and for both full paths and display names.

[gemini-code-assist]

You're very welcome, @jpantsjoha! I'm glad to hear that the suggestions were helpful and that the updated approach using os.path.basename() and os.path.splitext() effectively addresses the platform compatibility, filename extraction, and run_id generation concerns. It's great to see the pattern now robustly handles file paths across different operating systems and input types. Excellent work!

[boyangsvl]

Hi @jpantsjoha , could you move these content to adk-docs repo? That's for public documentation.

[jpantsjoha]

Closing this PR as requested by @boyangsvl. The documentation content has been relocated to the correct repository.

New PR: google/adk-docs#785
Location: docs/tools/best-practices.md

Thank you for the guidance on proper repository structure!