API Reference

Packages

• kubeswarm.io/v1alpha1

kubeswarm.io/v1alpha1

Package v1alpha1 contains API Schema definitions for the kubeswarm v1alpha1 API group.

Resource Types

• SwarmAgent
• SwarmAgentList
• SwarmBudget
• SwarmBudgetList
• SwarmEvent
• SwarmEventList
• SwarmMemory
• SwarmMemoryList
• SwarmNotify
• SwarmNotifyList
• SwarmRegistry
• SwarmRegistryList
• SwarmRun
• SwarmRunList
• SwarmSettings
• SwarmSettingsList
• SwarmTeam
• SwarmTeamList

AgentCapability

AgentCapability advertises one capability this agent offers to SwarmRegistry and the MCP gateway.

Appears in:

• SwarmAgentSpec

Field	Description	Default	Validation
name string	Name uniquely identifies this capability. Used for registry lookups and MCP tool naming.		MinLength: 1 Required: true
description string	Description explains the capability to human operators and LLM consumers.		Optional: true
tags string array	Tags enable coarse-grained filtering in registry lookups. A lookup matches agents that declare ALL listed tags.		Optional: true
exposeMCP boolean	ExposeMCP registers this capability as a named tool at the MCP gateway endpoint for this agent. Requires the MCP gateway to be enabled in the operator.	false	Optional: true
inputSchema RawExtension	InputSchema is a JSON Schema object describing the capability's input parameters. Stored as a raw YAML/JSON object; enables CRD validation and tooling introspection.		Optional: true
outputSchema RawExtension	OutputSchema is a JSON Schema object describing the capability's output shape.		Optional: true

AgentConnection

AgentConnection defines another agent callable as a tool via A2A. Exactly one of agentRef or capabilityRef must be set.

Appears in:

• SwarmAgentSpec

Field	Description	Default	Validation
name string	Name is the local identifier for this agent connection. Used in guardrails.tools allow/deny patterns: "<name>/<capability>".		MinLength: 1 Required: true
agentRef LocalObjectReference	AgentRef names a SwarmAgent in the same namespace whose MCP-exposed capabilities are made available as tools. The target must have at least one capability with exposeMCP: true.		Optional: true
capabilityRef LocalObjectReference	CapabilityRef names a capability ID in the namespace's SwarmRegistry. The operator resolves the MCP gateway URL at reconcile time.		Optional: true
trust ToolTrustLevel	Trust classifies the trust level of this agent connection. Defaults to guardrails.tools.trust.default when unset.		Enum: [internal external sandbox] Optional: true
instructions string	Instructions is operational context injected into the agent's system prompt for calls to this agent. Use to constrain scope or set expectations.		Optional: true

AgentFleetEntry

AgentFleetEntry is one agent's summary in the registry fleet view.

Appears in:

• SwarmRegistryStatus

Field	Description	Default	Validation
name string	Name is the SwarmAgent name.
model string	Model is the LLM model this agent is configured to use.
readyReplicas integer	ReadyReplicas is the number of agent pods currently ready.
dailyTokens integer	DailyTokens is the rolling 24h token usage copied from SwarmAgent.status.		Optional: true
capabilities string array	Capabilities lists the capability IDs this agent contributes to the index.		Optional: true

AgentGuardrails

AgentGuardrails groups tool permissions, budget reference, and execution limits.

Appears in:

• SwarmAgentSpec

Field	Description	Default	Validation
tools ToolPermissions	Tools configures allow/deny lists and trust policy for tool calls.		Optional: true
budgetRef LocalObjectReference	BudgetRef references a SwarmBudget that governs token spend for this agent. When the budget is exhausted new tasks are rejected.		Optional: true
limits GuardrailLimits	Limits constrains per-agent resource and cost usage.		Optional: true

AgentHealthCheck

AgentHealthCheck defines how agent health is evaluated.

Appears in:

• AgentObservability

Field	Description	Default	Validation
type string	Type is the probe strategy. semantic: sends a prompt to the agent and evaluates the response via LLM. ping: sends an HTTP request to the agent's health endpoint.	semantic	Enum: [semantic ping]
intervalSeconds integer	IntervalSeconds is how often the probe runs.	30	Optional: true
prompt string	Prompt is the message sent when type is semantic.		Optional: true
notifyRef LocalObjectReference	NotifyRef references a SwarmNotify policy used for AgentDegraded events.		Optional: true

AgentLogging

AgentLogging controls structured log emission from the agent runtime. All logs are emitted as JSON via slog.

Appears in:

• AgentObservability

Field	Description	Default	Validation
level string	Level is the minimum log level emitted.	info	Enum: [debug info warn error] Optional: true
toolCalls boolean	ToolCalls enables structured logging of tool invocations: tool name, args, and result. Emits log lines with msg="tool_call". Disabled by default to avoid noisy logs.		Optional: true
llmTurns boolean	LLMTurns enables logging of the full LLM message history per task. Verbose and potentially sensitive — enable only for debugging.		Optional: true
redaction LogRedactionPolicy	Redaction controls scrubbing of sensitive values from log output.		Optional: true

AgentLoopMemory

AgentLoopMemory configures vector memory read/write within the tool-use loop. Requires a SwarmMemory with a vector backend referenced via ref.

Appears in:

• AgentLoopPolicy

Field	Description	Default	Validation
ref LocalObjectReference	Ref references the SwarmMemory object providing the vector backend.		Optional: true
store boolean	Store enables writing a summary of each tool result to the vector store after execution.		Optional: true
retrieve boolean	Retrieve enables fetching similar prior findings from the vector store before each tool call. Findings are injected as a <swarm:prior-findings> block with the tool result.		Optional: true
topK integer	TopK is the maximum number of prior findings injected per tool call.	3	Optional: true
minSimilarity float	MinSimilarity is the minimum cosine similarity score for a retrieved finding to be injected. Findings below this threshold are silently dropped.	0.7	Maximum: 1 Minimum: 0 Optional: true
summaryTokens integer	SummaryTokens is the advisory token limit for per-result summaries stored in the vector store. When > 0 a cheap model call produces the summary before storing. When 0 the raw result is truncated to MaxTokens instead.	256	Optional: true
maxTokens integer	MaxTokens is the hard truncation limit applied when SummaryTokens is 0.	1024	Optional: true

AgentLoopPolicy

AgentLoopPolicy configures the agent runner's agentic loop behaviour.

Appears in:

• AgentRuntime

Field	Description	Default	Validation
dedup boolean	Dedup skips tool calls whose fingerprint (tool name + args hash) was already executed in the current task. The dedup set is task-local and discarded on completion.		Optional: true
compression LoopCompressionConfig	Compression configures in-loop context compression. When set, the runner summarises older conversation turns when accumulated tokens exceed the threshold, allowing the agent to run beyond the model's context window.		Optional: true
memory AgentLoopMemory	Memory configures vector memory read/write during the tool-use loop. Requires a SwarmMemory with a vector backend referenced via memory.ref.		Optional: true

AgentMetrics

AgentMetrics controls Prometheus-compatible metrics exposure for the agent runtime.

Appears in:

• AgentObservability

Field	Description	Default	Validation
enabled boolean	Enabled exposes a /metrics endpoint on the agent pod for Prometheus scraping.	false	Optional: true

AgentObservability

AgentObservability groups health check, logging, and metrics configuration.

Appears in:

• SwarmAgentSpec

Field	Description	Default	Validation
healthCheck AgentHealthCheck	HealthCheck defines how agent health is evaluated and how degraded agents are alerted.		Optional: true
logging AgentLogging	Logging controls structured log emission from the agent runtime.		Optional: true
metrics AgentMetrics	Metrics controls Prometheus metrics exposure.		Optional: true

AgentPlugins

AgentPlugins configures external gRPC plugin overrides for the LLM provider and task queue. These are escape hatches for environments where the built-in providers are insufficient. See RFC-0025.

Appears in:

• SwarmAgentSpec

Field	Description	Default	Validation
llm PluginEndpoint	LLM is the host:port of an external gRPC LLM provider plugin. When set the agent uses the gRPC adapter instead of the built-in provider.		Optional: true
queue PluginEndpoint	Queue is the host:port of an external gRPC task queue plugin. When set TASK_QUEUE_URL is ignored and the agent uses the gRPC queue adapter.		Optional: true

AgentPrompt

AgentPrompt configures the agent's system prompt. Exactly one of inline or from must be set.

Appears in:

• SwarmAgentSpec

Field	Description	Default	Validation
inline string	Inline is the system prompt text written directly in the manifest. For long or frequently-iterated prompts prefer from.		Optional: true
from SystemPromptSource	From references a ConfigMap or Secret key whose content is used as the system prompt. Updating the referenced object triggers an automatic rolling restart of agent pods.		Optional: true

AgentRuntime

AgentRuntime groups all execution concerns for the agent deployment.

Appears in:

• SwarmAgentSpec

Field	Description	Default	Validation
replicas integer	Replicas is the number of agent instances to run. Ignored when autoscaling is set; autoscaling.minReplicas acts as the floor.	1	Maximum: 50 Minimum: 0 Optional: true
autoscaling SwarmAgentAutoscaling	Autoscaling configures KEDA-based autoscaling. When set, replicas is ignored. Requires KEDA v2 installed in the cluster.		Optional: true
resources ResourceRequirements	Resources sets CPU and memory requests/limits for agent pods. When not set the operator injects safe defaults: requests: cpu=100m, memory=128Mi limits: cpu=500m, memory=512Mi, ephemeral-storage=256Mi		Optional: true
loop AgentLoopPolicy	Loop configures deep-research runtime features: semantic dedup, in-loop context compression, and vector memory read/write. All features are disabled by default.		Optional: true

AgentTools

AgentTools groups all tool connections available to the agent.

Appears in:

• SwarmAgentSpec

Field	Description	Default	Validation
mcp MCPToolSpec array	MCP lists MCP server connections. Each entry exposes multiple tools via the Model Context Protocol SSE transport.		Optional: true
webhooks WebhookToolSpec array	Webhooks lists inline single-endpoint HTTP tools.		Optional: true

ArtifactSpec

ArtifactSpec declares a named file artifact produced by a pipeline step. The agent is expected to write the artifact file under $AGENT_ARTIFACT_DIR/<name>.

Appears in:

• SwarmTeamPipelineStep

Field	Description	Default	Validation
name string	Name is the artifact identifier, used in template references: {{ .steps.<stepName>.artifacts.<name> }}		MinLength: 1 Required: true
description string	Description documents the artifact for operators and tooling.		Optional: true
contentType string	ContentType is the MIME type hint for the artifact (e.g. application/pdf).		Optional: true

ArtifactStoreGCSSpec

ArtifactStoreGCS configures Google Cloud Storage artifact storage.

Appears in:

• ArtifactStoreSpec

Field	Description	Default	Validation
bucket string	Bucket is the GCS bucket name.		Required: true
prefix string	Prefix is an optional object prefix applied to all stored artifacts.		Optional: true
credentialsSecret LocalObjectReference	CredentialsSecret references a k8s Secret with a service account JSON key under the "credentials.json" key.		Optional: true

ArtifactStoreLocalSpec

ArtifactStoreLocalSpec configures a volume-backed local artifact store. In Kubernetes, set ClaimName to mount a PersistentVolumeClaim into every agent pod in the team. For single-process local runs (swarm run CLI), ClaimName is not needed and Path is used as a plain directory on the local filesystem.

Appears in:

• ArtifactStoreSpec

Field	Description	Default	Validation
path string	Path is the mount path inside agent pods (and the directory path for swarm run). Defaults to /artifacts in Kubernetes (when ClaimName is set) or /tmp/swarm-artifacts for CLI runs.		Optional: true
claimName string	ClaimName is the name of a PersistentVolumeClaim to mount at Path inside agent pods. Required for Kubernetes deployments; omit for swarm run (CLI) local testing. The PVC must support ReadWriteMany if multiple agent replicas run concurrently; ReadWriteOnce is sufficient for single-replica agents.		Optional: true

ArtifactStoreS3Spec

ArtifactStoreS3 configures Amazon S3 artifact storage.

Appears in:

• ArtifactStoreSpec

Field	Description	Default	Validation
bucket string	Bucket is the S3 bucket name.		Required: true
region string	Region is the AWS region (e.g. us-east-1).		Optional: true
prefix string	Prefix is an optional key prefix applied to all stored artifacts.		Optional: true
credentialsSecret LocalObjectReference	CredentialsSecret references a k8s Secret containing AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY keys. When empty, the default credential chain is used.		Optional: true

ArtifactStoreSpec

ArtifactStoreSpec configures where pipeline file artifacts are stored.

Appears in:

• SwarmTeamSpec

Field	Description	Default	Validation
type ArtifactStoreType	Type selects the storage backend.		Enum: [local s3 gcs] Required: true
local ArtifactStoreLocalSpec	Local configures local-disk storage. Only used when type=local.		Optional: true
s3 ArtifactStoreS3Spec	S3 configures Amazon S3 storage. Only used when type=s3.		Optional: true
gcs ArtifactStoreGCSSpec	GCS configures Google Cloud Storage. Only used when type=gcs.		Optional: true

ArtifactStoreType

Underlying type: string

ArtifactStoreType identifies the storage backend for file artifacts.

Validation:

• Enum: [local s3 gcs]

Appears in:

• ArtifactStoreSpec

Field	Description
local	ArtifactStoreLocal stores artifacts on the local filesystem (swarm run only).
s3	ArtifactStoreS3 stores artifacts in an Amazon S3 bucket.
gcs	ArtifactStoreGCS stores artifacts in a Google Cloud Storage bucket.

BearerAuth

BearerAuth configures bearer token authentication for an MCP server. The token value is never inlined into the pod spec — it is injected as an env var.

Appears in:

• MCPServerAuth

Field	Description	Default	Validation
secretKeyRef SecretKeySelector	SecretKeyRef selects the key of a Secret containing the bearer token.

BudgetStatus

Underlying type: string

BudgetStatus is the phase summary for an SwarmBudget.

Validation:

• Enum: [OK Warning Exceeded]

Appears in:

• SwarmBudgetStatus

Field	Description
OK
Warning
Exceeded

ConcurrencyPolicy

Underlying type: string

ConcurrencyPolicy controls what happens when a trigger fires while a previously dispatched pipeline is still running.

Validation:

• Enum: [Allow Forbid]

Appears in:

• SwarmEventSpec

Field	Description
Allow	ConcurrencyAllow always dispatches a new pipeline run, even if a previous one is still running.
Forbid	ConcurrencyForbid skips the fire if any pipeline owned by this trigger is still Running.

ContextCompressConfig

ContextCompressConfig configures the compression LLM call.

Appears in:

• StepContextPolicy

Field	Description	Default	Validation
targetTokens integer	TargetTokens is the advisory token budget for the compressed output. 0 means no explicit budget — the agent uses its own judgement.		Optional: true
model string	Model is the model used for compression. Defaults to the pipeline's configured model when unset. A cheaper model (e.g. claude-haiku-4-5) is recommended.		Optional: true
prompt string	Prompt overrides the system prompt sent to the compression LLM. The placeholder "{{ .targetTokens }}" is available. When unset, a built-in summarisation prompt is used.		Optional: true

ContextExtractConfig

ContextExtractConfig configures field or pattern extraction.

Appears in:

• StepContextPolicy

Field	Description	Default	Validation
path string	Path is evaluated as a JSONPath expression when the step output is valid JSON, or as a Go regexp (first capture group) for prose output.		Required: true

EmbeddingConfig

EmbeddingConfig configures the embedding model used to convert text into vectors for the vector-store backend (RFC-0026). Required when backend is "vector-store" and spec.vectorStore is set.

Appears in:

• SwarmMemorySpec

Field	Description	Default	Validation
model string	Model is the embedding model ID. Supported: text-embedding-3-small, text-embedding-3-large (OpenAI), text-embedding-004 (Google), voyage-3-lite (Voyage AI).		MinLength: 1 Required: true
provider string	Provider selects the embedding provider. When "auto" (default), the provider is inferred from the model name.	auto	Enum: [auto openai google voyageai] Optional: true
dimensions integer	Dimensions is the output vector dimension. When 0 the model default is used. Use this to select a smaller dimension on models that support Matryoshka representations (e.g. text-embedding-3-small supports 512 or 1536).		Optional: true
apiKeyRef SecretKeySelector	APIKeyRef references a Secret key that holds the embedding provider API key. When not set, the agent falls back to the same provider key used for the LLM (OPENAI_API_KEY etc.). Required when the embedding provider differs from the LLM provider.		Optional: true

GuardrailLimits

GuardrailLimits constrains per-agent resource and cost usage.

Appears in:

• AgentGuardrails
• SwarmTeamRole

Field	Description	Default	Validation
tokensPerCall integer	TokensPerCall is the maximum number of tokens per LLM API call.	8000	Optional: true
concurrentTasks integer	ConcurrentTasks is the maximum number of tasks processed in parallel per replica.	5	Optional: true
timeoutSeconds integer	TimeoutSeconds is the per-task deadline in seconds.	120	Optional: true
dailyTokens integer	DailyTokens is the rolling 24-hour token budget (input + output combined). When reached the operator scales replicas to 0 and sets a BudgetExceeded condition. Resumes automatically when the 24-hour window rotates. Zero means no daily limit.		Minimum: 1 Optional: true
retries integer	Retries is the number of times a failed task is requeued before dead-lettering. Set to 0 to disable retries entirely.	3	Maximum: 100 Minimum: 0 Optional: true

IndexedCapability

IndexedCapability is one capability entry in the SwarmRegistry status index.

Appears in:

• SwarmRegistryStatus

Field	Description	Default	Validation
id string	ID is the capability identifier.
description string	Description is the human-readable description of the capability, taken from the first agent that declares it. Used by the router LLM to select the right agent.
agents string array	Agents is the list of SwarmAgent names that advertise this capability.
tags string array	Tags is the union of all tags declared for this capability across all agents.

LocalObjectReference

LocalObjectReference identifies an object in the same namespace.

Appears in:

• AgentConnection
• AgentGuardrails
• AgentHealthCheck
• AgentLoopMemory
• ArtifactStoreGCSSpec
• ArtifactStoreS3Spec
• MTLSAuth
• PluginTLSConfig
• RedisMemoryConfig
• RegistryLookupSpec
• SwarmAgentSpec
• SwarmBudgetSpec
• SwarmTeamRole
• SwarmTeamRoutingSpec
• SwarmTeamSpec
• VectorStoreMemoryConfig

Field	Description	Default	Validation
name string	Name of the referenced object.		Required: true

LogRedactionPolicy

LogRedactionPolicy controls what is scrubbed from agent runtime logs.

Appears in:

• AgentLogging

Field	Description	Default	Validation
secrets boolean	Secrets scrubs values sourced from secretKeyRef from tool call args and results.	true	Optional: true
pii boolean	PII scrubs common PII patterns (email addresses, IP addresses, phone numbers) from tool call args and results.		Optional: true

LoopCompressionConfig

LoopCompressionConfig controls when and how the runner compresses accumulated context.

Appears in:

• AgentLoopPolicy

Field	Description	Default	Validation
threshold float	Threshold is the fraction of the resolved context window at which compression is triggered. Must be between 0.5 and 0.95.	0.75	Maximum: 0.95 Minimum: 0.5 Optional: true
preserveRecentTurns integer	PreserveRecentTurns is the number of most recent turns kept verbatim during compression. The system prompt is always preserved.	4	Optional: true
model string	Model is the model used for the compression call. A cheap fast model is recommended (e.g. claude-haiku-4-5-20251001). Defaults to claude-haiku-4-5-20251001 when unset.		Optional: true
timeoutSeconds integer	TimeoutSeconds is the maximum time allowed for the compression model call. If exceeded compression is skipped and a CompressionTimeout warning event is recorded.	30	Optional: true
contextWindow integer	ContextWindow explicitly sets the model's context window size in tokens. When set, overrides provider metadata and the built-in model map. Useful for custom or private model endpoints.		Optional: true
instructions string	Instructions overrides the built-in system prompt for the compression call.		Optional: true

LoopSpec

LoopSpec defines loop behaviour for a pipeline step.

Appears in:

• SwarmTeamPipelineStep

Field	Description	Default	Validation
condition string	Condition is a Go template expression evaluated after each iteration. The step repeats while this evaluates to a truthy value ("true", non-empty, non-"false", non-"0"). Example: "{{ gt (len .steps.collect.output) 0 }}"		Required: true
maxIterations integer	MaxIterations caps the number of loop repetitions to prevent infinite loops.	10	Maximum: 100 Minimum: 1

MCPBinding

MCPBinding maps a capability ID to the MCP server URL that provides it in this deployment. Used to resolve MCPServerSpec.capabilityRef at reconcile time so that shared agent definitions (e.g. from cookbook) remain URL-free.

Appears in:

• SwarmRegistrySpec

Field	Description	Default	Validation
capabilityId string	CapabilityID is the capability identifier to resolve. Must match MCPServerSpec.capabilityRef on the referencing agent.		MinLength: 1 Required: true
url string	URL is the SSE endpoint of the MCP server that provides this capability.		MinLength: 1 Required: true

MCPHeader

MCPHeader defines a single HTTP header sent with every request to an MCP server. Exactly one of value or secretKeyRef must be set.

Appears in:

• MCPToolSpec

Field	Description	Default	Validation
name string	Name is the HTTP header name.		MinLength: 1 Required: true
value string	Value is a literal header value. Use for non-sensitive headers.		Optional: true
secretKeyRef SecretKeySelector	SecretKeyRef selects a key of a Secret for sensitive header values.		Optional: true

MCPServerAuth

MCPServerAuth configures authentication for a single MCP server connection. Exactly one of bearer or mtls must be set.

Appears in:

• MCPToolSpec

Field	Description	Default	Validation
bearer BearerAuth	Bearer configures Authorization: Bearer token authentication.		Optional: true
mtls MTLSAuth	MTLS configures mTLS client certificate authentication.		Optional: true

MCPToolSpec

MCPToolSpec defines one MCP server connection available to the agent. Exactly one of url or capabilityRef must be set.

Appears in:

• AgentTools
• SwarmTeamRole

Field	Description	Default	Validation
name string	Name is a unique identifier for this MCP server within the agent. Used in guardrails.tools allow/deny patterns: "<name>/<tool>".		MinLength: 1 Required: true
url string	URL is the direct SSE endpoint of the MCP server. Mutually exclusive with capabilityRef.		Optional: true
capabilityRef string	CapabilityRef names a capability ID in the namespace's SwarmRegistry. The operator resolves the actual MCP server URL at reconcile time. Use this in shareable agent definitions so the URL is supplied per-deployment. Mutually exclusive with url.		Optional: true
trust ToolTrustLevel	Trust classifies the trust level of this MCP server. Defaults to the guardrails.tools.trust.default when unset.		Enum: [internal external sandbox] Optional: true
instructions string	Instructions is operational context injected into the agent's system prompt for this tool server. Use for deployment-specific constraints (branch, project key, environment). General tool documentation belongs in the MCP tool's own description.		Optional: true
auth MCPServerAuth	Auth configures authentication for this MCP server. When not set the connection is unauthenticated.		Optional: true
headers MCPHeader array	Headers is a list of HTTP headers sent with every request to this MCP server.		Optional: true

MTLSAuth

MTLSAuth configures mTLS client certificate authentication for an MCP server. The Secret is mounted as a read-only volume inside the agent pod. It must contain tls.crt, tls.key, and optionally ca.crt.

Appears in:

• MCPServerAuth

Field	Description	Default	Validation
secretRef LocalObjectReference	SecretRef names the Secret containing the TLS credentials.

MemoryBackend

Underlying type: string

MemoryBackend defines the memory storage strategy for an agent.

Validation:

• Enum: [in-context vector-store redis]

Appears in:

• SwarmMemorySpec
• SwarmSettingsSpec

Field	Description
in-context
vector-store
redis

NetworkPolicyMode

Underlying type: string

NetworkPolicyMode controls how the operator generates a NetworkPolicy for agent pods.

Validation:

• Enum: [default strict disabled]

Appears in:

• SwarmAgentSpec

Field	Description
default	NetworkPolicyModeDefault allows DNS, Redis, and open HTTPS egress.
strict	NetworkPolicyModeStrict allows DNS and Redis egress only; HTTPS egress is restricted to the resolved IPs of declared MCP servers.
disabled	NetworkPolicyModeDisabled skips NetworkPolicy generation entirely. Use when the cluster CNI (Cilium, Calico) manages network policy externally.

NotifyChannelSpec

NotifyChannelSpec defines a single notification channel.

Appears in:

• SwarmNotifySpec

Field	Description	Default	Validation
type NotifyChannelType	Type determines the channel implementation.		Enum: [webhook slack]
webhook WebhookChannelSpec	Webhook configures a generic HTTP POST channel. Required when type is "webhook".		Optional: true
slack SlackChannelSpec	Slack configures a Slack incoming webhook channel. Required when type is "slack".		Optional: true
template string	Template is an optional Go template for the message body. Context is NotifyPayload. Overrides the channel's default format. For "webhook": template output is the raw POST body. For "slack": template output replaces the default Block Kit message text.		Optional: true

NotifyChannelType

Underlying type: string

NotifyChannelType determines which channel implementation to use.

Validation:

• Enum: [webhook slack]

Appears in:

• NotifyChannelSpec

Field	Description
webhook
slack

NotifyDispatchResult

NotifyDispatchResult records the most recent dispatch attempt for one channel.

Appears in:

• SwarmNotifyStatus

Field	Description	Default	Validation
channelIndex integer	ChannelIndex is the zero-based index of the channel in spec.channels.
lastFiredAt Time	LastFiredAt is when the most recent dispatch attempt was made.		Optional: true
lastEvent NotifyEvent	LastEvent is the event type that triggered the most recent dispatch.		Enum: [TeamSucceeded TeamFailed TeamTimedOut BudgetWarning BudgetExceeded DailyLimitReached AgentDegraded] Optional: true
succeeded boolean	Succeeded is false when all retry attempts failed.
error string	Error is the last error message when Succeeded is false.		Optional: true

NotifyEvent

Underlying type: string

NotifyEvent is the type of event that triggers a notification.

Validation:

• Enum: [TeamSucceeded TeamFailed TeamTimedOut BudgetWarning BudgetExceeded DailyLimitReached AgentDegraded]

Appears in:

• NotifyDispatchResult
• SwarmNotifySpec

Field	Description
TeamSucceeded
TeamFailed
TeamTimedOut
BudgetWarning
BudgetExceeded
DailyLimitReached
AgentDegraded

PluginEndpoint

PluginEndpoint defines a gRPC plugin connection address and optional TLS config.

Appears in:

• AgentPlugins

Field	Description	Default	Validation
address string	Address is the host:port of the gRPC plugin server.		MinLength: 1 Required: true
tls PluginTLSConfig	TLS configures mTLS for the gRPC connection. When not set the connection is plaintext.		Optional: true

PluginTLSConfig

PluginTLSConfig references a Secret containing TLS credentials for a gRPC plugin. The Secret must contain tls.crt, tls.key, and ca.crt.

Appears in:

• PluginEndpoint

Field	Description	Default	Validation
secretRef LocalObjectReference	SecretRef names the Secret containing the TLS credentials.

PromptFragment

PromptFragment is one composable piece of text injected into the agent system prompt. Fragments from multiple SwarmSettings objects are composed using the settingsRefs list on SwarmAgent or SwarmTeamRole. Within a single SwarmSettings, fragments are applied in list order. When the same fragment name appears in multiple referenced settings, the last occurrence wins.

Appears in:

• SwarmSettingsSpec

Field	Description	Default	Validation
name string	Name identifies this fragment. Must be unique within the SwarmSettings object. Used for override resolution when the same name appears in multiple settings.		MinLength: 1 Required: true
text string	Text is the fragment content. May be multi-line.		Required: true
position string	Position controls where this fragment is injected relative to the agent's systemPrompt. prepend — inserted before systemPrompt (persona, context, constraints) append — inserted after systemPrompt (output rules, closing instructions)	append	Enum: [prepend append]

PromptFragments

PromptFragments holds reusable prompt components. Deprecated: use Fragments instead. Retained for backward compatibility.

Appears in:

• SwarmSettingsSpec

Field	Description	Default	Validation
persona string	Persona is a persona/role description prepended to the system prompt. Deprecated: define a PromptFragment with position=prepend instead.
outputRules string	OutputRules defines output format constraints appended to the system prompt. Deprecated: define a PromptFragment with position=append instead.

RedisMemoryConfig

RedisMemoryConfig configures the Redis memory backend.

Appears in:

• SwarmMemorySpec

Field	Description	Default	Validation
secretRef LocalObjectReference	SecretRef names a Secret whose REDIS_URL key is injected into agent pods.
ttlSeconds integer	TTLSeconds is how long memory entries are retained. 0 means no expiry.	3600
maxEntries integer	MaxEntries caps the number of stored entries per agent instance. 0 means unlimited.

RegistryLookupSpec

RegistryLookupSpec configures runtime agent resolution via SwarmRegistry.

Appears in:

• SwarmTeamPipelineStep

Field	Description	Default	Validation
capability string	Capability is the exact capability ID to match.		MinLength: 1 Required: true
tags string array	Tags narrows candidates to agents that declare ALL listed tags.		Optional: true
strategy RegistryLookupStrategy	Strategy controls which agent is selected when multiple match.	least-busy	Enum: [least-busy round-robin random]
registryRef LocalObjectReference	RegistryRef names the SwarmRegistry to query. Defaults to first registry in namespace.		Optional: true
fallback string	Fallback is the role/agent name to use when no agent matches. If unset and no match, the step fails with RegistryLookupFailed.		Optional: true

RegistryLookupStrategy

Underlying type: string

RegistryLookupStrategy controls which agent wins when multiple match.

Validation:

• Enum: [least-busy round-robin random]

Appears in:

• RegistryLookupSpec

Field	Description
least-busy
round-robin
random

RegistryScope

Underlying type: string

RegistryScope controls which SwarmAgents are indexed by an SwarmRegistry.

Validation:

• Enum: [namespace-scoped cluster-wide]

Appears in:

• SwarmRegistrySpec

Field	Description
namespace-scoped	RegistryScopeNamespace indexes only SwarmAgents in the same namespace (default).
cluster-wide	RegistryScopeCluster indexes all SwarmAgents cluster-wide. Requires a ClusterRole that grants cross-namespace SwarmAgent reads.

SlackChannelSpec

SlackChannelSpec configures a Slack incoming webhook notification channel.

Appears in:

• NotifyChannelSpec

Field	Description	Default	Validation
webhookURLFrom SecretKeySelector	WebhookURLFrom reads the Slack incoming webhook URL from a Secret key.

StepContextPolicy

StepContextPolicy controls how a step's output is prepared before injection into downstream step prompts via "{{ .steps.<name>.output }}".

Appears in:

• SwarmRunSpec
• SwarmTeamPipelineStep
• SwarmTeamSpec

Field	Description	Default	Validation
strategy string	Strategy determines how the output is handled before downstream injection. full: verbatim injection wrapped in <swarm:step-output> (default, current behaviour). compress: output is summarised by an LLM call before injection. extract: a JSONPath or regexp is applied; only the matched value is injected. none: nothing is injected; "{{ .steps.<name>.output }}" resolves to "".	full	Enum: [full compress extract none]
compress ContextCompressConfig	Compress configures LLM-based summarisation. Only used when strategy=compress.		Optional: true
extract ContextExtractConfig	Extract configures field or pattern extraction. Only used when strategy=extract.		Optional: true

StepValidation

StepValidation configures output validation for a pipeline step. At least one of Contains, Schema, or Semantic must be set. When multiple modes are configured all must pass; evaluation order is Contains → Schema → Semantic (cheapest first).

Appears in:

• SwarmTeamPipelineStep

Field	Description	Default	Validation
contains string	Contains is a RE2 regular expression that must match somewhere in the step output. Avoid anchoring on multi-byte characters (e.g. emoji) — use substring match instead.		Optional: true
schema string	Schema is a JSON Schema string. The step output must be valid JSON that satisfies the schema's required fields and top-level property type constraints.		Optional: true
semantic string	Semantic is a natural-language validator prompt sent to an LLM. The LLM must respond with "PASS" (case-insensitive) for validation to pass. Use {{ .output }} in the prompt to embed the step output.		Optional: true
semanticModel string	SemanticModel overrides the LLM model used for semantic validation. Defaults to the step's SwarmAgent model when empty. Recommended: use a stronger model than the step agent to avoid grading its own output.		Optional: true
onFailure string	OnFailure controls what happens when validation fails. "fail" (default) marks the step Failed immediately. "retry" resets the step to Pending for re-execution.	fail	Enum: [fail retry] Optional: true
maxRetries integer	MaxRetries caps validation-level retries when OnFailure is "retry". Independent of queue-level task retries.	2	Maximum: 10 Minimum: 0 Optional: true
rejectPatterns string array	RejectPatterns is a list of RE2 regular expressions that act as a security gate against prompt injection. A match against any pattern causes the step to fail immediately with reason OutputRejected, regardless of other validation settings. Evaluated before Contains, Schema, and Semantic checks. Example: ["(?i)ignore.*previous.*instructions", "(?i)act as"]		Optional: true

SwarmAgent

SwarmAgent manages a pool of LLM agent instances.

Appears in:

• SwarmAgentList

Field	Description	Default	Validation
apiVersion string	kubeswarm.io/v1alpha1
kind string	SwarmAgent
metadata ObjectMeta	Refer to Kubernetes API documentation for fields of metadata.		Optional: true
spec SwarmAgentSpec			Required: true
status SwarmAgentStatus			Optional: true

SwarmAgentAutoscaling

SwarmAgentAutoscaling configures KEDA-based autoscaling for the agent's deployment. Requires KEDA v2 installed in the cluster. When set on an agent, runtime.replicas is ignored.

Appears in:

• AgentRuntime
• SwarmTeamRole

Field	Description	Default	Validation
minReplicas integer	MinReplicas is the minimum replica count (idle floor).	1	Minimum: 0 Optional: true
maxReplicas integer	MaxReplicas is the maximum replica count.	10	Minimum: 1 Optional: true
targetPendingTasks integer	TargetPendingTasks is the number of pending queue entries per replica used as the KEDA scale trigger. Scale-up fires when pending tasks exceed this threshold.	5	Minimum: 1 Optional: true

SwarmAgentList

SwarmAgentList contains a list of SwarmAgent.

Field	Description	Default	Validation
apiVersion string	kubeswarm.io/v1alpha1
kind string	SwarmAgentList
metadata ListMeta	Refer to Kubernetes API documentation for fields of metadata.
items SwarmAgent array

SwarmAgentMCPStatus

SwarmAgentMCPStatus reports the last observed health of one MCP server.

Appears in:

• SwarmAgentStatus

Field	Description	Default	Validation
name string	Name matches MCPToolSpec.name.
url string	URL is the MCP server endpoint that was probed.
healthy boolean	Healthy is true when the last probe received a non-5xx HTTP response.
message string	Message holds error detail when Healthy is false.		Optional: true
lastCheck Time	LastCheck is when the probe was last run.		Optional: true

SwarmAgentSpec

SwarmAgentSpec defines the desired state of a SwarmAgent.

Appears in:

• SwarmAgent

Field	Description	Default	Validation
model string	Model is the LLM model ID (e.g. "claude-sonnet-4-6").		MinLength: 1 Required: true
prompt AgentPrompt	Prompt configures the agent's system prompt.		Required: true
settings LocalObjectReference array	Settings references SwarmSettings objects whose fragments are composed into this agent's system prompt, in list order. Last occurrence wins for duplicate keys.		Optional: true
capabilities AgentCapability array	Capabilities advertises what this agent can do to SwarmRegistry and the MCP gateway. Agents without capabilities are invisible to registry lookups.		Optional: true
tools AgentTools	Tools groups MCP server connections and inline webhook tools.		Optional: true
agents AgentConnection array	Agents lists other SwarmAgent or registry capabilities callable as tools via A2A.		Optional: true
guardrails AgentGuardrails	Guardrails groups tool permissions, budget enforcement, and execution limits.		Optional: true
runtime AgentRuntime	Runtime groups replica count, autoscaling, resources, and loop policy.		Optional: true
registryRef LocalObjectReference	RegistryRef names the SwarmRegistry this agent registers into. Defaults to "default". Omit to opt out of all registry indexing.		Optional: true
networkPolicy NetworkPolicyMode	NetworkPolicy controls the NetworkPolicy generated for agent pods. default: DNS + Redis + open HTTPS egress. strict: DNS + Redis; HTTPS egress restricted to declared MCP server IPs. disabled: no NetworkPolicy generated (use when CNI manages policy externally).	default	Enum: [default strict disabled] Optional: true
apiKeyRef SecretKeySelector	APIKeyRef injects an LLM provider API key from a native Kubernetes Secret. The key is set as the environment variable named by the Secret key (e.g. key "ANTHROPIC_API_KEY" in Secret "my-keys" sets ANTHROPIC_API_KEY). For multiple keys or complex setups, use envFrom instead.		Optional: true
envFrom EnvFromSource array	EnvFrom injects environment variables from Secrets or ConfigMaps into agent pods. Entries listed here take precedence over the global kubeswarm-api-keys Secret.		Optional: true
plugins AgentPlugins	Plugins configures external gRPC provider or queue overrides (RFC-0025).		Optional: true
observability AgentObservability	Observability groups health check, logging, and metrics configuration.		Optional: true

SwarmAgentStatus

SwarmAgentStatus defines the observed state of SwarmAgent.

Appears in:

• SwarmAgent

Field	Description	Default	Validation
readyReplicas integer	ReadyReplicas is the number of agent pods ready to accept tasks.
replicas integer	Replicas is the total number of agent pods (ready or not).
desiredReplicas integer	DesiredReplicas is the autoscaling-computed target replica count. Nil for standalone agents not managed by a team autoscaler.		Optional: true
pendingTasks integer	PendingTasks is the current number of tasks waiting in the queue for this agent.		Optional: true
observedGeneration integer	ObservedGeneration is the .metadata.generation this status reflects.
dailyTokenUsage TokenUsage	DailyTokenUsage is the sum of tokens consumed in the rolling 24-hour window. Populated only when guardrails.limits.dailyTokens is set.		Optional: true
mcpServers SwarmAgentMCPStatus array	MCPServers reports the last observed connectivity state of each configured MCP server.		Optional: true
systemPromptHash string	SystemPromptHash is the SHA-256 hex digest of the resolved system prompt last applied.		Optional: true
exposedMCPCapabilities string array	ExposedMCPCapabilities lists the capability names currently registered at the MCP gateway.		Optional: true
conditions Condition array	Conditions reflect the current state of the SwarmAgent.

SwarmBudget

SwarmBudget defines a spend limit for one or more SwarmTeams. The SwarmBudgetController recalculates status every 5 minutes by querying the configured SpendStore. When hardStop is true, the SwarmRunReconciler blocks new runs that would violate the budget.

Appears in:

• SwarmBudgetList

Field	Description	Default	Validation
apiVersion string	kubeswarm.io/v1alpha1
kind string	SwarmBudget
metadata ObjectMeta	Refer to Kubernetes API documentation for fields of metadata.
spec SwarmBudgetSpec			Required: true
status SwarmBudgetStatus			Optional: true

SwarmBudgetList

SwarmBudgetList contains a list of SwarmBudget.

Field	Description	Default	Validation
apiVersion string	kubeswarm.io/v1alpha1
kind string	SwarmBudgetList
metadata ListMeta	Refer to Kubernetes API documentation for fields of metadata.
items SwarmBudget array

SwarmBudgetSelector

SwarmBudgetSelector scopes a budget to a subset of resources.

Appears in:

• SwarmBudgetSpec

Field	Description	Default	Validation
namespace string	Namespace scopes this budget to a single namespace. Empty means all namespaces in the cluster.		Optional: true
team string	Team scopes this budget to a single SwarmTeam by name. Empty means all teams in the selected namespace(s).		Optional: true
matchLabels object (keys:string, values:string)	MatchLabels selects SwarmTeams by label. Applied in addition to Namespace/Team.		Optional: true

SwarmBudgetSpec

SwarmBudgetSpec defines the desired state of an SwarmBudget.

Appears in:

• SwarmBudget

Field	Description	Default	Validation
selector SwarmBudgetSelector	Selector scopes this budget to matching resources.		Required: true
period string	Period is the rolling window for spend accumulation.	monthly	Enum: [daily weekly monthly] Optional: true
limit float	Limit is the maximum spend in the configured currency for one period.		Minimum: 0
currency string	Currency is the ISO 4217 currency code. Must match the operator's CostProvider.	USD	Optional: true
warnAt integer	WarnAt is the percentage of the limit at which a BudgetWarning notification fires (0–100). Zero disables warnings. Default: 80.	80	Maximum: 100 Minimum: 0 Optional: true
hardStop boolean	HardStop blocks new SwarmRuns when the limit is exceeded. When false (default), runs continue but a BudgetExceeded notification fires. When true, new SwarmRuns fail immediately with BudgetExceeded before any tokens are spent.	false	Optional: true
notifyRef LocalObjectReference	NotifyRef references an SwarmNotify policy for budget alerts. Fires BudgetWarning (at warnAt%) and BudgetExceeded (at 100%).		Optional: true

SwarmBudgetStatus

SwarmBudgetStatus defines the observed state of an SwarmBudget.

Appears in:

• SwarmBudget

Field	Description	Default	Validation
phase BudgetStatus	Phase summarises the current budget state.		Enum: [OK Warning Exceeded]
spentUSD float	SpentUSD is the total spend in the current period window.		XIntOrString: {}
pctUsed float	PctUsed is SpentUSD / Limit as a percentage (0–100).
periodStart Time	PeriodStart is the start of the current budget window.		Optional: true
lastUpdated Time	LastUpdated is when the status was last recalculated.		Optional: true
observedGeneration integer	ObservedGeneration is the .metadata.generation this status reflects.
conditions Condition array	Conditions reflect the current state of the budget.

SwarmEvent

SwarmEvent fires SwarmTeam pipeline runs in response to external events: a cron schedule, an inbound HTTP webhook, or another team pipeline completing.

Appears in:

• SwarmEventList

Field	Description	Default	Validation
apiVersion string	kubeswarm.io/v1alpha1
kind string	SwarmEvent
metadata ObjectMeta	Refer to Kubernetes API documentation for fields of metadata.		Optional: true
spec SwarmEventSpec			Required: true
status SwarmEventStatus			Optional: true

SwarmEventList

SwarmEventList contains a list of SwarmEvent.

Field	Description	Default	Validation
apiVersion string	kubeswarm.io/v1alpha1
kind string	SwarmEventList
metadata ListMeta	Refer to Kubernetes API documentation for fields of metadata.
items SwarmEvent array

SwarmEventSource

SwarmEventSource defines what fires the trigger.

Appears in:

• SwarmEventSpec

Field	Description	Default	Validation
type TriggerSourceType	Type is the source type: cron | webhook | team-output.		Enum: [cron webhook team-output] Required: true
cron string	Cron is a standard 5-field cron expression (minute hour dom month dow). Only used when type=cron. Example: "0 9 * * 1-5" (9am on weekdays)
teamOutput TeamOutputSource	TeamOutput triggers when the named SwarmTeam pipeline reaches a phase. Only used when type=team-output.

SwarmEventSpec

SwarmEventSpec defines the desired state of SwarmEvent.

Appears in:

• SwarmEvent

Field	Description	Default	Validation
source SwarmEventSource	Source defines what fires this trigger.		Required: true
targets SwarmEventTarget array	Targets is the list of team pipelines to dispatch when the trigger fires.		MinItems: 1 Required: true
concurrencyPolicy ConcurrencyPolicy	ConcurrencyPolicy controls what happens when the trigger fires while a previous run is still in progress. Defaults to Allow.	Allow	Enum: [Allow Forbid]
suspended boolean	Suspended pauses the trigger without deleting it.	false

SwarmEventStatus

SwarmEventStatus defines the observed state of SwarmEvent.

Appears in:

• SwarmEvent

Field	Description	Default	Validation
lastFiredAt Time	LastFiredAt is when the trigger last dispatched team runs.
nextFireAt Time	NextFireAt is the next scheduled fire time (cron type only).
firedCount integer	FiredCount is the total number of times this trigger has fired.
webhookURL string	WebhookURL is the URL to POST to in order to fire this trigger (webhook type only). Requires --trigger-webhook-url to be configured on the operator.
observedGeneration integer	ObservedGeneration is the .metadata.generation this status reflects.
conditions Condition array	Conditions reflect the current state of the trigger.

SwarmEventTarget

SwarmEventTarget describes what to dispatch when the trigger fires. Exactly one of Team or Agent must be set.

Appears in:

• SwarmEventSpec

Field	Description	Default	Validation
team string	Team is the name of the SwarmTeam to dispatch a pipeline run for. Exactly one of Team or Agent must be set.		Optional: true
agent string	Agent is the name of the SwarmAgent to invoke directly. When set, the event creates an SwarmRun with spec.agent and spec.prompt. Exactly one of Team or Agent must be set.		Optional: true
prompt string	Prompt is the task text submitted to the agent when Agent is set. Supports Go template syntax evaluated with the trigger fire context: {{ .trigger.name }} — trigger name {{ .trigger.firedAt }} — RFC3339 fire timestamp {{ .trigger.body.* }} — JSON fields from the webhook request body (webhook type only) {{ .trigger.output }} — upstream team output (team-output type only)		Optional: true
input object (keys:string, values:string)	Input values to set on the dispatched team pipeline, overriding the template team's inputs. Values are Go template strings evaluated with the trigger fire context (same as Prompt). Only used when Team is set.		Optional: true

SwarmFlowStepPhase

Underlying type: string

SwarmFlowStepPhase describes the execution state of a single pipeline step.

Validation:

• Enum: [Pending WarmingUp Running Validating Succeeded Failed Skipped]

Appears in:

• SwarmFlowStepStatus

Field	Description
Pending
WarmingUp	SwarmFlowStepPhaseWarmingUp means the step is waiting for its assigned agent's pods to become ready after a scale-from-zero event. Transitions to Running once ready.
Running
Validating	SwarmFlowStepPhaseValidating means the step completed and is awaiting output validation.
Succeeded
Failed
Skipped	SwarmFlowStepPhaseSkipped means the step was bypassed because its If condition evaluated to false.

SwarmFlowStepStatus

SwarmFlowStepStatus captures the observed state of a single step.

Appears in:

• SwarmRunStatus

Field	Description	Default	Validation
name string	Name matches the step name in spec.
phase SwarmFlowStepPhase	Phase is the current execution phase.		Enum: [Pending WarmingUp Running Validating Succeeded Failed Skipped]
taskID string	TaskID is the Redis stream message ID of the submitted task, used to correlate results from the agent-tasks-results stream.
output string	Output is the agent's response after context policy has been applied. For strategy=full this is the verbatim agent output (current behaviour). For strategy=compress this is the compressed summary. For strategy=extract this is the extracted value. For strategy=none this is empty.
rawOutput string	RawOutput is the original unprocessed agent output. Only populated when contextPolicy.strategy is compress or extract, so downstream steps can access pre-policy output via "{{ .steps.<name>.rawOutput }}".		Optional: true
compressionTokens integer	CompressionTokens is the token count of the compressed output. Only populated when contextPolicy.strategy=compress.		Optional: true
outputJSON string	OutputJSON is the agent's response as a JSON string, populated when the step has an OutputSchema and the response is valid JSON. Downstream steps can reference fields via "{{ .steps.<name>.data.<field> }}".
startTime Time	StartTime is when the step started executing.
completionTime Time	CompletionTime is when the step finished (success or failure).
message string	Message holds a human-readable status detail.
iterations integer	Iterations is the number of times this step has been executed (for loop steps).
tokenUsage TokenUsage	TokenUsage reports the tokens consumed by this step's LLM calls.
costUSD float	CostUSD is the estimated dollar cost of this step's LLM calls, calculated using the operator's configured CostProvider. Zero for unknown/local models.
validationAttempts integer	ValidationAttempts counts how many times output validation has been run on this step. Incremented on each validation attempt; reset when the step is retried from Pending.
validationMessage string	ValidationMessage holds the most recent validation failure reason. Cleared when validation passes.
artifacts object (keys:string, values:string)	Artifacts maps artifact names to their storage URLs or local paths. Populated after the step completes when spec.artifactStore is configured. Downstream steps reference artifacts via "{{ .steps.<name>.artifacts.<key> }}".
resolvedAgent string	ResolvedAgent is the SwarmAgent name selected by a registry lookup for this step. Empty when the step uses a static role reference.		Optional: true
selectedCapability string	SelectedCapability is the capability ID chosen by the router LLM. Only set for the synthetic "route" step in routed-mode runs.		Optional: true
routingReason string	RoutingReason is the router LLM's one-sentence explanation for its choice. Only set for the synthetic "route" step in routed-mode runs.		Optional: true

SwarmMemory

SwarmMemory defines the persistent memory backend for agent instances. Reference it from an SwarmAgent via spec.memoryRef to give agents durable memory across tasks.

Appears in:

• SwarmMemoryList

Field	Description	Default	Validation
apiVersion string	kubeswarm.io/v1alpha1
kind string	SwarmMemory
metadata ObjectMeta	Refer to Kubernetes API documentation for fields of metadata.		Optional: true
spec SwarmMemorySpec			Required: true
status SwarmMemoryStatus			Optional: true

SwarmMemoryList

SwarmMemoryList contains a list of SwarmMemory.

Field	Description	Default	Validation
apiVersion string	kubeswarm.io/v1alpha1
kind string	SwarmMemoryList
metadata ListMeta	Refer to Kubernetes API documentation for fields of metadata.
items SwarmMemory array

SwarmMemorySpec

SwarmMemorySpec defines the desired memory configuration.

Appears in:

• SwarmMemory

Field	Description	Default	Validation
backend MemoryBackend	Backend selects the memory storage strategy.		Enum: [in-context vector-store redis] Required: true
redis RedisMemoryConfig	Redis configures the Redis backend. Required when backend is "redis".
vectorStore VectorStoreMemoryConfig	VectorStore configures the vector-store backend. Required when backend is "vector-store".
embedding EmbeddingConfig	Embedding configures the embedding model used for vector memory operations (RFC-0026). Required when backend is "vector-store". The operator injects the resolved model ID, provider, and API key reference as environment variables into agent pods.		Optional: true

SwarmMemoryStatus

SwarmMemoryStatus defines the observed state of SwarmMemory.

Appears in:

• SwarmMemory

Field	Description	Default	Validation
observedGeneration integer	ObservedGeneration is the .metadata.generation this status reflects.
conditions Condition array	Conditions reflect the current state of the SwarmMemory.

SwarmNotify

SwarmNotify defines a reusable notification policy that routes run events to one or more channels (Slack, generic webhook, etc.).

Appears in:

• SwarmNotifyList

Field	Description	Default	Validation
apiVersion string	kubeswarm.io/v1alpha1
kind string	SwarmNotify
metadata ObjectMeta	Refer to Kubernetes API documentation for fields of metadata.		Optional: true
spec SwarmNotifySpec			Required: true
status SwarmNotifyStatus			Optional: true

SwarmNotifyList

SwarmNotifyList contains a list of SwarmNotify.

Field	Description	Default	Validation
apiVersion string	kubeswarm.io/v1alpha1
kind string	SwarmNotifyList
metadata ListMeta	Refer to Kubernetes API documentation for fields of metadata.
items SwarmNotify array

SwarmNotifySpec

SwarmNotifySpec defines the desired state of SwarmNotify.

Appears in:

• SwarmNotify

Field	Description	Default	Validation
on NotifyEvent array	On lists the events that trigger notifications. If empty, all events fire.		Enum: [TeamSucceeded TeamFailed TeamTimedOut BudgetWarning BudgetExceeded DailyLimitReached AgentDegraded] Optional: true
channels NotifyChannelSpec array	Channels lists the notification targets.		MinItems: 1
rateLimitSeconds integer	RateLimitSeconds is the minimum interval between notifications for the same (team, event) pair. Default: 300. Set to 0 to disable rate limiting.	300	Minimum: 0 Optional: true

SwarmNotifyStatus

SwarmNotifyStatus defines the observed state of SwarmNotify.

Appears in:

• SwarmNotify

Field	Description	Default	Validation
lastDispatches NotifyDispatchResult array	LastDispatches records the most recent dispatch result per channel index.		Optional: true
conditions Condition array	Conditions reflect the current state of the SwarmNotify.		Optional: true

SwarmRegistry

SwarmRegistry is a Kubernetes-native capability index that lets pipeline steps resolve an agent at runtime by what it can do rather than by a hardcoded name. Agents advertise capabilities via spec.capabilities on SwarmAgentSpec.

Appears in:

• SwarmRegistryList

Field	Description	Default	Validation
apiVersion string	kubeswarm.io/v1alpha1
kind string	SwarmRegistry
metadata ObjectMeta	Refer to Kubernetes API documentation for fields of metadata.		Optional: true
spec SwarmRegistrySpec			Optional: true
status SwarmRegistryStatus			Optional: true

SwarmRegistryList

SwarmRegistryList contains a list of SwarmRegistry.

Field	Description	Default	Validation
apiVersion string	kubeswarm.io/v1alpha1
kind string	SwarmRegistryList
metadata ListMeta	Refer to Kubernetes API documentation for fields of metadata.
items SwarmRegistry array

SwarmRegistryPolicy

SwarmRegistryPolicy controls delegation safety for registry-resolved steps.

Appears in:

• SwarmRegistrySpec

Field	Description	Default	Validation
maxDepth integer	MaxDepth is the maximum agent-to-agent delegation depth. Prevents runaway recursion.	3	Maximum: 20 Minimum: 1
allowCrossTeam boolean	AllowCrossTeam permits resolution of agents managed by other SwarmTeams. Default false — only agents not owned by another team's inline roles.	false

SwarmRegistrySpec

SwarmRegistrySpec defines the desired state of SwarmRegistry.

Appears in:

• SwarmRegistry

Field	Description	Default	Validation
scope RegistryScope	Scope controls which SwarmAgents are indexed. namespace-scoped: only SwarmAgents in the same namespace (default). cluster-wide: all SwarmAgents cluster-wide (requires ClusterRole).	namespace-scoped	Enum: [namespace-scoped cluster-wide]
policy SwarmRegistryPolicy	Policy controls delegation safety.		Optional: true
mcpBindings MCPBinding array	MCPBindings maps capability IDs to MCP server URLs for this deployment. Agents that declare mcpServers with capabilityRef have their URLs resolved from this list at reconcile time. This allows cookbook-style agent definitions to remain URL-free; operators supply the bindings per namespace.		Optional: true

SwarmRegistryStatus

SwarmRegistryStatus defines the observed state of SwarmRegistry.

Appears in:

• SwarmRegistry

Field	Description	Default	Validation
indexedAgents integer	IndexedAgents is the total number of SwarmAgents indexed by this registry.
fleet AgentFleetEntry array	Fleet is the list of SwarmAgents currently registered with this registry, with per-agent readiness and token usage. Replaces the implicit "all agents in namespace" model with an explicit opt-in list.		Optional: true
lastRebuild Time	LastRebuild is the time the index was last rebuilt.		Optional: true
capabilities IndexedCapability array	Capabilities lists all capabilities indexed, with their associated agents and tags.		Optional: true
observedGeneration integer	ObservedGeneration is the .metadata.generation this status reflects.
conditions Condition array	Conditions reflect the current state of the SwarmRegistry.

SwarmRun

SwarmRun is an immutable execution record. It covers both standalone agent invocations (spec.agent + spec.prompt) and team pipeline runs (spec.teamRef). Created automatically by SwarmEvent or directly via kubectl apply.

Appears in:

• SwarmRunList

Field	Description	Default	Validation
apiVersion string	kubeswarm.io/v1alpha1
kind string	SwarmRun
metadata ObjectMeta	Refer to Kubernetes API documentation for fields of metadata.
spec SwarmRunSpec			Required: true
status SwarmRunStatus			Optional: true

SwarmRunList

SwarmRunList contains a list of SwarmRun.

Field	Description	Default	Validation
apiVersion string	kubeswarm.io/v1alpha1
kind string	SwarmRunList
metadata ListMeta	Refer to Kubernetes API documentation for fields of metadata.
items SwarmRun array

SwarmRunPhase

Underlying type: string

SwarmRunPhase describes the overall execution state of an SwarmRun.

Validation:

• Enum: [Pending Running Succeeded Failed]

Appears in:

• SwarmRunStatus
• SwarmTeamStatus

Field	Description
Pending
Running
Succeeded
Failed

SwarmRunSpec

SwarmRunSpec is an immutable snapshot of everything needed to execute one run. Exactly one of TeamRef or Agent must be set. For team runs it is populated at trigger time from the parent SwarmTeam spec. For standalone agent runs only Agent and Prompt are required.

Appears in:

• SwarmRun

Field	Description	Default	Validation
teamRef string	TeamRef is the name of the SwarmTeam that owns this run. Exactly one of TeamRef or Agent must be set.		Optional: true
agent string	Agent is the name of the SwarmAgent to invoke for a standalone run. Exactly one of TeamRef or Agent must be set.		Optional: true
prompt string	Prompt is the task text submitted to the agent for a standalone run. Required when Agent is set.		Optional: true
teamGeneration integer	TeamGeneration is the SwarmTeam spec.generation at the time this run was created. Allows correlating a run with the exact team spec that was in effect. Only set for team runs.		Optional: true
input object (keys:string, values:string)	Input is the resolved input map for this run: team default inputs merged with any per-trigger overrides supplied via swarm trigger --input or SwarmEvent. Step inputs reference these values via "{{ .input.<key> }}".		Optional: true
pipeline SwarmTeamPipelineStep array	Pipeline is a snapshot of the SwarmTeam pipeline DAG at trigger time. Empty for routed-mode runs.		Optional: true
defaultContextPolicy StepContextPolicy	DefaultContextPolicy is a snapshot of the team's defaultContextPolicy at trigger time. Applied to non-adjacent step references; per-step contextPolicy takes precedence.		Optional: true
roles SwarmTeamRole array	Roles is a snapshot of the SwarmTeam role definitions at trigger time. Empty for routed-mode runs.		Optional: true
output string	Output is a Go template expression that selects the final run result. Example: "{{ .steps.summarize.output }}" For routed-mode runs this defaults to "{{ .steps.route.output }}" at trigger time.		Optional: true
routing SwarmTeamRoutingSpec	Routing is a snapshot of the SwarmTeam routing config at trigger time. Set when the team operates in routed mode. Mutually exclusive with Pipeline.		Optional: true
timeoutSeconds integer	TimeoutSeconds is the maximum wall-clock seconds this run may take. Zero means no timeout.		Minimum: 1 Optional: true
maxTokens integer	MaxTokens is the total token budget for this run across all steps. Zero means no limit.		Minimum: 1 Optional: true

SwarmRunStatus

SwarmRunStatus defines the observed execution state of an SwarmRun.

Appears in:

• SwarmRun

Field	Description	Default	Validation
phase SwarmRunPhase	Phase is the overall execution state.		Enum: [Pending Running Succeeded Failed]
steps SwarmFlowStepStatus array	Steps holds the per-step execution state for this run, including full step outputs. Unlike SwarmTeam.Status, this is never reset — it is the permanent record of what happened during this run.
output string	Output is the resolved final pipeline output once phase is Succeeded.
startTime Time	StartTime is when this run began executing.
completionTime Time	CompletionTime is when this run reached a terminal phase (Succeeded or Failed).
totalTokenUsage TokenUsage	TotalTokenUsage is the sum of token usage across all steps in this run.
totalCostUSD float	TotalCostUSD is the estimated total dollar cost of this run, summed across all steps using the operator's configured CostProvider.
observedGeneration integer	ObservedGeneration is the .metadata.generation this status reflects.
conditions Condition array	Conditions reflect the current state of the SwarmRun.

SwarmSettings

SwarmSettings holds shared configuration consumed by SwarmAgents.

Appears in:

• SwarmSettingsList

Field	Description	Default	Validation
apiVersion string	kubeswarm.io/v1alpha1
kind string	SwarmSettings
metadata ObjectMeta	Refer to Kubernetes API documentation for fields of metadata.		Optional: true
spec SwarmSettingsSpec			Required: true
status SwarmSettingsStatus			Optional: true

SwarmSettingsList

SwarmSettingsList contains a list of SwarmSettings.

Field	Description	Default	Validation
apiVersion string	kubeswarm.io/v1alpha1
kind string	SwarmSettingsList
metadata ListMeta	Refer to Kubernetes API documentation for fields of metadata.
items SwarmSettings array

SwarmSettingsSecurity

SwarmSettingsSecurity defines operator-level MCP security policy enforced at admission time. The admission webhook loads all SwarmSettings in a namespace and applies the strictest policy found — a single settings object with requireMCPAuth: true enforces it on all agents.

Appears in:

• SwarmSettingsSpec

Field	Description	Default	Validation
mcpAllowlist string array	MCPAllowlist is a list of URL prefixes. When set, the admission webhook rejects SwarmAgent specs that reference MCP server URLs not matching any listed prefix. Use this to prevent agents from calling arbitrary external MCP endpoints (T9). Example: ["https://search.mcp.example.com/", "https://browser.mcp.example.com/"]		Optional: true
requireMCPAuth boolean	RequireMCPAuth: when true, the webhook rejects SwarmAgent specs that declare MCP servers without an auth configuration (spec.mcpServers[*].auth.type must not be "none"). Ensures no agent can call an MCP server without verified credentials.		Optional: true

SwarmSettingsSpec

SwarmSettingsSpec defines the shared configuration values.

Appears in:

• SwarmSettings

Field	Description	Default	Validation
temperature string	Temperature controls response randomness (0.0–1.0).		Pattern: ^(0(\.[0-9]+)?|1(\.0+)?)$
outputFormat string	OutputFormat specifies the expected output format (e.g. "structured-json").
memoryBackend MemoryBackend	MemoryBackend defines where agent memory is stored.	in-context	Enum: [in-context vector-store redis]
fragments PromptFragment array	Fragments is an ordered list of named prompt fragments composed into the agent system prompt. Fragments from all referenced SwarmSettings are applied in settingsRefs list order. When the same fragment name appears in multiple settings, the last occurrence wins.		Optional: true
promptFragments PromptFragments	PromptFragments is deprecated. Use Fragments instead. When both are set, Fragments takes precedence and PromptFragments is ignored. Retained for backward compatibility; will be removed in v1beta1.		Optional: true
security SwarmSettingsSecurity	Security configures MCP server access policy enforced by the admission webhook. The strictest policy across all referenced SwarmSettings wins.		Optional: true

SwarmSettingsStatus

SwarmSettingsStatus defines the observed state of SwarmSettings.

Appears in:

• SwarmSettings

Field	Description	Default	Validation
observedGeneration integer	ObservedGeneration is the .metadata.generation this status reflects.
conditions Condition array	Conditions reflect the current state of the SwarmSettings.

SwarmTeam

SwarmTeam is the unified resource for agent teams. It supports three execution modes: dynamic mode (no spec.pipeline — service semantics, roles use delegate() for routing), pipeline mode (spec.pipeline set — job semantics, DAG execution like SwarmFlow), and routed mode (spec.routing set — LLM-driven capability dispatch via SwarmRegistry, RFC-0019).

Appears in:

• SwarmTeamList

Field	Description	Default	Validation
apiVersion string	kubeswarm.io/v1alpha1
kind string	SwarmTeam
metadata ObjectMeta	Refer to Kubernetes API documentation for fields of metadata.
spec SwarmTeamSpec			Required: true
status SwarmTeamStatus			Optional: true

SwarmTeamAutoscaling

SwarmTeamAutoscaling configures demand-driven replica scaling for a team's inline agents. The operator adjusts replicas between 0 and spec.roles[].replicas based on active pipeline steps. This is distinct from KEDA-based autoscaling on individual SwarmAgents.

Appears in:

• SwarmTeamSpec

Field	Description	Default	Validation
enabled boolean	Enabled turns on team-owned autoscaling. When false the operator does not touch replicas.		Optional: true
scaleToZero SwarmTeamScaleToZero	ScaleToZero configures idle scale-to-zero. When unset, roles are always kept at their configured replica count.		Optional: true

SwarmTeamInputSpec

SwarmTeamInputSpec defines one formal input parameter for a pipeline. Parameters declared here are validated and defaulted when an SwarmRun is created.

Appears in:

• SwarmTeamSpec

Field	Description	Default	Validation
name string	Name is the parameter key, referenced in step prompts via "{{ .input.<name> }}".		MinLength: 1 Required: true
type string	Type is the expected type of the value, used for documentation and tooling. The operator enforces presence/default but does not coerce string values.	string	Enum: [string number boolean object array] Optional: true
description string	Description documents the parameter for operators and tooling.		Optional: true
required boolean	Required marks this parameter as mandatory. When true and the parameter is absent from spec.input at run creation, the SwarmRun is immediately failed.		Optional: true
default string	Default is the value applied when Required is false and the parameter is not provided in spec.input.		Optional: true

SwarmTeamLimits

SwarmTeamLimits constrains team-level resource usage.

Appears in:

• SwarmTeamSpec

Field	Description	Default	Validation
maxDailyTokens integer	MaxDailyTokens is the rolling 24-hour token budget across the whole team pipeline. Zero means no daily limit.		Minimum: 1

SwarmTeamList

SwarmTeamList contains a list of SwarmTeam.

Field	Description	Default	Validation
apiVersion string	kubeswarm.io/v1alpha1
kind string	SwarmTeamList
metadata ListMeta	Refer to Kubernetes API documentation for fields of metadata.
items SwarmTeam array

SwarmTeamPhase

Underlying type: string

SwarmTeamPhase describes the overall state of an SwarmTeam.

Validation:

• Enum: [Pending Ready Running Succeeded Failed]

Appears in:

• SwarmTeamStatus
• TeamOutputSource

Field	Description
Pending
Ready
Running
Succeeded
Failed

SwarmTeamPipelineStep

SwarmTeamPipelineStep is one node in the SwarmTeam DAG pipeline.

Appears in:

• SwarmRunSpec
• SwarmTeamSpec

Field	Description	Default	Validation
role string	Role references a role name in spec.roles. The step name equals the role name.		MinLength: 1 Required: true
inputs object (keys:string, values:string)	Inputs is a map of input key → Go template expression referencing pipeline inputs or earlier step outputs. Example: "{{ .steps.research.output }}"
dependsOn string array	DependsOn lists role names (step names) that must complete before this step runs.
if string	If is an optional Go template expression. When set, the step only executes if the expression evaluates to a truthy value. A falsy result marks the step Skipped.
loop LoopSpec	Loop makes this step repeat until Condition evaluates to false or MaxIterations is reached.
outputSchema string	OutputSchema is an optional JSON Schema string that constrains this step's output.
validate StepValidation	Validate configures optional output validation for this step. When set, the step enters Validating phase after the agent completes and only transitions to Succeeded once all configured checks pass.		Optional: true
outputArtifacts ArtifactSpec array	OutputArtifacts declares file artifacts this step produces. The agent writes each artifact to $AGENT_ARTIFACT_DIR/<name> after its task. Artifact URLs are stored in SwarmFlowStepStatus.Artifacts and available to downstream steps via "{{ .steps.<stepName>.artifacts.<name> }}".		Optional: true
inputArtifacts object (keys:string, values:string)	InputArtifacts maps a local artifact name to an upstream step's artifact. The value format is "<stepName>.<artifactName>". The resolved URL is injected via AGENT_INPUT_ARTIFACTS env var as a JSON map.		Optional: true
registryLookup RegistryLookupSpec	RegistryLookup resolves the executing agent by capability at runtime. The SwarmRun controller resolves this before the step starts and records the resolved agent in status.resolvedAgent.		Optional: true
contextPolicy StepContextPolicy	ContextPolicy controls how this step's output is prepared before injection into downstream step prompts. Defaults to strategy=full (verbatim, current behaviour).		Optional: true

SwarmTeamRole

SwarmTeamRole defines one role in the team.

Appears in:

• SwarmRunSpec
• SwarmTeamSpec

Field	Description	Default	Validation
name string	Name is the unique role identifier (e.g. "researcher", "coordinator").		MinLength: 1 Required: true
swarmAgent string	SwarmAgent is the name of an existing SwarmAgent in the same namespace. Mutually exclusive with Model+SystemPrompt (inline definition).		Optional: true
swarmTeam string	SwarmTeam is the name of another SwarmTeam in the same namespace whose entry role fulfils this role. Only valid in pipeline mode (spec.pipeline must be set).		Optional: true
model string	Model is the LLM model ID for an inline role definition. If set, the operator auto-creates an SwarmAgent named {team}-{role}.		Optional: true
systemPrompt string	SystemPrompt is the inline system prompt for an auto-created SwarmAgent. Deprecated for production use: inline prompts are stored directly in etcd and can exceed the 1.5 MB per-object limit when prompts are large or when many roles are defined in one SwarmTeam. Use SystemPromptRef instead for any prompt larger than ~50 KB or for any production workload. Inline prompts remain fully supported for local development, quickstart examples, and prompts under 50 KB.		Optional: true
systemPromptRef SystemPromptSource	SystemPromptRef references a ConfigMap or Secret key whose content is used as the system prompt for this role's auto-created SwarmAgent. Takes precedence over SystemPrompt when both are set. Preferred for production workloads — prompt text is stored in a ConfigMap/Secret rather than in etcd as part of the SwarmTeam object, avoiding etcd size limits.		Optional: true
mcpServers MCPToolSpec array	MCPServers lists MCP tool servers for an inline role definition.		Optional: true
tools WebhookToolSpec array	Tools lists inline HTTP webhook tools for an inline role definition.		Optional: true
replicas integer	Replicas is the number of agent pods for an inline role definition.	1	Optional: true
limits GuardrailLimits	Limits constrains per-agent resource usage for an inline role definition.		Optional: true
resources ResourceRequirements	Resources sets CPU and memory requests/limits for the agent pods of an inline role definition. When not set the operator injects safe defaults (requests: cpu=100m mem=128Mi; limits: cpu=500m mem=512Mi ephemeral-storage=256Mi). Set this field explicitly to tune for your workload's actual footprint.		Optional: true
autoscaling SwarmAgentAutoscaling	Autoscaling configures KEDA-based autoscaling for an inline role's managed SwarmAgent.		Optional: true
canDelegate string array	CanDelegate lists role names this role is permitted to call via delegate(). Empty means this is a leaf role — it cannot delegate further.		Optional: true
settingsRefs LocalObjectReference array	SettingsRefs references one or more SwarmSettings whose fragments are composed into this role's system prompt, in list order. Only applies to inline roles (those with model + systemPrompt/systemPromptRef). For roles referencing an external SwarmAgent (swarmAgent: <name>), set settingsRefs on the SwarmAgent CR directly.		Optional: true
envFrom EnvFromSource array	EnvFrom injects environment variables from Secrets or ConfigMaps into the agent pods created for this role. Use this to supply API keys (ANTHROPIC_API_KEY, OPENAI_API_KEY, OPENAI_BASE_URL, etc.) on a per-role basis. Entries listed here take precedence over the global kubeswarm-api-keys Secret set via the Helm chart. Only applies to inline roles (those with model + systemPrompt/systemPromptRef).		Optional: true
externalProviderAddr string	ExternalProviderAddr is the host:port of an external gRPC LLM provider plugin (RFC-0025). When set, the agent for this role uses the gRPC adapter instead of the built-in provider. The operator injects this value as SWARM_PLUGIN_LLM_ADDR into the role's agent pods. Only applies to inline roles.		Optional: true
externalQueueAddr string	ExternalQueueAddr is the host:port of an external gRPC task queue plugin (RFC-0025). When set, TASK_QUEUE_URL is ignored and the agent for this role uses the gRPC queue adapter. The operator injects this value as SWARM_PLUGIN_QUEUE_ADDR into the role's agent pods. Only applies to inline roles.		Optional: true

SwarmTeamRoleStatus

SwarmTeamRoleStatus captures the observed state of one team role.

Appears in:

• SwarmTeamStatus

Field	Description	Default	Validation
name string	Name matches SwarmTeamRole.Name.
readyReplicas integer	ReadyReplicas is the number of agent pods ready to accept tasks.
desiredReplicas integer	DesiredReplicas is the configured replica count for this role.
managedSwarmAgent string	ManagedSwarmAgent is the name of the auto-created SwarmAgent for inline roles.

SwarmTeamRoutingSpec

SwarmTeamRoutingSpec configures routed mode execution for an SwarmTeam. When set on an SwarmTeam, incoming tasks are dispatched automatically to the best-matching agent by an LLM router call against SwarmRegistry — no pipeline DAG or hardcoded roles required.

Appears in:

• SwarmRunSpec
• SwarmTeamSpec

Field	Description	Default	Validation
registryRef LocalObjectReference	RegistryRef names the SwarmRegistry to query for capability resolution. Defaults to the first SwarmRegistry found in the namespace when omitted.		Optional: true
model string	Model is the LLM model used for the router call. A lightweight model (e.g. haiku) is sufficient and recommended. Defaults to the operator-wide default model when omitted.		MinLength: 1 Optional: true
systemPrompt string	SystemPrompt overrides the default router system prompt. Use {{ .Capabilities }} to embed the capability list and {{ .Input }} to embed the task input in a custom prompt.		Optional: true
fallback string	Fallback is the name of a standalone SwarmAgent to use when no capability matches or the router LLM fails to select one. When absent and no match is found, the run fails with RoutingFailed.		Optional: true
maxHops integer	MaxHops is the maximum number of sequential routing decisions per run. Reserved for future multi-hop support. Must be 1 in this version.	1	Maximum: 1 Minimum: 1 Optional: true

SwarmTeamScaleToZero

SwarmTeamScaleToZero configures scale-to-zero behaviour for a team's inline agents.

Appears in:

• SwarmTeamAutoscaling

Field	Description	Default	Validation
enabled boolean	Enabled activates scale-to-zero. When true, idle roles are scaled to 0 replicas after AfterSeconds of inactivity and are warmed back up automatically when a new run triggers.		Optional: true
afterSeconds integer	AfterSeconds is how long a role must be idle (no active steps) before it is scaled to zero. Minimum 30. Defaults to 300 (5 minutes).	300	Minimum: 30 Optional: true

SwarmTeamSpec

SwarmTeamSpec defines the desired state of SwarmTeam.

Appears in:

• SwarmTeam

Field	Description	Default	Validation
entry string	Entry is the role name that receives external tasks in dynamic mode. Exactly one role should be the entry point for dynamic teams. In pipeline mode (spec.pipeline set), entry is optional.		Optional: true
output string	Output is a Go template expression that selects the final pipeline result. Example: "{{ .steps.summarize.output }}" Only used in pipeline mode.		Optional: true
inputs SwarmTeamInputSpec array	Inputs defines the formal schema for pipeline input parameters. When set, required parameters are enforced and defaults are applied before an SwarmRun starts executing. Steps reference these values via "{{ .input.<name> }}".		Optional: true
input object (keys:string, values:string)	Input is the initial data passed into the pipeline. Step inputs can reference these values via "{{ .input.<key> }}". Only used in pipeline mode.		Optional: true
timeoutSeconds integer	TimeoutSeconds is the maximum wall-clock seconds the pipeline may run. Zero means no timeout. Only used in pipeline mode.		Minimum: 1 Optional: true
maxTokens integer	MaxTokens is the total token budget for the entire pipeline run. Zero means no limit. Only used in pipeline mode.		Minimum: 1 Optional: true
limits SwarmTeamLimits	Limits constrains team-level resource usage.		Optional: true
roles SwarmTeamRole array	Roles defines the roles that make up this team. At least one role is required unless spec.routing is set (routed mode).		Optional: true
pipeline SwarmTeamPipelineStep array	Pipeline defines an optional DAG of steps that drive ordered execution. When set, the team operates in pipeline mode (job semantics). When unset, the team operates in dynamic mode (service semantics).		Optional: true
defaultContextPolicy StepContextPolicy	DefaultContextPolicy is applied to any step's output when it is referenced by a non-adjacent downstream step. A step is considered adjacent when it appears in the consuming step's dependsOn list, or is the immediately preceding step when dependsOn is absent. Per-step contextPolicy takes precedence over this default. When unset, strategy=full is used for all steps (current behaviour).		Optional: true
successfulRunsHistoryLimit integer	SuccessfulRunsHistoryLimit is the number of successful SwarmRun objects to retain for this team. Oldest runs beyond this limit are deleted automatically. Set to 0 to delete successful runs immediately after completion.	10	Minimum: 0 Optional: true
failedRunsHistoryLimit integer	FailedRunsHistoryLimit is the number of failed SwarmRun objects to retain.	3	Minimum: 0 Optional: true
runRetainFor Duration	RunRetainFor is the maximum age of completed SwarmRun objects for this team. Runs older than this duration are deleted regardless of the history limits. Zero means no age-based cleanup (only count-based limits apply). Example: "168h" (7 days), "720h" (30 days).		Optional: true
notifyRef LocalObjectReference	NotifyRef references an SwarmNotify policy in the same namespace. When set, the operator dispatches notifications after terminal phase transitions.		Optional: true
budgetRef LocalObjectReference	BudgetRef references an SwarmBudget in the same namespace that governs token spend for this team. When the budget is exhausted, new runs are blocked.		Optional: true
registryRef string	RegistryRef names the SwarmRegistry used for registryLookup steps and routed mode agent resolution. Defaults to "default".	default	Optional: true
artifactStore ArtifactStoreSpec	ArtifactStore configures where pipeline file artifacts are stored. When unset, file artifact support is disabled and any OutputArtifacts declarations on pipeline steps are ignored.		Optional: true
autoscaling SwarmTeamAutoscaling	Autoscaling configures demand-driven replica scaling for this team's inline agents. When enabled, the operator scales each role's managed SwarmAgent between 0 and its configured replica count based on the number of active pipeline steps for that role. Only applies to inline roles (those with model+systemPrompt); external SwarmAgent references are not scaled by the team controller.		Optional: true
routing SwarmTeamRoutingSpec	Routing configures routed mode. When set, the team operates in routed mode: tasks are dispatched automatically via an LLM router call against SwarmRegistry. Mutually exclusive with spec.pipeline and spec.roles.		Optional: true

SwarmTeamStatus

SwarmTeamStatus defines the observed state of SwarmTeam.

Appears in:

• SwarmTeam

Field	Description	Default	Validation
phase SwarmTeamPhase	Phase is the overall team state. For pipeline teams this mirrors the most recent SwarmRun phase. For dynamic teams this reflects infrastructure readiness.		Enum: [Pending Ready Running Succeeded Failed]
roles SwarmTeamRoleStatus array	Roles lists the observed state of each role.
entryRole string	EntryRole is the role name that is the external submission point.
lastRunName string	LastRunName is the name of the most recently created SwarmRun for this team. Empty when no run has been triggered yet.
lastRunPhase SwarmRunPhase	LastRunPhase is the phase of the most recently created SwarmRun. Mirrors SwarmRun.Status.Phase for quick visibility in kubectl get swarmteam.		Enum: [Pending Running Succeeded Failed]
scaledToZero boolean	ScaledToZero is true when all inline-role agents have been scaled to 0 replicas due to team autoscaling idle timeout. The team warms up automatically when triggered.		Optional: true
lastActiveTime Time	LastActiveTime is when the team last had an active (running) pipeline step. Used by the autoscaler to decide when to scale idle roles to zero.		Optional: true
observedGeneration integer	ObservedGeneration is the .metadata.generation this status reflects.
conditions Condition array	Conditions reflect the current state of the SwarmTeam.

SystemPromptSource

SystemPromptSource selects a system prompt from a ConfigMap or Secret key. Exactly one of configMapKeyRef and secretKeyRef must be set.

Appears in:

• AgentPrompt
• SwarmTeamRole

Field	Description	Default	Validation
configMapKeyRef ConfigMapKeySelector	ConfigMapKeyRef selects a key of a ConfigMap in the same namespace.		Optional: true
secretKeyRef SecretKeySelector	SecretKeyRef selects a key of a Secret in the same namespace. Use when the prompt contains sensitive instructions.		Optional: true

TeamOutputSource

TeamOutputSource references an SwarmTeam whose pipeline completion fires the trigger.

Appears in:

• SwarmEventSource

Field	Description	Default	Validation
name string	Name is the SwarmTeam to watch.		Required: true
onPhase SwarmTeamPhase	OnPhase is the team phase that fires the trigger. Defaults to Succeeded.	Succeeded	Enum: [Pending Ready Running Succeeded Failed]

TokenUsage

TokenUsage records the number of tokens consumed by a single step or the whole pipeline.

Appears in:

• SwarmAgentStatus
• SwarmFlowStepStatus
• SwarmRunStatus

Field	Description	Default	Validation
inputTokens integer	InputTokens is the total number of prompt/input tokens sent to the LLM.
outputTokens integer	OutputTokens is the total number of completion/output tokens generated by the LLM.
totalTokens integer	TotalTokens is InputTokens + OutputTokens, provided for convenient display.

ToolPermissions

ToolPermissions defines allow/deny lists and trust policy for tool calls.

Appears in:

• AgentGuardrails

Field	Description	Default	Validation
allow string array	Allow is an allowlist of tool calls in "<server-name>/<tool-name>" format. Wildcards are supported: "filesystem/*" allows all tools from the filesystem server. When set, only listed tool calls are permitted. Deny takes precedence over allow.		Optional: true
deny string array	Deny is a denylist of tool calls in "<server-name>/<tool-name>" format. Wildcards are supported: "shell/*" denies all shell tools. Deny takes precedence over allow when both match.		Optional: true
trust ToolTrustPolicy	Trust configures the default trust level and input validation policy.		Optional: true

ToolTrustLevel

Underlying type: string

ToolTrustLevel classifies the trust level of a tool or agent connection. Used by the admission controller and runtime to enforce input validation policy.

Validation:

• Enum: [internal external sandbox]

Appears in:

• AgentConnection
• MCPToolSpec
• ToolTrustPolicy
• WebhookToolSpec

Field	Description
internal	ToolTrustInternal is for tools within the same organisation / cluster.
external	ToolTrustExternal is for third-party or internet-facing tools.
sandbox	ToolTrustSandbox is for untrusted or experimental tools; enforces strictest validation.

ToolTrustPolicy

ToolTrustPolicy sets the default trust level and validation behaviour for tools.

Appears in:

• ToolPermissions

Field	Description	Default	Validation
default ToolTrustLevel	Default is the trust level applied to tools and agents that do not declare an explicit trust field. Defaults to external.	external	Enum: [internal external sandbox] Optional: true
enforceInputValidation boolean	EnforceInputValidation rejects tool calls whose arguments do not match the tool's declared schema when the tool's effective trust level is sandbox.		Optional: true

TriggerSourceType

Underlying type: string

TriggerSourceType identifies what fires the trigger.

Validation:

• Enum: [cron webhook team-output]

Appears in:

• SwarmEventSource

Field	Description
cron	TriggerSourceCron fires on a cron schedule.
webhook	TriggerSourceWebhook fires when an HTTP POST is received at the trigger's webhook URL.
team-output	TriggerSourceTeamOutput fires when a named SwarmTeam pipeline reaches a given phase.

VectorStoreMemoryConfig

VectorStoreMemoryConfig configures the vector-store memory backend.

Appears in:

• SwarmMemorySpec

Field	Description	Default	Validation
provider VectorStoreProvider	Provider is the vector database to use.		Enum: [qdrant pinecone weaviate]
endpoint string	Endpoint is the base URL of the vector database (e.g. "http://qdrant:6333").		Required: true
collection string	Collection is the collection/index name to store memories in.	agent-memories
secretRef LocalObjectReference	SecretRef optionally names a Secret whose VECTOR_STORE_API_KEY is injected into agent pods.
ttlSeconds integer	TTLSeconds is how long memory entries are retained. 0 means no expiry.

VectorStoreProvider

Underlying type: string

VectorStoreProvider names a supported vector database.

Validation:

• Enum: [qdrant pinecone weaviate]

Appears in:

• VectorStoreMemoryConfig

Field	Description
qdrant
pinecone
weaviate

WebhookChannelSpec

WebhookChannelSpec configures a generic HTTP POST notification channel.

Appears in:

• NotifyChannelSpec

Field	Description	Default	Validation
url string	URL is the webhook endpoint as a literal string.		Optional: true
urlFrom SecretKeySelector	URLFrom reads the URL from a Secret key. Takes precedence over URL.		Optional: true
method string	Method is the HTTP method. Defaults to POST.	POST	Enum: [GET POST PUT PATCH]
headers WebhookHeader array	Headers are additional HTTP headers included in every request.		Optional: true

WebhookHeader

WebhookHeader defines a single HTTP header added to outbound webhook requests.

Appears in:

• WebhookChannelSpec

Field	Description	Default	Validation
name string	Name is the HTTP header name.
value string	Value is the literal header value.		Optional: true
valueFrom SecretKeySelector	ValueFrom reads the header value from a Secret key.		Optional: true

WebhookToolSpec

WebhookToolSpec defines an inline HTTP tool available to the agent without a full MCP server. Use for simple single-endpoint callbacks. For rich integrations prefer an MCP server.

Appears in:

• AgentTools
• SwarmTeamRole

Field	Description	Default	Validation
name string	Name is the tool identifier exposed to the LLM. Must be unique within the agent.		MinLength: 1 Required: true
url string	URL is the HTTP endpoint the agent calls when the LLM invokes this tool.		Required: true
method string	Method is the HTTP method used when calling the endpoint.	POST	Enum: [GET POST PUT PATCH]
description string	Description explains the tool's purpose to the LLM and to human operators.		Optional: true
trust ToolTrustLevel	Trust classifies the trust level of this webhook endpoint. Defaults to the guardrails.tools.trust.default when unset.		Enum: [internal external sandbox] Optional: true
schema RawExtension	Schema is a JSON Schema object describing the tool's input parameters. Stored as a raw JSON/YAML object; validated by the LLM runtime.		Optional: true