fix: Re-constructing Agent RPC URL in the AgentCard using the card's request attributes

[vladkol]

Re-constructing Agent RPC URL in the AgentCard using the card's request attributes

Current AgentCard request handler implementation in JSONRPCApplication and RESTAdapter return AgentCard with the agent's RPC url is it's originally created in code, often as local endpoints (e.g. http://localhost:8000).

Modern cloud runtime usually allows multiple ways to access deployed services. Some of them, such as load balancers may expose these services under vanity URLs. Others, like Google Cloud Run, have endpoint URLs dynamically assigned at a time of the deployment.

This PR adds "rewriting" of the agent's RPC url based on how the AgentCard was requested: with host, port, protocol and path adjusted according to the way the card's request was made. It accounts for deployments with load balancers, URL mapping, etc.

Fixes #398
Will also properly fix google/adk-python#2405

Release-As: 0.3.3

[gemini-code-assist]

Summary of Changes

Hello @vladkol, 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!

The pull request implements a crucial fix for how Agent RPC URLs are presented in AgentCard responses. Previously, these URLs might default to local endpoints (e.g., http://localhost:8000), which is problematic in modern cloud deployments that use dynamic URLs, load balancers, or URL mapping. This change introduces logic to dynamically reconstruct the Agent RPC URL based on the incoming request's attributes, including X-Forwarded-* headers, ensuring the AgentCard provides the correct, externally accessible URL for the agent.

Highlights

• Dynamic RPC URL Reconstruction: A new private method, _modify_rpc_url, has been introduced in both JSONRPCApplication and RESTAdapter to intelligently reconstruct the agent's RPC URL. This method leverages the incoming request's host, port, scheme, and path, and correctly interprets X-Forwarded-Host, X-Forwarded-Proto, and X-Forwarded-Path headers to determine the public-facing URL.
• AgentCard URL Correction: The _modify_rpc_url logic is now applied to both public and authenticated AgentCard responses. This ensures that the url field within the AgentCard accurately reflects the external endpoint from which the card was requested, rather than an internal or default URL.
• Enhanced Cloud Deployment Compatibility: By dynamically adjusting the RPC URL, this change significantly improves compatibility with cloud environments like Google Cloud Run, which assign dynamic endpoint URLs, and with setups involving load balancers or reverse proxies that use X-Forwarded-* headers.
• Comprehensive Test Coverage: New test cases have been added for both JSON-RPC and REST adapters to thoroughly validate the URL rewriting functionality under various scenarios, including different combinations of X-Forwarded-* headers and base URLs, ensuring the fix works as expected.

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 in your pull request via creating an issue comment (i.e. comment on the pull request page) using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands.

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 issue 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 introduces a valuable feature for dynamically reconstructing the agent's RPC URL based on request headers. This is a great addition for supporting deployments behind reverse proxies or in cloud environments. The implementation is well-tested for various scenarios.

My main feedback points are:

1. Code Duplication: The core logic in _modify_rpc_url is duplicated across JSONRPCApplication and RESTAdapter. This should be refactored into a single, shared utility function to improve maintainability. I've added a specific comment about this.
2. Potential Bug: There's a potential TypeError in the new _modify_rpc_url method if the request host is None. I've left inline comments with suggestions on how to fix this in both affected files.

[kthota-g]

It's not required for agent and agent_card to be hosted from the same url. For example, agent card may be hosted on http://example.com and the agent_card.url could be specified as http://agent.example.com. So, we can't default to using the forwarded headers for the url.

Card modifier should be used for this scenario so users can mutate the card as needed.