databricks-agentbricks 0.2.0__py3-none-any.whl

databricks_agentbricks/cli/dev.py

@@ -0,0 +1,310 @@
+"""`ab dev` — run a scaffolded agent locally, wrapping `databricks apps run-local`.
+
+Runs the app from its ``app.yaml`` exactly as the Databricks Apps runtime would locally: reads the
+manifest's command + env, and (with ``--prepare-environment``) builds the venv via uv. This is the
+local counterpart to ``ab deploy`` — same source dir, same manifest — so what runs here matches
+what ships. Delegating to ``apps run-local`` means agentbricks inherits the Apps team's local-run behavior
+rather than re-implementing it.
+"""
+
+from __future__ import annotations
+
+import pathlib
+from typing import Optional
+
+import click
+import yaml
+
+from databricks_agentbricks import render
+from databricks_agentbricks.cli.deploy import (
+    _load_project,
+    resource_bindings,
+)
+from databricks_agentbricks.cli.endpoint_examples import print_agent_invoke_command
+from databricks_agentbricks.cli.tracing import start_local_tracing_server, stop_local_tracing_server
+from databricks_agentbricks.databricks_cli import _databricks
+from databricks_agentbricks.errors import AgentCliError
+from databricks_agentbricks.project_config import require_managed_tool_support
+from databricks_agentbricks.project_types import AgentServer
+from databricks_agentkit.runtime.store import RUNTIME_STORE_LOCAL_ENV
+from databricks_agentkit.runtime.tool_manifest import MEMORY_STORE_ENV, SESSION_STORE_ENV
+
+# Default local port; `databricks apps run-local` listens here unless --app-port overrides it.
+_DEFAULT_APP_PORT = 8000
+_LOCAL_APP_YAML = "app.agentbricksdev.yaml"
+
+# Env vars that pin a package index for the *deployed* Apps build (a cloud-only workaround, see
+# `ab deploy`). They point at an index the deploying environment can reach, which is not
+# necessarily reachable from the local dev machine — so `ab dev`'s local `uv` build must ignore
+# them and use the machine's own configured index instead.
+_BUILD_INDEX_ENVS = frozenset({"PIP_INDEX_URL", "UV_INDEX_URL", "UV_DEFAULT_INDEX"})
+
+# Workspace managed-resource env that `ab deploy` writes into app.yaml but `ab dev` must NOT
+# inherit - dev runs every resource locally. These are stripped from the dev manifest:
+#   - tracing: dev sets up its OWN local MLflow server, so a stale workspace MLFLOW_EXPERIMENT_ID
+#     (which MLflow resolves ahead of MLFLOW_EXPERIMENT_NAME) would point the local agent at an
+#     experiment that doesn't exist on the local sqlite server. dev re-adds the local
+#     MLFLOW_TRACKING_URI / MLFLOW_EXPERIMENT_NAME itself.
+#   - stores: dev never uses the workspace memory/session stores (memory off, sessions in-process),
+#     so a prior deploy's AGENT_MEMORY_STORE / AGENT_SESSION_STORE must not quietly pull dev onto
+#     them. dev re-adds nothing here - the runtime falls back to its local defaults.
+# (The Runtime Store's lakebase env needs no strip: dev already forces RUNTIME_STORE_LOCAL=true.)
+_DEPLOY_TRACING_ENVS = frozenset(
+    {"MLFLOW_TRACKING_URI", "MLFLOW_EXPERIMENT_ID", "MLFLOW_TRACING_DESTINATION"}
+)
+_DEPLOY_RESOURCE_ENVS = _DEPLOY_TRACING_ENVS | {MEMORY_STORE_ENV, SESSION_STORE_ENV}
+
+
+@click.command()
+@click.option(
+    "--source",
+    default=".",
+    type=click.Path(exists=True, file_okay=False),
+    help="Local source directory to run (containing app.yaml). Defaults to the current directory.",
+)
+@click.option(
+    "--prepare-environment/--no-prepare-environment",
+    default=None,
+    help="Build the app's environment with uv before running. Default: build only if no .venv "
+    "exists yet, and reuse it otherwise. Requires uv.",
+)
+@click.option("--app-port", type=int, default=None, help="Port to run the app on (default 8000).")
+@click.pass_obj
+def dev(
+    obj,
+    source: str,
+    prepare_environment: Optional[bool],
+    app_port: Optional[int],
+) -> None:
+    """Run your agent locally so you can try it before deploying.
+
+    Starts the agent on a local server — by default http://localhost:8000 — and prints where to
+    reach it: the chat UI if the project has one, otherwise a sample request against the agent's
+    API.
+
+    Auth uses your Databricks profile (`-p` / `ab login`), and the agent reaches Databricks model
+    serving through the AI Gateway on that profile — so there are no model keys to set up.
+
+    Under the hood this wraps `databricks apps run-local`: it reads the command + env from
+    `app.yaml` and runs the app the way the Apps runtime would, so local behavior matches a
+    deployment. The environment is built on the first run and reused after; pass
+    `--prepare-environment` to force a rebuild (e.g. after changing dependencies).
+
+    Everything runs locally: `ab dev` is a local deployment that does not depend on a Databricks
+    workspace for its resources. Tracing goes to a local MLflow tracking server (sqlite-backed, under `.agentbricks/`)
+    so traces are recorded on your machine with no workspace experiment or setup - open the printed
+    Traces URL to view them (`ab tracing unbind` doesn't affect dev; it only stops the deployed
+    agent's tracing). Long-term memory is off and conversation history is in-process (not durable):
+    the memory/session stores bound with `ab memory/sessions bind` are created and used only when you
+    `ab deploy`, not here. So there's nothing to provision and no service-principal grant to make;
+    that all happens at `ab deploy` time.
+    """
+    source_dir = pathlib.Path(source)
+    app_yaml = source_dir / "app.yaml"
+    if not app_yaml.exists():
+        raise AgentCliError(
+            f"No app.yaml found at {app_yaml}.",
+            hint="Run from a scaffolded project, or pass --source <dir> (see `ab init`).",
+        )
+
+    project = _load_project(source_dir)
+    if project is not None and project.tools:
+        require_managed_tool_support(source_dir)
+
+    # `ab dev` is a fully local sandbox: the Runtime Store and tracing already run locally, and
+    # memory/sessions follow suit here. Dev never reaches the workspace for stores (so it stays fast
+    # and works offline): long-term memory is off and conversation history is in-process (not
+    # durable), regardless of any binding. Stores are created and used only by `ab deploy`; the
+    # deploy-written store env is stripped from the dev manifest (see `_dev_entry_point`) so a prior
+    # deploy can't quietly pull dev onto the workspace stores. Read the bindings only to name them.
+    memory_store, session_store, trace_experiment = resource_bindings(source_dir)
+    if memory_store:
+        render.console().print(
+            f"[dim]Memory store '{memory_store}' is bound but `ab dev` runs with "
+            "long-term memory off. Run `ab deploy` to use bound store.[/]"
+        )
+    if session_store:
+        render.console().print(
+            f"[dim]Session store '{session_store}' is bound but `ab dev` keeps "
+            "conversation history in-process (not durable). Run `ab deploy` to use bound store.[/]"
+        )
+    if trace_experiment:
+        render.console().print(
+            f"[dim]Tracing experiment '{trace_experiment}' is bound but `ab dev` "
+            "traces to a local MLflow server. Run `ab deploy` to trace to the bound experiment.[/]"
+        )
+    local_env: dict[str, str] = {}
+    # Local tracing: start a local MLflow tracking server backed by sqlite under .agentbricks/ and point the
+    # agent at it via the dev-only manifest — for any project, regardless of framework/server. An agent
+    # that uses MLflow (autolog or `start_trace`) then traces to it; it's harmless for one that doesn't.
+    # Traces stay on the machine — no workspace experiment, no auth, no username needed — and the same
+    # server serves the trace UI. Launched via `uvx mlflow` so it needs neither the (skinny) CLI env nor
+    # the agent venv, and it owns the sqlite schema (so there's no client/server migration mismatch).
+    # Best-effort: any launch failure degrades to running without traces. `ab deploy` handles the
+    # managed workspace experiment instead.
+    tracing_server, tracing_env = start_local_tracing_server(source_dir)
+    # Everything after the server starts runs under try/finally, so any failure — e.g. a malformed
+    # app.yaml that `_dev_entry_point` rejects — still tears the local server down (and removes the
+    # dev-only manifest) instead of orphaning the process.
+    entry_point: Optional[pathlib.Path] = None
+    try:
+        trace_url: Optional[str] = None
+        if tracing_env:
+            local_env.update(tracing_env)
+            uri = tracing_env["MLFLOW_TRACKING_URI"]
+            name = tracing_env.get("MLFLOW_EXPERIMENT_NAME")
+            # Can't deep-link the experiment (created lazily on the first request; its local id isn't
+            # stable), so name it after the local MLflow UI URL so the user knows which one to open.
+            trace_url = f"{uri} (experiment name: {name})" if name else uri
+
+        # Default: prepare only when there's no venv yet, so repeat runs don't rebuild. Explicit
+        # --prepare-environment / --no-prepare-environment overrides the auto-detect.
+        if prepare_environment is None:
+            prepare_environment = not (source_dir / ".venv").exists()
+
+        args = ["apps", "run-local"]
+        if prepare_environment:
+            args.append("--prepare-environment")
+        if app_port is not None:
+            args += ["--app-port", str(app_port)]
+
+        # Run against a local-only manifest that forces the Runtime Store in-process, removes deploy-only
+        # package-index overrides, and injects any locally resolved store ids and the local tracing env.
+        entry_point = _dev_entry_point(app_yaml, local_env or None)
+        # run-local resolves this relative to cwd and rejects an absolute alternate-manifest path.
+        args += ["--entry-point", entry_point.name]
+
+        # `run-local` prints a generic "go to http://localhost:<port>" line that points at the chat UI —
+        # misleading for an API-only project, which serves no page there (404). Print an accurate line up
+        # front, keyed on whether this project actually carries the chat-app overlay.
+        _announce_local_url(
+            source_dir,
+            app_port or _DEFAULT_APP_PORT,
+            project.server if project else None,
+            trace_url,
+        )
+
+        # Run in the project dir so run-local finds the app; stream output (no capture).
+        _databricks(
+            args,
+            obj.profile,
+            cwd=str(source_dir),
+            action="Could not start the agent locally.",
+        )
+    finally:
+        # Remove the local-only manifest so a later `ab deploy` cannot sync it to the workspace, and
+        # stop the local tracing server — even if setup above raised before run-local.
+        if entry_point is not None:
+            entry_point.unlink(missing_ok=True)
+        if tracing_server is not None:
+            stop_local_tracing_server(tracing_server)
+
+
+def _announce_local_url(
+    source_dir: pathlib.Path, port: int, server: AgentServer | None, trace_url: str | None = None
+) -> None:
+    """Print how to reach the running app: the chat UI if present, else a sample invoke request.
+
+    ``trace_url`` (when tracing is on) is shown alongside so a dev run surfaces where its traces land,
+    matching the ``Traces`` line ``ab deploy`` prints.
+    """
+    base = f"http://localhost:{port}"
+    deploy_name = source_dir.resolve().name
+    tool_step: str | tuple[str, str] = (
+        "Edit agent/agent.py to give the agent a tool"
+        if server == AgentServer.CUSTOM
+        else ("ab tools add mcp <service>", "Give the agent a tool")
+    )
+    if (source_dir / "runtime" / "ui.py").is_file():
+        fields = {"Chat UI": base}
+        if trace_url:
+            fields["Traces"] = trace_url
+        render.success(
+            "Starting agent",
+            fields=fields,
+            next_steps=[
+                f"Open {base} to chat with your agent",
+                tool_step,
+                ("ab memory bind <store>", "Attach a memory / session store"),
+                (f"ab deploy {deploy_name}", "Deploy it to Databricks"),
+            ],
+        )
+    else:
+        # No page is served at `/`, so give a copy-pasteable request instead of just the URL.
+        uses_runtime_api = server == AgentServer.AGENTBRICKS
+        endpoint = f"{base}/api/invocations" if uses_runtime_api else f"{base}/invocations"
+        body = (
+            '{"id": "00000000-0000-4000-8000-000000000000", '
+            '"input": [{"role": "user", "content": "hi"}]}'
+            if uses_runtime_api
+            else '{"input": [{"role": "user", "content": "hi"}]}'
+        )
+        sample = f"curl -X POST {endpoint} -H 'Content-Type: application/json' -d '{body}'"
+        fields = {"Invoke": f"POST {endpoint}"}
+        if trace_url:
+            fields["Traces"] = trace_url
+        render.success(
+            "Starting API-only agent (no chat UI — see `ab init --help`)",
+            fields=fields,
+            next_steps=[
+                (sample, "Send a test request"),
+                tool_step,
+                (f"ab deploy {deploy_name}", "Deploy it to Databricks"),
+            ],
+        )
+
+    print_agent_invoke_command(
+        f"--url {base}",
+        uses_runtime_api=(source_dir / "runtime" / "ui.py").is_file()
+        or server == AgentServer.AGENTBRICKS,
+    )
+
+
+def _dev_entry_point(
+    app_yaml: pathlib.Path, extra_env: dict[str, str] | None = None
+) -> pathlib.Path:
+    """Write the local-only app manifest consumed by ``apps run-local``.
+
+    The manifest marks the process as local so Agent Bricks Runtime uses its in-memory store. Keeping this in
+    the entry point is more reliable than forwarding ``--env`` through the Databricks CLI and does
+    not mutate the deployable ``app.yaml``. Deploy-only package-index variables and the deploy-written
+    workspace resource env (see ``_DEPLOY_RESOURCE_ENVS`` - tracing + memory/session stores) are
+    removed so dev stays fully local. ``extra_env`` is merged in (overriding any same-named entries)
+    for dev-only overrides such as the local tracing config.
+    """
+    try:
+        doc = yaml.safe_load(app_yaml.read_text()) or {}
+    except yaml.YAMLError as exc:
+        raise AgentCliError(f"Could not parse {app_yaml}: {exc}") from exc
+    if not isinstance(doc, dict):
+        raise AgentCliError(f"Invalid {app_yaml}: top level must be an object.")
+    env = doc.get("env")
+    if env is not None and not isinstance(env, list):
+        raise AgentCliError(f"Invalid {app_yaml}: env must be a list.")
+    filtered = [
+        e for e in (env or []) if not (isinstance(e, dict) and e.get("name") in _BUILD_INDEX_ENVS)
+    ]
+    filtered = [
+        e
+        for e in filtered
+        if not (isinstance(e, dict) and e.get("name") == RUNTIME_STORE_LOCAL_ENV)
+    ]
+    # Drop the deploy-written workspace resource env (tracing + memory/session stores) so a prior
+    # `ab deploy` can't pull dev onto workspace resources: a stale MLFLOW_EXPERIMENT_ID would beat
+    # the local MLFLOW_EXPERIMENT_NAME dev re-adds below, and AGENT_MEMORY_STORE / AGENT_SESSION_STORE
+    # would silently point the local runtime at the workspace stores instead of its local defaults.
+    filtered = [
+        e for e in filtered if not (isinstance(e, dict) and e.get("name") in _DEPLOY_RESOURCE_ENVS)
+    ]
+    for name, value in (extra_env or {}).items():
+        filtered = [e for e in filtered if not (isinstance(e, dict) and e.get("name") == name)]
+        filtered.append({"name": name, "value": value})
+    filtered.append({"name": RUNTIME_STORE_LOCAL_ENV, "value": "true"})
+    doc["env"] = filtered
+    # The Apps CLI rejects hidden or hyphenated entry-point filenames.
+    dev_yaml = app_yaml.parent / _LOCAL_APP_YAML
+    try:
+        dev_yaml.write_text(yaml.safe_dump(doc, sort_keys=False))
+    except OSError as exc:
+        raise AgentCliError(f"Could not write {dev_yaml}: {exc}") from exc
+    return dev_yaml

databricks_agentbricks/cli/endpoint.py

@@ -0,0 +1,145 @@
+"""CLI entry point for invoking arbitrary HTTP endpoints."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import replace
+from typing import Optional
+from uuid import uuid4
+
+import click
+
+from databricks_agentbricks.cli.deploy import _app_url, _prefixed_name
+from databricks_agentbricks.cli.endpoint_output import SsePrinter, render_response
+from databricks_agentbricks.cli.endpoint_request import build_request
+from databricks_agentbricks.cli.endpoint_transport import HttpSession
+from databricks_agentbricks.errors import AgentCliError
+from databricks_agentkit._api_client import _workspace_client
+
+_ROUTING_COOKIE = "__Host-databricks-app-router"
+
+
+def _resolve_endpoint(
+    app: str | None,
+    url: str | None,
+    profile: Optional[str],
+) -> tuple[str, bool]:
+    if app and url:
+        raise AgentCliError("APP and --url are mutually exclusive.")
+    if url:
+        return url.rstrip("/"), False
+    if not app:
+        raise AgentCliError(
+            "Provide a Databricks App name or --url.",
+            hint="Use --url http://localhost:8000 when running the agent locally.",
+        )
+    app_name = _prefixed_name(app)
+    resolved_url = _app_url(app_name, profile)
+    if not resolved_url:
+        raise AgentCliError(f"Could not resolve a URL for Databricks App {app_name!r}.")
+    return resolved_url.rstrip("/"), True
+
+
+def _authorization_header(profile: Optional[str]) -> str:
+    try:
+        client = _workspace_client(profile)
+        if client.config.auth_type == "pat":
+            raise AgentCliError(
+                "Databricks Apps API routes require OAuth; the selected profile uses a PAT.",
+                hint="Authenticate the same workspace with `databricks auth login`.",
+            )
+        authorization = client.config.authenticate().get("Authorization")
+    except AgentCliError:
+        raise
+    except Exception as exc:  # noqa: BLE001 - render auth failures without a traceback
+        raise AgentCliError(f"Could not initialize endpoint authentication: {exc}.") from exc
+    if not authorization:
+        raise AgentCliError("Could not resolve an OAuth access token for the endpoint request.")
+    return authorization
+
+
+def _platform_headers(
+    *,
+    authenticate: bool,
+    profile: Optional[str],
+    session_id: str | None,
+) -> dict[str, str]:
+    headers: dict[str, str] = {}
+    if authenticate:
+        headers["Authorization"] = _authorization_header(profile)
+    if session_id:
+        headers["Cookie"] = f"{_ROUTING_COOKIE}={session_id}"
+    return headers
+
+
+@click.group()
+def endpoint() -> None:
+    """Invoke arbitrary HTTP endpoints."""
+
+
+@click.command("invoke")
+@click.argument("app", required=False, metavar="[APP]")
+@click.option("--url", default=None, help="Base URL for localhost or an arbitrary HTTP server.")
+@click.option("--method", default="POST", show_default=True)
+@click.option("--path", required=True, help="Request path, such as /api/invocations.")
+@click.option("--query", "query", multiple=True, help="Query parameter as 'name=value'.")
+@click.option("--json", "json_value", default=None, help="Complete JSON request body.")
+@click.option("--sse", is_flag=True, help="Consume the response as Server-Sent Events.")
+@click.option(
+    "--session-id",
+    default=None,
+    help="Application session id (default: generated for a Databricks App).",
+)
+@click.option("--timeout", type=click.FloatRange(min=0.1), default=300.0, show_default=True)
+@click.option("--auth/--no-auth", default=None, help="Inject Databricks OAuth authentication.")
+@click.pass_obj
+def invoke(
+    obj,
+    app,
+    url,
+    method,
+    path,
+    query,
+    json_value,
+    sse,
+    session_id,
+    timeout,
+    auth,
+) -> None:
+    """Send one HTTP request to a Databricks App or arbitrary URL."""
+    base_url, is_app = _resolve_endpoint(app, url, obj.profile)
+    authenticate = is_app if auth is None else auth
+    session_id = session_id or (str(uuid4()) if is_app else None)
+    request = build_request(
+        base_url=base_url,
+        method=method,
+        path=path,
+        query=query,
+        json_value=json_value,
+        timeout=timeout,
+        sse=sse,
+    )
+    request = replace(
+        request,
+        headers={
+            **request.headers,
+            **_platform_headers(
+                authenticate=authenticate,
+                profile=obj.profile,
+                session_id=session_id,
+            ),
+        },
+    )
+    printer = SsePrinter(enabled=sse and obj.output == "text")
+    response = HttpSession().send(request, on_event=printer)
+    if not 200 <= response.status_code < 300:
+        raise AgentCliError(
+            f"Endpoint returned HTTP {response.status_code}.",
+            hint=json.dumps(response.body, default=str)[:1000]
+            if response.body is not None
+            else None,
+        )
+    render_response(response, output=obj.output, streamed=sse)
+
+
+endpoint.add_command(invoke)

databricks_agentbricks/cli/endpoint_examples.py

@@ -0,0 +1,33 @@
+"""Copy-pasteable examples for invoking Agent Bricks-generated agent endpoints."""
+
+from __future__ import annotations
+
+import shlex
+
+from rich.text import Text
+
+from databricks_agentbricks import render
+
+
+def agent_invoke_command(target: str, *, uses_runtime_api: bool) -> str:
+    """Build a single-line example, generating a fresh runtime invocation ID on every run."""
+    path = "/api/invocations" if uses_runtime_api else "/invocations"
+    body = '{"input":[{"role":"user","content":"hi"}]}'
+    if uses_runtime_api:
+        # Double quotes allow command substitution while preserving the JSON's literal quotes.
+        body = '{"id":"$(uuidgen)",' + body[1:]
+        json_arg = '"' + body.replace('"', r"\"") + '"'
+    else:
+        json_arg = shlex.quote(body)
+    return f"ab endpoint invoke {target} --path {path} --json {json_arg}"
+
+
+def print_agent_invoke_command(target: str, *, uses_runtime_api: bool) -> None:
+    """Print only the new invocation example without changing the existing success panel."""
+    con = render.console()
+    con.print(Text("Invoke with Agent Bricks", style=render.SECONDARY))
+    # A separate, soft-wrapped line avoids copying panel borders or inserted line breaks.
+    con.print(
+        Text(agent_invoke_command(target, uses_runtime_api=uses_runtime_api), style=render.COMMAND),
+        soft_wrap=True,
+    )

databricks_agentbricks/cli/endpoint_output.py

@@ -0,0 +1,53 @@
+"""Output rendering for endpoint commands."""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+import click
+
+from databricks_agentbricks import render
+from databricks_agentbricks.cli.endpoint_transport import EndpointResponse
+
+
+def render_response(response: EndpointResponse, *, output: str, streamed: bool) -> None:
+    """Render an endpoint response in JSON or human-readable form."""
+    if output == "json":
+        render.emit_json(_response_payload(response))
+        return
+    if streamed:
+        return
+    if isinstance(response.body, (dict, list)):
+        render.emit_json(response.body)
+    elif response.body is not None:
+        click.echo(str(response.body))
+
+
+def _response_payload(response: EndpointResponse) -> dict[str, Any]:
+    payload: dict[str, Any] = {
+        "url": response.url,
+        "status_code": response.status_code,
+        "elapsed_seconds": round(response.elapsed_seconds, 6),
+    }
+    if response.events:
+        payload["events"] = list(response.events)
+    else:
+        payload["body"] = response.body
+    return payload
+
+
+class SsePrinter:
+    """Print SSE data values as they arrive."""
+
+    def __init__(self, *, enabled: bool):
+        self.enabled = enabled
+
+    def __call__(self, event: dict[str, Any]) -> None:
+        if not self.enabled:
+            return
+        data = event.get("data")
+        if isinstance(data, str):
+            click.echo(data)
+        else:
+            click.echo(json.dumps(data, default=str))

databricks_agentbricks/cli/endpoint_request.py

@@ -0,0 +1,71 @@
+"""Generic HTTP request construction for Agent Bricks endpoint commands."""
+
+from __future__ import annotations
+
+import json
+import urllib.parse
+from typing import Any, Mapping
+
+from databricks_agentbricks.cli.endpoint_transport import EndpointRequest
+from databricks_agentbricks.errors import AgentCliError
+
+
+def parse_pairs(values: tuple[str, ...], *, separator: str, description: str) -> dict[str, str]:
+    """Parse repeatable CLI key/value options."""
+    parsed: dict[str, str] = {}
+    for value in values:
+        key, found, item = value.partition(separator)
+        key = key.strip()
+        if not found or not key or "\n" in key or "\n" in item:
+            raise AgentCliError(f"Invalid {description} {value!r}.")
+        parsed[key] = item.strip()
+    return parsed
+
+
+def load_json(value: str | None) -> Any:
+    """Validate and decode an optional JSON request body."""
+    if value is None:
+        return None
+    try:
+        return json.loads(value)
+    except json.JSONDecodeError as exc:
+        raise AgentCliError(f"Invalid JSON request body: {exc}.") from exc
+
+
+def request_url(base_url: str, path: str, query: Mapping[str, str]) -> str:
+    """Join a request path to a base URL and merge query parameters."""
+    parsed_path = urllib.parse.urlsplit(path)
+    if parsed_path.scheme or parsed_path.netloc:
+        raise AgentCliError("--path must be relative to the selected endpoint URL.")
+    joined = urllib.parse.urljoin(f"{base_url}/", path)
+    if not query:
+        return joined
+    parsed = urllib.parse.urlsplit(joined)
+    merged_query = dict(urllib.parse.parse_qsl(parsed.query, keep_blank_values=True))
+    merged_query.update(query)
+    return urllib.parse.urlunsplit(parsed._replace(query=urllib.parse.urlencode(merged_query)))
+
+
+def build_request(
+    *,
+    base_url: str,
+    method: str,
+    path: str,
+    query: tuple[str, ...],
+    json_value: str | None,
+    timeout: float,
+    sse: bool,
+) -> EndpointRequest:
+    """Materialize one generic HTTP request."""
+    body = load_json(json_value)
+    request_query = parse_pairs(query, separator="=", description="query parameter")
+    headers = {"Content-Type": "application/json"} if json_value is not None else {}
+    return EndpointRequest(
+        url=request_url(base_url, path, request_query),
+        method=method.upper(),
+        headers=headers,
+        body=body,
+        timeout=timeout,
+        sse=sse,
+        body_set=json_value is not None,
+    )