> ## Documentation Index
> Fetch the complete documentation index at: https://docs.guild.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# guild.yaml reference

> Declare the integrations, sub-agents, built-in tools, models, and runtime environment for Goose, Native, OpenClaw, and LangGraph agents.

`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](/guide/goose-agents) | [Native](/guide/native-agents) | [OpenClaw](/guide/openclaw-agents) | [LangGraph](/guide/langgraph-agents) |
| - | - | - | - | - |
| [`integrations`](#integrations) | Yes | Yes | Yes | Yes |
| [`sub_agents`](#sub_agents) | Yes | Yes | Yes | Yes |
| [`builtins`](#builtins) | Yes | Yes | Yes | Yes |
| [`models`](#models) | Yes | Yes | Yes | Yes |
| [`environment`](#environment) | Yes | No | No | No |

TypeScript agents don't use `guild.yaml`. They declare tools in code. See [Tools](/sdk/tools).

## Example

```yaml theme={null}
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](/platform/llm-settings#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.

```yaml theme={null}
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:

```yaml theme={null}
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`.

<Warning>
  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.
</Warning>

## `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](/platform/environments), 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`](#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](/guide/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](#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.