ArkAgent Spec

API: arkonis.dev/v1alpha1 Kind: ArkAgent Short name: arkagent

Full example 

apiVersion: arkonis.dev/v1alpha1
kind: ArkAgent
metadata:
  name: research-agent
  namespace: default
spec:
  replicas: 2
  model: llama3.2
  systemPrompt: |
    You are a research agent. Gather and summarize information
    accurately and concisely. Always cite your sources.
  systemPromptRef:
    configMapKeyRef:
      name: research-prompt
      key: system.txt
  mcpServers:
    - name: web-search
      url: https://search.mcp.internal/sse
      headers:
        - name: Authorization
          valueFrom:
            secretKeyRef:
              name: mcp-credentials
              key: token
  tools:
    - name: fetch_news
      description: "Fetch the latest news headlines for a given topic."
      url: "http://news-api.internal/headlines"
      method: POST
      inputSchema: |
        {"type":"object","properties":{"topic":{"type":"string"}},"required":["topic"]}
  limits:
    maxTokensPerCall: 8000
    maxConcurrentTasks: 5
    timeoutSeconds: 120
  livenessProbe:
    type: semantic
    intervalSeconds: 60
    validatorPrompt: "Reply with exactly one word: HEALTHY"
  configRef: analyst-base
  memoryRef:
    name: research-memory

Spec fields

Top-level

Field Type Required Description
replicas int32 no Number of agent pod replicas. Default: 1. Range: 0–50.
model string yes Model identifier passed to the LLM provider (e.g. llama3.2, gpt-4o, claude-sonnet-4-20250514).
systemPrompt string one of Inline system prompt. Mutually exclusive with systemPromptRef.
systemPromptRef ConfigMapKeyRef one of Reference to a ConfigMap key containing the system prompt. The operator restarts agent pods when the ConfigMap changes.
mcpServers []MCPServerSpec no MCP tool servers to connect at pod startup.
tools []WebhookToolSpec no Inline HTTP webhook tools — no MCP server required.
limits AgentLimits no Per-agent resource and token limits.
livenessProbe AgentProbe no Semantic health check configuration.
configRef string no Name of an ArkSettings in the same namespace. Merged into the effective system prompt.
memoryRef LocalObjectReference no Name of an ArkMemory in the same namespace. Injects memory backend config into agent pods.

systemPromptRef

Field Type Description
configMapKeyRef.name string ConfigMap name in the same namespace.
configMapKeyRef.key string Key in the ConfigMap data.

mcpServers[]

Field Type Required Description
name string yes Logical name. Used as tool name prefix (name__tool).
url string yes SSE endpoint URL of the MCP server.
headers []HeaderSpec no HTTP headers to include in the SSE connection request (e.g. auth tokens).

mcpServers[].headers[]

Field Type Description
name string Header name (e.g. Authorization).
value string Literal header value.
valueFrom.secretKeyRef.name string Secret name.
valueFrom.secretKeyRef.key string Key in the secret.

tools[] (inline webhook tools)

Field Type Required Description
name string yes Tool identifier exposed to the LLM. Must be unique within the deployment.
description string no Explains the tool’s purpose. The LLM uses this to decide when to invoke it.
url string yes HTTP endpoint the agent calls when the tool is invoked.
method string no HTTP method. Default: POST.
inputSchema string no JSON Schema (raw JSON string) describing the tool’s input parameters.

limits

Field Type Default Description
maxTokensPerCall int 8000 Token budget (input + output) per LLM API call.
maxConcurrentTasks int 5 Max tasks a single pod processes simultaneously.
timeoutSeconds int 120 Per-task timeout. Task is abandoned and error returned after this duration.

livenessProbe

Field Type Default Description
type string ping ping — HTTP reachability only. semantic — enables /readyz LLM validation.
intervalSeconds int 60 Interval between semantic validation checks.
validatorPrompt string (built-in) Custom prompt sent to the LLM during /readyz validation.

Built-in agent tools

Tool Description
submit_subtask Enqueue a new agent task asynchronously. Returns the task ID. Enables supervisor/worker patterns.
delegate (injected in ArkTeam context) Route a task to a specific team role.

Status fields

Field Type Description
replicas int32 Total pods managed by this agent.
readyReplicas int32 Pods passing both liveness and readiness checks.
conditions []Condition Standard Kubernetes conditions (Available, Progressing, Degraded).

See also

Apache 2.0 · ARKONIS