<div align="center">
<img src="https://raw.githubusercontent.com/routecraftjs/routecraft/HEAD/routecraft.svg" alt="Routecraft" width="120" />
<p><strong>에이전트를 위한 도구. 또는 에이전트 자체의 뼈대(harness)입니다.</strong></p>
<a href="https://github.com/routecraftjs/routecraft/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/routecraftjs/routecraft/actions/workflows/ci.yml/badge.svg"></a>
<img alt="Bun" src="https://img.shields.io/badge/Bun-1.1%2B-fbf0df?logo=bun">
<img alt="Node.js" src="https://img.shields.io/badge/Node.js-22%2B-3c873a?logo=node.js">
<img alt="TypeScript" src="https://img.shields.io/badge/TypeScript-5.9%2B-3178c6?logo=typescript">
<a href="./LICENSE"><img alt="License" src="https://img.shields.io/badge/License-Apache%202.0-blue"></a>
<a href="https://github.com/routecraftjs/routecraft/issues"><img alt="Issues" src="https://img.shields.io/github/issues/routecraftjs/routecraft"></a>
<a href="https://github.com/routecraftjs/routecraft/pulls"><img alt="PRs" src="https://img.shields.io/badge/PRs-welcome-brightgreen"></a>
</div>
개요 (About)
Routecraft는 팀이 함께 구축하는 오픈 소스 AI 자동화 플랫폼입니다. 'Capability'란 라우트(route)와 같습니다. 즉, 특정 출처(source)에서 시작하여 여러 연산(operations)을 거쳐 최종 목적지(destination)로 이어지는 타입이 지정된 파이프라인입니다. 동일한 라우트는 어떤 에이전트나 편집기(editor)를 위한 MCP 도구가 될 수 있으며, 자신이 실행하는 에이전트를 위한 도구가 되거나, HTTP 엔드포인트가 될 수도 있고, 스케줄링된 작업(scheduled job)이 될 수도 있습니다. 이는 오직 그 라우트의 출처에만 의존합니다. 노트북에서 이를 증명한 후, 팀 뼈대(team harness)로 승격시키면 모든 팀원이 자신들의 계정 자격 증명(service credentials)을 사용하여 이용할 수 있게 됩니다. 에이전트 역시 일종의 라우트이며, 모델 호출(model call) 주변에 적용되는 가드레일(guardrails)은 다른 어떤 단계에도 동일하게 적용됩니다. 라우트로 작성되지 않은 것은 아무것도 도달할 수 없습니다.
craft-harness는 Routecraft 기능들로 구축된 완전한 에이전트입니다: 채팅, 샌드박스 셸, 웹 가져오기 및 검색, 작업 공간(workspace), 메모리, 스케줄러, 인간 승인(human approvals), 그리고 편집기 기능을 포함합니다. 이 모든 것은 capabilities/에서 볼 수 있고 변경할 수 있는 일반적인 라우트입니다.
bunx create-routecraft my-agent --example https://github.com/routecraftjs/craft-harness
dcd my-agent
bun run setup
...
다른 터미널에서:
bun run exec chat --session=demo --message="what can you do?"
인스턴스는 격리되어 있고, 설정 파일이 자격 증명(credential)을 담고 있으며, 기록은 --session 이름의 파일입니다. 동일한 대화는 http://localhost:8081/mcp에서 MCP를 통해, 그리고 에이전트 클라이언트 프로토콜(Agent Client Protocol)을 통해 편집기에서 접근할 수 있습니다.
기능(capability)의 모습
import { craft, mail } from '@routecraft/routecraft'
import { mcp } from '@routecraft/ai'
import { z } from 'zod'
...
소스 코드가 문을 결정합니다. .from(mcp())는 이를 MCP 도구로 만듭니다. .from(direct())는 모든 로컬 에이전트가 호출하고 craft exec이 실행할 수 있는 기능으로 만들고, .from(http())는 엔드포인트로 만듭니다. 그 사이의 단계들은 변하지 않습니다. cron() 스케줄은 본문(body)을 가져오지 않으므로, 이 입력을 구성하여 direct()를 통해 기능을 호출하는 자체 작은 라우트를 얻게 됩니다.
에이전트도 하나의 라우트입니다
import { craft, direct } from '@routecraft/routecraft'
import { agent, tools } from '@routecraft/ai'
import { z } from 'zod'
...
도구(Tools)는 블랙리스트가 아닌 기능들의 허용 목록(allowlist)입니다. 에이전트는 또한 agents/ 아래의 마크다운 파일일 수도 있으며, 이 파일에는 모델과 도구에 대한 프론트매터(frontmatter)가 포함되어 있고, 이는 craft start가 프로젝트 내 다른 모든 것과 함께 발견합니다. 에이전트가 라우트의 한 단계이기 때문에, .authorize(), .throttle(), .retry(), .timeout() 및 .circuitBreaker()는 모델 호출에 대해 다른 어떤 단계와 마찬가지로 적용됩니다.
얻게 되는 기능
-
재시작에도 살아남는 작업. .defer()는 스토어(store) 내의 교환(exchange)을 지연시키고, .resume()은 토큰, 시간 또는 날짜가 지난 후 어떤 전송 수단(transport)에서도 이를 재활성화합니다. Durable agents도 대화 중간에 동일한 방식으로 지연시킬 수 있습니다.
-
세션 및 백그라운드 도구를 갖춘 에이전트. 대화는 개인이 소유하는 기록이며, 도구(tool)는 장기적인 작업을 라우트(route)에 맡기고 완료될 때 돌아올 수 있습니다. Agent adapter.
-
편집기에서 에이전트와 대화하기. craft acp와 acp 설정 키는 Agent Client Protocol을 제공합니다. 편집기에서 대화하기.
-
MCP 양방향 지원. mcp() 및 mcp 플러그인을 사용하여 라우트를 도구로 노출하고, 에이전트의 도구 목록에서 MCP(server:tool)을 호출하여 다른 서버의 도구를 호출할 수 있습니다. 에이전트에 노출하기, MCP 호출하기.
-
격리된 호스트 실행. shell()은 각 명령어마다 임시 Docker 컨테이너를 포함하여 격리 계층(isolation tier)에서 명령을 실행하며, 기본적으로 외부 통신(egress)이 차단됩니다.
-
관리 API 및 이를 구동하는 CLI. ops 플러그인은 건강 상태(health), 준비 상태(readiness), 라우트 목록, 그리고 스코프 제한 계층(scope-gated tiers) 뒤의 디스패치 기능을 제공하며, craft exec과 craft ops가 그 클라이언트입니다. CLI 참고.
-
설계 단계부터 보안성 확보. JWT, JWKS 및 API 키 검증기(validators), 라우트 진입점에서의 .authorize(), 모든 홉(hop)을 거치는 주체(principals). 보안 기능
-
확장하는 한 가지 방법. 플러그인(Plugin)은 id와 라이프사이클 훅(lifecycle hooks)을 가진 디스크립터이며, 타입이 지정된 포트(typed ports)를 제공하고 요구할 수 있고, 고정된 체인(fixed chain)의 슬롯에 훅을 추가하며, 빌더 단계(builder steps)와 교환소(exchange)의 페싯(facet)을 선언하고, 체인 위치를 채우는 것을 대체할 수 있습니다. 프레임워크 자체 기능도 같은 방식으로 구축된 플러그인입니다. Plugins.
기존 프로젝트에 Routecraft 추가하기
bunx create-routecraft my-app
cd my-app
bun add @routecraft/ai nodemailer
위 기능은 @routecraft/ai의 mcp()를 사용하고 mail()을 통해 전송하며, 이는 nodemailer가 필요합니다. 어댑터는 패키지 이름이 누락되면 실행 시 이를 알립니다.
Claude Desktop에 기능을 노출하려면 ~/Library/Application Support/Claude/claude_desktop_config.json에 추가하세요:
{
"mcpServers": {
"my-tools": {
...
이제 Claude에게 말해보세요: "어제 회의에 대한 감사 인사를 [email protected]으로 이메일 보내줘". Claude는 도구를 발견하고 검증된 입력값과 함께 이를 호출합니다.
craft CLI는 Bun (>=1.1.0)에서 실행됩니다. Node 사용자는 @routecraft/routecraft를 프로그래밍 방식으로 임베드할 수 있습니다. Programmatic Invocation 가이드를 참조하세요.
📚 시작하기 | 프로젝트 구조 | 예제 | API 레퍼런스
Monorepo 구조
packages/routecraft – 핵심 라이브러리 (builder, DSL, context, adapters, consumers, ops 플러그인)packages/ai – AI 통합: LLM 제공업체, 에이전트, 임베딩(embeddings), MCP 서버/클라이언트, ACPpackages/cli – 기능 실행 및 컨텍스트 시작을 위한 craft CLI (Bun >= 1.1.0)packages/create-routecraft – 프로젝트 스캐폴더 (bunx create-routecraft)packages/eslint-plugin-routecraft – 기능 작성용 ESLint 규칙packages/prettier-plugin-routecraft – 간결한 DSL 포맷팅을 위한 Prettier 플러그인packages/os – 시스템 네이티브 어댑터: shell()을 통한 격리된 서브프로세스 실행, agentBrowser()를 통한 브라우저 자동화packages/testing – 테스트 유틸리티 (testContext, spy logger, mockAdapter, fixtures)skills/ – Routecraft 작성용 에이전트 스킬 (Claude Code, Cursor, Codex, Windsurf, Cline, Continue, Copilot 등; bunx skills add routecraftjs/routecraft). skills/README.md 참조apps/routecraft.dev – 문서 사이트 (문서(docs), 예제, 가이드)examples/ – 실행 가능한 예제 기능들
예제 (Examples)
examples/src/에서 실행 가능한 예제를 확인하세요: hello-world.ts, mcp-greet.ts, agent.ts, find-product.ts, mail-noreply-notify.ts, jev-judge.ts, programmatic-invocation.ts, split.ts. 각 파일은 다른 기능 조합을 시연합니다.
하나를 사용해 보세요:
bun install
bun run build
bunx craft run ./examples/dist/mcp-greet.js
엔드투엔드(end-to-end) 워크스루는 문서 사이트를 참조하세요.
기여 (Contributing)
기여 환영합니다! 변경 사항을 제안하고, 어댑터를 추가하며, 기능을 작성하는 방법에 대한 지침은 https://routecraft.dev/docs/community/contribution-guide의 기여 가이드를 읽어주세요.
라이선스 (License)
Apache 2.0 License에 따라 라이선스가 부여됩니다.