AgentDefinition YAML Reference

The AgentDefinition YAML is hive’s portable agent format — a single, self-contained document (kind: AgentDefinition) that describes whole agent: its identity, its engine, its behavior, and even its work prompt. This is the file the dashboard’s + agent → Import from URL overlay points you at, and it is exactly the schema that overlay reads. This page documents every field, grouped to match the file’s structure.

If you clicked + agent in the dashboard and were sent to v2/examples/agents/customized-agent.yaml for an example, this is the reference for that file. For the other way agents are configured — inline entries under agents: in hive.yaml, using snake_case keys — see Agent Configuration. The two describe the same underlying agent; they differ in shape and casing (see How this maps to hive.yaml below).

Which Hive does this document? This page tracks the Hive v2 line — the same line the dashboard, the + agent overlay, and the example YAML come from. Hive’s docs site currently publishes a single main (Latest) channel; there is no separate v2 entry in the version selector even though the example file lives on the repo’s v2 branch. If a dashboard link sends you to .../blob/v2/v2/examples/..., that doubled v2 is branch v2 plus the in-repo path v2/examples/..., not a typo — it is the current, supported example.

The document envelope

Every AgentDefinition starts with the same four top-level keys:

apiVersion: hive.kubestellar.io/v1
kind: AgentDefinition
metadata:
  # identity & presentation
spec:
  # engine, behavior, triggers, tools, connections

metadata — identity and presentation

metadata:
  name: customized-agent
  displayName: "Customized Agent"
  description: "A template agent that demonstrates the portable agent definition format."
  emoji: "🛠"
  color: "#e67e22"

spec — engine, behavior, and triggers

Everything below lives under spec:.

Engine — what powers the agent

spec:
  backend: copilot
  model: claude-sonnet-4-6

backend accepts of three kinds of value:

1. A subscription CLI: claude, copilot, goose, codex, pi, bob, or aider. You log in per CLI from the dashboard, and every agent using that CLI shares the login. (gemini is also offered live in the dashboard; as a persisted value prefer the validated list here.)
2. A self-hosted inference backend: vllm, llm-d, or litellm. These are OpenAI-compatible endpoints you configure with a base URL and a key reference; the agent launches the Claude CLI routed through hive’s inference translator, so there is no separate login.
3. A configured Model Gateway name (for example openrouter). When backend names a gateway you have configured, the agent is routed through that gateway’s OpenAI-compatible endpoint. The gateway must exist in your hive configuration first; the name here simply selects it. If your hive has an OpenRouter / Model Gateway setup page, configure the gateway there before referencing it as a backend.

The engine also decides how model discovery works and how pinning behaves. For the full comparison of subscription CLIs vs. inference backends, live model discovery, and the pin/auto-switch rules, see Agent Configuration → Methods.

Identity & routing

spec:
  role: custom
  sortOrder: 50
  beadRole: worker
  aliases:
    - cu
  laneKeywords:
    - custom
    - review
  detectKeywords:
    - customized

Behavior — what it may do, and when

spec:
  mode: ADVISORY
  staleTimeout: 28800
  restartStrategy: immediate
  clearOnKick: true
  includeRepos: true

cadences — how often the governor kicks it

spec:
  cadences:
    idle: 4h
    quiet: 4h
    busy: 2h
    surge: "off"

cadences is a map from governor mode (idle, quiet, busy, surge) to the interval at which this agent is kicked in that mode. Any interval Go’s duration parser accepts works (5m, 2h, 4h); "off" (or pause) suspends kicks for that mode without disabling the agent.

The governor computes the mode from queue depth and kicks each agent on the cadence that mode assigns it. For the full model — evaluation cycle, thresholds, and budgets — see Governor.

promptTemplate — the agent’s work prompt

spec:
  promptTemplate: |
    # ${AGENT_DISPLAY_NAME} — Custom Agent Policy
 
    ${GH_AUTH}
 
    You are the **${AGENT_NAME}** agent for ${PROJECT_ORG}/${PROJECT_PRIMARY_REPO}.
 
    ## Your Role
    Analyze the codebase and provide recommendations based on your expertise.
 
    ## Work List
    ISSUES: ${ISSUE_LIST}
    PRs: ${PR_LIST}
 
    ${KNOWLEDGE}

${VAR} references are substituted on every kick (${ISSUE_LIST}, ${PR_LIST}, ${AGENT_NAME}, ${PROJECT_ORG}, ${KNOWLEDGE}, …). For the complete variable list and how to add your own, see Variable Substitution.

Bundling the prompt inline is what makes an AgentDefinition portable: config plus policy travel together in importable file.

channels — how the agent gets triggered

Channels declare how an agent is triggered. When omitted, the agent uses the default governor timer kick. Declaring channels lets you trigger on webhooks, schedules, Discord, or beads instead of (or in addition to) the timer.

spec:
  channels:
    - type: kick
    - type: webhook
      events: ["issues.opened"]
    - type: schedule
      schedule: "0 */4 * * *"

Note: Channels are a current, supported v2 feature. (Older copies of the example labeled this (v3 feature); that label is being removed — treat channels as available today.)

tools — declarative tool permissions

The tools block replaces the coarse mode tier with an explicit permission preset plus per-tool overrides. When present, it governs instead of mode.

spec:
  tools:
    preset: advisory
    rules:
      - pattern: "mcp__github__create_issue"
        action: allow
        reason: "allow creating advisory issues"

Note: Tools are a current, supported v2 feature.

connections — external service integrations

Connections attach external services (MCP servers, HTTP APIs, knowledge sources) to an agent.

spec:
  connections:
    - name: github-mcp
      type: mcp
      uri: "stdio:///usr/local/bin/mcp-github"

Note: Connections are a current, supported v2 feature.

Complete annotated example

This mirrors the shipped v2/examples/agents/customized-agent.yaml. Import it from the dashboard via + agent → Import from URL, or copy it as a starting point and edit the fields above.

apiVersion: hive.kubestellar.io/v1
kind: AgentDefinition
metadata:
  name: customized-agent                # required — roster key & identifier
  displayName: "Customized Agent"        # dashboard label
  description: "A template agent that demonstrates the portable agent definition format. Customize this to create your own specialized agent."
  emoji: "🛠"                            # dashboard badge
  color: "#e67e22"                       # dashboard accent
spec:
  backend: copilot                       # engine: CLI | inference backend | gateway name
  model: claude-sonnet-4-6               # model id for that engine
  role: custom                           # behavioral role tag
  mode: ADVISORY                         # GitHub tier: ADVISORY|ISSUES_ONLY|ISSUES_AND_PRS|ISSUES_PRS_MERGE
  sortOrder: 50                          # dashboard ordering (lower first)
  beadRole: worker                       # worker | supervisor
  staleTimeout: 28800                    # seconds of silence before "stale" (> longest cadence)
  restartStrategy: immediate             # reconnect a dead session immediately
  clearOnKick: true                      # fresh context on each kick
  includeRepos: true                     # append the project repo list to each kick
  laneKeywords:                          # route matching issues/PRs into this lane
    - custom
    - review
  detectKeywords:                        # attribute GitHub activity back to this agent
    - customized
  aliases:                               # short dispatch names
    - cu
 
  # Channels — how this agent gets triggered (supported v2 feature).
  # Omit to use governor timer kicks.
  # channels:
  #   - type: kick
  #   - type: webhook
  #     events: ["issues.opened"]
  #   - type: schedule
  #     schedule: "0 */4 * * *"
 
  # Tools — declarative tool permissions (supported v2 feature).
  # Present = governs instead of `mode`.
  # tools:
  #   preset: advisory
  #   rules:
  #     - pattern: "mcp__github__create_issue"
  #       action: allow
  #       reason: "allow creating advisory issues"
 
  # Connections — external service integrations (supported v2 feature).
  # connections:
  #   - name: github-mcp
  #     type: mcp
  #     uri: "stdio:///usr/local/bin/mcp-github"
 
  cadences:                              # per-governor-mode kick intervals
    idle: 4h
    quiet: 4h
    busy: 2h
    surge: "off"                         # "off" (or pause) suspends kicks in this mode
 
  promptTemplate: |                      # inline periodic work prompt (${VAR} substituted per kick)
    # ${AGENT_DISPLAY_NAME} — Custom Agent Policy
 
    ${GH_AUTH}
 
    You are the **${AGENT_NAME}** agent for ${PROJECT_ORG}/${PROJECT_PRIMARY_REPO}.
 
    ## Your Role
    Analyze the codebase and provide recommendations based on your expertise.
    Focus on the repositories listed below and create advisory beads for your findings.
 
    ## Rules
    - work items from the kick message
    - Always sign commits with DCO: git commit -s
    - Respect hold labels
    - Write a bead for every finding
 
    ## Work List
    ISSUES: ${ISSUE_LIST}
    PRs: ${PR_LIST}
 
    ${KNOWLEDGE}

Import defaults

When you import an AgentDefinition, a few fields get default values if you leave them out:

enabled and paused are operator lifecycle state, not definition fields: they are managed from the dashboard, not from the imported YAML, so an imported definition can never silently enable or un-pause an agent behind your back.

How this maps to hive.yaml

An imported AgentDefinition becomes entry under agents: in the running config. The portable format uses apiVersion/kind/metadata/spec with camelCase keys; the inline hive.yaml form uses snake_case keys directly under the agent name. The mapping is-to-one:

For the inline hive.yaml form, the smallest-agent walkthrough, ACMM packs, and the governor, start at Agent Configuration.

What to read next

• Agent Configuration — the inline hive.yaml agent form, defaults, ACMM packs, and the full anatomy of an agent.
• Governor — how cadences turn into kicks.
• Variable Substitution — the ${VAR} references used in promptTemplate.