Custom Resources¶
Sympozium models every agentic concept as a Kubernetes Custom Resource. All
are in the sympozium.ai/v1alpha1 API group.
Core¶
| CRD | Kubernetes Analogy | Purpose |
|---|---|---|
Agent |
Namespace / Tenant | Per-user gateway — channels, provider config, memory settings, skill bindings |
AgentRun |
Job / Sandbox CR | Single agent execution — task, model, result capture, memory extraction. Optionally uses Agent Sandbox CRDs for kernel-level isolation |
SympoziumPolicy |
NetworkPolicy | Feature and tool gating — what an agent can and cannot do |
SkillPack |
ConfigMap | Portable skill bundles — kubectl, Helm, or custom tools — mounted into agent pods as files, with optional sidecar containers for cluster ops |
SympoziumSchedule |
CronJob | Recurring tasks — heartbeats, sweeps, scheduled runs with cron expressions |
Ensemble |
Helm Chart / Operator Bundle | Pre-configured agent bundles — activating a pack stamps out Agents, Schedules, and memory for each persona |
Model |
Deployment + Service | Cluster-local inference — declares a model (GGUF or HuggingFace), controller deploys an inference server (llama.cpp, vLLM, or TGI) and exposes an OpenAI-compatible endpoint |
MCPServer |
Deployment + Service | Managed Model Context Protocol server — external tool providers with auto-discovery and allow/deny filtering |
SympoziumConfig |
Cluster configuration | Platform-wide singleton — gateway, canary, and pricing settings |
ModelConnection |
ExternalName Service | Namespaced, reusable model route — provider, protocol, endpoint, models, and an optional Secret whose key is pinned to that endpoint's origin |
Execution and sessions¶
| CRD | Kubernetes Analogy | Purpose |
|---|---|---|
AgentRuntime |
RuntimeClass | Administrator-approved, digest-pinned harness that replaces agent-runner (one-shot or session-capable); on Celln, a wrapper referencing a CellnRuntimeProfile. Agents select one with spec.runtimeRef |
HarnessSession |
Deployment + Service | A persistent, Agent-owned AgentHarness process (Pi, Hermes) behind Agents → Chat, with state on a per-session PVC |
AgentRunTurn (arturn) |
— | One follow-up message and its result within an enduring Celln run; a durable record, not another running agent |
WorkspaceSession (ws) |
PersistentVolumeClaim | A persistent /workspace for one (Agent, sessionKey) pair; owns its PVC and is owned by the Agent |
Celln catalogue and policy¶
| CRD | Scope | Purpose |
|---|---|---|
CellnRuntimeProfile |
Cluster | Immutable, operator-published runtime revision: executable hashes, lifecycles, ceilings and the native parent/worker material for the fleet |
CellnExecutionPolicy |
Cluster | Which namespaces may run which profiles, tools and model routes, with lease/turn/request/token ceilings |
ClusterCellnTool |
Cluster | Shared, immutable tool revision lent to cells (brokered tools and commands borrowed from pinned images; spec.sourceImage) |
CellnTool |
Namespaced | Legacy namespaced tool metadata from the pre-0.12 catalogue; nothing publishes or executes it any more (the fleet lends ClusterCellnTools) |
CellnToolSubmission |
Namespaced | Untrusted request to publish a tool; creating it approves nothing |
The Celln fleet installer creates
the cluster-scoped objects once per scope and per-namespace wrappers
(AgentRuntime, Agent, ModelConnection) on first use.
Agent¶
The core resource representing an agent identity. Each instance has:
- An LLM provider configuration (model, API key reference, base URL)
- Skill bindings (which SkillPacks are active)
- Channel connections (Telegram, Slack, etc.)
- Memory settings (enabled/disabled, max size)
- A policy reference
- Optional node selector and tolerations for placing agent pods on specific nodes (e.g. GPU nodes running Ollama)
- An optional harness runtime (
spec.runtimeRef) and execution defaults (spec.execution: backend, lifecycle, model connection, Celln tool selection)
apiVersion: sympozium.ai/v1alpha1
kind: Agent
metadata:
name: my-agent
spec:
agents:
default:
model: gpt-4o
skills:
- skillPackRef: k8s-ops
- skillPackRef: code-review
policyRef: permissive
Placing agent pods¶
spec.agents.default.nodeSelector and spec.agents.default.tolerations pin
an Agent's pods to a node pool, for example a GPU pool tainted
nvidia.com/gpu=present:NoSchedule that runs a local model. The controller
copies the tolerations onto every AgentRun it creates for the Agent
(schedules, channels, delegations, the API), and a run may also set
spec.tolerations itself. They apply to Job, Deployment (serving) and
Sandbox pods.
spec:
agents:
default:
model: qwen3
nodeSelector:
pool: gpu
tolerations:
- key: nvidia.com/gpu
operator: Equal
value: present
effect: NoSchedule
Model tuning¶
Three optional fields under spec.agents.default tune the LLM for runs on the built-in agent-runner:
| Field | Values | Anthropic | OpenAI and compatible |
|---|---|---|---|
thinking |
off, minimal, low, medium, high |
Extended thinking, with a budget of 1024 / 2048 / 4096 / 8192 tokens | reasoning_effort |
maxTokens |
integer ≥ 1 | max_tokens (default 8192) |
max_completion_tokens on hosted OpenAI, max_tokens on other servers |
temperature |
decimal string, e.g. "0.2" |
0–1 | 0–2 |
spec:
agents:
default:
model: claude-sonnet-4-20250514
thinking: medium
maxTokens: 12000
temperature: "0.3"
Upgrading: thinking now takes effect
Before this release thinking was accepted but ignored. An Agent that has carried thinking: high since then will now run with extended thinking or reasoning_effort on upgrade, which costs more tokens per call. Scheduled runs are affected too, because the schedule controller copies the Agent's thinking onto them. Check your Agents for a stored thinking value, for example with kubectl get agents -A -o custom-columns=NAME:.metadata.name,THINKING:.spec.agents.default.thinking, and set it to off or remove it where you did not mean it.
Every AgentRun of the Agent inherits these fields at reconcile time. That covers channel messages, schedules, the API, the web proxy, sub-agents and hand-written AgentRuns. A value set on the AgentRun's own spec.model takes precedence. Ensemble personas accept the same three fields, next to their per-persona model.
Provider behaviour to be aware of:
- Anthropic with thinking on. The API requires the thinking budget to be smaller than
max_tokens. WithmaxTokensunset,max_tokensgrows to leave 4096 tokens for the answer. WithmaxTokensset, your cap wins and the budget is limited to half of it; if that falls under the 1024-token minimum, thinking is turned off.temperatureis ignored while thinking is on, because the API rejects it. - Models that reject the thinking setting. On Anthropic, a 400 that names thinking (a model without extended thinking); on OpenAI, a 400 that names
reasoning_effort. Either way the runner retries once without it and stops sending it for the rest of the run, sothinkingdegrades to a no-op instead of failing the run. The cost is one extra request per run. - Harness and Celln runs do not inherit these fields. Those runtimes reject them when they are set explicitly, as with
model.thinkingtoday.
AgentRun¶
Represents a single agent execution. The controller reconciles each AgentRun into an ephemeral Kubernetes Job containing the agent container, IPC bridge, and any skill sidecars.
apiVersion: sympozium.ai/v1alpha1
kind: AgentRun
metadata:
name: quick-check
spec:
agentRef: my-agent
agentId: default
sessionKey: "quick-check-001"
task: "How many nodes are in the cluster?"
model:
provider: openai
model: gpt-4o
authSecretRef: my-openai-key
skills:
- skillPackRef: k8s-ops
timeout: "5m"
Phase transitions: Pending → Running → Succeeded (or Failed). When lifecycle hooks with postRun are defined: Pending → Running → PostRunning → Succeeded (or Failed). A gate with lifecycle.retry.inPlace uses AwaitingGate in place of PostRunning and may loop back to Running.
A response gate can retry a rejected run. With lifecycle.retry.inPlace: true the pod parks in AwaitingGate and continues on the same conversation, so the whole chain is one AgentRun and each attempt is an entry in status.attempts[]. Otherwise (the default) each attempt is its own AgentRun, linked by status.retryOf and status.attempt; a superseded attempt ends Failed with status.gateVerdict: retried.
Setting spec.backend: celln routes the run to a hardware-isolated Celln microVM instead of a Job, and spec.executionLifecycle chooses one-shot or enduring (a leased parent cell that takes follow-up AgentRunTurns). Celln runs use the model route of the Agent's Celln backend (spec.model.connectionRef), not a key in the run, and do not support SkillPacks, MCP, ensembles, delegation or shared memory. See Celln Backend.
Other fields worth knowing: spec.task.mode: harness or an AgentRuntime replaces agent-runner with an approved harness (Harness Mode); spec.mode: server runs a long-lived Deployment (Serving Mode); spec.tolerations places the pod on tainted nodes; spec.cleanup is delete or keep.
SympoziumPolicy¶
Gates features and tools. The webhook checks feature gates and limits when a run is admitted; the controller applies the tool rules to every run's pod. See Security.
| Policy | Who it is for | Key rules |
|---|---|---|
| Permissive | Dev clusters, demos | All tools allowed |
| Default | General use | All tools allowed except fetch_url |
| Restrictive | Production, security | All tools denied by default, must be explicitly allowed |
SkillPack¶
Portable skill bundles mounted into agent pods as files. Can optionally declare sidecar containers with runtime tools and RBAC rules. See Skills & Sidecars for details.
SympoziumSchedule¶
Cron-based recurring agent runs. See Scheduled Tasks for details.
Ensemble¶
Pre-configured agent bundles. See Ensembles for details.
ModelConnection¶
A namespaced, reusable model route. An Agent selects one with
spec.execution.modelConnectionRef; native Celln runs select one with
spec.model.connectionRef. The controller pins the connection UID, spec, and
revision before admitting a run or persistent session, so a conversation is
never silently redirected to another provider. See
Model connections for persistent harnesses.
AgentRuntime and HarnessSession¶
An AgentRuntime is the admin-owned description of an external harness:
a digest-pinned image, its adapter contract and capabilities, and a support
owner. An Agent references it with spec.runtimeRef; runs inherit it. A
session-capable runtime gives the Agent a persistent Chat, served by a
HarnessSession (a Deployment and private Service with a per-session PVC).
See AgentHarness and
Harness Mode.
AgentRunTurn¶
Follow-up messages to an enduring Celln run. The API server creates them
(POST /api/v1/runs/{name}/turns) with the run's controller
ownerReference; a turn without one is refused. Each turn records its
message, phase and result. See Celln Backend.
WorkspaceSession¶
A persistent /workspace for one (Agent, sessionKey) pair, owning its PVC.
Enable it on an Agent with spec.workspace.perSessionPVC: true (optional
size, default 1Gi; storageClassName; idleTTL, default 720h);
otherwise /workspace is an ephemeral emptyDir. Runs with the same session
key share the workspace and are serialised, because the PVC is
ReadWriteOnce. Deleting the session or its Agent deletes the PVC, and an idle
session is reclaimed after idleTTL. Manage them with sympozium workspace list|show|delete|exec
(see the CLI reference).
Celln catalogue and policy¶
CellnRuntimeProfile, CellnExecutionPolicy and ClusterCellnTool are the
cluster-scoped, immutable authority the Celln fleet admits runs against: the
controller resolves a run's namespace, runtime, tools and model route into one
decision and re-checks it before every turn. They are created by the fleet
installer; see Celln Fleet Installation.