Feat/web artifact metadata 3710

[sarojrout]

Please ensure you have read the contribution guide before creating a pull request.

Link to Issue or Description of Change

1. Link to an existing issue (if applicable):

• Closes: #3710
• Related: #N/A

2. Or, if no issue exists, describe the change:

If applicable, please follow the issue templates to provide as much detail as possible.

Problem: The web FastAPI server exposes only artifact content endpoints, so HTTP/web clients cannot read ArtifactVersion metadata that contains custom_metadata, canonical_uri, or timestamps. Features like context offloading rely on that metadata, which means the sample currently only works inside Python runners and not via the web API.

Solution: Add two metadata-focused endpoints (/versions/metadata and /versions/{id}/metadata) that proxy the existing artifact-service methods, wire them into the conformance HTTP client, and add regression tests. This makes the web API feature-complete with the backend artifact service and enables context-offloading workflows over HTTP/SSE.

Testing Plan

Unit Tests:

• [x] I have added or updated unit tests for my change.
• [x] All unit tests pass locally.

uv run pytest tests/unittests/cli/test_fast_api.py uv run pytest tests/unittests/cli/conformance/test_adk_web_server_client.py

Manual End-to-End (E2E) Tests:

Not run; server changes verified via automated FastAPI + client tests. (If you need a manual scenario, start adk web, call the new metadata endpoints, and ensure the responses include customMetadata.)

Checklist

• [x] I have read the CONTRIBUTING.md document.
• [x] I have performed a self-review of my own code.
• [x] I have commented my code, particularly in hard-to-understand areas.
• [x] I have added tests that prove my fix is effective or that my feature works.
• [x] New and existing unit tests pass locally with my changes.
• [ ] I have manually tested my changes end-to-end.
• [x] Any dependent changes have been merged and published in downstream modules.

Additional context

The new endpoints mirror the existing content endpoints so HTTP clients can watch actions.artifactDelta and fetch metadata as needed.

[google-cla[bot]]

Thanks for your pull request! It looks like this may be your first contribution to a Google open source project. Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA).

View this failed invocation of the CLA check for more information.

For the most up to date status, view the checks section at the bottom of the pull request.

[adk-bot]

Response from ADK Triaging Agent

Hello @sarojrout, thank you for creating this PR!

It looks like you haven't signed the Contributor License Agreement (CLA) yet. Please visit https://cla.developers.google.com/ to sign it. This is a necessary step before we can review and merge your contribution.

Thanks!

[gemini-code-assist[bot]]

Summary of Changes

Hello @sarojrout, I'm Gemini Code Assist[^1]! 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 significantly enhances the ADK framework by expanding the web API's capabilities to include artifact metadata, which is vital for advanced workflows like context offloading. It also updates core infrastructure by bumping the minimum Python version and refining event handling, particularly for streaming and session management. Furthermore, the PR introduces new practical examples of agent development and improves the robustness and observability of existing integrations, such as BigQuery and MCP tools.

Highlights

• Web Artifact Metadata Endpoints: Introduced new FastAPI endpoints (/versions/metadata and /versions/{id}/metadata) to expose artifact version metadata, including custom metadata, canonical URIs, and timestamps. This enables web clients to access richer artifact information, crucial for features like context offloading over HTTP/SSE.
• Python Version Update: The minimum required Python version for the ADK project has been raised from 3.9+ to 3.10+, reflecting updated dependencies and development standards.
• New Sample Agents: Two new sample agents have been added: an adk_stale_agent for auditing GitHub issues and a hello_doctor agent demonstrating a health-oriented educational assistant. A rewind_session sample was also added to showcase session rewind functionality.
• Progressive SSE Streaming: Implemented initial support for progressive Server-Sent Events (SSE) streaming, allowing for more granular and ordered delivery of LLM response parts, including thoughts and function calls, enhancing real-time interaction capabilities.
• Enhanced BigQuery Plugin & Tooling: The BigQuery Agent Analytics Plugin now provides more detailed error messages for schema mismatches and improved logging for LLM requests. BigQuery tools now propagate the application_name to job labels for better tracking.
• Flexible Function Declaration for Tools: MCP tools and Anthropic LLM integration now support using parameters_json_schema and response_json_schema directly in function declarations, offering more flexibility and control over tool definitions.
• Improved Error Messaging for LLMs: Added enhanced error messaging for RESOURCE_EXHAUSTED (429) errors from Gemini models, providing developers with guidance on how to mitigate common rate-limiting issues.

Ignored Files

• Ignored by pattern: .github/workflows/** (11)
  • .github/workflows/analyze-releases-for-adk-docs-updates.yml
  • .github/workflows/check-file-contents.yml
  • .github/workflows/copybara-pr-handler.yml
  • .github/workflows/discussion_answering.yml
  • .github/workflows/isort.yml
  • .github/workflows/pr-triage.yml
  • .github/workflows/pyink.yml
  • .github/workflows/python-unit-tests.yml
  • .github/workflows/stale-bot.yml
  • .github/workflows/triage.yml
  • .github/workflows/upload-adk-docs-to-vertex-ai-search.yml

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 :thumbsup: and :thumbsdown: 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.

[^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.

[sarojrout]

Summary of Changes

Hello @sarojrout, I'm Gemini Code Assist1! 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 significantly enhances the ADK framework by expanding the web API's capabilities to include artifact metadata, which is vital for advanced workflows like context offloading. It also updates core infrastructure by bumping the minimum Python version and refining event handling, particularly for streaming and session management. Furthermore, the PR introduces new practical examples of agent development and improves the robustness and observability of existing integrations, such as BigQuery and MCP tools.

Highlights

• Web Artifact Metadata Endpoints: Introduced new FastAPI endpoints (/versions/metadata and /versions/{id}/metadata) to expose artifact version metadata, including custom metadata, canonical URIs, and timestamps. This enables web clients to access richer artifact information, crucial for features like context offloading over HTTP/SSE.
• Python Version Update: The minimum required Python version for the ADK project has been raised from 3.9+ to 3.10+, reflecting updated dependencies and development standards.
• New Sample Agents: Two new sample agents have been added: an adk_stale_agent for auditing GitHub issues and a hello_doctor agent demonstrating a health-oriented educational assistant. A rewind_session sample was also added to showcase session rewind functionality.
• Progressive SSE Streaming: Implemented initial support for progressive Server-Sent Events (SSE) streaming, allowing for more granular and ordered delivery of LLM response parts, including thoughts and function calls, enhancing real-time interaction capabilities.
• Enhanced BigQuery Plugin & Tooling: The BigQuery Agent Analytics Plugin now provides more detailed error messages for schema mismatches and improved logging for LLM requests. BigQuery tools now propagate the application_name to job labels for better tracking.
• Flexible Function Declaration for Tools: MCP tools and Anthropic LLM integration now support using parameters_json_schema and response_json_schema directly in function declarations, offering more flexibility and control over tool definitions.
• Improved Error Messaging for LLMs: Added enhanced error messaging for RESOURCE_EXHAUSTED (429) errors from Gemini models, providing developers with guidance on how to mitigate common rate-limiting issues.

Ignored Files

• Ignored by pattern: .github/workflows/** (11)

  • .github/workflows/analyze-releases-for-adk-docs-updates.yml
  • .github/workflows/check-file-contents.yml
  • .github/workflows/copybara-pr-handler.yml
  • .github/workflows/discussion_answering.yml
  • .github/workflows/isort.yml
  • .github/workflows/pr-triage.yml
  • .github/workflows/pyink.yml
  • .github/workflows/python-unit-tests.yml
  • .github/workflows/stale-bot.yml
  • .github/workflows/triage.yml
  • .github/workflows/upload-adk-docs-to-vertex-ai-search.yml

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. ↩

fixed these by rebuilding the branch again from upstream/main

[ryanaiagent]

Hi @sarojrout , Thanks for the Pull request. Can you please fix the lint errors using autoformat.sh before we proceed with the review .

[sarojrout]

Hi @ryanaiagent , i rebased and pushed again after resolving the merge conflicts and linting errors. pls review