Orchestrator 개요

Core Beliefs

Orchestrator가 기반하는 핵심 원칙들:

1. 마크다운 중심의 지식관리: 마크다운 파일은 AI가 이해하고 처리하기에 가장 적합한 포맷이다. 모든 지식은 마크다운으로 변환하여 저장 및 관리한다.

2. 코딩 에이전트의 지식 적용: 코딩 에이전트는 파일 시스템 기반에 최적화되어 있고, 코드베이스의 semantical한 구조는 일반적으로 우리가 지식을 관리하는 방식과 유사하다. 따라서 코딩 에이전트를 파일 시스템 기반 지식 베이스에 적용하면 효율적인 지식 관리가 가능해진다.

3. 이벤트 기반 자동화: 지식 근로자들이 물리적 파일을 주고받으며 협업하는 것을 모티브로 하여, cron expression과 OS의 파일 시스템 이벤트(생성, 수정, 삭제)에 기반하여 지식 업무의 자동화를 구현한다.

Components

Orchestrator를 구성하는 핵심 컴포넌트들. 설정은 orchestrator.yaml에서 관리 ((4) Orchestrator 설정 참조).

• Raw Data = 내 지식관리의 근간이 되는 모든 데이터 (마크다운 포맷)
• Skills & Prompts = 내 지식관리의 자동화 코드 및 매뉴얼
• Agent & Task = 프롬프트를 수행하는 주체, 그리고 프롬프트 수행 상황을 요약하는 문서
• Orchestrator = Config에 따라 Agent를 실행 및 관리하며, 유저와의 인터랙션 포인트

flowchart LR
    RD[Raw Data] --> O[Orchestrator]
    SP[Skills & Prompts] --> O
    O --> AT[Agent & Task]
    AT --> RD

Vault

Obsidian으로부터 계승한 컨셉. 지식 데이터(Raw Data)와 자동화 설정 파일(Skills & Prompts)이 저장되는 공간.

Orchestrator

Vault와 Agent들을 관장하는 최상위 시스템.

• 태스크 생성, 실행, 관리
• 유저와의 인터랙션
  • 지식 데이터에 대한 QnA
  • Agent를 이용한 복잡한 작업 실행
  • 기본 LLM과의 가벼운 소통

Agent

작업을 수행하는 실행 주체. 다음 요소들로 정의됨:

Task

Agent가 작업을 수행할 때 생성되는 .md 파일. Input, Output, 작업 상황이 기록됨.

아키텍처 개요

flowchart TB
    subgraph Core["Orchestrator Core"]
        EM[Execution Manager]
        AR[Agent Registry]
        TM[Task Manager]
    end

    subgraph Triggers["Event Triggers"]
        FSM[File System Monitor]
        CRON[Cron Scheduler]
        POL[Pollers]
    end

    subgraph Execution["Execution Layer"]
        CC[Claude Code]
        GEM[Gemini CLI]
    end

    Triggers --> Core
    Core --> Execution

핵심 컴포넌트:

• Orchestrator Core: 이벤트 감지 및 Agent 자동 실행
• Event Triggers: 파일 감시, Cron 스케줄, 외부 데이터 폴링
• Execution Layer: Claude Code, Gemini CLI 등 실제 작업 수행

핵심 설정값 이해

orchestrator.yaml의 주요 설정에 대한 개념적 이해입니다.

max_concurrent vs max_parallel

# 예: max_concurrent=3, max_parallel=2인 경우
# Agent A가 2개 Task 실행 중이면, 다른 Agent는 최대 1개만 실행 가능

task_create 설정

poll_interval 권장값

Workflow

Orchestrator가 Trigger를 감지하면 다음 순서로 실행:

1. Task.md 파일을 Tasks 폴더에 생성
2. Trigger에 매칭하는 Agent를 spawn하여 프롬프트 구성 및 실행
   • 시스템 프롬프트 + 에이전트 프롬프트 본문
   • Trigger 컨텍스트 (Event, Input Path, Task File)
   • Output 컨텍스트 (Output Directory, Output Type)

sequenceDiagram
    participant T as Trigger
    participant O as Orchestrator
    participant A as Agent
    participant TK as Task

    T->>O: 이벤트 발생
    O->>TK: Task.md 생성
    O->>A: Agent spawn
    A->>A: 프롬프트 실행
    A->>TK: 결과 업데이트

CLI 구조

AI4PKM CLI는 Python 패키지로 구현되어 있으며, Orchestrator 중심 아키텍처를 따릅니다.

핵심 모듈

ai4pkm_cli/
├── main/                    # CLI 진입점
│   ├── cli.py               # 메인 명령어
│   ├── orchestrator.py      # orchestrator run/stop/status
│   └── trigger_agent.py     # 수동 에이전트 실행
│
├── orchestrator/            # 핵심 로직
│   ├── core.py              # Orchestrator 메인
│   ├── agent_registry.py    # 에이전트 등록/매칭
│   ├── execution_manager.py # 실행 관리
│   ├── file_monitor.py      # 파일 감시 (watchdog)
│   ├── task_manager.py      # Task 파일 관리
│   ├── cron_scheduler.py    # Cron 스케줄링
│   └── poller_manager.py    # 외부 데이터 폴링
│
└── pollers/                 # 외부 소스 연동
    ├── gobi.py              # Gobi 앱
    ├── limitless.py         # Limitless AI
    └── apple_photos.py      # Apple Photos

모듈별 역할

실행 흐름 상세

1. Orchestrator 시작

ai4pkm -o

시작 시 다음이 초기화됩니다:

• orchestrator.yaml 로드 및 검증
• AgentRegistry에 에이전트 등록
• FileMonitor로 input_path 폴더 감시 시작
• CronScheduler로 스케줄 에이전트 등록
• PollerManager로 외부 폴러 시작

2. 파일 이벤트 처리

flowchart LR
    subgraph 감지
        F[파일 생성/수정]
        FM[FileMonitor]
    end

    subgraph 매칭
        AR[AgentRegistry]
        AG[Agent 선택]
    end

    subgraph 실행
        TM[Task 생성]
        EM[Executor 실행]
        R[결과 저장]
    end

    F --> FM --> AR --> AG --> TM --> EM --> R

3. Poller 연동

외부 앱 → Poller → 파일 생성 → FileMonitor → Agent 실행

Gobi 앱 → GobiPoller → _Inbox_/*.md → EIC Agent → AI/Articles/

상세 설정은 (4) Orchestrator 설정 참조

참조

• (4) Orchestrator 설정 - 상세 설정 방법
• 용어 사전 - 용어 정의

학습 경로