diff --git a/docs/GettingStarted.md b/docs/GettingStarted.md new file mode 100644 index 00000000..60ad4a5f --- /dev/null +++ b/docs/GettingStarted.md @@ -0,0 +1,134 @@ +# Getting Started with AIShell + +AIShell 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 AIShell. + +## What is AIShell? + +AIShell is a command line interface (CLI) tool that allows you to interact with different AI +assistants within your CLI. You can choose which agent to use when you start AIShell. And you can +switch between them when you're using AIShell. + +Each AI assistant is known as an agent. In this version of AIShell, we include two agents, one +talking to an **Azure OpenAI** instance of **gpt-4o** and an Azure agent that can assist with Azure +CLI commands. During this initial development period, we provide you with access to Azure OpenAI. +When AIShell formally releases, you must provide your own Azure OpenAI deployment and update +the configuration to use your instance. + +The AIShell executable (`aish.exe`) can be run in your command shell for a full-screen experience. +If you're using Windows Terminal and PowerShell 7, you can use the **AIShell** PowerShell module to +create a split-screen or sidecar experience. This is the recommended way to use AIShell because +you get deeper integration with the shell. These features include: + +- Inserting code from the sidecar response directly into the working shell +- Multi-step commands are put into the Predictive IntelliSense buffer for quick acceptance +- Easy, single-command error recovery + +## Starting AIShell + +Use the `Start-AIShell` command in the **AIShell** module to open a split pane experience in Windows +Terminal. When AIShell starts, it prompts you to choose an agent. + +![An animation showing Getting Started with AIShell.](/docs/media/startAISHell.gif) + +## Using AIShell + +Now that you have selected an agent, you can begin chatting with it. The installed Azure OpenAI +agent is configured to be a PowerShell expert. This means we've modified the system prompt +to say it should act like a PowerShell expert. It's not trained on any specific PowerShell code or +documentation. In the final version, you must configure the agent with your endpoint, API keys, +and system prompt before using it. For this walkthrough, we've performed these steps for you. + +The Azure agent is designed to bring the Copilot in Azure experience directly to your command line. It +provides assistance for Azure CLI and Azure PowerShell commands. Typically, you need to sign into +Azure using the `az login` or `Connect-AzAccount` commands. However, for this walkthrough, we've done +that for you. + +## Use AIShell 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?" + +Here's a quick demo showing the Azure Agent in action: + +![An animation showing Azure Agent in action.](/docs/media/AzureAgent.gif) + +### 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](/docs/media/SwitchingAgents.gif) + +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 AIShell.](/docs/media/InsertCode.gif) + + +### Key bindings for commands + +AIShell has key bindings for the `/code` command. They key bindings are currently hard-coded, but +custom key bindings will be supported in future releases. + +| 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 | + +### 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 AIShell window for resolution. This command asks the AI model to help you +resolve the error. + +![An animation showing Resolving Errors with AIShell.](/docs/media/ResolveError.gif) + +### Invoking AIShell + +You can use the `Invoke-AIShell` cmdlet to send queries to the current agent in the open AIShell window. +This command allows you to interact with the AI model from your working terminal. + +![An animation using Invoke-AIShell.](/docs/media/InvokeAIShell.gif) + diff --git a/docs/media/AzureAgent.gif b/docs/media/AzureAgent.gif new file mode 100644 index 00000000..9d3ef285 Binary files /dev/null and b/docs/media/AzureAgent.gif differ diff --git a/docs/media/InsertCode.gif b/docs/media/InsertCode.gif new file mode 100644 index 00000000..ba6e221c Binary files /dev/null and b/docs/media/InsertCode.gif differ diff --git a/docs/media/InvokeAIShell.gif b/docs/media/InvokeAIShell.gif new file mode 100644 index 00000000..086d3081 Binary files /dev/null and b/docs/media/InvokeAIShell.gif differ diff --git a/docs/media/ResolveError.gif b/docs/media/ResolveError.gif new file mode 100644 index 00000000..84023d8c Binary files /dev/null and b/docs/media/ResolveError.gif differ diff --git a/docs/media/SwitchingAgents.gif b/docs/media/SwitchingAgents.gif new file mode 100644 index 00000000..fda7416d Binary files /dev/null and b/docs/media/SwitchingAgents.gif differ diff --git a/docs/media/startAISHell.gif b/docs/media/startAISHell.gif new file mode 100644 index 00000000..56beb511 Binary files /dev/null and b/docs/media/startAISHell.gif differ