feat(core): support authenticated A2A agent card discovery

[SandyTao520]

Summary

This PR enables support for A2A remote agents whose `AgentCard` discovery endpoint (`/.well-known/agent-card.json`) is protected by authentication. It also improves user feedback when agent discovery or registration fails.

Details

• Authenticated Discovery: Implemented logic in `AgentRegistry` and `A2AClientManager` to apply "bootstrap" credentials defined in the agent's Markdown frontmatter to the initial `AgentCard` fetch.
• HTTP Auth Provider: Added `HttpAuthProvider` to support Bearer and Basic authentication schemes, including dynamic value resolution ($ENV and !command).
• Error Surfacing: Updated `AgentRegistry` to catch and surface registration/discovery errors to the user via `coreEvents.emitFeedback`, replacing silent background warnings.
• Unit Testing: Added tests to `AgentRegistry.test.ts` to verify that discovery failures are correctly reported to the UI.

Related Issues

Closes #17607

How to Validate

1. Setup Secure Agent:
   • Create an agent definition in `.gemini/agents/secure.md` pointing to an A2A server that requires a Bearer token for its `/.well-known/agent-card.json`.
   • Include the correct `auth` block in the Markdown.
2. Verify Discovery:
   • Start the CLI (`npm run start`).
   • Confirm the agent is successfully registered and available in `@` mentions.
3. Verify Error Reporting:
   • Change the token in `.gemini/agents/secure.md` to an invalid one.
   • Restart the CLI.
   • Confirm an error message appears in the UI: `Error loading A2A agent "secure": 401 Unauthorized`.

Pre-Merge Checklist

• Updated relevant documentation and README (if needed)
• Added/updated tests (if needed)
• Noted breaking changes (if any)
• Validated on required platforms/methods:
  • MacOS
    • npm run

[gemini-code-assist]

Summary of Changes

Hello, 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 significantly enhances the A2A (Agent-to-Agent) communication capabilities by introducing robust support for authenticated remote agents. It allows agents to be discovered and registered even when their AgentCard endpoint requires authentication, improving the security and flexibility of agent integration. Additionally, it refines the user experience by providing clearer error messages for failed agent operations, moving away from silent failures to explicit feedback.

Highlights

• Authenticated Agent Card Discovery: Implemented logic in AgentRegistry and A2AClientManager to apply 'bootstrap' credentials, defined in the agent's Markdown frontmatter, to the initial AgentCard fetch. This enables support for A2A remote agents whose discovery endpoint is protected by authentication.
• HTTP Auth Provider: Added a new HttpAuthProvider to support Bearer and Basic authentication schemes, including dynamic value resolution for credentials (e.g., from environment variables or command output). This provider also includes retry logic for 401/403 responses to re-resolve dynamic credentials.
• Improved Error Surfacing: Updated AgentRegistry to catch and surface registration/discovery errors to the user via coreEvents.emitFeedback, replacing previous silent background warnings. This provides better user feedback when agent discovery or registration fails.
• Expanded Agent Markdown Configuration: Modified the agent Markdown parsing to allow for a generic value field in HTTP authentication configurations, enabling support for any IANA-registered HTTP authentication scheme beyond just Bearer and Basic.

Changelog

• packages/a2a-server/src/http/app.ts
  • Imported Request type from express.
  • Imported UnauthenticatedUser and UserBuilder from @a2a-js/sdk/server/express.
  • Configured coderAgentCard to include bearerAuth and basicAuth security schemes and security requirements.
  • Added a customUserBuilder function to handle Bearer and Basic authentication for incoming requests.
  • Updated A2AExpressApp instantiation to pass the customUserBuilder.
• packages/core/src/agents/agentLoader.test.ts
  • Added a test case to parse remote agents with Digest authentication using a raw value.
  • Added a test case to parse remote agents with a generic custom HTTP scheme using a raw value.
• packages/core/src/agents/agentLoader.ts
  • Modified FrontmatterAuthConfig to allow scheme to be any string and added an optional value field for raw authentication.
  • Updated httpAuthSchema to accept any string for scheme and included an optional value field.
  • Modified httpAuthSchema's superRefine logic to handle raw value authentication, bypassing token/username/password checks if value is present.
  • Updated convertFrontmatterAuthToConfig to return a configuration object with value if provided in the frontmatter, for generic HTTP schemes.
  • Adjusted the default case in convertFrontmatterAuthToConfig to throw an error for unknown HTTP schemes without a raw value.
• packages/core/src/agents/auth-provider/factory.ts
  • Imported HttpAuthProvider.
  • Implemented the creation of HttpAuthProvider for http authentication types in A2AAuthProviderFactory.
• packages/core/src/agents/auth-provider/http-provider.test.ts
  • Added a new test file for HttpAuthProvider.
  • Included tests for Bearer authentication, including environment variable resolution.
  • Included tests for Basic authentication.
  • Included tests for generic/raw authentication schemes like CustomScheme and Digest.
  • Added tests for the retry logic of HttpAuthProvider on 401 responses, including re-initialization and max retry limits.
• packages/core/src/agents/auth-provider/http-provider.ts
  • Added a new file defining the HttpAuthProvider class.
  • Implemented initialize method to resolve authentication credentials (token, username/password, or raw value) dynamically.
  • Implemented headers method to construct the Authorization header based on the configured scheme and resolved credentials.
  • Implemented shouldRetryWithHeaders method to re-resolve credentials and retry on 401/403 HTTP status codes.
• packages/core/src/agents/auth-provider/types.ts
  • Extended HttpAuthConfig to include a new union type for generic HTTP schemes, allowing a scheme string and a raw value string.
• packages/core/src/agents/registry.test.ts
  • Imported A2AAuthProviderFactory and A2AAuthProvider types.
  • Added a mock for A2AAuthProviderFactory.
  • Added a test case to verify that a remote agent with authentication configuration is registered correctly, using the A2AAuthProviderFactory.
  • Added a test case to surface an error if remote agent registration fails, verifying coreEvents.emitFeedback is called.
• packages/core/src/agents/registry.ts
  • Imported A2AAuthProviderFactory and AuthenticationHandler.
  • Wrapped agent registration calls in Promise.allSettled with individual try-catch blocks to surface errors via coreEvents.emitFeedback for user, project, and extension agents.
  • Modified registerAgent to conditionally create an AuthenticationHandler using A2AAuthProviderFactory if definition.auth is present, falling back to ADCHandler.
  • Updated error handling in registerAgent to emit a user-friendly error message via coreEvents.emitFeedback when A2A agent loading fails.
• packages/core/src/agents/remote-invocation.test.ts
  • Imported A2AAuthProviderFactory and A2AAuthProvider types.
  • Added a mock for A2AAuthProviderFactory.
  • Added a test case to ensure A2AAuthProviderFactory is used when authentication is present in the agent definition during remote agent invocation.
• packages/core/src/agents/remote-invocation.ts
  • Imported A2AAuthProviderFactory.
  • Modified authHandler property to be optional and initialized dynamically.
  • Added a getAuthHandler private method to create or retrieve the appropriate AuthenticationHandler, prioritizing A2AAuthProviderFactory if definition.auth is present, otherwise falling back to ADCHandler.
  • Updated clientManager.loadAgent to use the dynamically obtained authHandler.

Activity

• The author has validated the changes on MacOS.
• The author has validated the changes using npm run.
• Relevant documentation and README were updated.
• Tests were added/updated to cover the new functionality.

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

[github-actions]

Size Change: +1.54 kB (+0.01%)

Total Size: 25.8 MB

Filename	Size	Change
./bundle/gemini.js	25.3 MB	+1.54 kB (+0.01%)

ℹ️ 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 introduces critical security vulnerabilities related to dynamic value resolution in resolveAuthValue, including Remote Code Execution (RCE) via shell command execution and potential credential exfiltration, which violates the rule for sanitizing environment variable expansion in HTTP headers. The A2A server also contains hardcoded credentials. It is strongly recommended to address these security issues, particularly removing the shell command execution feature and implementing strict controls over environment variable resolution, before merging. Additionally, consider refactoring duplicated error handling logic in AgentRegistry for better maintainability.

[adamfweidman]

thanks! This should help with the UX Robustness as well!

Could we make this function a helper since we have it a few time? (it can take in scope: string to plut into user/project/extension)