Architecture overview
The agent system consists of three core components:Coordinator
Orchestrates parallel agent execution using decision trees
Semantic analyzer
Classifies user intent without external API calls
Specialized agents
Domain-specific workers (logs, metrics, K8s, security, etc.)
How it works
When you ask a question, Clanker follows this workflow:1. Semantic analysis
The semantic analyzer performs lightweight NLP to classify your query without calling external services. It scores intent by summing keyword weights and infers urgency, timeframe, and target services.2. Decision tree traversal
The coordinator uses the semantic analysis to traverse a decision tree that maps user intent to agent execution strategies.- Condition: When this strategy applies (keyword matching)
- Agent types: Which specialized agents to spawn
- Priority: Execution order for dependency management
- Parameters: Configuration for the agents
3. Parallel agent execution
The coordinator spawns agents in dependency-aware groups, running independent agents in parallel while respecting data dependencies.Agent types
Clanker includes specialized agents for different investigation domains:Log agent
Log agent
Discovers log groups, retrieves recent entries, and identifies error patterns.Provides:
Execution order: 1 (no dependencies)
logs, error_patterns, log_metricsExecution order: 1 (no dependencies)
Metrics agent
Metrics agent
Gathers CloudWatch metrics, performance data, and threshold violations.Provides:
Execution order: 1 (no dependencies)
metrics, performance_data, thresholdsExecution order: 1 (no dependencies)
Infrastructure agent
Infrastructure agent
Checks service configuration, deployment status, and resource health.Provides:
Execution order: 2 (can use metrics/logs if available)
service_config, deployment_status, resource_healthExecution order: 2 (can use metrics/logs if available)
Security agent
Security agent
Analyzes access patterns, security configurations, and vulnerabilities.Requires:
Provides:
Execution order: 3 (depends on logs and infrastructure)
logs, service_configProvides:
security_status, access_patterns, vulnerabilitiesExecution order: 3 (depends on logs and infrastructure)
K8s agent
K8s agent
Inspects Kubernetes cluster resources, pod health, and deployment status.Provides:
Execution order: 1 (no dependencies)
k8s_resources, k8s_healthExecution order: 1 (no dependencies)
Performance agent
Performance agent
Identifies bottlenecks and provides scaling recommendations.Requires:
Provides:
Execution order: 5 (depends on metrics, logs, infrastructure)
metrics, logs, resource_healthProvides:
performance_analysis, bottlenecks, scaling_recommendationsExecution order: 5 (depends on metrics, logs, infrastructure)
internal/agent/coordinator/agent_types.go.
Chain of thought tracking
Every agent decision is recorded in a chain of thought for debugging and transparency:Enable agent tracing with
--agent-trace or debug: true in your config to see detailed coordinator lifecycle logs.Performance characteristics
| Approach | Time | Requests |
|---|---|---|
| Sequential (naive) | 6-8 seconds | 5-10 serial calls |
| Parallel agents | 2-3 seconds | 5-10 concurrent calls |
Example execution
Here’s what happens when you ask “Why is my Lambda failing?”:Semantic analysis
Intent:
Urgency:
Target services:
Data types:
troubleshoot (confidence 0.85)Urgency:
highTarget services:
lambda, logsData types:
logs, metrics, statusAgent spawning
Order group 1:
- Log agent (discover Lambda log groups, get recent errors)
- Metrics agent (get Lambda metrics: invocations, errors, duration)
- Infrastructure agent (get Lambda configuration, environment variables)
Next steps
Natural language
Learn how Clanker interprets your questions
Agent architecture
Deep dive into agent implementation