[Remote Agents] Add gRPC transport support

[alisa-alisa]

Summary

This PR introduces robust support for the A2A V0 protocol and enables native gRPC communication for remote agents using the latest @a2a-js/sdk. It focuses on standardizing agent card normalization, improving discovery reliability across different transport layers, and ensuring correct agent indexing within the registry.

Details

🛠 Core Improvements

• Native gRPC Support: Enabled gRPC communication by integrating GrpcTransportFactory and configuring secure/insecure credentials based on the agent's target URL.
• Consistent SSRF Protection: Implemented a standard-compliant safeFetch utility that mirrors the native fetch API. This protected implementation is used consistently across the codebase, including in AgentRegistry for card resolution/hashing and in A2AClientManager for agent communication. It enforces connection-level IP filtering and DNS rebinding protection (using safeLookup) to prevent internal network probing.
• Robust IP Address Validation: Replaced fragile regex-based IP range checks with the ipaddr.js library. This ensures more reliable and maintainable SSRF protection by correctly handling various IP notations (IPv4, IPv6, and IPv4-mapped IPv6) and matching them against standardized CIDR ranges.
• Content-Based Agent Acknowledgement: Implemented a more secure acknowledgement mechanism for remote agents. The registry now fetches and hashes the content of the AgentCard to detect modifications after initial approval, preventing Indirect Prompt Injection attacks that could result from modified remote agent configurations.
• DNS Rebinding Protection: Configured a secure lookup function in the undici dispatcher that filters private IP addresses at the connection level, ensuring SSRF checks cannot be bypassed using short-TTL DNS records.
• Robust URL Parsing: Replaced fragile string-based URL logic with the native URL API and direct object manipulation to ensure reliable agent discovery even in the presence of fragments or query parameters.
• Robust Card Normalization: Added comprehensive normalization logic in a2aUtils.ts to handle varied agent card formats, ensuring transport and url fields are consistently populated and discovery works reliably.
• A2A Server Configuration: Updated packages/a2a-server to respect enableAgents and agents settings, ensuring remote agents can be configured and used within the experimental A2A server environment.
• Registry Indexing: Ensured agents are indexed in the AgentRegistry using their (potentially overridden) name. This ensures that when an agent's name is modified via settings, the LLM can still correctly look up the agent's definition during tool execution. Added explicit validation to prevent name collisions during this process.
• Optimized URL Resolution: Resolved a "path doubling" bug where the SDK would incorrectly append .well-known to URLs that already contained the standard path.
• SDK Upgrade: Updated to @a2a-js/sdk@0.3.10 to leverage improved client factory patterns and better type safety.

🧪 Enhanced Test Coverage

• a2aUtils.test.ts: Validates "History Fallback" and conservative normalization.
• a2a-client-manager.test.ts: Tests protocol routing, robust URL resolution, and multi-layer SSRF protection including DNS rebinding scenarios.
• registry.test.ts: Added validation for canonical name indexing during registration.
• config.test.ts (a2a-server): Verified that agent settings are correctly propagated to the core configuration.

Related Issues

Closes ticket #18642.

How to Validate

1. Automated Tests

Run the comprehensive test suite:

npm test -w @google/gemini-cli-core -- src/agents/a2aUtils.test.ts src/agents/a2a-client-manager.test.ts src/agents/registry.test.ts

2. Live gRPC V0 Validation

Verify communication against the official A2A-Go reference implementation:

A. Prepare the Go Server (a2a-go repo)

1. Switch to V0 Handler: In examples/helloworld/server/grpc/main.go, update the import:
   • From: "github.com/a2aproject/a2a-go/a2agrpc/v1"
   • To: "github.com/a2aproject/a2a-go/a2agrpc/v0"
2. Set Protocol Version: In a2a/core.go, ensure the Version constant is set to "0.1":
   • const Version ProtocolVersion = "0.1"
3. Run the server: go run examples/helloworld/server/grpc/main.go

B. Prepare the Gemini CLI (this repo)

1. Register the Agent: Create .gemini/agents/grpc-test-agent.md with:

   ---
   kind: remote
   name: grpc-test-agent
   agent_card_url: http://localhost:9001/.well-known/agent-card.json
   description: Manual test for gRPC V0
   ---

2. Enable Agents: In .gemini/settings.json, ensure agents are enabled:

   {
     "experimental": {
       "enableAgents": true
     }
   }

C. Verify Communication

1. Start A2A Server:

   DEBUG=true GEMINI_YOLO_MODE=true npm run start -w @google/gemini-cli-a2a-server

2. Trigger Test Message: In another terminal, call the agent via curl:

   curl -N -X POST http://localhost:56474/ \
     -H "Content-Type: application/json" \
     -d '{
       "jsonrpc": "2.0",
       "id": "1",
       "method": "message/stream",
       "params": {
         "message": {
           "kind": "message",
           "role": "user",
           "parts": [{ "kind": "text", "text": "Hello, call the grpc-test-agent tool and say hi" }],
           "messageId": "test-final-attempt",
           "metadata": {
             "coderAgent": {
               "kind": "agent-settings",
               "workspacePath": "'$(pwd)'"
             }
           }
         }
       }
     }'

3. Expected Result: Verify the "Hello, world!" response is received correctly in the stream.

[alisa-alisa]

/gemini review

[gemini-cli]

Hi @alisa-alisa, thank you so much for your contribution to Gemini CLI! We really appreciate the time and effort you've put into this.

We're making some updates to our contribution process to improve how we track and review changes. Please take a moment to review our recent discussion post: Improving Our Contribution Process & Introducing New Guidelines.

Key Update: Starting January 26, 2026, the Gemini CLI project will require all pull requests to be associated with an existing issue. Any pull requests not linked to an issue by that date will be automatically closed.

Thank you for your understanding and for being a part of our community!

[github-actions]

Size Change: +242 kB (+0.93%)

Total Size: 26.2 MB

Filename	Size	Change
./bundle/gemini.js	25.7 MB	+242 kB (+0.95%)

ℹ️ View Unchanged

Filename	Size
./bundle/node_modules/@google/gemini-cli-devtools/dist/client/main.js	221 kB
./bundle/node_modules/@google/gemini-cli-devtools/dist/src/_client-assets.js	227 kB
./bundle/node_modules/@google/gemini-cli-devtools/dist/src/index.js	11.5 kB
./bundle/node_modules/@google/gemini-cli-devtools/dist/src/types.js	132 B
./bundle/sandbox-macos-permissive-open.sb	890 B
./bundle/sandbox-macos-permissive-proxied.sb	1.31 kB
./bundle/sandbox-macos-restrictive-open.sb	3.36 kB
./bundle/sandbox-macos-restrictive-proxied.sb	3.56 kB
./bundle/sandbox-macos-strict-open.sb	4.82 kB
./bundle/sandbox-macos-strict-proxied.sb	5.02 kB

_{compressed-size-action}

[gemini-code-assist]

Code Review

This pull request enhances remote agent support by integrating native gRPC communication via @a2a-js/sdk, improving agent card normalization, registry indexing, and URL resolution, with expanded test coverage. However, the resolveAgentCard method fetches remote agent cards from user-supplied URLs without sufficient validation, introducing a high-severity Server-Side Request Forgery (SSRF) vulnerability. Additionally, the current URL parsing logic is fragile and could lead to incorrect agent card resolution in edge cases. It is recommended to implement robust URL validation for agent card discovery.

[alisa-alisa]

/gemini review

[gemini-code-assist]

Code Review

This pull request introduces support for gRPC transport in the A2A client manager and enhances agent configuration and security. Key changes include updating @a2a-js/sdk, @bufbuild/protobuf, and @grpc/grpc-js dependencies, and extending the Settings interface to include experimental.enableAgents and agents overrides. The A2AClientManager now configures ClientFactory with gRPC, REST, and JSON-RPC transports, and includes new logic to normalize agent card URLs, handle .well-known paths, and implement Server-Side Request Forgery (SSRF) protection by rejecting private IP ranges for remote agents (except localhost). The a2aUtils module was updated with normalizeAgentCard to ensure consistent agent card structures and getGrpcCredentials for dynamic gRPC credential handling. The review comment highlights a critical security vulnerability: the current SSRF protection only validates the initial agent card URL, but not URLs specified within the agent card manifest itself (e.g., url or additionalInterfaces fields), which could allow an attacker to redirect connections to internal services. The reviewer recommends extending isPrivateIp validation to all URLs extracted from the agent card before client initialization.

[alisa-alisa]

/gemini review

[gemini-code-assist]

Code Review

This pull request introduces significant enhancements for remote agent communication by adding native gRPC support and upgrading the A2A SDK. It also includes comprehensive agent card normalization, a fix for registry indexing using canonical names, and thorough test coverage, improving functionality and robustness. However, a high-severity vulnerability has been identified: the implemented 'Deep SSRF Protection' is incomplete. It relies solely on string-based hostname checks and lacks DNS resolution, making it susceptible to bypasses via attacker-controlled domains that resolve to private IPs. This undermines the explicit goal of preventing access to sensitive private IP ranges like AWS/GCP metadata services.

[alisa-alisa]

/gemini review

[gemini-code-assist]

Code Review

This pull request introduces significant enhancements for remote agent communication, including native gRPC support and robust, multi-layered SSRF protection. While the changes are well-structured and include comprehensive tests, the implemented SSRF protection has weaknesses, including bypasses via 0.0.0.0/:: and vulnerability to DNS rebinding, which need to be addressed for robust security. Furthermore, a high-severity issue was identified in the URL parsing logic that could lead to incorrect agent card resolution when a URL contains a specially crafted fragment.

[alisa-alisa]

/gemini review

[gemini-code-assist]

Code Review

This pull request adds valuable support for gRPC transport in remote agents and introduces significant security enhancements against SSRF attacks. However, a high-severity bypass was identified in the IP address validation logic due to incomplete coverage of IPv6 representations, specifically IPv4-mapped IPv6 addresses, which could allow an attacker to bypass the SSRF filters and access internal resources. Furthermore, the DNS rebinding protection, implemented via a custom undici lookup function, does not extend to gRPC connections, leaving the gRPC transport susceptible to SSRF attacks.

[alisa-alisa]

/gemini review

[gemini-code-assist]

Code Review

This pull request introduces significant enhancements by adding native gRPC transport support for remote agents and implementing multi-layered SSRF protection. The changes are extensive and well-structured, including robust URL normalization, DNS rebinding protection, and improved test coverage. I've identified a critical security issue in the regular expression used for validating IPv4-mapped IPv6 addresses, which could potentially allow for an SSRF bypass. The detailed comment for the fix has been retained as it does not contradict any provided rules.

_{Note: Security Review did not run due to the size of the PR.}

[alisa-alisa]

/gemini review

[gemini-code-assist]

Code Review

This pull request introduces robust support for gRPC transport for remote agents, along with significant security enhancements, including native gRPC integration, deep SSRF protection, DNS rebinding mitigation, and more robust agent card normalization. However, critical security vulnerabilities have been identified in the SSRF implementation, specifically incomplete private IP range lists, fail-open behavior on DNS resolution failures, and a DNS rebinding vulnerability in the new safeFetch utility. These issues could allow an attacker to bypass SSRF protections and access internal network services. Additionally, there is critical feedback regarding the DNS pinning logic for gRPC that needs to be addressed to ensure its correctness and security.

[alisa-alisa]

/gemini review

[gemini-code-assist]

Code Review

This pull request introduces significant enhancements, most notably adding gRPC transport support for remote agents and implementing robust, multi-layered SSRF and DNS rebinding protection. However, a high-severity vulnerability was identified in the agent acknowledgement logic, where the use of a URL-based hash for remote agents allows for Indirect Prompt Injection if the remote agent card content is modified after initial approval. Implementing content-based hashing for acknowledgement is recommended to address this. Additionally, the IP address validation logic could be made more robust to further strengthen the new security measures.

[alisa-alisa]

/gemini review

[gemini-code-assist]

Code Review

This pull request introduces significant enhancements for remote agents, including gRPC support and robust security measures against SSRF and DNS rebinding. However, a critical Server-Side Request Forgery (SSRF) vulnerability was identified in the AgentRegistry. The new content-based hashing logic fetches remote agent cards without using the protected fetch implementation, specifically lacking DNS rebinding protection. This could allow an attacker to probe internal networks or access sensitive metadata services if a malicious agent configuration is loaded. Please ensure that security measures are consistently applied to prevent such attacks.

[alisa-alisa]

/gemini review

[gemini-code-assist]

Code Review

This pull request introduces significant enhancements, most notably adding gRPC transport support for remote agents and implementing robust, multi-layered SSRF protection. The use of ipaddr.js for reliable IP validation and a custom safeLookup function for DNS rebinding protection are excellent security improvements. The change to content-based hashing for agent acknowledgement is a critical fix to prevent potential prompt injection attacks. I've found one critical security issue where the new safeFetch implementation was not used in one of the new code paths, which I've detailed in a specific comment. Otherwise, the code is well-structured, the new tests are comprehensive, and the changes align well with the project's goals of being a powerful and secure tool.

_{Note: Security Review did not run due to the size of the PR.}

[alisa-alisa]

/gemini review

[gemini-code-assist]

Code Review

This pull request introduces significant and well-executed improvements for remote agent communication, notably adding gRPC support and robust security enhancements. The implementation of multi-layered SSRF protection, including connection-level DNS filtering with safeLookup and content-based hashing for agent acknowledgement, is excellent. The move to ipaddr.js for IP validation and the fixes for URL normalization and registry indexing greatly improve the system's reliability. I have one critical comment regarding the handling of Request objects in a new fetch wrapper, which could lead to incorrect request methods being used.

[alisa-alisa]

/gemini review

[gemini-code-assist]

Code Review

This pull request introduces significant and well-implemented enhancements, particularly in adding gRPC support and robust SSRF protection for remote agents. The use of ipaddr.js, connection-level IP filtering, and content-based hashing for agent acknowledgement are excellent security improvements. However, the critical issue identified in the agent registration logic, which breaks name overrides, remains. Please see the detailed comment for more information.

[alisa-alisa]

/gemini review

[gemini-code-assist]

Code Review

This pull request introduces significant enhancements by adding gRPC transport support for remote agents and implementing a robust, multi-layered defense against Server-Side Request Forgery (SSRF) vulnerabilities. The changes are comprehensive, including native gRPC integration, consistent SSRF protection through a new safeFetch utility, improved IP validation using ipaddr.js, and DNS rebinding protection. The agent acknowledgement mechanism has been hardened with content-based hashing, and agent card normalization and URL handling have been made more reliable. The codebase is cleaner and more secure as a result. The changes are well-tested, with new unit and integration tests covering the new functionality and security features. After a thorough review, I found no issues of high or critical severity. The implementation is solid and demonstrates excellent attention to security and correctness.