guild.yaml reference

guild.yaml declares what Guild brokers for an agent: the integrations, sub-agents, and built-in tools it can call, the models it prefers, and, for Goose agents, the runtime environment it runs in. Each integration operation, sub-agent, and built-in tool you declare becomes a tool the agent can call. Place guild.yaml at the root of the agent’s version files, next to the agent type’s entry point. It’s optional: omit it when the agent needs none of these. Guild validates it at build time.

Supported sections

Each agent type accepts a different set of sections. Declaring a section the agent type doesn’t support is a build error.

Section	Goose	Native	OpenClaw	LangGraph
`integrations`	Yes	Yes	Yes	Yes
`sub_agents`	Yes	Yes	Yes	Yes
`builtins`	Yes	Yes	Yes	Yes
`models`	Yes	Yes	Yes	Yes
`environment`	Yes	No	No	No

TypeScript agents don’t use guild.yaml. They declare tools in code. See Tools.

Example

environment: acme~python-3.12   # Goose agents only

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

`models`

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 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

Declare at most 16 entries. Each entry accepts the following fields.

Field	Rule
`provider`	Required. The LLM provider: `anthropic`, `openai`, `gemini`, `meta`, `deepseek`, `alibaba`, `moonshot`, or `zai`. Case-insensitive.
`model`	Optional. A specific model from the provider. When omitted, any model from that provider is accepted.

`integrations`

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_agents`

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.

`builtins`

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

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

Which built-in tools an agent can use depends on its type:

Service	Tool	Behavior	Goose, OpenClaw, LangGraph	Native
`console`	`console_log`	Logs a message to the debug console. Doesn’t suspend the task.	Yes	No
`ui`	`ui_prompt`	Asks the user for more information. Suspends the task until they answer.	Yes	Yes
`ui`	`ui_progress`	Posts a progress update without pausing the run.	No	Yes
`guild`	`guild_credentials_request`	Asks the user to connect credentials for an integration. Suspends the task.	Yes	No

Declaring a service or tool the agent type doesn’t support is a build error. Omitting tools for a service, as in - name: guild, imports all of that service’s tools the agent type supports.

`environment`

Goose agents only. environment pins the agent to a runtime environment, written as "<owner>~<name>", such as acme~python-3.12. When omitted, the agent runs in the default guildai~goosebox image.

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 service the agent type supports, and each tool listed under tools must be one of that service’s tools for the agent type. See builtins.
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 — for Goose agents, 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. See Supported sections. Declaring a section the agent type doesn’t 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, deepseek, alibaba, moonshot, or zai), and there can be at most 16 entries. Anything else is a build error.

Overview

The Smith

The Factory

Platform

Agent SDK

guild.yaml reference

Supported sections

Example

`models`

`integrations`

Selecting integration tools in the editor

`sub_agents`

`builtins`

`environment`

Validation rules

​Supported sections

​Example

​models

​integrations

​Selecting integration tools in the editor

​sub_agents

​builtins

​environment

​Validation rules

Supported sections

Example

`models`

`integrations`

Selecting integration tools in the editor

`sub_agents`

`builtins`

`environment`

Validation rules