statewright/statewright
State machine guardrails for AI agents
Statewright란 무엇인가?
Statewright는 명시적이고 강제 가능한 단계를 가진 에이전트 워크플로우를 실행할 수 있는 오픈소스 프레임워크입니다. 작업의 각 단계(예: 계획, 구현, 테스트)에 대한 상태 머신을 정의하고 각 단계에서 허용되는 LLM 도구를 제어합니다. 지원되는 AI 클라이언트(Claude Code, Codex, Cursor, OpenCode, Pi, OMX 또는 사용자 정의 MCP 호스트)에 연결하면 통합이 도구 호출을 가로채고 허용되지 않은 작업을 차단하며 다른 단계를 다른 모델로 라우팅할 수 있습니다.
왜 중요한가
일반적인 AI 지원 코딩 에이전트는 작업 전체에서 동일한 도구를 계속 사용할 수 있으므로 검토 전에 코드를 편집하거나 테스트가 완료되기 전에 배포하기 쉽습니다. Statewright는 이러한 경계를 명시적으로 만들고 호스트가 지원하는 경우 강제합니다. 이를 통해 다음을 얻을 수 있습니다:
- 안전성 – 파일 편집이나 파괴적인 셸 명령과 같은 도구는 지정한 상태에서만 허용됩니다.
- 세분화된 모델 라우팅 – 저렴한 단계에는 저렴한 모델을 실행하고 무거운 단계에는 더 큰 모델로 전환할 수 있습니다.
- 승인 게이트 – 워크플로우는 진행하기 전에 인간 검토를 위해 일시 중지할 수 있습니다.
- 반복 가능하고 감사 가능한 실행 – 모든 전환, 가드 및 도구 사용이 기록됩니다.
핵심 구성 요소(README에 설명됨)
| 구성 요소 | 언어 / 역할 | 주요 책임 |
|---|---|---|
엔진 (crates/engine) |
Rust | 순수 상태 머신 평가기 – LLM 없음, 결정론적, 가드, 전환 및 도구 허용 목록 제공. |
에이전트 바이너리 (crates/cli, sw-agent) |
Rust | 제한된 루프에서 LLM을 실행하고 JSONL 이벤트를 스트리밍하며 상태별 모델 라우팅을 존중하고 요청 시 단일 상태를 실행할 수 있습니다. |
실행기 / 플러그인 계층 (plugins/*, crates/mcp-gateway) |
Rust + 호스트 어댑터 | 워크플로우 세션, 자격 증명, 원격 측정을 보유하고 지원되는 각 클라이언트(Claude, Codex, Pi 등)에 대한 네이티브 도구 후크를 변환합니다. |
TUI (crates/tui, statewright) |
Rust (ratatui) | sw-agent를 실행하는 터미널 UI로 실시간 JSONL 이벤트를 표시하고 워크플로우와 상호 작용할 수 있습니다. |
워크플로우의 모습
워크플로우는 상태, 허용된 도구, 선택적 상태별 모델, 가드 및 전환을 나열하는 JSON 정의입니다. 예(단순화):
{
"id": "bugfix",
"initial": "planning",
"meta": {"default_model": "claude-sonnet-4"},
"states": {
"planning": {"allowed_tools": ["Read","Grep"], "model": "claude-haiku"},
"implementing": {"allowed_tools": ["Read","Edit","Write"]},
"testing": {"allowed_tools": ["Read","Bash"], "allowed_commands": ["pytest"]},
"completed": {"type": "final"}
}
}
엔진은 allowed_tools 목록을 강제하고 허용되지 않은 Bash 명령을 차단하며 전환 시 인간 승인을 요구할 수 있습니다.
지원되는 AI 호스트
Statewright는 다음을 위한 네이티브 플러그인을 제공합니다:
- Claude Code (0.3.4 후보) – 네이티브 OAuth, 사전 권한 검사.
- Codex – 관리형 App-Server 어댑터.
- Pi, OpenCode, Cursor, OMX – 각각 동일한 안전장치를 강제하는 얇은 브리지가 있습니다. 사용자 정의 MCP 호스트도 게이트웨이를 통해 연결할 수 있습니다.
연구 스냅샷
5개 작업 SWE-bench 하위 집합에 대한 소규모 실험에서 Statewright 제약 조건 하에 더 큰 모델(13.8GB gpt-oss:20b 및 19.9GB gemma4:31b)이 모든 작업을 해결한 반면 더 작은 모델은 실패했습니다. 저자들은 이것이 최소 모델 크기를 증명하지 않으며 단지 안전장치가 에이전트가 궤도를 유지하는 데 도움이 된다는 것을 보여준다고 언급합니다.
가격 및 배포
- 관리형 클라우드 [statewright.ai] – 무료 티어(워크플로우 3개, 월 200회 전환) 및 유료 티어($9/월 Pro, $99/월 Team, 엔터프라이즈 맞춤형). 청구는 워크플로우 저장소, 실행 기록 및 MCP 게이트웨이를 포함합니다.
- 자체 호스팅 – Docker-Compose 스택(PocketBase + 게이트웨이 + 편집기). 모델 서빙을 위해 자체 Ollama를 사용합니다. 엔진과 에이전트는 Apache-2.0입니다. 게이트웨이는 현재 FSL-1.1-ALv2입니다(2029년에 Apache-2.0으로 전환 예정).
트레이드오프 / 제한 사항
- MCP 인식 클라이언트 또는 사용자 정의 후크가 필요 – 모든 AI 채팅 도구가 지원하는 것은 아닙니다.
- 워크플로우는 수동으로 작성된 JSON입니다(에이전트가
statewright_create_workflow를 통해 생성할 수 있지만). - 과도하게 제한적인 워크플로우는 에이전트가 멈출 수 있습니다.
statewright_deactivate명령으로 가드를 우회할 수 있습니다. - 연구 결과는 작은 벤치마크 하위 집합으로 제한됩니다.
누가 사용할까?
- 개발 팀 – 안전하고 감사 가능한 AI 지원 코드 변경을 원하는 팀.
- 도구 빌더 – 엄격한 정책 시행으로 LLM 에이전트를 임베드하려는 사람들.
- 연구자 – 상태 머신 기반 프롬프트 또는 상태별 모델 라우팅을 탐구하는 사람들.
TL;DR: Statewright는 Rust 기반 오픈소스 툴킷으로, 상태 머신 기반 AI 에이전트 워크플로우를 정의하고 상태별 도구 권한을 강제하며 다른 단계를 다른 모델로 라우팅할 수 있습니다. 여러 최신 AI 코딩 어시스턴트와 통합되며 자체 호스팅 또는 관리형 클라우드 서비스를 통해 사용할 수 있습니다.
관련
- Dispatch
- 프로젝트
- 프로젝트
- 프로젝트
- 프로젝트