recipe

Documentation

Overview

Package recipe provides a declarative way to define and share Agent configurations. Inspired by Goose's Recipe system, it allows users to create reusable Agent templates with pre-configured tools, prompts, and behaviors.

Index

• type Author
• type Builder
  • func NewBuilder() *Builder
  • func (b *Builder) AddExtension(ext ExtensionConfig) *Builder
  • func (b *Builder) AddParameter(param Parameter) *Builder
  • func (b *Builder) Build() (*Recipe, error)
  • func (b *Builder) Description(desc string) *Builder
  • func (b *Builder) Instructions(instructions string) *Builder
  • func (b *Builder) PermissionMode(mode PermissionMode) *Builder
  • func (b *Builder) Prompt(prompt string) *Builder
  • func (b *Builder) Title(title string) *Builder
  • func (b *Builder) Tools(tools ...string) *Builder
• type ExtensionConfig
  • func (e *ExtensionConfig) IsEnabled() bool
  • func (e *ExtensionConfig) Validate() error
• type Parameter
  • func (p *Parameter) Validate() error
• type ParameterRequirement
• type ParameterType
• type PermissionMode
• type Recipe
  • func ListRecipes(dir string) ([]*Recipe, error)
  • func LoadFromBytes(data []byte) (*Recipe, error)
  • func LoadFromFile(path string) (*Recipe, error)
  • func (r *Recipe) ApplyParameters(values map[string]string) error
  • func (r *Recipe) ToYAML() ([]byte, error)
  • func (r *Recipe) Validate() error
• type Settings

Types

type Author

type Author struct {
	// Name of the author
	Name string `yaml:"name,omitempty" json:"name,omitempty"`

	// Contact information (email, URL, etc.)
	Contact string `yaml:"contact,omitempty" json:"contact,omitempty"`

	// URL to author's website or profile
	URL string `yaml:"url,omitempty" json:"url,omitempty"`
}

Author contains creator information.

type Builder

type Builder struct {
	// contains filtered or unexported fields
}

Builder provides a fluent API for creating recipes.

func NewBuilder

func NewBuilder() *Builder

NewBuilder creates a new recipe builder.

func (*Builder) AddExtension

func (b *Builder) AddExtension(ext ExtensionConfig) *Builder

AddExtension adds an MCP extension.

func (*Builder) AddParameter

func (b *Builder) AddParameter(param Parameter) *Builder

AddParameter adds a configurable parameter.

func (*Builder) Build

func (b *Builder) Build() (*Recipe, error)

Build creates the recipe.

func (*Builder) Description

func (b *Builder) Description(desc string) *Builder

Description sets the recipe description.

func (*Builder) Instructions

func (b *Builder) Instructions(instructions string) *Builder

Instructions sets the system instructions.

func (*Builder) PermissionMode

func (b *Builder) PermissionMode(mode PermissionMode) *Builder

PermissionMode sets the permission mode.

func (*Builder) Prompt

func (b *Builder) Prompt(prompt string) *Builder

Prompt sets the initial prompt.

func (*Builder) Title

func (b *Builder) Title(title string) *Builder

Title sets the recipe title.

func (*Builder) Tools

func (b *Builder) Tools(tools ...string) *Builder

Tools sets the enabled tools.

type ExtensionConfig

type ExtensionConfig struct {
	// Type is the extension type: "stdio", "sse", "builtin"
	Type string `yaml:"type" json:"type"`

	// Name is the unique identifier for this extension
	Name string `yaml:"name" json:"name"`

	// Description of what this extension does
	Description string `yaml:"description,omitempty" json:"description,omitempty"`

	// Cmd is the command to run (for stdio type)
	Cmd string `yaml:"cmd,omitempty" json:"cmd,omitempty"`

	// Args are command arguments (for stdio type)
	Args []string `yaml:"args,omitempty" json:"args,omitempty"`

	// URL is the server URL (for sse type)
	URL string `yaml:"url,omitempty" json:"url,omitempty"`

	// Env are environment variables to set
	Env map[string]string `yaml:"env,omitempty" json:"env,omitempty"`

	// Timeout in seconds
	Timeout int `yaml:"timeout,omitempty" json:"timeout,omitempty"`

	// Enabled indicates if this extension should be loaded
	Enabled *bool `yaml:"enabled,omitempty" json:"enabled,omitempty"`
}

ExtensionConfig defines an MCP extension.

func (*ExtensionConfig) IsEnabled

func (e *ExtensionConfig) IsEnabled() bool

IsEnabled returns whether the extension is enabled (default true).

func (*ExtensionConfig) Validate

func (e *ExtensionConfig) Validate() error

Validate checks if the extension is valid.

type Parameter

type Parameter struct {
	// Key is the parameter name
	Key string `yaml:"key" json:"key"`

	// Type is the input type: "string", "number", "boolean", "select", "file"
	Type ParameterType `yaml:"input_type" json:"input_type"`

	// Requirement specifies if the parameter is required
	Requirement ParameterRequirement `yaml:"requirement" json:"requirement"`

	// Description explains what this parameter does
	Description string `yaml:"description" json:"description"`

	// Default value (not allowed for file type)
	Default string `yaml:"default,omitempty" json:"default,omitempty"`

	// Options for select type
	Options []string `yaml:"options,omitempty" json:"options,omitempty"`
}

Parameter defines a configurable parameter.

func (*Parameter) Validate

func (p *Parameter) Validate() error

Validate checks if the parameter is valid.

type ParameterRequirement

type ParameterRequirement string

ParameterRequirement specifies if a parameter is required.

const (
	ParamRequired   ParameterRequirement = "required"
	ParamOptional   ParameterRequirement = "optional"
	ParamUserPrompt ParameterRequirement = "user_prompt"
)

type ParameterType

type ParameterType string

ParameterType represents the input type of a parameter.

const (
	ParamTypeString  ParameterType = "string"
	ParamTypeNumber  ParameterType = "number"
	ParamTypeBoolean ParameterType = "boolean"
	ParamTypeSelect  ParameterType = "select"
	ParamTypeFile    ParameterType = "file"
	ParamTypeDate    ParameterType = "date"
)

type PermissionMode

type PermissionMode string

PermissionMode controls tool approval behavior.

const (
	// PermissionAutoApprove automatically approves all tool calls
	PermissionAutoApprove PermissionMode = "auto_approve"

	// PermissionSmartApprove auto-approves read-only tools, asks for others
	PermissionSmartApprove PermissionMode = "smart_approve"

	// PermissionAlwaysAsk always asks for user confirmation
	PermissionAlwaysAsk PermissionMode = "always_ask"
)

type Recipe

type Recipe struct {
	// Version of the recipe format (semver)
	Version string `yaml:"version" json:"version"`

	// Title is a short name for the recipe
	Title string `yaml:"title" json:"title"`

	// Description explains what this recipe does
	Description string `yaml:"description" json:"description"`

	// TemplateID references an existing template from appconfig
	// If empty, uses the default template
	TemplateID string `yaml:"template_id,omitempty" json:"template_id,omitempty"`

	// Instructions override or extend the system prompt
	Instructions string `yaml:"instructions,omitempty" json:"instructions,omitempty"`

	// Prompt is the initial message to send to the agent
	Prompt string `yaml:"prompt,omitempty" json:"prompt,omitempty"`

	// Tools is a list of tool names to enable
	Tools []string `yaml:"tools,omitempty" json:"tools,omitempty"`

	// Extensions defines MCP extensions to load
	Extensions []ExtensionConfig `yaml:"extensions,omitempty" json:"extensions,omitempty"`

	// Parameters defines user-configurable parameters
	Parameters []Parameter `yaml:"parameters,omitempty" json:"parameters,omitempty"`

	// Settings contains runtime settings
	Settings *Settings `yaml:"settings,omitempty" json:"settings,omitempty"`

	// Author information
	Author *Author `yaml:"author,omitempty" json:"author,omitempty"`

	// Activities are suggested prompts shown in UI
	Activities []string `yaml:"activities,omitempty" json:"activities,omitempty"`

	// PermissionMode controls tool approval behavior
	PermissionMode PermissionMode `yaml:"permission_mode,omitempty" json:"permission_mode,omitempty"`
}

Recipe defines a reusable Agent configuration.

func ListRecipes

func ListRecipes(dir string) ([]*Recipe, error)

ListRecipes returns all recipes in the given directory.

func LoadFromBytes

func LoadFromBytes(data []byte) (*Recipe, error)

LoadFromBytes parses a recipe from YAML bytes.

func LoadFromFile

func LoadFromFile(path string) (*Recipe, error)

LoadFromFile loads a recipe from a YAML file.

func (*Recipe) ApplyParameters

func (r *Recipe) ApplyParameters(values map[string]string) error

ApplyParameters substitutes parameter values in the recipe.

func (*Recipe) ToYAML

func (r *Recipe) ToYAML() ([]byte, error)

ToYAML serializes the recipe to YAML.

func (*Recipe) Validate

func (r *Recipe) Validate() error

Validate checks if the recipe is valid.

type Settings

type Settings struct {
	// Provider name (e.g., "anthropic", "openai")
	Provider string `yaml:"provider,omitempty" json:"provider,omitempty"`

	// Model name
	Model string `yaml:"model,omitempty" json:"model,omitempty"`

	// Temperature for generation
	Temperature *float32 `yaml:"temperature,omitempty" json:"temperature,omitempty"`

	// MaxTokens limits output length
	MaxTokens *int `yaml:"max_tokens,omitempty" json:"max_tokens,omitempty"`
}

Settings contains runtime configuration.