AgentDefinition schema

The agent document type, validated against the published JSON schema.

Example

agent.json

{
  "id": "writer-agent",
  "name": "Writer Agent",
  "locality": "LOCAL",
  "version": "1.0.0",
  "systemPrompt": "You are a concise writer.",
  "providerPreferences": [
    {
      "provider": "openai",
      "model": "gpt-4o-mini"
    }
  ],
  "supportedCommands": [
    "COMPLETE",
    "CONTINUE"
  ]
}

Properties

Property	Type	Required	Description
id	string	yes	Unique agent identifier. Must match the agent directory name stem.
name	string	yes	—
locality	enum (LOCAL, CLOUD)	yes	LOCAL runs on operator-controlled infrastructure(i.e. Ollama, vllm). CLOUD calls an external API(i.e. ChatGpt, Claude).
enabled	boolean	no	Whether the agent is enabled. Disabled agents are ignored by the system.
systemPrompt	string	no	Inline system prompt. If omitted, systemprompt.md in the agent directory is used.
providerPreferences	array of ProviderPreference	yes	Ordered list of provider preferences. First available provider is used.
supportedCommands	array | null	no	Subset of commands this agent may return. Null means all commands.
author	string	no	Author of the agent. Optional metadata.
contact	string	no	Contact information for the agent author. Optional metadata.
version	string	yes	Agent version. Can be used for display or to trigger specific logic based on version.
modelTier	enum (LITE, STANDARD, POWERFUL, null)	no	Optional capability tier resolved to a concrete model per provider at invocation time. A raw model pin on a providerPreference always wins over the tier. Null relies on pins or provider defaults.

Definitions

ProviderPreference

Property	Type	Required	Description
provider	enum (azure-openai, bedrock, claude, gemini, mistral, ollama, openai, openai-compatible, vllm)	yes	Lowercase provider name.
model	string | null	no	Optional model override. Null means use provider default.