Goose agents

A Goose agent is defined by a recipe.yaml file in the Goose recipe format. Instead of writing TypeScript, you describe the agent’s instructions, parameters, and response schema in YAML. Guild validates the recipe at build time and runs it as a headless agent. Use this agent type when you already have a Goose recipe or want to define agent behavior in a portable, declarative YAML format without writing code.

Create a Goose agent

guild agent init --name my-goose-agent --agent-type goose

Replace the template recipe.yaml file with your Goose recipe, then save and run the agent like you would any other Guild agent.

Open Agents in the left nav, click Your agents, then click Create Agent.
Under Or start another way, choose Start with code.
Choose Goose Agent.
Replace the template recipe.yaml with your Goose recipe.

The online editor provides built-in JSON Schema validation, autocompletion, and descriptive hover tooltips when editing recipe.yaml, guild.yaml, and package.json files to help you write valid configurations.

Recipe file

Place recipe.yaml at the root of the agent’s version files. It must be valid YAML with a mapping at the document root.

description: Review code with a configurable focus
instructions: You are a {{ language }} reviewer focused on {{ focus }}.
prompt: Review the code provided below.
parameters:
  - key: language
    input_type: select
    requirement: required
    description: Language under review
    options: [python, typescript]
  - key: focus
    input_type: string
    requirement: optional
    default: best practices
    description: Review focus area

Recipe fields

Guild honors a subset of Goose recipe fields. Fields that Guild cannot honor are rejected at build time with an explicit error rather than silently ignored — a recipe author who declares an extension expects the agent to have it, and running without it would produce confusing behavior.

Field	Treatment
`description`	Honored — required. Persisted as the version and agent description.
`instructions`	Honored — rendered and sent to the agent as its system prompt.
`prompt`	Honored — rendered, used as the default initial message.
`parameters`	Honored — drives the input schema and template rendering.
`response`	Honored — `json_schema` becomes the output schema.
`title`	Ignored — validated as a string if present; Guild uses the agent name.
`version`	Ignored
`author`	Ignored
`activities`	Ignored — desktop-only in Goose.
`extensions`	Rejected — Guild does not honor recipe extensions.
`settings`	Rejected — provider and model are platform-controlled.
`sub_recipes`	Rejected — not supported.
`retry`	Rejected — not supported.
Any unknown field	Rejected — catches typos and unreviewed future fields.

At least one of instructions or prompt must be present.

Parameters

parameters is a list of mappings. Each entry defines one input variable available in the template.

Field	Rule
`key`	Required. Must match `^[a-zA-Z_][a-zA-Z0-9_]*$`. Must be unique across the list.
`input_type`	Required. One of `string`, `number`, `boolean`, `date`, `select`. `file` is not supported.
`requirement`	Required. One of `required`, `optional`, `user_prompt`.
`description`	Required, non-empty string. Shown in the generated input form.
`default`	Required for `optional` parameters; forbidden for `required` and `user_prompt` parameters.
`options`	Required non-empty list of unique strings for `select`; forbidden for other types.

`user_prompt` parameters

Parameters with requirement: user_prompt are treated as required on Guild. In Goose, these prompt the user interactively when missing. On Guild, the input form serves the same role — callers must supply them.

Default coercion

Recipe defaults may be written typed (default: 10) or as strings (default: "10"). Guild coerces the value to the declared type:

number — integer, float, or numeric string
boolean — YAML boolean or "true"/"false" (case-insensitive)
date — ISO YYYY-MM-DD string
select — must be one of options
string — any scalar

A non-coercible default is a build error.

Template variables

instructions and prompt are Jinja-style templates. Parameters are available as template variables. Validation rules:

Templates must be syntactically valid.
Every variable referenced in a template must be a declared parameter.
Every declared parameter must appear in at least one template.
{{ recipe_dir }} is not available — Guild’s execution model has no recipe directory.

Templates render in a sandbox. Template expressions cannot access the host environment.

Input schema

Guild derives the agent’s input schema from the recipe’s parameters. The schema is JSON Schema Draft 2020-12. The top-level shape is:

{ "text": "...", "parameters": { "<key>": "<value>", ... } }

`text`

text is always a string property in the schema.

Required when the recipe has no prompt — callers must provide a message.
Optional when the recipe has a prompt. Description: "Optional message appended after the recipe's default prompt."

`parameters` object

parameters is included when the recipe declares at least one parameter. Parameters with requirement: required or requirement: user_prompt appear in the required array. The parameters object itself is required at the top level when its required array is non-empty.

Type mapping

`input_type`	JSON Schema property
`string`	`{"type": "string"}`
`number`	`{"type": "number"}`
`boolean`	`{"type": "boolean"}`
`date`	`{"type": "string", "format": "date"}`
`select`	`{"type": "string", "enum": [<options>]}`

Each property carries the parameter’s description. Optional parameters carry their coerced default.

Example

The recipe above produces:

{
  "type": "object",
  "properties": {
    "text": {
      "type": "string",
      "description": "Optional message appended after the recipe's default prompt."
    },
    "parameters": {
      "type": "object",
      "properties": {
        "language": {
          "type": "string",
          "enum": ["python", "typescript"],
          "description": "Language under review"
        },
        "focus": {
          "type": "string",
          "default": "best practices",
          "description": "Review focus area"
        }
      },
      "required": ["language"],
      "additionalProperties": false
    }
  },
  "required": ["parameters"],
  "additionalProperties": false
}

If the recipe had no prompt field, text would also appear in the top-level required array.

Test an agent with parameters

The Test view in the online editor runs your agent against input you supply. When an agent defines parameters, the Test box expects a { text, parameters } JSON payload instead of a plain message — a shape that is easy to miss. To make it discoverable, the editor shows a This agent takes parameters callout in the Test view whenever the agent’s input schema declares parameters. The callout holds a ready-to-copy JSON starting point built from the agent’s real parameter keys. Each key is prefilled with its default value when it has one, the first option for a select parameter, or a typed placeholder otherwise ("" for strings, 0 for numbers, false for booleans). Copy the template, fill in your values, and send it to start the test session. For the recipe above, the callout shows:

{
  "text": "",
  "parameters": {
    "language": "python",
    "focus": "best practices"
  }
}

Output schema

When response.json_schema is present, it is persisted verbatim as the agent’s output schema. When absent, the output schema defaults to the canonical text shape, so the agent’s final answer behaves like a prompt-driven agent’s text output:

{
  "type": "object",
  "properties": {
    "type": {"type": "string", "const": "text"},
    "text": {"type": "string"}
  },
  "required": ["type", "text"],
  "additionalProperties": false
}

Runtime behavior

At task start, the recipe is re-read from the version’s files and the input is applied as follows:

Parameter values — declared defaults, overridden by values in input.parameters.
Template rendering — instructions and prompt are rendered with the resolved parameter values.
System prompt — the rendered instructions, when present.
Initial message:
- Recipe has no prompt → text is the initial message (the schema makes it required).
- Recipe has a prompt, no text given → the rendered prompt.
- Both present → the rendered prompt, then text, joined by a blank line.
Workspace context — when present, prepended to the recipe’s prompt at task start, wrapped in a {% raw %} block so it is not treated as a template. The resulting prompt orders workspace context first, then the rendered recipe prompt, then text. Prepending the context inside the prompt carries it on every --resume turn, matching the native Goose runtime behavior.

Chat input

Chat-originated input arrives as {"type": "text", "text": "..."}. When the agent’s schema includes a top-level text string property, that input maps to {"text": "<text>"}. A bare chat message can only start a Goose agent whose schema does not require parameters. Structured input from a parent agent is validated against the Goose agent’s input schema before any wrapping. When the input already conforms to the schema, it passes through unchanged, so a parent agent can send structured parameters directly. Only input that does not conform to the schema is wrapped as canonical text {"type": "text", "text": "<serialized input>"}.

Integrations and sub-agents (`guild.yaml`)

A Goose agent often needs to act on external systems, delegate work to other agents, or call built-in platform tools. Declare these dependencies in an optional guild.yaml file placed at the root of the agent’s version files, alongside recipe.yaml. Each integration operation, sub-agent, and built-in tool you declare becomes a tool the agent can call. Omit guild.yaml when the agent needs no external integrations, sub-agents, or built-in tools.

environment: acme~python-3.12

models:
  - provider: anthropic
    model: claude-sonnet-5
  - provider: openai
    model: gpt-5

integrations:
  - name: acme~github
    version: ^1.4.0
    tools: [github_repos_get, github_issues_list]

sub_agents:
  - name: acme~research
    version: ^1.0.0

builtins:
  - name: console
    tools: [console_log]
  - name: ui
    tools: [ui_prompt]
  - name: guild

Environment field

environment is an optional top-level field that pins the agent to a runtime environment, written as "<owner>~<name>" (for example, acme~python-3.12). When omitted, the agent runs in the standard goosebox image.

Models field

models is an optional top-level field that declares the fallback runtime models the agent runs on, as an ordered list of LLM providers and models. Guild loads these declared models when it resolves the LLM for a task, tries each entry in order, and uses the first one the account’s model policies allow. When the agent’s code passes its own LLM preferences for a call, those preferences win and Guild does not read models; the declared models apply only as the fallback for agents that pass no preferences of their own. When omitted, the agent uses the account’s default LLM configuration.

models:
  - provider: anthropic
    model: claude-sonnet-5
  - provider: openai
    model: gpt-5
  - provider: anthropic
    model: claude-haiku-4-5

Omit model for an entry to accept any model from that provider and let the server choose one:

models:
  - provider: anthropic

Each entry under models accepts the following fields.

Field	Rule
`provider`	Required. The LLM provider. One of `anthropic`, `openai`, `gemini`, `meta`, or `fake`.
`model`	Optional. A specific model from the provider. When omitted, any model from that provider is accepted.

Integration fields

Each entry under integrations declares one integration dependency.

Field	Rule
`name`	Required. The integration identifier, such as `acme~github`.
`version`	Required. A semver range, such as `^1.4.0`, that must resolve to a published version.
`tools`	Optional. A list of operations to expose as tools. When omitted, all operations of the resolved integration version are made available.

Selecting integration tools in the editor

The web agent editor lets you pick which of an integration’s tools to expose, rather than importing every operation. Keeping the list short helps an agent stay under the tool limits models impose, which a full integration can exceed on its own. The Integrations section opens one dialog, Integrations and tools, for both browsing and configuration:

Active integrations appear as tabs on the left.
The selected integration’s tools appear as a checklist on the right. Check a tool to expose it, uncheck it to remove it.
The Add integration tab turns the panel into a browsable catalog.

Each selected tool is written to guild.yaml as {service}_{operation} in snake case — for example, github_repos_get.

An integration cannot be left with no tools selected. An empty tools: [] list means all of the integration’s tools, so it cannot express “none” — deselecting everything warns that the integration will be dropped from the agent unless you pick at least one.

Sub-agent fields

Each entry under sub_agents declares one sub-agent dependency.

Field	Rule
`name`	Required. The sub-agent identifier, such as `acme~research`.
`version`	Required. A semver range, such as `^1.0.0`, that must resolve to a published version.

Builtin fields

Each entry under builtins exposes a platform service’s curated tools to the agent.

Field	Rule
`name`	Required. The platform service to expose. One of `console`, `ui`, or `guild`.
`tools`	Optional. A list of the service’s tools to expose. When omitted, all curated tools for that service are included.

The supported services and their tools are:

Service	Tool	Behavior
`console`	`console_log`	Logs a message to the debug console. Does not suspend the task.
`ui`	`ui_prompt`	Prompts the user for additional information or clarification. Suspends the task.
`guild`	`guild_credentials_request`	Requests that the user configure credentials for a specific integration. Suspends the task.

Omitting tools for a service — for example, - name: guild — imports all of that service’s permitted built-in tools.

Validation rules

Guild validates guild.yaml at build time, alongside recipe.yaml.

Version resolution — the version range for each integration and sub-agent must resolve to a published version. A range that resolves to no published version is a build error.
Tool verification — when tools is specified for an integration, each listed tool must carry the integration’s service prefix (for example, github_) and map to a real operation on the resolved integration version. A tool that does not match an available operation is a build error. When tools is omitted, all operations of the resolved integration version are available.
Built-in tools — each name under builtins must be a supported service (console, ui, or guild), and each tool listed under tools must be a permitted tool for that service. An unsupported service or tool is a build error. When tools is omitted, all of the service’s curated tools are included.
Access and permissions — a public agent cannot depend on a private integration or a private sub-agent, and a sub-agent cannot be archived. See Versions for the full dependency visibility rules.
Runtime environment — when environment is set, the referenced runtime environment must exist and must be public or owned by the agent’s owner. A public agent cannot depend on a private environment.
Supported sections — each top-level section must be one the agent type supports. Goose agents support environment, but Native, OpenClaw, and LangChain agents do not. Declaring a section the agent type does not support is a build error rather than being silently ignored.
Unique tool names — the resolved tool names must not collide. A duplicate name across integrations, sub-agents, and builtins is a build error.
Models — when models is set, each entry must name a supported provider (anthropic, openai, gemini, meta, or fake). An unsupported provider is a build error.

Build-time validation

Guild validates the full recipe when you publish a version. All validation errors are reported together — not fail-fast. On success, three values are persisted on the agent version: description, input_schema, and output_schema.

instructions, prompt, and parameters are not persisted on the version — the recipe file is their single source of truth. Because versions are immutable, a recipe that validated at build time parses identically at task start.

Overview

The Smith

The Factory

Platform

Agent SDK

Goose agents

Create a Goose agent

Recipe file

Recipe fields

Parameters

`user_prompt` parameters

Default coercion

Template variables

Input schema

`text`

`parameters` object

Type mapping

Example

Test an agent with parameters

Output schema

Runtime behavior

Chat input

Integrations and sub-agents (`guild.yaml`)

Environment field

Models field

Integration fields

Selecting integration tools in the editor

Sub-agent fields

Builtin fields

Validation rules

Build-time validation

​Create a Goose agent

​Recipe file

​Recipe fields

​Parameters

​user_prompt parameters

​Default coercion

​Template variables

​Input schema

​text

​parameters object

​Type mapping

​Example

​Test an agent with parameters

​Output schema

​Runtime behavior

​Chat input

​Integrations and sub-agents (guild.yaml)

​Environment field

​Models field

​Integration fields

​Selecting integration tools in the editor

​Sub-agent fields

​Builtin fields

​Validation rules

​Build-time validation

Create a Goose agent

Recipe file

Recipe fields

Parameters

`user_prompt` parameters

Default coercion

Template variables

Input schema

`text`

`parameters` object

Type mapping

Example

Test an agent with parameters

Output schema

Runtime behavior

Chat input

Integrations and sub-agents (`guild.yaml`)

Environment field

Models field

Integration fields

Selecting integration tools in the editor

Sub-agent fields

Builtin fields

Validation rules

Build-time validation