Agent 개요
Agent는 Elftia의 핵심 기능 중 하나입니다. AI가 단순히 질문에 수동적으로 답하는 것을 넘어 능동적으로 작업을 실행하는 능력을 갖추게 합니다 — 파일 읽기/쓰기, 명령 실행, 웹 검색, 외부 도구 호출, 심지어 여러 하위 Agent를 병렬로 조율하는 것까지 가능합니다.
Agent란 무엇인가
전통적인 채팅에서 AI는 텍스트만 출력할 수 있습니다. Agent 모드에서 AI는 다음을 수행할 수 있습니다:
- 작업 분석 — 요청을 이해하고 실행 계획 수립
- 도구 호출 — 파일 읽기, 코드 편집, 명령 실행
- 반복 개선 — 결과 확인, 오류 수정, 실행 계속
- 결과 반환 — 작업 완료 후 최종 응답 제공
이 "생각 → 행동 → 관찰 → 재생각"의 순환을 Agent 루프(Agent Loop)라고 합니다.
사용자 메시지 → 엔진 배분 → LLM 사고 → 도구 호출 → 결과 관찰 → 루프 계속 또는 응답 반환
↑ ↓
└───────────────────────────────────────────┘
다중 엔진 아키텍처
Elftia는 여러 Agent 엔진을 지원하며, 각 엔진은 서로 다른 시나리오에 적합합니다:
| 엔진 유형 | ID | 설명 | 적합한 시나리오 |
|---|---|---|---|
| TinyElf | tinyelf | Elftia 내장 경량 Agent 엔진 | 일상적인 코딩, 파일 작업, 자동화 작업 |
| Claude SDK | claude-sdk | Anthropic 공식 Agent SDK 기반 | Claude 네이티브 툴체인이 필요한 시나리오 |
| CLI Runner | cli | 외부 커맨드라인 도구 (Claude Code, Codex) | 외부 CLI Agent 사용 |
| Chat | chat | 순수 채팅 엔진 (도구 호출 없음) | 간단한 Q&A, 번역, 글쓰기 |
| STChat | st-chat | 단일 턴 대화 엔진 | 빠른 단일 턴 작업 |
| API | api | 경량 API 호출 | 미디어 생성 등 비채팅 시나리오 |
TinyElf 엔진
TinyElf는 Elftia의 기본 Agent 엔진으로, 다음과 같은 특징이 있습니다:
- 프로세스 내 실행 — 하위 프로세스나 프록시 서버를 시작할 필요 없이 빠르게 시작
- 다중 LLM 지원 — TinyElfLLMAdapter를 통해 모든 LLM 제공업체에 적응
- 내장 툴체인 — 파일 읽기/쓰기, Shell 명령, 웹 검색, MCP 도구
- 하위 Agent 협업 — 전경 및 배경 하위 Agent 병렬 실행 지원
- Skill 시스템 — 재사용 가능한 SKILL.md 스킬 지침 로드 가능
- 보안 제어 — 3계층 보안 (방화벽 + 가디언 Agent + 권한 확인)
Claude SDK 엔진
@anthropic-ai/claude-agent-sdk 기반으로, Claude의 네이티브 기능이 필요한 시나리오에 적합합니다:
- Claude의 공식 사전 설정 시스템 프롬프트 및 도구 사용
- 비 Anthropic 제공업체 지원 (형식 변환을 위한 내장 프록시 서버 활용)
- 다중 API 키 부하 분산
CLI Runner 엔진
ProcessSupervisor를 통해 외부 CLI 도구 프로세스를 관리합니다:
- Claude Code CLI 및 Codex CLI 지원
- PTY 터미널 모드 및 표준 하위 프로세스 모드
- 자동 타임아웃 처리 및 출력 파싱
핵심 기능
도구 호출
Agent는 다양한 도구를 사용하여 작업을 완료할 수 있습니다:
| 도구 카테고리 | 도구 | 설명 |
|---|---|---|
| 파일 시스템 | Read, Write, Edit, ListDir, Glob, Grep | 프로젝트 파일 읽기, 쓰기, 검색 |
| Shell | Bash | 터미널 명령 실행 |
| 웹 | WebSearch, WebFetch | 웹 콘텐츠 검색 및 가져오기 |
| 하위 Agent | spawn_agent | 하위 작업 처리를 위한 하위 Agent 시작 |
| 세션 관리 | SessionsSpawn, SessionsList, SessionsSend | 세션 간 협업 |
| Skills | list_skills, read_skill | 스킬 콘텐츠 조회 및 읽기 |
| MCP | mcp__* (동적 로드) | 외부 MCP 서버 도구 |
| 제어 | Notify, SessionsYield | 알림 및 흐름 제어 |
하위 Agent 협업
Agent는 하위 Agent를 시작하여 하위 작업을 병렬로 처리할 수 있습니다:
- 전경 하위 Agent — 블로킹하며 결과를 기다려 부모 Agent에 직접 반환
- 배경 하위 Agent — 백그라운드에서 비동기적으로 실행; 완료 시 결과가 부모 루프에 주입
- Agent 구성 상속 — 하위 Agent는 부모 Agent의 MCP 도구 및 스킬 상속 가능
- 보안 상속 — 하위 Agent는 부모 Agent의 보안 설정 및 권한 모드 상속
Skill 시스템
Skill(스킬)은 SKILL.md 파일로 존재하는 재사용 가능한 지침 세트입니다:
- 프로젝트 스킬 —
.claude/skills/에 배치, 프로젝트 내에서 공유 - 개인 스킬 —
~/.claude/skills/에 배치, 전역으로 사용 가능 - 커뮤니티 스킬 — SkillHub를 통해 검색 및 설치
Agent 갤러리
Elftia에는 다양한 시나리오를 커버하는 사전 구성된 Agent가 내장되어 있습니다:
- 프로그래밍 어시스턴트, 코드 리뷰, 테스트 작성
- 문서 작성, 번역 및 교정
- 리서치 분석, 데이터 처리
- 작업 자동화, 워크플로 오케스트레이션
Agents 페이지: 단층 평면 모델
버전 0.1.7에서 2단계 병합을 완료했습니다 — 더 이상 "Persona / Avatar / Agent 3계층 구조"가 없습니다. 모든 agent는 Agents 페이지 (
/agents)의 단일 그리드에서 관리됩니다.
하나의 agent = 하나의 독립적인 대화 대상
페이지 레이아웃:
- 왼쪽 카테고리 바: 13개 카테고리 (Featured, My, Work, Coding, Creative, Research, Writing, Life, Education, Entertainment, Social, Automation, Tools)
- 상단 검색: agent 이름 / 설명 / 태그로 검색
- 오른쪽 그리드: 모든 내장 + 사용자 정의 agent 카드
내장 agent
- Clawia — 범용 Agent, 주요 대화 진입점
- Cocoia — 예약 작업 전용
- Canvas — 시각적 프로토타이핑
- ClaudeCode — 코드 개발
- Design Studio — 디자인 워크벤치
- Artia — 창작 어시스턴트
- 동적으로 로드되는 datia 클래스 패키지: Deep Research, Visual Layout, Novel Writer 등
기반 미디어 생성 agent (Chat / Image / Video / Music)는 시스템에 남아 있으며 전용 패널 진입점을 통해 호출됩니다; Agents 페이지에 개별적으로 노출되지 않습니다.
데이터 마이그레이션 참고 사항
기반 데이터 마이그레이션은 업그레이드 시 자동으로 수행됩니다:
- v82 (0.1.7, 1단계): 평면 agent 모델로 복귀; Codia 아래에 있던 Canvas / ClaudeCode가 독립적인 최상위 agent로 분리
- v87 (0.1.7, 2단계): 기반 Persona 및 Agent 테이블을 단일 agent 테이블로 병합, 데이터 모델 단순화
이전 세션은 완전히 보존됩니다: 이전에 Codia 아래에 있던 세션은 이제 사용한 agent 아래에 독립적으로 나열됩니다; 이전 메시지는 손실되지 않습니다. 롤백이 필요한 경우, 지원팀이 <userData>/migrations/의 스냅샷 파일을 사용하여 복원할 수 있습니다.
빠른 시작
내장 Agent 사용하기
- Agent 패널 열기 (사이드바의 Agent 아이콘)
- Agent 갤러리를 탐색하여 적합한 Agent 선택
- 대화 시작 — Agent가 필요한 도구를 자동으로 호출
사용자 정의 Agent 만들기
- Agent 패널에서 "Agent 만들기" 클릭
- 이름, 설명, 시스템 프롬프트 설정
- 사용 가능한 도구 및 권한 모드 선택
- 저장 후 사용 시작
자세한 단계는 사용자 정의 Agent 만들기를 참조하세요.
자주 묻는 질문
| 문제 | 원인 | 해결 방법 |
|---|---|---|
| Agent가 도구를 실행할 수 없음 | 엔진 유형이 chat (도구 지원 없음) | tinyelf 또는 claude-sdk 엔진으로 전환 |
| 도구 실행 시 자주 확인 요청 | 권한 모드가 default | acceptEdits 또는 bypassPermissions로 설정 |
| Agent 루프가 너무 빨리 중단 | maxIterations가 너무 낮게 설정됨 | 최대 반복 횟수 증가 (기본값: 40) |
| MCP 도구가 나타나지 않음 | MCP 서버가 연결되지 않음 | Agent 구성에서 MCP 서버 추가 |
| 하위 Agent 실행 실패 | 하위 Agent 구성 파일이 유효하지 않음 | .claude/agents/*.md 형식 확인 |
관련 링크
- 내장 Agent — 사전 설정 Agent 탐색 및 사용
- 사용자 정의 Agent 만들기 — 자신만의 Agent 구성 작성
- 도구 권한 및 보안 — 권한 모드 및 보안 설정
- Skill 시스템 — 스킬 사용 및 만들기