> ## 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.16/configure/resources/specialties) by its `name`. |
| `host` | string | **Yes** | - | Reference an existing [Host](/0.16/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. |
| `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.16/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
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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.