Architectural Design Decisions in AI Agent Harnesses

TL;DR

This study analyzes 70 AI agent systems to identify common architectural decisions, patterns, and co-occurrences, providing insights and guidance for designing and selecting agent-system frameworks.

Contribution

It introduces a transparent methodology for analyzing heterogeneous agent systems and uncovers recurring design dimensions, patterns, and co-occurrence structures.

Findings

Five recurring design dimensions identified: subagent architecture, context management, tool systems, safety mechanisms, and orchestration.

Corpus favors file-persistent, hybrid, and hierarchical context strategies; registry-oriented tools dominate.

Deep coordination correlates with explicit context, structured governance, and formalized tool registration.

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.