SandBase Harness

English | 中文

Listed on deepseek-plugin.org

Release

Official MCP Registry

Discussions

CodeQL

License

AI가 읽을 수 있는 프로젝트 메타데이터: llms.txt · 설치 가이드

AI 에이전트를 위한 로컬 우선(local-first) 런타임입니다. 세션, 격리된 도구(sandboxed tools), 메모리, 자격 증명(credentials), 감사 추적(audit trails), 그리고 내장 콘솔(Console) — 이 모든 것이 사용자의 기기 또는 자체 인프라에서 실행됩니다.

왜 필요한가 (Why)

에이전트 SDK는 모델 루프(model loop)를 처리합니다. 하지만 프로덕션 에이전트는 더 많은 것을 필요로 합니다: 지속적인 세션, 도구 거버넌스(tool governance), 샌드박스 경계(sandbox boundaries), 자격 증명 처리, 메모리, 감사 가능성(auditability), 그리고 사람이 무슨 일이 일어났는지 검사할 수 있는 UI입니다. managed-agents는 바로 그 런타임 계층이며 — 시각적 워크플로우 빌더도 아니고 또 다른 모델 SDK도 아닙니다.

주요 기능 (Features)

• Claude Managed Agents 스타일의 /v1 API 및 로컬 콘솔
• 에이전트, 세션, 환경, 자격 증명 금고(credential vaults), 메모리 저장소(memory stores), 파일, 스킬, API 키에 대한 기본 SQLite 메타데이터 — 워크스페이스 상태 디렉터리에 로컬 파일/스킬 바이트가 저장됨
• 세션 재생 및 디버깅을 위한 재개 가능한 서버 전송 이벤트(Server-Sent Events)
• 설정 V2를 통해 구성되는 단일 활성 모델 제공자 경계(model provider boundary)
• 샌드박스 백엔드: 로컬 프로세스, Docker (세션별 컨테이너), Kubernetes (kubectl exec/cp), 자체 호스팅 워커 큐
• MCP 도구 세트, 권한 정책, 내장 도구 및 스킬 패키지
• managed-agents/sdk의 TypeScript SDK
• 릴리스 게이트: npm run release:check

빠른 시작 (Quick Start)

요구 사항: Node.js 22+, npm 10+, 그리고 모델 제공자 API 키(OpenAI, Anthropic, MiniMax 또는 모든 OpenAI 호환 엔드포인트). Docker는 선택 사항이며 Docker 기반 샌드박스에만 필요합니다.

git clone --branch v0.3.8 --depth 1 https://github.com/sandbaseai/sandbase-harness.git
cd sandbase-harness
npm ci
...

init은 실행하는 디렉터리에 워크스페이스를 작성합니다: 에이전트, 스킬 폴더 및 config.yaml 파일이며, 이 파일의 제공자 참조는 ${OPENAI_API_KEY} 환경 변수입니다. start는 http://127.0.0.1:3000에서 API와 콘솔을 서비스합니다.

설정 > 설정(Settings > Setup) 페이지(http://127.0.0.1:3000/dashboard)에서 두 단계를 완료해야 합니다:

1. Provider 설정. 제공업체(provider) 양식에 API 키를 붙여넣고 저장하세요. 그러면 페이지에서 저장된 구성이 아직 활성화되지 않았다고 보고하므로, 런타임을 재시작해야 합니다. Ctrl+C로 중지한 다음 start 명령을 다시 실행하거나, 재시작 버튼을 사용하세요. 저장된 설정은 시작 시에만 적용됩니다. 제공업체가 목록에 없다면, OpenAI와 호환되는 공급업체를 선택하고 기본 URL(base URL)을 설정하세요.
2. 모델 설정. Agent models 패널에서 제공업체가 실제로 서비스하는 모델 ID를 설정해야 합니다. 예를 들어 DeepSeek의 경우 deepseek-chat입니다. 에이전트는 자체 모델 ID를 가지고 있으므로, init이 작성한 gpt-4o는 모든 제공업체에 유효하지 않으며, 잘못된 ID는 model_not_found 오류로 턴(turn)을 실패하게 만듭니다.

콘솔에서 첫 번째 메시지를 보내세요: Sessions를 열고 에이전트를 위한 세션을 생성한 다음, 컴포저에 입력합니다. 터미널에서는 하나의 명령으로 충분합니다:

node ../sandbase-harness/dist/index.js chat agent_assistant --message "hello" --tool-approval allow

chat은 해당 메시지를 보내고 턴이 안정화되면 종료됩니다. --message가 없으면 세션을 열어두고 사용자가 중지할 때까지 스트리밍합니다. --tool-approval allow는 에이전트가 수행할 수 있는 도구 호출(tool calls)을 사전 승인하며, 그렇지 않으면 init 템플릿은 승인을 위해 해당 기능을 보류하고 사람이 답변하기를 기다립니다. CLI를 참조하세요.

npm의 범위 지정되지 않은(unscoped) managed-agents 이름은 이 프로젝트가 아닙니다. 공식 스코프 패키지가 이 저장소에 발표될 때까지는 위에 표시된 태그가 지정된 GitHub 소스 릴리스에서만 설치하세요. npx managed-agents 또는 npm install managed-agents를 실행하지 마세요.

Codespaces에서 사용해 보기

포함된 개발 컨테이너는 종속성을 설치하고 런타임을 빌드합니다. 터미널이 준비되면 포워딩된 포트에서 서버를 시작하세요:

node dist/index.js start --host 0.0.0.0

포워딩된 SandBase Harness 콘솔 포트를 열고, **설정(Settings) > 설정(Setup)**에서 모델을 구성하세요. Codespaces 사용량은 GitHub에서 청구될 수 있습니다. 위에 설명된 로컬 퀵 스타트는 무료이며 모든 런타임 데이터를 사용자 기기에 유지합니다.

스크린샷

콘솔 개요	설정	API 참조
overview	settings	api-ref

공식 SDK 사용하기

런타임은 동일한 포트에서 자체 /v1 API를 제공하며, 공식 Anthropic TypeScript SDK 클라이언트가 이를 변경 없이 구동합니다. 클라이언트의 baseURL을 런타임으로 지정하고, 런타임 API 키를 제공하면 examples/official-sdk에 있는 퀵 스타트가 전체 턴(turn)—메시지, 도구 호출(tool call), 도구 결과(tool result), 최종 답변—을 대상으로 실행합니다. 이 예제는 tests/conformance/official-sdk-quickstart.test.ts에 의해 모든 풀 리퀘스트(pull request)에서 실행되므로, 설명되는 호환성은 주장되는 것이 아니라 테스트되는 것입니다.

동일한 표면은 docs/api.md에도 명시되어 있으며, 이 저장소 자체의 TypeScript SDK는 아래 SDK에서 문서화됩니다.

CMA 호환성

게시된 Claude Managed Agents 계약에 대한 커버리지는 src/core/capabilities/matrix.ts에서 항목별로 선언됩니다: 공식 SDK의 라우트 표면(SDK 0.131.0 기준 110개 메서드/경로 쌍) 중 90개의 경로는 마운트되고 20개는 이름으로 거부되며, 어떤 경로도 연기되지 않습니다. Partial 및 Unsupported 항목은 항상 그 이유를 명시합니다.

아래 표는 npm run docs:compat에 의해 생성되며, 계약의 정직성 테스트(contract-honesty test)는 이 매트릭스에서 벗어날 때 실패합니다.

수동 일시 정지(Manual pause) 및 재개(unpause) 기능이 존재하며, 일시 중지된 배포(paused deployment)도 수동 실행을 허용합니다. 시간 기반 실행(timed runs)은 deployment_run.started, .succeeded, .failed를 발행하는 반면, 수동 실행은 아무것도 발행하지 않습니다. 또한, deployment.created, .updated, .paused, .unpaused, .archived는 에이전트가 사라지는 연쇄 반응(agent-gone cascade)을 포함하여 전환 시점에 각각 발행하며, DELETE는 배포와 해당 실행 기록을 하나의 트랜잭션으로 제거한 후 deployment.deleted를 발행합니다. 런타임의 60초 간격 체크(tick)는 진행 중인 배포(due deployments)를 처리하고 시작(startup) 시점에는 포워드 스케줄을 재설정하지만, 놓친 트리거를 다시 재생하지는 않습니다. 남아있는 격차: mcp_egress_blocked_error는 MCP egress가 게이팅되지 않기 때문에 생성하는 경로(producing path)가 없습니다. |
| operations | outcome-grading | 지원됨 (Supported) | |
| operations | outcome-evaluation | 지원됨 (Supported) | |
| ... |<!-- compat-table:end -->

CLI

managed-agents init
managed-agents start [--host 127.0.0.1] [--port 3000]
managed-agents apply <file...>   # 매니페스트에서 에이전트/환경/배포 생성 또는 업데이트
...

apply는 동일한 API의 선언적(declarative) 형태입니다. 즉, 프론트매터에 에이전트 정의가 포함된 Markdown 파일(--- 아래 본문은 시스템 프롬프트가 됨), .yaml 환경 문서, 또는 Markdown 배포 매니페스트를 의미합니다 (프론트매터는 name, agent, environment, schedule를 담고; 본문은 초기 user.message가 됩니다). 해석된 ID들은 파일 옆의 managed-agents-lock.json에 저장되므로, 수정 후 apply를 다시 실행하면 중복 생성을 하는 대신 동일한 리소스를 업데이트합니다 — 이 잠금 파일(lock file)을 매니페스트와 함께 커밋하세요. 나중에 작성된 파일은 이름으로 이전 파일을 참조할 수 있으므로, apply coding-assistant.md environment.yaml deployment.md는 배포를 앞의 두 파일이 생성한 행에 연결합니다.

도구가 승인이 필요한 턴에서 실패하는 대신 주차되고, chat은 실행하기 전에 사용자에게 문의한 후 런타임이 같은 턴을 계속하도록 합니다. --tool-approval allow는 이러한 모든 호출을 사전에 결정하며, 이는 스크립트나 CI 작업이 사용하는 방식이고, deny는 이를 거부합니다. 프롬프트할 터미널이 없으면 기본값인 ask는 아무것도 응답하지 않고 대기 중인 호출들을 이름과 함께 비제로 종료하므로, 스크립트는 정책을 상속받기보다 자체적으로 명시하게 됩니다. 사용자 정의 도구는 예외입니다: 오직 사용자의 클라이언트만이 그 결과를 생성할 수 있으며, chat은 그렇게 말하고 비제로 종료합니다. 사용법을 참조하십시오.

SDK

import { ManagedAgentsClient } from 'managed-agents/sdk';

const client = new ManagedAgentsClient({
...

/v1 API는 Claude Managed Agents 리소스 형태를 따르므로, Anthropic SDK를 로컬 런타임에 연결할 수도 있습니다:

import Anthropic from '@anthropic-ai/sdk';

const client = new Anthropic({
...

인증 (Authentication)

기본적으로 열려 있습니다. API 키가 하나 이상 존재하면 인증이 활성화됩니다:

# 환경 변수를 통한 정적 키
export MANAGED_AGENTS_API_KEY=sk-local-example

...

클라이언트는 Authorization: Bearer <key>를 전송합니다.

통합 및 예제