Honor AI_AGENT and pass raw values through. (#1683)

## Why

The Go SDK detects AI coding agents and surfaces them as `agent/<name>`
in the User-Agent. Today the generic fallback (when no proprietary env
var fires) only honors the agents.md `AGENT=<name>` standard. Vercel's
`@vercel/detect-agent` library uses a parallel `AI_AGENT=<name>`
convention that tools in the Vercel ecosystem set instead; we currently
miss those.

Separately, the existing fallback coerces any unrecognized value to the
literal string `"unknown"`. That buries useful signal: a tool setting
`AI_AGENT=claude-code_2-1-141_agent` ends up as `agent/unknown`,
discarding the very signal (tool name plus version variant) we want to
see. Bucketing arbitrary names is an ETL concern, not the SDK's.

## Changes

Two behavior changes in `useragent/agent.go`:

1. **`AI_AGENT` fallback.** Add `AI_AGENT=<name>` as a secondary
fallback after `AGENT=<name>`. `AGENT` wins when both are set to
non-empty values; empty is treated as unset for both. Explicit product
matchers (e.g. `CLAUDECODE=1`) still always win over both.

2. **Raw passthrough instead of `"unknown"`.** Drop the known-product
lookup in the fallback. The value is piped through the existing
`Sanitize()` helper (so disallowed chars become `-` and the User-Agent
allowlist `[0-9A-Za-z_.+-]+` is satisfied) and capped at 64 chars to
keep the header bounded. Known products like `cursor` or `claude-code`
pass through unchanged because they already satisfy the allowlist.

Same change should land in `databricks-sdk-py` and
`databricks-sdk-java`; sibling PRs to follow.

## Test plan

- [x] `go test ./useragent/...` passes
- [x] `gofmt -l useragent/` clean
- [x] `AI_AGENT=<known product>` returns the product name
- [x] `AI_AGENT=<unrecognized>` returns the raw sanitized value (no
longer `"unknown"`)
- [x] `AGENT` wins over `AI_AGENT` when both are non-empty
- [x] Empty `AGENT` falls through to `AI_AGENT`
- [x] Disallowed chars in `AGENT` / `AI_AGENT` are sanitized to `-`
- [x] Values longer than 64 chars are truncated
- [x] Explicit matcher (e.g. `CLAUDECODE=1`) still wins over both
fallbacks

Author: renaudhartert-db

NEXT_CHANGELOG.md

@@ -6,6 +6,13 @@
 
 ### New Features and Improvements
 
+* Honor the Vercel `AI_AGENT=<name>` env var as a secondary fallback for
+  AI agent detection in the User-Agent header (after the agents.md
+  `AGENT=<name>` standard). Unrecognized fallback values now pass through
+  the User-Agent sanitized and length-capped at 64 chars instead of being
+  coerced to `agent/unknown`, so versioned variants such as
+  `claude-code_2-1-141_agent` surface as-is.
+
 ### Bug Fixes
 
 ### Documentation

useragent/agent.go

@@ -13,12 +13,24 @@ type knownAgent struct {
 	product string
 }
 
-// agentEnvVar is the agents.md standard env var. When set to a value we
-// don't specifically recognize, detection falls back to "unknown".
-const agentEnvVar = "AGENT"
+const (
+	// agentEnvVar is the agents.md standard env var.
+	agentEnvVar = "AGENT"
+
+	// aiAgentEnvVar is the Vercel @vercel/detect-agent convention. It
+	// serves the same purpose as agentEnvVar; agentEnvFallback consults it
+	// only when agentEnvVar is unset or empty.
+	aiAgentEnvVar = "AI_AGENT"
+
+	// maxAgentFallbackLen caps fallback values to keep the User-Agent
+	// bounded. Explicit-matcher products are short by construction; only
+	// the fallback path can carry arbitrary lengths.
+	maxAgentFallbackLen = 64
+)
 
 // listKnownAgents returns the canonical list of AI coding agents.
-// Keep this list in sync with databricks-sdk-py and databricks-sdk-java.
+// Keep this list, and the AGENT / AI_AGENT fallback handling in
+// agentEnvFallback, in sync with databricks-sdk-py and databricks-sdk-java.
 // Agents are listed alphabetically by product name.
 func listKnownAgents() []knownAgent {
 	return []knownAgent{
@@ -43,19 +55,16 @@ func listKnownAgents() []knownAgent {
 // lookupAgentProvider checks environment variables for known AI agents.
 //
 // Explicit product-specific env vars always take precedence over the generic
-// agents.md AGENT env var. AGENT is consulted only as a fallback when no
-// explicit matcher fires, so that an explicit signal (e.g. CLAUDECODE=1)
-// always wins over a conflicting AGENT=<name> value.
+// AGENT and AI_AGENT env vars, so that an explicit signal (e.g.
+// CLAUDECODE=1) always wins over a conflicting AGENT=<name> value.
 //
 // The function counts how many distinct agents matched via explicit env vars:
 //   - Exactly one agent matched: return its product name.
 //   - More than one agent matched: return "multiple". Agent env vars can be
 //     stacked when one agent invokes another as a subagent (e.g. Claude Code
 //     spawning a Cursor CLI subprocess), so the child process inherits env
 //     vars from multiple layers.
-//   - Zero agents matched: if the agents.md standard AGENT env var is set to
-//     a non-empty value, return that value if it matches a known product name,
-//     or "unknown" otherwise. If AGENT is not set, return "".
+//   - Zero agents matched: see agentEnvFallback.
 func lookupAgentProvider() string {
 	agents := listKnownAgents()
 
@@ -75,7 +84,7 @@ func lookupAgentProvider() string {
 	case 1:
 		return matches[0]
 	case 0:
-		return agentEnvFallback(agents)
+		return agentEnvFallback()
 	default:
 		return "multiple"
 	}
@@ -104,20 +113,23 @@ func collapseCopilotBYOK(matches []string) []string {
 	return filtered
 }
 
-// agentEnvFallback honors the agents.md AGENT=<name> standard.
-// Returns the value if it matches a known product name, "unknown" if AGENT
-// is set to any other non-empty value, and "" if AGENT is unset or empty.
-func agentEnvFallback(agents []knownAgent) string {
-	v, ok := os.LookupEnv(agentEnvVar)
-	if !ok || v == "" {
+// agentEnvFallback returns a sanitized, length-capped name from AGENT
+// or AI_AGENT, preferring AGENT when both are non-empty. The value is
+// passed through rather than categorized so that new names are propagated
+// without the need to update the list of known agents.
+func agentEnvFallback() string {
+	v := os.Getenv(agentEnvVar)
+	if v == "" {
+		v = os.Getenv(aiAgentEnvVar)
+	}
+	if v == "" {
 		return ""
 	}
-	for _, a := range agents {
-		if a.product == v {
-			return v
-		}
+	v = Sanitize(v)
+	if len(v) > maxAgentFallbackLen {
+		v = v[:maxAgentFallbackLen]
 	}
-	return "unknown"
+	return v
 }
 
 var (
@@ -128,13 +140,12 @@ var (
 // AgentProvider returns the detected AI agent name, cached for the process lifetime.
 // Returns one of:
 //   - the known product name when exactly one agent is detected via explicit
-//     env matchers, or when AGENT is set to a known product name and no
-//     explicit matcher fired;
+//     env matchers;
 //   - "multiple" when multiple explicit matchers fire for different agents
 //     (typically nested agents, e.g. Cursor CLI running as a Claude Code
 //     subagent);
-//   - "unknown" when no explicit matcher fired and AGENT is set to a value
-//     that is not a known product name;
+//   - a sanitized, length-capped value from AGENT or AI_AGENT when no
+//     explicit matcher fired (see agentEnvFallback);
 //   - "" when no agent is detected.
 func AgentProvider() string {
 	agentOnce.Do(func() {

useragent/agent_test.go

@@ -1,6 +1,7 @@
 package useragent
 
 import (
+	"strings"
 	"testing"
 
 	"github.com/databricks/databricks-sdk-go/internal/env"
@@ -130,24 +131,34 @@ func TestLookupAgentProvider(t *testing.T) {
 		},
 		// AGENT fallback behavior.
 		{
-			name:   "AGENT with unknown value falls back to unknown",
+			name:   "AGENT=cursor falls back to cursor",
+			envs:   map[string]string{"AGENT": "cursor"},
+			expect: "cursor",
+		},
+		{
+			name:   "AGENT with unrecognized value passes through (sanitized)",
 			envs:   map[string]string{"AGENT": "someweirdthing"},
-			expect: "unknown",
+			expect: "someweirdthing",
 		},
 		{
-			name:   "AGENT empty string does not trigger fallback",
-			envs:   map[string]string{"AGENT": ""},
-			expect: "",
+			name:   "AGENT versioned variant passes through unchanged",
+			envs:   map[string]string{"AGENT": "claude-code_2-1-141_agent"},
+			expect: "claude-code_2-1-141_agent",
 		},
 		{
-			name:   "AGENT=cursor falls back to cursor via known product name",
-			envs:   map[string]string{"AGENT": "cursor"},
-			expect: "cursor",
+			name:   "AGENT with disallowed chars is sanitized to hyphens",
+			envs:   map[string]string{"AGENT": "claude code/agent"},
+			expect: "claude-code-agent",
 		},
 		{
-			name:   "AGENT=claude-code falls back to claude-code via known product name",
-			envs:   map[string]string{"AGENT": "claude-code"},
-			expect: "claude-code",
+			name:   "AGENT longer than the cap is truncated",
+			envs:   map[string]string{"AGENT": strings.Repeat("a", 100)},
+			expect: strings.Repeat("a", 64),
+		},
+		{
+			name:   "AGENT empty string does not trigger fallback",
+			envs:   map[string]string{"AGENT": ""},
+			expect: "",
 		},
 		{
 			name:   "known matcher wins over AGENT fallback",
@@ -178,6 +189,53 @@ func TestLookupAgentProvider(t *testing.T) {
 			envs:   map[string]string{"COPILOT_CLI": "1", "COPILOT_MODEL": "gpt-4", "CLAUDECODE": "1"},
 			expect: "multiple",
 		},
+		// AI_AGENT fallback (Vercel @vercel/detect-agent convention).
+		{
+			name:   "AI_AGENT=cursor falls back to cursor",
+			envs:   map[string]string{"AI_AGENT": "cursor"},
+			expect: "cursor",
+		},
+		{
+			name:   "AI_AGENT empty string does not trigger fallback",
+			envs:   map[string]string{"AI_AGENT": ""},
+			expect: "",
+		},
+		{
+			name:   "known matcher wins over AI_AGENT fallback",
+			envs:   map[string]string{"AI_AGENT": "somethingunknown", "CLAUDECODE": "1"},
+			expect: "claude-code",
+		},
+		// AGENT vs AI_AGENT precedence: AGENT wins when both are non-empty.
+		{
+			name:   "AGENT wins over AI_AGENT when both are set to known products",
+			envs:   map[string]string{"AGENT": "claude-code", "AI_AGENT": "cursor"},
+			expect: "claude-code",
+		},
+		{
+			name:   "AGENT set to unrecognized non-empty value still wins over AI_AGENT",
+			envs:   map[string]string{"AGENT": "somethingunknown", "AI_AGENT": "cursor"},
+			expect: "somethingunknown",
+		},
+		{
+			name:   "AGENT set, AI_AGENT empty: AGENT value is used",
+			envs:   map[string]string{"AGENT": "cursor", "AI_AGENT": ""},
+			expect: "cursor",
+		},
+		{
+			name:   "empty AGENT falls through to AI_AGENT",
+			envs:   map[string]string{"AGENT": "", "AI_AGENT": "cursor"},
+			expect: "cursor",
+		},
+		{
+			name:   "both AGENT and AI_AGENT empty returns no agent",
+			envs:   map[string]string{"AGENT": "", "AI_AGENT": ""},
+			expect: "",
+		},
+		{
+			name:   "explicit CLAUDECODE wins over AI_AGENT=cursor",
+			envs:   map[string]string{"AI_AGENT": "cursor", "CLAUDECODE": "1"},
+			expect: "claude-code",
+		},
 	}
 
 	for _, tt := range tests {