Agent

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 by its `name`.
`host`	string	Yes	—	Reference an existing Host 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 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

agents/web-01-agent.mdx

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

CLI

Deploy

Configure

Frontmatter

`credential_config[]` shape

Fields NOT supported

Example

Gotchas

​Frontmatter

​credential_config[] shape

​Fields NOT supported

​Example

​Gotchas

Frontmatter

`credential_config[]` shape

Fields NOT supported

Example

Gotchas