AGBoss는 LangGraph 기반 AI 에이전트 워크플로를 TypeScript로 구성하고 정적으로 검증하는 오픈소스 프레임워크다. 제작자는 의존성 주입, 실행 경로 검증, 예산·개인정보 정책, 테스트 기능을 제공한다고 설명한다. 현재 공개된 버전은 v0.1.0이며 런타임 @agboss/core와 CLI·정적 컴파일러 @agboss/cli를 npm에서 배포한다.

새 프로젝트는 CLI로 생성할 수 있다.

npm exec --yes --package=@agboss/cli@0.1.0 -- agboss create my-app
cd my-app
npm install

기존 프로젝트에 추가할 때는 런타임을 일반 의존성으로, CLI를 개발 의존성으로 설치한 뒤 정적 검사를 실행한다.

npm install @agboss/core
npm install -D @agboss/cli
npx agboss check

새 프로젝트 생성기는 package.json에 두 패키지를 등록하고 AGENTS.md, CLAUDE.md와 AI 코딩 에이전트용 안내 파일을 만든다. npm install의 postinstall은 agboss check를 실행해 .agboss/types.d.ts를 생성하고, 버전에 맞는 안내 자료 13개를 .claude/skills/agboss/에 푼다. 사용자는 .env에 OPENROUTER_API_KEY를 설정한 뒤 npm run chat으로 예제를 실행할 수 있다. 기존 프로젝트에서는 @agboss/core가 운영 런타임에 들어가고, @agboss/cli는 정적 검사·코드 생성·개발 감시·시각화 도구를 제공해 운영 컨테이너 이미지에는 포함하지 않는 구조다.

AGBoss는 에이전트, 액션, 라우터, 도구, MCP 서버, A2A 서비스와 지식 베이스를 데코레이터 기반의 엄격한 타입 구성 요소로 다룬다. 이를 @Application 컨테이너에 등록하고 생성자 의존성 주입으로 연결한다. CLI의 agboss check는 워크플로 경로와 구성 요소 입력·출력 관계를 정적으로 검사하며, 선언된 액션 보상과 오류 경로, 병렬 실행과 조인, 하위 워크플로도 검사 대상이다. 제작자는 실행 전 예산 검사, PII 토큰 마스킹, 인간 검토를 위한 일시 중지, 멀티 인스턴스 SQLite WAL 임대와 작업 분배, 서명된 에이전트 메시 네트워크, 평가·테스트 파이프라인도 기능으로 제시한다.

설치 후 구성과 실행

CLI는 프로젝트 package.json의 "agboss": { "application": "src/job-scout.application.ts" }에 지정된 애플리케이션을 대상으로 동작한다. 다른 경로는 --application <path>로 지정할 수 있다. npx agboss check는 타입 선언 파일을 만들고, agboss dev는 애플리케이션의 src/ 변경을 감시해 검사를 다시 실행한다. 애플리케이션에 시작점이 여러 개라면 실행 명령에 전체 시작 이름을 지정해야 한다. 하나뿐이면 생략할 수 있다.

npx agboss chat # the application's one start; with several: --start <name>
npx agboss run --start chat-workflow-start "my resume src/data/sample-resume.md"
npx agboss run --start <name> --input '<json>' # a start taking a DTO: checked field by field first
npx agboss describe [--json] # the application: workflows, starts, children, implementations — no API key
npx agboss check --env prod # types, assembly, the worst case per start, prod's process variables
npx agboss dev # watch mode: types regenerated, problems printed on change
npx agboss studio # LangGraph Studio on every workflow — no studio.ts, no langgraph.json
npx agboss --help # run, eval, replay, golden, compare, rag index

agboss studio는 애플리케이션의 모든 워크플로와 하위 워크플로를 빌드해 .agboss/에 LangGraph Studio 설정을 만들고 개발 서버를 실행한다. 조립 오류나 필요한 환경 변수가 있으면 서버를 시작하기 전에 멈춘다. agboss describe는 API 키 없이 애플리케이션 구성을 출력한다. 실행 명령에 시작 이름이 없거나 존재하지 않는 이름을 쓰면 시작점 목록을 보여 주고 실행하지 않는다.

애플리케이션 설정에는 워크플로와 모델 제공자, 예산, 저장소 구현을 등록한다. 기본 모델 제공자를 쓰지 않고 하나라도 직접 등록하면 등록한 목록이 전체 목록으로 간주된다. 각 모델은 serves에 따라 정확히 한 제공자에 연결돼야 한다. 제공자가 없으면 [model.unserved], 둘이면 [model.ambiguous-provider] 오류가 난다. agboss check --models는 애플리케이션의 모든 워크플로에서 모델 연결을 검사한다. 제공자별 재시도, 호출 제한, 회로 차단 정책을 설정할 수 있으며, 호출 제한이 없으면 별도 제한은 적용되지 않는다. API 키는 환경 설정의 Secret 필드로 읽는다.

환경은 애플리케이션별 계약 클래스와 환경별 객체로 구성한다. Secret 값은 프로세스 변수에서만 읽으며 기본값을 둘 수 없다. 필드 누락이나 타입 불일치는 컴파일 또는 애플리케이션 조립 검사에서 드러난다. agboss check --env prod는 필요한 변수의 이름과 값·비밀 여부를 출력하지만 실제 값은 표시하지 않는다. agboss chat은 기본적으로 dev 환경을 읽고, --env staging처럼 다른 환경을 고를 수 있다. 테스트는 test.environment.ts를 사용하며 파일이 없으면 실패한다. 애플리케이션에 설정이 없어도 EmptyEnvironment 계약은 필요하다.

실행·저장·비용 관리

저장소 계약은 기본적으로 메모리 구현을 사용한다. 재시작 후에도 일시 중지 상태와 실행 기록을 유지하거나 여러 프로세스에서 복구하려면 SQLite 구현을 애플리케이션에 등록해야 한다. SQLite 저장소는 한 애플리케이션 인스턴스당 하나의 파일을 사용하고 WAL과 busy_timeout, BEGIN IMMEDIATE를 사용한다. 파일 경로는 환경 계약의 sqlitePath로 지정해야 한다. 문서에 따르면 하나의 파일은 한 머신에서 사용하며, 메모리 기본 저장소는 재시작 뒤 상태가 남지 않는다.

실행 트리는 임대를 통해 한 번에 한 실행 주체가 처리한다. SQLite 저장소를 사용하는 경우 인스턴스는 시작 시와 30초마다 중단된 실행을 찾아 만료된 임대를 얻고 마지막 체크포인트부터 이어 간다. 기본 임대는 30초이며 10초마다 갱신된다. 기본 종료 대기 시간은 25초다. app.close()는 실행을 기다린 뒤 제한 시간이 지나면 중단하며, 다른 인스턴스가 실행을 이어받을 수 있다. 라이브니스·레디니스 검사 메서드도 제공하지만, 프레임워크가 HTTP 엔드포인트를 직접 열지는 않는다.

예산은 @Budget 구성 요소로 설정한다. 실행 단위 예산, 기간별 테넌트 예산, 애플리케이션 예산을 둘 수 있고, 매 실행 시작과 모델 호출 전 예산을 확인한다. 실행 시작 시 예산을 넘겼으면 첫 단계 전에 거부되며, 호출 비용은 실제 비용이 확인된 뒤 기록된다. 따라서 병렬 호출이 이미 진행 중이면 예산을 조금 초과할 수 있고, 초과 폭은 진행 중인 호출 비용에 좌우된다. 모델이 아닌 유료 서비스 비용은 SpendRecorder로 기록할 수 있다. 실행별 단계 수 제한은 별도 설정이며 금액 예산과는 다르다.

PII 정책은 모델 경계에서 개인정보를 마스킹한다. 토큰 치환은 실행 체크포인트의 토큰 맵을 이용해 되돌릴 수 있고, 거부 정책은 지정한 개인정보가 입력이나 답변에 포함되면 실행 또는 해당 도구 호출을 거부한다. 마스킹된 값을 모델에 보내지만 도구·액션·완료 단계는 복원된 값을 받는다. 애플리케이션·워크플로·에이전트·라우터에 정책을 등록할 수 있다. 애플리케이션 공통 pseudonymKey를 설정하지 않으면 인스턴스마다 다른 키를 만들 수 있으며, 이 경우 여러 인스턴스의 로그에서 같은 값이 서로 다른 토큰으로 보일 수 있다는 경고가 나온다.

워크플로와 검증 기능

코드 라우터는 모델을 호출하지 않고 입력에 따라 경로를 선택할 수 있다. 병렬 실행은 .toParallelAgents()나 .toParallelActions()로 시작하고 .join()으로 결과를 합친다. maxConcurrency로 동시 실행 수를 제한하며, 실패 처리 정책과 조인 오류 경로도 지정한다. 정해진 수의 응답만 기다리는 쿼럼은 최소·최대 응답 수와 마감 시간을 설정하며, 조건에 맞지 않으면 QuorumNotReachedError가 발생한다. 워크플로를 다른 워크플로의 단계로 실행하거나, maxDepth를 설정해 직접 재귀 실행할 수도 있다. 서로가 서로를 호출하는 상호 재귀는 정적 검사 오류다.

인간 검토가 필요한 실행은 채널에서 일시 중지하고 pauseId로 재개한다. 응답자는 채널 역할에 따라 실행 소유자 또는 채널이 부여한 자격으로 제한할 수 있다. 자유 형식 답변은 @ReplyInterpreter로 결정으로 해석할 수 있다. 답변을 해석할 수 없거나 검증에 실패하면 일시 중지 상태는 유지되며, 다시 답하거나 구조화된 결정을 보낼 수 있다. app.resume은 테넌트와 응답자 정보를 받을 수 있고, 다른 테넌트의 일시 중지 건에는 접근할 수 없다.

@Judge는 에이전트 답변의 품질을 판정하고, @InputGuardrail과 @OutputGuardrail은 모델 입력이나 답변을 차단한다. 판정 모델과 가드레일 모델 호출 비용은 실행 비용에 포함된다. 컴팩션은 오래된 대화 기록을 요약하거나 최근 대화만 유지한다. 요약은 새 실행이 대화 기록을 처음 읽을 때 지연 실행되며, 요약 오류가 나면 새 실행은 작업을 시작하지 않는다.

테스트는 testWith(Application)으로 실제 애플리케이션 컨테이너를 실행하고 모델 호출은 스크립트로 대체한다. 네트워크는 차단되고 MCP 서버는 대체되며, 기본 테스트 시계는 VirtualClock, ID는 테스트마다 결정적으로 생성된다. testTool, testAction, testRouter, testArbiter, testRag, testJudge, testGuardrail, testPii 등 구성 요소별 테스트 러너도 제공한다. 저장소 예제에는 agboss check와 npm test를 CI에서 실행하는 독립 예제 애플리케이션 7개가 포함돼 있다. 제작자는 원시 LangGraph 그래프에서 TypeScript 컴파일을 통과하는 경로 오류를 agboss check가 실행 전에 잡는 예제도 제시한다.

배포 자료와 조건

설명서와 빠른 시작은 AGBoss 문서, 빠른 시작, CLI 참조에서 볼 수 있다. 코드와 예제는 AGBoss 저장소와 독립 예제 저장소에 공개돼 있다. 라이선스는 Apache License 2.0이다.

이 자료는 저장소의 제품 설명과 사용 문서를 바탕으로 하며, 기능 주장은 제작자가 제시한 것이다. 실제 적용에는 TypeScript 프로젝트 구성과 환경 변수 설정, 필요한 경우 영속 저장소 및 모델 제공자 설정이 필요하다.