# chizhang21/agentrally-operator architecture

> Architecture diagram of the GitHub repository chizhang21/agentrally-operator, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/chizhang21/agentrally-operator
- Repository: https://github.com/chizhang21/agentrally-operator

## Overview

AgentRally is a Kubernetes operator for deploying and managing containerized AI agents; the agents themselves own model calls, tools, conversation state, and APIs. Users apply an AgentGroup, AgentDefinition, and AgentInstance. The operator prepares the group namespace and policy, publishes reusable definition configuration, then manages each instance’s execution and workspace through a Sandbox and Pod. Other documented capabilities include prewarming, runtime isolation, Gateway interaction, cluster-capability reporting, and an optional outbound connector. Some subsystem paths are supported by the tree and README, but their internal call relationships were not sampled.

Main entry points: [`internal/controller/agentinstance/controller.go`](https://github.com/chizhang21/agentrally-operator/blob/main/internal/controller/agentinstance/controller.go) (Instance controller), [`internal/controller/agentdefinition/controller.go`](https://github.com/chizhang21/agentrally-operator/blob/main/internal/controller/agentdefinition/controller.go) (Definition controller), [`api/v1alpha1/agentdefinition_types.go`](https://github.com/chizhang21/agentrally-operator/blob/main/api/v1alpha1/agentdefinition_types.go) (AgentDefinition), [`internal/controller/agentgroup/controller.go`](https://github.com/chizhang21/agentrally-operator/blob/main/internal/controller/agentgroup/controller.go) (Group controller)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Kubernetes API"]
  node_groupresource["AgentGroup"]
  node_definitionresource["AgentDefinition"]
  node_instanceresource["AgentInstance"]
  node_capresource[("ClusterCapabilities")]
end

subgraph group_controllers["Reconciliation"]
  node_operator["Operator manager<br/>[main.go]"]
  node_groupcontroller["Group controller<br/>[controller.go]"]
  node_definitioncontroller["Definition controller<br/>[controller.go]"]
  node_instancecontroller["Instance controller<br/>[controller.go]"]
end

subgraph group_runtime["Execution and capacity"]
  node_configuration["Definition publishing<br/>[revision.go]"]
  node_allocation["Capacity allocation<br/>[pool.go]"]
  node_prewarming["Prewarming<br/>[prewarming.go]"]
  node_executionconfig["Execution configuration<br/>[resolve.go]"]
  node_podconfig["Pod configuration<br/>[defaults.go]"]
  node_sandbox["Sandbox lifecycle<br/>[api.go]"]
  node_workspace["Workspace volumes<br/>[workspace.go]"]
end

subgraph group_platform["Cluster platform"]
  node_capcontroller["Capability controller<br/>[controller.go]"]
  node_capdiscovery["Cluster discovery<br/>[discovery.go]"]
  node_storage["Storage discovery<br/>[storage.go]"]
end

subgraph group_integration["External integration"]
  node_connector["Outbound connector<br/>[main.go]"]
  node_invocations["Invocation transport"]
end

node_user(("kubectl / GitOps"))
node_backend(("Connector backend"))
node_pod["Agent Pod / PVC"]
node_gateway["Kubernetes Gateway"]

node_user -->|"applies"| node_groupresource
node_user -->|"applies"| node_definitionresource
node_user -->|"applies"| node_instanceresource
node_operator -->|"registers"| node_groupcontroller
node_operator -->|"registers"| node_definitioncontroller
node_operator -->|"registers"| node_instancecontroller
node_groupresource -->|"reconciles"| node_groupcontroller
node_definitionresource -->|"reconciles"| node_definitioncontroller
node_instanceresource -->|"reconciles"| node_instancecontroller
node_groupcontroller -->|"prepares namespace"| node_definitioncontroller
node_definitioncontroller -->|"publishes revision"| node_configuration
node_definitioncontroller -->|"retires capacity"| node_allocation
node_instancecontroller -.->|"resolves config"| node_executionconfig
node_instancecontroller -.->|"allocates capacity"| node_allocation
node_instancecontroller -->|"manages lifecycle"| node_sandbox
node_instancecontroller -->|"configures workspace"| node_workspace
node_instancecontroller -->|"creates execution"| node_pod
node_allocation -->|"supports spare capacity"| node_prewarming
node_podconfig -->|"configures layout"| node_pod
node_capcontroller -->|"refreshes report"| node_capdiscovery
node_capdiscovery -.->|"discovers storage"| node_storage
node_capcontroller -->|"updates status"| node_capresource
node_groupcontroller -->|"checks network report"| node_capresource
node_definitionresource -->|"configures container"| node_podconfig
node_definitionresource -.->|"supplies settings"| node_executionconfig
node_instanceresource -->|"configures interaction"| node_gateway
node_connector -->|"runs transport"| node_invocations
node_invocations -->|"exchanges commands"| node_backend

click node_operator "https://github.com/chizhang21/agentrally-operator/blob/main/cmd/main.go"
click node_groupresource "https://github.com/chizhang21/agentrally-operator/blob/main/api/v1alpha1/agentgroup_types.go"
click node_definitionresource "https://github.com/chizhang21/agentrally-operator/blob/main/api/v1alpha1/agentdefinition_types.go"
click node_instanceresource "https://github.com/chizhang21/agentrally-operator/blob/main/api/v1alpha1/agentinstance_types.go"
click node_groupcontroller "https://github.com/chizhang21/agentrally-operator/blob/main/internal/controller/agentgroup/controller.go"
click node_definitioncontroller "https://github.com/chizhang21/agentrally-operator/blob/main/internal/controller/agentdefinition/controller.go"
click node_instancecontroller "https://github.com/chizhang21/agentrally-operator/blob/main/internal/controller/agentinstance/controller.go"
click node_configuration "https://github.com/chizhang21/agentrally-operator/blob/main/internal/definition/revision.go"
click node_allocation "https://github.com/chizhang21/agentrally-operator/blob/main/internal/allocation/pool.go"
click node_prewarming "https://github.com/chizhang21/agentrally-operator/blob/main/internal/allocation/prewarming.go"
click node_executionconfig "https://github.com/chizhang21/agentrally-operator/blob/main/internal/executionconfig/resolve.go"
click node_podconfig "https://github.com/chizhang21/agentrally-operator/blob/main/internal/podconfig/defaults.go"
click node_sandbox "https://github.com/chizhang21/agentrally-operator/blob/main/internal/sandbox/api.go"
click node_workspace "https://github.com/chizhang21/agentrally-operator/blob/main/internal/controller/agentinstance/workspace.go"
click node_capcontroller "https://github.com/chizhang21/agentrally-operator/blob/main/internal/controller/clustercapabilities/controller.go"
click node_capdiscovery "https://github.com/chizhang21/agentrally-operator/blob/main/internal/capabilities/discovery.go"
click node_storage "https://github.com/chizhang21/agentrally-operator/blob/main/internal/capabilities/storage.go"
click node_capresource "https://github.com/chizhang21/agentrally-operator/blob/main/api/v1alpha1/clustercapabilities_types.go"
click node_connector "https://github.com/chizhang21/agentrally-operator/blob/main/cmd/connector/main.go"
click node_invocations "https://github.com/chizhang21/agentrally-operator/blob/main/internal/connector/invocation_client.go"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_groupresource,node_definitionresource,node_instanceresource,node_capresource toneBlue
class node_operator,node_groupcontroller,node_definitioncontroller,node_instancecontroller toneAmber
class node_configuration,node_allocation,node_prewarming,node_executionconfig,node_podconfig,node_sandbox,node_workspace toneMint
class node_capcontroller,node_capdiscovery,node_storage toneRose
class node_connector,node_invocations,node_user,node_backend,node_pod,node_gateway toneIndigo
```

## Components

### Kubernetes API

- [AgentGroup](https://github.com/chizhang21/agentrally-operator/blob/main/api/v1alpha1/agentgroup_types.go): `api/v1alpha1/agentgroup_types.go`
- [AgentDefinition](https://github.com/chizhang21/agentrally-operator/blob/main/api/v1alpha1/agentdefinition_types.go): `api/v1alpha1/agentdefinition_types.go`
- [AgentInstance](https://github.com/chizhang21/agentrally-operator/blob/main/api/v1alpha1/agentinstance_types.go): `api/v1alpha1/agentinstance_types.go`
- [ClusterCapabilities](https://github.com/chizhang21/agentrally-operator/blob/main/api/v1alpha1/clustercapabilities_types.go): `api/v1alpha1/clustercapabilities_types.go`

### Reconciliation

- [Operator manager](https://github.com/chizhang21/agentrally-operator/blob/main/cmd/main.go): `cmd/main.go`
- [Group controller](https://github.com/chizhang21/agentrally-operator/blob/main/internal/controller/agentgroup/controller.go): `internal/controller/agentgroup/controller.go`
- [Definition controller](https://github.com/chizhang21/agentrally-operator/blob/main/internal/controller/agentdefinition/controller.go): `internal/controller/agentdefinition/controller.go`
- [Instance controller](https://github.com/chizhang21/agentrally-operator/blob/main/internal/controller/agentinstance/controller.go): `internal/controller/agentinstance/controller.go`

### Execution and capacity

- [Definition publishing](https://github.com/chizhang21/agentrally-operator/blob/main/internal/definition/revision.go): `internal/definition/revision.go`
- [Capacity allocation](https://github.com/chizhang21/agentrally-operator/blob/main/internal/allocation/pool.go): `internal/allocation/pool.go`
- [Prewarming](https://github.com/chizhang21/agentrally-operator/blob/main/internal/allocation/prewarming.go): `internal/allocation/prewarming.go`
- [Execution configuration](https://github.com/chizhang21/agentrally-operator/blob/main/internal/executionconfig/resolve.go): `internal/executionconfig/resolve.go`
- [Pod configuration](https://github.com/chizhang21/agentrally-operator/blob/main/internal/podconfig/defaults.go): `internal/podconfig/defaults.go`
- [Sandbox lifecycle](https://github.com/chizhang21/agentrally-operator/blob/main/internal/sandbox/api.go): `internal/sandbox/api.go`
- [Workspace volumes](https://github.com/chizhang21/agentrally-operator/blob/main/internal/controller/agentinstance/workspace.go): `internal/controller/agentinstance/workspace.go`

### Cluster platform

- [Capability controller](https://github.com/chizhang21/agentrally-operator/blob/main/internal/controller/clustercapabilities/controller.go): `internal/controller/clustercapabilities/controller.go`
- [Cluster discovery](https://github.com/chizhang21/agentrally-operator/blob/main/internal/capabilities/discovery.go): `internal/capabilities/discovery.go`
- [Storage discovery](https://github.com/chizhang21/agentrally-operator/blob/main/internal/capabilities/storage.go): `internal/capabilities/storage.go`

### External integration

- [Outbound connector](https://github.com/chizhang21/agentrally-operator/blob/main/cmd/connector/main.go): `cmd/connector/main.go`
- [Invocation transport](https://github.com/chizhang21/agentrally-operator/blob/main/internal/connector/invocation_client.go): `internal/connector/invocation_client.go`

### Other components

- **kubectl / GitOps**
- **Connector backend**
- **Agent Pod / PVC**
- **Kubernetes Gateway**

## Connections

- kubectl / GitOps → AgentGroup: applies (evidence: `README.md`)
- kubectl / GitOps → AgentDefinition: applies (evidence: `README.md`)
- kubectl / GitOps → AgentInstance: applies (evidence: `README.md`)
- Operator manager → Group controller: registers (evidence: `cmd/main.go`)
- Operator manager → Definition controller: registers (evidence: `cmd/main.go`)
- Operator manager → Instance controller: registers (evidence: `cmd/main.go`)
- AgentGroup → Group controller: reconciles (evidence: `README.md`)
- AgentDefinition → Definition controller: reconciles (evidence: `README.md`)
- AgentInstance → Instance controller: reconciles (evidence: `README.md`)
- Group controller → Definition controller: prepares namespace (evidence: `README.md`)
- Definition controller → Definition publishing: publishes revision (evidence: `internal/controller/agentdefinition/controller.go`)
- Definition controller → Capacity allocation: retires capacity (evidence: `internal/controller/agentdefinition/controller.go`)
- Instance controller → Execution configuration: resolves config
- Instance controller → Capacity allocation: allocates capacity
- Instance controller → Sandbox lifecycle: manages lifecycle (evidence: `README.md`)
- Instance controller → Workspace volumes: configures workspace (evidence: `README.md`)
- Instance controller → Agent Pod / PVC: creates execution (evidence: `README.md`)
- Capacity allocation → Prewarming: supports spare capacity (evidence: `README.md`)
- Pod configuration → Agent Pod / PVC: configures layout (evidence: `README.md`)
- Capability controller → Cluster discovery: refreshes report (evidence: `internal/controller/clustercapabilities/controller.go`)
- Cluster discovery → Storage discovery: discovers storage
- Capability controller → ClusterCapabilities: updates status (evidence: `internal/controller/clustercapabilities/controller.go`)
- Group controller → ClusterCapabilities: checks network report (evidence: `internal/controller/agentgroup/controller.go`)
- AgentDefinition → Pod configuration: configures container (evidence: `README.md`)
- AgentDefinition → Execution configuration: supplies settings
- AgentInstance → Kubernetes Gateway: configures interaction (evidence: `README.md`)
- Outbound connector → Invocation transport: runs transport (evidence: `cmd/connector/main.go`)
- Invocation transport → Connector backend: exchanges commands (evidence: `internal/connector/invocation_client.go`)