# AgentRun

#sympozium #crd #agentrun

## Definicja

`AgentRun` reprezentuje **pojedyncze wywołanie agenta**. Każdy AgentRun reconciliuje się w Kubernetes Job (tryb task) lub Deployment (tryb server).

**Plik:** `api/v1alpha1/agentrun_types.go`

## Spec

```yaml
apiVersion: sympozium.ai/v1alpha1
kind: AgentRun
metadata:
  name: my-run-001
spec:
  instanceRef: my-agent        # Powiązanie z SympoziumInstance
  agentId: default
  sessionKey: session-123
  task: "Sprawdź stan klastra"
  systemPrompt: "Jesteś SRE inżynierem..."

  model:
    provider: anthropic
    model: claude-sonnet-4-20250514
    baseURL: ""
    thinking: "high"
    authSecretRef: anthropic-key
    nodeSelector:
      gpu-type: a100

  mode: task|server           # Job vs Deployment

  parent:                     # Dla sub-agentów
    runName: parent-run
    sessionKey: parent-session
    spawnDepth: 1

  skills:
    - skillPackRef: k8s-ops

  toolPolicy:
    allow: [read_file, list_directory]
    deny: [execute_command]

  timeout: 5m
  cleanup: delete|keep       # Po zakończeniu

  sandbox:                    # Container-level sandbox
    enabled: true
    image: custom-sandbox:v1

  agentSandbox:              # Kernel-level sandbox (Sandbox CR)
    enabled: true
    runtimeClass: gvisor
    warmPoolRef: wp-my-agent

  env:                       # Custom env vars
    MY_VAR: my-value
```

## Status

```yaml
status:
  phase: Pending|Running|Serving|Succeeded|Failed
  podName: my-run-001-abc123
  jobName: my-run-001
  sandboxName: my-run-001-sandbox    # Agent Sandbox mode
  startedAt: "2024-01-01T00:00:00Z"
  completedAt: "2024-01-01T00:05:00Z"
  result: "Klaster jest zdrowy. 15 podów running..."
  error: ""
  exitCode: 0
  tokenUsage:
    inputTokens: 1500
    outputTokens: 800
    totalTokens: 2300
    toolCalls: 5
    durationMs: 45000
  traceID: "abc123def456"        # OTel trace
  deploymentName: ""              # Server mode
  serviceName: ""                 # Server mode
```

## Fazy lifecycle

```
""(empty) → Pending → Running → Succeeded
                              → Failed
                    → Serving (tryb server - długo żyjący)
```

### Przejścia faz

| Z fazy | Do fazy | Trigger |
|--------|---------|---------|
| "" / Pending | Running | Job/Sandbox CR utworzony, pod running |
| Running | Succeeded | Pod zakończył się z kodem 0 |
| Running | Failed | Pod zakończył się z kodem != 0 lub timeout |
| Pending | Serving | Mode=server, Deployment ready |
| Serving | Succeeded | AgentRun usunięty (cleanup Deployment) |

## Token Usage Tracking

AgentRun śledzi zużycie tokenów LLM:
- `inputTokens` - tokeny promptu
- `outputTokens` - tokeny odpowiedzi
- `totalTokens` - suma
- `toolCalls` - liczba wywołań narzędzi
- `durationMs` - czas wall-clock w ms

## Sub-agenty

AgentRun wspiera hierarchię parent-child:
```yaml
parent:
  runName: parent-run-001
  sessionKey: parent-session
  spawnDepth: 1  # Głębokość w drzewie
```

Limity zdefiniowane w [[SympoziumInstance]] → `agents.default.subagents`:
- `maxDepth: 2` - max zagnieżdżenie
- `maxConcurrent: 5` - max równoległych
- `maxChildrenPerAgent: 3` - max dzieci per agent

## History Pruning

Controller utrzymuje max 50 zakończonych AgentRun per instancja (konfigurowalny `RunHistoryLimit`). Starsze są automatycznie usuwane.

---

Powiązane: [[SympoziumInstance]] | [[Cykl życia AgentRun]] | [[Cykl życia Agent Pod]]