Skip to content

datarobot_genai.dragent.deployment_urls

deployment_urls

Shared URL construction utilities for DataRobot deployment endpoints.

These helpers are the single source of truth for the URL patterns used to reach a DataRobot-hosted A2A agent and to look up its agent card from the central registry. Both the server side (advertising its own URL in the agent card) and the client side (deriving the RPC base URL from a deployment_id) use these functions so that the patterns stay in sync automatically.

When a workload is served from an Envoy-fronted enclave, :func:resolve_external_workload_base is the agent's own gateway route and :func:resolve_external_workload_api_endpoint is the enclave's /api/v2 base (memory service, and so on) — distinct from the control-hub DATAROBOT_ENDPOINT.

join_mount_path 

join_mount_path(base: str, mount_path: str) -> str

Append mount_path to base, returning a single trailing slash either way.

A generic composer, not an A2A-specific policy: DRAgentA2AConfig never actually produces an empty mount_path (mounting A2A at the application root is rejected there), but this function still handles it, collapsing to base's own trailing slash rather than leaving a // behind. Slashes on both sides are stripped before joining so callers need not agree on which side owns the separator.

Parameters

base: Path the mount hangs off, e.g. "deployments/xyz/directAccess". mount_path: Path suffix A2A is mounted under, possibly empty.

Returns

str "{base}/{mount_path}/", or "{base}/" when mount_path is empty.

Source code in datarobot_genai/dragent/deployment_urls.py 
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
def join_mount_path(base: str, mount_path: str) -> str:
    """Append ``mount_path`` to ``base``, returning a single trailing slash either way.

    A generic composer, not an A2A-specific policy: ``DRAgentA2AConfig`` never actually
    produces an empty ``mount_path`` (mounting A2A at the application root is rejected
    there), but this function still handles it, collapsing to ``base``'s own trailing
    slash rather than leaving a ``//`` behind. Slashes on both sides are stripped before
    joining so callers need not agree on which side owns the separator.

    Parameters
    ----------
    base:
        Path the mount hangs off, e.g. ``"deployments/xyz/directAccess"``.
    mount_path:
        Path suffix A2A is mounted under, possibly empty.

    Returns
    -------
    str
        ``"{base}/{mount_path}/"``, or ``"{base}/"`` when ``mount_path`` is empty.
    """
    root = base.rstrip("/")
    suffix = mount_path.strip("/")
    return f"{root}/{suffix}/" if suffix else f"{root}/"

normalize_api_v2_endpoint 

normalize_api_v2_endpoint(endpoint: str) -> str

Return endpoint with exactly one trailing /api/v2 and no trailing slash.

Callers hand us DATAROBOT_ENDPOINT in both spellings — with and without the /api/v2 suffix — and the deployment / workload routes live below it. Normalising in one place keeps .../api/v2/api/v2/... and .../deployments/... (missing /api/v2) out of the URL builders.

Parameters

endpoint: DataRobot endpoint

str The endpoint with a single /api/v2 suffix.

Source code in datarobot_genai/dragent/deployment_urls.py 
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
def normalize_api_v2_endpoint(endpoint: str) -> str:
    """Return ``endpoint`` with exactly one trailing ``/api/v2`` and no trailing slash.

    Callers hand us ``DATAROBOT_ENDPOINT`` in both spellings — with and without
    the ``/api/v2`` suffix — and the deployment / workload routes live below it.
    Normalising in one place keeps ``.../api/v2/api/v2/...`` and
    ``.../deployments/...`` (missing ``/api/v2``) out of the URL builders.

    Parameters
    ----------
    endpoint:
        DataRobot endpoint
    -------
    str
        The endpoint with a single ``/api/v2`` suffix.
    """
    base = endpoint.rstrip("/")
    if base.endswith(_API_V2_SUFFIX):
        return base
    return f"{base}{_API_V2_SUFFIX}"

resolve_datarobot_endpoint 

resolve_datarobot_endpoint(require: bool = False) -> str | None

Return the effective DataRobot API endpoint from the environment.

Checks environment variables in priority order:

  1. DATAROBOT_PUBLIC_API_ENDPOINT — preferred for externally reachable URLs (on-prem deployments often set DATAROBOT_ENDPOINT to an internal k8s address while DATAROBOT_PUBLIC_API_ENDPOINT holds the public URL).
  2. DATAROBOT_ENDPOINT — standard SDK variable.
  3. Built-in default (https://app.datarobot.com/api/v2) when require is False.
Parameters

require: When True, raises :class:ValueError if neither env var is set. When False (default), falls back to the built-in default endpoint.

Returns

str | None The resolved endpoint string, or None only when require is False and both env vars are unset (returns the default instead, so in practice this always returns a non-None value when require=False).

Raises

ValueError If require=True and neither DATAROBOT_PUBLIC_API_ENDPOINT nor DATAROBOT_ENDPOINT is set.

Source code in datarobot_genai/dragent/deployment_urls.py 
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
def resolve_datarobot_endpoint(require: bool = False) -> str | None:
    """Return the effective DataRobot API endpoint from the environment.

    Checks environment variables in priority order:

    1. ``DATAROBOT_PUBLIC_API_ENDPOINT`` — preferred for externally reachable URLs
       (on-prem deployments often set ``DATAROBOT_ENDPOINT`` to an internal k8s
       address while ``DATAROBOT_PUBLIC_API_ENDPOINT`` holds the public URL).
    2. ``DATAROBOT_ENDPOINT`` — standard SDK variable.
    3. Built-in default (``https://app.datarobot.com/api/v2``) when ``require``
       is *False*.

    Parameters
    ----------
    require:
        When *True*, raises :class:`ValueError` if neither env var is set.
        When *False* (default), falls back to the built-in default endpoint.

    Returns
    -------
    str | None
        The resolved endpoint string, or *None* only when ``require`` is
        *False* **and** both env vars are unset (returns the default instead,
        so in practice this always returns a non-None value when
        ``require=False``).

    Raises
    ------
    ValueError
        If ``require=True`` and neither ``DATAROBOT_PUBLIC_API_ENDPOINT`` nor
        ``DATAROBOT_ENDPOINT`` is set.
    """
    endpoint = os.getenv("DATAROBOT_PUBLIC_API_ENDPOINT") or os.getenv("DATAROBOT_ENDPOINT")
    if endpoint:
        return endpoint
    if require:
        raise ValueError("DATAROBOT_PUBLIC_API_ENDPOINT or DATAROBOT_ENDPOINT must be set.")
    return _DEFAULT_DATAROBOT_ENDPOINT

resolve_external_workload_base 

resolve_external_workload_base() -> str | None

Return the API gateway's base URL for this workload, or None when not behind one.

An Envoy API gateway serves a workload from a per-enclave host and path prefix that DATAROBOT_ENDPOINT cannot derive, so it injects both as env vars. Their presence is the signal that the URLs composed elsewhere in this module are unreachable; both are required. The host is accepted with or without a scheme (https:// assumed).

Returns

str | None https://{host}/{prefix}, no trailing slash, or None when either var is unset.

Source code in datarobot_genai/dragent/deployment_urls.py 
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
def resolve_external_workload_base() -> str | None:
    """Return the API gateway's base URL for this workload, or *None* when not behind one.

    An Envoy API gateway serves a workload from a per-enclave host and path prefix that
    ``DATAROBOT_ENDPOINT`` cannot derive, so it injects both as env vars.  Their presence is
    the signal that the URLs composed elsewhere in this module are unreachable; both are
    required.  The host is accepted with or without a scheme (``https://`` assumed).

    Returns
    -------
    str | None
        ``https://{host}/{prefix}``, no trailing slash, or *None* when either var is unset.
    """
    host = _external_workload_host()
    if host is None:
        return None
    prefix = os.getenv(WORKLOAD_EXTERNAL_PREFIX_ENV, "").strip()
    return f"{host}/{prefix.strip('/')}"

resolve_external_workload_api_endpoint 

resolve_external_workload_api_endpoint() -> str | None

Return the enclave API gateway's /api/v2 endpoint, or None when not behind one.

Same presence signal as :func:resolve_external_workload_base (both host and prefix). The prefix is this workload's own route and is not part of the platform API base — only the host is used, so the DataRobot client talks to services on the enclave (memory, and so on) rather than the control hub.

Returns

str | None https://{host}/api/v2, no trailing slash, or None when either var is unset.

Source code in datarobot_genai/dragent/deployment_urls.py 
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
def resolve_external_workload_api_endpoint() -> str | None:
    """Return the enclave API gateway's ``/api/v2`` endpoint, or *None* when not behind one.

    Same presence signal as :func:`resolve_external_workload_base` (both host and prefix).
    The prefix is this workload's own route and is not part of the platform API base —
    only the host is used, so the DataRobot client talks to services on the enclave
    (memory, and so on) rather than the control hub.

    Returns
    -------
    str | None
        ``https://{host}/api/v2``, no trailing slash, or *None* when either var is unset.
    """
    host = _external_workload_host()
    if host is None:
        return None
    return normalize_api_v2_endpoint(host)

build_deployment_a2a_url 

build_deployment_a2a_url(endpoint: str, deployment_id: str, mount_path: str = A2A_MOUNT_PATH) -> str

Construct the A2A direct-access URL for a DataRobot deployment.

directAccess forwards the full prefixed path to the container, so the suffix the agent actually mounted A2A under has to appear here too or the advertised URL would not resolve.

Parameters

endpoint: DataRobot API endpoint base URL, e.g. https://app.datarobot.com/api/v2. A trailing slash is stripped before composing the URL. deployment_id: The DataRobot deployment ID. mount_path: Path suffix A2A is mounted under inside the container, "a2a" by default. DRAgentA2AConfig never passes "" (it rejects mounting A2A at the application root), but this generic composer still accepts it.

Returns

str A URL of the form {endpoint}/deployments/{deployment_id}/directAccess/a2a/, with a2a replaced by mount_path and omitted entirely when it is empty.

Source code in datarobot_genai/dragent/deployment_urls.py 
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
def build_deployment_a2a_url(
    endpoint: str, deployment_id: str, mount_path: str = A2A_MOUNT_PATH
) -> str:
    """Construct the A2A direct-access URL for a DataRobot deployment.

    ``directAccess`` forwards the full prefixed path to the container, so the suffix
    the agent actually mounted A2A under has to appear here too or the advertised URL
    would not resolve.

    Parameters
    ----------
    endpoint:
        DataRobot API endpoint base URL, e.g. ``https://app.datarobot.com/api/v2``.
        A trailing slash is stripped before composing the URL.
    deployment_id:
        The DataRobot deployment ID.
    mount_path:
        Path suffix A2A is mounted under inside the container, ``"a2a"`` by default.
        ``DRAgentA2AConfig`` never passes ``""`` (it rejects mounting A2A at the
        application root), but this generic composer still accepts it.

    Returns
    -------
    str
        A URL of the form ``{endpoint}/deployments/{deployment_id}/directAccess/a2a/``,
        with ``a2a`` replaced by ``mount_path`` and omitted entirely when it is empty.
    """
    base = endpoint.rstrip("/")
    return join_mount_path(
        f"{base}/deployments/{deployment_id}/{DEPLOYMENT_DIRECT_ACCESS_PATH}", mount_path
    )

build_deployment_agent_card_url 

build_deployment_agent_card_url(endpoint: str, deployment_id: str) -> str

Construct the agent card registry URL for a DataRobot deployment.

Parameters

endpoint: DataRobot API endpoint base URL, e.g. https://app.datarobot.com/api/v2. A trailing slash is stripped before composing the URL. deployment_id: The DataRobot deployment ID.

Returns

str A URL of the form {endpoint}/deployments/{deployment_id}/agentCard/.

Source code in datarobot_genai/dragent/deployment_urls.py 
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
def build_deployment_agent_card_url(endpoint: str, deployment_id: str) -> str:
    """Construct the agent card registry URL for a DataRobot deployment.

    Parameters
    ----------
    endpoint:
        DataRobot API endpoint base URL, e.g. ``https://app.datarobot.com/api/v2``.
        A trailing slash is stripped before composing the URL.
    deployment_id:
        The DataRobot deployment ID.

    Returns
    -------
    str
        A URL of the form ``{endpoint}/deployments/{deployment_id}/agentCard/``.
    """
    base = endpoint.rstrip("/")
    return f"{base}/deployments/{deployment_id}/agentCard/"

build_workload_a2a_url 

build_workload_a2a_url(endpoint: str, workload_id: str, mount_path: str = A2A_MOUNT_PATH) -> str

Construct the A2A URL for a DataRobot workload.

The workload route forwards the full prefixed path to the container, so the suffix the agent actually mounted A2A under has to appear here too or the advertised URL would not resolve.

Parameters

endpoint: DataRobot API endpoint base URL, e.g. https://app.datarobot.com/api/v2. A trailing slash is stripped before composing the URL. workload_id: The DataRobot workload ID. mount_path: Path suffix A2A is mounted under inside the container, "a2a" by default. DRAgentA2AConfig never passes "" (it rejects mounting A2A at the application root), but this generic composer still accepts it.

Returns

str A URL of the form {endpoint}/endpoints/workloads/{workload_id}/a2a/, with a2a replaced by mount_path and omitted entirely when it is empty.

Source code in datarobot_genai/dragent/deployment_urls.py 
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
def build_workload_a2a_url(
    endpoint: str, workload_id: str, mount_path: str = A2A_MOUNT_PATH
) -> str:
    """Construct the A2A URL for a DataRobot workload.

    The workload route forwards the full prefixed path to the container, so the suffix
    the agent actually mounted A2A under has to appear here too or the advertised URL
    would not resolve.

    Parameters
    ----------
    endpoint:
        DataRobot API endpoint base URL, e.g. ``https://app.datarobot.com/api/v2``.
        A trailing slash is stripped before composing the URL.
    workload_id:
        The DataRobot workload ID.
    mount_path:
        Path suffix A2A is mounted under inside the container, ``"a2a"`` by default.
        ``DRAgentA2AConfig`` never passes ``""`` (it rejects mounting A2A at the
        application root), but this generic composer still accepts it.

    Returns
    -------
    str
        A URL of the form ``{endpoint}/endpoints/workloads/{workload_id}/a2a/``, with
        ``a2a`` replaced by ``mount_path`` and omitted entirely when it is empty.
    """
    base = endpoint.removesuffix("/")
    return join_mount_path(f"{base}/endpoints/workloads/{workload_id}", mount_path)

build_deployment_mcp_url 

build_deployment_mcp_url(endpoint: str, deployment_id: str) -> str

Construct the MCP URL.

Parameters

endpoint: DataRobot endpoint, with or without the /api/v2 suffix. deployment_id: The DataRobot deployment ID.

Returns

str A URL of the form {endpoint}/api/v2/deployments/{deployment_id}/directAccess/mcp.

Source code in datarobot_genai/dragent/deployment_urls.py 
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
def build_deployment_mcp_url(endpoint: str, deployment_id: str) -> str:
    """Construct the MCP  URL.

    Parameters
    ----------
    endpoint:
        DataRobot endpoint, with or without the ``/api/v2`` suffix.
    deployment_id:
        The DataRobot deployment ID.

    Returns
    -------
    str
        A URL of the form
        ``{endpoint}/api/v2/deployments/{deployment_id}/directAccess/mcp``.
    """
    base = normalize_api_v2_endpoint(endpoint)
    return f"{base}/deployments/{deployment_id}/{DEPLOYMENT_MCP_PATH}"

workload_mcp_url_from_endpoint 

workload_mcp_url_from_endpoint(workload_endpoint: str, path: str = MCP_PATH) -> str

Append the MCP path to the endpoint the platform reported for a workload.

This is the only way to address a workload's MCP server: its route cannot be composed from a workload ID, due to different endpoints for the API Gateway. We look up the endpoint from the workload API (:func:datarobot_genai.core.mcp.config.lookup_workload_endpoint) and append the path to what it reports.

Parameters

workload_endpoint: The workload's endpoint field as returned by the Workload API. path: Path the MCP server is served from, relative to the endpoint.

Returns

str {workload_endpoint}/{path}, with duplicate slashes avoided.

Source code in datarobot_genai/dragent/deployment_urls.py 
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
def workload_mcp_url_from_endpoint(workload_endpoint: str, path: str = MCP_PATH) -> str:
    """Append the MCP path to the endpoint the platform reported for a workload.

    This is the only way to address a workload's MCP server: its route cannot be
    composed from a workload ID, due to different endpoints for the API Gateway.
    We look up the endpoint from the workload API
    (:func:`datarobot_genai.core.mcp.config.lookup_workload_endpoint`) and append
    the path to what it reports.

    Parameters
    ----------
    workload_endpoint:
        The workload's ``endpoint`` field as returned by the Workload API.
    path:
        Path the MCP server is served from, relative to the endpoint.

    Returns
    -------
    str
        ``{workload_endpoint}/{path}``, with duplicate slashes avoided.
    """
    return f"{workload_endpoint.rstrip('/')}/{path.lstrip('/')}"

build_local_mcp_url 

build_local_mcp_url(port: int, host: str = 'localhost') -> str

Construct the MCP URL for an MCP server running locally.

Parameters

port: Port the local MCP server listens on. host: Host name, localhost by default.

Returns

str A URL of the form http://localhost:{port}/mcp.

Source code in datarobot_genai/dragent/deployment_urls.py 
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
def build_local_mcp_url(port: int, host: str = "localhost") -> str:
    """Construct the MCP URL for an MCP server running locally.

    Parameters
    ----------
    port:
        Port the local MCP server listens on.
    host:
        Host name, ``localhost`` by default.

    Returns
    -------
    str
        A URL of the form ``http://localhost:{port}/mcp``.
    """
    return f"http://{host}:{port}/{MCP_PATH}"

build_workload_agent_card_url 

build_workload_agent_card_url(endpoint: str, workload_id: str) -> str

Construct the agent card URL for a DataRobot workload.

Parameters

endpoint: DataRobot API endpoint base URL, e.g. https://app.datarobot.com/api/v2. A trailing slash is stripped before composing the URL. workload_id: The DataRobot workload ID.

Returns

str A URL of the form {endpoint}/workloads/{workload_id}/agentCard/.

Source code in datarobot_genai/dragent/deployment_urls.py 
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
def build_workload_agent_card_url(endpoint: str, workload_id: str) -> str:
    """Construct the agent card URL for a DataRobot workload.

    Parameters
    ----------
    endpoint:
        DataRobot API endpoint base URL, e.g. ``https://app.datarobot.com/api/v2``.
        A trailing slash is stripped before composing the URL.
    workload_id:
        The DataRobot workload ID.

    Returns
    -------
    str
        A URL of the form ``{endpoint}/workloads/{workload_id}/agentCard/``.
    """
    base = endpoint.removesuffix("/")
    return f"{base}/workloads/{workload_id}/agentCard/"

build_agent_cards_registry_url 

build_agent_cards_registry_url(endpoint: str) -> str

Construct the URL for the central agent card registry.

The central registry lists all agent cards within the user's organisation (tenant context) and requires only API-token authentication, not the per-agent AuthZ that the agent's own card endpoint demands.

Parameters

endpoint: DataRobot API endpoint base URL, e.g. https://app.datarobot.com/api/v2. A trailing slash is stripped before composing the URL.

Returns

str A URL of the form {endpoint}/agentCards/.

Source code in datarobot_genai/dragent/deployment_urls.py 
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
def build_agent_cards_registry_url(endpoint: str) -> str:
    """Construct the URL for the central agent card registry.

    The central registry lists all agent cards within the user's organisation
    (tenant context) and requires only API-token authentication, not the
    per-agent AuthZ that the agent's own card endpoint demands.

    Parameters
    ----------
    endpoint:
        DataRobot API endpoint base URL, e.g. ``https://app.datarobot.com/api/v2``.
        A trailing slash is stripped before composing the URL.

    Returns
    -------
    str
        A URL of the form ``{endpoint}/agentCards/``.
    """
    base = endpoint.rstrip("/")
    return f"{base}/agentCards/"