utility Module

Provides utility functions for the Tooling components.

Functions

build_mcp_server_url

Constructs the full MCP server URL using the base URL and server name.

build_mcp_server_url(server_name: str) -> str

Parameters

Name Description
server_name
Required
str

The MCP server name.

Returns

Type Description
str

The full MCP server URL.

get_chat_history_endpoint

Gets the chat history endpoint URL for sending chat history to the MCP platform.

get_chat_history_endpoint() -> str

Returns

Type Description
str

The chat history endpoint URL.

get_mcp_base_url

Gets the base URL for MCP servers.

get_mcp_base_url() -> str

Returns

Type Description
str

The base URL for MCP servers.

get_mcp_platform_authentication_scope

Gets the MCP platform authentication scope.

get_mcp_platform_authentication_scope() -> list[str]

Returns

Type Description
list[str]

A list containing the appropriate MCP platform authentication scope.

get_tooling_gateway_for_digital_worker

Gets the tooling gateway URL for the specified digital worker.

get_tooling_gateway_for_digital_worker(agentic_app_id: str) -> str

Parameters

Name Description
agentic_app_id
Required
str

The agentic app identifier of the digital worker.

Returns

Type Description
str

The tooling gateway URL for the digital worker.

is_development_environment

Returns True if the current environment is configured as development.

Resolution order (first non-empty value wins):

  1. PYTHON_ENVIRONMENT — explicit Python SDK variable used in current samples.
  2. ENVIRONMENT — legacy Python SDK variable (backward compatibility).
  3. ASPNETCORE_ENVIRONMENT — Azure hosting convention.
  4. DOTNET_ENVIRONMENT — generic-host convention.
  5. Defaults to "Development" when none of the above are set.

PYTHON_ENVIRONMENT and ENVIRONMENT are checked first so that agents which explicitly set ENVIRONMENT=Production are not affected if a host process also sets ASPNETCORE_ENVIRONMENT.

is_development_environment() -> bool

Returns

Type Description
bool

True when the resolved environment is "development" (case-insensitive).

resolve_token_scope_for_server

Resolve the OAuth scope to request for a given MCP server.

V2 servers carry their own audience in the audience field (bare GUID or api:// URI form). When an explicit scope is provided (e.g. "Tools.ListInvoke.All"), the scope is {audience}/{scope}. When scope is absent, {audience}/.default is used (relies on pre-consented scopes). V1 servers (no audience, audience equals the shared ATG AppId in bare GUID or api:// URI form) always fall back to the shared ATG /.default scope.

resolve_token_scope_for_server(server: MCPServerConfig) -> str

Parameters

Name Description
server
Required
MCPServerConfig

The MCP server configuration to resolve the scope for.

Returns

Type Description
str

The OAuth scope string, e.g. "<guid>/Tools.ListInvoke.All", "api://<guid>/.default", or the shared ATG "<atg-guid>/.default".