Agent-as-Code (AaC) uses a unique hybrid architecture that combines a high-performance Go core with flexible runtime environments, primarily focusing on Python for AI/ML workloads.
This diagram maps the primary Go packages and CLI entry points to their roles in the system. Commands in internal/cmd/* invoke the parser (internal/parser/agent.go), builder (internal/builder/builder.go), runtime (internal/runtime/runtime.go), and registry (internal/registry/registry.go).
flowchart TB
subgraph "Agent-as-Code Framework"
subgraph "Core Layer"
GC[Go Core<br/>Performance]
RS[Runtime System<br/>Execution]
RG[Registry<br/>Distribution]
CLI[CLI Interface<br/>User Entry]
end
subgraph "Support Layer"
AY[agent.yaml<br/>Config]
TP[Templates<br/>Reuse]
LLM[Local LLM<br/>Ollama]
BS[Build System<br/>Container]
end
end
GC --> RS
RS --> RG
CLI --> GC
AY --> GC
TP --> BS
LLM --> RS
BS --> RG
This view links user surfaces (CLI in internal/cmd/*) to core subsystems and execution/storage backends used during agent init/build/run/push flows.
flowchart TB
subgraph "User Layer"
CLI[CLI Commands<br/>agent CLI]
WI[Web Interface<br/>Dashboard]
API[API Clients<br/>SDK]
CICD[CI/CD Tools<br/>GitHub/GitLab]
end
subgraph "Core Layer"
PR[Parser<br/>YAML/JSON]
BD[Builder<br/>Docker]
RT[Runtime<br/>Container]
RG[Registry<br/>Storage]
end
subgraph "Runtime Layer"
PY[Python<br/>AI/ML]
NJ[Node.js<br/>Web]
GO[Go<br/>Performance]
CU[Custom<br/>Runtimes]
end
subgraph "Storage Layer"
DK[Docker<br/>Images]
K8S[Kubernetes<br/>Orchestration]
CL[Cloud<br/>AWS/GCP/Azure]
LF[Local<br/>Filesystem]
end
CLI --> PR
WI --> PR
API --> PR
CICD --> BD
PR --> BD
BD --> RT
RT --> RG
RT --> PY
RT --> NJ
RT --> GO
RT --> CU
BD --> DK
RT --> K8S
RG --> CL
RT --> LF
End-to-end flow grounded in the codepath: internal/cmd/* → parser (ParseFile/Validate) → builder (generateDockerfile/buildDockerImage) → image → registry (Push/Pull) → runtime (Run/Stop/StreamLogs).
flowchart LR
UI[User Input] --> CLI[CLI Interface]
CLI --> PR[Parser<br/>YAML]
PR --> BD[Builder<br/>Docker]
BD --> CI[Container Image]
CI --> RG[Registry Storage]
RG --> RM[Runtime Manager]
RM --> RO[Results Output]
style UI fill:#e1f5fe
style RO fill:#e8f5e8
style CI fill:#fff3e0
Reflects types and methods in internal/parser/agent.go: AgentSpec, AgentMetadata, AgentSpecDetails, and methods FindAgentFile, ParseFile, Parse, Validate.
flowchart TB
subgraph "Parser Component"
subgraph "Input Layer"
AY[agent.yaml<br/>agent.yml<br/>Agent.yaml<br/>Agent.yml]
end
subgraph "Processing Layer"
YP[YAML Parser<br/>gopkg.in/yaml.v3]
SV[Schema Validator]
end
subgraph "Output Layer"
VA[Validated AgentSpec]
MD[Metadata]
SD[Spec Details]
EH[Error Handler]
end
end
AY --> YP
YP --> SV
SV --> VA
VA --> MD
VA --> SD
SV --> EH
style AY fill:#e3f2fd
style VA fill:#e8f5e8
style EH fill:#ffebee
Concrete call sequence in the parser: FindAgentFile → file read → YAML unmarshal → Validate (required fields, runtime allowlist, port checks) → AgentSpec in-memory model.
flowchart LR
FD[File Discovery] --> YP[YAML Parsing]
YP --> SV[Schema Validation]
SV --> VO[Validated Output]
subgraph "Process Steps"
FF[FindAgentFile]
UM[Unmarshal YAML]
VR[Validate Required Fields]
VR2[Validate Runtime]
VR3[Validate Ports]
AS[AgentSpec Struct]
end
FD --> FF
YP --> UM
SV --> VR
VR --> VR2
VR2 --> VR3
VR3 --> AS
style FD fill:#e3f2fd
style VO fill:#e8f5e8
Based on internal/builder/builder.go: ValidateContext ensures a valid agent.yaml; generateDockerfile emits runtime-specific Dockerfiles; buildDockerImage streams build output; Push publishes tags.
flowchart TB
subgraph "Builder Component"
subgraph "Input Layer"
VA[Validated AgentSpec]
BC[Build Context]
end
subgraph "Processing Layer"
DG[Dockerfile Generator]
RT[Runtime Specific Template]
DE[Docker Build Engine]
end
subgraph "Output Layer"
CI[Container Image]
II[Image ID]
IS[Image Size]
IT[Image Tags]
RP[Registry Push]
end
end
VA --> DG
BC --> DG
DG --> RT
RT --> DE
DE --> CI
CI --> II
CI --> IS
CI --> IT
CI --> RP
style VA fill:#e8f5e8
style CI fill:#fff3e0
Build phases as implemented: parse/validate config → generate Dockerfile (runtime templates) → Docker build (BuildKit via API) → optional push to a registry.
flowchart LR
PC[Parse Config] --> GD[Generate Dockerfile]
GD --> BI[Build Image]
BI --> PR[Push Registry]
subgraph "Process Details"
VC[Validate Context]
RT[Runtime Template]
DB[Docker BuildKit]
RC[Registry Client]
SO[Stream Output]
end
PC --> VC
GD --> RT
BI --> DB
PR --> RC
DB --> SO
style PC fill:#e3f2fd
style PR fill:#e8f5e8
From internal/runtime/runtime.go: Runtime uses the Docker client to create/start containers with parsed ports, env, volumes; returns ContainerInfo and can stream logs or stop containers.
flowchart TB
subgraph "Runtime Component"
subgraph "Input Layer"
CI[Container Image]
RO[Runtime Options]
end
subgraph "Execution Layer"
CM[Container Manager]
DC[Docker Client]
PM[Port Mapping]
VM[Volume Mounts]
end
subgraph "Output Layer"
CI2[Container Info]
ID[ID]
NM[Name]
PT[Ports]
HM[Health Monitor]
end
end
CI --> CM
RO --> CM
CM --> DC
CM --> PM
CM --> VM
CM --> CI2
CI2 --> ID
CI2 --> NM
CI2 --> PT
CM --> HM
style CI fill:#fff3e0
style CI2 fill:#e8f5e8
Execution path in code: ValidateImage (local inspect) → ContainerCreate with port bindings/env/volumes → ContainerStart → log streaming and health handling.
flowchart LR
VI[Validate Image] --> CC[Create Container]
CC --> SC[Start Container]
SC --> MH[Monitor Health]
subgraph "Execution Details"
CL[Check Local Image]
CP[Configure Ports]
CV[Configure Volumes]
EP[Execute Entry Point]
LS[Log Streaming]
HC[Health Checks]
end
VI --> CL
CC --> CP
CC --> CV
SC --> EP
MH --> LS
MH --> HC
style VI fill:#e3f2fd
style MH fill:#e8f5e8
Grounded in internal/registry/registry.go: routes operations to Docker Hub or custom agent registries; supports Push, Pull, local image listing, and basic filtering.
flowchart TB
subgraph "Registry Component"
subgraph "Input Layer"
LI[Local Images]
RO[Registry Operations]
end
subgraph "Processing Layer"
RR[Registry Router]
AR[Agent Registry]
DR[Docker Registry]
AM[Auth Manager]
end
subgraph "Output Layer"
PR[Push/Pull Results]
IM[Image Metadata]
DG[Digest]
SZ[Size]
SE[Search Engine]
end
end
LI --> RR
RO --> RR
RR --> AR
RR --> DR
RR --> AM
AR --> PR
DR --> PR
PR --> IM
IM --> DG
IM --> SZ
RR --> SE
style LI fill:#e3f2fd
style PR fill:#e8f5e8
Operational flow: validate auth/token → choose registry target → stream push/pull via Docker API → parse basic results (repository/tag/digest/size).
flowchart LR
AR[Authenticate Request] --> RO[Route Operation]
RO --> EO[Execute Operation]
EO --> RR[Return Results]
subgraph "Operation Details"
VT[Validate Token]
SR[Select Registry]
SD[Stream Data]
PR[Parse Response]
end
AR --> VT
RO --> SR
EO --> SD
EO --> PR
style AR fill:#e3f2fd
style RR fill:#e8f5e8
How internal/cmd/init.go, build.go, run.go, and push.go wire the CLI to parser, builder, runtime, and registry, matching the end-to-end developer workflow.
flowchart TB
subgraph "System Integration Layer"
subgraph "CLI Layer"
AI[agent init]
AB[agent build]
AR[agent run]
AP[agent push]
end
subgraph "Core Layer"
PR[Parser]
BD[Builder]
RT[Runtime]
RG[Registry]
end
subgraph "Runtime Layer"
CM[Container Manager]
HM[Health Monitor]
LM[Log Manager]
MC[Metrics Collector]
end
end
AI --> PR
AB --> BD
AR --> RT
AP --> RG
PR --> BD
BD --> RT
RT --> RG
RT --> CM
RT --> HM
RT --> LM
RT --> MC
style AI fill:#e3f2fd
style AP fill:#e3f2fd
style MC fill:#e8f5e8
Reference deployment topology for the images produced by the builder and pushed by the registry client. Scaling/orchestration is handled by the target platform (e.g., Docker/Kubernetes).
flowchart TB
subgraph "Deployment Architecture"
subgraph "Environments"
DE[Development Environment]
SE[Staging Environment]
PE[Production Environment]
end
subgraph "Components"
LB[Local Build]
TR[Test Registry]
PR[Production Registry]
LR[Local Runtime]
SR[Staging Runtime]
PR2[Production Runtime]
end
subgraph "CI/CD Pipeline"
SC[Source Code]
BT[Build & Test]
DP[Deploy]
GR[Git Repository]
AB[Agent Build]
KD[Kubernetes Deployment]
SM[Service Mesh]
end
end
DE --> LB
SE --> TR
PE --> PR
DE --> LR
SE --> SR
PE --> PR2
GR --> SC
SC --> BT
BT --> AB
AB --> DP
DP --> KD
KD --> SM
style DE fill:#e3f2fd
style PE fill:#e8f5e8
Security facets reflected in code: use of AGENT_REGISTRY_URL/AGENT_REGISTRY_TOKEN in registry.New(), environment inspection in version.go, and Docker client auth delegation for registry operations.
flowchart TB
subgraph "Security Architecture"
subgraph "Authentication Layer"
AKM[API Key Management]
TBA[Token-Based Auth]
OAF[OAuth2 Flow]
end
subgraph "Authorization Layer"
RBAC[Role-Based Access Control]
RL[Resource Limits]
CC[Capability Controls]
end
subgraph "Secrets Management"
EV[Environment Variables]
KS[Kubernetes Secrets]
HV[HashiCorp Vault]
end
subgraph "Network Security"
FR[Firewall Rules]
NP[Network Policies]
TE[TLS/SSL Encryption]
IW[IP Whitelisting]
end
end
AKM --> RBAC
TBA --> RL
OAF --> CC
EV --> AKM
KS --> TBA
HV --> OAF
FR --> NP
NP --> TE
TE --> IW
style AKM fill:#e3f2fd
style HV fill:#e8f5e8
High-level request hardening steps complementary to the current CLI; registry operations authenticate via Docker client or provided tokens, with auditability via CLI output/logs.
flowchart LR
RA[Request Arrives] --> AU[Authenticate User]
AU --> AR[Authorize Request]
AR --> EO[Execute Operation]
subgraph "Security Steps"
VI[Validate Input]
CC[Check Credentials]
VP[Verify Permissions]
AL[Audit Log]
end
RA --> VI
AU --> CC
AR --> VP
EO --> AL
style RA fill:#e3f2fd
style EO fill:#e8f5e8
Operational visibility built around Docker metrics/logs: Runtime.StreamLogs supports continuous log streaming; additional metrics/alerts are intended to be provided by the deployment platform.
flowchart TB
subgraph "Monitoring Architecture"
subgraph "Data Collection"
MC[Metrics Collector]
LA[Log Aggregator]
HC[Health Checks]
end
subgraph "Processing Layer"
PM[Prometheus]
ES[ELK Stack]
AM[Alert Manager]
end
subgraph "Visualization Layer"
GD[Grafana Dashboards]
LA2[Log Analysis]
NS[Notification System]
end
subgraph "Metrics Types"
RM[Runtime Metrics]
AM2[Application Metrics]
IM[Infrastructure Metrics]
end
end
MC --> PM
LA --> ES
HC --> AM
PM --> GD
ES --> LA2
AM --> NS
RM --> MC
AM2 --> MC
IM --> MC
style MC fill:#e3f2fd
style GD fill:#e8f5e8
Reference flow for integrating container runtime logs/metrics into a typical Prometheus/Grafana and ELK stack when agents are deployed in production.
flowchart LR
AR[Agent Runtime] --> MC[Metrics Collector]
MC --> SQ[Storage & Query]
SQ --> AE[Alerting Engine]
subgraph "Data Processing"
GM[Generate Metrics]
AF[Aggregate & Filter]
TS[Time Series]
ET[Evaluate Thresholds]
end
AR --> GM
MC --> AF
SQ --> TS
AE --> ET
style AR fill:#e3f2fd
style AE fill:#e8f5e8
Reference scaling model: AaC outputs container images; horizontal/vertical scaling is performed by the orchestrator (e.g., HPA/VPA in Kubernetes) around the built agent containers.
flowchart TB
subgraph "Scalability Architecture"
subgraph "Load Balancer"
TD[Traffic Distribution]
HC2[Health Checks]
SA[Session Affinity]
end
subgraph "Auto-scaling Engine"
HPA[HPA (K8s)]
VPA[VPA (K8s)]
CM2[Custom Metrics]
end
subgraph "Resource Management"
CM3[CPU Monitoring]
MM[Memory Monitoring]
SM2[Storage Monitoring]
end
end
TD --> HPA
HC2 --> VPA
SA --> CM2
HPA --> CM3
VPA --> MM
CM2 --> SM2
style TD fill:#e3f2fd
style SM2 fill:#e8f5e8
Decision loop situates outside of AaC code and acts on platform metrics; AaC remains the image/entrypoint provider for scaled workloads.
flowchart LR
MM2[Monitor Metrics] --> AP[Analyze Patterns]
AP --> DS[Decide Scaling]
DS --> EA[Execute Actions]
subgraph "Scaling Process"
CR[Collect Real-time]
MLA[ML Algorithm]
SU[Scale Up]
SD2[Scale Down]
PR3[Provision Resources]
end
MM2 --> CR
AP --> MLA
DS --> SU
DS --> SD2
EA --> PR3
style MM2 fill:#e3f2fd
style EA fill:#e8f5e8
Production topology illustrating how the built agent images run behind gateways and load balancers with service mesh and storage integrations—consistent with containerized deployment of AaC agents.
flowchart TB
subgraph "Production Environment"
subgraph "Internet Gateway"
CDN[CDN<br/>CloudFlare]
WAF[WAF<br/>Security]
end
subgraph "Load Balancer"
TD2[Traffic Distribution]
HC3[Health Checks]
end
subgraph "Application Layer"
AI2[Agent Instances]
ASG[Auto-scaling Groups]
end
subgraph "Infrastructure Layer"
KC[Kubernetes Cluster]
SM3[Service Mesh]
EN[Envoy Proxy]
end
subgraph "Data Layer"
MS[Monitoring Stack]
LS2[Logging Stack]
BS2[Backup System]
end
end
CDN --> WAF
WAF --> TD2
TD2 --> HC3
HC3 --> AI2
AI2 --> ASG
ASG --> KC
KC --> SM3
SM3 --> EN
AI2 --> MS
KC --> LS2
KC --> BS2
style CDN fill:#e3f2fd
style BS2 fill:#e8f5e8
Reference HA design for running multiple agent instances and stateful dependencies across regions; the AaC-produced images participate as stateless workloads.
flowchart TB
subgraph "High Availability"
subgraph "Primary Region"
AS[Active Services]
DM[Database Master]
SP[Storage Primary]
end
subgraph "Secondary Region"
SS[Standby Services]
DR2[Database Replica]
SB[Storage Backup]
end
subgraph "Failover Mechanism"
HM2[Health Monitoring]
AF2[Auto Failover]
DS3[Data Sync]
end
end
AS --> HM2
DM --> DS3
SP --> DS3
HM2 --> AF2
AF2 --> SS
DS3 --> DR2
DS3 --> SB
style AS fill:#e3f2fd
style AF2 fill:#e8f5e8
Performance guidance tied to current implementation: the builder optimizes context creation (skips dotfiles), orders layers for better caching, and relies on Docker’s caching; runtime uses Docker APIs efficiently.
flowchart TB
subgraph "Performance Architecture"
subgraph "Application Level"
CO[Code Optimization]
AO[Algorithm Efficiency]
CS[Caching Strategy]
end
subgraph "Runtime Level"
MP[Memory Pooling]
CP[Connection Pooling]
RL2[Resource Limits]
end
subgraph "Infrastructure Level"
CA[CPU Affinity]
NT[Network Tuning]
SO2[Storage Optimization]
end
subgraph "Caching Strategy"
L1C[L1 Cache<br/>Memory]
L2C[L2 Cache<br/>Redis]
L3C[L3 Cache<br/>CDN]
end
end
CO --> MP
AO --> CP
CS --> RL2
MP --> CA
CP --> NT
RL2 --> SO2
CS --> L1C
CS --> L2C
CS --> L3C
style CO fill:#e3f2fd
style L3C fill:#e8f5e8
Forward-looking areas to consider alongside the current code: broader runtime integrations, improved caching strategies in the builder, and richer orchestration hooks around the runtime/registry.
flowchart LR
subgraph "Future Architecture"
subgraph "Phase 1 (Q2 2024)"
ELL[Enhanced Local LLM]
MC2[Model Caching]
MP2[Multi-Platform]
end
subgraph "Phase 2 (Q3 2024)"
AO2[Advanced Orchestration]
SM4[Service Mesh]
CM4[Custom Metrics]
end
subgraph "Phase 3 (Q4 2024)"
AIP[AI/ML Pipeline]
EC[Edge Computing]
QC[Quantum Computing]
end
subgraph "Innovation Areas"
AML[AutoML Pipelines]
FL[Federated Learning]
IOT[IoT Integration]
QS[Quantum Security]
end
end
ELL --> AO2
MC2 --> SM4
MP2 --> CM4
AO2 --> AIP
SM4 --> EC
CM4 --> QC
AIP --> AML
EC --> IOT
QC --> QS
style ELL fill:#e3f2fd
style QC fill:#e8f5e8
The Go core provides:
- High-performance CLI operations
- Configuration parsing and validation
- Build system
- Runtime orchestration
- Registry operations
Key features:
- Fast startup time
- Low memory footprint
- Cross-platform compatibility
- Strong type safety
- Concurrent operations
Implementation:
// Core configuration parser
type AgentSpec struct {
APIVersion string `yaml:"apiVersion"`
Kind string `yaml:"kind"`
Metadata AgentMetadata `yaml:"metadata"`
Spec AgentSpecDetails `yaml:"spec"`
}
// Runtime manager
type RuntimeManager struct {
runtime string
model ModelConfig
config map[string]interface{}
}
// Builder system
type Builder struct {
parser *Parser
runtime *RuntimeManager
registry *Registry
}The runtime system manages:
- Agent execution environments
- Model integration
- Resource management
- Monitoring and health checks
Supported runtimes:
- Python (primary for AI/ML)
- Node.js
- Go
- Rust
- Java
Example Python runtime:
class AgentRuntime:
def __init__(self, config: dict):
self.model = self.init_model(config)
self.capabilities = self.load_capabilities(config)
async def execute(self, input: dict) -> dict:
result = await self.model.generate(input)
return self.process_result(result)Handles:
- Agent image storage
- Version management
- Distribution
- Authentication
Features:
- Secure storage
- Version control
- Access management
- Image validation
Based on agent.yaml:
- Kubernetes-inspired format
- Declarative configuration
- Validation system
- Environment management
Example:
apiVersion: agent.dev/v1
kind: Agent
metadata:
name: my-agent
spec:
runtime: python:3.11
model:
provider: openai
name: gpt-4Provides:
- Reusable agent templates
- Best practice implementations
- Quick start capabilities
- Customization options
- Build Process
agent.yaml → Parser → Validator → Builder → Runtime → Image
- Execution Flow
Image → Runtime Manager → Model Setup → Agent Execution → Results
- Distribution Flow
Image → Registry Client → Authentication → Upload → Distribution
class ModelManager:
def __init__(self, config: dict):
self.provider = config["provider"]
self.model = self.load_model(config)
async def generate(self, prompt: str) -> str:
return await self.model.generate(prompt)type RuntimeIntegration struct {
Name string
Version string
Handler func(config map[string]interface{}) error
}
func (r *RuntimeIntegration) Execute(input []byte) ([]byte, error) {
// Runtime-specific execution logic
}type RegistryClient struct {
URL string
Auth AuthConfig
Transport http.RoundTripper
}
func (r *RegistryClient) PushImage(image Image) error {
// Image push logic
}-
Authentication
- API key management
- Token-based auth
- Registry authentication
-
Authorization
- Role-based access
- Resource limits
- Capability controls
-
Secrets Management
- Environment variables
- Secure storage
- Runtime injection
-
Metrics
- Runtime statistics
- Model performance
- Resource usage
-
Logging
- Structured logging
- Error tracking
- Audit trails
-
Health Checks
- Agent status
- Model health
- Resource monitoring
-
Go Core
- Minimal memory footprint
- Fast startup time
- Efficient concurrency
-
Runtime Optimization
- Resource pooling
- Cache management
- Memory efficiency
-
Distribution
- Efficient image format
- Layer caching
- Delta updates
-
Local Development
agent init my-agent agent build -t my-agent:dev . agent run my-agent:dev -
Testing
agent test my-agent:dev agent inspect my-agent:dev -
Deployment
agent push my-agent:latest agent deploy my-agent:latest
-
Configuration
- Use version control
- Implement validation
- Document changes
-
Development
- Follow templates
- Use type hints
- Write tests
-
Deployment
- Use staging
- Monitor resources
- Implement logging
Planned enhancements:
- Enhanced local LLM support
- Improved model caching
- Advanced orchestration
- Extended runtime support
- Enhanced security features