How chizhang21/agentrally-operator works
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: agentinstance/controller.go Instance controller · agentdefinition/controller.go Definition controller · agentdefinition_types.go AgentDefinition · agentgroup/controller.go Group controller
Components 24
Kubernetes API
- AgentGroup
api/v1alpha1/agentgroup_types.go - AgentDefinition
api/v1alpha1/agentdefinition_types.go - AgentInstance
api/v1alpha1/agentinstance_types.go - ClusterCapabilities
api/v1alpha1/clustercapabilities_types.go
Reconciliation
- Operator manager
cmd/main.go - Group controller
internal/controller/agentgroup/controller.go - Definition controller
internal/controller/agentdefinition/controller.go - Instance controller
internal/controller/agentinstance/controller.go
Execution and capacity
- Definition publishing
internal/definition/revision.go - Capacity allocation
internal/allocation/pool.go - Prewarming
internal/allocation/prewarming.go - Execution configuration
internal/executionconfig/resolve.go - Pod configuration
internal/podconfig/defaults.go - Sandbox lifecycle
internal/sandbox/api.go - Workspace volumes
internal/controller/agentinstance/workspace.go
Cluster platform
- Capability controller
internal/controller/clustercapabilities/controller.go - Cluster discovery
internal/capabilities/discovery.go - Storage discovery
internal/capabilities/storage.go
External integration
- Outbound connector
cmd/connector/main.go - Invocation transport
internal/connector/invocation_client.go
Other components
- kubectl / GitOps
- Connector backend
- Agent Pod / PVC
- Kubernetes Gateway
Connections 28
- kubectl / GitOps → AgentGroup: applies
README.md - kubectl / GitOps → AgentDefinition: applies
README.md - kubectl / GitOps → AgentInstance: applies
README.md - Operator manager → Group controller: registers
cmd/main.go - Operator manager → Definition controller: registers
cmd/main.go - Operator manager → Instance controller: registers
cmd/main.go - AgentGroup → Group controller: reconciles
README.md - AgentDefinition → Definition controller: reconciles
README.md - AgentInstance → Instance controller: reconciles
README.md - Group controller → Definition controller: prepares namespace
README.md - Definition controller → Definition publishing: publishes revision
internal/controller/agentdefinition/controller.go - Definition controller → Capacity allocation: retires capacity
internal/controller/agentdefinition/controller.go - Instance controller → Execution configuration: resolves config
- Instance controller → Capacity allocation: allocates capacity
- Instance controller → Sandbox lifecycle: manages lifecycle
README.md - Instance controller → Workspace volumes: configures workspace
README.md - Instance controller → Agent Pod / PVC: creates execution
README.md - Capacity allocation → Prewarming: supports spare capacity
README.md - Pod configuration → Agent Pod / PVC: configures layout
README.md - Capability controller → Cluster discovery: refreshes report
internal/controller/clustercapabilities/controller.go - Cluster discovery → Storage discovery: discovers storage
- Capability controller → ClusterCapabilities: updates status
internal/controller/clustercapabilities/controller.go - Group controller → ClusterCapabilities: checks network report
internal/controller/agentgroup/controller.go - AgentDefinition → Pod configuration: configures container
README.md - AgentDefinition → Execution configuration: supplies settings
- AgentInstance → Kubernetes Gateway: configures interaction
README.md - Outbound connector → Invocation transport: runs transport
cmd/connector/main.go - Invocation transport → Connector backend: exchanges commands
internal/connector/invocation_client.go