sunagent

SunAgent is an open-source project designed to demystify modern AI Agent architectures by implementing a modular, provider-independent runtime from first principles. Rather than treating agents as black-box applications, the project focuses on the underlying mechanisms that enable reliable, long-running autonomous workflows, including the Agent Loop, Tool Calling, Context Management, Memory, Planning, and Execution Runtime. The repository is structured to facilitate learning and experimentation. The `src` directory contains the core modular implementation, where each component is designed as an independent and reusable module. The `docs` folder provides design documents and technical explanations of the engineering trade-offs involved. For practical application, the `harnesses` directory offers declarative YAML configuration files to define agent setups without code changes, supporting inheritance for easy iteration on variants. The `evaluation` directory contains benchmark task definitions and result records for comparing agent configurations over time. Key features include a provider-independent event stream called RunTrace, which records lifecycle, LLM, and tool events for observability and debugging. The project supports OpenAI-compatible Chat Completions APIs, allowing integration with various model providers. A learning roadmap outlines future experiments in areas such as streaming output, multi-agent collaboration, and external tool protocols like MCP. SunAgent is intended for engineers, developers, and researchers interested in understanding, testing, and building trustworthy agent systems.