Refactor agent_user_id to agent_instance_id

Replaced `agent_user_id` with `agent_instance_id` across the codebase to standardize the unique identifier for agents. Updated method signatures, arguments, logging, and validation logic to reflect this change.

Aligned token scope handling with the new authentication mechanism by replacing `get_ppapi_token_scope` with `get_mcp_platform_authentication_scope`. Removed legacy token scopes and updated constants accordingly.

Modified tooling gateway URL generation to use `agent_instance_id`. Updated documentation, examples, and logging to ensure consistency with the new identifier.

Author: sellakumaran

libraries/microsoft-agents-a365-tooling-extensions-agentframework/README.md

@@ -82,7 +82,7 @@ async def main():
         chat_client=chat_client,
         agent_instructions="You are a helpful assistant that can provide weather and restaurant information.",
         initial_tools=[],  # Your existing tools
-        agent_user_id="user-123",
+        agent_instance_id="user-123",
         environment_id="prod",
         auth_token="your-auth-token"
     )
@@ -139,7 +139,7 @@ async def main():
         loaded from configured servers. Use these tools to enhance your capabilities.
         """,
         initial_tools=existing_tools,
-        agent_user_id="user-123",
+        agent_instance_id="user-123",
         environment_id="production",
         auth_token="your-auth-token"
     )
@@ -190,7 +190,7 @@ agent = await service.add_tool_servers_to_agent(
     chat_client=chat_client,
     agent_instructions="You are a helpful assistant with access to various tools.",
     initial_tools=[],  # Your existing tools
-    agent_user_id="user-123",
+    agent_instance_id="user-123",
     environment_id="prod",
     auth_token="your-token"
 )

libraries/microsoft-agents-a365-tooling-extensions-agentframework/microsoft_agents_a365/tooling/extensions/agentframework/services/mcp_tool_registration_service.py

@@ -41,7 +41,7 @@ async def add_tool_servers_to_agent(
         chat_client: Union[OpenAIChatClient, AzureOpenAIChatClient],
         agent_instructions: str,
         initial_tools: List[Any],
-        agent_user_id: str,
+        agent_instance_id: str,
         environment_id: str,
         auth: Optional[Authorization] = None,
         auth_token: Optional[str] = None,
@@ -54,7 +54,7 @@ async def add_tool_servers_to_agent(
             chat_client: The chat client instance (Union[OpenAIChatClient, AzureOpenAIChatClient])
             agent_instructions: Instructions for the agent behavior
             initial_tools: List of initial tools to add to the agent
-            agent_user_id: Unique identifier for the agent user
+            agent_instance_id: Unique identifier for the agent instance
             environment_id: Environment identifier for MCP server discovery
             auth: Optional authorization context
             auth_token: Optional bearer token for authentication
@@ -65,12 +65,12 @@ async def add_tool_servers_to_agent(
         """
         try:
             self._logger.info(
-                f"Listing MCP tool servers for agent {agent_user_id} in environment {environment_id}"
+                f"Listing MCP tool servers for agent {agent_instance_id} in environment {environment_id}"
             )
 
             # Get MCP server configurations
             server_configs = await self._mcp_server_configuration_service.list_tool_servers(
-                agent_user_id=agent_user_id,
+                agent_instance_id=agent_instance_id,
                 environment_id=environment_id,
                 auth_token=auth_token,
             )

libraries/microsoft-agents-a365-tooling-extensions-azureaifoundry/microsoft_agents_a365/tooling/extensions/azureaifoundry/services/mcp_tool_registration_service.py

@@ -18,7 +18,7 @@
 from azure.ai.agents.models import McpTool, ToolResources
 from microsoft_agents.hosting.core import Authorization, TurnContext
 
-from ...common.utils.utility import get_ppapi_token_scope, get_use_environment_id
+from ...common.utils.utility import get_mcp_platform_authentication_scope, get_use_environment_id
 
 # Local imports
 from microsoft_kairo.tooling.common.services.mcp_tool_server_configuration_service import (
@@ -72,7 +72,7 @@ def __init__(
     async def add_tool_servers_to_agent(
         self,
         project_client: "AIProjectClient",
-        agent_user_id: str,
+        agent_instance_id: str,
         environment_id: str,
         auth: Authorization,
         context: TurnContext,
@@ -83,7 +83,7 @@ async def add_tool_servers_to_agent(
 
         Args:
             project_client: The Azure Foundry AIProjectClient instance.
-            agent_user_id: Agent User ID for the agent.
+            agent_instance_id: Agent Instance ID for the agent.
             environment_id: Environment ID for the environment.
             auth_token: Authentication token to access the MCP servers.
 
@@ -95,19 +95,19 @@ async def add_tool_servers_to_agent(
             raise ValueError("project_client cannot be None")
 
         if not auth_token:
-            scopes = get_ppapi_token_scope()
+            scopes = get_mcp_platform_authentication_scope()
             authToken = await auth.exchange_token(context, scopes, "AGENTIC")
             auth_token = authToken.token
 
         try:
             # Get the tool definitions and resources using the async implementation
             tool_definitions, tool_resources = await self._get_mcp_tool_definitions_and_resources(
-                agent_user_id, environment_id, auth_token or ""
+                agent_instance_id, environment_id, auth_token or ""
             )
 
             # Update the agent with the tools
             project_client.agents.update_agent(
-                agent_user_id, tools=tool_definitions, tool_resources=tool_resources
+                agent_instance_id, tools=tool_definitions, tool_resources=tool_resources
             )
 
             self._logger.info(
@@ -116,20 +116,20 @@ async def add_tool_servers_to_agent(
 
         except Exception as ex:
             self._logger.error(
-                f"Unhandled failure during MCP tool registration workflow for agent user {agent_user_id}: {ex}"
+                f"Unhandled failure during MCP tool registration workflow for agent user {agent_instance_id}: {ex}"
             )
             raise
 
     async def _get_mcp_tool_definitions_and_resources(
-        self, agent_user_id: str, environment_id: str, auth_token: str
+        self, agent_instance_id: str, environment_id: str, auth_token: str
     ) -> Tuple[List[McpTool], Optional[ToolResources]]:
         """
         Internal method to get MCP tool definitions and resources.
 
         This implements the core logic equivalent to the C# method of the same name.
 
         Args:
-            agent_user_id: Agent User ID for the agent.
+            agent_instance_id: Agent Instance ID for the agent.
             environment_id: Environment ID for the environment.
             auth_token: Authentication token to access the MCP servers.
 
@@ -143,17 +143,17 @@ async def _get_mcp_tool_definitions_and_resources(
         # Get MCP server configurations
         try:
             servers = await self._mcp_server_configuration_service.list_tool_servers(
-                agent_user_id, environment_id, auth_token
+                agent_instance_id, environment_id, auth_token
             )
         except Exception as ex:
             self._logger.error(
-                f"Failed to list MCP tool servers for AgentUserId={agent_user_id}: {ex}"
+                f"Failed to list MCP tool servers for AgentInstanceId={agent_instance_id}: {ex}"
             )
             return ([], None)
 
         if len(servers) == 0:
             self._logger.info(
-                f"No MCP servers configured for AgentUserId={agent_user_id}, EnvironmentId={environment_id}"
+                f"No MCP servers configured for AgentInstanceId={agent_instance_id}, EnvironmentId={environment_id}"
             )
             return ([], None)
 

libraries/microsoft-agents-a365-tooling-extensions-openai/README.md

@@ -53,7 +53,7 @@ registration_service = McpToolRegistrationService()
 # Add MCP tool servers to your OpenAI agent
 await registration_service.add_tool_servers_to_agent(
     agent=your_openai_agent,
-    agent_user_id="user-123",
+    agent_instance_id="user-123",
     environment_id="prod",
     auth=authorization_context,
     context=turn_context,

libraries/microsoft-agents-a365-tooling-extensions-openai/microsoft_agents_a365/tooling/extensions/openai/mcp_tool_registration_service.py

@@ -17,7 +17,7 @@
 )
 
 from microsoft_agents_a365.tooling.utils.utility import (
-    get_ppapi_token_scope,
+    get_mcp_platform_authentication_scope,
     get_use_environment_id,
 )
 
@@ -51,7 +51,7 @@ def __init__(self, logger: Optional[logging.Logger] = None):
     async def add_tool_servers_to_agent(
         self,
         agent: Agent,
-        agent_user_id: str,
+        agent_instance_id: str,
         environment_id: str,
         auth: Authorization,
         context: TurnContext,
@@ -66,7 +66,7 @@ async def add_tool_servers_to_agent(
 
         Args:
             agent: The existing agent to add servers to
-            agent_user_id: Agent User ID for the agent
+            agent_instance_id: Agent Instance ID for the agent
             environment_id: Environment ID for the environment
             auth_token: Authentication token to access the MCP servers
 
@@ -75,18 +75,18 @@ async def add_tool_servers_to_agent(
         """
 
         if not auth_token:
-            scopes = get_ppapi_token_scope()
+            scopes = get_mcp_platform_authentication_scope()
             authToken = await auth.exchange_token(context, scopes, "AGENTIC")
             auth_token = authToken.token
 
         # Get MCP server configurations from the configuration service
         # mcp_server_configs = []
         # TODO: radevika: Update once the common project is merged.
         self._logger.info(
-            f"Listing MCP tool servers for agent {agent_user_id} in environment {environment_id}"
+            f"Listing MCP tool servers for agent {agent_instance_id} in environment {environment_id}"
         )
         mcp_server_configs = await self.config_service.list_tool_servers(
-            agent_user_id=agent_user_id, environment_id=environment_id, auth_token=auth_token
+            agent_instance_id=agent_instance_id, environment_id=environment_id, auth_token=auth_token
         )
 
         self._logger.info(f"Loaded {len(mcp_server_configs)} MCP server configurations")

libraries/microsoft-agents-a365-tooling-extensions-semantickernel/README.md

@@ -55,7 +55,7 @@ registration_service = McpToolRegistrationService()
 # Add MCP tool servers to your Semantic Kernel
 await registration_service.add_tool_servers_to_kernel(
     kernel=kernel,
-    agent_user_id="user-123",
+    agent_instance_id="user-123",
     environment_id="prod",
     auth_token="your-auth-token"
 )

libraries/microsoft-agents-a365-tooling-extensions-semantickernel/microsoft_agents_a365/tooling/extensions/semantickernel/services/mcp_tool_registration_service.py

@@ -24,7 +24,7 @@
 )
 from ...common.models import MCPServerConfig
 from ...common.utils.constants import Constants
-from ...common.utils.utility import get_tools_mode, get_ppapi_token_scope, get_use_environment_id
+from ...common.utils.utility import get_tools_mode, get_mcp_platform_authentication_scope, get_use_environment_id
 
 
 from semantic_kernel.connectors.mcp import MCPStreamableHttpPlugin
@@ -80,7 +80,7 @@ def __init__(
     async def add_tool_servers_to_agent(
         self,
         kernel: sk.Kernel,
-        agent_user_id: str,
+        agent_instance_id: str,
         environment_id: str,
         auth: Authorization,
         context: TurnContext,
@@ -91,7 +91,7 @@ async def add_tool_servers_to_agent(
 
         Args:
             kernel: The Semantic Kernel instance to which the tools will be added.
-            agent_user_id: Agent User ID for the agent.
+            agent_instance_id: Agent Instance ID for the agent.
             environment_id: Environment ID for the environment.
             auth_token: Authentication token to access the MCP servers.
 
@@ -101,15 +101,15 @@ async def add_tool_servers_to_agent(
         """
 
         if not auth_token:
-            scopes = get_ppapi_token_scope()
+            scopes = get_mcp_platform_authentication_scope()
             authToken = await auth.exchange_token(context, scopes, "AGENTIC")
             auth_token = authToken.token
 
-        self._validate_inputs(kernel, agent_user_id, environment_id, auth_token)
+        self._validate_inputs(kernel, agent_instance_id, environment_id, auth_token)
 
         # Get and process servers
         servers = await self._mcp_server_configuration_service.list_tool_servers(
-            agent_user_id, environment_id, auth_token
+            agent_instance_id, environment_id, auth_token
         )
         self._logger.info(f"🔧 Adding MCP tools from {len(servers)} servers")
 
@@ -174,13 +174,13 @@ async def add_tool_servers_to_agent(
     # ============================================================================
 
     def _validate_inputs(
-        self, kernel: Any, agent_user_id: str, environment_id: str, auth_token: str
+        self, kernel: Any, agent_instance_id: str, environment_id: str, auth_token: str
     ) -> None:
         """Validate all required inputs."""
         if kernel is None:
             raise ValueError("kernel cannot be None")
-        if not agent_user_id or not agent_user_id.strip():
-            raise ValueError("agent_user_id cannot be null or empty")
+        if not agent_instance_id or not agent_instance_id.strip():
+            raise ValueError("agent_instance_id cannot be null or empty")
         if not environment_id or not environment_id.strip():
             raise ValueError("environment_id cannot be null or empty")
         if not auth_token or not auth_token.strip():

libraries/microsoft-agents-a365-tooling/README.md

@@ -58,7 +58,7 @@ mcp_config = MCPServerConfig(
 # Use configuration service to list available MCP servers
 config_service = McpToolServerConfigurationService()
 mcp_servers = await config_service.list_tool_servers(
-    agent_user_id="agent-123",
+    agent_instance_id="agent-123",
     environment_id="prod",
     auth_token="your-auth-token"
 )

libraries/microsoft-agents-a365-tooling/microsoft_agents_a365/tooling/services/mcp_tool_server_configuration_service.py

@@ -70,13 +70,13 @@ def __init__(self, logger: Optional[logging.Logger] = None):
     # --------------------------------------------------------------------------
 
     async def list_tool_servers(
-        self, agent_user_id: str, environment_id: str, auth_token: str
+        self, agent_instance_id: str, environment_id: str, auth_token: str
     ) -> List[MCPServerConfig]:
         """
         Gets the list of MCP Servers that are configured for the agent.
 
         Args:
-            agent_user_id: Agent User ID for the agent.
+            agent_instance_id: Agent Instance ID for the agent.
             environment_id: Environment ID for the environment.
             auth_token: Authentication token to access the MCP servers.
 
@@ -88,17 +88,17 @@ async def list_tool_servers(
             Exception: If there's an error communicating with the tooling gateway.
         """
         # Validate input parameters
-        self._validate_input_parameters(agent_user_id, environment_id, auth_token)
+        self._validate_input_parameters(agent_instance_id, environment_id, auth_token)
 
         self._logger.info(
-            f"Listing MCP tool servers for agent {agent_user_id} in environment {environment_id}"
+            f"Listing MCP tool servers for agent {agent_instance_id} in environment {environment_id}"
         )
 
         # Determine configuration source based on environment
         if self._is_development_scenario():
             return self._load_servers_from_manifest(environment_id)
         else:
-            return await self._load_servers_from_gateway(agent_user_id, environment_id, auth_token)
+            return await self._load_servers_from_gateway(agent_instance_id, environment_id, auth_token)
 
     # --------------------------------------------------------------------------
     # ENVIRONMENT DETECTION
@@ -290,13 +290,13 @@ def _log_manifest_search_failure(self) -> None:
     # --------------------------------------------------------------------------
 
     async def _load_servers_from_gateway(
-        self, agent_user_id: str, environment_id: str, auth_token: str
+        self, agent_instance_id: str, environment_id: str, auth_token: str
     ) -> List[MCPServerConfig]:
         """
         Reads MCP server configurations from tooling gateway endpoint for production scenario.
 
         Args:
-            agent_user_id: Agent User ID for the agent.
+            agent_instance_id: Agent Instance ID for the agent.
             environment_id: Environment ID for the environment.
             auth_token: Authentication token to access the tooling gateway.
 
@@ -309,7 +309,7 @@ async def _load_servers_from_gateway(
         mcp_servers: List[MCPServerConfig] = []
 
         try:
-            config_endpoint = get_tooling_gateway_for_digital_worker(agent_user_id)
+            config_endpoint = get_tooling_gateway_for_digital_worker(agent_instance_id)
             headers = self._prepare_gateway_headers(auth_token, environment_id)
 
             self._logger.info(f"Calling tooling gateway endpoint: {config_endpoint}")
@@ -445,21 +445,21 @@ def _parse_gateway_server_config(
     # --------------------------------------------------------------------------
 
     def _validate_input_parameters(
-        self, agent_user_id: str, environment_id: str, auth_token: str
+        self, agent_instance_id: str, environment_id: str, auth_token: str
     ) -> None:
         """
         Validates input parameters for the main API method.
 
         Args:
-            agent_user_id: Agent User ID to validate.
+            agent_instance_id: Agent Instance ID to validate.
             environment_id: Environment ID to validate.
             auth_token: Authentication token to validate.
 
         Raises:
             ValueError: If any parameter is invalid or empty.
         """
-        if not agent_user_id:
-            raise ValueError("agent_user_id cannot be empty or None")
+        if not agent_instance_id:
+            raise ValueError("agent_instance_id cannot be empty or None")
         if not environment_id:
             raise ValueError("environment_id cannot be empty or None")
         if not auth_token:

libraries/microsoft-agents-a365-tooling/microsoft_agents_a365/tooling/utils/__init__.py

@@ -10,7 +10,7 @@
     get_mcp_base_url,
     build_mcp_server_url,
     get_tools_mode,
-    get_ppapi_token_scope,
+    get_mcp_platform_authentication_scope,
 )
 
 __all__ = [
@@ -19,5 +19,5 @@
     "get_mcp_base_url",
     "build_mcp_server_url",
     "get_tools_mode",
-    "get_ppapi_token_scope",
+    "get_mcp_platform_authentication_scope",
 ]