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

> ## Agent Instructions
> To act on a user's behalf in Guild, use the Guild REST API at https://api.guild.ai/v1.
> The OpenAPI spec is unauthenticated: https://docs.guild.ai/openapi.json (or openapi.yaml).
> Authenticate with an account API key, sent as HTTP Basic (key id as username, secret as password) or as `Authorization: Bearer <api_key_id>:<api_key_secret>`. See https://docs.guild.ai/api-reference/introduction#authentication.
> To run one agent on demand without account-wide access, use an API trigger instead: https://docs.guild.ai/platform/api-triggers.
> To act on Guild from an MCP client, connect to https://api.guild.ai/mcp (OAuth) or run `guild mcp` locally. Setup: https://docs.guild.ai/api-reference/mcp.
> To search these docs from an MCP client, connect to https://docs.guild.ai/mcp. The full page index is https://docs.guild.ai/llms.txt.

# Workspace agents

> Add agents to a Guild workspace, see which credential each one uses, control automatic version upgrades, and remove agents you no longer need.

The **Agents** page lists the agents installed in a workspace. An installed agent is available to everyone in the workspace, and you can run it from chat or from [triggers](https://docs.guild.ai/platform/triggers.md). To build or publish agents, see [Your agents](https://docs.guild.ai/platform/agents.md).

Open the workspace and click **Agents** under **Setup**.

## The agents list

| Column | Description |
| - | - |
| **Agent** | The agent's name and owner. |
| **Version** | The installed version, or `-` if the agent has none. |
| **Binding** | The credentials bound to this agent in this workspace. See [Bindings](#bindings). |
| **Added By** | Who installed the agent here. |
| **Added** | When it was installed. |

Search the list by name, and sort it by **Newest**, **Oldest**, **Recently updated**, **Least recently updated**, **Name A-Z**, or **Name Z-A**. Select a row to open the agent's [detail page](#agent-detail-page).

### Bindings

A binding is a credential granted or dedicated to the agent. The column shows whether the agent has one of its own, not which credential a call resolves to when it has none.

| Binding | Meaning |
| - | - |
| ***app*: Granted · *owner*** | An existing credential shared with this agent, running as *owner*. |
| ***app*: Dedicated** | A credential that exists only for this agent. |
| **Organization pool (no binding)** | Nothing bound, so the agent falls through to member, workspace, and account credentials. |
| **Nothing yet. Grant or connect.** | Nothing bound, and the workspace [bars the account pool](https://docs.guild.ai/platform/workspace-credentials.md#restricting-the-account-pool). A call fails unless a member or workspace credential covers it. |

An agent bound for several apps lists one per line. To change bindings, use the [Credentials](https://docs.guild.ai/platform/workspace-credentials.md#which-identity-each-agent-will-use) page or the agent's [Integrations](#integrations) section.

### Row menu

Each row's menu offers:

* **Test agent**, **View agent**, **Edit agent (CLI)**, and **Fork agent**
* **Edit agent (UI)** and **Settings**, if you can edit the agent
* **Publish to Agent Hub**, if you can edit the agent and it isn't public yet. It's disabled until you commit a version, and in an organization it needs admin permission. See [Publish to the Agent Hub](https://docs.guild.ai/platform/publish-to-agent-hub.md).
* **View on Agent Hub**, for public agents
* **Remove from Workspace**. See [Remove an agent](#remove-an-agent).

## Add an agent

1. Click **Add Agent**.
2. Find the agent. The dialog has three tabs:
   * **All** — every published agent you can install.
   * **Organization** — your organization's agents. Shown only in organization-owned workspaces.
   * **Workspace** — the agents already installed here.
3. Click the add button on the agent's row.

Each row shows the agent's description, creator, and its like, fork, and install counts. Select a row to see its latest published versions before you add it. The same dialog removes agents: use the button on an installed agent's row.

An agent added from this dialog has **Autoupdate** on. To add one with **Autoupdate** off, use `guild workspace agent add <agent> --no-autoupdate`. See [`guild workspace`](https://docs.guild.ai/cli/commands/workspace).

## Agent detail page

The detail page shows how an agent is installed and governed in this workspace. **View agent** opens the agent's own page, outside the workspace.

### Overview

| Field | Description |
| - | - |
| **Workspace** | The workspace the agent is installed in. |
| **Owner** | The account that owns the agent. |
| **Current version** | The installed version, or **No version**. |
| **Version note** | The installed version's summary, when it has one. |
| **Added by** | Who installed the agent here. |
| **Added** | When it was installed. |

### Autoupdate

When **Autoupdate** is on, the workspace moves to each new version of the agent as soon as it's published. The next session runs that version's code with the workspace's context and credentials. The switch saves immediately.

Turn **Autoupdate** off to pin the installed version. The web UI doesn't offer a manual upgrade. To move a pinned agent to a specific version, call [Update an installed agent](https://docs.guild.ai/api-reference/workspaces/update-an-installed-agents-version-or-settings.md) with `new_version_id`, or turn **Autoupdate** back on to jump to the latest.

### Models

This section appears only when the account has its own LLM keys. It sets [model rules](https://docs.guild.ai/platform/llm-settings#model-policies) for this agent in this workspace, which is the most specific level a rule can have.

A badge shows which rules apply:

* **Inherited** — this level uses the rules of the level above it. The list is read-only. Click **Override** to copy those rules here, in order, and start editing them.
* **Overridden** — this level sets its own rules, which replace the inherited ones entirely. Click **Reset to inherited** to drop them. Reset can't be undone.

If the account default changes after you override, the status reads **The account default changed -- these rules still apply.** Click **View account default** to compare.

**Manage LLM settings** opens the account's [Models & providers](https://docs.guild.ai/platform/llm-settings) page, where keys and the account default live. If the account has no keys of its own, Guild-provided tokens serve every call and there are no rules to set.

Rules are ranked, and the first matching rule wins. The rule list has these columns:

| Column | Description |
| - | - |
| **#** | The rule's rank. Drag the handle to reorder. |
| **Key** | The account credential the rule applies to. Each key can have at most one rule per level. |
| **Publisher** | The model publisher on that key. |
| **Models** | **All models**, the allowed models, or **No models -- key disabled**. |

Click **Add rule** to add one. It's disabled once every key has a rule. Use the row's **Rule actions** menu to **Edit** or **Delete** a rule.

In the **Add rule** or **Edit rule** dialog, pick a **Key**, then choose one of:

* **All models on this key** — allow every model the provider exposes for that key.
* **Specific models** — click **Add model** and pick from the **Provider catalog**, or type a glob such as `haiku-*` or `gpt-4o-*` and select **Add "*value*"**.

Saving a **Specific models** rule with no models disables that key at this level, so agents here can't use it.

Changes apply immediately. There is no separate save step.

### Integrations

The **Credentials for this agent** card shows the credentials this agent holds in this workspace.

The credentials are listed in two groups:

* **Granted to this agent** — existing credentials shared with the agent, each marked **Granted · *owner***. Pick one from **Search credentials…** and click **Grant credential** to add it. A grant runs as the credential's owner.
* **Dedicated to this agent** — credentials that exist only for this agent, marked **Dedicated**. Click **Connect a credential**, choose the integration, then **Connect API key** or **Connect via OAuth**. If the agent already has a dedicated credential for that integration, connecting a new one replaces it and deletes the old one.

Each row has a **Policy** chip and a **Policies** link that open the credential's [policies](https://docs.guild.ai/platform/credential-policies.md). Click **Revoke grant** to remove a credential from the agent, then confirm. When two rows are for the same integration, an **ID** chip tells them apart.

Only the person who added the agent to this workspace, the owner of a personal account, or an organization admin can change these credentials. Everyone else sees them read-only.

### Upgrade history

Lists the agent's last 10 version changes in this workspace, with **Date**, **Old Version**, **New Version**, and **Upgraded By**. An upgrade that **Autoupdate** made reads **Automated upgrade**.

### Sessions

Lists the sessions that used this agent in this workspace, newest first. Select one to open it.

## Remove an agent

Click **Remove from Workspace** in the agents list, or **Remove agent** on the detail page, then confirm. Removing an agent:

* deactivates any triggers that use it in this workspace
* leaves the agent itself, and its installs in other workspaces, unchanged

You can add it back later. To take an agent out of every workspace at once, archive it instead. See [Disabling an agent](https://docs.guild.ai/platform/agents.md#disabling-an-agent).

## Related pages

* [Your agents](https://docs.guild.ai/platform/agents.md) for building, publishing, and archiving agents
* [Workspace credentials](https://docs.guild.ai/platform/workspace-credentials.md) for every credential agents in this workspace can use
* [Workspace models](https://docs.guild.ai/platform/workspace-models.md) for the rules that apply to every agent in this workspace