diff --git a/docs/plugins/using-toolkits.md b/docs/plugins/using-toolkits.md index 042cfa5b..20e7a91b 100644 --- a/docs/plugins/using-toolkits.md +++ b/docs/plugins/using-toolkits.md @@ -1,18 +1,18 @@ # Using Toolkits -[Toolkits](https://block.github.io/goose/plugins/plugins.html) in Goose are add-ons that expand its capabilities, offering tools and prompts for specific tasks. They make it easier to interact with external systems and handle complex operations. In this guide, we'll cover how to use Toolkits included in `goose` and those available through the `goose-plugins` repository. +[Toolkits](https://block.github.io/goose/plugins/plugins.html) in Goose are add-ons that expand its capabilities, offering tools and prompts for specific tasks. They make it easier to interact with external systems and handle complex operations. In this guide, we'll cover how to use toolkits included in `goose` and those available through the `goose-plugins` repository. !!! important - Before using Toolkits, ensure Goose is installed and properly set up. If you haven’t installed Goose yet, follow the [Goose Installation Guide](https://block.github.io/goose/installation.html). + Before using toolkits, ensure Goose is installed and properly set up. If you haven’t installed Goose yet, follow the [Goose Installation Guide](https://block.github.io/goose/installation.html). ## Listing Available Toolkits -To list available Toolkits, use the following command within the Goose repo: +To list available toolkits, use the following command within the Goose repo: ``` goose toolkit list ``` -This will display a list of all Toolkits available in your environment. +This will display a list of all toolkits available in your environment. The output should look similar to the following: @@ -35,10 +35,10 @@ The list above is limited. For a complete list, refer to the [Goose Available To ## Adding Toolkits to a Profile -To use a Toolkit within your Goose sessions, you'll need to add them to the `profiles.yaml` file, which can be found in your `User` directory at `~/.config/goose/profiles.yaml`. Here's how to add multiple Toolkits: +To use a Toolkit within your Goose sessions, you'll need to add them to the `profiles.yaml` file, which can be found in your `User` directory at `~/.config/goose/profiles.yaml`. Here's how to add multiple toolkits: -```yaml -my-profile: +```yaml title="profiles.yaml" +default: provider: openai processor: gpt-4o accelerator: gpt-4o-mini @@ -54,38 +54,55 @@ my-profile: You always want to have the `synopsis` Toolkit, formerly known as the `developer` Toolkit enabled. It is essential for Goose to be able to create files for you, if this is removed it will greatly limit Goose's functionality. -Additionally, use the `requires` field to specify dependencies between Toolkits, and any necessary configurations. If there are no requirements, simply add an empty set of braces: `{}`. However, if a toolkit requires dependencies or configurations, you can specify that here. For example, if `my_toolkit` depends on `another_toolkit`, you would configure it as shown below: - -```yaml -my-profile: - provider: openai - processor: gpt-4o - accelerator: gpt-4o-mini - moderator: synopsis - toolkits: - - name: synopsis - requires: {} - - name: my_toolkit - requires: - another_toolkit: - config_option_1: value1 -``` +Additionally, use the `requires` field to specify dependencies between toolkits, and any necessary configurations. If there are no requirements, simply add an empty set of braces: `{}`. ## Starting a Goose Session with Toolkits -Once your [profile](https://block.github.io/goose/guidance/getting-started.html#configuring-goose-with-the-profilesyaml-file) is set up, start a Goose session with the specified profile: +Once your [profile](https://block.github.io/goose/guidance/getting-started.html#configuring-goose-with-the-profilesyaml-file) is set up, you can start a Goose session with the specified profile. You can configure multiple profiles in your profiles.yaml file to suit different needs. For example, you might have separate `default` and `work` profiles: + +```yaml title="profiles.yaml" +default: + provider: openai + processor: gpt-4o + accelerator: gpt-4o-mini + moderator: synopsis + toolkits: + - name: synopsis + requires: {} + - name: screen + requires: {} +work: + provider: block + processor: gpt-4o + accelerator: gpt-4o-mini + moderator: synopsis + toolkits: + - name: synopsis + requires: {} + - name: jira + requires: {} +``` + +In the example above: +- The `default` profile uses the `synopsis`, and `screen` toolkits. +- The `work` profile is configured with the `synopsis` and `jira` toolkits. + +To start a session with the `work` profile, run: ```bash -goose session start --profile my-profile +goose session start --profile work ``` -This command initializes Goose with the Toolkits defined in your profile. +If your `profile.yaml` file contains only one profile, you can simply run: -!!! example - If your profile includes the `synopsis` and `my_toolkit` Toolkits, Goose will initialize with both functionalities. +```bash +goose session start +``` ## Using Toolkits from Goose Plugins -To access additional Toolkits provided by the `goose-plugins` repository, follow these steps: +Goose comes with a default set of toolkits for essential functionality. For more specialized tasks and integrations, the `goose-plugins` repository provides optional toolkits that you can add as needed. This allows you to customize Goose to match your specific workflows without overloading the core installation. + +To access these additional toolkits, follow these steps: ### Install `goose-plugins`: @@ -106,8 +123,8 @@ uv run goose toolkit list ### Update the `profiles.yaml` File: Add the desired Toolkit from the `goose-plugins` repository to your profile. For example: -```yaml -my-profile: +```yaml title="profiles.yaml" +default: provider: openai processor: gpt-4o accelerator: gpt-4o-mini @@ -115,14 +132,14 @@ my-profile: toolkits: - name: synopsis requires: {} - - name: artify + - name: jira requires: {} ``` ### Start the Goose Session: ```bash -goose session start --profile my-profile +goose session start --profile default ```