Architectural Design Decisions in AI Agent Harnesses

Abstract: AI agent systems increasingly rely on reusable non-LLM engineering infrastructure that packages tool mediation, context handling, delegation, safety control, and orchestration. Yet the architectural design decisions in this surrounding infrastructure remain understudied. This paper presents a protocol-guided, source-grounded empirical study of 70 publicly available agent-system projects, addressing three questions: which design-decision dimensions recur across projects, which co-occurrences structure those decisions, and which typical architectural patterns emerge. Methodologically, we contribute a transparent investigation procedure for analyzing heterogeneous agent-system corpora through source-code and technical-material reading. Empirically, we identify five recurring design dimensions (subagent architecture, context management, tool systems, safety mechanisms, and orchestration) and find that the corpus favors file-persistent, hybrid, and hierarchical context strategies; registry-oriented tool systems remain dominant while MCP- and plugin-oriented extensions are emerging; and intermediate isolation is common but high-assurance audit is rare. Cross-project co-occurrence analysis reveals that deeper coordination pairs with more explicit context services, stronger execution environments with more structured governance, and formalized tool-registration boundaries with broader ecosystem ambitions. We synthesize five recurring architectural patterns spanning lightweight tools, balanced CLI frameworks, multi-agent orchestrators, enterprise systems, and scenario-verticalized projects. The result provides an evidence-based account of architectural regularities in agent-system engineering, with grounded guidance for framework designers, selectors, and researchers.

• The paper demonstrates that co-occurrence analysis reveals strong links between subagent complexity and robust context management.
• The paper employs systematic coding of 70 projects to map architectural dimensions such as tool registration and safety protocols.
• The paper highlights that explicit engineering choices in orchestration and isolation are crucial for reliable, scalable AI agent systems.

Architectural Design Decisions in AI Agent Harnesses: An Expert Synthesis

Introduction and Context

This study systematically examines the architectural design space of AI agent harnesses—the crucial non-LLM infrastructure layer enabling persistent, extensible, and governable operation for LLM-based agents. Unlike prior research centering on agent algorithms and reasoning, the paper investigates the explicit engineering decisions underlying 70 publicly available agent-system projects, spanning tooling, orchestration, context retention, and safety control. The methodology involves direct source- and documentation-level inspection, protocolized coding across five key dimensions, and co-occurrence analysis to uncover regularities in architectural choice.

Empirical Design Space: Dimensions and Choices

The study identifies five recurring, source-verifiable architectural dimensions structuring agent harnesses:

1. Subagent Architecture: Ranging from single-agent baselines to orchestrator-worker, recursive, and event-driven decompositions. Hierarchical or orchestrated subagent patterns predominate in systems targeting complex coordination, with explicit depth limits frequently enforced.
2. Context Management: Encompassing context windowing, LLM-based summarization, file persistence, vector/RAG, and layered hybrid/enterprise schemes. Notably, hybrid and hierarchical context strategies dominate, reflecting the token budgeting and persistence burdens of multi-step workflows.
3. Tool System: Frameworks generally rely on explicit registries, decorator-driven extension, protocolized MCP (Model Context Protocol) interfaces, DSL/declarative methods, or plugin ecosystems. Registry architectures are most common, though MCP-first and plugin ecosystems are gaining traction, especially in developer-oriented platforms.
4. Safety Mechanisms: Spanning approval workflows, isolation levels (none, process, container, WASM), and audit capabilities. Intermediate process or container isolation is widespread, yet high-assurance auditability is rare; over 40% of projects lack explicit security event trails.
5. Orchestration: The control logic for task execution, from imperative loops to event-driven and declarative/DSL workflows. ReAct-style interleaving remains prevalent, but planning/execute separation and event-driven orchestration are substantial minorities.

These dimensions are not orthogonal: decisions in one (e.g., subagent complexity) exert strong pressure on others (context persistence, safety controls).

Co-occurrence and Structural Regularities

A salient contribution is the cross-dimensional co-occurrence analysis. Key findings include:

• Subagent Complexity ↔ Context Sophistication: Projects with deep orchestration (multi-agent, recursive) almost universally implement persistent, hierarchical, or summarization-based context management (support 0.73, lift 1.8). Decentralized workflows intrinsically require robust state transfer and durable memory.
• Execution Isolation ↔ Policy-based Safety: Containerization or WASM isolation is nearly always paired with explicit approval engines and structured auditing (support 0.89, lift 3.4), while ad hoc or absent isolation aligns with minimal governance.
• Tool Registration ↔ Ecosystem Ambition: Protocolized (MCP) or plugin-based tool registration disproportionately appears in projects targeting developer platforms or broad CLI exposure (support 0.62, lift 2.8).

Negative co-occurrence findings are equally important: programming language, use case, or surface-level capability growth do not reliably predict architectural complexity or safety posture. Frameworks in Python or TypeScript span the full design space; vertical use case specialization does not necessitate deep architecture; increased tool power does not guarantee governance maturity.

Emergent Architectural Patterns

The cross-project synthesis yields five recurrent, analytically distinct architectural patterns:

1. Lightweight Tool: Single-agent, session-bound or file persistence, minimal/composed tool registry, little/no isolation. Best for narrow or ephemeral workflows.
2. Balanced CLI Framework: Basic subagent delegation, file/JSONL persistence, MCP registry or extension support, process-level sandboxing, category-based tool routing. Suited for developer tools and moderate-complexity workflows.
3. Multi-Agent Orchestrator: Explicit orchestrator-worker/recursive subagent infrastructure, hierarchical/hybrid memory, structured tool delegation, container/WASM sandboxing, policy-based safety, event-driven control. Supports sophisticated automation and collaborative frameworks.
4. Enterprise Full-Featured: Deep subagent hierarchies, enterprise memory (vector DB, hierarchical), plugin architectures, full MCP, layered container isolation, audit, approval. Targeted at production and compliance-sensitive deployments.
5. Scenario/Research Vertical: Often optimized for specific experiment or domain; highly variable architecture, infrastructure minimized outside the focal scenario.

Each pattern encapsulates a tight bundle of design decisions, enforcing tradeoffs between extensibility, governance, operational overhead, and adaptability.

Theoretical and Practical Implications

These findings have both immediate engineering and research-theoretic ramifications:

• For Framework Designers: Early definition of target complexity and operating envelope is essential. Incremental feature additions outside a coherent architectural bundle generate maintenance and governance friction. For instance, introducing orchestrator-worker subagent structures without persistent, token-budgeted memory typically leads to operational failure modes.
• For Framework Selectors: Selection criteria should center on architectural fit (coordination, persistence, safety) rather than generic claims of capability. High extensibility or tool integration without the corresponding safety/gov stack is empirically unsustainable in open deployment.
• For AI-Oriented Software Architecture Research: The existence of strong co-occurrence bundles, together with analytically relevant non-co-occurrences, demonstrates that agent harnesses have matured into a structured architectural domain. This motivates more formal benchmarking, standardized codebooks, and longitudinal studies of architectural evolution.

While architectural pluralism persists (i.e., no single best pattern has emerged), the observed regularities bode well for cumulative knowledge building about AI agent engineering. Design space analysis is thus a necessary step prior to rigorous cross-framework comparison and systematic progress.

Limitations and Future Directions

The study’s limitations are transparent: a public-project bias, absence of closed/commercial codebases, and a time-fixed corpus. Coding nonuniformity is mitigated through SOP-aided vertical/horizontal module analysis and human audit, but interpretive discretion remains. The temporal volatility of this domain further cautions against generalizing any single configuration as optimal.

Future research should pursue:

• Longitudinal tracking of architectural transitions;
• Outcome-correlated measurement, e.g., maintainability or robustness versus design bundle;
• Architectural benchmarking frameworks for standardized evaluation;
• Expanded co-occurrence analysis utilizing larger or more diverse corpora.

Conclusion

This paper establishes a rigorous empirical foundation for understanding the architectural design decisions shaping agent harnesses. Subagent structure, context/persistence strategy, tool registry, safety/isolation, and orchestration style have clear, recurrent forms and interrelations. The work demonstrates that architectural choices, not just algorithmic capability, define agent system reliability, extensibility, and governability. By articulating the regularities—and meaningful exceptions—across a comprehensive corpus, it sets a new baseline for both future AI research and practical agent-system engineering.