Deep Agent Builder 문서 작성 에이전트
문서 작성 에이전트는 대화 결과를 텍스트 답변으로 끝내지 않고, 작업 폴더에서 Word, PowerPoint, Excel 파일을 만들고 확인한 뒤 다운로드할 수 있는 문서로 전달하는 실행 모드입니다. 이 페이지에서는 모드 선택부터 파일 확인과 전달까지의 순서, 첨부파일을 계산에 사용하는 범위, 실패했을 때 다음 판단을 설명합니다.
시작하기 전에 확인할 것
다음 조건을 먼저 확인합니다.
- 에이전트를 조회하고 수정할 권한이 있습니다.
- 문서 작성에 사용할 스킬과 첨부파일을 준비했습니다.
- 결과를 저장하거나 다운로드할 위치와 파일 형식을 정했습니다.
- 고객 자료 대신 승인된 비식별 테스트 자료를 사용합니다.
문서 작성 모드가 선택됐다는 사실만으로 파일 생성이나 다운로드가 끝난 것은 아닙니다. 파일이 실제로 작성됐는지, 문서 구조를 확인했는지, 전달된 링크가 원래 결과를 가리키는지 각각 확인해야 합니다.
문서 작성 모드의 경계
에이전트 설정에서 일반 모드와 문서 작성 모드를 구분합니다. 실행 요청의 foreground와 background 선택은 실행 방식이며 문서 작성 모드를 고르는 값이 아닙니다. 설정을 읽지 못하거나 값이 없거나 알 수 없는 값이면 일반 모드로 처리될 수 있으므로, 실행 전에 에이전트 설정과 화면의 현재 선택을 함께 확인하세요.
문서 작성 모드는 별도 서버가 아니라 기존 Agent Runtime 안에서 실행됩니다. 작업 폴더가 있어야 파일 도구를 사용할 수 있으며, thread가 없는 실행에서는 파일 작업이 거부될 수 있습니다. 작업 폴더가 준비되지 않은 degraded 경로에서는 문서 도구 없이 일반 모드로 실행될 수 있습니다.
문서 작성 모드에서 사용하는 주요 결과는 다음과 같습니다.
| 결과 | 확인할 내용 |
|---|---|
| 작업 폴더 파일 | 문서 작성 도구와 코드 실행이 만든 실제 파일 |
| 문서 점검 결과 | 문서 구조, 텍스트, 차트와 점검 결과를 텍스트로 확인한 내용 |
| 저장된 문서 | 완성된 Word, PowerPoint, Excel 파일을 보관하는 결과 |
| 다운로드 첨부 | Word, PowerPoint, Excel, PDF를 채팅 첨부로 전달하는 결과 |
저장과 다운로드는 같은 동작이 아닙니다. Canvas에 파일을 저장해도 채팅 첨부가 자동으로 생긴다고 가정하지 말고, 필요한 결과를 각각 확인합니다. 미리보기나 Office 렌더링에 실패해도 저장된 파일 자체가 유지될 수 있으므로, 화면 미리보기와 파일 저장 상태를 나눠 판단하세요.
문서 작성 스킬을 준비합니다
문서 작성용 스킬은 일반 스킬과 구분되는 document 유형으로 관리할 수 있습니다. 문서 ZIP을 등록할 때는 정확히 하나의 SKILL.md가 있어야 하며, 경로 탈출, 절대 경로, 심볼릭 링크, 허용되지 않은 확장자와 압축 해제 크기 초과 여부가 검사됩니다. 업로드에 포함된 스크립트는 업로드만으로 실행되지 않습니다.
스킬을 연결할 때는 다음 순서로 확인합니다.
- 문서 형식과 작업 목적에 맞는 스킬을 선택합니다.
- 에이전트에 연결된 스킬 목록에서 선택한 항목이 보이는지 확인합니다.
- 스킬이 필요한 입력 형식과 출력 형식을 설명하는지 확인합니다.
- 비식별 테스트 자료로 문서 작성과 결과 전달을 시험합니다.
내장 스킬과 연결된 스킬은 런타임에서 접근 범위가 다를 수 있습니다. 승인 정보가 없을 때 내장 스킬은 계속 조회되더라도 연결된 스킬은 거부될 수 있습니다. 연결된 스킬을 불러오지 못하면 파일 생성 문제로 단정하지 말고 스킬 승인 범위와 에이전트 설정을 먼저 확인합니다.
문서를 만들고 확인합니다
다음 순서로 한 번의 문서 작업을 검증합니다.
- 문서 목적, 대상 독자, 파일 형식을 정합니다. 결과를 저장할지 다운로드할지도 구분합니다.
- 필요한 문서 스킬과 비식별 입력 자료를 연결합니다.
- 문서 작성 에이전트가 사용할 작업 폴더와 입력 첨부를 확인합니다.
- 문서 내용을 작성하도록 요청합니다. 문서 작성 하위 에이전트로 위임된 경우에도 최종 파일 전달 결과를 확인합니다.
- 문서 점검 결과로 제목, 본문, 표, 차트와 파일 구조를 확인합니다. 텍스트 점검 결과만으로 렌더링된 이미지의 모양까지 확인했다고 판단하지 않습니다.
- 완성된 파일을 저장하거나 다운로드합니다.
- 반환된 파일명과 링크를 열어 원래 요청한 형식과 내용이 맞는지 확인합니다.
문서가 완성됐다는 답변만으로 파일이 존재한다고 보지 마세요. 저장 결과, 점검 결과, 다운로드 링크가 각각 확인될 때 작업을 완료로 기록합니다. 하위 에이전트가 반환한 다운로드 링크는 변형하지 않고 그대로 사용해야 합니다.
첨부파일로 표를 계산할 때
문서 작성 모드에서 CSV와 XLSX는 일반 대화 첨부와 다른 계산 경로를 사용할 수 있습니다. 원본을 작업 폴더로 가져온 뒤 run_codes로 계산하고, 각 호출은 새 Python 프로세스에서 실행됩니다. 한 호출에서 만든 변수나 DataFrame이 다음 호출에 자동으로 남지 않으므로 중간 결과는 작업 폴더의 파일로 저장한 뒤 다음 호출에서 다시 읽습니다.
CSV를 계산할 때는 인코딩과 구분자를 먼저 확인합니다. UTF-8 BOM, 선언된 인코딩, UTF-8, cp949 순서로 해석할 수 있으며 후보 결과가 서로 다르면 인코딩을 확인해야 합니다. 디코딩 오류를 무시하거나 다른 문자로 바꿔 결과를 숨기지 않습니다. 엑셀 통합 문서는 여러 시트를 분리해 읽을 수 있지만, 계산 결과와 원본 파일을 혼동하지 않도록 결과 파일을 별도로 저장합니다.
첨부파일을 가져올 때는 현재 실행 스레드에 속한 파일만 사용할 수 있습니다. 같은 이름의 대상 파일이나 심볼릭 링크를 임의로 덮어쓰지 않으며, 작업 폴더 예산을 넘으면 이번 호출에서 새로 만든 파일을 정리할 수 있습니다.
저장, 취소와 실행 제한
문서 파일 쓰기는 대상별 잠금과 작업 폴더 예산의 영향을 받습니다. 쓰기가 끝난 뒤 예산을 초과하면 기존 파일을 복원하고 새 파일을 삭제하는 경로가 있을 수 있습니다. 취소 요청이 들어와도 이미 시작된 쓰기와 필요한 정리가 끝난 뒤 취소가 전달될 수 있습니다.
코드 실행은 wall-clock 시간 제한과 출력 크기 제한을 받습니다. Bash는 정적 거부 검사를 통과한 경우에만 실행되며, 이 실행 경계가 완전한 파일시스템이나 네트워크 격리를 의미하지는 않습니다. 따라서 비밀값이나 고객 자료를 입력하지 말고, 실행 결과에 내부 경로와 자격 증명이 포함되지 않는지 확인합니다.
실패했을 때의 판단
| 증상 | 먼저 확인할 것 | 다음 행동 |
|---|---|---|
| 일반 답변만 반환됨 | 에이전트 모드, 작업 폴더, thread 존재 여부 | 설정이 docwriter인지와 파일 작업 조건을 다시 확인 |
| 문서 스킬을 불러오지 못함 | 스킬 유형, 승인 범위, 연결 상태 | 연결된 스킬의 승인과 에이전트별 스킬 경로를 확인 |
| 파일은 있지만 미리보기가 없음 | 저장 결과와 렌더링 결과가 분리됐는지 | 저장된 원본을 점검하고 미리보기 실패를 별도 기록 |
| 다운로드 링크가 열리지 않음 | 반환된 링크의 변경 여부와 첨부 등록 상태 | 링크를 임의로 고치지 말고 export 결과와 전달 상태를 다시 확인 |
| CSV 계산 결과가 다름 | 인코딩, 구분자, 시트, 중간 파일 | 원본을 다시 읽고 호출 사이의 결과 파일을 확인 |
| 실행이 시간 초과됨 | 작업 크기, 호출별 제한, 출력량 | 작업을 나누고 큰 출력은 파일로 저장한 뒤 다시 점검 |
완료 기준과 다음 문서
문서 작성 작업은 다음 조건을 모두 확인했을 때 완료로 기록합니다.
- 문서 작성 모드와 작업 폴더가 실제 실행에 사용됐습니다.
- 요청한 형식의 파일이 만들어졌고 문서 구조를 점검했습니다.
- 저장과 다운로드 중 필요한 결과를 구분해 확인했습니다.
- 첨부파일을 사용했다면 원본, 계산 과정, 결과 파일을 구분했습니다.
- 비식별 자료만 사용했고 비밀값과 내부 경로를 결과에 남기지 않았습니다.
다음 문서에서 연결 설정과 입력 자원을 더 확인할 수 있습니다.