vocion-core

Vocion (@vocion/core)은 AI 에이전트 작업을 단순한 프로토타이핑이 아닌 실제 프로덕션 환경에서 실행하기 위한 오픈 프레임워크입니다. README에서는 대상 사용자를 에이전트 팀을 프로덕션으로 전환하려는 엔지니어나 기술 리드로 설정하며, 단일 챗봇, 일회성 스크립트 또는 호스팅형 노코드 빌더에는 적합하지 않음을 명시합니다. 이 프로젝트는 Postgres 실행, Git을 통한 설정 관리, 그리고 중요한 작업에 대한 인간의 개입(human-in-the-loop)을 전제로 합니다. 코어 패키지는 npm에 게시되지 않으며, 저장소를 클론하여 직접 실행해야 합니다. 플랫폼 구성 요소 Vocion은 Next.js 앱, Postgres 스키마, MCP 서버 및 워크플로우 러너의 결합으로 설명됩니다. 사용자는 Sources, Objects, Skills, Playbooks, Workflows, Missions, Automations, Agents, Teams를 Git 내의 YAML 및 마크다운으로 작성하여 데이터베이스에 적용하며, 이를 통해 통합 휴먼 리뷰 큐, 관측성 및 플러그인 생태계를 갖춘 타입 안정성이 보장된 런타임을 제공받습니다. 하나의 런타임에서 세 가지 작업 모드가 공유됩니다: - Workflows: 승인 및 질문 게이트가 포함된 결정론적 단계. - Missions: 에이전트 팀이 계획을 세우고 작업하며 검토 하에 결과물을 생성하는 개방형 상시 책임 작업. - Teams: 책임 있는 인간 관리자 아래 리더를 중심으로 그룹화된 여러 에이전트. 기타 기능으로는 증분 및 클라이언트 범위의 수집 파이프라인을 갖춘 Google Ads, GA4, HubSpot, Gmail, Slack, Google Drive용 내장 커넥터 팩, 권한 주체로 해석되는 테넌트 Bearer 토큰 기반의 멀티테넌트 제어 평면, REST를 통해 리뷰 큐를 노출하는 쓰기 API(리뷰 목록 및 결정 엔드포인트), 그리고 에이전트 및 도구 평면으로서의 HTTP 기반 MCP가 포함됩니다. 탐색 및 변경 권한이 분리되어 있으며, 승인 게이트가 포함된 자율성 사다리가 실행을 제어하고, 클라이언트 간 격리는 프롬프트가 아닌 쿼리 수준에서 강제됩니다. 에이전트 실행은 harness.runsOn 설정을 통해 구성할 수 있습니다. 문서화된 옵션으로는 앱 프로세스 내부 실행, AWS Bedrock AgentCore Runtime의 프로젝트 전용 컨테이너 실행, 또는 AWS 관리형 하네스 위임이 있으며, 각 경우에 어떤 AWS 계정에서 토큰 비용을 지불하는지 설명되어 있습니다. 계층형 패키지 및 플러그인 계약 해당 저장소는 더 큰 플랫폼의 코어 레이어입니다. SDK 패키지는 Skill 및 PluginManifest 타입, LLM 클라이언트 타입을 포함한 안정적인 플러그인 계약을 정의합니다. 커넥터와 스킬은 별도의 플러그인 npm 패키지로 제공되며, 별도 저장소에 포크 가능한 스타터 설치 파일이 계획되어 있습니다. 플러그인은 매니페스트를 내보내는 npm 패키지이며, 코어는 부팅 시 SDK를 통해 매니페스트를 로드합니다. README에는 스키마 검증 라이브러리로 구축된 샘플 스킬 정의가 나와 있으며, 여기에는 slug, 이름, 버전, 제공자, 승인 요구 사항, 입력 및 출력 스키마, 그리고 PluginManifest로 내보낸 run 함수가 선언되어 있습니다. packages/plugins 디렉토리에는 참조용 transcript-highlights 플러그인이 포함되어 있습니다. 코드로서의 워크스페이스(Workspace as code) 모든 테넌트 컨텍스트는 워크스페이스에 저장됩니다. 워크스페이스는 저장소 체크아웃 외부에 위치하며 일반적으로 자체 저장소로 관리되는 YAML 및 마크다운 디렉토리입니다. 이를 통해 클라이언트 컨텍스트를 풀 리퀘스트(PR)에서 검토할 수 있으며 코어와 섞이지 않습니다. 환경 변수가 앱을 워크스페이스로 연결하며, 이 변수가 없으면 워크스페이스가 구성되지 않습니다. 문서화된 엔티티 타입과 위치는 다음과 같습니다: 워크스페이스 매니페스트, 에이전트(YAML 파일 및 시스템 프롬프트 마크다운 파일), 팀, 스킬, 플레이북, 미션, API로 생성된 워크플로우 실행 내역, 워크플로우, 시간 및 이벤트가 정의되는 유일한 곳인 자동화, 소스 가중치와 분류 프롬프트를 가진 객체 타입, 커넥터 종류와 동기화 주기를 가진 소스, 자동 실행 가능 작업을 정의하는 신뢰 규칙, 누적된 규칙의 명명된 버킷인 학습 단계, 에이전트별 테스트 케이스를 위한 평가 데이터셋, 테넌트 정의 대시보드 페이지. 코어 내부에는 베이스 팩이 포함되어 워크스페이스 하단에 레이어로 배치됩니다. extends 지시문으로 이를 고정하고, use 목록으로 에이전트를 활성화하며, 동일한 slug 파일을 통해 기본값을 오버라이드할 수 있습니다. 워크스페이스를 데이터베이스에 적용하면 워크스페이스 버전과 함께 감사 행이 기록되며, 도구 호출 시 워크스페이스 해시를 찍어 출력 결과가 어떤 프롬프트에서 생성되었는지 추적할 수 있습니다. 설치 및 운영 시작 방법은 클론 및 설치, 환경 예제 파일 복사 후 데이터베이스 URL, 인증 비밀키 및 최소 하나 이상의 LLM 제공자 키 설정, dev:up 스크립트를 통한 지원 서비스(Postgres, Langfuse, Temporal) 시작, 마이그레이션 실행, 워크스페이스 스캐폴딩, WORKSPACE_PATH 지정 및 적용, 그리고 localhost 3000 포트에서 개발 서버 시작 순으로 안내됩니다. 프로젝트 스크립트에는 린팅, 타입 체크, 테스트, 워크스페이스 적용 및 평가 실행이 포함됩니다. Claude Code, Cursor, Zed와 같은 MCP 클라이언트를 위해 단일 개발자 설치용 로컬 stdio 명령과 원격 HTTP 엔드포인트를 제공합니다. HTTP 엔드포인트에서는 테넌트 Bearer 토큰에서 조직을 도출하며, 모든 도구 호출은 인간과 동일한 권한 모델 하에 해당 조직 범위로 제한됩니다. 자격 증명은 양방향으로 처리되며 대시보드 페이지에서 관리됩니다. 인바운드 토큰은 Vocion에서 발행하여 SHA-256 해시로만 저장하며 평문으로는 한 번만 표시됩니다. 아웃바운드 벤더 키는 워크스페이스별로 제공될 수 있으며, 조직별 데이터 암호화 키를 사용하여 AES-256-GCM으로 암호화되어 저장되므로 워크스페이스 자체의 벤더 계정으로 비용이 청구됩니다. 플랫폼당 조직당 하나의 라이브 키가 허용됩니다. 모든 아웃바운드 벤더 호출은 먼저 워크스페이스에 저장된 키를 확인하고, 그 다음 서버 환경 변수를 확인합니다. 이는 채팅 모델, 수집 및 쿼리 시의 임베딩, 리랭킹, 비전 및 이미지 생성을 포함하며, 설계상 두 개의 내부 경로만 서버 키를 유지합니다. 암호화 설정은 개발용 로컬 볼트(vault) 모드와 실제 고객 키를 보유한 설치 환경에 권장되는 KMS 모드를 제공합니다. 검색(Retrieval)은 자체적으로 구현되었습니다: HNSW 코사인 유사도를 사용하는 pgvector와 Postgres 전체 텍스트 검색을 결합하고, 두 경로의 결과를 상호 순위 융합(Reciprocal Rank Fusion)으로 통합하며, 선택적으로 LLM 리랭킹을 수행합니다. 임베딩 및 리랭크 모델은 환경 수준 설정이며, 타입별 및 에이전트별 검색 가중치는 코드 변경 없이 워크스페이스에서 작성합니다. 스택 및 통합 사용된 스택은 App Router를 포함한 Next.js 16, React 19 및 엄격한 TypeScript, ORM을 포함한 PostgreSQL 16, 계정 및 프로젝트 멤버십을 통한 역할 기반 액세스 제어를 제공하는 Auth.js / NextAuth v5, 스킬별로 교체 가능한 LLM 제공자인 OpenAI 및 Anthropic, LLM 트레이싱을 위한 Langfuse 및 스팬/메트릭을 위한 OpenTelemetry, Postgres 기반의 인프로세스 내구성 워크플로우 단계 러너입니다. Slack 채팅 인터페이스에서는 에이전트를 멘션하면 스레드 답글이 생성되지만, 승인은 (기능 플래그 뒤에 숨겨진) 리뷰 큐에서만 가능합니다. 또한 리스, 하트비트, 실행당 비용 및 리퍼(reaper)를 갖춘 수 시간 분량의 실행을 위한 외부 워커 제어 평면이 포함되어 있습니다(이 또한 기능 플래그 적용). 라이선스 이 프로젝트는 Mozilla Public License 2.0(MPL 2.0) 하에 소스가 공개되어 있습니다. 이는 OSI 승인 라이선스이며 파일 수준의 카피레프트(copyleft)를 적용합니다. 사용, 자체 호스팅, 검사, 수정 및 더 큰 독점 시스템에 포함할 수 있으며, 배포 시 수정된 Vocion 파일은 MPL 하에 공개되어야 하지만 주변 애플리케이션 코드는 사용자의 소유로 남습니다. README에 따르면 데이터, 비즈니스 컨텍스트, 에이전트 설정, 워크플로우, 평가 이력 및 운영 출력물은 사용자의 소유이며, 프로젝트를 자체 환경에 배포할 수 있습니다. 다만 Vocion 자체의 화이트라벨링, 독점 라이선스 하의 배포, 벤더 지원 관리형 서비스, 독점 엔터프라이즈 모듈, 상업적 보증 및 서비스 수준 계약(SLA) 등의 특정 사용 사례는 별도의 계약이 필요합니다. 이름과 로고는 Metacto, Inc.의 상표이며 MPL은 상표권을 부여하지 않습니다. 문서 안내 README에는 코드 없이 빈 디렉토리에서 에이전트 인력까지 구축하는 시작 가이드, 저장소 내에서 작동하는 코딩 에이전트를 위한 파일, 기계 판독 가능한 문서 인덱스, 워크스페이스 작성 가이드, 엔티티별 필드 참조, 모든 객체가 어디서 작성/저장/실행/표시되는지 설명하는 객체 모델 페이지, 대시보드 페이지 가이드, 다양한 환경 및 부모 프로젝트 패턴을 다루는 배포 문서가 링크되어 있습니다. 기여 가이드는 툴링으로 강제되는 Conventional Commits, DCO 서명, 커밋 전 타입 체크, 테스트 및 린트 실행을 다룹니다.