diff --git a/reference/docs-conceptual/AIShell/developer/create-ollama-agent.md b/reference/docs-conceptual/AIShell/developer/create-ollama-agent.md index 10b6d06..9f93c79 100644 --- a/reference/docs-conceptual/AIShell/developer/create-ollama-agent.md +++ b/reference/docs-conceptual/AIShell/developer/create-ollama-agent.md @@ -1,7 +1,7 @@ --- 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: 12/12/2024 +ms.date: 05/16/2025 ms.topic: how-to --- @@ -15,6 +15,11 @@ get the desired output or assistance. Agents are implemented as C# classes that 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 @@ -22,14 +27,12 @@ For details about the `AIShell.Abstraction` layer and `AIShell.Kernel`, see the ## Steps to create an agent -For this example we create an agent to communicate with the language model `phi3` by utilizing -[Ollama][01], a CLI tool for managing and using locally built LLM/SLMs. The complete source code of -the agent can be found in the [`shell/agents/AIShell.Ollama.Agent`][04] folder of the repository. -the repository. +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. +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: @@ -94,8 +97,7 @@ public sealed class OllamaAgent : ILLMAgent 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. You will implement the **OllamaChatService** class in a later -step. +of the **OllamaChatService** class, which you implement in a later step. ```csharp public sealed class OllamaAgent : ILLMAgent @@ -204,8 +206,8 @@ public sealed class OllamaAgent : ILLMAgent } ``` -For the initial implementation, the agent to returns "Hello World!" to prove that you created the -correct interfaces. You will also add a `try-catch` block to catch and handle any exceptions when +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. @@ -267,7 +269,7 @@ Before you can use the Ollama API, you need to create classes that send input to responses from the Ollama API. The following [Ollama example][02] shows the format of the input and the response from the agent. -For this example we call the Ollama API with streaming disabled. Ollama generates a single, fixed +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. @@ -465,7 +467,7 @@ This command builds all necessary packages in the `\bin\Debug\net8.0` folder of 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. -There are two location where you can install agents: +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 @@ -488,10 +490,11 @@ Please select an agent to use: ## How can I share my own agent? -Currently there is 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, if you put its `dll` files -in the `agents` folder of the base directory of `aish.exe`, the agent will be loaded by `aish`. +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 diff --git a/reference/docs-conceptual/AIShell/developer/ollama-agent-readme.md b/reference/docs-conceptual/AIShell/developer/ollama-agent-readme.md index 245d495..f988503 100644 --- a/reference/docs-conceptual/AIShell/developer/ollama-agent-readme.md +++ b/reference/docs-conceptual/AIShell/developer/ollama-agent-readme.md @@ -15,7 +15,7 @@ You can also use this example code as a template to create your own agent. - Install [Ollama][01] - Install a [Ollama model][02], we - suggest using the `phi3` model as it is set as the default model in the code + suggest using the `phi3` model as it's set as the default model in the code - [Start the Ollama API server][03] ## Configuration @@ -35,8 +35,6 @@ There is an updated version of the Ollama agent available in the AI Shell reposi 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 -- Configuration is currently hard coded in the code and will be moved to a configuration file in the - future [01]: https://github.com/ollama/ollama diff --git a/reference/docs-conceptual/AIShell/how-to/agent-openai.md b/reference/docs-conceptual/AIShell/how-to/agent-openai.md index 44ad85c..4e77c8f 100644 --- a/reference/docs-conceptual/AIShell/how-to/agent-openai.md +++ b/reference/docs-conceptual/AIShell/how-to/agent-openai.md @@ -1,7 +1,7 @@ --- title: OpenAI agent README description: Learn how to use the OpenAI agent in AI Shell. -ms.date: 03/03/2025 +ms.date: 05/16/2025 ms.topic: how-to --- # OpenAI agent @@ -23,9 +23,14 @@ recommend using an Azure OpenAI deployment for enhanced security and privacy. ## Configuration -Before getting started you need to configure the agent with the details of your OpenAI details. To -configure the agent, run `/agent config openai-gpt` to open up the setting file in your default -editor. Update the file based on the following example: +Before getting started, you need to configure the agent with the details of your OpenAI +implementation. To configure the agent, use the `/agent config openai-gpt` command to open +configuration file in your default editor. + +- Azure OpenAI requires the `endpoint`, `deployment` name, and the `model` name. +- Public OpenAI only requires the `model` name. No endpoint, no deployment name. + +Update the file based on the following example: ```jsonc { @@ -68,7 +73,7 @@ editor. Update the file based on the following example: ``` > [!NOTE] -> The endpoint for the Azure OpenAI configuration does not need a full endpoint including the +> The endpoint for the Azure OpenAI configuration doesn't need a full endpoint including the > deployment, for example you can just use the following endpoint format, > `https://.openai.azure.com`. @@ -85,8 +90,8 @@ select different OpenAI models for each GPT as required. The command `/gpt` is provided to make it easy to manage the GPTs. -- Run `/gpt use ` to switch to another GPT instance, or run `/gpt use` to simply choose - from the available ones. +- 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. @@ -108,10 +113,10 @@ Commands: ## Support for other OpenAI-compatible models -With the release of AI Shell v1.0.0-preview.2, the `openai-gpt` agent extends support to third party +With the release of AI Shell v1.0.0-preview.2, the `openai-gpt` agent extends support to third-party models that follow the OpenAI API specifications, allowing for a more flexible AI experience. Many -of these models are open source tools for running SLMs and LLMs locally. The `openai-gpt` agent nows -supports the following additional models: +of these models are open source tools for running SLMs and LLMs locally. The `openai-gpt` agent now +supports the following models: - [**Ollama**][08] - [**LM Studio**][06] @@ -120,10 +125,23 @@ supports the following additional models: - [**Google Gemini**][02] - [**Grok**][05] -To use these models, you only need to configure the `endpoint`, `key` and `model name` in the agent -config file. The following `openai.agents.config` file contains example configurations for two of -the new AI providers. For more information about endpoints and model names, see to the documentation -for the specific model. +To use these models, you only need to configure the `endpoint`, `key`, and `model` name in the agent +configuration file. The following `openai.agents.config` file contains example configurations for +two of the new AI providers. For more information about endpoints and model names, see the +documentation for the specific model. + +With the release of AI Shell v1.0.0-preview.4, the `openai-gpt` agent supports the following +models names: + +- `o1` +- `o3` +- `o4-mini` +- `gpt-4.1` +- `gpt-4o` +- `gpt-4` +- `gpt-4-32k` +- `gpt-4-turbo` +- `gpt-3.5-turbo` [01]: /azure/ai-services/openai/how-to/create-resource?pivots=web-portal diff --git a/reference/docs-conceptual/AIShell/how-to/aishell-reference.md b/reference/docs-conceptual/AIShell/how-to/aishell-reference.md index cdb07ff..e509606 100644 --- a/reference/docs-conceptual/AIShell/how-to/aishell-reference.md +++ b/reference/docs-conceptual/AIShell/how-to/aishell-reference.md @@ -1,7 +1,7 @@ --- title: AI Shell command reference description: Learn about the command-line options and commands available in AI Shell. -ms.date: 10/29/2024 +ms.date: 05/16/2025 ms.topic: reference --- # AI Shell command reference @@ -33,21 +33,35 @@ By default, `aish` provides a base set of chat commands used to interact with th 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 + 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 + /refresh Start a new chat session. Core + /retry Regenerate a new response for the last query. Core ``` -## `/agent` sub commands +## `/agent` + +Command for agent management. + +``` +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` @@ -62,7 +76,6 @@ Arguments: `` Name of an agent. Options: - `--editor ` The editor to open the setting file in. -- `-h`, `--help` Show help and usage information Example: @@ -74,10 +87,6 @@ Example: List all available agents. -Options: - -- `-h`, `--help` Show help and usage information - Example: ``` @@ -99,14 +108,41 @@ Example: 2. Define the GPT(s). See details at https://aka.ms/aish/openai 3. Run '/refresh' to apply the new settings. - azure (active) This AI assistant can generate Azure CLI and - Azure PowerShell commands for managing - Azure resources, answer questions, and provides - information tailored to your specific Azure - environment. + azure This AI assistant connects you to the Copilot in + Azure 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. + +``` +agent use [] [options] +``` + +Arguments: `` - Name of an agent. + +## `/clear` + +Clears the screen. You can also use the alias `/cls`. + +## `/code` + +Command to interact with the code generated. + ``` +code [command] [options] +``` + +Subcommands: -## `/code` sub commands +- `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] ### `/code copy` @@ -121,11 +157,7 @@ code copy [] [options] Arguments: - `` Use the n-th (1-based) code snippet. Use all the code when no value is specified. -[default: -1] - -Options: - -- `-h`, `--help` Show help and usage information + [default: -1] Examples diff --git a/reference/docs-conceptual/AIShell/install-aishell.md b/reference/docs-conceptual/AIShell/install-aishell.md index a6d4aa0..4ab8835 100644 --- a/reference/docs-conceptual/AIShell/install-aishell.md +++ b/reference/docs-conceptual/AIShell/install-aishell.md @@ -24,17 +24,23 @@ AI Shell is supported on the following platforms: - 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 -- iTerm2 preferred (no split-screen experience) +- Default macOS Terminal app for the standalone experience +- iTerm2 required to use the split-screen 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 or higher (recommended) +- PowerShell 7.4.6 or higher +- PSReadLine v2.4.2-beta2 or higher - Any terminal emulator supported by the OS (no split-screen experience) > [!NOTE] @@ -55,8 +61,8 @@ On Windows, this script: On macOS, this script: -- Installs the `aish` executable to `/usr/local/AIShell` -- Due to some limitations, the **AIShell** module is not installed +- 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 diff --git a/reference/docs-conceptual/AIShell/overview.md b/reference/docs-conceptual/AIShell/overview.md index 4cdd4a3..9ab957c 100644 --- a/reference/docs-conceptual/AIShell/overview.md +++ b/reference/docs-conceptual/AIShell/overview.md @@ -1,7 +1,7 @@ --- title: What is AI Shell? description: Learn about AI Shell, an interactive shell that provides a chat interface with language models. -ms.date: 11/18/2024 +ms.date: 05/16/2025 ms.topic: overview --- @@ -13,10 +13,10 @@ interact with the agents in a conversational manner. The AI Shell project includes: -- The command-line shell (`aish`) interface +- 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 tight integration with PowerShell. For more information, see the +- A PowerShell module for integration with PowerShell. For more information, see the [AI Shell module][01]. Each AI assistant is known as an agent. The initial release of AI Shell includes two agents: @@ -37,42 +37,39 @@ shell. These features include: ## Project Status -AI Shell is currently in **Public Preview**. This means that the tool is available for testing, but -it's not feature-complete. Please note that some elements of the tool are still under development -and are subject to change. Your feedback is important to us during this development phase. We -encourage you to share your experiences to help us improve AI Shell. +The current version of AI Shell is 1.0.0-preview.4. AI Shell is provided for testing, but it's not +feature-complete. Some elements of the tool are still under development and are subject to change. +Your feedback is important to us during this development phase. We encourage you to share your +experiences to help us improve AI Shell. ## Known Issues This current release of AI Shell has some known issues that we're actively working on addressing: -- The **AI Shell** module isn't supported on Linux. -- The split-screen experience only works with Windows Terminal. The `aish` executable can be run on - macOS and Linux, but the split-screen experience isn't available. +- The split-screen experience works with Windows Terminal and iTerm2 for macOS. +- The **AI Shell** module isn't supported on Linux. You can run the `aish` executable on Linux, + but it isn't tested on any Linux distribution. - If you have multiple versions of Windows Terminal installed, the `Start-AIShell` command opens a new terminal window running a different 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 are using the default Mac Terminal, the colors may not render correctly and may be +- If you're using the default Mac Terminal, the colors might not render correctly. It might be difficult to read the code generated. -If you encounter any other issues, please report them to our [GitHub repository][03]. +You can report other issues in the [GitHub repository][03]. -## Providing Feedback +## Providing feedback We welcome your feedback to help improve AI Shell! Here are ways you can get involved: - **File Issues:** If you encounter bugs, have suggestions for new features, or would like to report - inconsistencies, please open an issue on the [AI Shell GitHub repository][03]. -- **Join the discussions:** Join our community discussions on the on the - [GitHub discussions][02] tab. Share ideas, discuss potential improvements, and connect with other - users. This is also where we encourage you to share any agents you may create. -- **Documentation:** If you notice any documentation gaps, please suggest changes or submit PRs to + inconsistencies, open an issue on the [AI Shell GitHub repository][03]. +- **Join the discussions:** Join our community discussions in the [GitHub discussions][02] tab. + Share ideas, discuss potential improvements, connect with other users, and share any agents you + create. +- **Documentation:** If you notice any documentation gaps, you can suggest changes or submit PRs to improve our documentation. -We aren't accepting pull requests for code changes at this time, but we value your feedback and -documentation contributions. - [01]: /powershell/module/aishell/ [02]: https://github.com/PowerShell/ProjectMercury/discussions diff --git a/reference/ps-modules/AIShell/AIShell.md b/reference/ps-modules/AIShell/AIShell.md index fe152e7..f06e068 100644 --- a/reference/ps-modules/AIShell/AIShell.md +++ b/reference/ps-modules/AIShell/AIShell.md @@ -1,10 +1,11 @@ --- Download Help Link: https://aka.ms/aishell-help -Help Version: 0.1.0 +Help Version: 1.0.0 Locale: en-US Module Guid: ecb8bee0-59b9-4dae-9d7b-a990b480279a Module Name: AIShell -ms.date: 10/29/2024 +ms.date: 05/16/2025 +ms.custom: 1.0.0-preview.4 title: AIShell Module --- diff --git a/reference/ps-modules/AIShell/Invoke-AIShell.md b/reference/ps-modules/AIShell/Invoke-AIShell.md index 3841ef3..1e29db4 100644 --- a/reference/ps-modules/AIShell/Invoke-AIShell.md +++ b/reference/ps-modules/AIShell/Invoke-AIShell.md @@ -2,7 +2,8 @@ external help file: AIShell.Integration.dll-Help.xml Module Name: AIShell online version: -ms.date: 10/29/2024 +ms.date: 05/16/2025 +ms.custom: 1.0.0-preview.4 schema: 2.0.0 --- @@ -16,13 +17,31 @@ Sends a query to the connected AIShell window. Results are shown in the AIShell ### Default (Default) ``` -Invoke-AIShell [-Query] [-Agent ] [[-Context] ] [] +Invoke-AIShell -Query [-Agent ] [-Context ] [] ``` ### Clipboard ``` -Invoke-AIShell [-Query] [-Agent ] [-ContextFromClipboard] [] +Invoke-AIShell -Query [-Agent ] [-ContextFromClipboard] [] +``` + +### PostCode + +``` +Invoke-AIShell [-PostCode] [] +``` + +### CopyCode + +``` +Invoke-AIShell [-CopyCode] [] +``` + +### Exit + +``` +Invoke-AIShell [-Exit] [] ``` ## DESCRIPTION @@ -50,7 +69,7 @@ currently selected agent. ```yaml Type: System.String -Parameter Sets: (All) +Parameter Sets: Default, Clipboard Aliases: Required: False @@ -70,7 +89,7 @@ Parameter Sets: Default Aliases: Required: False -Position: 1 +Position: Named Default value: None Accept pipeline input: True (ByValue) Accept wildcard characters: False @@ -92,17 +111,68 @@ 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: (All) +Type: System.String[] +Parameter Sets: Default, Clipboard Aliases: Required: True -Position: 0 +Position: Named Default value: None Accept pipeline input: False Accept wildcard characters: False diff --git a/reference/ps-modules/AIShell/Resolve-Error.md b/reference/ps-modules/AIShell/Resolve-Error.md index 0575a53..f46c957 100644 --- a/reference/ps-modules/AIShell/Resolve-Error.md +++ b/reference/ps-modules/AIShell/Resolve-Error.md @@ -2,7 +2,8 @@ external help file: AIShell.Integration.dll-Help.xml Module Name: AIShell online version: -ms.date: 03/03/2025 +ms.date: 05/16/2025 +ms.custom: 1.0.0-preview.4 schema: 2.0.0 --- diff --git a/reference/ps-modules/AIShell/Start-AIShell.md b/reference/ps-modules/AIShell/Start-AIShell.md index 8c8cbe2..f4c3619 100644 --- a/reference/ps-modules/AIShell/Start-AIShell.md +++ b/reference/ps-modules/AIShell/Start-AIShell.md @@ -2,7 +2,8 @@ external help file: AIShell.Integration.dll-Help.xml Module Name: AIShell online version: -ms.date: 10/29/2024 +ms.date: 05/16/2025 +ms.custom: 1.0.0-preview.4 schema: 2.0.0 --- @@ -24,6 +25,10 @@ Starts an AIShell session in a split pane window of Windows Terminal and iTerm2. 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