feat(adka2a): add http.Handler constructors for simplified A2A server setup

[majiayu000]

Summary

This PR adds convenient http.Handler constructors to the adka2a package, addressing the feedback in #419 and providing a more ergonomic alternative to PR #459.

New Functions

Function	Description
NewJSONRPCHandler	Returns a ready-to-use http.Handler for A2A JSON-RPC transport
NewServeMux	Returns a complete http.ServeMux with both agent card and invoke endpoints
NewRequestHandler	Returns a transport-agnostic handler for custom transports (gRPC, etc.)

Design Rationale

The key insight from the review of #459 was that returning a2asrv.RequestHandler doesn't provide enough value—users still need to import a2asrv and wrap it themselves. This PR takes a different approach:

1. Complete abstraction: NewJSONRPCHandler and NewServeMux return standard library types (http.Handler / *http.ServeMux), so users don't need to know about a2asrv at all.

2. Layered API: Three functions at different abstraction levels:

   • NewServeMux - Highest level, one-liner server setup
   • NewJSONRPCHandler - Mid level, for custom routing
   • NewRequestHandler - Low level, for custom transports

3. Consistency with adkrest: Follows the same pattern as adkrest.NewHandler.

Before/After Comparison

Before (current):

mux := http.NewServeMux()
mux.Handle(a2asrv.WellKnownAgentCardPath, a2asrv.NewStaticAgentCardHandler(agentCard))

executor := adka2a.NewExecutor(adka2a.ExecutorConfig{...})
requestHandler := a2asrv.NewHandler(executor)
mux.Handle("/invoke", a2asrv.NewJSONRPCHandler(requestHandler))

After (with this PR):

mux := adka2a.NewServeMux(adka2a.HandlerConfig{
    ExecutorConfig: adka2a.ExecutorConfig{...},
    AgentCard:      agentCard,
})

Test Plan

• Added unit tests for all new functions
• Tests verify handler creation and basic HTTP responses
• All existing tests pass
• Updated example in examples/a2a/main.go to use new API

Related Issues

Fixes #419
Supersedes #459

🤖 Generated with Claude Code

[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 @majiayu000, 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 developer experience for setting up A2A (Agent-to-Agent) servers by introducing high-level http.Handler constructors. It aims to simplify the integration process, reduce boilerplate code, and provide a more intuitive API for exposing ADK agents via HTTP, addressing previous feedback and improving upon earlier design attempts.

Highlights

• Simplified A2A Server Setup: Introduces http.Handler constructors (NewJSONRPCHandler, NewServeMux, NewRequestHandler) in the adka2a package to streamline the setup of A2A servers, making it more ergonomic and abstracting away a2asrv details.
• New http.Handler Constructors: Three new functions are added: NewJSONRPCHandler provides a ready-to-use http.Handler for A2A JSON-RPC transport; NewServeMux returns a complete http.ServeMux with both agent card and invoke endpoints for a one-liner server setup; and NewRequestHandler offers a transport-agnostic handler for custom transports like gRPC.
• Layered API Design: The new functions provide a layered API with different abstraction levels: NewServeMux (highest), NewJSONRPCHandler (mid), and NewRequestHandler (low), catering to various integration needs and offering flexibility.
• Improved Abstraction: The new constructors return standard library types (http.Handler, *http.ServeMux), reducing the need for users to directly interact with or import a2asrv components, similar to the pattern seen in adkrest.NewHandler.

🧠 New Feature in Public Preview: You can now enable Memory to help Gemini Code Assist learn from your team's feedback. This makes future code reviews more consistent and personalized to your project's style. Click here to enable Memory in your admin console.

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 convenient http.Handler constructors that significantly simplify setting up an A2A server. The new layered API (NewServeMux, NewJSONRPCHandler, NewRequestHandler) is well-designed, providing flexibility for different use cases. The code is well-documented and includes a comprehensive set of unit tests. The example usage in examples/a2a/main.go clearly demonstrates the improvement in ergonomics.

My review includes a few suggestions to further improve the code:

• Refactoring to reduce code duplication in the new handlers.
• Improving test robustness by handling potential errors and adding more thorough verification.

Overall, this is a great contribution that improves the developer experience.

[gemini-code-assist]

To improve maintainability and reduce code duplication, NewJSONRPCHandler can be simplified by calling NewRequestHandler. Both functions currently duplicate the logic for creating an executor.

Suggested change

	executor := NewExecutor(config.ExecutorConfig)
	requestHandler := a2asrv.NewHandler(executor, opts...)
	return a2asrv.NewJSONRPCHandler(requestHandler)
	return a2asrv.NewJSONRPCHandler(NewRequestHandler(config, opts...))

[gemini-code-assist]

It's a good practice to handle errors, even in tests. The error from io.ReadAll is currently ignored. If io.ReadAll fails, json.Unmarshal will likely fail with a less informative error message. Please check the error to make the test more robust.

body, err := io.ReadAll(rec.Body)
if err != nil {
	t.Fatalf("failed to read response body: %v", err)
}

[gemini-code-assist]

This test verifies that NewRequestHandler and a2asrv.NewJSONRPCHandler don't return nil, but it doesn't actually test if the resulting handler works. To make this test more meaningful, consider adding an HTTP request to verify that the handler responds correctly, similar to what's done in TestNewJSONRPCHandler.

// The returned handler should be usable with different transports
// Wrap it with JSON-RPC transport to verify
jsonrpcHandler := a2asrv.NewJSONRPCHandler(handler)
if jsonrpcHandler == nil {
	t.Fatal("a2asrv.NewJSONRPCHandler() returned nil")
}

// Verify the handler responds to JSON-RPC requests
reqBody := `{"jsonrpc":"2.0","method":"message/send","params":{"message":{"role":"user","parts":[{"type":"text","text":"hello"}]}},"id":"1"}`
req := httptest.NewRequest(http.MethodPost, "/a2a/invoke", strings.NewReader(reqBody))
req.Header.Set("Content-Type", "application/json")
rec := httptest.NewRecorder()

jsonrpcHandler.ServeHTTP(rec, req)

if rec.Code != http.StatusOK {
	t.Errorf("handler returned status %d, want %d", rec.Code, http.StatusOK)
}