Skip to content

Build AI methods with your coding agent, then run them anywhere: as an MCP for chatbots, as a webapp for people, or via API for your software.

fix/Pipelex-cli-user-agent · L-261008-593ce4 (#1379)

Louis Choquelc71dc4320ef4
diff --git a/CHANGELOG.md b/CHANGELOG.md
index c1990fea0..1f2a4da66 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -11,6 +11,7 @@
### Fixed
+- **The CLIs identify themselves as `pipelex-cli` to the hosted API**: every request `pipelex run --hosted`, `pipelex-agent run --hosted` and `pipelex login` send now leads its `User-Agent` with `pipelex-cli/<version>`, the token the client-identification spec reserves for these CLIs, so the hosted API counts their runs on its CLI surface instead of as calls from an SDK.
- **A home configuration directory holding only some files gets the kit's missing ones**: every boot now copies into `~/.pipelex/`, or the directory `PIPELEX_HOME` names, each kit file it lacks, never overwriting one it holds or writing through a symbolic link, so a kit file deleted from it comes back. A directory holding anything at all, such as the `pipelex_service.toml` an earlier release wrote, used to be left as it was, and every boot then failed with "Config files are missing for the inference backend library". The inference files are copied as one unit, only when the directory has no `inference/backends.toml`, each file and kit manifest is written whole or not at all, so a fill cut short is completed by the next boot, and a directory Pipelex cannot write to is read as it is.
- **`pipelex-agent init --help` keeps `list[str]`**: the `--config` help printed the schema's `"backends": list[str]` as `"backends": list`, because Typer renders help as Rich markup and Rich took `[str]` for a style; the bracket is now escaped and printed.
diff --git a/docs/building-methods/pipes/running-on-the-hosted-api.md b/docs/building-methods/pipes/running-on-the-hosted-api.md
index bb448b123..c02578acb 100644
--- a/docs/building-methods/pipes/running-on-the-hosted-api.md
+++ b/docs/building-methods/pipes/running-on-the-hosted-api.md
@@ -6,7 +6,7 @@ description: "Run methods on the hosted Pipelex API from Python with pipelex-sdk
The Pipelex Python API has two halves. `PipelexMTHDSProtocol`, shown in [Executing Pipelines](executing-pipelines.md), runs a method in your own process, with your own inference backends and provider keys. **`PipelexAPIClient`**, from the `pipelex-sdk` package, runs it on the hosted Pipelex API, with only a Pipelex API key. `pipelex-sdk` is a dependency of `pipelex`, so it is installed with it, and it is the client `pipelex run --hosted` uses under the hood.
-Use the client directly: it has no Pipelex wrapper, and it needs no `Pipelex.make()`, since nothing runs locally.
+Use the client directly: it has no Pipelex wrapper, and it needs no `Pipelex.make()`, since nothing runs locally. Its requests identify themselves in their `User-Agent` as pipelex-sdk's, while the CLI's lead with `pipelex-cli/<version>`; to put your own application's name in front, pass pipelex-sdk's `app_info` to the constructor.
## The Key and the Origin
diff --git a/docs/tools/cli/agent-cli.md b/docs/tools/cli/agent-cli.md
index f26db4096..85f4ebd30 100644
--- a/docs/tools/cli/agent-cli.md
+++ b/docs/tools/cli/agent-cli.md
@@ -53,7 +53,7 @@ For `bundle` and `method`, use `--pipe` to target a specific pipe.
#### Running on the hosted API
-With `--runner hosted` (or `--hosted`, or `[run] execution = "hosted"`), the run executes on the hosted Pipelex API and nothing local is booted: no provider key or inference configuration is needed on this machine, only a Pipelex API key in `PIPELEX_API_KEY` (in the shell, or in `~/.pipelex/.env`). What the run sends is what a local run would load. `run bundle` sends the bundle, then every `.mthds` file of its library directories. `run pipe` sends its library directories' files (the installed method exporting the pipe and `-L`, else `PIPELEXPATH`) and is refused when it has none. `run method` sends an installed or local method's files, but a published address (`github.com/owner/repo[/name][@tag]`) goes as a `method_ref` and a stored method's catalog id (`mt_…`) as a `method_id`, both resolved by the hosted API, so nothing is fetched or read locally and `-L` is refused with them. A local file named at a document or image input is uploaded first (a relative path in an inputs file resolves against that file's directory, and a `file://` URI is read as its path), and the run's inputs carry its storage URI; an explicit `null`, such as an optional image left out, reaches the run as `null`. The method's signature is read only when some value of the inputs names an existing file on this machine, so inputs naming none go straight to the run, a method calling another one by its address included. Such a method cannot have a local file uploaded yet: give the file as an `https://` URL. `run bundle` on a bundle file with no `-L` sends `PIPELEXPATH`'s files too, as a local run loads them, and `run method` takes a method installed under a name spelled like a catalog id (`mt_reports`) as that method. `--dry-run` and `--mock-inputs` are refused on a hosted run.
+With `--runner hosted` (or `--hosted`, or `[run] execution = "hosted"`), the run executes on the hosted Pipelex API and nothing local is booted: no provider key or inference configuration is needed on this machine, only a Pipelex API key in `PIPELEX_API_KEY` (in the shell, or in `~/.pipelex/.env`). What the run sends is what a local run would load. `run bundle` sends the bundle, then every `.mthds` file of its library directories. `run pipe` sends its library directories' files (the installed method exporting the pipe and `-L`, else `PIPELEXPATH`) and is refused when it has none. `run method` sends an installed or local method's files, but a published address (`github.com/owner/repo[/name][@tag]`) goes as a `method_ref` and a stored method's catalog id (`mt_…`) as a `method_id`, both resolved by the hosted API, so nothing is fetched or read locally and `-L` is refused with them. A local file named at a document or image input is uploaded first (a relative path in an inputs file resolves against that file's directory, and a `file://` URI is read as its path), and the run's inputs carry its storage URI; an explicit `null`, such as an optional image left out, reaches the run as `null`. The method's signature is read only when some value of the inputs names an existing file on this machine, so inputs naming none go straight to the run, a method calling another one by its address included. Such a method cannot have a local file uploaded yet: give the file as an `https://` URL. `run bundle` on a bundle file with no `-L` sends `PIPELEXPATH`'s files too, as a local run loads them, and `run method` takes a method installed under a name spelled like a catalog id (`mt_reports`) as that method. `--dry-run` and `--mock-inputs` are refused on a hosted run. Its requests name their client in the `User-Agent` as `pipelex-cli/<version>`, as `pipelex run --hosted` does, so the hosted API counts them as CLI runs.
The success envelope has the shape of a local run's. Compact, it is the main output's content. With `--with-memory`, `main_stuff.json` is that content (the hosted API renders no Markdown, so the markdown output shows the JSON), `working_memory` is the whole working memory, `pipeline_run_id` names the run on the hosted API, and `uploads` lists the files uploaded for it. A hosted run writes nothing to disk.
diff --git a/docs/tools/cli/run.md b/docs/tools/cli/run.md
index 6b3cff935..47687d49f 100644
--- a/docs/tools/cli/run.md
+++ b/docs/tools/cli/run.md
@@ -185,7 +185,7 @@ Where a run executes is decided in this order:
2. `[run] execution` in `.pipelex/pipelex.toml` (`"local"` or `"hosted"`; the project's file over the one in `~/.pipelex/`), which [`pipelex init`](init.md#where-your-runs-execute) writes from your answer, see [Run Configuration](../../configuration/config-practical/run-config.md).
3. Local.
-The key is read from `PIPELEX_API_KEY`, exported in your shell or saved in `~/.pipelex/.env` (or a `.env` in the working directory), which Pipelex loads at startup. [`pipelex login`](login.md) gets a key through your browser and saves it there. The run goes to `--base-url` when given, else to `PIPELEX_BASE_URL`, else to `https://api.pipelex.com`. Either value must be an origin, `scheme://host[:port]` with `http` or `https` and no path such as `/v1`; anything else is refused before a request is sent, naming the setting it came from. A self-hosted Pipelex API server is reached the same way, by pointing the base URL at it.
+The key is read from `PIPELEX_API_KEY`, exported in your shell or saved in `~/.pipelex/.env` (or a `.env` in the working directory), which Pipelex loads at startup. [`pipelex login`](login.md) gets a key through your browser and saves it there. The run goes to `--base-url` when given, else to `PIPELEX_BASE_URL`, else to `https://api.pipelex.com`. Either value must be an origin, `scheme://host[:port]` with `http` or `https` and no path such as `/v1`; anything else is refused before a request is sent, naming the setting it came from. A self-hosted Pipelex API server is reached the same way, by pointing the base URL at it. Every request a hosted run sends names its client in its `User-Agent` as `pipelex-cli/<version>`, followed by the versions of the pipelex-sdk and mthds clients it runs on, so the hosted API counts it as a CLI run; the header carries no key and nothing that identifies you.
**What a hosted run sends** is what a local run would load:
diff --git a/pipelex/hosted/client_factory.py b/pipelex/hosted/client_factory.py
index 964211d87..5eca71e6d 100644
--- a/pipelex/hosted/client_factory.py
+++ b/pipelex/hosted/client_factory.py
@@ -22,8 +22,10 @@ PIPELEX_API_KEY_ENV_KEY = "PIPELEX_API_KEY"
PIPELEX_BASE_URL_ENV_KEY = "PIPELEX_BASE_URL"
#: The origin a hosted run goes to when neither `--base-url` nor `PIPELEX_BASE_URL` names another.
HOSTED_API_DEFAULT_BASE_URL = DEFAULT_API_BASE_URL
-#: The name this runtime gives itself in the `User-Agent` of every hosted request.
-_APP_NAME = "pipelex"
+#: The name the `pipelex` and `pipelex-agent` CLIs give themselves in the `User-Agent` of every hosted request: the
+#: client-identification registry's token for them, which the hosted plane counts on its `cli` surface. Every caller of
+#: `make_hosted_client` is one of their commands; library code calling the hosted API would need a name of its own.
+_CLI_APP_NAME = "pipelex-cli"
def redact_url_for_display(*, url: str) -> str:
@@ -73,7 +75,7 @@ def make_hosted_client(*, base_url: str | None = None, api_key: str | None = Non
HostedBaseUrlError: If the base URL is not host-only, naming the setting it came from.
"""
try:
- return PipelexAPIClient(api_key=api_key, base_url=base_url, app_info=AppInfo(name=_APP_NAME, version=get_package_version()))
+ return PipelexAPIClient(api_key=api_key, base_url=base_url, app_info=AppInfo(name=_CLI_APP_NAME, version=get_package_version()))
except PipelineRequestError:
# The SDK's constructor raises this for one reason only: a base URL that is not an origin.
source = "--base-url" if base_url is not None else PIPELEX_BASE_URL_ENV_KEY
diff --git a/tests/unit/pipelex/hosted/test_hosted_client_factory.py b/tests/unit/pipelex/hosted/test_hosted_client_factory.py
index 76543992a..3c1c86009 100644
--- a/tests/unit/pipelex/hosted/test_hosted_client_factory.py
+++ b/tests/unit/pipelex/hosted/test_hosted_client_factory.py
@@ -58,10 +58,12 @@ class TestHostedClientFactory:
"""No key is not refused here: a self-hosted runner answers its protocol routes without one."""
assert make_hosted_client().api_key == ""
- def test_the_user_agent_names_pipelex(self) -> None:
- """Every request says it comes from this runtime, so the hosted plane can tell its callers apart."""
+ def test_the_user_agent_names_the_cli(self) -> None:
+ """Every request leads with `pipelex-cli`, the registry's token for these CLIs, so the hosted plane counts it on
+ its `cli` surface: an unregistered first token would be read as an integrator app on the `sdk` surface.
+ """
client = make_hosted_client()
- assert client.user_agent.startswith(f"pipelex/{get_package_version()} ")
+ assert client.user_agent.startswith(f"pipelex-cli/{get_package_version()} pipelex-sdk-python/")
@pytest.mark.parametrize(
("base_url", "env_base_url", "named_source"),