<p align="center">
<img src="https://raw.githubusercontent.com/Kohaku-Lab/KohakuTerrarium/HEAD/images/banner.png" alt="KohakuTerrarium" width="800">
</p>
<p align="center">
<strong>에이전트를 구축하는 장치로, 새로운 에이전트가 필요할 때마다 이 장치를 다시 구축할 필요가 없습니다.</strong>
</p>
<p align="center">
<img src="https://img.shields.io/badge/python-3.10%2B-blue" alt="Python 3.10+">
<img src="https://img.shields.io/badge/license-KohakuTerrarium--1.0-green" alt="License">
<img src="https://img.shields.io/badge/version-2.0.0-orange" alt="Version">
</p>
<p align="center">
<strong>영어</strong> · <a href="README.zh.md">번체 중국어</a> · <a href="README.zh-CN.md">간체 중국어</a>
</p>
<p align="center">
<a href="https://terrarium.kohaku-lab.org"><strong>문서화</strong></a>
</p>
실행 예시 (60초 만에)
pip install kohakuterrarium
kt login codex
kt install @kt-biome
...
이것은 파일 도구, 셸 접근, 웹 검색, 서브 에이전트, 재개 가능한 세션을 갖춘 인터랙티브 셸입니다. Ctrl+D를 누르면 종료되며, kt resume --last는 중단했던 지점부터 정확하게 다시 시작합니다.
동일한 에이전트를 라이브러리로 사용하면 네 줄이면 충분합니다:
from kohakuterrarium import Agent
agent = await Agent.build("@kt-biome/creatures/swe")
...
더 많은 안내가 필요하신가요? Getting Started를 참고하세요. 직접 구축하고 싶으신가요? First Creature를 참고하세요. 임베드하고 싶으신가요? Programmatic Usage를 참고하세요.
이 제품이 필요한가요?
다음과 같은 경우 KohakuTerrarium이 필요할 수 있습니다: 새로운 에이전트 형태가 필요하지만 기반(substrate)을 다시 구축하고 싶지 않을 때; 커스터마이징 가능한 강력한 기본 에이전트를 원할 때; 자체 Python 환경에서 에이전트를 구동해야 할 때 (배치 작업, 봇, 파이프라인); 요구 사항이 아직 진화하는 단계에 있을 때.
기존 에이전트 제품으로는 부족할 수 있는 경우가 있을 것입니다. 예를 들어, 기존의 에이전트 제품(Claude Code, Codex 등)이 이미 안정적인 요구 사항을 충족시키거나, 사용자의 정신적 모델(mental model)이 컨트롤러/도구/트리거/서브 에이전트/채널과 매핑되지 않거나, 또는 작업당 50ms 미만의 지연 시간(latency)이 필요한 경우입니다. boundaries에서 더 솔직한 정보를 확인하세요.
KohakuTerrarium이란 무엇인가
KohakuTerrarium은 에이전트를 만드는 프레임워크이지, 또 다른 에이전트 그 자체는 아닙니다.
지난 2년 동안 Claude Code, Codex, Gemini CLI, OpenCode, OpenClaw, Hermes Agent 등 눈에 띄게 많은 에이전트 제품들이 등장했습니다. 이들은 진정으로 다른 제품들이며, 모두 동일한 기반 구조(substrate)를 처음부터 재구현합니다: 컨트롤러 루프, 도구 디스패치(tool dispatch), 트리거, 서브 에이전트, 세션, 영속성(persistence), 다중 에이전트 연결 방식 등이 그것입니다. 새로운 에이전트 형태가 나올 때마다 배관 공사(plumbing) 전체를 처음부터 다시 구현해야 하는 비용이 발생합니다.
KohakuTerrarium은 이 기반 구조를 한곳에 모아 놓았기 때문에, 다음 에이전트 형태는 새 리포지토리(repo)가 아니라 설정 파일과 몇 가지 커스텀 모듈만으로도 구축할 수 있습니다.
핵심 추상화 개념은 **크리처(creature)**입니다. 크리처는 자체 컨트롤러, 도구, 서브 에이전트, 트리거, 메모리 및 I/O를 가진 독립적인 에이전트입니다. 크리처는 테라리움(Terrarium) 엔진에 의해 호스팅됩니다. 테라리움은 채널, 생명 주기(lifecycle), 출력 연결 방식(output wiring), 핫플러그(hot-plug) 기능을 소유하며, 그래프 변경에 따라 발생하는 토폴로지 및 세션 기록 관리까지 담당하는 그래프 런타임입니다. 그 위에는 스튜디오(Studio) 계층이 존재하여 카탈로그, ID, 활성 세션, 영속성, 그리고 웹/데스크톱/API 관리 인터페이스를 제공합니다. 선택적으로, 레이버라토리(Laboratory) 전송 계층은 호스트와 엔진을 여러 머신에 분산시킬 수 있습니다. 스튜디오와 테라리움은 변경되지 않으며, 그 사이에 WebSocket 연결 지점만 삽입됩니다.
모든 것이 Python으로 되어 있습니다. 에이전트는 await할 수 있는 객체이며, 타입 지정된 결과를 반환합니다. 이들은 사용자의 도구(tools), 봇(bots), 배치 작업(batch jobs) 내부에 임베드될 뿐만 아니라 다른 에이전트 내부에도 포함될 수 있습니다.
오늘 바로 시도해 볼 수 있는 기본 크리처 목록은 프레임워크를 기반으로 구축된 유용한 에이전트 및 플러그인의 공식 팩인 kt-biome을 참고하세요.
적용 분야
| Product | Framework | Utility / Wrapper |
|---|
| LLM App | ChatGPT, Claude.ai | LangChain, LangGraph, Dify | DSPy |
| ... | | | |
| 대부분의 툴링은 에이전트 계층(agent layer) 아래에 위치하거나, 에이전트가 무엇인지에 대한 깊은 이해 없이 바로 다중 에이전트 오케스트레이션으로 점프합니다. KohakuTerrarium은 에이전트 자체에서 시작합니다. | | | |
크리처는 다음 요소들로 구성됩니다:
- 컨트롤러(Controller): 추론 루프(reasoning loop)
- 입력(Input): 이벤트가 에이전트에 들어오는 방식
- 출력(Output): 결과가 에이전트를 나가는 방식
- 도구(Tools): 수행할 수 있는 행동
- 트리거(Triggers): 활성화시키는 것
- 서브 에이전트(Sub-agents): 전문화된 작업을 위한 내부 위임
테라리움은 채널, 라이프사이클 관리(lifecycle management), 관측 가능성(observability)을 통해 여러 크리처를 수평적으로 구성합니다.
주요 기능 (Key features)
-
에이전트 수준의 추상화(Agent-level abstraction). 6개 모듈로 이루어진 크리처 모델은 일급 개념입니다. 새로운 에이전트 형태는 “런타임을 재구축하는 것”이 아니라 “설정 파일과 몇 가지 사용자 정의 모듈을 작성하는 것”입니다.
-
실제 파이썬 API(A real Python API). Agent.build, 타임아웃이 실제로 취소되는 타입 지정된 TurnResult 턴, 스트리밍되는 타입 지정 이벤트, 모든 함수를 에이전트 도구로 변환하는 @kt.tool, 직접적인 LLM 인스턴스 주입, 사일런트 폴백 대신 기본적으로 엄격한 오류 처리 등을 지원합니다.
-
내장 세션 지속성 및 재개(Built-in session persistence and resume). 엔진은 세션 파일(session= / Terrarium(session_dir=))을 생성하고 소유하며, kt resume 또는 Terrarium.resume으로 몇 시간 후에 재개할 수 있습니다. SessionReader는 완료된 모든 실행 기록을 오프라인에서 재생합니다.
-
검색 가능한 세션 기록(Searchable session history). 모든 이벤트가 인덱싱됩니다. kt search와 search_memory 도구를 사용하여 과거 작업을 검색할 수 있습니다 (사용자 및 에이전트 모두 가능).
-
비차단 컨텍스트 압축(Non-blocking context compaction). 장시간 실행되는 에이전트는 백그라운드에서 컨텍스트가 압축되는 동안 계속 작동합니다.
-
포괄적인 내장 도구 및 서브 에이전트. 파일, 셸, 웹, JSON, 노트북, 검색, 편집, 제한된 탐색 및 검토 기능 외에도 특권 노드(privileged nodes)에서는 group_* 그래프 에디터 도구를 제공합니다.
-
컨텍스트 인식 사이드 대화(Context-aware side conversations). 기본적으로 활성화된 검사 전용 fork 헬퍼와 /btw는 부모 컨텍스트의 격리된 스냅샷을 사용합니다. 메인 작업에 질문이나 그 답변을 주입하지 않고 사이드 질문을 하거나 다시 열고 계속할 수 있습니다. 비활성화하려면 fork_enabled: false를 사용하세요. 가이드.
-
MCP 지원(MCP support). 에이전트별 또는 전역적으로 stdio / 스트리밍 가능한 HTTP MCP 서버를 연결할 수 있습니다. 네 가지 메타 도구는 연결하는 서버의 개수와 관계없이 프롬프트를 간결하게 유지합니다.
-
패키지 시스템 + 마켓플레이스(Package system + marketplace). kt install @name은 TerrariumMarket을 통해 해결되며, kohakuterrarium.packages.ensure("@name")는 불변의 스크립트 측 원시 요소(idempotent script-side primitive)입니다.
-
합성 대수(Composition algebra). 에이전트를 파이프라인으로 연결하기 위한 >>, &, |, *, .iterate 연산자가 있습니다.
-
다중 런타임 표면(Multiple runtime surfaces). CLI, TUI, 웹 대시보드, 네이티브 데스크톱 앱을 즉시 사용할 수 있습니다.
-
선택적 4계층 인증(Optional four-layer auth). 호스트 토큰(Host token), 관리자 비밀번호(admin password), 다중 사용자 계정(multi-user accounts)을 지원합니다. 각 계층별로 선택적으로 활성화할 수 있으며, 기본값은 모든 기능이 비활성화된 상태입니다. 인증(Authentication)을 참조하세요.
빠른 시작 (Quick start)
권장 Python 버전: 3.12 이상입니다. CI는 3.12 이상을 검증하며, 3.10 및 3.11도 여전히 설치하고 실행할 수 있지만(requires-python = ">=3.10") 최선의 노력으로 지원됩니다.
1. KohakuTerrarium 설치
pip install kohakuterrarium
...
2. 기본 크리처 및 플러그인 설치
kt install @kt-biome
kt marketplace search
kt install <git-url>
...
소스, 버전 고정(version pinning), 환경 변수 재정의(env overrides)에 대한 자세한 내용은 docs/en/guides/packages.md를 참조하세요.
3. 모델 제공업체 인증 (Authenticate a model provider)
kt login codex # Codex OAuth (ChatGPT 구독)
kt model default gpt-5.4
또는 kt config key set <provider>를 통해 API 키 제공자 설정
Codex OAuth, OpenRouter/OpenAI, 네이티브 Anthropic, Google Gemini, Kimi Code, GLM Coding Plan 및 모든 OpenAI 호환 API를 지원합니다.
4. 무언가 실행하기 (Run something)
kt run @kt-biome/creatures/swe --mode cli
kt terrarium run @kt-biome/terrariums/swe_team
kt serve start
...
경로 선택하기 (Choose your path)
지금 무언가를 실행하고 싶어요 (I want to run something now)
나만의 크리처를 만들고 싶어요 (I want to build my own creature)
다중 에이전트 구성을 하고 싶어요 (I want multi-agent composition)
Python에 임베드하고 싶어요 (I want to embed it in Python)
무슨 일이 벌어지고 있는지 이해하고 싶어요 (I want to understand what's going on)
배포하고 싶어요 (I want to deploy it)
– Docker 배포: AIO, 호스트 + 워커, 분산 컴포즈 레시피
– systemd 배포: kt service install + 강화된 유닛 (hardened units)
– 리버스 프록시 배포: nginx / Cloudflare 터널 + TLS
– 실험실 (Laboratory): 다중 노드 lab-host / lab-client 모델
프레임워크 자체 개발에 참여하고 싶을 때
– 개발 홈
– 내부 구조 (Internals)
– 테스트
– AGENTS.md: 이 프레임워크에서 작동하거나 이와 관련된 코딩 에이전트에 대한 단일 파일 개요 (brief)
– [src/kohakuterrarium/] 아래의 패키지 README
핵심 정신 모델 (Core mental model)
Creature
List, Create, Delete +------------------+
+-----| Tools System |
+---------+ | +------------------+
...
Creature는 자체 런타임 (runtime), 도구 (tools), 서브 에이전트 (sub-agents), 프롬프트 (prompts) 및 상태(state)를 가진 독립적인 에이전트입니다.
kt run path/to/creature
kt run @package/path/to/creature
런타임 계층 구조 (Runtime hierarchy)
User / API / Desktop
|
v
...
