Skip to main content
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

FieldTypeRequiredDefaultDescription
namestringNo—Display name. Omitting it lets the platform auto-generate one.
specialtystringYes—Reference an existing Specialty by its name.
hoststringYes—Reference an existing Host by its name. The agent’s organization is inherited from this host.
main_enginestringYes—Model key for the main engine (must exist in the tenant model catalog).
secondary_enginestringYes—Model key for the secondary engine.
remote_executionbooleanNotrueAlmost always true. Set false only for the rare local-execution case.
credential_configarrayNo[]Credential bindings. Array position carries priority — index 0 is tried first.

​
credential_config[] shape

FieldTypeRequiredDescription
credentialstringYesReference a Credential by its name.
credential_rolestringYesRole this credential fills (ssh_username, ssh_password, ssh_private_key, ssh_public_key).
is_requiredbooleanNo (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.