Inject user agent header at runtime

python/packages/core/agent_framework/__init__.py

@@ -122,6 +122,7 @@ from ._telemetry import (
     APP_INFO,
     USER_AGENT_KEY,
     USER_AGENT_TELEMETRY_DISABLED_ENV_VAR,
+    get_user_agent_extra_headers,
     prepend_agent_framework_to_user_agent,
 )
 from ._tools import (
@@ -422,6 +423,7 @@ __all__ = [
     "evaluator",
     "executor",
     "function_middleware",
+    "get_user_agent_extra_headers",
     "handler",
     "included_messages",
     "included_token_count",

python/packages/core/agent_framework/_telemetry.py

@@ -59,6 +59,24 @@ def _get_user_agent() -> str:
     return f"{'/'.join(prefixes)}/{AGENT_FRAMEWORK_USER_AGENT}"
 
 
+def get_user_agent_extra_headers() -> dict[str, str]:
+    """Return extra headers containing the current User-Agent string for per-request injection.
+
+    This function evaluates the user agent at call time, picking up any active
+    ``user_agent_prefix`` context. Use it to supply ``extra_headers`` on individual
+    API calls so that the User-Agent reflects the current functional area.
+
+    When user agent telemetry is disabled, an empty dict is returned.
+
+    Returns:
+        A dict with ``"User-Agent"`` set to the runtime user agent string,
+        or an empty dict when telemetry is disabled.
+    """
+    if not IS_TELEMETRY_ENABLED:
+        return {}
+    return {USER_AGENT_KEY: _get_user_agent()}
+
+
 def prepend_agent_framework_to_user_agent(headers: dict[str, Any] | None = None) -> dict[str, Any]:
     """Prepend "agent-framework" to the User-Agent in the headers.
 

python/packages/core/tests/core/test_telemetry.py

@@ -6,6 +6,7 @@ from agent_framework import (
     AGENT_FRAMEWORK_USER_AGENT,
     USER_AGENT_KEY,
     USER_AGENT_TELEMETRY_DISABLED_ENV_VAR,
+    get_user_agent_extra_headers,
     prepend_agent_framework_to_user_agent,
 )
 from agent_framework._telemetry import user_agent_prefix
@@ -150,3 +151,33 @@ def test_user_agent_prefix_nesting():
     # Both removed
     result = prepend_agent_framework_to_user_agent()
     assert result["User-Agent"] == AGENT_FRAMEWORK_USER_AGENT
+
+
+# region Test get_user_agent_extra_headers
+
+
+def test_get_user_agent_extra_headers_returns_user_agent():
+    """Test that get_user_agent_extra_headers returns a User-Agent header."""
+    result = get_user_agent_extra_headers()
+    assert "User-Agent" in result
+    assert result["User-Agent"] == AGENT_FRAMEWORK_USER_AGENT
+
+
+def test_get_user_agent_extra_headers_with_prefix():
+    """Test that get_user_agent_extra_headers respects user_agent_prefix context."""
+    with user_agent_prefix("test-host"):
+        result = get_user_agent_extra_headers()
+        assert result["User-Agent"].startswith("test-host/")
+        assert AGENT_FRAMEWORK_USER_AGENT in result["User-Agent"]
+
+    # After exiting context, prefix is removed
+    result = get_user_agent_extra_headers()
+    assert result["User-Agent"] == AGENT_FRAMEWORK_USER_AGENT
+
+
+def test_get_user_agent_extra_headers_with_nested_prefix():
+    """Test that get_user_agent_extra_headers picks up nested prefixes."""
+    with user_agent_prefix("outer"), user_agent_prefix("inner"):
+        result = get_user_agent_extra_headers()
+        assert "outer" in result["User-Agent"]
+        assert "inner" in result["User-Agent"]