tkmind/tkmind_go
1
0
Fork 0
Code Issues Pull Requests Actions 5 Packages Projects Releases Wiki Activity

docs: recipe updates (#3844)

Browse Source
This commit is contained in:
dianed-square
2025-08-06 13:18:36 -07:00
committed by GitHub
parent bb26521471
commit b52112c197
6 changed files with 456 additions and 9 deletions
Download Patch File Download Diff File Expand all files Collapse all files
documentation/docs/guides/recipes/index.md
+5
View File
@@ -52,6 +52,11 @@ import styles from '@site/src/components/Card/styles.module.css';
description="Learn how to save, organize, and find your Goose recipes for easy access and reuse."
link="/docs/guides/recipes/storing-recipes"
/>
<Card
title="Sub-Recipes In Parallel Tutorial"
description="Learn how to run multiple sub-recipes instances concurrently."
link="/docs/tutorials/sub-recipes-in-parallel"
/>
</div>
</div>
documentation/docs/guides/recipes/recipe-reference.md
+44 -2
View File
@@ -140,6 +140,7 @@ The `extensions` field allows you to specify which Model Context Protocol (MCP)
| `name` | String | Unique name for the extension |
| `cmd` | String | Command to run the extension |
| `args` | Array | List of arguments for the command |
| `env_keys` | Array | (Optional) Names of environment variables required by the extension |
| `timeout` | Number | Timeout in seconds |
| `bundled` | Boolean | (Optional) Whether the extension is bundled with Goose |
| `description` | String | Description of what the extension does |
@@ -163,9 +164,35 @@ extensions:
cmd: uvx
args:
- 'mcp_presidio@latest'
description: "For searching logs using Presidio"
- type: stdio
name: github-mcp
cmd: github-mcp-server
args: []
env_keys:
- GITHUB_PERSONAL_ACCESS_TOKEN
timeout: 60
description: "GitHub MCP extension for repository operations"
```
### Extension Secrets
This feature is only available through the CLI.
If a recipe uses an extension that requires a secret, Goose can prompt users to provide the secret when running the recipe:
1. When a recipe is loaded, Goose scans all extensions (including those in sub-recipes) for `env_keys` fields
2. If any required environment variables are missing from the secure keyring, Goose prompts the user to enter them
3. Values are stored securely in the system keyring and reused for subsequent runs
To update a stored secret, remove it from the system keyring and run the recipe again to be re-prompted.
:::info
This feature is designed to prompt for and securely store secrets (such as API keys), but `env_keys` can include any environment variable needed by the extension (such as API endpoints, configuration values, etc.).
Users can press `ESC` to skip entering a variable if it's optional for the extension.
:::
## Settings
The `settings` field allows you to configure the AI model and provider settings for the recipe. This overrides the default configuration when the recipe is executed.
@@ -209,6 +236,7 @@ The `sub_recipes` field specifies the [sub-recipes](/docs/guides/recipes/sub-rec
| `name` | String | Unique identifier for the sub-recipe |
| `path` | String | Relative or absolute path to the sub-recipe file |
| `values` | Object | (Optional) Pre-configured parameter values that are passed to the sub-recipe |
| `sequential_when_repeated` | Boolean | (Optional) Forces sequential execution of multiple sub-recipe instances. See [Running Sub-Recipes In Parallel](/docs/tutorials/sub-recipes-in-parallel) for details |
### Example Sub-Recipe Configuration
@@ -312,7 +340,7 @@ The `response` field enables recipes to enforce a final structured JSON output f
1. **Validate the output**: Validates the output JSON against your JSON schema with basic JSON schema validations
2. **Final structured output**: Ensure the final output of the agent is a response matching your JSON structure
This **enables automation** by returning consistent, parseable results for scripts and workflows. Recipes can produce structured output when run from either the Goose CLI or Goose Desktop.
This **enables automation** by returning consistent, parseable results for scripts and workflows. Recipes can produce structured output when run from either the Goose CLI or Goose Desktop. See [use cases and ideas for automation workflows](/docs/guides/recipes/session-recipes#structured-output-for-automation).
### Basic Structure
@@ -370,6 +398,20 @@ Advanced template features include:
Default content
{% endblock %}
```
- `indent()` template filter
### indent() Filter For Multi-Line Values
Use the `indent()` filter to ensure multi-line parameter values are properly indented and can be resolved as valid JSON or YAML format. This example uses `{{ raw_data | indent(2) }}` to specify an indentation of two spaces when passing data to a sub-recipe:
```yaml
sub_recipes:
- name: "analyze"
path: "./analyze.yaml"
values:
content: |
{{ raw_data | indent(2) }}
```
## Built-in Parameters
documentation/docs/guides/recipes/session-recipes.md
+66 -1
View File
@@ -413,10 +413,11 @@ You can turn your current Goose session into a reusable recipe that includes the
</TabItem>
</Tabs>
:::info Privacy & Isolation
:::info Privacy, Isolation, & Secrets
- Each person gets their own private session
- No data is shared between users
- Your session won't affect the original recipe creator's session
- The CLI can prompt users for required [extension secrets](/docs/guides/recipes/recipe-reference#extension-secrets)
:::
</TabItem>
@@ -568,6 +569,70 @@ retry:
See the [Recipe Reference Guide](/docs/guides/recipes/recipe-reference#automated-retry-with-success-validation) for complete retry configuration options and examples.
### Structured Output for Automation
Recipes can enforce [structured JSON output](/docs/guides/recipes/recipe-reference#structured-output-with-response), making them ideal for automation workflows that need to parse and process agent responses reliably. Key benefits include:
- **Reliable parsing**: Consistent JSON format for scripts, automation, and CI/CD pipelines
- **Built-in validation**: Ensures output matches your requirements
- **Easy extraction**: Final output appears as a single line for simple parsing
Structured output is particularly useful for:
- **Development workflows**: Code analysis reports, test results with pass/fail counts, and build status with deployment readiness
- **Data processing**: Results with counts and validation status, content analysis with structured findings
- **Documentation generation**: Consistent metadata and structured project reports for further processing
**Example structured output configuration:**
```yaml
response:
json_schema:
type: object
properties:
build_status:
type: string
enum: ["success", "failed", "warning"]
description: "Overall build result"
tests_passed:
type: number
description: "Number of tests that passed"
tests_failed:
type: number
description: "Number of tests that failed"
artifacts:
type: array
items:
type: string
description: "Generated build artifacts"
deployment_ready:
type: boolean
description: "Whether the build is ready for deployment"
required:
- build_status
- tests_passed
- tests_failed
- deployment_ready
```
**How it works:**
1. Recipe runs normally with provided instructions
2. Goose calls a `final_output` tool with JSON matching your schema
3. Output is validated against the JSON schema
4. If validation fails, Goose receives error details and must correct the output
5. Final validated JSON appears as the last line of output for easy extraction
**Example automation usage:**
```bash
# Run recipe and extract JSON output
goose run --recipe analysis.yaml --params project_path=./src > output.log
RESULT=$(tail -n 1 output.log)
echo "Analysis Status: $(echo $RESULT | jq -r '.build_status')"
echo "Issues Found: $(echo $RESULT | jq -r '.tests_failed')"
```
:::info
Structured output is supported in recipes run in both the Goose CLI and Goose Desktop. However, creating and editing the `json_schema` configuration must be done manually in the recipe file.
:::
## What's Included
A recipe captures:
documentation/docs/guides/recipes/sub-recipes.md
+124 -5
View File
@@ -9,6 +9,10 @@ Sub-recipes are recipes that are used by another recipe to perform specific task
- **Multi-step workflows** - Break complex tasks into distinct phases with specialized expertise
- **Reusable components** - Create common tasks that can be used in various workflows
:::warning Experimental Feature
Running sub-recipes in parallel is an experimental feature in active development. Behavior and configuration may change in future releases.
:::
## How Sub-Recipes Work
The "main recipe" registers its sub-recipes in the `sub_recipes` field, which contains the following fields:
@@ -26,15 +30,15 @@ Sub-recipe sessions run in isolation - they don't share conversation history, me
### Parameter Handling
Sub-recipes receive parameters in two ways:
Parameters received by sub-recipes can be used in prompts and instructions using `{{ parameter_name }}` syntax. Sub-recipes receive parameters in two ways:
1. **Pre-set values**: Fixed parameter values defined in the `values` field are automatically provided and cannot be overridden at runtime
2. **Automatic parameter inheritance**: Sub-recipes automatically have access to all parameters passed to the main recipe at runtime.
2. **Context-based parameters**: The AI agent can extract parameter values from the conversation context, including results from previous sub-recipes
Pre-set values take precedence over inherited parameters. If both the main recipe and `values` field provide the same parameter, the `values` version is used.
Pre-set values take precedence over context-based parameters. If both the conversation context and `values` field provide the same parameter, the `values` version is used.
:::info Template Variables
Parameters received by sub-recipes can be used in prompts and instructions using `{{ parameter_name }}` syntax.
:::tip
Use the `indent()` filter to maintain valid YAML format when passing multi-line parameter values to sub-recipes, for example: `{{ content | indent(2) }}`. See [Template Support](/docs/guides/recipes/recipe-reference#template-support) for more details.
:::
## Examples
@@ -151,6 +155,10 @@ prompt: |
```
</details>
:::tip
For faster execution when sub-recipes are independent, see [Running Sub-Recipes In Parallel](/docs/tutorials/sub-recipes-in-parallel) to execute multiple sub-recipes concurrently.
:::
### Conditional Processing
This Smart Project Analyzer example shows conditional logic that chooses between different sub-recipes based on analysis:
@@ -284,6 +292,117 @@ prompt: |
```
</details>
### Context-Based Parameter Passing
This Travel Planner example shows how sub-recipes can receive parameters from conversation context, including results from previous sub-recipes:
**Usage:**
```bash
goose run --recipe travel-planner.yaml
```
**Main Recipe:**
```yaml
# travel-planner.yaml
version: "1.0.0"
title: "Travel Activity Planner"
description: "Get weather data and suggest appropriate activities"
instructions: |
Plan activities by first getting weather data, then suggesting activities based on conditions.
prompt: |
Plan activities for Sydney by first getting weather data, then suggesting activities based on the weather conditions we receive.
sub_recipes:
- name: weather_data
path: "./sub-recipes/weather-data.yaml"
# No values - location parameter comes from prompt context
- name: activity_suggestions
path: "./sub-recipes/activity-suggestions.yaml"
# weather_conditions parameter comes from conversation context
extensions:
- type: builtin
name: developer
timeout: 300
bundled: true
```
**Sub-Recipes:**
<details>
<summary>weather_data</summary>
```yaml
# sub-recipes/weather-data.yaml
version: "1.0.0"
title: "Weather Data Collector"
description: "Fetch current weather conditions for a location"
instructions: |
You are a weather data specialist. Gather current weather information
including temperature, conditions, and seasonal context.
parameters:
- key: location
input_type: string
requirement: required
description: "City or location to get weather data for"
extensions:
- type: stdio
name: weather
cmd: uvx
args:
- mcp_weather@latest
timeout: 300
description: "Weather data for trip planning"
- type: builtin
name: developer
timeout: 300
bundled: true
prompt: |
Get the current weather conditions for {{ location }}.
Include temperature, weather conditions (sunny, rainy, etc.),
and any relevant seasonal information.
```
</details>
<details>
<summary>activity_suggestions</summary>
```yaml
# sub-recipes/activity-suggestions.yaml
version: "1.0.0"
title: "Activity Recommender"
description: "Suggest activities based on weather conditions"
instructions: |
You are a travel expert. Recommend appropriate activities and attractions
based on current weather conditions.
parameters:
- key: weather_conditions
input_type: string
requirement: required
description: "Current weather conditions to base recommendations on"
extensions:
- type: builtin
name: developer
timeout: 300
bundled: true
prompt: |
Based on these weather conditions: {{ weather_conditions }},
suggest appropriate activities, attractions, and travel tips.
Include both indoor and outdoor options as relevant.
```
</details>
In this example:
- The `weather_data` sub-recipe gets the location from the prompt context (the AI extracts "Sydney" from the natural language prompt)
- The `activity_suggestions` sub-recipe gets weather conditions from the conversation context (the AI uses the weather results from the first sub-recipe)
## Best Practices
- **Single responsibility**: Each sub-recipe should have one clear purpose
- **Clear parameters**: Use descriptive names and descriptions