Platform Architecture and Agent Orchestration
Reference architecture (components)
flowchart TD
TI[Task Intake<br/>migration wave / issue / backlog] --> AM[Agent Manager<br/>scheduler, quotas, path locks]
AM --> WE[Workflow Engine<br/>Temporal or Argo]
WE --> SR[Sandbox Runner Pool<br/>ephemeral k8s jobs]
SR --> RS[Repo Snapshot + Cache<br/>sparse checkout, artifact cache]
SR --> TC[Toolchain Images<br/>TS, Go, linters, test tools]
SR --> LG[LLM Gateway<br/>cloud + local models]
AM --> PE[Policy Engine<br/>ownership, secrets, guardrails]
SR --> CI[CI / Checks / PR Bot] --> GH[GitHub PRs / Checks / Merge Queue]
WE --> TS2[Triage Service] --> SU[Stakeholder UI] --> SL[Slack / Jira / Email]
SR --> OC[OTel Collector] --> MB[Metrics/Logs/Traces Backend] --> DA[Dashboards / Alerts]
Separate workflow state, execution sandboxes, developer-surface integrations.
Agent roles
| Role | Responsibility |
|---|---|
| Analysis agent | Builds impact + dependency context |
| Plan agent | Change strategy, identifies missing info |
| Code-modification agent | Edits code inside sandbox |
| Test/repair agent | Targeted tests/lint/build, loops on failures within bounded retries |
| CI integration agent | Publishes GitHub Checks + annotations |
| PR agent | Draft PRs, evidence, descriptions, check summaries |
| Review agent | PR review comments on unified diff |
| Stakeholder-Q&A triage agent | Blocking ambiguity into structured questions, routes, resumes on answer |
Backbone: GitHub Checks API, review-comment endpoints, App auth model, webhooks, CODEOWNERS.
Scheduling and concurrency
Optimize for conflict avoidance and CI survivability, not raw agent count. Four gating dimensions:
- Path locks — semaphores on directories/packages/service boundaries (no two agents rewriting the same subsystem).
- Component-owner quotas
- CI lane quotas — protect runner capacity.
- Fleet-wide cost quotas
Priority classes favor short validation jobs + escalated blockers over background exploration. Argo: mutexes, semaphores, priority, retries. K8s: quotas, pod priority. Temporal: task queues, workers poll only with spare capacity.
Initial scaling target: 1,000 logical agents; 100–250 active code-writing executions; 20–50 validation-heavy executions; single-digit merge-queue lanes per protected branch. Everyone else waits on locks, CI capacity, or stakeholder answers.
Resource isolation (multi-tenant)
Every sandbox: ephemeral, non-privileged by default, identity-scoped.
- K8s ResourceQuotas (CPU/mem/storage/object counts per namespace)
- Pod Security Standards (baseline/restricted)
- NetworkPolicies (east-west traffic)
- Projected service-account tokens (time-bound)
- IRSA / workload identity for least-privilege cloud access
- Stronger containment: gVisor (application-kernel), Kata (lightweight VMs)
- GitHub Actions: ephemeral self-hosted runners, ARC on Kubernetes for autoscaling. CI validation via ARC; agent platform uses custom sandbox jobs for non-CI execution.
Orchestration comparison
| Option | Best fit | Strengths | Limits |
|---|---|---|---|
| Temporal | Durable multi-step agent workflows: waiting states, approvals, retries, resumability | Durable/recoverable executions, huge concurrency, task queues + server-side throttling | More platform complexity than pure K8s jobs |
| Argo Workflows | K8s-native DAGs, batch waves, controlled parallelism | Semaphores, mutexes, priority, retry strategies, native K8s fit | Less natural for long-lived “waiting on human” state |
| K8s Jobs + custom queue | Simple execution substrate | Flexible, easy to reason about, run-to-completion isolation | You build durable state, retries, routing, observability yourself |
Recommendation: Temporal for agent lifecycle orchestration + K8s Jobs for execution. Argo if org already has strong K8s workflow maturity and human-wait states are small.