로컬 AI 에이전트의 파일 액세스: 도구

로컬 AI 에이전트 파일 접근: 도구와 버그 수정

우리 로컬 AI 에이전트 Doka가 이제 파일 접근 기능을 갖췄습니다. 하지만 llama.cpp의 치명적인 KV-캐시 버그를 먼저 수정해야 했죠. 시스템 프롬프트가 Session started: ${new Date().toISOString()}으로 시작해 매 반복마다 바뀌었습니다. 이로 인해 전체 캐시가 무효화되어 모델이 10회 반복 동안 2000개의 프롬프트 토큰을 처음부터 재계산하며 20,000개 토큰을 낭비했습니다.

타임스탬프를 프롬프트 끝이나 사용자 턴 끝으로 옮기자 캐시가 유지됐습니다. 8회 이상 반복되는 루프에서 다단계 작업 속도가 2~3배 빨라졌어요. 이 패턴은 Anthropic의 Claude 권장 사항과 비슷하지만, 로컬 모델에서도 필수입니다.

권한 게이트로 안전한 파일 접근

파일 읽기 도구는 간단하지만, 쓰기 기능에는 안전장치가 필요합니다. 도구 상자 안 각 도구에 dangerous 플래그가 있습니다:

const fileTools: Tool[] = [
  {
    name: 'read_file',
    dangerous: false,
  },
  {
    name: 'write_file',
    dangerous: true,
  },
  {
    name: 'edit_file',
    dangerous: true,
  },
  {
    name: 'delete_file',
    dangerous: true,
  },
];

위험한 도구가 호출되면 대화상자가 떠서 인수(경로와 내용의 처음 500자)를 보여줍니다. "허용" 버튼이 기본이 아닙니다. 거부 시 에이전트에 오류를 반환합니다:

{
  "error": "사용자가 write_file 권한을 거부했습니다",
  "canRetry": false,
  "suggestion": "사용자에게 의도한 파일 경로를 확인하라고 요청하세요"
}

완전한 파일 도구 세트

여섯 가지 도구를 구현했습니다:

• read_file(path: string): string
• write_file(path: string, content: string): void (위험)
• edit_file(path: string, instruction: string): void (위험)
• list_dir(path: string): FileEntry[]
• move_file(from: string, to: string): void (위험)
• delete_file(path: string): void (위험)

edit_file은 지시사항에 따라 패치를 적용합니다(읽기 → 패치 → 쓰기 → 검증). 대용량 파일을 컨텍스트로 전달하지 않아 효율적입니다.

경로 관련 오류 수정

에이전트가 상대 경로 때문에 같은 이름의 파일을 다른 디렉터리에서 혼동했습니다. 해결책:

• 시스템 프롬프트에 기본 작업 디렉터리 지정.
• 경로 유효성 검사: 범위를 벗어나면 오류 발생.
• 지시: 경로가 모호하면 사용자에게 물어보기.

이 버그는 테스트 3~4에서 드러났습니다: 에이전트가 대상 폴더 대신 루트의 notes.md를 선택했죠.

write_file이나 edit_file 후 자동 검증을 추가했습니다: 자동 read_file 확인. 단계가 늘지만 권한이나 디스크 문제로 인한 조용한 실패를 막습니다. MAX_TOOL_STEPS를 12로 늘려 계획 + 읽기 + 쓰기 + 검증을 지원합니다.

투명성을 위한 에이전트 타임라인

사용자들이 "블랙박스"를 불평했습니다: 3분 대기 중 단계가 보이지 않았죠. 사이드바 로그를 추가했습니다:

• 도구 호출과 인수.
• 결과.
• 타임스탬프.

이벤트 스트림(tool_call_start / tool_call_end)이 React에서 실시간으로 렌더링됩니다. 파일 접근에서 필수: 사용자가 정확한 경로와 작업을 확인할 수 있습니다.

구조화된 오류와 재시도 로직

이전에는 Node.js 스택 트레이스가 쏟아져 무한 재시도나 환각이 발생했습니다. 이제 구조화됐습니다:

{
  "error": "파일을 찾을 수 없습니다: /path/to/file.md",
  "canRetry": false,
  "suggestion": "먼저 list_dir로 경로를 확인하세요"
}

canRetry로 무의미한 루프를 줄입니다. 네트워크 타임아웃은 true, 존재하지 않는 파일은 false입니다.

재구성된 시스템 프롬프트

시스템 프롬프트를 섹션으로 나눴습니다:

• 역할과 경계: 기능과 제한.
• 우선순위 규칙: 안전 > 정확성 > 속도.
• 응답 형식: 유형별 구조.
• Few-shot 예시: 엣지 케이스 추론.

이 구조로 긴 체인에서 환각, 특히 규칙 기반 거부를 줄였습니다.

계획 단계: 생각 → 계획 → 실행

도구 전에 지시:

도구 사용 전에 짧은 계획을 작성하세요:
THINK: [어떤 정보가 필요한가?]
PLAN: [단계 1 → 단계 2 → 단계 3]
ACT: [계획 실행]

중복 도구 호출을 반으로 줄입니다. 행동 전에 목표 설정을 강제합니다.

주요 요약

• 동적 데이터(타임스탬프)를 프롬프트 끝으로 옮기면 KV-캐시로 루프가 2~3배 빨라집니다.
• 대화상자와 구조화 오류로 쓰기 위험 최소화.
• 자동 검증과 경로 유효성으로 조용한 파일 작업 실패 제거.
• 에이전트 타임라인으로 파일 접근 단계 투명성 확보.
• 계획 포함 구조화 프롬프트로 다단계 작업 신뢰성 향상.

— Editorial Team