review comments

Signed-off-by: Jet Chiang <pokyuen.jetchiang-ext@solo.io>

Author: supreme-gg-gg

go/api/config/crd/bases/kagent.dev_agents.yaml

@@ -7722,9 +7722,7 @@ spec:
                                 type: string
                               type: array
                           required:
-                          - id
                           - name
-                          - tags
                           type: object
                         minItems: 1
                         type: array

go/api/config/crd/bases/kagent.dev_sandboxagents.yaml

@@ -5380,9 +5380,7 @@ spec:
                                 type: string
                               type: array
                           required:
-                          - id
                           - name
-                          - tags
                           type: object
                         minItems: 1
                         type: array

go/api/v1alpha2/agent_types.go

@@ -26,8 +26,6 @@ import (
 	"k8s.io/apimachinery/pkg/runtime/schema"
 	"k8s.io/apimachinery/pkg/types"
 	"sigs.k8s.io/controller-runtime/pkg/client"
-
-	"trpc.group/trpc-go/trpc-a2a-go/server"
 )
 
 // AgentType represents the agent type
@@ -529,7 +527,23 @@ type A2AConfig struct {
 	Skills []AgentSkill `json:"skills,omitempty"`
 }
 
-type AgentSkill server.AgentSkill
+// AgentSkill describes a specific capability or function of the agent.
+type AgentSkill struct {
+	// ID is the unique identifier for the skill.
+	ID string `json:"id,omitempty"`
+	// Name is the human-readable name of the skill.
+	Name string `json:"name"`
+	// Description is an optional detailed description of the skill.
+	Description string `json:"description,omitempty"`
+	// Tags are optional tags for categorization.
+	Tags []string `json:"tags,omitempty"`
+	// Examples are optional usage examples.
+	Examples []string `json:"examples,omitempty"`
+	// InputModes are the supported input data modes/types.
+	InputModes []string `json:"inputModes,omitempty"`
+	// OutputModes are the supported output data modes/types.
+	OutputModes []string `json:"outputModes,omitempty"`
+}
 
 const (
 	AgentConditionTypeAccepted            = "Accepted"

go/api/v1alpha2/zz_generated.deepcopy.go

@@ -60,7 +60,6 @@ func (a *handlerMux) SetAgentHandler(
 	card a2atype.AgentCard,
 	tracing middleware,
 ) error {
-	// TODO(cleanup): Replace this protocol mux with the standard v1 handler stack once legacy clients/runtimes are unsupported.
 	requestHandler := NewPassthroughRequestHandler(client, &card)
 	legacyJSONRPCHandler := a2av0.NewJSONRPCHandler(requestHandler)
 	v1JSONRPCHandler := a2asrv.NewJSONRPCHandler(requestHandler)

go/core/internal/a2a/a2a_handler_mux.go

@@ -6,7 +6,6 @@ import (
 	"net"
 	"net/http"
 	"reflect"
-	"time"
 
 	a2atype "github.com/a2aproject/a2a-go/v2/a2a"
 	a2aclient "github.com/a2aproject/a2a-go/v2/a2aclient"
@@ -42,9 +41,6 @@ func NewA2ARegistrar(
 	a2aBaseUrl string,
 	sandboxA2ABaseURL string,
 	authenticator auth.AuthProvider,
-	_ int,
-	_ int,
-	_ time.Duration,
 ) (*A2ARegistrar, error) {
 	if clientRegistry == nil {
 		return nil, fmt.Errorf("clientRegistry must not be nil")
@@ -170,7 +166,7 @@ func (a *A2ARegistrar) upsertAgentHandler(ctx context.Context, agent v1alpha2.Ag
 		// Keep legacy fallback during rollout so old agent pods continue to serve traffic.
 		filterInterfacesByVersion(card.SupportedInterfaces, a2atype.ProtocolVersion("0.3")),
 		a2aclient.WithJSONRPCTransport(httpClient),
-		// TODO(cleanup): Remove the compat transport after legacy runtimes are unsupported.
+		// TODO(0.11.0): Remove the compat transport after legacy runtimes are unsupported.
 		a2aclient.WithCompatTransport(
 			a2atype.ProtocolVersion("0.3"),
 			a2atype.TransportProtocolJSONRPC,
@@ -204,19 +200,22 @@ func (a *A2ARegistrar) upsertAgentHandler(ctx context.Context, agent v1alpha2.Ag
 	return nil
 }
 
+// debugHTTPClient returns nil in normal operation, letting the a2aclient SDK apply its
+// default 3-minute request timeout. In debug mode it overrides the dial target so all
+// A2A traffic is redirected to a fixed address (e.g. a local proxy).
 func debugHTTPClient() *http.Client {
 	debugAddr := env.KagentA2ADebugAddr.Get()
-	if debugAddr != "" {
-		client := new(http.Client)
-		client.Transport = &http.Transport{
+	if debugAddr == "" {
+		return nil
+	}
+	return &http.Client{
+		Transport: &http.Transport{
 			DialContext: func(ctx context.Context, network, addr string) (net.Conn, error) {
 				var zeroDialer net.Dialer
 				return zeroDialer.DialContext(ctx, network, debugAddr)
 			},
-		}
-		return client
+		},
 	}
-	return &http.Client{}
 }
 
 func (a *A2ARegistrar) a2aRouteURL(agent v1alpha2.AgentObject) string {

go/core/internal/a2a/a2a_registrar.go

@@ -10,6 +10,10 @@ import (
 	"k8s.io/apimachinery/pkg/types"
 )
 
+// staticHeadersInterceptor injects agent-level static headers (e.g. API keys, tenant IDs)
+// into every outgoing A2A call. Headers are fixed at construction time so they are never
+// re-resolved per request, which makes the interceptor safe for concurrent calls.
+// Currently this is only used for testing in invoke_api_test.go
 type staticHeadersInterceptor struct {
 	a2aclient.PassthroughInterceptor
 	headers map[string]string
@@ -28,6 +32,11 @@ func (s *staticHeadersInterceptor) Before(ctx context.Context, req *a2aclient.Re
 	return ctx, nil, nil
 }
 
+// upstreamAuthInterceptor applies per-request auth when the controller proxies an A2A call
+// to a managed agent. Auth must be evaluated per request because the session principal is only
+// available in the call context, not at agent registration time. It also propagates W3C
+// TraceContext so distributed traces span across the controller→agent hop without agents
+// needing to handle propagation themselves.
 type upstreamAuthInterceptor struct {
 	a2aclient.PassthroughInterceptor
 	authProvider auth.AuthProvider

go/core/internal/a2a/client_interceptors.go

@@ -40,7 +40,7 @@ func GetA2AAgentCard(agent v1alpha2.AgentObject) *a2atype.AgentCard {
 			card.Skills = append(card.Skills, a2atype.AgentSkill{
 				ID:          skill.ID,
 				Name:        skill.Name,
-				Description: derefString(skill.Description),
+				Description: skill.Description,
 				Tags:        skill.Tags,
 				Examples:    skill.Examples,
 				InputModes:  skill.InputModes,
@@ -50,10 +50,3 @@ func GetA2AAgentCard(agent v1alpha2.AgentObject) *a2atype.AgentCard {
 	}
 	return &card
 }
-
-func derefString(s *string) string {
-	if s == nil {
-		return ""
-	}
-	return *s
-}

go/core/internal/controller/translator/agent/utils.go

@@ -355,7 +355,7 @@ func (h *SessionsHandler) HandleListTasksForSession(w ErrorResponseWriter, r *ht
 
 	log.Info("Successfully retrieved session tasks", "count", len(tasks))
 
-	// TODO(cleanup): Remove legacy API conversion after legacy wire support is no longer supported.
+	// TODO(0.11.0): Remove legacy API conversion after legacy wire support is no longer supported.
 	switch wireVersion {
 	case utils.A2AWireVersionLegacy:
 		legacyTasks := make([]any, 0, len(tasks))

go/core/internal/httpserver/handlers/sessions.go

@@ -45,7 +45,7 @@ func (h *TasksHandler) HandleGetTask(w ErrorResponseWriter, r *http.Request) {
 	}
 
 	log.Info("Successfully retrieved task")
-	// TODO(cleanup): Remove legacy API conversion after legacy wire support is no longer supported.
+	// TODO(0.11.0): Remove legacy API conversion after legacy wire support is no longer supported.
 	// Currently this will return either legacy or v1 task depending on the wire version
 	var data any
 	switch wireVersion {
@@ -76,7 +76,7 @@ func (h *TasksHandler) HandleCreateTask(w ErrorResponseWriter, r *http.Request)
 	}
 
 	task := a2a.Task{}
-	// TODO(cleanup): Remove legacy API conversion after legacy wire support is no longer supported.
+	// TODO(0.11.0): Remove legacy API conversion after legacy wire support is no longer supported.
 	switch wireVersion {
 	case utils.A2AWireVersionLegacy:
 		legacyTask := protocol.Task{}