feat: adding dynamic agent request handler

[richardanaya]

Description

Thank you for opening a Pull Request!
Before submitting your PR, there are a few things you can do to make sure it goes smoothly:

• ☑️ Follow the CONTRIBUTING Guide.
• [☑️Make your Pull Request title in the https://www.conventionalcommits.org/ specification.
  • Important Prefixes for release-please:
    • fix: which represents bug fixes, and correlates to a SemVer patch.
    • feat: represents a new feature, and correlates to a SemVer minor.
    • feat!:, or fix!:, refactor!:, etc., which represent a breaking change (indicated by the !) and will result in a SemVer major.
• ☑️ Ensure the tests and linter pass
• ☑️ Appropriate docs were updated (if necessary)

Fixes #134 🦕

---

• added support for dynamic agent, should be backwards compatible with existing servers in terms of boilerplate. I do auto-detection of how to handle the new request handler and support for nested urls inside of a2a_express_app.ts
• added samples for:
  * dynamic agent (calculator and weather agent served from same endpoint)
  * single agent servers (showing backward compatibility is same)
  * agent restricted by header authorization (showing new opportunities)

[gemini-code-assist]

Summary of Changes

Hello @richardanaya, 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 server-side capabilities by introducing dynamic agent routing. This feature allows developers to consolidate multiple agents under a single Express route, simplifying server configuration and making it easier to manage and extend agent-based applications. The included sample provides a clear example of how to implement and utilize this new dynamic routing pattern.

Highlights

• Dynamic Agent Request Handler: Introduced a new DynamicAgentRequestHandler class that allows a single server endpoint to host multiple agents by dynamically resolving the appropriate agent card, task store, and agent executor based on the incoming request's URL context.
• Express App Integration: The A2AExpressApp has been updated to support dynamic routing, enabling it to work seamlessly with the DynamicAgentRequestHandler. This includes new options to enable dynamic routing and methods to set the route context for the handler.
• New Sample Server: A new sample server (src/samples/servers/dynamic_agents/index.ts) has been added, demonstrating how to use the DynamicAgentRequestHandler to serve both a Calculator Agent and a Weather Agent from a single /agents route, showcasing the dynamic routing capabilities.

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 powerful DynamicAgentRequestHandler that allows a single server to host multiple agents, with routing determined by the request context (like the URL). The implementation uses a flexible resolver pattern and is well-integrated with the existing A2AExpressApp. The changes are accompanied by a clear sample application and unit tests.

My review focuses on a few key areas:

• Correctness: Ensuring state (like tasks) is managed correctly across requests in the new dynamic model.
• Maintainability: Reducing code duplication and improving type safety.
• Testing: Ensuring the new functionality is adequately tested.

I've identified a critical issue in the sample implementation regarding task store instantiation, which would lead to data loss. I've also found opportunities to refactor duplicated code in the Express app and improve type safety and testing. Overall, this is a great feature addition, and with these refinements, it will be even more robust and easier to maintain.

[richardanaya]

I think this is a at point it's worth looking at, and I have nothing more to add.