Deep Agent Builder Thread와 첨부파일 보관
Thread는 에이전트 대화와 실행을 다시 찾고 이어가기 위한 단위입니다. 이 페이지에서는 Thread를 만들고 목록에서 찾은 뒤, 실행 상태와 첨부파일을 확인하고 삭제할 때 무엇이 함께 바뀌는지 판단하는 방법을 설명합니다.
시작하기 전에 확인할 것
다음 조건을 먼저 확인합니다.
- 에이전트와 Thread를 조회할 권한이 있습니다.
- 실행을 시작하려면 실행 권한도 있습니다.
- 확인할 자료는 승인된 비식별 테스트 자료입니다.
- 삭제 전에는 보존해야 할 대화와 첨부파일을 별도로 확인했습니다.
Thread ID는 화면에 표시되는 이름과 다를 수 있습니다. 실행과 조회에는 외부 호출용 공개 식별자를 사용하며, 다른 사용자의 Thread나 존재하지 않는 Thread는 같은 방식으로 조회되지 않습니다.
Thread의 역할
Thread는 대화의 위치이면서 실행을 연결하는 기준입니다. Thread 목록에는 현재 실행 중인 run이나 최신 run이 함께 나타날 수 있지만, 메시지, 첨부파일, 산출물, branch, 실행 기록은 각각 별도의 조회 대상입니다.
다음 구분을 유지하세요.
| 대상 | 확인할 내용 |
|---|---|
| Thread | 제목, 고정 여부, 현재 모델, 생성·수정 시각 |
| Run | pending, running, interrupted 같은 실행 상태와 실행 결과 |
| Message | 대화 본문과 입력에 포함된 첨부 |
| Attachment | 입력으로 등록된 파일의 상태와 연결 |
| Artifact | 실행이 만든 결과 파일 또는 결과 자원 |
Thread가 목록에 보인다는 사실만으로 실행이 끝났거나 첨부파일이 보존됐다고 판단하지 마세요.
Thread를 만들고 실행을 확인합니다
1. Thread와 실행의 목적을 정합니다
대화 목적을 나타내는 짧은 제목과 비식별 테스트 입력을 준비합니다. 제목은 공백을 정리한 뒤 저장되며 너무 길면 잘릴 수 있으니, 제목의 앞부분이 목적을 알려 주도록 쓰는 것이 좋습니다. 같은 요청을 재전송할 수 있다면 중복 요청 식별 키 사용 여부도 먼저 정합니다. 같은 사용자가 같은 에이전트에 같은 키를 재사용하면 처음 만든 Thread를 다시 받을 수 있지만, 다른 에이전트에 같은 키를 사용하면 충돌이 됩니다.
2. Thread를 만듭니다
Thread를 만든 뒤 응답에서 공개 식별자와 제목을 확인합니다. 이후 외부 호출은 내부 숫자 ID가 아니라 공개 식별자를 기준으로 이어갑니다. 목록에서 Thread가 보이지 않으면 생성 권한과 현재 사용자 범위를 먼저 확인합니다.
3. 실행을 시작합니다
Thread에서 실행을 시작할 때 background 실행 여부를 구분합니다. background 실행은 202와 함께 run 및 Thread 식별자, pending 상태를 반환할 수 있습니다. 실행 중인 Thread 목록은 status=running으로 확인할 수 있으며, 상태가 pending, running, interrupted 중 무엇인지 구분해 기록합니다.
실행이 끝났는지는 답변이 표시됐는지만으로 판단하지 마세요. run의 상태와 결과를 별도로 확인하고, 필요한 경우 Thread 상세와 메시지 목록을 다시 조회합니다.
4. 목록에서 Thread를 찾습니다
목록은 cursor 기반으로 다음 페이지를 받을 수 있습니다. 제목 검색과 에이전트 조건을 함께 사용해 찾을 범위를 줄일 수 있으며, 기본 목록은 평가용 Thread를 제외하고 고정된 Thread와 최근 수정 순서를 우선합니다. 한 번에 받은 메시지 목록이 전체 대화라고 가정하지 마세요. 메시지는 페이지 단위로 반환되며 한 번에 정해진 개수까지만 받을 수 있습니다. 나머지는 다음 페이지를 조회해서 확인합니다.
5. 보존 정책이 적용되는 Thread를 구분합니다
Thread 중에는 화면에서 지우지 않아도 시스템이 정리 대상으로 관리하는 종류가 있습니다. 평가용 Thread가 그 예입니다. 평가용 Thread에는 보존 기간이 정해져 있고, 보존 기간 설정이 켜져 있으면 기간이 지난 Thread를 일반 삭제와 같은 경로로 정리합니다. 이 정리는 설정에 따라 꺼져 있을 수도 있습니다.
실무에서 평가에 쓴 Thread를 나중에 다시 볼 계획이라면, 보존 기간이 지나기 전에 필요한 메시지와 Artifact를 따로 보관하세요. 평가용 Thread를 일반 Thread처럼 오래 보관한다고 가정하지 마세요.
첨부파일과 산출물을 구분합니다
대화에 넣은 파일은 현재 실행 Thread에 속한 입력입니다. 파일을 첨부한 뒤에는 그 파일이 실행 입력으로 연결됐는지 확인하고, 실행 결과에 파일이 사용됐다고 추측하지 말고 실제 결과와 연결을 대조합니다.
문서형 파일의 입력과 실행 결과는 같은 자원으로 취급하지 않습니다. 실행이 만든 Artifact도 입력 Attachment와 같은 자원이 아닙니다.
첨부를 확인할 때는 다음 순서로 판단합니다.
- 현재 Thread에 속한 파일인지 확인합니다.
- 화면이나 실행 정보에서 제공되는 파일 상태가 있다면 확인합니다.
- run이 해당 파일을 입력으로 사용했는지 실행 정보와 대조합니다.
- 결과가 Artifact인지, 입력 Attachment의 재표시인지 구분합니다.
- 필요한 보존 범위와 삭제 범위를 기록합니다.
제목 수정과 고정
Thread 상세에서 제목, 고정 여부, 현재 모델을 수정할 수 있습니다. 제목은 비어 있으면 거부될 수 있고 길이 제한을 넘으면 잘릴 수 있습니다. 정의되지 않은 필드를 함께 보내지 말고, 변경 사항이 없는 수정 요청도 성공으로 기록하지 마세요.
모델을 바꾸는 경우에는 추가 모델 조회 권한이 필요할 수 있습니다. 화면에서 모델 이름이 바뀌었는지와 이후 새 실행이 어떤 모델 설정을 읽었는지는 별도로 확인합니다.
삭제하기 전에 확인할 것
삭제는 단순히 목록에서 숨기는 동작으로 취급하지 마세요. 구현 계약상 Thread의 본문과 메시지 이력은 hard delete 대상이고, 첨부파일은 soft delete로 처리되며 branch는 제거됩니다. 진행 중인 background run은 취소될 수 있지만 audit 기록은 남습니다. 서로 다른 저장 영역의 정리는 하나의 원자적 작업이 아니므로, 삭제 성공 응답만으로 모든 저장소의 정리가 동시에 끝났다고 확대하지 마세요. 메시지 정리가 별도 단계에서 이루어지는 환경이라면 정리가 실패했을 때 삭제 자체가 실패로 처리될 수 있습니다. 이 경우 Thread가 남아 있거나 일부 자료가 남아 보일 수 있으니, 삭제를 다시 시도하기 전에 현재 상태를 먼저 확인합니다.
삭제를 실행하기 전 다음을 확인합니다.
- 필요한 메시지와 Artifact를 별도 보관했는가
- 진행 중인 run이 없는가, 또는 취소를 허용하는가
- 첨부파일의 soft delete와 재조회 가능성 범위를 확인했는가
- 감사 기록이 남아야 하는 요청인지 확인했는가
대표적인 실패와 다음 판단
| 증상 | 먼저 확인할 것 | 다음 행동 |
|---|---|---|
| Thread를 찾을 수 없음 | 공개 식별자, 사용자 범위, 조회 권한 | 내부 ID로 바꾸지 말고 공개 식별자와 권한을 다시 확인 |
| background 실행이 계속 pending | run 상태, 입력 첨부 상태, 실행 권한 | Thread를 삭제하거나 재전송하지 말고 상태와 입력 준비를 먼저 확인 |
| 목록에 Thread가 보이지 않음 | cursor, 제목 검색, 에이전트 조건 | 다음 cursor를 조회하고 조건을 좁혔는지 확인 |
| 평가용 Thread가 사라짐 | 평가용 Thread 보존 기간 설정 여부 | 보존 기간이 지난 평가용 Thread는 자동 정리될 수 있으니 필요한 자료를 미리 보관 |
| 첨부는 보이지만 결과가 없음 | 첨부와 run 입력의 연결 | 파일 연결과 실행 결과를 분리해 기록 |
| 삭제 뒤 일부 자료가 남아 보임 | hard delete, soft delete, audit 보존 구분 | 첨부와 감사 기록의 보존 계약을 확인하고 삭제 성공으로 전체 정리를 단정하지 않음 |
실사용 대화, 고객 자료, 비밀값을 테스트 입력으로 사용하지 마세요. Thread를 삭제하거나 재실행하기 전에는 보존이 필요한 메시지와 Artifact를 비식별 방식으로 따로 확인합니다.
완료 기준과 다음 문서
Thread 작업은 다음 조건을 모두 확인했을 때 완료로 기록합니다.
- 공개 식별자로 Thread를 만들고 다시 조회했습니다.
- background 실행 상태를 결과와 함께 확인했습니다.
- 메시지, Attachment, Artifact, run을 서로 다른 대상으로 확인했습니다.
- 삭제 전 보존 범위와 삭제 후 hard delete, soft delete, audit 보존 범위를 구분했습니다.
- 비식별 테스트 자료만 사용했습니다.
다음 문서에서 실행 자원과 입력 경계를 이어서 확인할 수 있습니다.