<img src="./gambit_1color_bg.png" alt="Gambit logo" height="50" />

에이전트 프레임워크 (Agent frameworks)는 에이전트를 구축하도록 도와줍니다. Gambit은 에이전트가 제대로 작동한다는 증거를 만드는 것을 도와줍니다.

Gambit은 에이전트 시스템을 위한 합성 시나리오 (synthetic scenario) 및 평가 레이어 (evaluation layer)입니다. 현실적인 시나리오를 생성하고, 그 품질을 검증하며, 에이전트를 대상으로 실행하고, 행동을 채점하며, 추적 증거 (trace evidence)를 캡처하고, 실패 사례를 회귀 테스트 세트 (regression suites)로 전환합니다.

네이티브 Gambit 에이전트는 완전히 통합된 루프 (fully integrated loop)로 가는 가장 빠른 경로입니다: 타입이 지정된 입출력 (typed inputs and outputs), 로컬 실행 (local runs), 시나리오, 채점기 (graders), 추적 (traces), 권한 증거 (permission evidence), 그리고 시뮬레이터의 Build/Test/Grade/Verify 워크플로우를 제공합니다.

데모 영상 시청.

빠른 시작 (Quickstart)

요구 사항: Node.js 18 이상 및 OPENROUTER_API_KEY (OpenRouter 스타일의 API를 프록시하는 경우 OPENROUTER_BASE_URL을 설정하세요).

npx를 사용하여 CLI를 직접 실행합니다 (설치 불필요):

export OPENROUTER_API_KEY=...
npx @bolt-foundry/gambit demo

예제 파일(hello 에이전트 정의 및 examples/ 갤러리)을 다운로드하고 환경 변수를 설정합니다.

시뮬레이터(simulator)를 통한 온보딩을 시작하려면 다음을 실행하세요:

npx @bolt-foundry/gambit-simulator serve gambit/hello.deck.md
open http://localhost:8000/debug

Build 탭을 사용하여 자신만의 워크스페이스 에이전트와 시나리오를 초안 작성하세요.

터미널(repl)에서 예제를 실행합니다:

npx @bolt-foundry/gambit repl gambit/hello.deck.md

이 예제는 단순히 "hello"라고 말하고 사용자의 메시지를 다시 반복합니다.

브라우저(시뮬레이터 패키지를 통한 serve)에서 예제를 실행합니다:

npx @bolt-foundry/gambit-simulator serve gambit/hello.deck.md
open http://localhost:8000/debug

---

왜 Gambit인가

에이전트 팀은 이미 에이전트를 구축하고 오케스트레이션 (orchestrate)할 수 있는 많은 방법을 가지고 있습니다: 네이티브 Gambit, Mastra, LangGraph, OpenAI Agents SDK, CrewAI, Google ADK, LlamaIndex, Pydantic AI, 그리고 커스텀 스택 (custom stacks). 더 어려운 제품 문제는 해당 에이전트들이 생존하는 데 필요한 상황을 만들어내고, 그 상황들이 좋은 테스트인지 확인하며, 행동이 퇴보(regress)할 때 증거를 보존하는 것입니다.

Gambit은 다음과 같은 신뢰성 루프 (reliability loop)에 집중합니다:

• 시나리오 생성 (Generate scenarios): 현실적인 사용자, 도구, 워크플로 (workflow), 정책 및 엣지 케이스 (edge case) 압박을 위한 시나리오를 생성합니다.
• 시나리오 데이터 평가 (Evaluate the scenario data): 현실성, 커버리지 (coverage), 난이도, 근거 (grounding), 중복성 및 기대 결과의 명확성을 평가합니다.
• 에이전트 평가 실행 (Run agent evals): 네이티브 Gambit, Mastra, LangGraph, OpenAI 또는 커스텀 에이전트를 대상으로 평가를 실행합니다.
• 행동 채점 (Grade behavior): 트랜스크립트 (transcripts), 아티팩트 (artifacts), 트레이스 (traces) 및 타입화된 출력 (typed outputs)을 통해 행동을 채점합니다.
• 실패 진단 (Diagnose failures): 트레이스 증거와 권한 증거를 통해 실패를 진단합니다.
• 회귀 테스트 스위트 재생성 (Regenerate regression suites): 실패 사례로부터 회귀 테스트 스위트를 재생성하여 동일한 행동이 다시 조용히 망가지는 것을 방지합니다.

네이티브 Gambit 에이전트의 경우, 동일한 시스템이 에이전트를 정의, 실행, 트레이스, 테스트, 채점 및 디버깅하는 과정을 엔드 투 엔드 (end to end)로 수행합니다. Mastra, LangGraph, OpenAI 또는 커스텀 에이전트의 경우, Gambit은 프레임워크의 반대편에 위치합니다: 즉, 테스트 데이터 엔진, 채점 루프 (grader loop), 로컬 재현 하네스 (reproduction harness) 및 CI 행동 체크 역할을 수행합니다.

일반적인 워크플로 (Common workflows)

네이티브 Gambit 경로 (Native Gambit path)

Gambit에서 에이전트를 정의하고, 로컬에서 실행하며, 계속 작동해야 하는 행동에 대한 시나리오를 추가하고, 채점기 (graders)를 부착하고, 시뮬레이터에서 트레이스를 검사하며, CI에서 동일한 체크를 재사용합니다. 이는 Gambit이 에이전트 정의와 검증 루프를 모두 소유하기를 원할 때 가장 직접적인 경로입니다.

자체 에이전트 사용 (Bring your own agent)

Mastra를 사용하여 TypeScript 에이전트 애플리케이션을 구축합니다. Gambit을 사용하여 중요한 Mastra 행동에 대한 시나리오 스위트를 생성 및 검증한 다음, 해당 실행에서 생성된 트랜스크립트와 아티팩트를 채점합니다. 얇은 래퍼 (thin wrapper)를 통해 실행 입력, 트랜스크립트 턴 (transcript turns), 아티팩트, 상태 경로 (state paths) 및 트레이스 참조를 기록하면 Gambit이 이를 채점하고 실패 사례를 재현 가능한 상태로 유지할 수 있습니다.

풀 리퀘스트 게이트 (Pull request gate)

모든 풀 리퀘스트 (pull request)에서 중요한 시나리오를 실행하고, 결과로 나온 트랜스크립트나 아티팩트를 채점하며, 행동이 기대 표준 미만으로 떨어지면 체크를 실패 처리합니다. 실패한 체크는 트레이스, 상태 및 재현 입력을 유지해야 하므로 회귀 (regression) 문제를 로컬에서 디버깅할 수 있어야 합니다.

# 제안된 워크플로우 형태. 이것은 위치 가이드이며, 공개된
# bolt-foundry/gambit-action 릴리스가 아닙니다.
name: Agent behavior checks
...

현상 유지 (Status quo)

• 팀들은 에이전트를 구축할 수 있는 그 어느 때보다 많은 방법을 가지고 있지만, 자신들의 평가 (eval) 데이터가 프로덕션 (production)에서 중요하게 작용할 동작을 커버하고 있는지 확인할 방법은 더 적습니다.
• 합성 시나리오 (Synthetic scenarios)들은 그럴듯해 보일 수 있지만, 서로 중복되거나, 정책의 엣지 케이스 (policy edges)를 놓치거나, 예상되는 결과를 명확하게 명시하지 못할 수 있습니다.
• 에이전트의 실패는 종종 제공자 로그 (provider logs) 속으로 사라져 버리므로, 팀은 회귀 (regression)를 유발한 정확한 입력, 트랜스크립트 (transcript), 도구 호출 (tool calls), 그리고 아티팩트 (artifacts)를 재현할 수 없습니다.
• CI는 보통 에이전트의 동작보다 코드의 형태를 더 신뢰성 있게 체크합니다.

우리의 비전 (Our vision)

• 에이전트가 생존하는 데 필요한 상황들을 생성합니다: 사용자, 작업, 워크플로우, 도구 압박 (tool pressure), 정책 엣지 (policy edges), 그리고 하드 실패 모드 (hard failure modes).
• 시나리오 데이터 자체가 신뢰할 수 있는 평가 (eval) 데이터가 되기 전에 먼저 등급을 매깁니다.
• 큐레이션된 스위트 (curated suite)를 대상으로 모든 대상 에이전트를 실행하고 트랜스크립트 (transcript), 상태 (state), 아티팩트 (artifacts), 트레이스 이벤트 (trace events), 그리고 권한 증거 (permission evidence)를 보존합니다.
• 역량 격차 (capability gap), 도구 문제 (tool issue), 프롬프트 문제 (prompt issue), 정책 모호성 (policy ambiguity), 검색 실패 (retrieval miss), 또는 안전하지 않은 동작 (unsafe action)에 의해 실패 원인을 진단합니다.
• 이러한 실패들을 더 정교한 후속 시나리오와 회귀 (regression) 체크로 다시 피드백합니다.

---

CLI 사용하기 (Using the CLI)

CLI를 사용하여 에이전트 정의를 로컬에서 실행하고, 출력을 스트리밍하며, 트레이스/상태 (traces/state)를 캡처하세요. 현재의 CLI와 파일 형식은 여전히 정확한 구현 용어로 deck을 사용합니다.

npx로 실행 (설치 불필요):

npx @bolt-foundry/gambit <command>

에이전트 정의를 한 번 실행:

npx @bolt-foundry/gambit run <deck> --context <json|string> --message <json|string>

--context는 기존의 --init 플래그를 대체합니다. CLI는 기존 스크립트가 계속 작동할 수 있도록 현재까지 --init을 지원 중단 예정 (deprecated) 별칭으로 허용합니다.

REPL로 진입 (기본적으로 스트리밍):

npx @bolt-foundry/gambit repl <deck>

에이전트 정의를 위한 집중형 브라우저 채팅 시작:

npx @bolt-foundry/gambit chat <deck> --state .gambit/chat/workspace.sqlite --trace .gambit/chat/trace.jsonl

전체 시뮬레이터 워크벤치 (simulator workbench) 없이 로컬호스트 트랜스크립트 (localhost transcript), 저장된 상태 (saved state), 트레이스 출력 (trace output), 그리고 런타임 제공 도구 (runtime-supplied tools)가 필요한 경우 chat을 사용하세요. 터미널 루프 (terminal loop)에는 repl을, 일회성 자동화 (one-shot automation)에는 run을, 그리고 Build/Test/Grade/Verify 워크플로우에는 gambit-simulator serve를 사용하세요.

반복 가능한 재현 (repeatable repros)을 위해, --repro-message <text>를 전달하면 원래의 사용자 요청을 자동으로 전송하지 않고 세션 페이로드 (session payload)에 첨부할 수 있습니다.

Markdown/TOML 파일을 사용하여 런타임 도구 (runtime tools)를 제공하세요:

npx @bolt-foundry/gambit chat MANAGER.md --runtime-tools ./workloop-runtime-tools.mock.md
npx @bolt-foundry/gambit chat support.deck.md --runtime-tools ./taxo-runtime-tools.mock.md

런타임 도구 파일은 name, description, 선택 사항인 inputSchema, 그리고 선택 사항인 action을 포함하는 [[tools]] 항목을 사용합니다. 액션 바인딩 (Action bindings)은 도구 인자 (tool arguments)를 컨텍스트 (context)로 하여 Gambit 에이전트 정의를 실행하며, 제품 특화 도구들을 이식 가능한 루트 에이전트 (portable root agent) 외부에 유지합니다. Workloop 스타일 및 Taxo 스타일의 모의 도구 피스처 (mock tool fixtures)는 examples/local-chat/을 참조하세요.

루트 에이전트 (root agent)에 대해 시나리오 페르소나 (scenario persona)를 실행하세요:

npx @bolt-foundry/gambit scenario <root-deck> --test-deck <persona-deck>

저장된 세션을 채점 (Grade) 하세요:

npx @bolt-foundry/gambit grade <grader-deck> --state <file>

시뮬레이터 패키지와 함께 디버그 UI (Debug UI) 서버를 시작하세요:

npx @bolt-foundry/gambit-simulator serve <deck> --port 8000

트레이싱 (Tracing) 및 상태 (state):

--trace <file>: JSONL 트레이스용
--verbose: 이벤트 출력용
--state <file>: 세션 유지용

워커 샌드박스 (Worker sandbox) 기본값

• 덱 (decks)을 실행하는 CLI 명령은 기본적으로 워커 샌드박스 (worker sandbox) 실행을 사용합니다.
• 기존의 인프로세스 (in-process) 실행을 강제하려면 --no-worker-sandbox (또는 --legacy-exec)를 사용하세요.
• --worker-sandbox는 워커 실행을 명시적으로 강제합니다.
• --sandbox / --no-sandbox는 권장되지 않는 (deprecated) 별칭입니다.
• gambit.toml 대응 설정:

  [execution]
  worker_sandbox = false # --no-worker-sandbox와 동일
  # legacy_exec = true    # 동일한 롤백 토글
  

npm 런처 (npx @bolt-foundry/gambit ...)는 사용자의 플랫폼에 맞는 Gambit CLI 바이너리를 실행하므로, 이러한 기본값과 플래그가 동일하게 적용됩니다.

시뮬레이터 (Simulator) 사용하기

시뮬레이터는 실행 과정을 스트리밍하고 트레이스 (traces)를 렌더링하는 로컬 디버그 UI (Debug UI)입니다. 이제 시뮬레이터는 프레임워크 패키지가 아닌 @bolt-foundry/gambit-simulator에 위치합니다.

npx로 실행 (설치 불필요):

npx @bolt-foundry/gambit-simulator <command>

시작하기:

npx @bolt-foundry/gambit-simulator serve <deck> --port 8000

그 다음 다음 주소를 여세요:

또한 다음 주소도 제공합니다:

http://localhost:8000/verify (기본적으로 활성화되어 있으며, GAMBIT_SIMULATOR_VERIFY_TAB=0으로 비활성화 가능)

로컬 반복 작업을 위해 결정론적인 (deterministic) Verify 피스처 (fixtures)를 시딩 (seed)하려면:

cd packages/gambit
deno task verify:seed-fixture

디버그 UI (Debug UI)는 트랜스크립트 레인 (transcript lanes)과 트레이스/도구 피드 (trace/tools feed)를 보여줍니다. 만약 덱 (deck)에 contextSchema가 있다면, UI는 기본값과 원시 JSON (raw JSON) 탭이 포함된 스키마 기반 폼 (schema-driven form)을 렌더링합니다. 로컬 우선 상태 (Local-first state)는 .gambit/ 디렉토리에 저장됩니다 (세션, 트레이스, 노트).

빌드 채팅 프로바이더 (Build Chat Provider) (Workbench)

Workbench 빌드 채팅의 기본값은 Codex CLI (codex-cli/default)입니다. 대신 Claude Code CLI를 통해 빌드 채팅을 실행하려면 (OpenRouter 경로 없음), 다음과 같이 설정하세요:

export GAMBIT_SIMULATOR_BUILD_CHAT_PROVIDER=claude-code-cli

선택적 오버라이드 (overrides):

export GAMBIT_SIMULATOR_BUILD_CHAT_MODEL=claude-code-cli/default
export GAMBIT_SIMULATOR_BUILD_CHAT_MODEL_FORCE=claude-code-cli/sonnet

시뮬레이터가 실행 중일 때는 Workbench 헤더 (New chat 왼쪽)에서 프로바이더를 전환할 수도 있습니다.

라이브러리 (Library) 사용하기

TypeScript 에이전트 정의, 재사용 가능한 지침 스니펫 (instruction snippets), 또는 커스텀 연산 단계 (compute steps)가 필요할 때 라이브러리 (Library)를 사용하세요. 호환성을 위해 내보내기(exported)된 헬퍼 이름은 defineDeck 및 defineCard로 유지됩니다.

JSR에서 헬퍼를 가져오세요:

import { defineDeck, defineCard } from "jsr:@bolt-foundry/gambit";

관련 항목 (Related)

• reviews/2026-04-15-AAR-raw-response-items.md

I/O를 검증하기 위해 Zod를 사용하여 contextSchema/responseSchema를 정의하고, 연산 에이전트 (compute agent) 정의를 위한 run/execute를 구현하세요. 코드에서 자식 에이전트 정의를 호출하려면 ctx.spawnAndWait({ path, input })를 사용하세요. ctx.log(...)를 사용하여 구조화된 트레이스 이벤트 (trace events)를 방출하세요.

프로그래밍 방식의 runDeckResponses를 위한 런타임 기본값 (Runtime defaults)

@bolt-foundry/gambit의 runDeckResponses는 Gambit 1.0의 표준 런타임 엔트리포인트 (entrypoint)입니다. 이는 CLI와 동일한 프로바이더/모델 기본값 (별칭 확장, 프로바이더 라우팅, 폴백 동작)을 사용하며 구조화된 응답 (Responses) 출력을 반환합니다. 단일 문자열 어시스턴트 텍스트는 프레젠테이션 투영 (presentation projection)이며, 런타임 상태가 아닙니다.

이전 (각 호출자에서 직접 프로바이더 설정):

import {
  createOpenRouterProvider,
  runDeckResponses,
...

이후 (기본값이 설정된 래퍼 (wrapper)):

import { runDeckResponses } from "jsr:@bolt-foundry/gambit";

const result = await runDeckResponses({
...

런타임별 재정의 (공유 런타임 객체):

import {
  createDefaultedRuntime,
  runDeckResponses,
...

교체 매핑 (Replacement mapping):

• 레거시 직접 코어 패스스루 (direct core passthrough) 내보내기: runDeck -> runDeckCore
• 표준 구조화된 기본값 내보내기: runDeckResponses
• 레거시 기본값 호환성 내보내기: runDeck
• 런타임 빌더 (Runtime builder): createDefaultedRuntime

---

첫 번째 네이티브 Gambit 에이전트 작성하기

최소한의 Markdown 에이전트 정의 (모델 기반): hello_world.deck.md

+++
label = "hello_world"

...

실행하기:

npx @bolt-foundry/gambit run ./hello_world.deck.md --context '"Gambit"' --stream

TypeScript를 이용한 연산 에이전트 정의 (모델 호출 없음): echo.deck.ts

// echo.deck.ts
import { defineDeck } from "jsr:@bolt-foundry/gambit";
import { z } from "zod";
...

실행 방법:

npx @bolt-foundry/gambit run ./echo.deck.ts --context '{"text":"ping"}'

자식 액션(child action)을 포함한 에이전트 정의 (TypeScript 도구 호출): agent_with_time.deck.md

+++
label = "agent_with_time"
modelParams = { model = "openai/gpt-4o-mini", temperature = 0 }
...

그리고 자식 액션(child action): get_time.deck.ts

// get_time.deck.ts
import { defineDeck } from "jsr:@bolt-foundry/gambit";
import { z } from "zod";
...

실행 방법:

npx @bolt-foundry/gambit run ./agent_with_time.deck.md --context '"hello"' --stream

레거시 respond-flow 데모 (이전 호환성 유지)

packages/gambit/examples/respond_flow/는 이전의 기록(transcript)/채점기(grader) 동작을 위한 레거시 호환성 예제로 유지됩니다. 새로운 에이전트 정의는 gambit_respond를 호출하는 대신, 스키마(schema)에 유효한 어시스턴트 출력을 직접 반환해야 합니다.