커스텀 Agent 만들기

AI4PKM Orchestrator에서 자신만의 에이전트를 만들고 설정하는 가이드입니다.

에이전트 개요

에이전트는 특정 작업을 자동으로 수행하는 AI 기반 워커입니다.

구성 요소

에이전트 = 프롬프트 파일 + Orchestrator 설정

1. 프롬프트 파일 (_Settings_/Prompts/*.md)
   - 에이전트가 무엇을 할지 정의

2. Orchestrator 설정 (orchestrator.yaml)
   - 언제, 어떻게 실행할지 정의

생성 절차

1. 아이디어 구상
   ↓
2. 프롬프트 파일 작성
   ↓
3. orchestrator.yaml에 노드 추가
   ↓
4. 테스트 실행
   ↓
5. 프로덕션 배포 (enabled: true)

프롬프트 파일 작성

파일 위치

VaultName/
└── _Settings_/
    └── Prompts/
        └── Your Agent Name (YAN).md

기본 구조

---
title: Your Agent Name
abbreviation: YAN
category: learning|publishing|automation|analysis
description: 간단한 설명 (1문장)
version: 1.0
---

# Your Agent Name

에이전트의 목적을 1-2문장으로 설명합니다.

## Input
- Source: input/path/*.md
- 입력 파일 형식 및 요구사항

## Output
- File: output/path/{{filename}}_result.md
- 출력 파일 형식 및 내용

## Main Process
1. 단계 1
   - 세부 작업 1-1
   - 세부 작업 1-2

2. 단계 2
   - 세부 작업 2-1

## Output Format
[출력 예시 템플릿]

## Important Notes
1. 주의사항 1
2. 주의사항 2

Front Matter 필드

orchestrator.yaml 설정

기본 노드 구조

nodes:
  - type: agent
    name: Your Agent Name (YAN)
    abbreviation: yan
    executor: claude_code
    input_path: input/folder
    output_path: output/folder
    enabled: true

필수 필드

선택 필드

입력 경로 설정

# 단일 경로
input_path: Documents

# 여러 경로
input_path:
  - Documents
  - Projects
  - Research

# 하위 폴더 포함
input_path: Projects/**

고급 트리거 조건

파일 패턴 필터

# 특정 확장자만
input_pattern: "*.md"

# 복수 패턴
input_pattern: "*.{md,txt}"

# 제외 패턴
exclude_pattern: "*_processed.md"

내용 기반 트리거

# 특정 마커가 있을 때만 실행
trigger_content_pattern: "%% #ai-research %%"

# 처리 후 마커 제거
post_process_action: remove_trigger_content

시간 기반 조건

# 최근 24시간 이내 파일만
trigger_max_age_hours: 24

# 7일 이상 된 파일만
trigger_min_age_hours: 168

크기 기반 조건

# 100KB 이상만
trigger_min_size_kb: 100

# 10MB 이하만
trigger_max_size_kb: 10000

Cron 스케줄

# 매일 오전 9시
cron: "0 9 * * *"

# 매주 월요일 오전 9시
cron: "0 9 * * 1"

# 매월 1일 자정
cron: "0 0 1 * *"

복합 조건 예시

nodes:
  - type: agent
    name: AI Research Analyzer
    abbreviation: ara
    executor: claude_code
    input_path: Research

    # 파일 필터
    input_pattern: "*.md"
    exclude_pattern: "*_analyzed.md"

    # 내용 기반
    trigger_content_pattern: "%% #ai-research %%"

    # 조건
    trigger_min_size_kb: 50
    trigger_max_age_hours: 72

    # 후처리
    post_process_action: remove_trigger_content

    # 성능
    max_parallel: 1
    task_priority: high
    timeout_minutes: 30

    output_path: Research/Analyzed
    output_type: new_file
    enabled: true

테스트 및 디버깅

상태 확인

# Orchestrator 상태
ai4pkm --orchestrator-status

# 에이전트 목록
ai4pkm --list-agents

# 설정 검증
ai4pkm --show-config

수동 테스트

# 에이전트 대화형 트리거
ai4pkm -t

# 에이전트 약어로 직접 실행
ai4pkm YAN

로그 확인

# 실시간 로그
tail -f _Settings_/Logs/orchestrator.log

# 특정 실행 로그
cat _Settings_/Logs/2025-12-24-153805-YAN.log

일반적인 문제

워크플로우 체인

여러 에이전트를 연결하여 자동화 파이프라인을 구축할 수 있습니다.

순차 체인

nodes:
  # 1단계: 정리
  - type: agent
    name: Cleaner
    input_path: 00-Inbox
    output_path: 01-Cleaned

  # 2단계: 강화
  - type: agent
    name: Enricher
    input_path: 01-Cleaned
    output_path: 02-Enriched

  # 3단계: 발행
  - type: agent
    name: Publisher
    input_path: 02-Enriched
    output_path: 03-Published

동작:

1. 00-Inbox/article.md 저장
2. Cleaner → 01-Cleaned/article.md 생성
3. Enricher → 02-Enriched/article.md 생성
4. Publisher → 03-Published/article.md 생성

분기 체인

nodes:
  # 공통 처리
  - type: agent
    name: Processor
    input_path: Inbox
    output_path: Processed

  # 분기 A: 요약
  - type: agent
    name: Summarizer
    input_path: Processed
    output_path: Summaries

  # 분기 B: 번역
  - type: agent
    name: Translator
    input_path: Processed
    output_path: Translated

무한 루프 방지

# 방법 1: 입출력 경로 분리
input_path: Documents
output_path: Documents/Processed

# 방법 2: 제외 패턴 사용
exclude_pattern: "*_processed.md"

# 방법 3: 트리거 마커 사용
trigger_content_pattern: "%% #process %%"
post_process_action: remove_trigger_content

Best Practices

단일 책임 원칙

# 좋은 예: 한 가지 작업
- name: SNS  # 학습 노트 요약만
- name: EIC  # 웹 클리핑 정리만

# 나쁜 예: 너무 많은 작업
- name: MegaAgent  # 정리 + 요약 + 발행 + 태그

명확한 입출력 분리

# 좋은 예
input_path: vl_ai4pkm_clippings    # 원본
output_path: vl_ai4pkm_materials   # 결과

# 나쁜 예
input_path: Documents
output_path: Documents  # 혼란 가능

점진적 배포

# 1. 처음에 비활성화로 테스트
enabled: false

# 2. 수동 테스트 후 활성화
enabled: true

참조

• (0) Orchestrator 개요 - 시스템 아키텍처
• (4) Orchestrator 설정 - 설정 파일 가이드
• (5) CLI 명령어 가이드 - CLI 명령어
• (1) Poller 시스템 가이드 - 외부 데이터 연동

학습 경로