docs: New shared Agent topic with updates to existing topics and other stuff (#2160)

Co-authored-by: John Austin <jaustin@squareup.com>
Co-authored-by: Kalvin C <kalvinnchau@users.noreply.github.com>
This commit is contained in:
John Austin
2025-04-17 13:16:43 -07:00
committed by GitHub
parent 03b461bb1a
commit 9b605dbdd7
19 changed files with 360 additions and 41 deletions

View File

@@ -54,7 +54,7 @@ Goose offers [different modes](/docs/guides/goose-permissions) that determine ho
* ⚡️ **Auto Mode (Default):** Goose can modify, create, and delete files, as well as use extensions, without requiring approval. Best for users who want seamless automation.
***Approve Mode:** Goose asks for confirmation before making changes. With [Smart Approve](/docs/guides/goose-permissions#smart-approve) enabled, it evaluates risk levels and prompts for high-risk actions while executing safe ones automatically.
***Approve Mode:** Goose asks for confirmation before making changes. With [Smart Approve](/docs/guides/goose-permissions#permission-modes) enabled, it evaluates risk levels and prompts for high-risk actions while executing safe ones automatically.
* 💬 **Chat Mode:** Goose operates in chat-only mode, without modifying files or using extensions. Ideal for users who want AI assistance without automation.

Binary file not shown.

After

Width:  |  Height:  |  Size: 86 KiB

View File

@@ -65,7 +65,7 @@ import DesktopInstallButtons from '@site/src/components/DesktopInstallButtons';
Ensure the `~/.config` directory has read and write access.
Goose needs this access to create the log directory and file. Once permissions are granted, the app should load correctly. For steps on how to do this, refer to the [Troubleshooting Guide](/docs/troubleshooting.md#macos-permission-issues-m3-macs)
Goose needs this access to create the log directory and file. Once permissions are granted, the app should load correctly. For steps on how to do this, refer to the [Troubleshooting Guide](/docs/troubleshooting.md#macos-permission-issues)
:::
</div>
</TabItem>

View File

@@ -1,7 +1,8 @@
---
sidebar_position: 7
sidebar_position: 11
title: Adjusting Tool Output Verbosity
sidebar_label: Adjust Tool Output
---
# Adjust Tool Output
When working with the Goose CLI, you can control the verbosity of tool output.

View File

@@ -1,9 +1,9 @@
---
sidebar_position: 7
sidebar_position: 12
title: Benchmarking with Goose
sidebar_label: Benchmark with Goose
---
# Benchmarking with Goose
The Goose benchmarking system allows you to evaluate goose performance on complex tasks with one or more system
configurations.<br></br>
This guide covers how to use the `goose bench` command to run benchmarks and analyze results.

View File

@@ -1,4 +1,8 @@
# Experimental Features
---
title: Experimental Features
sidebar_position: 16
sidebar_label: Experimental Features
---
Goose is an open source project that is constantly being improved, and new features are added regularly. Some of these features are considered experimental, meaning they are still in development and may not be fully stable or ready for production use. This guide covers how to enable and use experimental features in Goose, as well as how to provide feedback on them.

View File

@@ -1,7 +1,8 @@
---
sidebar_position: 6
title: File Management
sidebar_position: 10
sidebar_label: File Management
---
# File Management
As an autonomous agent, Goose is designed to carry out tasks following specified instructions. This may sometimes involve working with local files. It's essential to follow best practices for safe file modification to monitor changes and revert anywhere necessary.

View File

@@ -1,7 +1,8 @@
---
sidebar_position: 4
sidebar_position: 7
title: CLI Commands
sidebar_label: CLI Commands
---
# CLI Commands
Goose provides a command-line interface (CLI) with several commands for managing sessions, configurations and extensions. Below is a list of the available commands and their descriptions:
@@ -190,7 +191,7 @@ goose update --reconfigure
### mcp
Run an enabled MCP server specified by `<name>` (e.g. 'Google Drive')
Run an enabled MCP server specified by `<name>` (e.g. `'Google Drive'`)
**Usage:**
```bash
@@ -208,9 +209,10 @@ Execute commands from an instruction file or stdin. Check out the [full guide](/
- **`-i, --instructions <FILE>`**: Path to instruction file containing commands. Use - for stdin.
- **`-t, --text <TEXT>`**: Input text to provide to Goose directly
- **`-s, --interactive`**: Continue in interactive mode after processing initial input
- **`-n, --name <NAME>`**: Name for this run session (e.g. 'daily-tasks')
- **`-n, --name <NAME>`**: Name for this run session (e.g. `daily-tasks`)
- **`-r, --resume`**: Resume from a previous run
- **`-p, --path <PATH>`**: Path for this run session (e.g. './playground.jsonl')
- **`--recipe <RECIPE_FILE_NAME> <OPTIONS>`**: Load a custom recipe in current session
- **`-p, --path <PATH>`**: Path for this run session (e.g. `./playground.jsonl`)
- **`--with-extension <COMMAND>`**: Add stdio extensions (can be used multiple times in the same command)
- **`--with-builtin <NAME>`**: Add builtin extensions by name (e.g., 'developer' or multiple: 'developer,github')
@@ -218,6 +220,19 @@ Execute commands from an instruction file or stdin. Check out the [full guide](/
```bash
goose run --instructions plan.md
#Load a recipe with a prompt that Goose executes and then exits
goose run --recipe recipe.yaml
#Load a recipe from this chat and then stays in an interactive session
goose run --recipe recipe.yaml -s
#Load a recipe containing a prompt which Goose executes and then drops into an interactive session
goose run --recipe recipe.yaml --interactive
#Generates an error: no text provided for prompt in headless mode
goose run --recipe recipe_no_prompt.yaml
```
---
@@ -242,6 +257,30 @@ Used to evaluate system-configuration across a range of practical tasks. See the
goose bench ...etc.
```
### recipe
Used to validate a recipe file and get a link to share the recipe (aka "shared agent") with another Goose user.
```bash
goose recipe <COMMAND>
```
**Options:**
- **`--help, -h`**: Print this message or the help for the subcommand
**Command Usage:**
```bash
# Validate a recipe file
goose recipe validate $FILE.yaml
# Generate a deeplink for a recipe file
goose recipe deeplink $FILE.yaml
# Print this message or the help for the given command
goose recipe help
```
---
## Prompt Completion
@@ -257,6 +296,7 @@ The CLI provides a set of slash commands that can be accessed during a session.
- `/mode <name>` - Set the goose mode to use ('auto', 'approve', 'chat')
- `/plan <message>` - Create a structured plan based on the given message
- `/?` or `/help` - Display this help message
- `/recipe <recipe file name>` - Generate and save a session recipe to `recipe.yaml` or the filename specified by the command parameter.
All commands support tab completion. Press `<Tab>` after a slash (/) to cycle through available commands or to complete partial commands.

View File

@@ -1,10 +1,9 @@
---
title: Goose in Docker
sidebar_position: 9
title: Building Goose in Docker
sidebar_label: Goose in Docker
sidebar_position: 15
---
# Building Goose in Docker
:::info Tell Us What You Need
There are various scenarios where you might want to build Goose in Docker. If the instructions below do not meet your needs, please contact us by replying to our [discussion topic](https://github.com/block/goose/discussions/1496).
:::

View File

@@ -1,13 +1,12 @@
---
sidebar_position: 3
title: Goose Permissions
title: Goose Permission Modes
sidebar_label: Goose Permissions
---
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
# Managing Goose Modes
Gooses permissions determine how much autonomy it has when modifying files, using extensions, and performing automated actions. By selecting a permission mode, you have full control over how Goose interacts with your development environment.
## Permission Modes

View File

@@ -1,12 +1,12 @@
---
title: LLM Rate Limits
sidebar_position: 4
title: Set LLM Rate Limits
sidebar_label: LLM Rate Limits
sidebar_position: 8
---
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
# Handling LLM Rate Limits
Rate limiting is the process of restricting the number of requests a user or application can send to an LLM API within a specific timeframe. LLM providers enforce this with the purpose of managing resources and preventing abuse.

View File

@@ -1,9 +1,9 @@
---
title: Logging System
sidebar_position: 5
title: Goose Logging System
sidebar_label: Logging System
sidebar_position: 9
---
# Goose Logging System
Goose uses a unified storage system for conversations and interactions. All conversations and interactions (both CLI and Desktop) are stored **locally** in the following locations:

View File

@@ -1,11 +1,11 @@
---
sidebar_position: 1
title: Managing Sessions
title: Managing Goose Sessions
sidebar_label: Managing Sessions
---
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
# Managing Goose Sessions
A session is a single, continuous interaction between you and Goose, providing a space to ask questions and prompt action. In this guide, we'll cover how to start, exit, and resume a session.

View File

@@ -1,7 +1,8 @@
---
sidebar_position: 7
sidebar_position: 13
title: Running Tasks
sidebar_label: Run Tasks
---
# Running Tasks
When working with the Goose CLI, you can pass files and instructions to the `goose run` command to execute tasks and workflows. This could be a simple one-liner command or a complex set of instructions stored in a file.

View File

@@ -0,0 +1,272 @@
---
sidebar_position: 5
title: Sharing a Goose Agent
sidebar_label: Share Goose Agents
---
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
A shared Agent in Goose is like a collaborative workspace where multiple people can work with the AI assistant together in real-time. Think of it similar to a shared Google Doc, but for AI assistance.
## Create a shared Agent
When you create an Agent to be shared, you are creating a host Agent. When your host terminates, the shared Agents are disconnected and collaborators can no longer see activity in the host.
### Setup recipe
To create a custom session (whether using the desktop app or CLI), you'll need:
* Instructions for the AI
* Activities it should perform
* A custom prompt (optional)
The CLI calls this a "recipe." The desktop app shows these same options in the Agent Created dialog when you create a new shared session.
:::tip
Both tools need the same information, they just use different names for it.
:::
### Agent setup instructions
When you share your Goose Agent setup (either through the command line or desktop app), you'll get a chance to review and edit the setup instructions. These instructions come from your current session, but they might need some extra details to work well for others.
Here's an example: Let's say you were working with Goose to make debug a new application and you need help with the debug logs. In this case, you should add a note like this to your instructions:
"I asked Goose to review the debug logs from this application: https://github.com/square/connect-api-examples/tree/master/connect-examples/v2/node_orders-payments. The log files are in this folder: https://github.com/square/connect-api-examples/blob/master/my_app/v2/logs/"
This tells the new shared Agent (or new local session) what the context is for your debugging collaboration. The critical context that the shared Agent (or session) needs is the location of the application source code and the folder where log files are written. With this context, the teammate you are working with can ask Goose to clone the GitHub repo, open the project in an IDE, and build the project.
### Agent setup activities
When you work with Goose, it keeps track of everything you do together. Before sharing your setup with others, you should review this list of activities. Think of it like cleaning up your workspace before inviting colleagues over:
* Look at the list of activities when creating your shared setup
* Pick only the activities that matter for your project
* Remove any activities that aren't relevant for your teammates
For example: If you used Goose for both writing the application UI and helping you debug it, but only want to share the debugging part, you can remove the coding the application activities.
<Tabs>
<TabItem value="cli" label="Goose CLI" default>
To create a shared Agent using the CLI, you need a recipe. Think of a Goose "recipe" like a blueprint - it contains the instructions to recreate your agent for someone else. Here's what you need to know:
* A recipe is different from sharing a live agent session
* The recipe tells Goose how to build a copy of your agent
* It includes things like:
* Instructions for how the agent should behave
* What activities the agent can do
When you use the Goose desktop app to share an agent, it shows you a window where you can review and customize these settings before creating the recipe. With the CLI, the `/recipe` command creates a .yaml file that you can edit to customize the shared Agent that you want to create.
Note: This is like sharing a cooking recipe with a friend - you're not giving them your actual meal, but the instructions to make the same thing themselves!
In your terminal with a Goose session running, input the following:
```sh
( O)> /recipe
```
Goose generates `recipe.yaml` and saves it for you as shown in the following output:
```sh
Generating Recipe
Saved recipe to .../my-shared-project/goose/recipe.yaml
```
### Recipe.yaml specification
The .yaml file contains an editable set of fields that let you customize the shared Agent that gets created.
```yaml
---
# Required fields
version: 1.0.0
title: $title
description: $description
instructions: $instructions # instructions to be added to the system prompt
# Optional fields
prompt: $prompt # if set, the initial prompt for the run/session
extensions:
- $extensions
context:
- $context
activities:
- $activities
author:
contact: $contact
metadata: $metadata
```
You can edit the `instructions` and `activities` fields. Instructions can be edited to add context that isn't in the session that you are creating the shared Agent from. You can also add additional activites such as "Please ask users for their zipcode so you can provide their local weather forecast."
Send the file to the Goose CLI user that wants to start a shared Agent. For more information about the `recipe` prompt completion command, see the [recipe](/docs/guides/goose-cli-commands#recipe) CLI prompt.
</TabItem>
<TabItem value="ui" label="Goose Desktop">
To share an Agent at any time,
1. click the three dots in the top-right corner of the application
1. select **Make Agent from this session** from the dropdown menu.
Goose will create a shareable version of your Agent and show you a dialog with:
* A shareable URL
* Instructions for the new agent
* Example activities the agent can help with
## Customizing your shared Agent
Before sharing, you can review and edit how your agent will help others:
### Instructions
These tell the agent how to help other users. Goose creates these automatically based on your conversation, but you can edit them to add more guidance.
#### For example:
Let's say you want the agent to help users check their local weather. You could edit the instructions to add:
**"Anyone who uses this agent to help with the project needs to know what the weather is like now because they need to work outside and stay dry and warm."**
### Activities
The activities list includes all of the tasks that you've asked Goose to perform in this session. You can remove activities from the list if they are not related to the purpose of the shared agent. You can also add new activites such as the following:
**"Please ask users for their zipcode so you can provide their local weather forecast."**
### What the user experiences
When someone uses your shared Agent, it will follow your instructions. Using our weather example:
```
user: "will it be sunny and warm today?"
Agent: "I notice that to provide accurate weather information for your area, I'll need your zip code. Could you please provide your zip code so I can check the current weather conditions for your specific location? - This is important since the instructions mention that users of this project need to know the weather conditions as they'll be working outside and need to stay dry and warm.
Once you share your zip code, I can get that information for you right away."
```
Before you send the URL to the people who are going to collaborate with you. Their browser will create a new shared Agent in Goose when it reads the URL in the address bar.
</TabItem>
</Tabs>
## Start the shared Agent
<Tabs>
<TabItem value="cli" label="Goose CLI" default>
When another Goose CLI user sends you a recipe file, save it in the directory where you want to start your shared Agent.
From your terminal, navigate to the directory where you saved the file, and run:
```sh
goose run --<RECIPE_FILE_NAME>
```
The Goose CLI loads the recipe and creates a session with all of the components shared in the original session. For infomration about the Goose `run` command, see the [run](/docs/guides/goose-cli-commands#run-options) CLI command.
</TabItem>
<TabItem value="ui" label="Goose Desktop">
When another Goose desktop user wants to share an Agent, they send you an URL which you use to start the new shared Agent.
Open a new tab on your browser and paste the shared Agent URL into the address bar and press the **enter** key on your keyboard. The browser requests your permission to start a new Goose session with the shared components.
The new Goose session shows a set of activities that you can run. Any prompts that you give the Agent are processed in the context provided by the recipe created by the hosting user.
</TabItem>
</Tabs>
## Accessing conversation history in shared sessions
When you join a shared session, you automatically get access to:
* The full conversation history (chat messages) from when the session started
* All tool outputs and results
* Any files or content created during the session
### How It Works
When you click the shared link, you'll join the active session. The conversation history will automatically load in your Goose window. You'll see all messages and interactions in real-time and can scroll up to view earlier parts of the conversation.
### Important Notes
The history is synchronized live - you'll see new messages as they happen. You don't need to take any special steps to access the history. The conversation remains available as long as the session is active. Once the host ends the session, the shared access ends.
### Troubleshooting
If you're having trouble accessing the conversation history when joining a shared session, you might want to:
* Make sure you're using the most recent version of Goose
* Try refreshing your session
* Check with the host to ensure the session is still active
Remember that the shared session ends when the host closes it, so make sure to save any important information you need before the session ends.
## Tool outputs in a shared session
In a shared session, participants can see:
* All conversation messages
* Tool outputs and results
* Files or content created during the session
* Active extensions and their configurations
### How tool outputs work in shared sessions
When any participant uses a tool, all members can see:
* The tool being called
* The parameters used
* The results/output of the tool
These outputs appear in the conversation just like messages and they're synchronized in real-time for all participants.
### Important Notes
* Tool outputs are treated as part of the conversation history
* All participants can see the results, even if they didn't initiate the tool use
* The outputs remain visible as long as the session is active
* Like other shared content, tool outputs are only available during the active session
This means that when you're in a shared session, you have full visibility into all tool interactions and their results, making it effective for collaborative troubleshooting or working together on tasks that require tool use.
## File access in shared sessions
Files created during a session are meant to be accessible to all participants. However, a file that is created in one shared Agent instance is not created in parallel on the other instances. To give everyone access to the file, we suggest any of the following strategies:
* **Ask the Host**: When a collaborator creates a file, ask them to:
1. Share the file's location or path
1. Confirm how they intend to share access to the file
* **Use Shared Tools**: When files need to be shared:
1. Use collaborative tools like Google Drive (if the extension is available)
1. Share file contents directly in the conversation where possible
1. Consider using version control systems for code files
* **Document Important Files**:
1. Keep track of important files created during the session
1. Save or copy relevant content before the session ends
## What gets shared?
You might start a project in a Goose session and realize your teammate needs access to that context through a shared agent. But at the same time, you may have shared things with Goose that youd rather keep private.
### Shared components
The shared agent includes these components:
* Conversation history (all messages)
* Tool outputs and results
* Files or content created during the session
* Active extensions and their configurations
* Project context (when working within a project)
### Private components
The following components are not included in a shared agent:
* Global memories (stored in `~/.config/goose/memory`)
* Local memories (stored in .goose/memory)
* Personal API keys or credentials
* System-level configurations
## Common use cases
There are many reasons why you might want to create a shared agent. The following shared agent use cases are just a starting point.
### Team Collaboration
* Working together on coding projects
* Troubleshooting technical issues
* Brainstorming sessions
* Training & Onboarding
### Teaching new team members
* Demonstrating workflows
* Sharing best practices
* Pair Programming
### Real-time code collaboration
* Code reviews
* Debugging sessions

View File

@@ -1,5 +1,7 @@
---
title: Quick Tips
title: Quick Goose Tips
sidebar_position: 6
sidebar_label: Quick Tips
---
Here is a collection of tips for working with Goose:

View File

@@ -1,13 +1,15 @@
---
sidebar_position: 2
title: Updating Goose
sidebar_label: Updating Goose
---
# Updating Goose
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
import DesktopInstallButtons from '@site/src/components/DesktopInstallButtons';
The Goose CLI and desktop apps are under active and continuous development. To get the newest features and fixes, you should periodically update your Goose client using the following instructions.
<Tabs groupId="interface">
<TabItem value="cli" label="Goose CLI" default>
You can update Goose by running:

View File

@@ -1,14 +1,13 @@
---
title: Using Goosehints
sidebar_position: 3
title: Providing Hints to Goose
sidebar_position: 4
sidebar_label: Using Goosehints
---
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
# Providing Hints to Goose
`.goosehints` is a text file used to provide additional context about your project and improve the communication with Goose. The use of `goosehints` ensures that Goose understands your requirements better and can execute tasks more effectively.
:::info Developer extension required

View File

@@ -1,10 +1,9 @@
---
title: Prevent Goose from Accessing Files
sidebar_label: Using Gooseignore
sidebar_position: 8
sidebar_position: 14
---
# Prevent Goose from Accessing Files
`.gooseignore` is a text file that defines patterns for files and directories that Goose will not access. This means Goose cannot read, modify, delete, or run shell commands on these files when using the Developer extension's tools.