feat: adka2a should provide a http.Handler #459

majiayu000 · 2026-01-01T22:57:08Z

Summary

This PR adds convenient http.Handler constructors to the adka2a package, addressing the feedback in #419.

New Functions

Function	Return Type	Description
`NewJSONRPCHandler`	`http.Handler`	Ready-to-use handler for A2A JSON-RPC transport
`NewServeMux`	`*http.ServeMux`	Complete server with agent card + invoke endpoints
`NewRequestHandler`	`a2asrv.RequestHandler`	Transport-agnostic handler for custom transports (gRPC, etc.)

Design Rationale

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

Complete abstraction: NewJSONRPCHandler and NewServeMux return standard library types (http.Handler / *http.ServeMux), so users don't need to know about a2asrv at all.
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
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

🤖 Generated with Claude Code

Add NewHandler function that creates and returns an http.Handler for the A2A JSON-RPC API. This follows the same pattern as the adkrest package, providing a convenient way to create an A2A handler without having to manually create the executor and wrap it with a2asrv handlers. Fixes google#419 Signed-off-by: majiayu000 <1835304752@qq.com>

gemini-code-assist · 2026-01-01T22:57:18Z

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 enhances the adka2a package by providing a convenient, pre-configured HTTP handler for its JSON-RPC API. This change abstracts away the manual setup of executors and request handlers, offering a streamlined way to integrate the A2A service into HTTP servers, mirroring existing patterns for ease of use and consistency.

Highlights

New HTTP Handler for A2A JSON-RPC API: Introduced a new NewHandler function that returns an http.Handler for the A2A JSON-RPC API, simplifying the setup process.
Handler Configuration: Added a HandlerConfig struct to provide a structured way to configure the A2A HTTP handler, including executor and A2A request handler options.
Consistent Pattern: The new handler implementation follows the established pattern seen in adkrest.NewHandler, ensuring consistency across the codebase.

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

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 new http.Handler for the A2A JSON-RPC API, simplifying the setup for consumers of this package. The implementation is clean and follows existing patterns. My review includes a minor suggestion to improve the test code by removing a redundant check. Overall, the changes look good and improve the library's API.

gemini-code-assist · 2026-01-01T22:58:23Z

server/adka2a/handler_test.go

+	if _, ok := handler.(http.Handler); !ok {
+		t.Fatal("NewHandler() did not return an http.Handler")
+	}


The function signature for NewHandler already specifies a return type of http.Handler. The Go compiler guarantees that the returned value will be of this type, so this type assertion is redundant. The nil check on line 43 is sufficient to ensure a valid handler was returned.

baptmont · 2026-01-02T11:27:52Z

server/adka2a/handler.go

+func NewHandler(config HandlerConfig) http.Handler {
+	executor := NewExecutor(config.ExecutorConfig)
+	reqHandler := a2asrv.NewHandler(executor, config.A2AOptions...)
+	return a2asrv.NewJSONRPCHandler(reqHandler)


This is very opinionated towards JSONRPC, I will revisit this PR after we confirm the intention behind the issue reported. Thank you for your contribution

majiayu000 · 2026-01-04T11:31:38Z

@baptmont Updated the change to be transport-agnostic: adka2a.NewRequestHandler now returns an a2asrv.RequestHandler that callers can wrap with the transport they want (e.g., a2asrv.NewJSONRPCHandler). Removed the JSONRPC-specific handler and the redundant type assertion in the test. Please take another look.

yarolegovich · 2026-01-04T13:01:44Z

I think it's a very shallow utility, which is close to a simple re-export of a function provided by a2a SDK. Developers will need to import a2asrv anyway to init server with infra connectors (a2asrv.WithTaskStore etc.), so why not just create a handler using a2asrv.NewHandler?

This addresses the review feedback by providing a higher-level API that eliminates the need for users to import and understand the a2asrv package. Changes: - NewJSONRPCHandler: Returns http.Handler directly (recommended for most users) - NewServeMux: Returns complete http.ServeMux with agent card + invoke endpoints - NewRequestHandler: Kept for custom transport layers (gRPC, etc.) - Updated HandlerConfig to include optional AgentCard field - Added comprehensive tests for all new functions - Updated example to use the simplified NewServeMux API Before (required understanding a2asrv): ```go executor := adka2a.NewExecutor(config) requestHandler := a2asrv.NewHandler(executor) mux.Handle("/invoke", a2asrv.NewJSONRPCHandler(requestHandler)) mux.Handle(a2asrv.WellKnownAgentCardPath, a2asrv.NewStaticAgentCardHandler(card)) ``` After (one-liner): ```go mux := adka2a.NewServeMux(adka2a.HandlerConfig{ ExecutorConfig: config, AgentCard: card, }) ``` 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>

majiayu000 · 2026-01-05T06:58:16Z

@yarolegovich Thanks for the feedback! I've refactored the implementation to address your concern.

The key insight from your comment was that returning a2asrv.RequestHandler alone doesn't provide enough value since users still need to import a2asrv.

In this update, I've taken a different approach with a layered API:

Function	Return Type	Use Case
`NewServeMux`	`*http.ServeMux`	One-liner setup with agent card + invoke endpoints
`NewJSONRPCHandler`	`http.Handler`	Integration with custom HTTP routers
`NewRequestHandler`	`a2asrv.RequestHandler`	Custom transports (gRPC, etc.)

The value proposition:

For common use cases (most users): NewServeMux and NewJSONRPCHandler return standard library types. Users don't need to import or understand a2asrv at all:

// Before: 5 lines, requires a2asrv import
mux := http.NewServeMux()
mux.Handle(a2asrv.WellKnownAgentCardPath, a2asrv.NewStaticAgentCardHandler(card))
executor := adka2a.NewExecutor(config)
requestHandler := a2asrv.NewHandler(executor)
mux.Handle("/invoke", a2asrv.NewJSONRPCHandler(requestHandler))

// After: 1 call, no a2asrv import needed
mux := adka2a.NewServeMux(adka2a.HandlerConfig{...})

For advanced users (need WithTaskStore, etc.): NewRequestHandler accepts ...a2asrv.RequestHandlerOption, so they can still use all the a2asrv options while benefiting from the convenience:

handler := adka2a.NewJSONRPCHandler(config, 
    a2asrv.WithTaskStore(customDB),
    a2asrv.WithPushNotifications(store, sender),
)

This follows the same pattern as adkrest.NewHandler - providing high-level convenience while preserving flexibility for advanced configurations.

Virt10n01

locale?
Diff.txt

gemini-code-assist bot reviewed Jan 1, 2026

View reviewed changes

baptmont approved these changes Jan 2, 2026

View reviewed changes

baptmont requested a review from yarolegovich January 2, 2026 11:20

baptmont requested changes Jan 2, 2026

View reviewed changes

refactor(adka2a): expose transport-agnostic request handler

305d57a

majiayu000 mentioned this pull request Jan 5, 2026

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

Closed

4 tasks

Virt10n01 reviewed Jan 6, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat: adka2a should provide a http.Handler #459

feat: adka2a should provide a http.Handler #459

Uh oh!

majiayu000 commented Jan 1, 2026 •

edited

Loading

Uh oh!

gemini-code-assist bot commented Jan 1, 2026

Uh oh!

gemini-code-assist bot left a comment

Uh oh!

gemini-code-assist bot Jan 1, 2026

Uh oh!

baptmont Jan 2, 2026

Uh oh!

majiayu000 commented Jan 4, 2026 •

edited

Loading

Uh oh!

yarolegovich commented Jan 4, 2026

Uh oh!

majiayu000 commented Jan 5, 2026

Uh oh!

Virt10n01 left a comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

feat: adka2a should provide a http.Handler #459

Are you sure you want to change the base?

feat: adka2a should provide a http.Handler #459

Uh oh!

Conversation

majiayu000 commented Jan 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

New Functions

Design Rationale

Before/After Comparison

Test Plan

Related Issues

Uh oh!

gemini-code-assist bot commented Jan 1, 2026

Summary of Changes

Highlights

Footnotes

Uh oh!

gemini-code-assist bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

gemini-code-assist bot Jan 1, 2026

Choose a reason for hiding this comment

Uh oh!

baptmont Jan 2, 2026

Choose a reason for hiding this comment

Uh oh!

majiayu000 commented Jan 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

yarolegovich commented Jan 4, 2026

Uh oh!

majiayu000 commented Jan 5, 2026

Uh oh!

Virt10n01 left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

majiayu000 commented Jan 1, 2026 •

edited

Loading

majiayu000 commented Jan 4, 2026 •

edited

Loading