ArkTeam

ArkTeam groups ArkAgent resources into named roles with an explicit delegation graph. Each role gets an isolated Redis stream so tasks never bleed across team boundaries. The entry agent receives the initial task and can delegate sub-tasks to downstream roles using the built-in delegate() tool.

apiVersion: arkonis.dev/v1alpha1
kind: ArkTeam
metadata:
  name: research-team
  namespace: ai-team
spec:
  members:
    - role: coordinator
      arkAgent: coordinator-agent
      entry: true
      delegates:
        - reviewer
    - role: reviewer
      arkAgent: reviewer-agent

spec.members

Each entry in members maps a role name to an ArkAgent and optionally declares which roles it can delegate to.

Field Type Required Description
role string yes Unique role name within the team. Used as the routing key for delegate() calls.
arkAgent string yes Name of the ArkAgent in the same namespace to assign to this role.
entry bool no Marks this role as the entry point. Exactly one member must set entry: true. Inbound tasks are routed here.
delegates []string no List of role names this role is allowed to delegate sub-tasks to. The operator validates these references and rejects cycles.

How it works

When an ArkTeam is applied:

  1. The operator annotates each member ArkAgent with its role, isolated queue URL (arkonis.dev/team-queue-url), and a JSON routing table of delegate roles (arkonis.dev/team-routes).
  2. Agent pods are restarted to pick up the new TASK_QUEUE_URL and AGENT_TEAM_ROUTES environment variables.
  3. An ArkService is auto-created for the entry role so external callers can submit tasks without knowing the internal queue layout.

The delegate() tool is injected into every team-member agent at runtime. When the LLM calls it, the agent runtime routes the sub-task to the target role’s isolated queue and returns the result inline.

Queue isolation

Each role gets its own Redis stream: <namespace>.<team-name>.<role>. This means:

  • Tasks submitted to coordinator never appear in reviewer’s queue.
  • A non-team agent polling the global queue cannot accidentally pick up team tasks.
  • Each role can be scaled independently — its queue depth is a clean signal for KEDA autoscaling.

Validation

The operator performs the following checks at reconcile time and sets a Ready=False condition if any fail:

  • Exactly one member has entry: true.
  • All delegates references point to roles defined in the same members list.
  • No delegation cycles exist (DFS cycle detection).
  • All referenced ArkAgent resources exist in the same namespace.

Status 

status:
  conditions:
    - type: Ready
      status: "True"
      reason: TeamReconciled
      message: team "research-team" ready with 2 roles

Example: 4-role magazine pipeline 

apiVersion: arkonis.dev/v1alpha1
kind: ArkTeam
metadata:
  name: magazine-team
  namespace: ark-system
spec:
  members:
    - role: topic-proposer
      arkAgent: topic-agent
      entry: true
      delegates:
        - researcher
    - role: researcher
      arkAgent: research-agent
      delegates:
        - editor
    - role: editor
      arkAgent: editor-agent
      delegates:
        - designer
    - role: designer
      arkAgent: designer-agent

Apache 2.0 · ARKONIS