[Feat]: Add Example_* test functions for a2aclient/ and a2asrv/ packages #257
Description
Is your feature request related to a problem? Please describe.
This is a follow-up to #209, which was addressed by #240 for the a2a/ core types package.
The a2aclient/ and a2asrv/ packages currently lack testable examples (Example_* functions) that render as runnable snippets on pkg.go.dev. Usage snippets exist in the respective doc.go files and the README, but they are not executable, not validated by go test, and do not appear as function-level examples in the generated documentation.
Describe the solution you'd like
Add example_test.go files following Go's ExampleXxx / ExampleType_Method naming convention for both the a2aclient/ and a2asrv/ packages (using v1 import paths: github.com/a2aproject/a2a-go/v1/a2aclient and github.com/a2aproject/a2a-go/v1/a2asrv).
Proposed examples for a2asrv/
| Function / Type | Example would demonstrate |
|---|---|
NewHandler |
Creating a basic request handler with an AgentExecutor |
NewJSONRPCHandler |
Wrapping a handler with JSON-RPC transport and registering it with http.ServeMux |
NewStaticAgentCardHandler |
Serving a static AgentCard on the well-known path |
NewAgentCardHandler |
Serving a dynamic AgentCard via a producer |
WithTaskStore |
Configuring a handler with a custom task store |
WithPushNotifications |
Enabling push notification support |
WithCallInterceptor |
Adding server-side middleware |
AgentExecutor (interface) |
Implementing a minimal agent executor that returns events |
Proposed examples for a2aclient/
| Function / Type | Example would demonstrate |
|---|---|
NewFromCard |
Creating a client from an AgentCard |
NewFromEndpoints |
Creating a client from known AgentInterface endpoints |
NewFactory |
Setting up a reusable client factory with shared options |
WithJSONRPCTransport |
Configuring JSON-RPC transport with a custom http.Client |
agentcard.DefaultResolver.Resolve |
Resolving an AgentCard from a URL |
AuthInterceptor |
Setting up credential-based authentication with InMemoryCredentialsStore |
WithCallInterceptors |
Adding client-side middleware |
Examples would use package a2aclient_test / package a2asrv_test (external test packages) to demonstrate the public API as an external consumer would use it. All examples would include // Output: comments and be validated by go test.
Describe alternatives you've considered
- Expanding README examples — helpful for high-level guidance, but they are not validated by the toolchain and do not appear in function-level documentation on pkg.go.dev.
- Adding examples inside existing
_test.gofiles — this would mix unit tests with documentation examples, reducing separation of concerns. A dedicatedexample_test.gofile is the idiomatic Go approach.
Additional context
I would be happy to open PRs implementing these examples. Given the recent release/spec-v1 promotion to main, I can rebase on latest at any point. If the maintainers consider it preferable to wait until the v1 SDK stabilizes further, I'm equally happy to hold off and submit once the timing is right.
I'd suggest splitting this into two PRs (one per package) to keep reviews focused, similar to the approach taken with #240.
Also, beyond a2aclient/ and a2asrv/, are there any other packages where you'd find this kind of testable examples valuable? I'd love to keep contributing in this direction wherever it's most useful for the project — just let me know and I'll be happy to pick them up.
Code of Conduct
- I agree to follow this project's Code of Conduct