-
Notifications
You must be signed in to change notification settings - Fork 2.3k
docs: new multi-model section with autopilot topic #4864
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
Merged
Changes from all commits
Commits
Show all changes
5 commits
Select commit
Hold shift + click to select a range
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,5 @@ | ||
| { | ||
| "label": "Multi-Model Config", | ||
| "position": 20, | ||
| "description": "Configure multiple models and providers for model-switching strategies." | ||
| } |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,127 @@ | ||
| --- | ||
| sidebar_position: 1 | ||
| title: Automatic Multi-Model Switching | ||
| sidebar_label: Automatic Model Switching | ||
| --- | ||
|
|
||
| The AutoPilot feature enables intelligent, context-aware switching between different models. You simply work naturally with goose, and AutoPilot chooses the right model based on conversation content, complexity, tool usage patterns, and other triggers. | ||
|
|
||
| :::warning Experimental Feature | ||
| AutoPilot is an experimental feature. Behavior and configuration may change in future releases. | ||
| ::: | ||
|
|
||
| ## How AutoPilot Works | ||
|
|
||
| After you configure which models to use for different roles, AutoPilot handles the rest. During your sessions, it automatically switches to the most appropriate model for your current task—whether you need specialized coding help, complex reasoning, or just want a second opinion. | ||
|
|
||
| **For example:** | ||
| - When you ask to "debug this error," AutoPilot switches to a model optimized for debugging | ||
| - When you request "analyze the performance implications," it switches to a model better suited for complex reasoning | ||
| - When you're doing repetitive coding tasks, it uses a cost-effective model, but escalates to a more powerful one when it encounters failures | ||
|
|
||
| Switching happens automatically based on: | ||
| - The terminology used in your requests ("debug", "analyze", "implement") | ||
| - How complex the task appears to be | ||
| - Whether previous attempts have failed and need a different approach | ||
| - How much autonomous work has been happening without your input | ||
|
|
||
| When AutoPilot switches to a specialized model, it stays with that model for a configured number of <abbr title="A turn is one complete prompt-response interaction between goose and the LLM" style={{ textUnderlineOffset: "3px" }}>turns</abbr> before evaluating whether to switch back to the base model or to a different specialized model based on the new context. | ||
|
|
||
| :::info | ||
| You can use `goose session --debug` in goose CLI to see when AutoPilot switches models. Note that each switch applies the provider's rate limits and pricing. | ||
| ::: | ||
|
|
||
| ## Configuration | ||
|
|
||
| Add the `x-advanced-models` section to your [`config.yaml`](/docs/guides/config-file) file and map your model preferences to [predefined](#predefined-roles) or custom roles. | ||
|
|
||
| The `provider`, `model` and `role` parameters are required. | ||
|
|
||
| ```yaml | ||
| # Base provider and model (always available) | ||
| GOOSE_PROVIDER: "anthropic" | ||
| GOOSE_MODEL: "claude-sonnet-4-20250514" | ||
|
|
||
| # AutoPilot models | ||
| x-advanced-models: | ||
| - provider: openai | ||
| model: o1-preview | ||
| role: deep-thinker | ||
| - provider: openai | ||
| model: gpt-4o | ||
| role: debugger | ||
| - provider: anthropic | ||
| model: claude-opus-4-20250805 | ||
| role: reviewer | ||
| ``` | ||
|
|
||
| **Migrate From Lead/Worker Model** | ||
|
|
||
| This example shows how you can reproduce [lead model](/docs/tutorials/lead-worker) behavior using `x-advanced-models`. | ||
|
|
||
| ```yaml | ||
| # Before: Defined lead model using environment variables | ||
| # GOOSE_LEAD_PROVIDER=openai | ||
| # GOOSE_LEAD_MODEL=o1-preview | ||
|
|
||
| # After: AutoPilot equivalent | ||
| GOOSE_PROVIDER: "anthropic" | ||
| GOOSE_MODEL: "claude-sonnet-4-20250514" # Base is used as the worker model | ||
|
|
||
| x-advanced-models: | ||
| - provider: openai | ||
| model: o1-preview | ||
| role: lead # Use the predefined lead role (or define a custom role) | ||
| ``` | ||
|
|
||
| ### Predefined Roles | ||
|
|
||
| AutoPilot includes a set of predefined roles defined in [`premade_roles.yaml`](https://github.com/block/goose/blob/main/crates/goose/src/agents/model_selector/premade_roles.yaml) that goose is aware of by default. Examples include: | ||
|
|
||
| - **deep-thinker**: Activates for complex reasoning tasks | ||
| - **debugger**: Switches in for error resolution | ||
| - **reviewer**: Monitors after extensive tool usage | ||
| - **coder**: Handles code implementation tasks | ||
| - **mathematician**: Processes mathematical computations | ||
|
|
||
| ### Custom Roles | ||
|
|
||
| You can create custom roles with specific triggers by defining them in your `config.yaml` file: | ||
|
|
||
| ```yaml | ||
| x-advanced-models: | ||
| - provider: openai | ||
| model: gpt-4o | ||
| role: custom-debugger | ||
| rules: | ||
| triggers: | ||
| keywords: ["bug", "broken", "failing", "crash"] | ||
| consecutive_failures: 1 | ||
| active_turns: 5 | ||
| priority: 15 | ||
| ``` | ||
|
|
||
| <details> | ||
| <summary>Custom Role Configuration Fields</summary> | ||
|
|
||
| **Rule Configuration:** | ||
| | Parameter | Description | Values | | ||
| |-----------|-------------|---------| | ||
| | `triggers` | Conditions that activate the role | Object (see parameters below) | | ||
| | `active_turns` | Number of turns the rule stays active once triggered | Integer (default: 5) | | ||
| | `priority` | Selection priority when multiple roles match | Integer (higher wins, default: 0) | | ||
|
|
||
| **Trigger Parameters:** | ||
|
|
||
| | Parameter | Description | Values | | ||
| |-----------|-------------|---------| | ||
| | `keywords` | Words that activate the role | Array of strings | | ||
| | `match_type` | How to match keywords | "any", "all" | | ||
| | `complexity_threshold` | Minimum complexity level | "low", "medium", "high" | | ||
| | `consecutive_failures` | Failures in sequence | Integer | | ||
| | `first_turn` | Trigger on conversation start | Boolean | | ||
| | `source` | Message source filter | "human", "machine", "any" | | ||
|
|
||
| The previous table includes several common rule trigger parameters. For the complete list, see the `TriggerRules` struct in [`autopilot.rs`](https://github.com/block/goose/blob/main/crates/goose/src/agents/model_selector/autopilot.rs). | ||
|
|
||
| </details> | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,58 @@ | ||
| --- | ||
| title: Multi-Model Configuration | ||
| hide_title: true | ||
| description: Approaches for configuring model-switching behavior to optimize for cost, performance, and results. | ||
| --- | ||
|
|
||
| import Card from '@site/src/components/Card'; | ||
| import styles from '@site/src/components/Card/styles.module.css'; | ||
| import Tabs from '@theme/Tabs'; | ||
| import TabItem from '@theme/TabItem'; | ||
|
|
||
| <h1 className={styles.pageTitle}>Multi-Model Configuration</h1> | ||
| <p className={styles.pageDescription}> | ||
| goose supports several approaches for using different models within a single session, allowing you to optimize for cost, performance, and task specialization. Strategies range from manual or turn-based model selection to dynamic, context-aware switching. | ||
| </p> | ||
|
|
||
| <div className={styles.categorySection}> | ||
| <h2 className={styles.categoryTitle}>📚 Documentation & Guides</h2> | ||
| <div className={styles.cardGrid}> | ||
| <Card | ||
| title="Automatic Multi-Model Switching" | ||
| description="Intelligent switching between models based on conversation content, complexity, and tool usage patterns." | ||
| link="/docs/guides/multi-model/autopilot" | ||
| /> | ||
| <Card | ||
| title="Lead/Worker Multi-Model Setup" | ||
| description="Automatic switching between models using a lead model for initial turns and a worker model for execution." | ||
| link="/docs/tutorials/lead-worker" | ||
| /> | ||
| <Card | ||
| title="Creating Plans Before Working" | ||
| description="Manual planning mode that uses a dedicated model to break complex projects into detailed, actionable steps." | ||
| link="/docs/guides/multi-model/creating-plans" | ||
| /> | ||
| <Card | ||
| title="Planning Complex Tasks" | ||
| description="Uses the Plan feature to transform a complex devcontainer setup into a systematic, executable roadmap." | ||
| link="/docs/tutorials/plan-feature-devcontainer-setup" | ||
| /> | ||
| </div> | ||
| </div> | ||
|
|
||
| <div className={styles.categorySection}> | ||
| <h2 className={styles.categoryTitle}>📝 Featured Blog Posts</h2> | ||
| <div className={styles.cardGrid}> | ||
| <Card | ||
| title="Treating LLMs Like Tools in a Toolbox: A Multi-Model Approach to Smarter AI Agents" | ||
| description="LLMs are specialized tools, and multi-model approaches create smarter, more efficient AI agents." | ||
| link="/blog/2025/06/16/multi-model-in-goose" | ||
| /> | ||
| <Card | ||
| title="LLM Tag Team: Who Plans, Who Executes?" | ||
| description="Learn how lead/worker model configuration creates an effective AI tag team, with one model for planning and another for execution." | ||
| link="/blog/2025/08/11/llm-tag-team-lead-worker-model" | ||
| /> | ||
| </div> | ||
| </div> | ||
|
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.