CogitoAgent: 지속적으로 사고하고 200개 이상의 도구를 실행하는 오픈 소스 로컬 우선 (Local-First) AI 에이전트

지속적으로 사고하십시오. 자율적으로 행동하십시오. 프라이버시를 유지하십시오.

오늘날 대부분의 AI 에이전트는 두 가지 부류 중 하나에 속합니다. 파일을 제3자 클라우드에 업로드하거나, 사용자가 다음 프롬프트를 입력할 때까지 유휴 상태로 대기하는 것입니다. CogitoAgent는 다른 입장을 취하는 오픈 소스 프로젝트입니다. 당신의 파일은 당신의 기기에 머물고, 에이전트는 스스로 계속해서 사고합니다.

이 포스트에서는 CogitoAgent가 무엇인지, 어떻게 설계되었는지, 그리고 왜 여러분이 이 프로젝트에 스타(star)를 주고 싶어 할지에 대해 설명하겠습니다.

• GitHub: https://github.com/SnowLeopard-io/CogitoAgent
• Gitee (중국 미러): https://gitee.com/cnt-code/cogito-agent
• 라이선스 (License): Apache 2.0
• 스택 (Stack): TypeScript 5.x · Node.js ≥ 22.12 · Electron · isolated-vm
• 현재 버전 (Current version): v2.3.2

CogitoAgent란 무엇인가?

CogitoAgent는 당신의 로컬 작업 공간(local workspace) 내부에서 직접 실행되는 오픈 소스 자율 에이전트 프레임워크입니다. 추론과 결정을 내리기 위해 당신이 선택한 LLM API(OpenAI 호환 엔드포인트라면 무엇이든 가능, API 키 직접 사용)를 호출하지만, 당신의 파일, 코드, git 저장소 및 데이터베이스는 절대 당신의 기기를 떠나지 않습니다.

핵심 문구는 **"클라우드 구동, 로컬 실행 (cloud-driven, local-executed)"**입니다. 이것은 완전히 오프라인으로 작동하는 로컬 LLM은 아닙니다 (그 기능은 로드맵에 있습니다). 대신, 대화 컨텍스트(conversation context)만 지정된 LLM API로 전송되며, 파일 I/O, 코드 실행, git 작업 및 데이터베이스 쿼리는 모두 로컬에서 수행됩니다.

만약 여러분이 AutoGPT, Claude Code 또는 Cline을 사용해 보았다면, CogitoAgent가 스스로를 어떻게 포지셔닝하는지 다음과 같이 설명할 수 있습니다:

핵심 기능 요약

1. TypeScript 코어 — 컴파일 타임 타입 안정성 (compile-time type safety)을 갖춘 전체 TypeScript 재작성.
2. 개인정보 보호 우선 — 워크스페이스 파일은 로컬에 유지되며, 대화 컨텍스트 (conversation context)만 LLM API로 전송됩니다.
3. 지속적인 사고 — thinkCycle()이 3초마다 자동으로 트리거됩니다 (설정 가능).
4. 도구 실행 — 파일 작업, 코드, git, 데이터베이스, OCR, Office, GIS, 생물정보학 (bioinformatics), 의학, 화학, 금융 등을 아우르는 28개의 도구 모듈 및 200개 이상의 도구 제공.
5. 보안 샌드박스 (Security sandbox) — JavaScript는 프로세스 수준의 격리를 위해 isolated-vm에서 실행되며, Python은 서브프로세스 (subprocess)를 통해 실행됩니다.
6. 멀티 세션 관리 — 영구 저장소 및 자동 압축 (150턴 / 100k 토큰) 기능을 갖춘 독립적인 세션.
7. 데스크톱 모드 — Electron 창이 WebSocket (포트 9527)을 통해 터미널 에이전트와 통신합니다.
8. MCP 프로토콜 — 다른 AI 클라이언트와의 통합을 위해 모든 도구를 MCP 서버 (포트 3001의 JSON-RPC 2.0)로 노출합니다.
9. 플러그인 시스템 — 사용자 정의 도구 플러그인을 동적으로 로드합니다.
10. 사고 체인 시각화 (Thought chain visualization) — 추론 과정과 도구 실행을 실시간으로 시각화합니다.
11. 에이전트 클러스터 (Agent cluster) — 서브 에이전트 생성, 작업 위임 및 멀티 에이전트 협업.
12. WeChat 통합 — QR 로그인, 메시지 송수신, 전용 세션 제공 (iLink 프로토콜을 통해 제공, 선택 사항).

아키텍처: 사고 루프 (Think Loop) + 상태 머신 (State Machine) + 레지스트리 (Registry)

CogitoAgent를 이해하는 가장 깔끔한 방법은 세 가지 핵심 구성 요소를 통하는 것입니다.

1. 사고 루프 (Agent.ts)

이것이 에이전트를

도구 호출 (Tool calls)은 커스텀 [TOOL] functionName(args) [/TOOL] 태그 형식을 통해 표현되며, tool-parser.ts에 의해 파싱됩니다. 네이티브 함수 호출 (Native function calling) 방식과 비교했을 때 이 접근 방식의 장점은 **모델 불가지론적 (Model-agnostic)**이라는 점입니다. 즉, 텍스트를 생성할 수 있는 모델이라면 어떤 모델이든 도구를 구동할 수 있으며, 이것이 CogitoAgent가 GPT, Claude 또는 모든 OpenAI 호환 제공업체와 함께 작동하는 이유입니다.

2. 상태 머신 (state.ts)

에이전트는 다음 세 가지 상태를 순환합니다:

• AWAITING_INPUT — 사용자 입력을 기다리는 중
• THINKING — 현재 추론 중
• AWAITING_CONFIRMATION — 사용자 승인을 기다리는 중 (위험한 작업의 경우)

AWAITING_CONFIRMATION 상태는 DANGEROUS_OPERATIONS 메커니즘과 쌍을 이룹니다. 파괴적인 작업 (파일 삭제, git push 등)은 실행 전 명시적인 사용자 확인을 요구합니다. 이것이 CogitoAgent가 자율성과 안전성 사이의 균형을 맞추는 방식입니다.

3. 도구 레지스트리 (registry.ts)

모든 도구는 단일 TOOL_REGISTRY에 등록되며, executeTool()에 의해 조회됩니다. 이를 중앙 집중화함으로써 다음과 같은 이점을 얻을 수 있습니다:

• 통계(Stats)를 통한 관측 가능성 (Observability) — stats.ts가 카테고리별 도구 호출 횟수와 성공률을 추적합니다.
• 트레이싱 (Tracing) — tracing.ts가 실행 시간을 포함한 도구 실행 이벤트를 기록합니다.
• 통합된 확장성 (Unified extensibility) — 플러그인 (plugin.ts)과 MCP (mcp.ts) 모두 동일한 레지스트리에 주입되며, 메인 루프는 그 출처를 알 필요가 없습니다.

도구 시스템: 28개 모듈에 걸친 200개 이상의 도구

이 프로젝트에서 가장 비중이 큰 부분입니다. 모듈의 샘플은 다음과 같습니다:

핵심 요약 (The takeaway): CogitoAgent는 단순한 "코딩 에이전트 (coding agent)"가 아닙니다. 이 에이전트는 과학 계산 (생물정보학 (bioinformatics), 분자량 (molecular weight), 의료 공식 (medical formulas)), 지리 공간 처리 (geospatial processing), 금융 계산 (financial calculations), 문서 생성 (document generation), 브라우저 자동화 (browser automation) 등을 단일 레지스트리 (registry)에 통합합니다. 연구자, 분석가, 그리고 사무 자동화 (office-automation)를 시도하는 사용자들에게 이러한 폭넓은 기능은 단순한 코드 생성 능력보다 더 중요할 때가 많습니다.

도구 세트 확장하기 (Extending the tool set)

• 플러그인 시스템 (Plugin system) (plugin.ts) — 커스텀 도구 플러그인을 동적으로 로드합니다. 저장소의 plugins/ 디렉토리에는 세 가지 예시 플러그인이 포함되어 있습니다: biopython-bio, pubmed-research, rdkit-chem (생물정보학 (bioinformatics) / 문헌 검색 (literature search) / 화학 정보학 (cheminformatics)).
• MCP 프로토콜 (MCP protocol) (mcp.ts) — 200개 이상의 모든 도구를 MCP 서버 (MCP Server)로 노출하여, MCP 호환 AI 클라이언트가 CogitoAgent의 도구 생태계를 재사용할 수 있도록 합니다.

멀티 에이전트 클러스터 (Multi-Agent Cluster): "한 명의 조력자"에서 "하나의 팀"으로

가장 흥미로운 기능 중 하나입니다. orchestrator.ts와 cluster.ts를 통해 메인 에이전트는 다음과 같은 작업을 수행할 수 있습니다:

• /spawn <persona> <name> <instruction> — 주어진 페르소나 (persona)를 가진 하위 에이전트 (sub-agent) 생성
• /delegate <agentId> <task> — 하위 에이전트에게 작업 위임
• parallelExecute — 하위 에이전트들을 병렬로 실행
• pipeline — 하위 에이전트들을 순차적인 파이프라인 (pipeline)으로 연결
• voting / panelDiscussion — 투표 (voting) 또는 라운드 테이블 (round-table) 의사결정 패턴

하위 에이전트의 상태 전이 (state transitions)는 표준화되어 있습니다:

idle → thinking → tool_executing → thinking → ... → done
  ↓                                                    ↓
  └────────────────── error ←──────────────────────────┘

전용 모니터 패널 (별도의 Electron 창, 16:9 레이아웃)은 세 가지 실시간 시각화 기능을 제공합니다:

1. 사고 체인 (Thought Chain) — 매개변수(parameters), 상태, 소요 시간과 함께 실시간으로 진행되는 추론 단계.
2. 도구 통계 (Tool Statistics) — 카테고리별 호출 횟수와 성공률을 나타내는 ECharts 막대 그래프; 색상 강도로 성공률을 인코딩합니다.
3. 클러스터 토폴로지 (Cluster Topology) — 메인 에이전트가 중앙에 있고 그 주변에 서브 에이전트들이 배치된 Canvas 렌더링 링 토폴로지; 활성화된 노드는 맥동(pulse)합니다.

이는 단순히 작업을 위임하는 것을 넘어, 에이전트가 작업하는 모습을 지켜볼 수 있음을 의미하며, 이는 멀티 에이전트(multi-agent) 동작을 디버깅하고 에이전트 관측성(observability)을 연구하는 데 진정으로 유용합니다.

show

페르소나 시스템: 프로그래머, 의사, 방랑 기사...

CogitoAgent는 personas/ 디렉토리에 두 가지 계열로 나뉜 20개 이상의 사전 설정된 페르소나(persona)를 포함하고 있습니다:

• 현대적 전문 역할 — 프로그래머 (Programmer), 의사 (Doctor), 생물학자 (Biologist), 화학자 (Chemist), 계산 과학자 (Computational-Scientist), 학자 (Scholar), 탐정 (Detective), 심리학자 (Psychologist), 교사 (Teacher), 요리사 (Chef), 화가 (Painter), 전략가 (Strategist), 상인 (Merchant)...
• 역사적 / 지역적 역할 — 방랑 기사 (Knight-Errant), 제국 비평가 (Imperial-Critic), 관리 (Scholar-Official), 몽골 청년 (Mongolian-Youth), 산베이 청년 (Shaanbei-Youth), 티베트 청년 (Tibetan-Youth), 전사 (Warrior), 그림자 호위무사 (Shadow-Guard), 은둔자 (Hermit)...

페르소나는 system-prompt.ts를 통해 로드되며 /persona <name> 명령어로 핫스왑(hot-swap)할 수 있습니다. 각 페르소나는 고유의 persona.md 파일을 가지며, 일부는 초상화 이미지를 포함합니다.

클러스터 기능과 결합하면, 문헌 검토를 위한 학자(Scholar) 서브 에이전트, 코드 작성을 위한 프로그래머(Programmer) 서브 에이전트, 그리고 이를 검토하기 위한 비평가(Critic) 서브 에이전트를 생성하여, 서로 다른 "성격"을 가진 에이전트들이 작업의 각 부분을 담당하게 할 수 있습니다.

세 가지 사용 모드

빠른 시작 (Quick Start)

요구 사항: Node.js ≥ 22.12, npm 또는 yarn, Python 3.x (선택 사항, Python 코드 실행용).

git clone https://github.com/SnowLeopard-io/CogitoAgent.git
cd CogitoAgent
npm install
...

첫 실행 시 다음 다섯 가지를 요구합니다:

1. API base URL — OpenAI 호환 엔드포인트(endpoint)라면 무엇이든 가능
2. API key — 사용자의 키
3. Model name — 예: gpt-4o, claude-3-sonnet
4. Workspace path — 에이전트가 접근할 수 있는 디렉토리 (홈 디렉토리가 아닌 전용 폴더를 사용하세요)
5. Persona — 사전 설정된 역할(preset role) 중 선택

Docker 한 줄 명령어로도 실행 가능합니다:

docker-compose up -d

중국 사용자 참고 사항: 만약 npm install 과정에서 Electron 바이너리를 가져오는 데 실패한다면, 설치 전에 ELECTRON_MIRROR=https://npmmirror.com/mirrors/electron/를 설정하세요. 더 빠른 클로닝(cloning)을 위해 Gitee 미러도 사용할 수 있습니다: https://gitee.com/cnt-code/cogito-agent

유용한 명령어

안전 팁: 항상

• v2.3.2 (2025-07) — 전체 TypeScript 마이그레이션 (full TypeScript migration); 6개의 새로운 전문 모듈 (GIS, Bio, Med, Chem, Finance, Math); CI/CD 파이프라인.
• v2.3.1 — QR 로그인 및 메시징을 포함한 WeChat iLink 프로토콜 통합.
• v2.3.0 — 멀티 세션 (multi-session), 샌드박스 (sandbox) 업그레이드, MCP 프로토콜, 플러그인 시스템, OCR/비전 (vision), 사고 체인 (thought-chain) 시각화.

다음 예정 사항:

• 로컬 LLM 지원 (Ollama / LM Studio — API 키 불필요)
• VS Code 확장 프로그램 및 MCP 클라이언트 (Client) 모드 (외부 MCP 서버에 연결)
• 로컬 벡터 데이터베이스 (vector DB)를 통한 장기 기억 (Long-term memory), 그리고 예약된 자율 작업 (scheduled autonomous tasks)
• 장기 계획: 모바일 컴패니언 앱, 플러그인 마켓플레이스, 엔터프라이즈 기능 (RBAC, 감사, SSO)