[Feature] Support Method Extensions (Extended Skills) - RequestHandler to handle custom RPC methods

[mashiike]

Is your feature request related to a problem? Please describe.

a2a-go does not support method extensions (extension skills) as outlined in the A2A protocol document.
https://a2a-protocol.org/latest/topics/extensions/

Method Extensions (Extended Skills): Adding entirely new RPC methods beyond the core set defined by the protocol. An Extended Skill refers to a capability or function an agent gains or exposes specifically through the implementation of an extension that defines new RPC methods. For example, a task-history extension might add a tasks/search RPC method to retrieve a list of previous tasks, effectively providing the agent with a new, extended skill.

https://github.com/a2aproject/a2a-go/blob/main/a2asrv/jsonrpc.go#L109

The JSON-RPC handler uses a fixed switch statement that returns ErrMethodNotFound for methods outside the core set, and the RequestHandler interface does not provide a mechanism for implementing custom RPC methods defined by extensions. This makes it difficult for developers to implement the extensions outlined in the protocol specification.

Describe the solution you'd like

To support custom RPC methods defined by extensions, we propose adding a new optional interface that RequestHandler implementations can optionally implement. For example:

// Handler for arbitrary RPC methods defined by extensions.
// Receives the method name and params, and returns a result or error.
// Returns ErrMethodNotFound if the method is not supported.
// Does not affect existing RequestHandler implementations.
type ExtendedMethodHandler interface {
    OnExtendedMethod(ctx context.Context, method string, params json.RawMessage) (any, error)
}

Modify the default clause in jsonrpcHandler.handleRequest as follows, so that if the registered RequestHandler implements ExtendedMethodHandler, its method will be called:

   default:
        if ext, ok := h.handler.(ExtendedMethodHandler); ok {
            result, err = ext.OnExtendedMethod(ctx, req.Method, req.Params)
        } else {
            err = a2a.ErrMethodNotFound
        }

This change enables handling of extension methods without any breaking changes to existing developer. If necessary, similar hooks can be added to the gRPC transport layer to ensure all transports support extension methods.

Describe alternatives you've considered

No response

Additional context

No response

Code of Conduct

• I agree to follow this project's Code of Conduct

[yarolegovich]

That's a good discussion topic, thanks for bringing it up.
The JSONRPC case makes sense with what you're proposing, I'll need a bit more time to think about how ExtendedMethodHandler should be passed and how should extension composition be performed if you're using multiple method extensions.

REST and gRPC transports are less clear.
The SDK can probably still bring value here by invoking call-interceptors, but this perhaps can be handled by updating InterceptedHandler with methods like:

func (h *InterceptedHandler) Invoke(ctx context.Context, method string, request any) (any, error)
func (h *InterceptedHandler) InvokeStreaming(ctx context.Context, method string, request any) iter.Seq2[any, error]

The methods can also be reused for implementing the protocol-defined methods.
SDK users can then use them as utilities in another gRPC service or REST endpoint handler, which they will register themselves.

An alternative would be to come up with some interface like

type RESTMethodExtensions interface { ... }
type GRPCMethodExtensions interface { ... }

with the API sufficient for registering an extended API surface and seamlessly integrating interceptors.

[mashiike]

Thank you for your quick response.
You're right, considering other transport options, that seems like a better option.

—

For multiple methods, I think the implementer can handle it as long as the method is passed as an argument.
I think it would be fine for the SDK to provide a simple intervention interface.

[mashiike]

I’m currently reading through the gRPC-side code as well.

From what I can see, when the transport is gRPC, the server can support additional methods simply by defining new protobuf messages and adding them to the service. This part seems relatively straightforward on the server side.

However, after looking more closely, I’m starting to think the more important question is actually on the client side. The client transport layer is much more structured, so understanding how the client should handle extension methods might give us better hints about how the server-side implementation should handle them as well.

[yarolegovich]

From what I can see, when the transport is gRPC, the server can support additional methods simply by defining new protobuf messages and adding them to the service. This part seems relatively straightforward on the server side.

Yeah, with gRPC I think extension implementers should write their own services, these will be invoked through standard gRPC transport. There's a question of simple type reuse.

I made the first prototyping pass today, you can have a look at #138

[mashiike]

Thanks for sharing the PR — I’ve taken a look at it.
I really like the approach.

I had been thinking about how the client side should handle extended methods, and the idea of using generics for this was truly eye-opening.
This direction looks very promising.

Thanks for the prototype.