AIClaw, 이제 실제로 다운로드 가능한 도구 출력 첨부 파일을 반환합니다

AIClaw는 이미 에이전트가 도구 (tools)를 실행하고, 파일을 생성하며, 단계별로 작업을 계속할 수 있도록 지원해 왔습니다. 약점은 사용자에게 다시 전달되는 과정이었습니다. 도구가 보고서, 이미지 또는 데이터 파일을 생성할 수는 있었지만, 최종 답변이 항상 해당 출력을 명확하게 보여주거나 직접 다운로드할 수 있게 만들지는 못했습니다.

최근의 AIClaw 변경 사항은 해당 워크플로우 (workflow)를 강화했습니다. 이제 도구로 생성된 파일들이 수집되고, 중복이 제거되며, API 응답 및 스트리밍 완료 청크 (streaming completion chunks)에 노출됩니다. 또한 최종 어시스턴트 메시지에 연결되며, 채팅 UI를 통해 안정적인 /public/files/<uuid> 다운로드 URL로 렌더링됩니다.

이는 단순한 외관상의 변경이 아닙니다. 도구 실행과 사용자에게 보이는 결과 사이의 루프 (loop)를 완성하는 것입니다.

문제점

도구를 사용하는 에이전트 시스템에서 "파일을 생성했습니다"라는 말만으로는 충분하지 않습니다. 사용자는 다음과 같은 작업이 필요합니다:

파일이 생성되었다는 사실을 인지
해당 파일이 어떤 최종 답변에 속하는지 확인
로그를 뒤지지 않고도 파일을 다운로드
해당 파일을 대화 기록과 연관된 상태로 유지

이러한 기능이 없다면, 특히 에이전트가 여러 도구를 사용하거나 하위 에이전트 (sub-agents)에게 작업을 위임할 때 생성된 결과물 (artifacts)을 잃어버리기 쉽습니다.

AIClaw에서 변경된 사항

최근의 첨부 파일 작업은 백엔드 (backend)와 프론트엔드 (frontend) 전반에 걸쳐 확인할 수 있습니다.

실행 측면에서 AIClaw는 이제 다음과 같은 작업을 수행합니다:

도구에 의해 반환된 파일 출력을 수집
도구가 파일 결과를 명시적으로 반환하지 않을 경우, 샌드박스 (sandbox) 디렉토리를 스캔하여 새로 생성된 파일을 탐색
sub_agent 결과에서 생성된 파일을 다시 추출
최종 응답이 저장되거나 스트리밍되기 전에 첨부 파일을 중복 제거

도구 실행 경로에서 이를 확인할 수 있습니다:

이제 최종 어시스턴트 응답에는 다음과 같은 Markdown 링크가 포함된 첨부 파일 섹션이 추가됩니다:

첨부 파일 목록 (Attachment List):
- [report.csv](/public/files/<uuid>)
- [chart.png](/public/files/<uuid>)

현재 중국어 코드베이스 수정 버전에서는, 저장된 최종 콘텐츠 내 해당 섹션이 附件列表로 렌더링됩니다.

응답 페이로드 (payload)에는 파일이 직접 포함됩니다:

차단형 (blocking) 채팅 응답은 이제 files를 반환합니다.
스트리밍 (streaming) done 청크는 이제 files를 포함합니다.

해당 경로는 다음 파일들에서 확인할 수 있습니다:

프론트엔드 (frontend)에서는 채팅 뷰가 /public/files/${file.uuid}를 통해 해당 파일 객체들을 클릭 가능한 다운로드 링크로 변환합니다:

/Users/yu/go/src/github.com/chowyu12/aiclaw/web/src/views/chat/Index.vue

이것이 실무에서 중요한 이유

이 기능은 AIClaw 에이전트가 순수 텍스트 대신 결과물 (artifacts)을 생성하는 모든 곳에서 유용합니다.

예시:

code_interpreter 작업이 CSV와 PNG 차트를 생성하는 경우.
브라우저 자동화 (browser automation) 흐름이 스크린샷이나 추출된 문서를 저장하는 경우.
서브 에이전트 (sub-agent)가 연구 요약 파일을 작성하고 이를 상위 실행 (parent run)으로 다시 전달하는 경우.
셸 명령 (shell command)이 샌드박스 (sandbox) 내에서 로그 번들 또는 변환된 데이터셋을 생성하는 경우.

이러한 개선이 이루어지기 전에는 사용자들이 "파일이 어디로 갔지?"라고 묻는 상황이 발생하곤 했습니다.

이제 기대되는 워크플로우는 훨씬 더 깔끔합니다:

도구가 실행됩니다.
AIClaw가 출력 파일들을 캡처합니다.
최종 답변에 명시적인 다운로드 링크가 포함됩니다.
API와 스트리밍 완료 (streamed completion) 모두 파일 메타데이터를 전달합니다.
UI가 대화 결과의 일부로 첨부 파일을 렌더링합니다.

이는 AIClaw가 단순히 도구를 호출하는 텍스트 전용 챗봇(chatbot)이라기보다, 보다 실용적인 작업 시스템(work system)처럼 동작함을 의미합니다.

중요한 작은 디테일: 하위 에이전트(sub-agent) 출력

이번 변경 사항의 유용한 점 중 하나는 파일 출력이 최상위 에이전트(top-level agent)에 국한되지 않는다는 것입니다.

이제 실행기(executor)는 sub_agent 결과에서 파일 참조(file references)를 추출하여 이를 부모 응답(parent response)으로 다시 통합합니다. 이는 많은 실제 AIClaw 워크플로(workflows)가 조사(research), 스크래핑(scraping) 또는 데이터 준비(data prep)를 위임된 작업(delegated tasks)으로 분할하기 때문에 중요합니다. 만약 자식 아티팩트(child artifacts)가 부모 경계에서 사라진다면, 시스템은 신뢰할 수 없게 느껴집니다.

이러한 파일들을 부모 답변으로 다시 가져옴으로써, 중첩된 에이전트 실행(nested agent execution)을 훨씬 더 신뢰할 수 있게 만듭니다.

또 다른 실용적인 개선 사항: 더 나은 스트리밍(streaming) 동작

동일한 변경 세트는 채팅 스트리밍 핸들러(chat streaming handlers)에 SSE 핑(ping) 지원도 추가합니다. 이는 첨부 파일과는 별개의 기능이지만, 에이전트가 여전히 작업 중인 동안 오래 걸리는 도구 워크플로(tool workflows)가 유지되도록 도와줍니다.

첨부 파일이 많은 실행(runs)의 경우, 이 두 기능의 조합은 유용합니다:

긴 도구 작업 중에도 스트리밍(streaming)이 활성 상태를 유지합니다.
최종 done 청크(chunk)가 생성된 파일들을 담을 수 있습니다.

제가 이 기능을 선택한 이유

이것은 AIClaw의 로컬 우선(local-first), 도구 지향적(tool-oriented) 설계 철학의 좋은 예시입니다. 이 플랫폼은 단순히 멋진 문단을 생성하려고 노력하는 것이 아닙니다. 작업을 완료하고 그 작업이 만들어낸 아티팩트(artifacts)를 반환하려고 노력합니다.

생성된 파일이 종종 실제 출력물(output)인 경우가 많습니다. 이를 응답 경로(response path)에서 일급 객체(first-class)로 만드는 것은 올바른 방향입니다.

만약 여러분이 AIClaw로 무언가를 구축하고 있다면, 이것은 또 다른 추상적인 프롬프트 수정(prompt tweak)보다 일상적인 사용성을 더 향상시켜 주는 종류의 기능입니다.