文档说明

文件	说明
`koaks`	Koaks Runtime 代码库。
`KoaksRuntime_详细设计文档.md`	当前维护的详细设计文档，系统说明 Koaks Agent Runtime 的需求追踪、总体架构、核心抽象、调度、资源管理、上下文与记忆、通信、容错、安全、观测、部署和测试验收设计。
`KoaksRuntime_技术报告.md`	当前维护的技术报告，重点记录源码与工程基线、赛题符合度、功能验证、测试和压力测试结果、上下文共享实验、性能分析、风险及后续落地路线。
`操作系统开源创新大赛作品原创承诺书.docx`	参赛作品原创性及相关责任的正式承诺文件。
`操作系统开源创新大赛项目说明书.docx`	用于赛事申报和评审的项目说明书，集中介绍项目背景、目标、方案、创新点、实现情况及成果。
`操作系统开源创新大赛PPT.pptx`	项目汇报与答辩使用的演示文稿。
演示视频	发布于哔哩哔哩的项目功能与运行效果演示视频。

作品简介

Koaks Runtime 是一个基于 Kotlin Multiplatform 与 Kotlin Coroutines 构建的多智能体用户态执行时，旨在将 Agent 从应用层对象提升为具有身份、生命周期、资源配额、通信端点和父子关系的受管执行实体。系统通过统一的 AgentRuntime 控制面提供并发上限、优先级与 FIFO 调度、动态子任务和任务图编排，并以等待让槽机制避免父子 Agent 在有限并发资源下发生死锁。

项目围绕多 Agent 场景实现了上下文引用共享、线程记忆与原子回合、进程内 IPC、资源注册与配额、故障隔离、监督重试、熔断、运行句柄控制和全局可观测性。同时提供声明式 Agent DSL、类型安全工具、MCP、Skills、结构化输出及多模型 Provider，可在 JVM、JS 和 macOS 等目标平台使用，并优先以 JVM 形态部署到 openEuler、openKylin 等 Linux 环境。

运行说明

首次运行会自动下载Gradle，请保持全球网络连接通畅或配置国内镜像源

1. 获取代码并准备环境

运行 Koaks 需要 JDK 21 或更高版本。可以直接克隆 Koaks 代码库：

git clone https://www.gitlink.org.cn/atri404/koaks.git
cd koaks
java -version

在自己的 Gradle Kotlin 项目中使用 Koaks 时，引入 Runtime 核心模块和所需的模型 Provider：

# 暂时还未发布，请使用源码运行
dependencies {
    implementation("org.koaks:koaks-core:0.0.1-snapshot1")
    implementation("org.koaks:koaks-model-qwen:0.0.1-snapshot1")
}

2. 使用 AgentRuntime 运行一个 Agent

**以下的代码仅作为单个功能演示，详细的使用教程请参照koaks仓库中的README **

下面的示例创建一个使用通义千问模型的 Agent，再交由显式创建的 AgentRuntime 统一调度和运行：

import kotlinx.coroutines.runBlocking
import org.koaks.framework.loop.agent
import org.koaks.framework.loop.use
import org.koaks.provider.qwen.qwen
import org.koaks.runtime.AgentRuntime

fun main() = runBlocking {
    val apiKey = System.getenv("QWEN_API_KEY")
        ?: error("请先设置 QWEN_API_KEY 环境变量")

    val myAgent = agent {
        id = "assistant"
        name = "assistant"
        instructions = "你是一个简洁、可靠的中文助手。"
        model {
            qwen(
                baseUrl = "你的模型服务地址",
                apiKey = apiKey,
                modelName = "qwen3.7-plus",
            )
        }
        terminateAfter(maxSteps = 1024)
    }

    myAgent.use { managedAgent ->
        AgentRuntime {
            maxConcurrency = 4
        }.use { runtime ->
            val result = runtime.run(
                agent = managedAgent,
                input = "请用三句话介绍 Koaks Runtime。",
            )
            println(result.text)
        }
    }
}

其中，Agent 是可复用的执行定义，AgentRuntime 负责管理运行实例的生命周期、并发调度、资源配额、上下文、通信和故障边界。需要执行多个 Agent 时，可以继续使用 runtime.spawn() 创建后台运行实例，并通过返回的 Handle 等待、暂停、恢复或取消任务。

3. 运行内置功能演示

Koaks 仓库提供了无需 API Key 的 Runtime Showcase，可直接验证调度、上下文、IPC、任务图、资源配额、故障隔离和可观测性：

./gradlew :examples:runRuntimeShowcase

赛题题目：面向多智能体的操作系统级执行时（Agent Runtime）（高校赛题）

赛题说明：

当前基于大语言模型（LLM）的智能体（Agent）系统正从“单Agent”快速演进到“多Agent协同”，广泛应用于自动编程、复杂任务规划、软件工程等场景。然而，现有多Agent系统大多停留在应用层框架（如Workflow/Graph调度），缺乏操作系统级的统一执行时（Runtime）支持，导致如下关键问题： 1）多Agent执行缺乏统一调度，易出现资源竞争与执行低效 2）上下文（Context/KV Cache）频繁冗余拷贝，系统开销大 3）模型调用、工具调用与系统资源之间缺乏统一抽象 4）复杂任务执行过程中缺乏“系统级可观测性与控制能力” 本赛题要求参赛者设计并实现一个面向多Agent系统的操作系统级执行时（Agent Runtime），将Agent提升为“操作系统一等公民”，实现对Agent任务的统一建模、调度与资源管理，并探索“AI Native OS”的关键机制。

赛题要求：

本赛题要求参赛队伍从操作系统视角出发，围绕多智能体系统的执行与管理问题，设计并实现一个具备统一调度、资源管理与上下文优化能力的Agent运行时系统。参赛作品不仅需要具备完整功能，还应在关键机制上体现创新性，并通过实际应用场景验证系统有效性与性能优势。

基于 openEuler、openKylin、OpenHarmony 等至少一个国内主流开源操作系统开发，鼓励在更多Linux发行版上编译、运行和测试。
实现面向多Agent任务的调度机制，支持任务依赖、动态生成任务及资源感知调度策略；
设计统一的Agent执行抽象模型，明确其生命周期管理、状态转换及与操作系统资源之间的关系；
设计Agent执行容错机制，通过隔离单体Agent故障，避免单点执行异常导致的多智能体系统性级联故障；
设计并实现高效的上下文管理机制，包括上下文复用、压缩及隔离策略，降低多Agent执行开销；
构建复杂多Agent应用场景，验证系统在真实任务中的可用性与稳定性；
实现Agent之间的高效通信机制。
评分细则（明确评审角度、标准和分值范围）：
系统设计与机制创新（30%）：是否提出具有前瞻性的Agent系统抽象及关键机制创新；
功能完整性与实现深度（25%）：核心模块是否完整实现，关键机制是否深入落地；
性能优化效果（20%）：在多Agent复杂任务中是否体现明显性能提升；
工程实现质量（15%）：系统架构、代码质量及可扩展性；
实验与分析质量（10%）：实验设计是否严谨，分析是否深入全面。
赛题联系人：
吴老师 wuyanxia@hrbeu.edu.cn
参考资料：
AIOS: LLM Agent Operating System
LangGraph / AutoGen / CrewAI 等多Agent框架
Linux调度器（CFS）与容器资源管理机制