multi-bot-agentic

multi-bot-agentic은 독립적인 AI 에이전트 엔지니어링 쇼케이스입니다. 명시적인 Observe -> Decide -> Act (관찰 -> 결정 -> 실행) 루프, 영구적인 이벤트 로그 (event logs), 근거 추적 (rationale traces), 프로바이더 어댑터 (provider adapters), 그리고 제한된 안전 제어 (bounded safety controls)를 갖춘 결정론적 에이전트 코디네이터 (deterministic agent coordinator)입니다.

이 프로젝트는 프라이빗 인프라에 의존하지 않고 multi-bot 제품 아이디어를 포트폴리오 품질로 재현하기 위해 구축되었습니다. 기본 경로는 결정론적인 가짜 프로바이더 (fake provider)와 함께 완전히 오프라인으로 실행됩니다. OpenAI GPT, Claude Code CLI, Gemini, 그리고 Kimi/Moonshot을 위한 실제 어댑터들이 포함되어 있습니다.

대부분의 에이전트 데모는 LLM이 모든 것을 결정하도록 합니다. 이 저장소는 프로덕션 중심의 경로를 택합니다:

• LLM은 제어 평면 (control plane)이 아닌 입력 소스 (input source)입니다.
• 결정론적 결정 엔진 (deterministic decision engine)이 행동을 선택합니다.
• 모든 결정에는 근거 추적 (rationale trace)이 포함됩니다.
• 모든 라이프사이클 전환 (lifecycle transition)은 영구 저장됩니다.
• 모든 외부 통합은 어댑터 (adapter)를 통해 이루어집니다.
• 안전 제어 (safety controls)가 범위, 런타임, 도구, 그리고 취소를 제한합니다.

LLM 우선 (LLM-first) 에이전트들은 종종 프롬프트에서 행동으로 바로 건너뜁니다. 무언가 잘못되었을 때, 트랜스크립트 (transcript)는 모델이 무엇을 말했는지는 보여줄 수 있지만, 어떤 제어 규칙이 해당 행동을 허용했는지는 보여주지 못할 수 있습니다.

multi-bot-agentic은 모든 결정을 RationaleTrace와 함께 영구적인 이벤트 (durable event)로 기록합니다: 규칙 ID (rule id), 사용된 관찰 내용 (observations used), 거부된 행동 (rejected actions), 그리고 설명 (explanation)을 포함합니다. 나중에 실행을 다시 재생 (replay)하여 엔진이 왜 call_llm, call_tool, finish, 또는 cancel을 선택했는지 정확하게 검사할 수 있습니다.

multi-bot-agentic replay --event-log data/runs.sqlite --event-type decision --format text

많은 에이전트 프레임워크는 모델이 직접 도구를 선택하고 호출하도록 허용합니다. 이는 편리하지만, 도구 접근이 명시적이고 제한적이며 감사 가능해야 (auditable) 하는 프로덕션 워크플로우에서는 위험합니다.

이 저장소는 모델 출력을 하나의 관찰 (observation)로 취급합니다. 결정론적 결정 엔진은 TOOL:checklist:<payload>와 같은 제약된 텍스트를 해석하고, 안전 정책 (safety policy)을 확인한 후, 허용 목록에 있는 (allowlisted) 도구 어댑터를 실행합니다.

공급자별 SDK와 응답 형태 (response shapes)는 에이전트 코드를 이식하기 어렵게 만듭니다. 하나의 모델을 중심으로 구축된 프로토타입은 종종 오케스트레이션 계층 (orchestration layer)에 공급자의 세부 사항을 노출하게 됩니다.

multi-bot-agentic은

하나의 어댑터 인터페이스 뒤에서 공급자들을 정규화합니다:

OpenAIAdapter: GPT 및 OpenAI 호환 채팅 완성 (chat completions)용.
ClaudeCodeCLIAdapter: 로컬 Claude Code CLI 워크플로우용.
GeminiAdapter: Gemini generateContent용.
KimiAdapter: Moonshot/Kimi 채팅 완성 (chat completions)용.
FakeLLMAdapter: 결정론적 (deterministic) CI 및 데모용.

러너 (runner)는 모든 공급자 응답을 ModelOutput으로 소비하므로, 오케스트레이션 로직은 공급자에 중립적인 상태를 유지합니다.

포트폴리오 및 CI 데모는 실제 모델 자격 증명 (credentials), 모델 가용성 또는 네트워크 동작에 의존해서는 안 됩니다.

가짜 (fake) 공급자는 실제 런타임이 소비할 수 있는 결정론적인 모델 유사 출력을 생성합니다. 이는 여전히 관찰(Observe) -> 결정(Decide) -> 실행(Act), 도구 라우팅 (tool routing), 안전 점검 (safety checks), 이벤트 로깅 (event logging), 재생 (replay) 및 보고 (reports) 과정을 수행합니다.

multi-bot-agentic run --goal "Create a launch checklist for an AI agent platform" --provider fake

장시간 실행되는 에이전트 작업에는 실행 후 검사 (post-run inspection)가 필요합니다. 지속 가능한 상태 (durable state)가 없다면, 충돌과 재시작은 추측의 영역으로 변합니다.

sqlite 이벤트 로그는 생명주기 전환 (lifecycle transitions), 관찰 (observations), 결정 (decisions), 실행 요청 (action requests), 실행 결과 (action results), 실패 (failures), 취소 (cancellations) 및 완료 (completion)를 기록합니다. 재생 (Replay)은 어떤 공급자나 도구도 호출하지 않으므로, 사후 분석 (postmortems)이 안전하고 결정론적입니다.

multi-bot-agentic report --event-log data/runs.sqlite

제한 없는 에이전트 루프 (unbounded agent loops)는 흔한 실패 모드입니다. 이는 시간을 낭비하고, 비용을 발생시키며, 사고 대응을 어렵게 만듭니다.

SafetyPolicy는 max_steps, 공급자/도구 타임아웃 (timeouts), 프롬프트 크기 제한 (prompt size limits), 취소 파일 (cancellation files) 및 도구 허용 목록 (tool allowlists)을 통해 실행 범위를 제한합니다. 실행이 예산에 도달하면, 결정 엔진 (decision engine)은 명시적인 생명주기 이벤트를 통해 종료되거나 실패합니다.

팀들은 종종 GPT 대 Gemini 대 Kimi 대 Claude Code를 테스트하고 싶어 하지만, 공급자별 코드는 비교를 노이즈가 심하게 만듭니다.

공급자 어댑터 (provider adapters)를 사용하면, 공급자를 교체하면서도 동일한 러너 (runner), 동일한 결정 엔진 (decision engine), 동일한 이벤트 로그 (event log), 그리고 동일한 재생/보고 (replay/report) UX를 유지할 수 있습니다.

multi-bot-agentic run --goal "Draft a migration plan" --provider openai
multi-bot-agentic run --goal "Draft a migration plan" --provider gemini
multi-bot-agentic run --goal "Draft a migration plan" --provider kimi
...

에이전트 데모는 종종 산문(prose)으로 끝납니다. 하지만 실제 워크플로 (workflows)에는 구조화되고 반복 가능한 아티팩트 (artifacts)가 필요합니다.

내장된 checklist 도구는 목표를 결정론적인(deterministic) 실행 체크리스트로 변환하고, 도구 결과를 이벤트 로그에 기록합니다. 이는 의도적으로 단순하게 설계되었지만, 모델이 제안하고, 정책(policy)이 검증하며, 어댑터가 실행하고, 이벤트 로그가 기록하는 프로덕션 패턴 (production pattern)을 보여줍니다.

계획 (planning), 도구 사용 (tool use), 모델 호출 (model calls), 재시도 (retries), 그리고 상태 (state)가 뒤섞이면 에이전트 시스템을 설명하기 어려워질 수 있습니다.

이 저장소 (repo)는 경계를 명확하게 유지합니다:

runner.py: 관찰(Observe) -> 결정(Decide) -> 실행(Act)을 담당합니다.
decision.py: 결정론적인 규칙 (deterministic rules) 및 근거 추적 (rationale traces).
lifecycle.py: 상태 머신 (state-machine) 전이.
event_log.py: 영구적인 (durable) sqlite 이벤트.
llm/: 공급자 어댑터 (provider adapters).
tools/: 화이트리스트에 등록된 도구 어댑터 (allowlisted tool adapters).
safety.py: 경계 및 취소 (bounds and cancellation).

실제 공급자 테스트 (Live provider tests)는 유용하지만, 모든 풀 리퀘스트 (pull request)마다 필수적일 필요는 없습니다.

CI는 Python 3.10, 3.11, 3.12 환경에서 린트 (lint), 포맷 (format), 타입 체크 (typecheck), 테스트, 그리고 가짜 공급자 (fake-provider) 스모크 데모 (smoke demo)를 실행합니다. 실제 공급자 호출은 자격 증명 (credentials)과 외부 시스템이 필요하기 때문에 운영자 트리거 (operator-triggered) 방식으로 유지됩니다.

Goal
|
v
...

python -m venv .venv
. .venv/bin/activate
python -m pip install -e ".[dev]"
...

영구적인 이벤트 로그를 재생 (Replay) 하세요:

multi-bot-agentic replay --event-log data/runs.sqlite
multi-bot-agentic replay --event-log data/runs.sqlite --format text
multi-bot-agentic report --event-log data/runs.sqlite

• 명시적인 관찰(Observe) -> 결정(Decide) -> 행동(Act) 런타임 루프.
• 근거 추적(rationale traces)을 포함한 결정론적 결정 엔진 (Deterministic decision engine).
• 상태 머신(State-machine) 라이프사이클: 생성됨(created), 관찰 중(observing), 결정 중(deciding), 행동 중(acting), 성공(succeeded), 실패(failed), 취소됨(cancelled).
• 재생(replay) 기능이 있는 내구성이 있는 SQLite 이벤트 로그.
• OpenAI GPT, Claude Code CLI, Gemini, 그리고 Kimi/Moonshot을 위한 LLM 어댑터 (adapters).
• 허용 목록(allowlisted) 실행을 포함한 도구 어댑터 (tool adapters), 결정론적 체크리스트 생성을 포함함.
• 최대 단계(max steps), 프롬프트 경계(prompt bounds), 취소(cancellation), 타임아웃(timeouts)을 위한 안전 제어.
• 내구성이 있는 근거 추적을 검사하기 위한 인간이 읽을 수 있는 재생 및 실행 보고서.
• 프로덕션 지향적 레이아웃:
  src/

, tests/

, scripts/

, migrations/

, .github/workflows/

, 환경 설정(env config), 문서(docs).

제공자 (Provider)	어댑터 (Adapter)	실시간 자격 증명 (Live credential)
Fake	결정론적 로컬 제공자 (deterministic local provider)	없음
GPT / OpenAI	OpenAIAdapter	OPENAI_API_KEY
Claude Code	ClaudeCodeCLIAdapter	로컬 claude 명령
Gemini	GeminiAdapter	GEMINI_API_KEY
Kimi / Moonshot	KimiAdapter	KIMI_API_KEY

모든 어댑터는 출력을 ModelOutput으로 정규화합니다. 러너(runner)는 결정 엔진이 다음 행동을 선택하기 전에 해당 출력을 관찰(observation)로 소비합니다.

checklist: fake-provider 데모에서 사용되는 결정론적 실행 체크리스트 생성기.
echo: 어댑터 테스트를 위한 안전한 텍스트 에코.
readonly_file: 루트에 포함된 읽기 전용 파일 리더.

src/multi_bot_agentic/ 런타임(runtime), 라이프사이클(lifecycle), 결정 엔진(decision engine), 이벤트 로그(event log), 어댑터(adapters)
tests/ 결정론적 단위 테스트(unit tests) 및 통합 테스트(integration tests)
scripts/ 데모 및 검증 스크립트(verification scripts)
...

scripts/check.sh

scripts/check.sh는 ruff, 포맷 체크(format check), mypy, pytest를 실행하며, 재생/보고 기능이 포함된 fake-provider 스모크 테스트(smoke run)를 수행합니다. CI는 Python 3.10, 3.11, 3.12에서 동일한 스크립트를 실행합니다.

더 풍부한 로컬 데모를 위해:

scripts/run_demo.sh

README의 GIF는 재현 가능합니다:

python scripts/render_demo_gif.py

이 저장소는 또한 docs/demo.svg를 정적 아키텍처 카드(architecture card)로 유지합니다.

MIT — LICENSE를 참조하세요.

이 에이전트가 해결하는 실제 문제들 — 결정론적 (deterministic) ODA 루프, 추론 흔적 (rationale traces), 지속 가능한 이벤트 로그 (durable event log), GPT / Claude / Gemini / Kimi 어댑터, 그리고 안전 제어 (타임아웃, 제한된 범위, 취소).

문제	현상	솔루션 문서
#001	디버깅이 어려운 비결정론적 (Non-deterministic) 에이전트 루프	doc
...
전체 인덱스: docs/use-cases/README.md

의사결정 엔진 (Decision engine)— 로그가 남는 추론 (rationale)을 포함한 결정론적 (deterministic) 단계 선택
상태 머신 (State machine)—created → observing → deciding → acting → succeeded | failed | cancelled

이벤트 로그 (Event log)— 재생 (replay)을 위한 SQLite/JSON 감사 추적 (audit trail)
도구 어댑터 (Tool adapters)— 플러그형 HTTP/LLM/검색 (retrieval) 통합
안전 (Safety)— 타임아웃, 취소 토큰 (cancellation tokens), 제한된 임상 범위 (bounded clinical scope)