Expand AI agent detection: Goose, Amp, Augment, Copilot (VS Code), Kiro, Windsurf (#1394)

## Why

We identify which AI agent is driving the SDK via the `agent/<name>`
user-agent segment. The current list covers 9 agents. This adds 6 more
and honors the emerging `AGENT=<name>` standard from agents.md so we can
see traffic from agents we haven't individually listed yet.

## Changes

Before: presence-only matching on a fixed list of env vars; multi-match
returns empty.

Now: each agent record has a list of matchers (env var plus optional
exact value), an agent fires if any matcher fires, ambiguity is judged
by unique product (not raw matcher count), and an `AGENT=<anything>`
fallback reports `unknown` when no specific entry matched.

Implementation:
- `databricks/sdk/useragent.py`: replaced the `_KNOWN_AGENTS` dict with
a list of `_AgentRecord` dataclasses each holding a `product` and a list
of `(env_var, value)` matchers. Rewrote `agent_provider()` to count
unique agents matched, handle the single/multi/zero cases, and fall back
to `unknown` when `AGENT` is set non-empty but no specific agent
matched. Cached result (`_agent_provider`) still uses the `None` vs `""`
sentinel pattern.
- `tests/test_user_agent.py`: added coverage for each new agent (goose,
amp, augment, copilot-vscode, kiro, windsurf), both Goose signals
together (not ambiguous), both Amp signals together (not ambiguous),
unknown fallback, empty `AGENT` does not trigger fallback, and
cross-agent ambiguity (`AGENT=goose` + `CLAUDECODE=1`).
- `NEXT_CHANGELOG.md`: entry under "Internal Changes".

New detections: Goose (`GOOSE_TERMINAL` or `AGENT=goose`), Amp
(`AMP_CURRENT_THREAD_ID` or `AGENT=amp`), Augment (`AUGMENT_AGENT`), VS
Code Copilot (`COPILOT_MODEL`), Kiro (`KIRO`), Windsurf
(`WINDSURF_AGENT`).

Parallel PRs with identical behavior are being opened in
`databricks-sdk-go` and `databricks-sdk-java`.

## Test plan

- [x] `python3 -m pytest tests/test_user_agent.py -v` passes (37 tests)
- [x] `make fmt` leaves the three modified files clean
- [x] Each new product detected when its primary env var is set
- [x] `AGENT=goose` alone returns `goose`
- [x] `GOOSE_TERMINAL=1` + `AGENT=goose` returns `goose` (not ambiguity)
- [x] `AMP_CURRENT_THREAD_ID` + `AGENT=amp` returns `amp` (not
ambiguity)
- [x] `AGENT=someweirdthing` returns `unknown`
- [x] `AGENT=""` returns `""` (fallback only fires on non-empty value)
- [x] Two distinct agents set simultaneously return `""`
- [x] `AGENT=goose` + `CLAUDECODE=1` returns `""` (cross-agent
ambiguity)

---------

Signed-off-by: simon <simon.faltum@databricks.com>

Author: simonfaltum

NEXT_CHANGELOG.md

@@ -14,4 +14,6 @@
 
 ### Internal Changes
 
+* Expanded AI agent detection: added Goose, Amp, Augment, Copilot (VS Code), Kiro, Windsurf. Honors the `AGENT=<name>` standard (resolves to a known product if the value matches one, otherwise `unknown`). Presence-only env var matchers now treat an empty string as "set" for parity with the Go and Java SDKs. Explicit agent env vars (e.g. `CLAUDECODE`, `GOOSE_TERMINAL`) always take precedence over the generic `AGENT=<name>` signal. When multiple agent env vars are present (e.g. a Cursor CLI subagent invoked from Claude Code), the user-agent reports `agent/multiple`.
+
 ### API Changes

databricks/sdk/useragent.py

@@ -3,6 +3,7 @@
 import os
 import platform
 import re
+from dataclasses import dataclass
 from typing import List, Optional, Tuple
 
 from .version import __version__
@@ -224,19 +225,38 @@ def cicd_provider() -> str:
     return _cicd_provider
 
 
-# Canonical list of known AI coding agents.
+# Canonical list of known AI coding agents. Alphabetical by product name.
 # Keep this list in sync with databricks-sdk-go and databricks-sdk-java.
-_KNOWN_AGENTS = {
-    "ANTIGRAVITY_AGENT": "antigravity",  # Closed source (Google)
-    "CLAUDECODE": "claude-code",  # https://github.com/anthropics/claude-code
-    "CLINE_ACTIVE": "cline",  # https://github.com/cline/cline (v3.24.0+)
-    "CODEX_CI": "codex",  # https://github.com/openai/codex
-    "COPILOT_CLI": "copilot-cli",  # https://github.com/features/copilot
-    "CURSOR_AGENT": "cursor",  # Closed source
-    "GEMINI_CLI": "gemini-cli",  # https://google-gemini.github.io/gemini-cli
-    "OPENCODE": "opencode",  # https://github.com/opencode-ai/opencode
-    "OPENCLAW_SHELL": "openclaw",  # https://github.com/anthropics/openclaw
-}
+#
+# Each record has a single env var that identifies the product by presence
+# (the env var just needs to be set, even to an empty string).
+@dataclass(frozen=True)
+class _AgentRecord:
+    env_var: str
+    product: str
+
+
+_KNOWN_AGENTS: List[_AgentRecord] = [
+    _AgentRecord("AMP_CURRENT_THREAD_ID", "amp"),  # https://ampcode.com/ (also sets AGENT=amp, handled centrally)
+    _AgentRecord("ANTIGRAVITY_AGENT", "antigravity"),  # Closed source (Google)
+    _AgentRecord("AUGMENT_AGENT", "augment"),  # https://www.augmentcode.com/
+    _AgentRecord("CLAUDECODE", "claude-code"),  # https://github.com/anthropics/claude-code
+    _AgentRecord("CLINE_ACTIVE", "cline"),  # https://github.com/cline/cline (v3.24.0+)
+    _AgentRecord("CODEX_CI", "codex"),  # https://github.com/openai/codex
+    _AgentRecord("COPILOT_CLI", "copilot-cli"),  # https://github.com/features/copilot
+    _AgentRecord(
+        "COPILOT_MODEL", "copilot-vscode"
+    ),  # VS Code Copilot terminal, best-effort heuristic, not officially identified
+    _AgentRecord("CURSOR_AGENT", "cursor"),  # Closed source
+    _AgentRecord("GEMINI_CLI", "gemini-cli"),  # https://google-gemini.github.io/gemini-cli
+    _AgentRecord(
+        "GOOSE_TERMINAL", "goose"
+    ),  # https://block.github.io/goose/ (also sets AGENT=goose, handled centrally)
+    _AgentRecord("KIRO", "kiro"),  # https://kiro.dev/ (Amazon)
+    _AgentRecord("OPENCLAW_SHELL", "openclaw"),  # https://github.com/anthropics/openclaw
+    _AgentRecord("OPENCODE", "opencode"),  # https://github.com/opencode-ai/opencode
+    _AgentRecord("WINDSURF_AGENT", "windsurf"),  # https://codeium.com/windsurf (Codeium)
+]
 
 # Private variable to store the detected agent provider. This value is computed
 # at the first invocation of agent_provider() and is cached for subsequent calls.
@@ -247,22 +267,54 @@ def cicd_provider() -> str:
 def agent_provider() -> str:
     """Detect if running inside a known AI coding agent.
 
-    Returns the agent name if exactly one known agent env var is set (non-empty).
-    Returns empty string if zero or multiple agents detected.
-    Result is cached after first call.
+    Iterates the list of known agents. Each agent fires if its explicit,
+    product-specific env var is set. If exactly one agent fired, returns its
+    product name. If more than one fired, returns "multiple" (nested agents,
+    e.g. a Cursor CLI subagent invoked by Claude Code, inherit env vars from
+    every enclosing layer).
+
+    Explicit agent env vars (e.g. CLAUDECODE, GOOSE_TERMINAL) always take
+    precedence. The agents.md-standard AGENT=<name> env var is only consulted
+    as a fallback when no explicit matcher fired:
+      - If AGENT matches a known product name, return that product.
+      - Otherwise return "unknown".
 
-    Unlike CI/CD detection (which returns the first/sorted match), agent detection
-    uses an ambiguity guard: multiple matches return empty. Agent env vars can be
-    stacked (e.g., running Cline inside Cursor), so we only report when unambiguous.
+    This means AGENT=<name> never contributes to the multi-agent signal: if
+    any explicit matcher fires, AGENT is ignored entirely, even when it names
+    a different known product.
+
+    Result is cached after first call.
     """
     global _agent_provider
     if _agent_provider is not None:
         return _agent_provider
 
-    detected = []
-    for env_var, name in _KNOWN_AGENTS.items():
-        if os.environ.get(env_var, ""):
-            detected.append(name)
+    matches = [a.product for a in _KNOWN_AGENTS if a.env_var in os.environ]
+
+    # Known BYOK false positive: Copilot CLI users often set COPILOT_MODEL
+    # alongside COPILOT_CLI. That pair is a single copilot-cli signal, not a
+    # stacked multi-agent setup.
+    if "copilot-cli" in matches and "copilot-vscode" in matches:
+        matches = [m for m in matches if m != "copilot-vscode"]
 
-    _agent_provider = detected[0] if len(detected) == 1 else ""
+    if len(matches) == 1:
+        _agent_provider = matches[0]
+    elif len(matches) > 1:
+        _agent_provider = "multiple"
+    else:
+        _agent_provider = _agent_env_fallback()
     return _agent_provider
+
+
+def _agent_env_fallback() -> str:
+    """Honor 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.
+    """
+    v = os.environ.get("AGENT", "")
+    if not v:
+        return ""
+    if v in {a.product for a in _KNOWN_AGENTS}:
+        return v
+    return "unknown"

tests/test_user_agent.py

@@ -181,19 +181,188 @@ def test_agent_provider_openclaw(clean_useragent_env):
     assert useragent.agent_provider() == "openclaw"
 
 
+def test_agent_provider_goose_env_var(clean_useragent_env):
+    os.environ["GOOSE_TERMINAL"] = "1"
+    from databricks.sdk import useragent
+
+    assert useragent.agent_provider() == "goose"
+
+
+def test_agent_provider_goose_via_agent_standard(clean_useragent_env):
+    os.environ["AGENT"] = "goose"
+    from databricks.sdk import useragent
+
+    assert useragent.agent_provider() == "goose"
+
+
+def test_agent_provider_goose_both_signals(clean_useragent_env):
+    # Both the dedicated env var and the AGENT=goose standard are set.
+    # This should NOT be ambiguous - it's still a single agent (goose).
+    os.environ["GOOSE_TERMINAL"] = "1"
+    os.environ["AGENT"] = "goose"
+    from databricks.sdk import useragent
+
+    assert useragent.agent_provider() == "goose"
+
+
+def test_agent_provider_amp_env_var(clean_useragent_env):
+    os.environ["AMP_CURRENT_THREAD_ID"] = "thread-123"
+    from databricks.sdk import useragent
+
+    assert useragent.agent_provider() == "amp"
+
+
+def test_agent_provider_amp_via_agent_standard(clean_useragent_env):
+    os.environ["AGENT"] = "amp"
+    from databricks.sdk import useragent
+
+    assert useragent.agent_provider() == "amp"
+
+
+def test_agent_provider_amp_both_signals(clean_useragent_env):
+    # Both AMP_CURRENT_THREAD_ID and AGENT=amp set - still single agent.
+    os.environ["AMP_CURRENT_THREAD_ID"] = "thread-123"
+    os.environ["AGENT"] = "amp"
+    from databricks.sdk import useragent
+
+    assert useragent.agent_provider() == "amp"
+
+
+def test_agent_provider_augment(clean_useragent_env):
+    os.environ["AUGMENT_AGENT"] = "1"
+    from databricks.sdk import useragent
+
+    assert useragent.agent_provider() == "augment"
+
+
+def test_agent_provider_copilot_vscode(clean_useragent_env):
+    os.environ["COPILOT_MODEL"] = "gpt-4"
+    from databricks.sdk import useragent
+
+    assert useragent.agent_provider() == "copilot-vscode"
+
+
+def test_agent_provider_kiro(clean_useragent_env):
+    os.environ["KIRO"] = "1"
+    from databricks.sdk import useragent
+
+    assert useragent.agent_provider() == "kiro"
+
+
+def test_agent_provider_windsurf(clean_useragent_env):
+    os.environ["WINDSURF_AGENT"] = "1"
+    from databricks.sdk import useragent
+
+    assert useragent.agent_provider() == "windsurf"
+
+
+def test_agent_provider_unknown_agent_fallback(clean_useragent_env):
+    # AGENT set to a value that doesn't match any known agent
+    # should fall back to "unknown".
+    os.environ["AGENT"] = "someweirdthing"
+    from databricks.sdk import useragent
+
+    assert useragent.agent_provider() == "unknown"
+
+
+def test_agent_provider_agent_known_product_name_fallback(clean_useragent_env):
+    # AGENT=<known product name> with no other matchers set should resolve
+    # to the matching product (e.g. cursor is only identified by CURSOR_AGENT;
+    # AGENT=cursor is a reasonable implicit signal to attribute it).
+    os.environ["AGENT"] = "cursor"
+    from databricks.sdk import useragent
+
+    assert useragent.agent_provider() == "cursor"
+
+
+def test_agent_provider_known_matcher_wins_over_agent_fallback(clean_useragent_env):
+    # When a known matcher fires, it wins even if AGENT is set to an
+    # unrelated value. The AGENT fallback only applies when nothing else hits.
+    os.environ["AGENT"] = "somethingweird"
+    os.environ["CLAUDECODE"] = "1"
+    from databricks.sdk import useragent
+
+    assert useragent.agent_provider() == "claude-code"
+
+
+def test_agent_provider_agent_empty_string(clean_useragent_env):
+    # AGENT="" (empty) should NOT trigger the fallback.
+    os.environ["AGENT"] = ""
+    from databricks.sdk import useragent
+
+    assert useragent.agent_provider() == ""
+
+
 def test_agent_provider_multiple_agents(clean_useragent_env):
+    # Nested agents (e.g. Claude Code spawning a Cursor CLI subagent) set
+    # multiple explicit matchers on the same process.
     os.environ["CLAUDECODE"] = "1"
     os.environ["CURSOR_AGENT"] = "1"
     from databricks.sdk import useragent
 
-    assert useragent.agent_provider() == ""
+    assert useragent.agent_provider() == "multiple"
+
+
+def test_agent_provider_three_stacked_agents(clean_useragent_env):
+    os.environ["CLAUDECODE"] = "1"
+    os.environ["CURSOR_AGENT"] = "1"
+    os.environ["AUGMENT_AGENT"] = "1"
+    from databricks.sdk import useragent
+
+    assert useragent.agent_provider() == "multiple"
+
+
+def test_agent_provider_explicit_wins_over_agent_naming_different_product(clean_useragent_env):
+    # Explicit env vars always win over the generic AGENT=<name> signal.
+    # AGENT=goose names a different known product, but CLAUDECODE is explicit,
+    # so claude-code wins. AGENT is ignored entirely when any explicit
+    # matcher fires.
+    os.environ["AGENT"] = "goose"
+    os.environ["CLAUDECODE"] = "1"
+    from databricks.sdk import useragent
+
+    assert useragent.agent_provider() == "claude-code"
+
+
+def test_agent_provider_explicit_goose_wins_over_agent_cursor(clean_useragent_env):
+    # Mirror of the above: GOOSE_TERMINAL is explicit, AGENT=cursor names a
+    # different known product. Explicit wins; AGENT is ignored.
+    os.environ["GOOSE_TERMINAL"] = "1"
+    os.environ["AGENT"] = "cursor"
+    from databricks.sdk import useragent
+
+    assert useragent.agent_provider() == "goose"
+
 
+def test_agent_provider_copilot_cli_and_vscode_collapses_to_copilot_cli(clean_useragent_env):
+    # Copilot CLI users (BYOK mode) often set COPILOT_MODEL alongside
+    # COPILOT_CLI. Treat the pair as a single copilot-cli signal rather than
+    # a stacked multi-agent setup.
+    os.environ["COPILOT_CLI"] = "1"
+    os.environ["COPILOT_MODEL"] = "gpt-4"
+    from databricks.sdk import useragent
 
-def test_agent_provider_empty_value(clean_useragent_env):
+    assert useragent.agent_provider() == "copilot-cli"
+
+
+def test_agent_provider_copilot_byok_collapse_then_still_multiple(clean_useragent_env):
+    # The Copilot BYOK collapse only removes the copilot-vscode match. If
+    # another agent is also present, the result is still "multiple".
+    os.environ["COPILOT_CLI"] = "1"
+    os.environ["COPILOT_MODEL"] = "gpt-4"
+    os.environ["CLAUDECODE"] = "1"
+    from databricks.sdk import useragent
+
+    assert useragent.agent_provider() == "multiple"
+
+
+def test_agent_provider_empty_value_still_counts_as_set(clean_useragent_env):
+    # Presence-only matchers fire even when the env var is set to an empty
+    # string. Parity with Go (os.LookupEnv) and Java (env.get != null).
     os.environ["CLAUDECODE"] = ""
     from databricks.sdk import useragent
 
-    assert useragent.agent_provider() == ""
+    assert useragent.agent_provider() == "claude-code"
 
 
 def test_user_agent_string_includes_agent(clean_useragent_env):
@@ -217,7 +386,7 @@ def test_user_agent_string_multiple_agents(clean_useragent_env):
     from databricks.sdk import useragent
 
     ua = useragent.to_string()
-    assert "agent/" not in ua
+    assert "agent/multiple" in ua
 
 
 def test_agent_provider_cached(clean_useragent_env):