TEC-200: user_agent parameter for attribution

README.md

@@ -99,11 +99,12 @@ with AgentScore(api_key="as_live_...") as client:
 
 ## Configuration
 
-| Parameter  | Default                     | Description              |
-|------------|----------------------------|--------------------------|
-| `api_key`  | `None`                     | API key from [agentscore.sh](https://agentscore.sh) |
-| `base_url` | `https://api.agentscore.sh` | API base URL             |
-| `timeout`  | `10.0`                     | Request timeout (seconds)|
+| Parameter     | Default                     | Description              |
+|---------------|-----------------------------|--------------------------|
+| `api_key`     | `None`                      | API key from [agentscore.sh](https://agentscore.sh) |
+| `base_url`    | `https://api.agentscore.sh` | API base URL             |
+| `timeout`     | `10.0`                      | Request timeout (seconds)|
+| `user_agent`  | `None`                      | Prepended to the default `User-Agent` as `"{user_agent} (agentscore-py/{version})"`. Use to attribute API calls to your app. |
 
 ## Error Handling
 

agentscore/client.py

@@ -27,20 +27,23 @@ def __init__(
         api_key: str,
         base_url: str = "https://api.agentscore.sh",
         timeout: float = 10.0,
+        user_agent: str | None = None,
     ):
         if not api_key:
             raise ValueError("AgentScore API key is required. Get one at https://agentscore.sh/sign-up")
         self.api_key = api_key
         self.base_url = base_url.rstrip("/")
         self.timeout = timeout
+        default_ua = f"agentscore-py/{_pkg_version('agentscore-py')}"
+        self.user_agent = f"{user_agent} ({default_ua})" if user_agent else default_ua
         self._sync_client: httpx.Client | None = None
         self._async_client: httpx.AsyncClient | None = None
 
     def _headers(self) -> dict:
         return {
             "Accept": "application/json",
             "X-API-Key": self.api_key,
-            "User-Agent": f"agentscore-py/{_pkg_version('agentscore-py')}",
+            "User-Agent": self.user_agent,
         }
 
     def _get_sync_client(self) -> httpx.Client:

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "agentscore-py"
-version = "1.6.0"
+version = "1.7.0"
 description = "Python client for the AgentScore trust and reputation API"
 readme = "README.md"
 license = "MIT"

tests/test_client.py

@@ -386,6 +386,21 @@ def test_user_agent_header_includes_version():
     assert request.headers["user-agent"] == f"agentscore-py/{version('agentscore-py')}"
 
 
+@respx.mock
+def test_user_agent_header_prepends_custom_user_agent():
+    """Custom user_agent should be rendered as '{custom} ({default})'."""
+    from importlib.metadata import version
+
+    respx.get(f"{BASE_URL}/v1/reputation/{ADDRESS}").mock(
+        return_value=httpx.Response(200, json=REPUTATION_PAYLOAD),
+    )
+    client = AgentScore(api_key=API_KEY, user_agent="my-app/1.2.3")
+    client.get_reputation(ADDRESS)
+    request = respx.calls[0].request
+    expected = f"my-app/1.2.3 (agentscore-py/{version('agentscore-py')})"
+    assert request.headers["user-agent"] == expected
+
+
 # ---------------------------------------------------------------------------
 # Edge cases
 # ---------------------------------------------------------------------------