ArkTeam Spec

API: arkonis.dev/v1alpha1 Kind: ArkTeam

Top-level spec fields

Field Type Required Description
roles []Role yes Named roles. Each is an inline agent, an ArkAgent reference, or an ArkTeam reference.
entry string dynamic mode Name of the role that receives inbound tasks. Required when spec.pipeline is absent.
output string no Go template producing the team’s final result.
input map[string]string no Default input values injected when the team is triggered without explicit input.
pipeline []PipelineStep no When set, runs steps in DAG order (pipeline mode). When absent with canDelegate, runs in dynamic mode.
timeoutSeconds int no Wall-clock timeout for the entire team execution. Fails with TimedOut.
maxTokens int no Hard token budget across all roles per run. Fails with BudgetExceeded when exceeded.
limits.maxDailyTokens int no Rolling 24-hour token cap. Scales all role replicas to 0 when hit; auto-resumes when the window rotates.

roles[]

Each role is one of three mutually exclusive types.

A) Inline role

Field Type Description
name string (required) Unique role name within the team.
model string LLM model ID (e.g. llama3.2, gpt-4o, claude-sonnet-4-20250514).
systemPrompt string Full system prompt text.
systemPromptRef ConfigMapKeyRef Reference to a ConfigMap key containing the system prompt.
mcpServers []MCPServerSpec MCP tool connections.
tools []InlineToolSpec Inline HTTP webhook tools.
replicas int Number of parallel workers on this role’s queue.
limits AgentLimits Per-call token limit, timeout, and concurrency.
canDelegate []string Roles this role may delegate to at runtime.

The operator auto-creates an ArkAgent named {team-name}-{role-name} with an owner reference.

B) ArkAgent reference

Field Type Description
name string Unique role name.
arkAgent string Name of an existing ArkAgent in the same namespace.
canDelegate []string Roles this role may delegate to.

C) ArkTeam reference

Field Type Description
name string Unique role name.
arkTeam string Name of another ArkTeam. Tasks are routed to that team’s entry role.

canDelegate semantics

Value Meaning
omit or [] Pure worker — no delegate() tool injected.
["role-a", "role-b"] Can only delegate to these roles. Validated at deploy time.
["*"] Fully autonomous — can delegate to any role in this team.

pipeline[] steps

Field Type Required Description
role string yes Name of a role defined in spec.roles.
inputs map[string]string no Key-value inputs. Values are Go template expressions.
dependsOn []string no Step names that must complete before this step runs. Steps with no shared ancestor run in parallel.
if string no Go template expression. Step is skipped when falsy. Satisfies downstream dependsOn checks.
loop LoopSpec no Repeat this step until loop.condition is false or loop.maxIterations is reached.
outputSchema string no JSON Schema (as a string). Agent is instructed to respond in this format. Downstream steps access fields via ``.

loop

Field Type Default Description
condition string — Go template expression. Repeats while truthy.
maxIterations int 10 Hard cap. Range: 1–100.

Template expressions

Expression Resolves to
`` A value from spec.input or the trigger payload
`` Raw output string from a completed pipeline step
`` Typed field from a step with outputSchema
`` Output from a dynamic role (dynamic mode)

Step phases

Phase Meaning
Pending Waiting for dependencies or not yet submitted
Running Task submitted to the agent queue
Succeeded Agent returned a valid result
Failed Agent errored or output failed schema validation
Skipped if condition was false

Status fields 

status:
  phase: Succeeded           # Pending | Ready | Running | Succeeded | Failed
  startTime: "2026-03-17T10:00:00Z"
  completionTime: "2026-03-17T10:00:45Z"
  output: "Final result..."

  steps:
    - name: researcher
      phase: Succeeded
      taskID: "1710000001-0"
      output: "..."
      startTime: "2026-03-17T10:00:01Z"
      completionTime: "2026-03-17T10:00:12Z"
      tokenUsage:
        inputTokens: 320
        outputTokens: 1240
        totalTokens: 1560

  roles:
    - name: researcher
      readyReplicas: 1
      desiredReplicas: 1
      managedArkAgent: content-pipeline-researcher

  totalTokenUsage:
    inputTokens: 1520
    outputTokens: 4640
    totalTokens: 6160

  conditions:
    - type: Ready
      status: "True"
      reason: Succeeded
      message: "all steps completed successfully"

Validation performed at reconcile time

  • All canDelegate references point to roles defined in spec.roles
  • No delegation cycles (DFS cycle detection)
  • All referenced ArkAgent and ArkTeam resources exist in the same namespace
  • spec.entry is set in dynamic mode and refers to a defined role
  • pipeline[] step role values resolve to entries in spec.roles
  • dependsOn chains form a valid DAG (no cycles)

See also

Apache 2.0 · ARKONIS