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

# Agent

> MDX frontmatter reference for agent resources

**Subdirectory:** `agents/` · **Body:** none

Agents are scoped to the **organization of their host** — you do not set `org` on the agent itself; it is resolved from the host reference at sync time.

## Frontmatter

| Field               | Type    | Required | Default | Description                                                                                                                       |
| ------------------- | ------- | -------- | ------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `name`              | string  | No       | —       | Display name. Omitting it lets the platform auto-generate one.                                                                    |
| `specialty`         | string  | **Yes**  | —       | Reference an existing [Specialty](/0.8/configure/resources/specialties) by its `name`.                                            |
| `host`              | string  | **Yes**  | —       | Reference an existing [Host](/0.8/configure/resources/hosts) by its `name`. The agent's organization is inherited from this host. |
| `main_engine`       | string  | **Yes**  | —       | Model `key` for the main engine (must exist in the tenant model catalog).                                                         |
| `secondary_engine`  | string  | **Yes**  | —       | Model `key` for the secondary engine.                                                                                             |
| `remote_execution`  | boolean | No       | `true`  | Almost always `true`. Set `false` only for the rare local-execution case.                                                         |
| `credential_config` | array   | No       | `[]`    | Credential bindings. **Array position carries priority** — index 0 is tried first.                                                |

### `credential_config[]` shape

| Field             | Type    | Required            | Description                                                                                       |
| ----------------- | ------- | ------------------- | ------------------------------------------------------------------------------------------------- |
| `credential`      | string  | **Yes**             | Reference a [Credential](/0.8/configure/resources/credentials) by its `name`.                     |
| `credential_role` | string  | **Yes**             | Role this credential fills (`ssh_username`, `ssh_password`, `ssh_private_key`, `ssh_public_key`). |
| `is_required`     | boolean | No (default `true`) | Whether the agent fails to start without this credential.                                         |

## Fields NOT supported

These are managed elsewhere and cannot be set in MDX:

* `id`, `tenant_id`, `org_id`, `created_at`, `updated_at` — system-set
* `archived_at` — managed from the UI
* `host_id`, `specialty_id`, `credential_config[].credential_id` — resolved from the **name** references above

Any extra key in frontmatter causes a strict-schema validation error.

## Example

```mdx agents/web-01-agent.mdx theme={null}
---
name: web-01-agent
specialty: linux-administration
host: web-01
main_engine: anthropic/claude-sonnet-4-6
secondary_engine: openai/gpt-4o
remote_execution: true
credential_config:
  - credential: web-admin-user
    credential_role: ssh_username
    is_required: true
  - credential: web-admin-password
    credential_role: ssh_password
    is_required: true
---
```

## Gotchas

* **Agents have no `org` field.** They inherit it from `host`. Renaming a host you reference from an agent is a coordinated change — pull, edit both, then sync.
* **`main_engine` and `secondary_engine` are model *keys*, not Model IDs.** The key is the display identifier in the catalog; the Model ID is what's sent to the provider's API.
* **Pull skips agents with no host.** An agent file is only meaningful with a host reference, so the exporter drops orphaned ones.