fix: robust UX for remote agent errors

[Shyam-Raghuwanshi]

Add structured error handling for remote A2A agent initialization
with user-friendly error messages and actionable remediation steps.

Problem:
When connecting to remote agents failed (server down, wrong URL,
auth issues), users saw raw 'TypeError: fetch failed' with no
guidance on what went wrong or how to fix it.

Solution:

• Add a2a-errors.ts with typed error classes:

  • AgentCardNotFoundError (404)
  • AgentCardAuthError (401/403)
  • AgentAuthConfigMissingError (missing auth config)
  • AgentConnectionError (network/generic)
  • classifyAgentError() walks the full error cause chain to detect
    HTTP status codes buried in nested .cause objects (including
    plain-object causes from HTTP libraries)

• Update a2a-client-manager.ts: wrap loadAgent() to rethrow as
  classified errors

• Update registry.ts: emit user-facing feedback via
  coreEvents.emitFeedback() for each error type; validate auth
  config against agent card security schemes before registration

• Update remote-invocation.ts: add formatExecutionError() for
  contextual error messages during agent execution

• Add 21 test cases covering all error types, classification logic,
  and cause-chain inspection (including plain-object causes)

Fixes: #17658

• 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
    • npx
    • Docker
    • Podman
    • Seatbelt
  • Windows
    • npm run
    • npx
    • Docker
  • Linux
    • npm run
    • npx
    • Docker

[google-cla]

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.

[gemini-code-assist]

Summary of Changes

Hello @Shyam-Raghuwanshi, 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 improves the user experience when interacting with remote A2A agents by replacing generic, unhelpful error messages with structured, user-friendly feedback. It introduces a robust error handling system that classifies various failure modes during agent initialization and execution, such as network issues, authentication problems, or missing agent cards. This change provides users with clear explanations and actionable remediation steps, making it much easier to diagnose and resolve issues with remote agents.

Highlights

• Structured Error Handling: Introduced a new module (a2a-errors.ts) defining structured error classes (e.g., AgentCardNotFoundError, AgentCardAuthError, AgentConnectionError) for remote A2A agent operations, providing more specific and actionable error information.
• Intelligent Error Classification: Implemented classifyAgentError to intelligently parse raw errors, including deep inspection of error cause chains and plain-object causes, to categorize them into the new typed error classes.
• Enhanced Agent Loading: Modified A2AClientManager to wrap agent loading logic in a try-catch block, rethrowing raw errors as classified A2AAgentError instances for better error propagation.
• User Feedback and Auth Validation: Updated AgentRegistry to emit user-facing feedback via coreEvents.emitFeedback for classified errors during agent registration and added validation for authentication configurations against agent card security schemes.
• Contextual Execution Error Messages: Added a formatExecutionError method in RemoteAgentInvocation to provide more contextual and user-friendly error messages during remote agent execution, leveraging the new typed error system.
• Comprehensive Testing: Included 21 new test cases to cover all new error types, the error classification logic, and the cause-chain inspection mechanism, ensuring robustness.

Changelog

• packages/core/src/agents/a2a-client-manager.ts
  • Imported classifyAgentError for error classification.
  • Wrapped agent card loading logic in a try-catch block to classify and rethrow errors.
• packages/core/src/agents/a2a-errors.test.ts
  • Added a new test file for A2AAgentError types and the classifyAgentError function, including tests for cause chain inspection.
• packages/core/src/agents/a2a-errors.ts
  • Added a new file defining A2AAgentError as a base class.
  • Introduced specific error subclasses: AgentCardNotFoundError, AgentCardAuthError, AgentAuthConfigMissingError, and AgentConnectionError.
  • Implemented collectErrorMessages to extract messages from nested error causes.
  • Implemented classifyAgentError to categorize raw errors into the appropriate A2AAgentError subclass based on message patterns and cause chain analysis.
• packages/core/src/agents/registry.ts
  • Imported new A2A error types and A2AAuthProviderFactory.
  • Updated JSDoc comments to reflect robust error handling.
  • Added logic to validate authentication configuration against agent card security schemes.
  • Modified error handling in registerRemoteAgent to emit user-friendly feedback via coreEvents.emitFeedback for classified A2A errors.
• packages/core/src/agents/remote-invocation.ts
  • Imported new A2A error types.
  • Replaced generic error message generation with a call to the new formatExecutionError method.
  • Added formatExecutionError to provide contextual error messages during remote agent invocation based on the type of A2AAgentError.

Activity

• The pull request introduces a new error handling system for remote A2A agents.
• It defines several custom error classes to provide more specific feedback.
• Logic was added to classify raw errors, even those deeply nested, into these new types.
• The agent client manager was updated to use this new classification during agent loading.
• The agent registry now provides user-facing feedback for these classified errors and validates authentication configurations.
• Remote invocation errors are now formatted to be more user-friendly.
• Comprehensive tests were added to validate the new error handling logic.

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 introduces a robust and user-friendly error handling mechanism for remote A2A agent initialization, which is a great improvement over the previous raw error messages. The new typed error classes, classification logic, and comprehensive tests are well-implemented. I've found one area for improvement in packages/core/src/agents/remote-invocation.ts where specific error checks are redundant due to a generic handler. Simplifying this will improve maintainability.

[adamfweidman]

Thanks for the contribution, please make sure to sign the CLA @Shyam-Raghuwanshi

[Shyam-Raghuwanshi]

Hi @adamfweidman, I signed the CLA.

[SandyTao520]

Overall LGTM, left a few comments. Please resolve comments and merge main, also please add some tests for for registry.ts and remote-invocation.ts changes.

[adamfweidman]

This generally looks good to me @Shyam-Raghuwanshi, thanks for the contribution! Can you attach screenshots for some of the Agent Errors?

[Shyam-Raghuwanshi]

@adamfweidman

[adamfweidman]

@Shyam-Raghuwanshi thanks! Can you please include the agent name in the error message?

[Shyam-Raghuwanshi]

@adamfweidman done.

[adamfweidman]

/gemini review

[gemini-code-assist]

Code Review

This pull request introduces a comprehensive error handling and classification system for remote agent operations. It defines several custom error types, such as AgentCardNotFoundError and AgentConnectionError, each providing structured, user-friendly messages. A new classifyAgentError utility is implemented to categorize raw errors by thoroughly inspecting their messages and cause chains, including HTTP status codes and network error codes. This system is integrated into the A2AClientManager, AgentRegistry, and RemoteAgentInvocation components to ensure clear and actionable feedback for users when remote agents fail to load or execute. Additionally, the AgentRegistry now includes validation for authentication configurations, emitting warnings if required auth settings are missing. A review comment suggests refactoring the collectErrorMessages helper function to remove duplicated logic for extracting error properties, proposing a unified approach to handle both Error instances and plain objects for improved maintainability and type safety.

[adamfweidman]

/gemini review

[gemini-code-assist]

Code Review

This pull request refactors error handling for remote agent interactions by introducing a new set of custom A2AAgentError types and a classifyAgentError utility. The A2AClientManager now uses this utility to classify errors during agent loading, and the AgentRegistry and RemoteAgentInvocation components have been updated to leverage these structured errors, providing more user-friendly messages and emitting appropriate feedback (errors or warnings) to the user. Additionally, the AgentRegistry now validates authentication configurations against agent card security schemes, issuing warnings for missing authentication. The collectErrorMessages function in a2a-errors.ts should be improved to consistently validate the range of HTTP status codes before including them in collected error messages, mirroring the logic applied to plain objects.

[gemini-code-assist]

Code Review

This pull request introduces a robust error handling mechanism for remote A2A agent initialization, which is a significant improvement for user experience and debuggability. The introduction of typed error classes in a2a-errors.ts and the classifyAgentError function for inspecting the full error cause chain are well-implemented. The changes are consistently applied across a2a-client-manager, registry, and remote-invocation to ensure that structured, user-friendly error messages are surfaced to the user. The accompanying tests are comprehensive and cover a wide range of error scenarios, including nested and non-standard error objects. Overall, this is a high-quality contribution that enhances the reliability of the A2A agent feature.

[adamfweidman]

@Shyam-Raghuwanshi Thank you for your contribution!