Skip to content
AI agent subsystem

AgentDefinition

An AgentDefinition is the recipe: a reusable, environment-independent description of a task. It carries no runtime details and has no status. It is pure configuration that Stations reference.

flowchart LR
    AD["AgentDefinition<br/>recipe"]:::hi --> ST["Station"] --> AG["Agent"] --> JB["Job"]
    classDef hi fill:#2f5fd8,color:#fff,stroke:#16224f;
    class AD hi

What it carries

Section titled “What it carries”
  • prompt: the task template. Supports {placeholder} tokens filled from an Agent’s parameters at run time (see Prompt templating).
  • model: the model id (for example claude-sonnet-4-6). If omitted, the runtime default is used. With the model catalog enabled, the ModelCatalog lists the ids the subsystem can run with its API keys.
  • allowed_tools / disallowed_tools: permission rules, e.g. Bash(npm run test:*) or Bash(rm *).
  • permission_mode: auto (the default) enforces the allow/deny lists; bypass grants all tools. On Gemini that takes --yolo and a policy that allows every tool in every approval mode (see Gemini under bypass).
  • max_turns: optional cap on agentic turns; omit for uncapped.
  • resources: what the run needs available to it — env, secrets (env-var name plus an allowlisted secret-store key), mcp_servers (each with secret-backed headers or env), repos, skills / skills_source (skills fetched into the run’s $HOME/.claude, plus the source’s hook bundle for the vendor the model routes to, extracted relative to $HOME), and conversation (a previous run this one continues).
  • output: the result contract: format (text / json / stream-json), an optional schema, event select filters, sinks (stdout, http, file), and watch (files the run is expected to produce, each raised as a named event).
  • execution: interactive (the default) runs the agent CLI in a Job pod; batch sends the prompt to the provider’s batch API from the controller, about half the price but with results that can take up to 24 hours and only a single model call. batch.timeoutMinutes and batch.onTimeout (fail or fallback to a normal Job) bound the wait, and batch.maxTokens (default 16000) caps the answer. Batch is off unless the controller is installed with the components/batch kustomize component. See batch runs. realtime keeps the agent CLI running in its Job pod and takes prompts over HTTP until the session is closed or has been idle for realtime.idleTimeoutMinutes (default 15); it is off unless the controller is installed with the components/realtime component. See realtime sessions.
  • tool_config: a raw passthrough object for tool-specific knobs; unknown fields are preserved.

Why it is separate

Section titled “Why it is separate”

Because the recipe holds nothing environment-specific, the same AgentDefinition can run unchanged across many Stations (a dev kind cluster, a CI namespace, or production) by pairing it with a different Pod template.

The full field reference is in AgentDefinition CRD.