diff --git a/learndocs-archive/docs-conceptual/AIShell/concepts/what-is-a-command-shell.md b/learndocs-archive/docs-conceptual/AIShell/concepts/what-is-a-command-shell.md new file mode 100644 index 00000000..0de9b505 --- /dev/null +++ b/learndocs-archive/docs-conceptual/AIShell/concepts/what-is-a-command-shell.md @@ -0,0 +1,100 @@ +--- +title: What is a command shell? +ms.date: 01/12/2026 +description: Learn what a command shell is and how it works. +ms.collection: ce-skilling-ai-copilot +--- +# What is a command shell? + +[!INCLUDE[aishell-deprecated](../../../includes/aishell-deprecated.md)] + +A command shell is a text-based interface for interacting with a computer, also known as a +Read-Eval-Print Loop ([REPL][15]). + +A shell takes input from the keyboard, evaluates that input, and executes the input as a shell +command or gives the input to the operating system to be executed. Most shells can also read +commands from a script file, and may include programming features like variables, flow control, and +functions. + +## Terminals + +A terminal is an application that provides a text-based interface for hosting command shells. Some +terminals are designed to work with a specific shell, while others can host multiple shells. They +may also include advanced features such as: + +- Ability to create multiple panes within a single window +- Ability to create multiple tabs to host multiple shells +- Ability to change color schemes and fonts +- Support for copy and paste operations + +The following list contains some examples of terminal applications: + +- [Windows Terminal][11] - a modern terminal application for Windows that can host multiple shells. +- [Windows Console Host][10] - the default host application on Windows for text-based applications. + It can also host the Windows Command Shell or PowerShell. +- [Terminal for macOS][14] - the default terminal application on macOS that can host the bash or zsh + shell. +- [iTerm2 for macOS][12] - a popular 3rd-party terminal application for macOS. +- [Azure Cloud Shell][02] - a browser-based terminal application that's hosted in Microsoft Azure. + Azure Cloud shell gives you the choice of using bash or PowerShell and come preconfigured with + many command-line tools to manage Azure resources. + +## General purpose command shells + +General purpose command shells are designed to work with the operating system. These shell allow you +to run any command that the operating system supports. They also include shell-specific commands and +programming features. The following list contains some examples of general purpose command shells: + +- [PowerShell][05] +- [Windows Command Shell][07] +- [bash][16] - popular on Linux +- [zsh][13] - popular on macOS + +## Utility command shells + +Utility command shells are designed to work with specific applications or services. These shells can +only run commands that are specific to the application or service. Some utility shells support +running commands from a script file, but they don't include programming features. Usually, these +shells can only be used interactively. + +- [AI Shell][01] - An interactive-only shell used to communicate with AI services such as Azure + OpenAI. +- [netsh][08] - Network shell (netsh) is a command-line utility that allows you to configure and + display the status of various network components on Windows. It is both a command-line tool and a + command shell. It also supports running commands from a script file. + +## Command-line tools + +A command-line tool is a standalone program that's run from a command shell. Command-line tools are +typically designed to perform a specific task, such as managing files, configuring settings, or +querying for information. Command-line tools can be used in any shell that supports running external +programs. + +- [Azure CLI][03] - a collection of command-line tools for managing Azure resources that can be run + in any supported shell. +- [Azure PowerShell][04] - a collection of PowerShell modules for managing Azure resources that can + be run in any supported version of PowerShell. +- [OpenSSH for Windows][06] - a command-line client, as well as a server, for secure communication + over a network. +- [Windows Commands][09] - a collection of command-line tools that are built into Windows. + +In general, command-line tools don't provide a command shell (REPL) interface. The `netsh` command +in Windows is an exception, as it's both a command-line tool and an interactive command shell. + + +[01]: ../overview.md +[02]: /azure/cloud-shell/overview +[03]: /cli/azure +[04]: /powershell/azure +[05]: /powershell/scripting/overview +[06]: /windows-server/administration/openssh/openssh-overview +[07]: /windows-server/administration/windows-commands/cmd +[08]: /windows-server/administration/windows-commands/netsh +[09]: /windows-server/administration/windows-commands/windows-commands +[10]: /windows/console/consoles +[11]: /windows/terminal +[12]: https://iterm2.com/ +[13]: https://support.apple.com/102360 +[14]: https://support.apple.com/guide/terminal/welcome/mac +[15]: https://wikipedia.org/wiki/Read%E2%80%93eval%E2%80%93print_loop +[16]: https://www.gnu.org/software/bash/ diff --git a/learndocs-archive/docs-conceptual/AIShell/developer/agent-architecture.md b/learndocs-archive/docs-conceptual/AIShell/developer/agent-architecture.md new file mode 100644 index 00000000..113ee332 --- /dev/null +++ b/learndocs-archive/docs-conceptual/AIShell/developer/agent-architecture.md @@ -0,0 +1,63 @@ +--- +title: Architecture of AI Shell +description: This article explains the architecture of AI Shell and API required to support agents. +ms.date: 01/12/2026 +ms.topic: concept-article +ms.collection: ce-skilling-ai-copilot +--- +# AI Shell architecture + +[!INCLUDE[aishell-deprecated](../../../includes/aishell-deprecated.md)] + +![AI Shell architecture diagram.][01] + +## AIShell.Abstraction + +This project will be released as a NuGet package. It contains all the interfaces for defining an +agent plugin that interacts with AI Shell. + +This abstraction layer includes: + +- `IShell`: Represents a proxy of the AI shell. +- `IHost`: Represents a proxy of the shell host. +- `IRenderElement`: Represents the `header/value` or `label/value` pairs for rendering objects in + table or list format. +- `IStreamRender`: Represents a special render for rendering streaming response. +- `ILLMAgent`: Represents an agent plugin. +- `IOrchestrator`: Derives `ILLMAgent`. Represents a special agent that can route a query to the + most suitable agent. +- `ICodeAnalyzer`: Derives `ILLMAgent`. Represents a special agent that can analyze code for + security concerns. +- `CommandBase`: represents a command that an agent can register to the shell when being loaded. + +The most important interface method in `ILLMAgent` is `Task Chat(string input, IShell shell)`, +which will be called by the shell when a query comes from the user. It gives extreme flexibility to +the implementation of an agent. An agent can do whatever it wants targeting an arbitrary AI backend +and render the output using the utilities provided by `IShell`. + +An agent plugin is responsible for managing its own chat history. + +## AIShell.Kernel + +This is the implementation of AI Shell. It consists of the following components: + +- ReadLine +- Renders (markdown render, stream render, paging render) +- Plugin management +- Host (a range of utility methods for writing output and interactive prompting) +- Command runner and built-in commands +- Utilities (clipboard, tab completion, predictive intellisense) + - Code execution for `python`, `powershell`, `cmd`, and `bash` (to enable agents to do function + calling with LLM. **not-yet-started**) +- Shell integration (deep integration with the command-line shell. **not-yet-started**) +- Configuration (colors, key bindings, and etc. **not-yet-started**) + +## AIShell.App + +This is a thin wrapper over `AIShell.Kernel` to create an executable. The initial idea is to +make `AIShell.Kernel` a library, so it can be used or hosted by other applications. We can +easily merge `AIShell.App` into `AIShell.Kernel` if this idea no longer make sense. + + +[01]: media/agent-architecture/aishell-agent-architecture.png + diff --git a/learndocs-archive/docs-conceptual/AIShell/developer/create-ollama-agent.md b/learndocs-archive/docs-conceptual/AIShell/developer/create-ollama-agent.md new file mode 100644 index 00000000..06d26b23 --- /dev/null +++ b/learndocs-archive/docs-conceptual/AIShell/developer/create-ollama-agent.md @@ -0,0 +1,508 @@ +--- +title: How to create an agent for Ollama +description: Learn how to create an agent for the Ollama language model in AI Shell. +ms.date: 01/12/2026 +ms.topic: how-to +ms.collection: ce-skilling-ai-copilot +--- +# Creating an Agent + +[!INCLUDE[aishell-deprecated](../../../includes/aishell-deprecated.md)] + +An agent is a code library that interfaces with the AI Shell to talk to a specific large +language model or other assistance provider. Users chat with the agents using natural language to +get the desired output or assistance. Agents are implemented as C# classes that implement the +`ILLMAgent` interface from the `AIShell.Abstraction` package. + +For details about the `AIShell.Abstraction` layer and `AIShell.Kernel`, see the +[AI Shell architecture][05] documentation. + +This article is a step-by-step guide to creating an agent for the [Ollama][01] language model. The +purpose of this article is to provide a simple example of how to create an agent. There's a more +robust implementation of the Ollama agent in the [`AIShell.Ollama.Agent`][04] folder of the +repository. + +## Prerequisites + +- .NET 8 SDK or newer +- PowerShell 7.4.6 or newer + +## Steps to create an agent + +For this example, we create an agent to communicate with the language model `phi3` using +[Ollama][01]. Ollama is a CLI tool for managing and using locally built LLM/SLMs. + +### Step 1: Create a new project + +First step is to create a new **classlib** project. + +1. Create a new folder named `OllamaAgent` +1. Run the following command to create a new project: + + ```shell + dotnet new classlib + ``` + +### Step 2: Add the necessary packages + +Within the newly created project, you need to install the [AIShell.Abstraction][06] package from the +NuGet gallery. Install the NuGet package using the following command: + +```shell +dotnet add package AIShell.Abstraction --version 1.0.0-preview.2 +``` + +This command adds the package to your `.csproj` file. Your `.csproj` file should contain the +following XML: + +```xml + + + + net8.0 + enable + true + + + + + + +``` + +> [!IMPORTANT] +> Be sure to check you are on the latest version from the NuGet gallery. + +### Step 3: Implement the agent class + +To implement the `ILLMAgent` interface, modify the `Class1.cs` file. + +1. Rename the file to `OllamaAgent.cs` +1. Rename the class to `OllamaAgent` +1. Add the .NET namespaces that are used by the code in the implementation + +```csharp +using System.Diagnostics; +using System.Text; +using System.Text.Json; +using AIShell.Abstraction; + +namespace AIShell.Ollama.Agent; + +public sealed class OllamaAgent : ILLMAgent +{ + +} +``` + +### Step 4: Add necessary class members and methods + +Next, implement the necessary variables and methods of the agent class. The comments provide +descriptions of the members of the **OllamaAgent** class. The `_chatService` member is an instance +of the **OllamaChatService** class, which you implement in a later step. + +```csharp +public sealed class OllamaAgent : ILLMAgent +{ + /// + /// The name of the agent + /// + public string Name => "ollama"; + + /// + /// The description of the agent to be shown at start up + /// + public string Description => "This is an AI assistant that uses the Ollama CLI tool. Be sure to follow all prerequisites in https://aka.ms/ollama/readme"; + + /// + /// This is the company added to `/like` and `/dislike` verbiage for who the telemetry helps. + /// + public string Company => "Microsoft"; + + /// + /// These are samples that are shown at start up for good questions to ask the agent + /// + public List SampleQueries => [ + "How do I list files in a given directory?" + ]; + + /// + /// These are any optional legal/additional information links you want to provide at start up + /// + public Dictionary LegalLinks { private set; get; } + + /// + /// This is the chat service to call the API from + /// + private OllamaChatService _chatService; + + /// + /// A string builder to render the text at the end + /// + private StringBuilder _text; + + /// + /// Dispose method to clean up the unmanaged resource of the chatService + /// + public void Dispose() + { + _chatService?.Dispose(); + } + + /// + /// Initializing function for the class when the shell registers an agent + /// + /// Agent configuration for any configuration file and other settings + public void Initialize(AgentConfig config) + { + _text = new StringBuilder(); + _chatService = new OllamaChatService(); + + LegalLinks = new(StringComparer.OrdinalIgnoreCase) + { + ["Ollama Docs"] = "https://github.com/ollama/ollama", + ["Prerequisites"] = "https://aka.ms/ollama/readme" + }; + + } + + /// + /// Get commands that an agent can register to the shell when being loaded + /// + public IEnumerable GetCommands() => null; + + /// + /// Gets the path to the setting file of the agent. + /// + public string SettingFile { private set; get; } = null; + + /// + /// Refresh the current chat by starting a new chat session. + /// An agent can reset chat states in this method. + /// + public void RefreshChat() {} + + /// + /// Gets a value indicating whether the agent accepts a specific user action feedback. + /// + /// The user action. + public bool CanAcceptFeedback(UserAction action) => false; + + /// + /// A user action was taken against the last response from this agent. + /// + /// Type of the action. + /// + public void OnUserAction(UserActionPayload actionPayload) {} + + /// + /// Main chat function that takes + /// + /// The user input from the chat experience + /// The shell that provides host functionality + /// Task Boolean that indicates whether the query was served by the agent. + public async Task Chat(string input, IShell shell) + { + + } +} +``` + +For the initial implementation, the agent to returns "Hello World!", proving that you created the +correct interfaces. You also need to add a `try-catch` block to catch and handle any exceptions when +the user tries to cancel the operation. + +Add the following code to your `Chat` method. + +```csharp +public async Task Chat(string input, IShell shell) +{ + // Get the shell host + IHost host = shell.Host; + + // get the cancellation token + CancellationToken token = shell.CancellationToken; + + try + { + host.RenderFullResponse("Hello World!"); + } + catch (OperationCanceledException e) + { + _text.AppendLine(e.ToString()); + + host.RenderFullResponse(_text.ToString()); + + return false; + } + + return true; +} +``` + +### Step 5: Add Ollama check + +Next, you need to make sure that Ollama is running. + +```csharp +public async Task Chat(string input, IShell shell) +{ + // Get the shell host + IHost host = shell.Host; + + // get the cancellation token + CancellationToken token = shell.CancellationToken; + + if (Process.GetProcessesByName("ollama").Length is 0) + { + host.RenderFullResponse("Please be sure that Ollama is installed and the server is running. Ensure that you have met all the prerequisites in the README for this agent."); + return false; + } + + // Calls to the API will go here + + return true; +} +``` + +### Step 6: Create data structures to exchange data with the Chat Service + +Before you can use the Ollama API, you need to create classes that send input to and receive +responses from the Ollama API. The following [Ollama example][02] shows the format of the input and +the response from the agent. + +This example calls the Ollama API with streaming disabled. Ollama generates a single, fixed +response. In the future, you could add streaming capabilities so that responses could be rendered in +real time, as the agent receives them. + +To define the data structures, create a new file in the same folder named `OllamaSchema.cs`. Copy +the following code to the file. + +```csharp +namespace AIShell.Ollama.Agent; + +// Query class for the data to send to the endpoint +internal class Query +{ + public string prompt { get; set; } + public string model { get; set; } + + public bool stream { get; set; } +} + +// Response data schema +internal class ResponseData +{ + public string model { get; set; } + public string created_at { get; set; } + public string response { get; set; } + public bool done { get; set; } + public string done_reason { get; set; } + public int[] context { get; set; } + public double total_duration { get; set; } + public long load_duration { get; set; } + public int prompt_eval_count { get; set; } + public int prompt_eval_duration { get; set; } + public int eval_count { get; set; } + public long eval_duration { get; set; } +} + +internal class OllamaResponse +{ + public int Status { get; set; } + public string Error { get; set; } + public string Api_version { get; set; } + public ResponseData Data { get; set; } +} +``` + +Now you have the pieces needed to construct a chat service that uses the Ollama API. A separate chat +service class isn't required, but it's useful to abstract the calls to the API. + +Create a new file called `OllamaChatService.cs` in the same folder as the agent. Copy the example +code into the file. + +> [!TIP] +> This example uses a hard-coded endpoint and language model for the Ollama API. In the future, you +> could define configurable parameters in an agent configuration file. + +```csharp +using System.Net.Http.Headers; +using System.Text; +using System.Text.Json; + +using AIShell.Abstraction; + +namespace AIShell.Ollama.Agent; + +internal class OllamaChatService : IDisposable +{ + /// + /// Ollama endpoint to call to generate a response + /// + internal const string Endpoint = "http://localhost:11434/api/generate"; + + /// + /// Http client + /// + private readonly HttpClient _client; + + /// + /// Initialization method to initialize the http client + /// + + internal OllamaChatService() + { + _client = new HttpClient(); + } + + /// + /// Dispose of the http client + /// + public void Dispose() + { + _client.Dispose(); + } + + /// + /// Preparing chat with data to be sent + /// + /// The user input from the chat experience + /// The HTTP request message + private HttpRequestMessage PrepareForChat(string input) + { + // Main data to send to the endpoint + var requestData = new Query + { + model = "phi3", + prompt = input, + stream = false + }; + + var json = JsonSerializer.Serialize(requestData); + + var data = new StringContent(json, Encoding.UTF8, "application/json"); + var request = new HttpRequestMessage(HttpMethod.Post, Endpoint) { Content = data }; + + return request; + } + + /// + /// Getting the chat response async + /// + /// Interface for the status context used when displaying a spinner. + /// The user input from the chat experience + /// The cancellation token to exit out of request + /// Response data from the API call + internal async Task GetChatResponseAsync(IStatusContext context, string input, CancellationToken cancellationToken) + { + try + { + HttpRequestMessage request = PrepareForChat(input); + HttpResponseMessage response = await _client.SendAsync(request, cancellationToken); + response.EnsureSuccessStatusCode(); + + context?.Status("Receiving Payload ..."); + Console.Write(response.Content); + var content = await response.Content.ReadAsStreamAsync(cancellationToken); + return JsonSerializer.Deserialize(content); + } + catch (OperationCanceledException) + { + // Operation was cancelled by user. + } + + return null; + } +} + +``` + +### Step 7: Call the chat service + +Next, you need to call the chat service in the main agent class. Modify the `Chat()` method to call +the chat service and render the response to the user. The following example shows the completed +`Chat()` method. + +```csharp +public async Task Chat(string input, IShell shell) +{ + // Get the shell host + IHost host = shell.Host; + + // get the cancellation token + CancellationToken token = shell.CancellationToken; + + if (Process.GetProcessesByName("ollama").Length is 0) + { + host.RenderFullResponse("Please be sure that Ollama is installed and the server is running. Ensure that you have met all the prerequisites in the README for this agent."); + return false; + } + + ResponseData ollamaResponse = await host.RunWithSpinnerAsync( + status: "Thinking ...", + func: async context => await _chatService.GetChatResponseAsync(context, input, token) + ).ConfigureAwait(false); + + if (ollamaResponse is not null) + { + // render the content + host.RenderFullResponse(ollamaResponse.response); + } + + return true; +} +``` + +The agent code is complete. + +### Step 8: Build and test the agent + +Next, you need to build and test that the code is working as expected. Run the following command: + +```shell +dotnet build +``` + +This command builds all necessary packages in the `\bin\Debug\net8.0` folder of the project. + +To have `aish` load the agent, you need to copy the `.dll` files to a folder in the `Agents` folder. +The folder name should be the same as the agent name. + +You can install agents in one of two locations: + +- In the `Agents` folder under the location where you installed `aish.exe`. The + [install script][08] for AI Shell installs in `%LOCALAPPDATA%\Programs\AIShell`. Create the + `%LOCALAPPDATA%\Programs\AIShell\Agents\OllamaAgent` folder. +- As an alternative, you install agents in `%USERPROFILE%\.aish\Agents`. Create the + `%USERPROFILE%\.aish\Agents\OllamaAgent` folder. + +Copy the `.dll` files to agent folder you created. You should see the agent when you start `aish`. + +```shell +AI Shell +v1.0.0-preview.2 + +Please select an agent to use: + + azure + >ollama + openai-gpt +``` + +## How can I share my own agent? + +There's no way to share your agents in a centralized repository. We suggest forking this repository +for development of your own agent. You can share a link your fork in the `Agent Sharing` section of +the [Discussions][03] tab of this repository. To use an agent, put agent `dll` files in the `agents` +folder of the base directory of `aish.exe`. AI Shell automatically loads the agents from that +folder. + + +[01]: https://github.com/ollama/ollama +[02]: https://github.com/ollama/ollama/blob/main/docs/api.md#request-no-streaming +[03]: https://github.com/PowerShell/AIShell/discussions/categories/agent-sharing +[04]: https://github.com/PowerShell/AIShell/tree/main/shell/agents/AIShell.Ollama.Agent +[05]: https://github.com/PowerShell/AIShell/blob/main/shell/README.md +[06]: https://www.nuget.org/packages/AIShell.Abstraction + diff --git a/learndocs-archive/docs-conceptual/AIShell/developer/deploy-azure-openai.md b/learndocs-archive/docs-conceptual/AIShell/developer/deploy-azure-openai.md new file mode 100644 index 00000000..e15e1ef1 --- /dev/null +++ b/learndocs-archive/docs-conceptual/AIShell/developer/deploy-azure-openai.md @@ -0,0 +1,198 @@ +--- +title: Deploy the Azure OpenAI Service using Bicep +description: This article provides the step-by-step instructions to deploy and instance of the Azure OpenAI Service using Bicep. +ms.date: 01/12/2026 +ms.topic: concept-article +ms.collection: ce-skilling-ai-copilot +--- +# Deploy the Azure OpenAI Service using Bicep + +[!INCLUDE[aishell-deprecated](../../../includes/aishell-deprecated.md)] + +In AIShell, the **openai-gpt** agent can be used with a public OpenAI instance or an Azure OpenAI +deployment. We recommend using the Azure OpenAI Service because it has additional features and +provides better manageability. This article provides the step-by-step instructions to deploy and +instance of the Azure OpenAI Service using Bicep. + +To use AIShell with the Azure OpenAI Service, you need the following Azure resources: + +- An Azure OpenAI Service account - a resource that contains multiple different model deployments. +- An Azure OpenAI Deployment - a model deployment that can be called using an API to generate + responses. + +## Prerequisites + +Before you begin, ensure you have the following prerequisites: + +- An active Azure subscription +- [Azure CLI][04] or [Azure PowerShell][05] installed locally or access to Azure Cloud Shell +- Proper permissions to create resources in your Azure subscription + +## Steps to Deploy + +These steps walk you through the following tasks: + +1. Download and modify the Bicep file +1. Deploy the Azure OpenAI Service +1. Configure the agent to use the deployment + +### 1. Download and modify the Bicep file + +Download the [main.bicep][07] file from the AIShell repository. + +You must modify the parameters at the top of the `./main.bicep` file to include your own values. +Replace the placeholders in angle brackets (`< >`) with your own values. + +```bicep +@description('This is the name of your AI Service Account') +param aiserviceaccountname string = '' + +@description('Custom domain name for the endpoint') +param customDomainName string = '' + +@description('Name of the deployment') +param modeldeploymentname string = '' + +@description('The model being deployed') +param model string = 'gpt-4' + +@description('Version of the model being deployed') +param modelversion string = 'turbo-2024-04-09' + +@description('Capacity for specific model used') +param capacity int = 80 + +@description('Location for all resources.') +param location string = resourceGroup().location + +@allowed([ + 'S0' +]) +param sku string = 'S0' +``` + +For this deployment, the Bicep file uses the following defaults: + +- The location of the Azure OpenAI account is set to the location of the resource group +- The AI model is `gpt-4` version `turbo-2024-04-09` + +You can change these settings for your particular needs. For more information on available models, +see [Azure OpenAI Service models][01]. You might need to modify the capacity of the deployment based +the model you use. For more information about setting the capacity, see +[Azure OpenAI Service quotas and limits][02]. + +### 2. Deploy the Azure OpenAI Service + +After you modified the Bicep file parameters, you're ready to deploy your own Azure OpenAI +instance. You can use Azure CLI or Azure PowerShell to deploy the Bicep files. + +#### Deploy using Azure CLI + +Use the following Azure CLI commands to deploy the Azure OpenAI Service. The following commands are +intended to be run in a Bash session. Replace the placeholders in angle brackets (`< >`) with your +own values. + +You can run the commands locally or in Azure Cloud Shell. If you run them locally, you must sign in +to your Azure account using `az login` and set the subscription using +`az account set --subscription `. + +```azurecli-interactive +az deployment group create \ + --resource-group '' \ + --template-file ./main.bicep + +# Get the endpoint and key of the deployment +az cognitiveservices account show \ + --name '' + --resource-group '' | jq -r .properties.endpoint + +az cognitiveservices account keys list \ + --name '' \ + --resource-group '' | jq -r .key1 +``` + +#### Deploy using Azure PowerShell + +Use the following Azure PowerShell commands to deploy the Azure OpenAI Service. Replace the +placeholders in angle brackets (`< >`) with your own values. + +You can run the commands locally or in Azure Cloud Shell. If you run them locally, you must sign in +to your Azure account using `Connect-AzAccount` and set the subscription using +`Set-AzContext -SubscriptionId `. + +```azurepowershell-interactive +$AzResourceGroupDeploymentSplat = @{ + ResourceGroupName = '' + TemplateFile = './main.bicep' +} +New-AzResourceGroupDeployment @AzResourceGroupDeploymentSplat + +# Get the endpoint and key of the deployment +$AzCognitiveServicesAccountSplat = @{ + ResourceGroupName = '' + Name = '' +} +Get-AzCognitiveServicesAccount @AzCognitiveServicesAccountSplat | + Select-Object -Property Endpoint + +Get-AzCognitiveServicesAccountKey @AzCognitiveServicesAccountSplat | + Select-Object -Property Key1 +``` + +### 3. Configure the agent to use the deployment + +Now that you have the endpoint and key for the deployment, you need to configure the **openai-gpt** +agent. The configuration is stored in a JSON file. + +Use the following steps to edit the JSON configuration. + +1. Start AIShell and select the `openai-gpt` agent from the list of agents. +1. At the AIShell command prompt, run the `/agent config` command. This command opens the JSON + configuration file. +1. Replace the placeholder values in angle brackets (`< >`) in the JSON file with the endpoint and + key values you obtained from the Azure OpenAI deployment. The following JSON shows an example of + the configuration settings you want to update. + + ```json + { + // Declare GPT instances. + "GPTs": [ + { + "Name": "ps-az-gpt4", + "Description": "", + "Endpoint": "", + "Deployment": "", + "ModelName": "gpt-4", + "Key": "", + "SystemPrompt": "1. You are a helpful and friendly assistant with expertise in PowerShell scripting and command line.\n2. Assume user is using the operating system `osx` unless otherwise specified.\n3. Use the `code block` syntax in markdown to encapsulate any part in responses that is code, YAML, JSON or XML, but not table.\n4. When encapsulating command line code, use '```powershell' if it's PowerShell command; use '```sh' if it's non-PowerShell CLI command.\n5. When generating CLI commands, never ever break a command into multiple lines. Instead, always list all parameters and arguments of the command on the same line.\n6. Please keep the response concise but to the point. Do not overexplain." + } + ], + // Specify the default GPT instance to use for user query. + // For example: "ps-az-gpt4" + "Active": "ps-az-gpt4" + } + ``` + +1. Save the JSON file and close the editor. + +## Conclusion + +You successfully deployed the Azure OpenAI Service and configured your `openai-gpt` agent to +communicate with your deployment. For more information about model training, filters, and settings +for Azure OpenAI deployments, see [Azure OpenAI Service documentation][03]. + +> [!NOTE] +> We would like to thank Sebastian Jensen for his guidance on how to deploy the Azure OpenAI Service +> using Bicep files. This article was inspired by his blog post on Medium and used with permission. +> Take a moment to read his original post: +> [Deploy an Azure OpenAI service with LLM deployments via Bicep][06]. + + +[01]: /azure/ai-services/openai/concepts/models?tabs=global-standard%2Cstandard-chat- +[02]: /azure/ai-services/openai/quotas-limits +[03]: /azure/cognitive-services/openai/ +[04]: /cli/azure/install-azure-cli +[05]: /powershell/azure/install-azure-powershell +[06]: https://medium.com/medialesson/deploy-an-azure-openai-service-with-llm-deployments-via-bicep-244411472d40 +[07]: https://raw.githubusercontent.com/PowerShell/AIShell/refs/heads/main/docs/development/AzureOAIDeployment/main.bicep + diff --git a/learndocs-archive/docs-conceptual/AIShell/developer/media/agent-architecture/aishell-agent-architecture.png b/learndocs-archive/docs-conceptual/AIShell/developer/media/agent-architecture/aishell-agent-architecture.png new file mode 100644 index 00000000..e14a04b2 Binary files /dev/null and b/learndocs-archive/docs-conceptual/AIShell/developer/media/agent-architecture/aishell-agent-architecture.png differ diff --git a/learndocs-archive/docs-conceptual/AIShell/developer/ollama-agent-readme.md b/learndocs-archive/docs-conceptual/AIShell/developer/ollama-agent-readme.md new file mode 100644 index 00000000..7c0d1db8 --- /dev/null +++ b/learndocs-archive/docs-conceptual/AIShell/developer/ollama-agent-readme.md @@ -0,0 +1,46 @@ +--- +title: Ollama agent README +description: Learn how to use the Ollama agent in AI Shell. +ms.date: 01/12/2026 +ms.collection: ce-skilling-ai-copilot +--- +# Ollama Plugin + +[!INCLUDE[aishell-deprecated](../../../includes/aishell-deprecated.md)] + +This agent is used to interact with a language model running locally by utilizing the Ollama API. +Before using this agent you need to have Ollama installed and running. To create an agent, you need +to implement the `IAgent` interface. + +You can also use this example code as a template to create your own agent. + +## Pre-requisites to using the agent + +- Install [Ollama][01] +- Install a [Ollama model][02], we + suggest using the `phi3` model as it's set as the default model in the code +- [Start the Ollama API server][03] + +## Configuration + +Currently to change the model you will need to modify the query in the code in the +`OllamaChatService` class. The default model is `phi3`. + +The default endpoint is `http://localhost:11434/api/generate` with `11434` being the default port. +This can be changed in the code and eventually will be added to a configuration file. + +There is an updated version of the Ollama agent available in the AI Shell repository. See the +[README][04] file for the Ollama plugin. + +## Known Limitations + +- There is no history shared across queries so the model will not be able to remember previous + queries +- Streaming is currently not supported if you change the stream value to `true` in the data to send + to the API it will not work + + +[01]: https://github.com/ollama/ollama +[02]: https://github.com/ollama/ollama?tab=readme-ov-file#model-library +[03]: https://github.com/ollama/ollama?tab=readme-ov-file#start-ollama +[04]: https://github.com/PowerShell/AIShell/blob/v1.0.0-preview.2/shell/agents/AIShell.Ollama.Agent/README.md diff --git a/learndocs-archive/docs-conceptual/AIShell/get-started/aishell-powershell.md b/learndocs-archive/docs-conceptual/AIShell/get-started/aishell-powershell.md new file mode 100644 index 00000000..944432f6 --- /dev/null +++ b/learndocs-archive/docs-conceptual/AIShell/get-started/aishell-powershell.md @@ -0,0 +1,137 @@ +--- +description: This article explains how to install and configure AI Shell, and get started chatting with an AI assistant in PowerShell. +ms.date: 01/12/2026 +title: Get started with AI Shell in PowerShell +ms.topic: get-started +ms.collection: ce-skilling-ai-copilot +--- +# Get started with AI Shell in PowerShell + +[!INCLUDE[aishell-deprecated](../../../includes/aishell-deprecated.md)] + +AI Shell was created to help command line users find the right commands to use, recover from errors, +and better understand the commands and the output they produce. Follow along and walk through some +examples to get started with AI Shell. + +## Starting AI Shell + +Use the `Start-AIShell` command in the **AI Shell** module to open the sidecar experience in Windows +Terminal. When AI Shell starts, it prompts you to choose an agent. + +![An animation showing Getting Started with AI Shell.][05] + +## Using AI Shell + +Before you can use the Azure OpenAI agent, you must create a configuration that includes your +endpoint, API keys, and system prompt. Start AI Shell, select the agent, and run `/agent config`. +Within the JSON config file that is opened you will have to provide your endpoint, deployment name, +model version and API key. You can configure the system prompt property to better ground the model +to your specific use cases, the default included is for a PowerShell expert. Additionally if you +wish you use OpenAI you can configure the agent with just your API key from OpenAI in the commented +out example in the JSON file. + +The Azure agent is designed to bring the Azure Copilot experience directly to your command line. It +provides assistance for Azure CLI and Azure PowerShell commands. To use this agent, you need to sign +into Azure using the `az login` command from Azure CLI. + +## Use AI Shell to interact with the agents + +Use these sample queries with each agent. + +Azure OpenAI Agent + +- "How do I create a text file named helloworld in PowerShell?" +- "What is the difference between a switch and a parameter in PowerShell?" +- How do I get the top 10 most CPU intensive processes on my computer? + +Azure Copilot Agent + +- "How do I create a new resource group with Azure CLI?" +- "How can I list out the storage accounts I have in Azure PowerShell?" +- "What is Application Insights?" +- "How to create a web app with Azure CLI?" + +Here's a quick demo showing the Azure Agent in action: + +![An animation showing Azure Agent in action.][01] + +### Switching Agents + +You can switch between agents using the `@` syntax in your chat messages. For example, + +![An animation showing switching between two agents with the @ sign][06] + +You can also use a chat command to switch agents. For example, to switch to the `openai-gpt` agent, +use `/agent use openai-gpt`. + +### Chat commands + +By default, `aish` provides a base set of chat commands used to interact with the AI model. To get a +list of commands, use the `/help` command in the chat session. + +``` + Name Description Source +────────────────────────────────────────────────────────────────────── + /agent Command for agent management. Core + /cls Clear the screen. Core + /code Command to interact with the code generated. Core + /dislike Dislike the last response and send feedback. Core + /exit Exit the interactive session. Core + /help Show all available commands. Core + /like Like the last response and send feedback. Core + /refresh Refresh the chat session. Core + /render Render a markdown file, for diagnosis purpose. Core + /retry Regenerate a new response for the last query. Core +``` + +### Inserting code + +When chatting with the agent, you can use the `/code post` command to automatically insert +the code from the response into the working shell. This is the simplest way to quickly get the code +you need to run in your shell. You can also use the hot key Ctrl+d, +Ctrl+d to insert the code into the working shell. + +![An animation showing Inserting Code with AI Shell.][02] + +### Key bindings for commands + +AI Shell has key bindings for the `/code` command. They key bindings are currently hard-coded, but +custom key bindings will be supported in a future release. + +| Key bindings | Command | Functionality | +| -------------------------------------------------------- | ---------------- | ------------------------------------------------------------------- | +| Ctrl+dCtrl+c | `/code copy` | Copy _all_ the generated code snippets to clipboard | +| Ctrl+\ | `/code copy ` | Copy the _n-th_ generated code snippet to clipboard | +| Ctrl+dCtrl+d | `/code post` | Post _all_ the generated code snippets to the connected application | +| Ctrl+d\ | `/code post ` | Post the _n-th_ generated code snippet to the connected application | + +Additionally, you can switch between the panes easier using the following keyboard shortcuts. + +| Key bindings | Functionality | +| ------------------------------------ | --------------------------------------------- | +| Alt+RightArrow | Moves your cursor to the right AI Shell pane | +| Alt+LeftArrow | Moves your cursor to the left PowerShell pane | + +### Resolving Errors + +If you encounter an error in your working terminal, you can use the `Resolve-Error` cmdlet to send +that error to the open AI Shell window for resolution. This command asks the AI model to help you +resolve the error. + +![An animation showing Resolving Errors with AI Shell.][04] + +### Invoking AI Shell + +You can use the `Invoke-AIShell` cmdlet to send queries to the current agent in the open AI Shell window. +This command allows you to interact with the AI model from your working terminal. + +![An animation using Invoke-AIShell.][03] + + +[01]: media/aishell-powershell/azure-agent.gif +[02]: media/aishell-powershell/insert-code.gif +[03]: media/aishell-powershell/invoke-aishell.gif +[04]: media/aishell-powershell/resolve-error.gif +[05]: media/aishell-powershell/start-aishell.gif +[06]: media/aishell-powershell/switch-agents.gif + diff --git a/learndocs-archive/docs-conceptual/AIShell/get-started/aishell-standalone.md b/learndocs-archive/docs-conceptual/AIShell/get-started/aishell-standalone.md new file mode 100644 index 00000000..4eff3505 --- /dev/null +++ b/learndocs-archive/docs-conceptual/AIShell/get-started/aishell-standalone.md @@ -0,0 +1,100 @@ +--- +description: This article explains how to install and configure AI Shell, and get started chatting with an AI assistant. +ms.date: 01/12/2026 +title: Get started with AI Shell +ms.topic: get-started +ms.collection: ce-skilling-ai-copilot +--- +# Get started with AI Shell + +[!INCLUDE[aishell-deprecated](../../../includes/aishell-deprecated.md)] + +AI Shell was created to help command line users find the right commands to use, recover from errors, +and better understand the commands and the output they produce. Follow along and walk through some +examples to get started with AI Shell. + +## Starting AI Shell + +Run the `aish` command in the shell of your choice. AI Shell starts in a new terminal window and +prompts you to choose an agent. + +## Using AI Shell + +If you plan to use the Azure OpenAI agent, you will have to configure it with your endpoint, API +keys, and system prompt before using it. You can do so by selecting the agent and then running +`/agent config`. Within the JSON config file that is opened you will have to provide your endpoint, +deployment name, model version and API key. You can configure the system prompt property to better +ground the model to your specific use cases, the default included is for a PowerShell expert. +Additionally if you wish you use OpenAI you can configure the agent with just your API key from +OpenAI in the commented out example in the JSON file. + +![An animation showing Getting Started with AI Shell.][02] + +The Azure agent is designed to bring the Azure Copilot experience directly to your command line. It +provides assistance for Azure CLI and Azure PowerShell commands. To use this agent, you need to sign +into Azure using the `az login` command from Azure CLI. + +## Use AI Shell to interact with the agents + +Use these sample queries with each agent. + +Azure OpenAI Agent + +- "How do I create a text file named helloworld in PowerShell?" +- "What is the difference between a switch and a parameter in PowerShell?" +- How do I get the top 10 most CPU intensive processes on my computer? + +Azure Agent + +- "How do I create a new resource group with Azure CLI?" +- "How can I list out the storage accounts I have in Azure PowerShell?" +- "What is Application Insights?" +- "How to create a web app with Azure CLI?" + +### Switching Agents + +You can switch between agents using the `@` syntax in your chat messages. For example, + +![An animation showing switching between two agents with the @ sign][02] + +You can also use a chat command to switch agents. For example, to switch to the `openai-gpt` agent, +use `/agent use openai-gpt`. + +### Chat commands + +By default, `aish` provides a base set of chat commands used to interact with the AI model. To get a +list of commands, use the `/help` command in the chat session. + +``` + Name Description Source +────────────────────────────────────────────────────────────────────── + /agent Command for agent management. Core + /cls Clear the screen. Core + /code Command to interact with the code generated. Core + /dislike Dislike the last response and send feedback. Core + /exit Exit the interactive session. Core + /help Show all available commands. Core + /like Like the last response and send feedback. Core + /refresh Refresh the chat session. Core + /render Render a markdown file, for diagnosis purpose. Core + /retry Regenerate a new response for the last query. Core +``` + +Since you are using it as a standalone executable, the `/code post` command will not work. It is +designed for the sidecar experience with PowerShell 7. See +[Get started with AI Shell in PowerShell][01] for more information. + +### Key bindings for commands + +AI Shell has key bindings for the `/code` command. They key bindings are currently hard-coded, but +custom key bindings will be supported in a future release. + +| Key binding | Command | Description | +| --------------------------------------------- | ---------------- | --------------------------------------------------- | +| Ctrl+dCtrl+c | `/code copy` | Copy _all_ the generated code snippets to clipboard | +| Ctrl+\ | `/code copy ` | Copy the _n-th_ generated code snippet to clipboard | + + +[01]: aishell-powershell.md +[02]: media/aishell-standalone/standalone-startup.gif + diff --git a/learndocs-archive/docs-conceptual/AIShell/get-started/media/aishell-powershell/azure-agent.gif b/learndocs-archive/docs-conceptual/AIShell/get-started/media/aishell-powershell/azure-agent.gif new file mode 100644 index 00000000..7c54f3d0 Binary files /dev/null and b/learndocs-archive/docs-conceptual/AIShell/get-started/media/aishell-powershell/azure-agent.gif differ diff --git a/learndocs-archive/docs-conceptual/AIShell/get-started/media/aishell-powershell/insert-code.gif b/learndocs-archive/docs-conceptual/AIShell/get-started/media/aishell-powershell/insert-code.gif new file mode 100644 index 00000000..b6e2a331 Binary files /dev/null and b/learndocs-archive/docs-conceptual/AIShell/get-started/media/aishell-powershell/insert-code.gif differ diff --git a/learndocs-archive/docs-conceptual/AIShell/get-started/media/aishell-powershell/invoke-aishell.gif b/learndocs-archive/docs-conceptual/AIShell/get-started/media/aishell-powershell/invoke-aishell.gif new file mode 100644 index 00000000..1b58592c Binary files /dev/null and b/learndocs-archive/docs-conceptual/AIShell/get-started/media/aishell-powershell/invoke-aishell.gif differ diff --git a/learndocs-archive/docs-conceptual/AIShell/get-started/media/aishell-powershell/resolve-error.gif b/learndocs-archive/docs-conceptual/AIShell/get-started/media/aishell-powershell/resolve-error.gif new file mode 100644 index 00000000..02240570 Binary files /dev/null and b/learndocs-archive/docs-conceptual/AIShell/get-started/media/aishell-powershell/resolve-error.gif differ diff --git a/learndocs-archive/docs-conceptual/AIShell/get-started/media/aishell-powershell/start-aishell.gif b/learndocs-archive/docs-conceptual/AIShell/get-started/media/aishell-powershell/start-aishell.gif new file mode 100644 index 00000000..cfe6c5bc Binary files /dev/null and b/learndocs-archive/docs-conceptual/AIShell/get-started/media/aishell-powershell/start-aishell.gif differ diff --git a/learndocs-archive/docs-conceptual/AIShell/get-started/media/aishell-powershell/switch-agents.gif b/learndocs-archive/docs-conceptual/AIShell/get-started/media/aishell-powershell/switch-agents.gif new file mode 100644 index 00000000..90f41172 Binary files /dev/null and b/learndocs-archive/docs-conceptual/AIShell/get-started/media/aishell-powershell/switch-agents.gif differ diff --git a/learndocs-archive/docs-conceptual/AIShell/get-started/media/aishell-standalone/standalone-startup.gif b/learndocs-archive/docs-conceptual/AIShell/get-started/media/aishell-standalone/standalone-startup.gif new file mode 100644 index 00000000..abc2ef6c Binary files /dev/null and b/learndocs-archive/docs-conceptual/AIShell/get-started/media/aishell-standalone/standalone-startup.gif differ diff --git a/learndocs-archive/docs-conceptual/AIShell/how-to/agent-azure.md b/learndocs-archive/docs-conceptual/AIShell/how-to/agent-azure.md new file mode 100644 index 00000000..7509c73f --- /dev/null +++ b/learndocs-archive/docs-conceptual/AIShell/how-to/agent-azure.md @@ -0,0 +1,74 @@ +--- +title: Azure Copilot Agent +description: Learn how to use the Azure Copilot agent in AI Shell. +ms.date: 01/12/2026 +ms.collection: ce-skilling-ai-copilot +--- +# Azure Copilot Agent + +[!INCLUDE[aishell-deprecated](../../../includes/aishell-deprecated.md)] + +This agent is designed to connect you to the [**Azure Copilot**][02] experience directly from your +command line. It provides assistance for Azure CLI commands, Azure PowerShell commands, and general +Azure knowledge. To use this agent, you need to sign in to Azure using the `az login` command from +Azure CLI. + +## Prerequisites + +- Windows 11 21H2 or higher +- Windows Terminal v1.19 or higher +- [Azure CLI][01] version 2.30.0 or higher installed +- [Azure PowerShell][01] version 14.0.0 or higher installed +- A valid access token for your Azure tenant created by `az login` or `Connect-AzAccount` + +## Sample Questions + +- "How do I create a new resource group with Azure CLI?" +- "How can I list out the storage accounts I have in Azure PowerShell?" +- "What is Application Insights?" +- "How to create a web app with Azure CLI?" + +## Agent features + +This agent includes the following features: + +- Supports authentication using either the `Connect-AzAccount` command from Azure PowerShell or the + `az login` command from Azure CLI. Run these commands before starting AI Shell to ensure the token + cache has a valid access token. +- The `/replace` command supports Azure PowerShell. The agent walks you through replacement of + parameter values in generated Azure PowerShell responses. + +## Telemetry and configuration + +The **Azure Copilot** agent captures a small set of telemetry data. The telemetry data captured +contains no personal identifiable information. The agent only captures product usage data to help us +improve the product experience. + +When you allow telemetry, the agent only collects the following information: + +- The `/` command that you used +- The number of questions asked +- The type of operating system used +- Any exceptions encountered during usage +- The details provided using the `/like` or `/dislike` commands + +You can disable this telemetry by modifying the **telemetry** property in the configuration file. +The Azure agent configuration is stored in a JSON file. You can view and edit the JSON config file +by using the `/agent config` command in AI Shell. The available settings are: + +```json +{ + "logging": true, + "telemetry": true +} +``` + +When logging is enabled, the agent writes logs in the `~/.aish/agent-config/azure` directory. To +disable logging, set the **logging** property to `false`. + +To disable telemetry, set the **telemetry** property to `false`. + + +[01]: /cli/azure/install-azure-cli +[02]: https://azure.microsoft.com/products/copilot + diff --git a/learndocs-archive/docs-conceptual/AIShell/how-to/agent-openai.md b/learndocs-archive/docs-conceptual/AIShell/how-to/agent-openai.md new file mode 100644 index 00000000..c8ab4a8f --- /dev/null +++ b/learndocs-archive/docs-conceptual/AIShell/how-to/agent-openai.md @@ -0,0 +1,235 @@ +--- +title: OpenAI agent +description: Learn how to configure the OpenAI agent. +ms.date: 01/12/2026 +ms.topic: how-to +ms.collection: ce-skilling-ai-copilot +--- +# OpenAI agent + +[!INCLUDE[aishell-deprecated](../../../includes/aishell-deprecated.md)] + +This agent provides a user-friendly platform for interacting with OpenAI services. The OpenAI agent +can connect to a public OpenAI service, a private deployment of the Azure OpenAI service, or any +other OpenAI-compatible service. We recommend using an Azure OpenAI deployment for enhanced security +and privacy. + +## Prerequisites + +Before you can use the agent, you must configure at least one GPT instance in the agent +configuration file. Collect the following information about your OpenAI implementation: + +- `ModelName` - the name of the AI model to use +- `Key` - the API key used to authenticate requests to the OpenAI service +- `Endpoint` - required for Azure OpenAI and other 3rd-party services +- `Deployment` - the name of your Azure OpenAI deployment + +You also need to give your GPT instance a `Name`, a `Description`, and a `SystemPrompt`. + +- `Name` - identifies the GPT instance in the agent configuration +- `Description` - provides additional context about its purpose and capabilities +- `SystemPrompt` - defines the behavior and personality of the GPT instance + +You can customize these values to fit your needs. + +## Configuration + +GPTs are tailored versions of base OpenAI models. You use a GPT to provide focused responses based +on the system prompt you give the model. By changing the system prompt and model, you can create +multiple GPTs for the same endpoint that are tailored for specific domains or scenarios. + +- Azure OpenAI requires the `Endpoint`, `Deployment`,`ModelName` and `Key` or `AuthType`. +- Public OpenAI only requires the `ModelName` and `Key`. The endpoint is fixed by OpenAI. There is + no deployment name. +- Other OpenAI-compatible services typically require the `Endpoint`, `ModelName`, and `Key`. + +GPTs are configured in the agent's settings file. To open the configuration file using your default +editor, use the `/agent config openai-gpt` command. + +Update the file based on the following example: + +```jsonc +{ + // Declare GPT instances. + "GPTs": [ + // To use the Azure OpenAI service: + // - Set `Endpoint` to the endpoint of your Azure OpenAI service, + // or the endpoint to the Azure API Management service if you are using it as a gateway. + // - Set `Deployment` to the deployment name of your Azure OpenAI service. + // - Set `ModelName` to the name of the model used for your deployment, e.g. "gpt-4-0613". + // - Set `Key` to the access key of your Azure OpenAI service, + // or the key of the Azure API Management service if you are using it as a gateway. + { + "Name": "ps-az-gpt4", + "Description": "A GPT instance with expertise in PowerShell scripting and command line utilities. Use gpt-4 running in Azure.", + "Endpoint": "", + "Deployment": "", + "ModelName": "", // required field to infer properties of the service, such as token limit. + "Key": "", + "SystemPrompt": "1. You are a helpful and friendly assistant with expertise in PowerShell scripting and command line.\n2. Assume user is using the operating system `Windows 11` unless otherwise specified.\n3. Use the `code block` syntax in markdown to encapsulate any part in responses that is code, YAML, JSON or XML, but not table.\n4. When encapsulating command line code, use '```powershell' if it's PowerShell command; use '```sh' if it's non-PowerShell CLI command.\n5. When generating CLI commands, never ever break a command into multiple lines. Instead, always list all parameters and arguments of the command on the same line.\n6. Please keep the response concise but to the point. Do not overexplain." + }, + + // To use the public OpenAI service: + // - Ignore the `Endpoint` and `Deployment` keys. + // - Set `ModelName` to the name of the model to be used. + // - Set `Key` to be the OpenAI access token. + // For example: + { + "Name": "ps-gpt4o", + "Description": "A GPT instance with expertise in PowerShell scripting and command line utilities. Use gpt-4o running in OpenAI.", + "ModelName": "gpt-4o", + "Key": "", + "SystemPrompt": "1. You are a helpful and friendly assistant with expertise in PowerShell scripting and command line.\n2. Assume user is using the operating system `Windows 11` unless otherwise specified.\n3. Use the `code block` syntax in markdown to encapsulate any part in responses that is code, YAML, JSON or XML, but not table.\n4. When encapsulating command line code, use '```powershell' if it's PowerShell command; use '```sh' if it's non-PowerShell CLI command.\n5. When generating CLI commands, never ever break a command into multiple lines. Instead, always list all parameters and arguments of the command on the same line.\n6. Please keep the response concise but to the point. Do not overexplain." + } + ], + + // Specify the default GPT instance to use for user query. + "Active": "ps-az-gpt4" +} +``` + +## `/gpt` Command + +Use the `/gpt` command to list and select the GPT you want to use. + +- Run `/gpt use ` to switch to another GPT instance, or run `/gpt use` to choose from the + available ones. +- Run `/gpt list ` to view the details of a GPT definition, or run `/gpt list` to list all + available GPTs. + +## Support for Microsoft Entra ID authentication + +The OpenAI agent support Entra ID authentication for Azure OpenAI instances. Instead of providing a +key, set the `AuthType` property to `EntraID`. This way, the agent can access your Azure OpenAI +resource without storing keys in the configuration file. + +```json +{ + // Declare GPT instances. + "GPTs": [ + // Declaration of an Azure OpenAI instance with EntraID authentication + { + "Name": "ps-az-entraId", + "Description": "A GPT instance with expertise in PowerShell scripting using Entra ID authentication.", + "Endpoint": "", + "Deployment": "", + "ModelName": "", + "AuthType": "EntraID", + "SystemPrompt": "You are a helpful and friendly assistant with expertise in PowerShell scripting and command line." + } + ], + + // Specify the default GPT instance to use for user query. + "Active": "ps-az-entraId" +} +``` + +Azure OpenAI uses the following hierarchy of credentials for authentication: + +- `EnvironmentCredential` +- `WorkloadIdentityCredential` +- `ManagedIdentityCredential` +- `SharedTokenCacheCredential` +- `VisualStudioCredential` +- `AzureCliCredential` +- `AzurePowerShellCredential` +- `AzureDeveloperCliCredential` +- `InteractiveBrowserCredential` + +For more information about these credentials, see .NET documentation for +[`DefaultAzureCredential`][09]. + +## Support for other OpenAI-compatible models + +The OpenAI agent supports third-party AI services that implement the OpenAI API specifications. Some +of these models are open source tools for running SLMs and LLMs locally. The OpenAI agent supports +the following 3rd-party models: + +- [**Ollama**][08] +- [**LM Studio**][06] +- [**Deepseek**][04] +- [**LocalAI**][07] +- [**Google Gemini**][03] +- [**Grok**][05] +- [**Foundry Local**][02] + +Foundry Local is an on-device AI inference solution from Microsoft, currently in public preview. AI +Shell interfaces with it using the OpenAI agent. You must install and configure Foundry Local on +your machine before you can use it with AI Shell. For more information, see +[Get started with Foundry Local][01]. + +The OpenAI agent supports the following model names: + +- `o1` +- `o3` +- `o4-mini` +- `gpt-5` +- `gpt-4.1` +- `gpt-4o` +- `gpt-4` +- `gpt-4-32k` +- `gpt-4-turbo` +- `gpt-3.5-turbo` +- `gpt-35-turbo` - Azure OpenAI name of the model +- Any of the model IDs supported by Foundry Local + +For more information about endpoints and model names, see the 3rd-party documentation for the AI +service you want to use. + +### Configure a Foundry Local endpoint + +After you have Foundry Local installed, run the following commands to get the information you need +to configure the OpenAI agent: + +```powershell +PS> foundry service start +🟢 Service is already running on http://127.0.0.1:56952/. + +PS> foundry model load phi-3.5-mini +🕔 Loading model... +🟢 Model phi-3.5-mini loaded successfully + +PS> foundry service ps +Models running in service: + Alias Model ID +🟢 phi-3.5-mini Phi-3.5-mini-instruct-generic-cpu +``` + +This example starts the Foundry Local service, loads the `phi-3.5-mini` model, and lists the models +in the running in the service. + +Next, add a new GPT to your `openai.agent.json` file. + +- The `foundry service start` shows the URI for the service. The `Endpoint` for the OpenAI agent is + the URI plus `/v1`. +- The `foundry service ps` command shows `ModelName` as the **Model ID**. Make sure you use the + exact casing as shown in **Model ID**. Foundry Local is case-sensitive. +- The API key is hardcoded to `OPENAI_API_KEY`. + +```json +{ + "GPTs": [ + { + "Name": "foundry-local", + "Description": "A GPT instance using Foundry Local.", + "Endpoint": "http://127.0.0.1:56952/v1", + "ModelName": "Phi-3.5-mini-instruct-generic-cpu", + "Key": "OPENAI_API_KEY" + } + ] + + "Active": "foundry-local" +} +``` + + +[01]: /azure/ai-foundry/foundry-local/get-started +[02]: /azure/ai-foundry/foundry-local/what-is-foundry-local +[03]: https://ai.google.dev/gemini-api/docs/openai +[04]: https://api-docs.deepseek.com/ +[05]: https://docs.x.ai/docs/overview#migrating-from-another-llm-provider +[06]: https://lmstudio.ai/docs/api/openai-api +[07]: https://localai.io/ +[08]: https://ollama.com/blog/openai-compatibility +[09]: xref:Azure.Identity.DefaultAzureCredential + diff --git a/learndocs-archive/docs-conceptual/AIShell/how-to/aishell-reference.md b/learndocs-archive/docs-conceptual/AIShell/how-to/aishell-reference.md new file mode 100644 index 00000000..1339c565 --- /dev/null +++ b/learndocs-archive/docs-conceptual/AIShell/how-to/aishell-reference.md @@ -0,0 +1,433 @@ +--- +title: AI Shell command reference +description: Learn about the command-line options and commands available in AI Shell. +ms.date: 01/12/2026 +ms.topic: reference +ms.collection: ce-skilling-ai-copilot +--- +# AI Shell command reference + +[!INCLUDE[aishell-deprecated](../../../includes/aishell-deprecated.md)] + +## Command-line options + +``` +Description: + AI for the command line. + +Usage: + aish [] [options] + +Arguments: + The query term used to get response from AI. + +Options: + --channel A named pipe used to setup communication + between aish and the command-line shell. + --shell-wrapper Path to the configuration file to wrap + AI Shell as a different application. + --version Show version information + -?, -h, --help Show help and usage information +``` + +## Chat commands + +To query the selected AI model, enter your prompt at the AI Shell prompt. AI Shell sends the prompt +request to the connected AI model. AI Shell also provides a base set of shell commands used to +interact with the AI model. + +To get a list of commands, use the `/help` command in the chat session. The following list contain +the AI Shell commands available to all agents. + +``` + Name Description Source +───────────────────────────────────────────────────────────────────────────────────── + /agent Command for agent management. Core + /clear Clear the screen. Core + /code Command to interact with the code generated. Core + /dislike Dislike the last response and send feedback. Core + /exit Exit the interactive session. Core + /help Show all available commands. Core + /like Like the last response and send feedback. Core + /mcp Command for managing MCP servers and tools. Core + /refresh Start a new chat session. Core + /retry Regenerate a new response for the last query. Core +``` + +AI Shell also provides commands specific to the selected agent. + +``` + Name Description Source +--------------------------------------------------------------------------------------------------- + /gpt Command for GPT management within the 'openai-gpt' agent. openai-gpt + /replace Replace argument placeholders in the generated scripts with the real value. azure +``` + +## General chat commands + +### `/agent` + +Command for agent management. + +Usage: + +``` +/agent [command] [options] +``` + +Options: `-h`, `--help` - Show help and usage information + +Subcommands + +- `config ` - Open up the setting file for an agent. When no agent is specified, + target the active agent. +- `list` - List all available agents. +- `use ` - Specify an agent to use, or choose one from the available agents. + +#### `/agent config` + +Open up the setting file for an agent. When no agent is specified, target the active agent. + +Usage: + +``` +/agent config [] [options] +``` + +Arguments: `` Name of an agent. + +Options: + +- `--editor ` - The editor to open the setting file in. +- `-h`, `--help` - Show help and usage information + +Example: + +``` +/agent config openai-gpt +``` + +#### `/agent list` + +List all available agents. + +Usage: + +``` +/agent list [options] +``` + +Options: + +- `-h`, `--help` Show help and usage information + +Example: + +``` +> /agent list + + Name Description +─────────────────────────────────────────────────────────────────────────────────────────────────── + + openai-gpt Active GPT: . A GPT instance with expertise in PowerShell scripting + using Entra ID authentication. + azure (active) This AI assistant connects you to the Azure Copilot and can generate Azure + CLI and Azure PowerShell commands for managing Azure resources and answer + questions about Azure. +``` + +#### `/agent use` + +Specify an agent to use, or choose one from the available agents. + +Usage: + +``` +/agent use [] [options] +``` + +Arguments: `` - Name of an agent (optional). If you don't provide an agent name, +AI Shell prompts you to choose one from the available agents. + +Options: + +- `-h`, `--help` - Show help and usage information + +### `/clear` + +Clears the screen. You can also use the alias `/cls`. + +### `/code` + +Command to interact with the code generated. + +Usage: + +``` +/code [command] [options] +``` + +Subcommands: + +- `copy ` Copy the n-th (1-based) code snippet to clipboard. Copy all the code when `` isn't + specified. [default: -1] +- `save ` - Save all the code to a file. +- `post ` - Post the n-th (1-based) code snippet to the connected command-line shell. Post all + the code when `` isn't specified. [default: -1] + +Options: + +- `-h`, `--help` - Show help and usage information + +#### `/code copy` + +Copy the n-th (1-based) code snippet to clipboard. Copy all the code when `` isn't specified. + +Usage: + +``` +/code copy [] [options] +``` + +Arguments: + +- `` Use the n-th (1-based) code snippet. Specify the argument as `-1` to use all the code. When + you don't specify the argument, the default value is `-1`. + +Options: + +- `-h`, `--help` - Show help and usage information + +Examples + +![An animation showing how to copy the specific code snippets to the clipboard.][01] + +#### `/code save` + +Save all the code to a file. + +Usage: + +``` +/code save [options] +``` + +Arguments: + +- `` The file path to save the code to. + +Options: + +- `--append` Append to the end of the file. +- `-h`, `--help` Show help and usage information + +Examples: + +The following example copies the all the code to a file. + +![A screenshot showing how to save the code to a file.][03] + +#### `/code post` + +Post the n-th (1-based) code snippet to the connected command-line shell. Post all the code +when `` isn't specified. + +Usage: + +``` +/code post [] [options] +``` + +Arguments: + +- `` Use the n-th (1-based) code snippet. Use all the code when no value is specified. + +Options: + +- `-h, --help` Show help and usage information + +Examples: + +![An animation showing how to post the specific code snippets to the connected command-line shell.][02] + +### `/dislike` + +Dislike the last response and send feedback. + +Usage: + +``` +/dislike [options] +``` + +Options: + +- `-h, --help` Show help and usage information + +### `/exit` + +Exit the interactive session. + +Usage: + +``` +/exit [options] +``` + +Options: + +- `-h, --help` Show help and usage information + +### `/like` + +Like the last response and send feedback. + +Usage: + +``` +/like [options] +``` + +Options: + +- `-h, --help` Show help and usage information + +### `/mcp` + +Command for managing MCP servers and tools. + +Usage: + +``` +/mcp [options] +``` + +Options: + +- `-h, --help` Show help and usage information + +### `/refresh` + +Start a new chat session. + +Usage: + +``` +/refresh [options] +``` + +Options: + +- `-h, --help` Show help and usage information + +### `/retry` + +Regenerate a new response for the last query. + +Usage: + +``` +/retry [options] +``` + +Options: + +- `-h, --help` Show help and usage information + +## Agent-specific chat commands + +### `/gpt` + +Command for GPT management within the 'openai-gpt' agent. + +Usage: + +``` +/gpt [command] [options] +``` + +Options: + +- `-h, --help` Show help and usage information + +Subcommands: + +- `list` - List a specific GPT, or all available GPTs. +- `use` - Specify a GPT to use, or choose one from the available GPTs. + +#### `/gpt list` + +List a specific GPT, or all available GPTs. + +Usage: + +``` +/gpt list [] [options] +``` + +Arguments: `` - The name of a GPT + +Options: + +- `-h`, `--help` - Show help and usage information + +Example + +``` +/gpt list + + Name Active Description +─────────────────────────────────────────────────────────────────────────────────────────────────── + az-entraId-gpt-4o A GPT instance with expertise in PowerShell scripting using + Entra ID authentication. + az-aikey-gpt-4o true A GPT instance with expertise in PowerShell scripting using + Entra ID authentication. +``` + +#### `/gpt use` + +Specify a GPT to use, or choose one from the available GPTs. + +Usage: + +``` +/gpt use [] [options] +``` + +Arguments: `` - The name of a GPT + +Options: + +- `-h`, `--help` - Show help and usage information + +### `/replace` + +Replace argument placeholders in the generated scripts with the real value. This command is only +available for the Azure agent. + +Usage: + +``` +/replace [options] +``` + +Options: + +- `-h`, `--help` - Show help and usage information + +## AI Shell command history + +AI Shell includes a modified version of PSReadLine. Like the PSReadLine module for PowerShell, AI +Shell lets you use the arrow keys to navigate through your command history. AI Shell saves the +history in a file named `AIShell_history.txt`, in the same location as the other PSReadLine history +files: + +- On Windows systems: `$Env:APPDATA\Microsoft\Windows\PowerShell\PSReadLine`. +- On non-Windows systems: `$Env:XDG_DATA_HOME/powershell/PSReadLine` or + `$Env:HOME/.local/share/powershell/PSReadLine`. + + +[01]: media/aishell-reference/code-copy-command.gif +[02]: media/aishell-reference/code-post-command.gif +[03]: media/aishell-reference/code-save-command.png + diff --git a/learndocs-archive/docs-conceptual/AIShell/how-to/mcp-support.md b/learndocs-archive/docs-conceptual/AIShell/how-to/mcp-support.md new file mode 100644 index 00000000..d8d057e5 --- /dev/null +++ b/learndocs-archive/docs-conceptual/AIShell/how-to/mcp-support.md @@ -0,0 +1,165 @@ +--- +title: MCP support +description: Learn how to enable and use MCPs in AIShell. +ms.date: 01/12/2026 +ms.topic: how-to +ms.collection: ce-skilling-ai-copilot +--- +# MCP support + +[!INCLUDE[aishell-deprecated](../../../includes/aishell-deprecated.md)] + +Model Context Protocol (MCP) is an open protocol that standardizes how applications provide context +to large language models (LLMs). Starting in AI Shell 1.0.0-preview.6, AI Shell can act as an MCP +Host and client to MCP servers. The key participants in the MCP architecture are: + +- MCP Host - AI Shell coordinates and manages one or multiple MCP clients +- MCP Client - The client component of AI Shell maintains a connection to an MCP server and obtains + context from an MCP server for the MCP host to use +- MCP Server - A program, running locally or hosted remotely, that provides context to MCP clients + +For more information about MCP, see the [Architecture Overview][06] in the official Model Context +Protocol documentation. + +MCP tools enable AI agents to access external tools and services to enhance their capabilities and +provide more accurate responses. MCPs can integrate with various APIs, databases, and other +resources, allowing agents to retrieve real-time information and perform complex tasks. + +## Built-in tools for AI Shell + +AI Shell comes with a set of MCP-like built-in tools that are available to all agents. These +commands are similar to MCP Server tools, but are exclusive to the AI Shell experience. The tools +enhance the AI Shell experience by providing context-aware capabilities and automation features. +You can use them in conjunction with other MCP servers to create a powerful AI-driven shell +environment. + +The following list contains the built-in tools and their usage: + +- `get_working_directory` - Get the current working directory of the connected PowerShell session, + including the provider name (e.g., `FileSystem`, `Certificate`) and the path (e.g., `C:\\`, + `cert:\\`). +- `get_command_history` - Get up to 5 of the most recent commands executed in the connected + PowerShell session. +- `get_terminal_content` - Get all output currently displayed in the terminal window of the + connected PowerShell session. +- `get_environment_variables` - Get environment variables and their values from the connected + PowerShell session. Values of potentially sensitive variables are redacted. +- `copy_text_to_clipboard` - Copy the provided text or code to the system clipboard, making it + available for pasting elsewhere. +- `post_code_to_terminal` - Insert code into the prompt of the connected PowerShell session without + executing it. The user can review and choose to run it manually by pressing Enter. +- `run_command_in_terminal` - This tool allows you to execute shell commands in a persistent + PowerShell session, preserving environment variables, working directory, and other context across + multiple commands. +- `get_command_output` - Get the output of a command previously started with + `run_command_in_terminal`. + +> [!NOTE] +> The built-in tools rely on the side-car experience with a connected PowerShell session and provide +> enhanced context awareness and automation capabilities. + +## Demos + +Here is a simple demo showing how you can have AI Shell run commands on your behalf using the +`run_command_in_terminal` tool: + +![Have the MCP run a command in terminal for you.][09] + +This example shows how additional context is provided to AI Shell to improve results: + +![Getting more context with built-in tools.][07] + +You can also use the `get_terminal_content` tool to get the content from the connected terminal and +provide it to AI Shell to help it understand what you are trying to do: + +![Getting content from the terminal for output created before AI Shell started.][08] + +## Find and configure MCP servers + +An MCP server is an application that runs locally or is hosted remotely and accessed through an +endpoint URL. Many MCP servers are open source and available for free. Local MCP server apps are +typically built using Node.js and can installed using `npm`. You can find a list of available MCP +servers at [Awesome MCP Servers][03]. + +Before you can use an MCP server (Local or remote) you must add it to the `mcp.json` configuration +file. In some cases, you might not need to install the local MCP before using it. However, the MCP +server will be installed the first time you start AI Shell. This can take several minutes. For the +best experience, preinstall the MCP server. Consult the documentation for your specific MCP server +for installation instructions. Remote MCP servers don't need to be installed. You just need to add +them to the `mcp.json` file. + +### Install a local MCP server + +The following example installs the `@modelcontextprotocol/server-everything` and +`@modelcontextprotocol/server-filesystem` MCP servers. These servers are published as node +packages. You must have `Node.js` installed to use these MCP servers. + +To install the MCP servers, you can use the following commands: + +```powershell +npm install -g @modelcontextprotocol/server-everything +npm install -g @modelcontextprotocol/server-filesystem +``` + +For more information about their command and capabilities, see the following documentation: + +- [Everything MCP Server][04] +- [Filesystem MCP Server][05] + +### Add MCP Servers + +To add an MCP server, create an `mcp.json` file in `$HOME\.aish\` folder. The following example +shows two local MCP servers, `everything` and `filesystem`, and two remote MCP server. You can add +as many MCP servers as you want. + +```json +{ + "servers": { + "everything": { + "type": "stdio", + "command": "npx", + "args": [ + "-y", + "@modelcontextprotocol/server-everything" + ] + }, + "filesystem": { + "type": "stdio", + "command": "npx", + "args": [ + "-y", + "@modelcontextprotocol/server-filesystem", + "C:/Users/username/" + ] + }, + "github": { + "type": "http", + "url": "https://api.githubcopilot.com/mcp/", + "headers": { + "Authorization": "Bearer " + } + }, + "microsoft.docs.mcp": { + "type": "http", + "url": "https://learn.microsoft.com/api/mcp" + } + } +} +``` + +For more information about the remote MCP server from Microsoft, see: + +- [GitHub's official MCP Server][02] +- [Microsoft Learn MCP Server][01] + + +[01]: /training/support/mcp +[02]: https://github.com/github/github-mcp-server +[03]: https://mcpservers.org/ +[04]: https://mcpservers.org/servers/modelcontextprotocol/everything +[05]: https://mcpservers.org/servers/modelcontextprotocol/filesystem +[06]: https://modelcontextprotocol.io/docs/learn/architecture +[07]: media/mcp-support/openai-agent-context.gif +[08]: media/mcp-support/openai-agent-get.gif +[09]: media/mcp-support/openai-agent-run.gif + diff --git a/learndocs-archive/docs-conceptual/AIShell/how-to/media/aishell-reference/code-copy-command.gif b/learndocs-archive/docs-conceptual/AIShell/how-to/media/aishell-reference/code-copy-command.gif new file mode 100644 index 00000000..36c6eeea Binary files /dev/null and b/learndocs-archive/docs-conceptual/AIShell/how-to/media/aishell-reference/code-copy-command.gif differ diff --git a/learndocs-archive/docs-conceptual/AIShell/how-to/media/aishell-reference/code-post-command.gif b/learndocs-archive/docs-conceptual/AIShell/how-to/media/aishell-reference/code-post-command.gif new file mode 100644 index 00000000..ba6e221c Binary files /dev/null and b/learndocs-archive/docs-conceptual/AIShell/how-to/media/aishell-reference/code-post-command.gif differ diff --git a/learndocs-archive/docs-conceptual/AIShell/how-to/media/aishell-reference/code-save-command.png b/learndocs-archive/docs-conceptual/AIShell/how-to/media/aishell-reference/code-save-command.png new file mode 100644 index 00000000..e473a5c6 Binary files /dev/null and b/learndocs-archive/docs-conceptual/AIShell/how-to/media/aishell-reference/code-save-command.png differ diff --git a/learndocs-archive/docs-conceptual/AIShell/how-to/media/mcp-support/openai-agent-context.gif b/learndocs-archive/docs-conceptual/AIShell/how-to/media/mcp-support/openai-agent-context.gif new file mode 100644 index 00000000..aaadd8a8 Binary files /dev/null and b/learndocs-archive/docs-conceptual/AIShell/how-to/media/mcp-support/openai-agent-context.gif differ diff --git a/learndocs-archive/docs-conceptual/AIShell/how-to/media/mcp-support/openai-agent-get.gif b/learndocs-archive/docs-conceptual/AIShell/how-to/media/mcp-support/openai-agent-get.gif new file mode 100644 index 00000000..80e62a9c Binary files /dev/null and b/learndocs-archive/docs-conceptual/AIShell/how-to/media/mcp-support/openai-agent-get.gif differ diff --git a/learndocs-archive/docs-conceptual/AIShell/how-to/media/mcp-support/openai-agent-run.gif b/learndocs-archive/docs-conceptual/AIShell/how-to/media/mcp-support/openai-agent-run.gif new file mode 100644 index 00000000..e59d9030 Binary files /dev/null and b/learndocs-archive/docs-conceptual/AIShell/how-to/media/mcp-support/openai-agent-run.gif differ diff --git a/learndocs-archive/docs-conceptual/AIShell/install-aishell.md b/learndocs-archive/docs-conceptual/AIShell/install-aishell.md new file mode 100644 index 00000000..5ee70496 --- /dev/null +++ b/learndocs-archive/docs-conceptual/AIShell/install-aishell.md @@ -0,0 +1,131 @@ +--- +title: Install AI Shell +description: Learn how to install AI Shell on your system. +ms.date: 01/12/2026 +ms.topic: install-set-up-deploy +ms.collection: ce-skilling-ai-copilot +--- +# Install AI Shell + +[!INCLUDE[aishell-deprecated](../../includes/aishell-deprecated.md)] + +AI Shell is an interactive shell that provides a chat interface for AI language models. For the best +experience, install the following packages: + +- The command-line shell (`aish`) interface +- The **AIShell** module for PowerShell + +This article explains how to install these packages on your system. + +## System requirements + +AI Shell is supported on the following platforms: + + +### [Windows](#tab/windows) + +- Windows 10 or higher +- PowerShell 7.4.6 or higher +- Windows Terminal +- PSReadLine v2.4.2-beta2 or higher + +### [macOS](#tab/macos) + +- macOS v13 Ventura or higher +- PowerShell 7.4.6 or higher +- Default macOS Terminal app for the standalone experience +- iTerm2 required to use the sidecar experience + - Python 3.11 or higher required to support iTerm2 + - Must enable **Python APIs** in the iTerm2 settings +- PSReadLine v2.4.2-beta2 or higher + +### [Linux](#tab/linux) + +- Ubuntu 20.04 or higher +- PowerShell 7.4.6 or higher +- PSReadLine v2.4.2-beta2 or higher +- Any terminal emulator supported by the OS (no sidecar experience) + + > [!NOTE] + > The AI Shell module isn't supported on Linux. + + + +--- + +## Install AI Shell + +For convenience, you can use `installaishell.ps1` script to install AI Shell. + +On Windows, this script: + +- Installs `aish.exe` to `$env:LOCALAPPDATA\Programs\AIShell` and adds it to your PATH +- Installs the **AIShell** module to your module path location + +On macOS, this script: + +- Installs the `aish` executable to `/usr/local/AIShell` and creates a symbolic link to + `/usr/local/bin/aish`. + +> [!NOTE] +> This script only works on Windows and Mac systems. Linux users need to follow the manual +> installation instructions. + +```powershell +Invoke-Expression "& { $(Invoke-RestMethod 'https://aka.ms/install-aishell.ps1') }" +``` + +To uninstall AI Shell, invoke the same expression with the `-Uninstall` parameter. + +```powershell +Invoke-Expression "& { $(Invoke-RestMethod 'https://aka.ms/install-aishell.ps1') } -Uninstall" +``` + +To manually install AI Shell, follow the instructions for your platform: + + +### [Windows](#tab/windows) + +1. Download the latest version from the [GitHub releases page][03]. Choose the file that matches + your system architecture. For example, `AIShell-1.0.0-preview.2-win-x64.zip`. +1. Extract the contents of the ZIP file to a location on your system. +1. Add the extracted folder to your **PATH** environment variable. +1. Install the AI Shell module from the PowerShell Gallery. + + ```powershell + Install-PSResource -Name AIShell -Preview + ``` + +### [macOS](#tab/macos) + +1. Download the latest version from the [GitHub releases page][03]. Choose the file that matches + your system architecture. For example, `AIShell-1.0.0-preview.2-osx-x64.tar.gz`. +1. Extract the contents of the TAR file to a location on your system. +1. Add the extracted folder to your **PATH** environment variable. +1. Install the AI Shell module from the PowerShell Gallery. + + ```powershell + Install-PSResource -Name AIShell -Preview + ``` + +### [Linux](#tab/linux) + +1. Download the latest version from the [GitHub releases page][03]. Choose the file that matches + your system architecture. For example, `AIShell-1.0.0-preview.2-linux-x64.tar.gz`. +1. Extract the contents of the TAR file to a location on your system. +1. Add the extracted folder to your **PATH** environment variable. + + + +--- + +## Next steps + +- [Get started with AI Shell][02] +- [Get started with AI Shell for PowerShell][01] + + +[01]: get-started/aishell-powershell.md +[02]: get-started/aishell-standalone.md +[03]: https://github.com/PowerShell/AIShell/releases/latest + diff --git a/learndocs-archive/docs-conceptual/AIShell/overview.md b/learndocs-archive/docs-conceptual/AIShell/overview.md new file mode 100644 index 00000000..1d4ef1cb --- /dev/null +++ b/learndocs-archive/docs-conceptual/AIShell/overview.md @@ -0,0 +1,60 @@ +--- +title: What is AI Shell? +description: Learn about AI Shell, an interactive shell that provides a chat interface with language models. +ms.date: 01/30/2026 +ms.topic: overview +ms.collection: ce-skilling-ai-copilot +--- +# What is AI Shell? + +[!INCLUDE[aishell-deprecated](../../includes/aishell-deprecated.md)] + +AI Shell is an interactive shell that provides a chat interface with language models. The shell +provides agents that connect to different AI models and other assistance providers. Users can +interact with the agents in a conversational manner. + +The AI Shell project includes: + +- A command-line shell interface (`aish`) +- A framework for creating AI agents and other assistance providers +- Integration with Windows Terminal and iTerm2 on macOS +- A PowerShell module for integration with PowerShell. For more information, see the + [AI Shell module][02]. +- Support for MCP servers and tools +- Support for [Foundry Local][01] deployments + +Each AI assistant is known as an agent. The initial release of AI Shell includes two agents: + +- **Azure OpenAI** agent that connects to an instance of **gpt-4o**. Use this agent for general + AI tasks. +- **Azure Copilot** agent that can assist with Microsoft Azure knowledge. Use the Azure agent for + assistance with Azure CLI and Azure PowerShell commands. + +You can run the AI Shell executable (`aish.exe`) in a standalone experience or you can use the +**AIShell** PowerShell module with PowerShell 7 to create a split-pane (sidecar) experience with +Windows Terminal. The sidecar experience is the recommended way to use AI Shell because you get +deeper integration with the shell. These features include: + +- The ability to insert code from the AI Shell response directly into the connect command shell +- Multi-step commands are added to the Predictive IntelliSense buffer for quick acceptance +- Simple, single-command error recovery +- MCP integration + +## Known issues + +This current release of AI Shell has some known issues that we're actively working on addressing: + +- The sidecar experience only works with Windows Terminal and iTerm2 for macOS. +- AI Shell isn't supported on Linux. You might get it to work but it doesn't support the split + terminal integration that you get with Windows Terminal and iTerm2. AI Shell isn't tested on any + Linux distribution. +- If you have preview (developer) and stable versions of Windows Terminal installed, the + `Start-AIShell` command opens a new terminal running the stable version of Windows Terminal. +- If you started Window Terminal as an administrator, the `Start-AIShell` command opens a new + terminal window running Windows Terminal without elevation. +- If you're using the default terminal app in macOS, you don't get the sidecar experience and the + colors might not render correctly. It might be difficult to read the generated code. + + +[01]: /azure/ai-foundry/foundry-local/what-is-foundry-local +[02]: /powershell/module/aishell/ diff --git a/learndocs-archive/docs-conceptual/AIShell/release-notes.md b/learndocs-archive/docs-conceptual/AIShell/release-notes.md new file mode 100644 index 00000000..1012ef3d --- /dev/null +++ b/learndocs-archive/docs-conceptual/AIShell/release-notes.md @@ -0,0 +1,128 @@ +--- +title: AI Shell release notes +description: > + Find out what's new in the latest release of AI Shell, an interactive shell that provides a chat interface with language models. +ms.date: 01/12/2026 +ms.topic: overview +ms.collection: ce-skilling-ai-copilot +--- +# AI Shell Release Notes + +[!INCLUDE[aishell-deprecated](../../includes/aishell-deprecated.md)] + +This document outlines the changes and improvements made in each release of AI Shell. For a more +complete list of changes, refer to the [Releases page][06] on GitHub. + +## 1.0.0-preview.7 - 2025-09-05 + +This release includes the following changes: + +- Move to Azure.Identity v1.14.2 and refactor the telemetry library (#404) +- Use login shell on macOS to start `aish` in sidecar pane to inherit proper PATH (#403) +- Properly escape tool description to avoid malformed Markup object (#408) +- Add gpt-5 models to the supported model list (#409) +- Update the history file name and exclude the environment and managed-identity credentials from + Azure authentication flow (#412) +- Keep the original casing of model name for custom endpoint to enable Foundry Local (#413) + +## [1.0.0-preview.6][02] - 2025-07-24 + + + +This release includes the following changes: + +- Update AppInsights connection string to use the new prod environment (#390) +- Make AIShell an MCP client to expose MCP tools to its agents (#392) +- Add built-in tools to AIShell (#394) +- Fix a null-reference exception bug when built-in tools are not available (#396) +- Improve `Resolve-Error` command and allow default system prompt for the `openai-gpt` agent (#397) +- Add the built-in tool `run_command_in_terminal` for AI to execute commands in the connected + PowerShell session (#398) - This tool is currently only enabled on Windows. + +## [1.0.0-preview.5][08] - 2025-06-13 + +This release is a security patch only, including the following changes: + +- Upgrade to .NET SDK 8.0.411 to address the .NET security issue [CVE-2025-30399][362]: .NET Remote + Code Vulnerability +- `OpenAI` agent: update `DefaultAzureCredential` to allow `InteractiveBrowserCredential` + (#383) + +## [1.0.0-preview.4][04] - 2025-05-15 + +This release includes the following changes: + +- Support posting code from the sidecar AIShell to PowerShell with `Invoke-AIShell -PostCode` (#361) +- Improve the reliability of `Start-AIShell` on macOS (#362) +- Publish NuGet package and PowerShell module in deploy box release (#365) +- Fix code posting on macOS: support posting code by both running `/code post` from the sidecar + AIShell and running `Invoke-AIShell -PostCode` from PowerShell (#366) +- Update model information to support the new OpenAI models (#368) +- Add `/clear` as an alias to the command `/cls` to clear console in AIShell (#370) +- Ignore the current active agent from the agent completion results for the `@` operator (#372) +- Update installation script to install the AIShell module on macOS too (#374) +- Enhanced model management and system prompt integration in OllamaAgent (#351) +- Adding the Phi Silica agent for "Copilot+PC" devices (#373) +- Use deploy box and `GitHubRelease` task to create the GitHub draft release (#379) +- Make sure the `Runspace` is available when importing the `AIShell` module and throw otherwise + (#379) + +## [1.0.0-preview.3][07] - 2025-03-12 + +This release includes the following changes: + +- Update flight flags and make corresponding changes to the `azure` agent (#349, #355) +- Update the regex for matching single-quote and double-quote strings for `PowerShell` and `Bash` + syntax (#357) +- Add support for Entra ID authentication when using the `interpreter` or `openai-gpt` agents (#356) +- Update `install-aishell.ps1` to allow a user to specify the version to install (#345) + +## [1.0.0-preview.2][01] - 2025-02-26 + +This release includes the following changes: + +- Check and remove execute permission from the config file (#317) +- Use `nano` or `$EDITOR` (if defined) to open the config file on Linux (#318) +- Refactor the `openai-gpt` agent to move to `Azure.AI.OpenAI` v2.1.0 (#328) +- Add support to Azure PowerShell login credential (#329) +- Allow using 3rd party AI services that are compatible with OpenAI API format in the `openai-gpt` + agent (#331) +- Check for update before return the description for `openai-gpt` agent (#332) +- Use `#7a7a7a` as the grey color in AIShell to meet the contrast requirement (#333) +- Remove the fallback logic for authorization check and stick to the production URL (#334) +- Capture native command output using screen scraping API on Windows (#335) +- Add `shell` as an alias to the `Bash` parser (#336) +- Enable `pluginstore` and update the topic name for CLI handler (#337) +- Log the response text if exception is thrown while processing a user query (#338) +- Enable parameter injection for Azure PowerShell response (#339) +- Fix build to preserve file permission for Linux and macOS packages (#344) +- Fix AzCLI command parsing to handle long/short flags and when no parameter is present (#344) +- Implement conversation context and streaming for the `Ollama` agent with `OllamaSharp` (#310) +- Adding docs and files for deploying an Azure OpenAI instance via Bicep file (#324) +- Modify readme and agent to point to docs (#326) + +## [1.0.0-preview.1][03] - 2024-11-15 + +AI Shell is a new CLI tool that creates an interactive shell to connect you with different +artificial intelligence assistants. We refer to these different AI assistants as AI agents; AI Shell +includes two agents by default: + +- Azure Copilot +- Azure OpenAI + +### Key features + +- Interactive chat to talk to AI agents +- Rendering of markdown responses +- Chat `/` commands to interact with the code responses from the AI agent of choice + + +[01]: https://devblogs.microsoft.com/powershell/ai-shell-preview-2/ +[02]: https://devblogs.microsoft.com/powershell/preview-6-ai-shell/ +[03]: https://devblogs.microsoft.com/powershell/announcing-the-public-preview-of-ai-shell/ +[04]: https://devblogs.microsoft.com/powershell/preview-4-ai-shell/ +[06]: https://github.com/PowerShell/AIShell/releases +[07]: https://github.com/PowerShell/AIShell/releases/tag/v1.0.0-preview.3 +[08]: https://github.com/PowerShell/AIShell/releases/tag/v1.0.0-preview.5 +[362]: https://github.com/dotnet/announcements/issues/362 + diff --git a/learndocs-archive/docs-conceptual/AIShell/toc.yml b/learndocs-archive/docs-conceptual/AIShell/toc.yml new file mode 100644 index 00000000..d607f0b1 --- /dev/null +++ b/learndocs-archive/docs-conceptual/AIShell/toc.yml @@ -0,0 +1,35 @@ +items: + - name: What is AI Shell? + href: overview.md + - name: Install AI Shell + href: install-aishell.md + - name: Release notes + href: release-notes.md + - name: What is a command shell? + href: concepts/what-is-a-command-shell.md + - name: Get started + items: + - name: Get started with AI Shell in PowerShell + href: get-started/aishell-powershell.md + - name: Get started with AI Shell (standalone) + href: get-started/aishell-standalone.md + - name: AI Shell command reference + href: how-to/aishell-reference.md + - name: AI Shell agents + items: + - name: Azure agent + href: how-to/agent-azure.md + - name: OpenAI agent + href: how-to/agent-openai.md + - name: MCP support + href: how-to/mcp-support.md + - name: Developer guide + items: + - name: Architecture of AI Shell + href: developer/agent-architecture.md + - name: How to create an agent for Ollama + href: developer/create-ollama-agent.md + - name: Ollama agent README + href: developer/ollama-agent-readme.md + - name: Deploy the Azure OpenAI Service using Bicep + href: developer/deploy-azure-openai.md diff --git a/learndocs-archive/ps-modules/AIShell/AIShell.md b/learndocs-archive/ps-modules/AIShell/AIShell.md new file mode 100644 index 00000000..adeb6523 --- /dev/null +++ b/learndocs-archive/ps-modules/AIShell/AIShell.md @@ -0,0 +1,39 @@ +--- +Download Help Link: https://aka.ms/aishell-help +Help Version: 1.0.0 +Locale: en-US +Module Guid: ecb8bee0-59b9-4dae-9d7b-a990b480279a +Module Name: AIShell +ms.date: 01/12/2026 +ms.custom: 1.0.0-preview.6 +title: AIShell Module +ms.collection: ce-skilling-ai-copilot +--- +# AIShell Module + +## Description + +[!INCLUDE[aishell-deprecated](../../includes/aishell-deprecated.md)] + +The AIShell module integrates PowerShell with AIShell. This integration enables the sharing queries, +errors, and results between PowerShell and AIShell. + +## AIShell Cmdlets + +### [Invoke-AICommand](Invoke-AICommand.md) + +Used by an MCP in AI Shell to invoke a command in the connected PowerShell session. + +### [Invoke-AIShell](Invoke-AIShell.md) + +Sends a query to the connected AIShell window. Results are shown in the AIShell window. + +### [Resolve-Error](Resolve-Error.md) + +Sends the last error in the current session for resolution in the connected AIShell window. + +### [Start-AIShell](Start-AIShell.md) + +Starts an AIShell session in a split pane window of Windows Terminal and iTerm2 and connects a +communication channel to the PowerShell session that started it. + diff --git a/learndocs-archive/ps-modules/AIShell/Invoke-AICommand.md b/learndocs-archive/ps-modules/AIShell/Invoke-AICommand.md new file mode 100644 index 00000000..713a1078 --- /dev/null +++ b/learndocs-archive/ps-modules/AIShell/Invoke-AICommand.md @@ -0,0 +1,68 @@ +--- +external help file: AIShell.Integration.dll-Help.xml +Module Name: AIShell +ms.custom: 1.0.0-preview.6 +ms.date: 01/12/2026 +online version: https://learn.microsoft.com/en-us/powershell/module/aishell/invoke-aicommand?view=ps-modules&wt.mc_id=ps-gethelp +schema: 2.0.0 +ms.collection: ce-skilling-ai-copilot +--- +# Invoke-AICommand + +## SYNOPSIS + +Used by an MCP in AI Shell to invoke a command in the connected PowerShell session. + +## SYNTAX + +``` +Invoke-AICommand [-Command] [] +``` + +## DESCRIPTION + +[!INCLUDE[aishell-deprecated](../../includes/aishell-deprecated.md)] + +MCPs in AI Shell use this cmdlet to invoke a command in the connected PowerShell session. This +command is not intended for users to directly invoke. When an AI model creates a result containing +commands, the MCP can use this cmdlet to execute the commands in the connected PowerShell session. + +## EXAMPLES + +## PARAMETERS + +### -Command + +The scriptblock to be executed. + +```yaml +Type: System.Management.Automation.ScriptBlock +Parameter Sets: (All) +Aliases: + +Required: True +Position: 0 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### CommonParameters + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, +-WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). + +## INPUTS + +### None + +## OUTPUTS + +### System.Object + +## NOTES + +## RELATED LINKS + diff --git a/learndocs-archive/ps-modules/AIShell/Invoke-AIShell.md b/learndocs-archive/ps-modules/AIShell/Invoke-AIShell.md new file mode 100644 index 00000000..5c566e3c --- /dev/null +++ b/learndocs-archive/ps-modules/AIShell/Invoke-AIShell.md @@ -0,0 +1,210 @@ +--- +external help file: AIShell.Integration.dll-Help.xml +Module Name: AIShell +online version: https://learn.microsoft.com/en-us/powershell/module/aishell/invoke-aishell?view=ps-modules&wt.mc_id=ps-gethelp +ms.date: 01/12/2026 +ms.custom: 1.0.0-preview.6 +schema: 2.0.0 +ms.collection: ce-skilling-ai-copilot +--- +# Invoke-AIShell + +## SYNOPSIS +Sends a query to the connected AIShell window. Results are shown in the AIShell window. + +## SYNTAX + +### Default (Default) + +``` +Invoke-AIShell -Query [-Agent ] [-Context ] [] +``` + +### Clipboard + +``` +Invoke-AIShell -Query [-Agent ] [-ContextFromClipboard] [] +``` + +### PostCode + +``` +Invoke-AIShell [-PostCode] [] +``` + +### CopyCode + +``` +Invoke-AIShell [-CopyCode] [] +``` + +### Exit + +``` +Invoke-AIShell [-Exit] [] +``` + +## DESCRIPTION + +[!INCLUDE[aishell-deprecated](../../includes/aishell-deprecated.md)] + +This cmdlet sends a query to the open AIShell agent and results are shown in the AIShell window. + +## EXAMPLES + +### Example 1 - Send a query to the AIShell agent + +```powershell +Start-AIShell +Invoke-AIShell -Query "How do I list out the 5 most CPU intensive processes?" +``` + +This example sends a query, "How do I list out the 5 most CPU intensive processes?" to the AIShell +agent. Responses are given in the AIShell window. + +## PARAMETERS + +### -Agent + +Specifies the agent to use in the current AIShell session. If not specified, AIShell uses the +currently selected agent. + +```yaml +Type: System.String +Parameter Sets: Default, Clipboard +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Context + +Additional context information you want to send to the AIShell agent. + +```yaml +Type: System.Management.Automation.PSObject +Parameter Sets: Default +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: True (ByValue) +Accept wildcard characters: False +``` + +### -ContextFromClipboard + +Use the content in your clipboard as context information for the AIShell agent. + +```yaml +Type: System.Management.Automation.SwitchParameter +Parameter Sets: Clipboard +Aliases: + +Required: True +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -CopyCode + +Invokes `/code copy` command in the AIShell sidecar session. This command copies the code in the +AIShell sidecar session to the clipboard. + +```yaml +Type: System.Management.Automation.SwitchParameter +Parameter Sets: CopyCode +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Exit + +Invokes `/exit` command in the AIShell sidecar session. This command closes the AIShell +sidecar session. + +```yaml +Type: System.Management.Automation.SwitchParameter +Parameter Sets: Exit +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -PostCode + +Invokes `/code post` command in the AIShell sidecar session. This command posts the code in the +AIShell sidecar session to your PowerShell session. + +```yaml +Type: System.Management.Automation.SwitchParameter +Parameter Sets: PostCode +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Query + +The user input to send to the AIShell agent. + +```yaml +Type: System.String[] +Parameter Sets: Default, Clipboard +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### CommonParameters + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, +-WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). + +## INPUTS + +### System.Management.Automation.PSObject + +## OUTPUTS + +### System.Object + +## NOTES + +PowerShell includes the following alias for this cmdlet: + +- All platforms: + - `askai` + +## RELATED LINKS + +[Start-AIShell](Start-AIShell.md) + +[Resolve-Error](Resolve-Error.md) + diff --git a/learndocs-archive/ps-modules/AIShell/Resolve-Error.md b/learndocs-archive/ps-modules/AIShell/Resolve-Error.md new file mode 100644 index 00000000..66d1e1f2 --- /dev/null +++ b/learndocs-archive/ps-modules/AIShell/Resolve-Error.md @@ -0,0 +1,109 @@ +--- +external help file: AIShell.Integration.dll-Help.xml +Module Name: AIShell +online version: https://learn.microsoft.com/en-us/powershell/module/aishell/resolve-error?view=ps-modules&wt.mc_id=ps-gethelp +ms.date: 01/12/2026 +ms.custom: 1.0.0-preview.6 +schema: 2.0.0 +ms.collection: ce-skilling-ai-copilot +--- +# Resolve-Error + +## SYNOPSIS +Sends the last error in the current session for resolution in the connected AIShell window. + +## SYNTAX + +``` +Resolve-Error [-Agent ] [-IncludeOutputFromClipboard] [] +``` + +## DESCRIPTION + +[!INCLUDE[aishell-deprecated](../../includes/aishell-deprecated.md)] + +When an error occurs in the current session, this cmdlet sends the error to the AIShell agent for +resolution. The command sends the full error object to the current AIShell agent session, which +attempts to provide a resolution. + +Beginning with theAI Shell v1.0.0-preview.2 release, the `Resolve-Error` cmdlet also works with +error messages output from native commands. + +## EXAMPLES + +### Example 1 - Resolves the last error + +```powershell +PS> Start-AIShell +#User receives an error + +PS> Resolve-Error +``` + +This example shows how to ask AIShell to resolve the last error that occurred in the current AIShell +session. AIShell analyzes the error and attempts to provide a solution in the AIShell agent window. + +## PARAMETERS + +### -Agent + +Specifies the agent to use in the current AIShell session. If not specified, AIShell uses the +currently selected agent. + +```yaml +Type: System.String +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -IncludeOutputFromClipboard + +When this parameter is specified, the output copied to the clipboard is included in the error sent +to AIShell. + +```yaml +Type: System.Management.Automation.SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### CommonParameters + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, +-WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). + +## INPUTS + +### None + +## OUTPUTS + +### System.Object + +## NOTES + +PowerShell includes the following alias for this cmdlet: + +- All platforms: + - `fixit` + +## RELATED LINKS + +[Invoke-AIShell](Invoke-AIShell.md) + +[Start-AIShell](Start-AIShell.md) + diff --git a/learndocs-archive/ps-modules/AIShell/Start-AIShell.md b/learndocs-archive/ps-modules/AIShell/Start-AIShell.md new file mode 100644 index 00000000..4d29f530 --- /dev/null +++ b/learndocs-archive/ps-modules/AIShell/Start-AIShell.md @@ -0,0 +1,95 @@ +--- +external help file: AIShell.Integration.dll-Help.xml +Module Name: AIShell +online version: https://learn.microsoft.com/en-us/powershell/module/aishell/start-aishell?view=ps-modules&wt.mc_id=ps-gethelp +ms.date: 01/12/2026 +ms.custom: 1.0.0-preview.6 +schema: 2.0.0 +ms.collection: ce-skilling-ai-copilot +--- +# Start-AIShell + +## SYNOPSIS +Starts an AIShell session in a split pane window of Windows Terminal and iTerm2 and connects a +communication channel to the PowerShell session that started it. + +## SYNTAX + +``` +Start-AIShell [-Path ] [] +``` + +## DESCRIPTION + +[!INCLUDE[aishell-deprecated](../../includes/aishell-deprecated.md)] + +Starts an AIShell session in a split pane window of Windows Terminal and iTerm2. The AIShell session +is started in the right pane of the terminal window. The left pane is the current shell session. You +must use these windows to interact with the AIShell session. + +When you run this cmdlet on macOS, it checks for the presence of iTerm2. If iTerm2 is not installed, +it attempts to install iTerm2 using the pip3 package manager. If iTerm2 is installed, it starts an +iTerm2 session in a split pane window. + +## EXAMPLES + +### Example 1 - Start an AIShell session + +```powershell +Start-AIShell +``` + +### Example 2 - Start an AIShell session with a specific path + +```powershell +Start-AIShell -PATH C:\Users\aish.exe +``` + +## PARAMETERS + +### -Path + +By default, the cmdlet looks for the `aish` executable in the locations listed in the `$env:PATH` +environment variable. Use this parameter to specify an alternate location for the `aish` +executable. + +```yaml +Type: System.String +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### CommonParameters + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, +-WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). + +## INPUTS + +### None + +## OUTPUTS + +### System.Object + +## NOTES + +PowerShell includes the following alias for this cmdlet: + +- All platforms: + - `aish` + +## RELATED LINKS + +[Invoke-AIShell](Invoke-AIShell.md) + +[Resolve-Error](Resolve-Error.md) +