Docs · The doctrine · Section 13
Summary decision matrix
Everything above fits in one decision table. Each row is a trade-off, with its recommended default and the signal that commands a change.
The trade-off matrix
| Decision | Recommended default | Evolve when |
|---|---|---|
| Core language | TypeScript (orchestration and interface) | Never without a reason; polyglot goes through a sidecar or a service. |
| Specialized capability | Sidecar in the library's language | As soon as a mature library lives in another ecosystem. |
| Component on the critical path | Compiled service behind a contract | Latency or throughput proven insufficient. |
| Decomposition | Hexagonal modular monolith | Load, lifecycle, isolation, or high availability demand it. |
| Integration with legacy systems | Anticorruption layer behind the port | Progressive replacement, feature by feature, never in one block. |
| Number of agents | Single orchestrator directing specialists | Parallelizable complexity, never for sequential reasoning. |
| Model abstraction | Single port, three tiers, direct SDK | Never a heavy chaining framework by default. |
| State | Stateless agent, immutable journal plus derived working view | Multi-instance: externalize the in-memory structures. |
| Crossing the process boundary | As late as possible, on an objective trigger | Then accept eventual consistency, compensation, and explicit causal order. |
| Contract evolution | Versioned, additive, read with a tolerant reader | Breaking change: expand then contract, under consumer-driven verification. |
| Memory and forgetting | Value score, invalidation (not deletion), consolidation with pointers to the source facts | Physical deletion reserved for invalidated derivatives under retention. |
| Evaluation | Tests, plus a continuous, guarded evaluation loop | Bounded self-tuning only, guarded, under human override. |
| Multi-agent budget and discovery | Central aggregated counter, in-memory registry | Block allocation and shared capability cards as soon as you leave the process. |
| Model unavailable | Multi-provider failover behind the port | Available from real go-live onward. |
| Changing the model (new or updated) | Validate in shadow deployment, then in stages | Never in a single move; rollback at the slightest divergence. |
| Waiting for a human approval | Suspend and release (durable state), rehydrate on decision | Never block the process; low-urgency requests batched in a queue. |
| Non-critical service | Fail-open, signaled degraded mode | Sensitive action: explicitly fail-closed instead. |
| Delegation autonomy | Bounded: templates, budgets, approvals | Widen only if the outcome actually improves. |
| Untrusted inputs | Retrieved content untrusted, least privilege, approval on the action | High privilege: dedicated patterns (frozen plan, quarantine of the untrusted). |
| Agent identity | Its own principal, distinct from the user served; explicit delegation, bounded in time and scope | Never borrowing the user's full rights; an agent outside the registry = a security anomaly. |
| Runtime secrets | Placeholder on the agent side, real key attached at the network boundary, allowed destinations | Never a key in the model's context or in the execution environment. |
| Shared building block (connectors, skills, cross-application memory, delivery) | Consumed via a port; adapter = discovery client via an index (section 15) | The index stays an index; delivery delivers; the orchestrator decides. |