sorry, module ID changes again

No worries at all! Will update the import paths to v2 and re-test. Thanks for the heads up.

not sure all examples here are useful. handler creation and registration certainly are, but ExamplePassthroughCallInterceptor and ExampleWellKnownAgentCardPath are certainly not.

for passthrough interceptor we can do something like:

func ExamplePassthroughCallInterceptor() {
  type myInterceptor struct {
    a2asrv.PassthroughCallInterceptor
  }

  handler := a2asrv.NewHandler(&echoExecutor{}, a2asrv.WithCallInterceptors(myInterceptor{}))
  fmt.Println("Handler created:", handler != nil)
  // Output:
  // Handler created: true
}

to show it exists for embedding so that method implementations are not required.

some examples like ExampleNewCallContext, ExampleNewServiceParams are not very practical because that's not the code users usually call, these methods are exported for custom transport implementations. if examples are intended to help less skilled developers understand how to use the package, I'd rather focus on the code they are more likely to write, for example for user this might be:

func ExampleUser() {
  authenticate := func(_ string) string { return "user" }

  interceptor := &testInterceptor{
    BeforeFn: func(ctx context.Context, callCtx *a2asrv.CallContext, req *a2asrv.Request) (context.Context, any, error) {
      if auth, ok := callCtx.ServiceParams().Get("authorization"); ok && strings.HasPrefix(auth[0], "Bearer ") {
        if name := authenticate(auth[0]); name != "" {
          callCtx.User = a2asrv.NewAuthenticatedUser(name, nil)
        }
      }
      return ctx, nil, nil
    },
  }

  executor := &echoExecutor{
    ExecuteFn: func(_ context.Context, execCtx *a2asrv.ExecutorContext) iter.Seq2[a2a.Event, error] {
      return func(yield func(a2a.Event, error) bool) {
        fmt.Println("Auth found:", execCtx.User.Name)
        yield(a2a.NewMessage(a2a.MessageRoleAgent, a2a.NewTextPart("echo")), nil)
      }
    },
  }

  ctx, _ := a2asrv.NewCallContext(context.Background(), a2asrv.NewServiceParams(map[string][]string{
    "Authorization": {"Bearer token"},
  }))
  handler := a2asrv.NewHandler(executor, a2asrv.WithCallInterceptors(interceptor))
  _, err := handler.SendMessage(ctx, &a2a.SendMessageRequest{
    Message: a2a.NewMessage(a2a.MessageRoleUser, a2a.NewTextPart("echo")),
  })
  fmt.Println("Error:", err)
  // Output:
  // Auth found: user
  // Error: <nil>
}

for service params ideally it's a jsonrpc http request with headers which are accessed by an interceptor from callContext.

I understand it's tricky and requires a balance of readability&clarity vs showcasing advanced use cases, but I think examples should exist as preventive answers to questions people are likely to ask 🙂
wdyt

Agreed, makes much more sense to frame examples as answers to questions people are likely to ask rather than an API surface tour. Good call.

Here's what I'm thinking:

• Drop ExampleWellKnownAgentCardPath, ExampleWithCallInterceptors, ExampleCallContext_Extensions, ExampleNewCallContext, ExampleNewServiceParams
• Rework ExamplePassthroughCallInterceptor to show the embedding pattern
• Add ExampleUser with the auth interceptor flow as you suggested
• Add ExampleAgentExecutor showing a minimal streaming implementation (submit → working → artifact → completed)
• Add ExampleNewHandler_fullServer showing the typical wiring: executor → handler → agent card + JSON-RPC on a single mux
• Update all import paths to v2

Would you trim or adjust any of these? I'll apply the same approach to the a2aclient examples in #263.

sounds good 👍

extra good if it'll have ExampleServiceParams where an http request is made to show that a header ends up in callCtx.ServiceParams() of an interceptor.

the easiest setup for this will be a NewRESTHandler() and GET /tasks/123. the request will return task not found, but we'll only be interested in service params, so doesn't mattter

Hi @yarolegovich,

While implementing ExampleServiceParams with NewRESTHandler() and GET /tasks/{id} as you suggested, I noticed that HTTP headers don't seem to reach callCtx.ServiceParams() in the interceptor.

Looking at the code, NewRESTHandler handler methods pass req.Context() directly to the request handler without calling NewCallContext(ctx, NewServiceParams(req.Header)), while NewJSONRPCHandler does inject them in ServeHTTP (jsonrpc_server.go:50). Because of this, attachMethodCallContext creates a CallContext with nil ServiceParams.

Here's a minimal test that reproduces it:

func TestREST_ServiceParams(t *testing.T) {
	ctx := t.Context()
	tid := a2a.NewTaskID()
	task := &a2a.Task{ID: tid, ContextID: a2a.NewContextID()}
	store := testutil.NewTestTaskStore().WithTasks(t, task)

	var gotAuth []string
	interceptor := &testInterceptor{
		BeforeFn: func(ctx context.Context, callCtx *CallContext, req *Request) (context.Context, any, error) {
			gotAuth, _ = callCtx.ServiceParams().Get("authorization")
			return ctx, nil, nil
		},
	}

	handler := NewHandler(&mockAgentExecutor{}, WithTaskStore(store), WithCallInterceptors(interceptor))
	server := httptest.NewServer(NewRESTHandler(handler))
	defer server.Close()

	req, err := http.NewRequestWithContext(ctx, "GET", server.URL+"/tasks/"+string(tid), nil)
	if err != nil {
		t.Fatalf("http.NewRequestWithContext() error = %v", err)
	}
	req.Header.Set("Authorization", "Bearer test-token")

	resp, err := server.Client().Do(req)
	if err != nil {
		t.Fatalf("server.Client().Do() error = %v", err)
	}
	defer resp.Body.Close()

	if len(gotAuth) == 0 || gotAuth[0] != "Bearer test-token" {
		t.Errorf("ServiceParams[authorization] = %v, want [Bearer test-token]", gotAuth)
	}
}

Result:

=== RUN   TestREST_ServiceParams
    example_test.go:44: ServiceParams[authorization] = [], want [Bearer test-token]
--- FAIL: TestREST_ServiceParams (0.00s)

That said, I may be approaching this incorrectly or missing something about how the REST handler is intended to work — please let me know if that's the case.

Would you like me to open an issue for this? For ExampleServiceParams I can either wait for the fix and then write it with NewRESTHandler as you suggested, or use NewJSONRPCHandler in the meantime — whatever you prefer.

nice find, it was probably forgotten and we should fix it. whatever works better for you:

1. Open an issue, wait for the fix and proceed with REST
2. Use JSONRPC handler. I don't mind it, just thought that a raw REST request would be easier to craft.
3. Add the line which we have in jsonrpc handler for constructing call context to REST handler as part of your PR

Nice, thanks for confirming! I'll go with option 1 — I've opened #275 for this and will wait for the fix. REST feels more natural and simpler for users to understand in an example, so I'd rather keep it that way.

@yarolegovich all updated — reworked the examples per your feedback, updated import paths to v2, and ExampleServiceParams now uses NewRESTHandler after #275. All 10 examples pass. Ready for review when you get a chance.