Agent Teams

ArkTeam lets you build multi-agent systems where agents have distinct roles and can delegate work to each other. Unlike ArkFlow which defines a fixed DAG executed by the operator, a team is a live group of agents that communicate through role-based delegation at runtime — the LLM decides when and what to delegate.

---

Core concepts

Role — a named position in the team (e.g. coordinator, reviewer). Each role maps to one ArkAgent.

Delegation graph — an explicit list of which roles each role is allowed to delegate to. The operator validates this at apply time and rejects cycles.

Entry role — the single role that receives inbound tasks. All external traffic routes here first.

Isolated queues — each role polls its own Redis stream (<namespace>.<team>.<role>). Tasks submitted to one role are invisible to all others.

---

Defining a team

apiVersion: arkonis.dev/v1alpha1
kind: ArkTeam
metadata:
  name: research-team
  namespace: ai-team
spec:
  members:
    - role: coordinator
      arkAgent: coordinator-agent
      entry: true # inbound tasks land here
      delegates:
        - reviewer # coordinator can hand off to reviewer
    - role: reviewer
      arkAgent: reviewer-agent
      # no delegates — reviewer is a terminal role

The referenced ArkAgent resources must exist in the same namespace. The operator annotates each agent with its role and queue URL, then restarts the pods to inject the new environment variables.

---

How delegation works

The operator injects a delegate(role, prompt) tool into every team-member agent. When the LLM calls it:

1. The agent runtime submits a new task to the target role’s isolated queue.
2. It blocks until the target agent completes the task.
3. The result is returned to the LLM as the tool output.

The agent’s system prompt should describe when and how to use delegate(). Example:

spec:
  systemPrompt: |
    You are a research coordinator. Analyse the user's question,
    write a thorough research summary, then delegate it to the
    reviewer role for quality assessment using delegate().
    Return the reviewer's feedback as your final answer.

---

Using a team with ArkFlow

You can combine ArkTeam with ArkFlow — each flow step targets an ArkAgent that happens to be a team member. The flow controller automatically routes the task to that agent’s isolated queue.

apiVersion: arkonis.dev/v1alpha1
kind: ArkFlow
metadata:
  name: magazine-pipeline
spec:
  steps:
    - name: propose
      arkAgent: topic-agent # member of magazine-team
      inputs:
        prompt: "Propose a tech article topic for 2026."
    - name: research
      arkAgent: research-agent # member of magazine-team
      dependsOn: [propose]
      inputs:
        prompt: "Research this topic: "

---

Firing a team via webhook

The operator auto-creates an ArkService for the entry role. To send a task to the team via HTTP, use an ArkEvent webhook trigger:

apiVersion: arkonis.dev/v1alpha1
kind: ArkEvent
metadata:
  name: team-trigger
spec:
  source:
    type: webhook
  targets:
    - pipeline: my-flow

TOKEN=$(kubectl get secret team-trigger-webhook-token -n ai-team \
  -o jsonpath='{.data.token}' | base64 -d)

curl -X POST \
  "http://ark-operator.ai-team.svc.cluster.local:8092/triggers/ai-team/team-trigger/fire?mode=sync&timeout=120s" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{}'

---

Inspecting a team

# Check team status and member roles
kubectl describe arkteam research-team -n ai-team

# Verify each agent has the correct queue annotation
kubectl get arkagent -n ai-team \
  -o custom-columns='NAME:.metadata.name,QUEUE:.metadata.annotations.arkonis\.dev/team-queue-url'

# Watch agent events (TaskStarted, TaskDelegated, TaskCompleted)
kubectl get events -n ai-team --field-selector reason=TaskDelegated