AI Orchestration
AMOF includes a custom AI agent runtime -- a full orchestrator that plans tasks, delegates to specialized workers, manages context, and enforces safety guardrails.
Overview
User Goal
|
v
+------------------+
| Agent Loop | Message -> LLM -> Tool Calls -> Execute -> Loop
+------------------+
|
v
+------------------+
| Task Planner | Breaks complex goals into subtask DAGs
+------------------+
|
v
+------------------+ +------------------+
| Executor | --> | Runners | code, k8s, helm, debug, jenkins
+------------------+ +------------------+
|
v
+------------------+
| Model Router | Selects model by complexity, risk, context size
+------------------+Agent Loop
The core agent loop in Agent.run() follows this cycle: receive message, build context, call LLM, parse response, execute tool calls, append results, loop until completion or budget exceeded.
Execution Modes
| Mode | Command | Behavior |
|---|---|---|
| Interactive | amof agent | REPL with slash commands (/status, /cost, /release, /review, /quit) |
| Single-shot | amof agent "task" | Execute one goal and exit |
| Plan-only | amof agent --plan "goal" | Read-only analysis; produces structured plan without modifying files |
Safety Controls
| Control | Mechanism |
|---|---|
| Cost ceiling | default_max_cost in agent.yaml (default: $5.00) |
| Budget warnings | Alerts at 50%, 75%, and 90% of budget |
| Iteration guard | Maximum iteration count prevents infinite loops |
| Lint-on-complete | All modified files linted before task completion |
Planner-Executor Architecture
Phase 1: Planning
The TaskPlanner uses a strong model to decompose a goal into a directed acyclic graph (DAG) of subtasks. Each subtask has an id, title, description, runner assignment, and dependency list.
Phase 2: Execution
The SubtaskExecutor iterates through subtasks in dependency order. For each subtask it resolves the runner, loads the prompt and tools, executes, and feeds results into the next dependent subtask.
Model Router & LLM Ladder
| Factor | Behavior |
|---|---|
| Low complexity (< 0.20) | Routes to fast tier (worker cascade) |
| High complexity (> 0.60) | Routes to strong tier (orchestrator cascade) |
| Large context (> 200k tokens) | Forces strong tier |
| Risk escalation | Infrastructure/deployment always use strong tier |
| Provider health | Tracks failures; routes around degraded providers |
| Fallback | Primary Anthropic, fallback OpenAI, 60s cooldown |
BYOK (Bring Your Own Key)
| Provider | Variable | Notes |
|---|---|---|
| Anthropic | ANTHROPIC_API_KEY | Auto SSL cert detection for corporate proxies |
| OpenAI | OPENAI_API_KEY | GPT and o-series models |
| OpenRouter | OPENROUTER_API_KEY | Unified gateway to 100+ models |
Tool System
Core Tools
| Tool | Description |
|---|---|
| Read | Read file contents with path validation |
| Write | Create or overwrite files (guardrail-checked) |
| StrReplace | Surgical find-and-replace within files |
| Delete | Delete files (guardrail-checked) |
| Shell | Execute shell commands (command blocking enforced) |
| Grep | Regex search across the codebase |
| Glob | Find files matching glob patterns |
| LS | List directory contents |
Orchestration Tools
| Tool | Description |
|---|---|
| Delegate | Spawn sub-agents for parallel subtask execution |
| MemorySearch | Semantic vector search over codebase embeddings |
| GitCheckpoint | Save and restore Git state for safe experimentation |
| ReadLints | Run linters and return diagnostics |
Operational Tools
| Tool | Description |
|---|---|
| K8s | Kubernetes pod inspection, log viewing, environment variables |
| Helm | Chart templating, diffing, syncing |
| Jenkins | Trigger CI/CD pipelines |
| Images | Container image discovery, diffing, migration |
| Audit | Record changelog entries |
Domain Runners
| Runner | Tools | Tier | Max Iterations |
|---|---|---|---|
| code | Read, Write, StrReplace, Delete, Shell, Grep, Glob, LS, GitCheckpoint, ReadLints | standard | 50 |
| k8s | K8s, Shell, Read, Grep | fast | 30 |
| helm | Helm, Read, Write, Shell, Grep, Glob | standard | 40 |
| debug | K8s, Read, Grep, Shell | standard | 40 |
| jenkins | Jenkins, Shell | fast | 20 |
Context Pipeline
- Repo Profiling: amof profile generates tech stack profiles from manifest files (Chart.yaml, package.json, etc.)
- Context Building: Assembles system prompt from repo profiles, ecosystem manifest, guardrails, codebase index, and rules
- Codebase Indexing: Incremental via Merkle tree -- only changed files sent to LLM (~$0.01-$0.10 incremental vs $0.10-$0.50 full)
- Context Summarization: Compresses old conversation turns while preserving file paths, decisions, and error resolutions
- High-Risk File Identification: Scores files by complexity, dependency count, and entry point status
Extended Thinking
| Setting | Behavior |
|---|---|
| Auto-detection | Identifies thinking-capable models; sets temperature=1, thinking.type=adaptive |
| Budget | thinking_budget: 16000 tokens in agent.yaml |
| Display | Thinking blocks rendered in faded italic in interactive shell |
| Prefill | Conditional assistant prefill disabled for thinking models (API requirement) |