챗봇 대화 세션
Session은 사용자와 Agent 사이의 대화 단위입니다. 세션에는 자체 RID, 연결된 Agent RID와 버전, 제목 및 대화 메타데이터가 있습니다. 메시지 본문과 응답은 Content, 응답을 생성하는 과정은 SessionTrace에서 조회합니다.
세션을 만들고 대화 추가
- Create Session으로 세션을 만듭니다.
agentVersion을 생략하면 생성 시점의 최신 게시 버전을 선택합니다. - 반환한 세션 RID로 대화를 추가합니다. Blocking Continue Session은 완성한 결과를 반환할 때까지 기다리고, Streaming Continue Session은 생성 중인 Markdown 텍스트를 전달합니다.
- 스트리밍이 정상 종료되면 Get Content로 최종 결과, 변수 변경값과 사용한 컨텍스트를 가져옵니다.
- 같은 세션의 응답을 기다리는 동안 다음 대화 추가 요청을 동시에 보내지 않습니다. 스트리밍을 중단해야 한다면 진행 중인 대화를 취소한 뒤 이어갑니다.
대화를 추가하면 Agent가 모델과 구성한 도구를 사용하여 응답을 생성합니다. 입력할 애플리케이션 변수는 Get Session에서 확인한 Agent 버전에 맞춰 Get Agent의 parameters를 조회하여 준비합니다.
입력 변수와 검색 컨텍스트
parameterInputs는 변수 ID를 키로 사용하는 맵입니다. 문자열 변수는 {"type":"string","value":"문자열"} 형식이고, 객체 집합 변수는 type: objectSet, 온톨로지 API 이름인 ontology, 전체 객체 집합 정의인 objectSet을 받습니다. 응답의 객체 집합 변수 변경값은 전체 정의가 아닌 RID이므로 입력과 출력 형식을 구분합니다.
사용자 메시지의 컨텍스트를 먼저 처리하려면 Get RAG Context For Session을 호출합니다. 객체 컨텍스트와 함수 검색 컨텍스트를 InputContext 목록으로 변환하여 대화 추가 요청의 contextsOverride에 전달합니다. 이 필드를 지정하면 자동 검색을 건너뛰고, 생략하면 Agent에 구성한 데이터 소스에서 자동으로 검색합니다. 빈 목록과 필드 생략을 같은 입력으로 만들지 않습니다.
메시지 ID와 추적 ID
| 식별자 | 용도 |
|---|---|
agentRid | AIP Chatbot Studio에서 만든 Agent 선택 |
sessionRid | 특정 사용자 대화 세션 선택 |
messageId | 클라이언트가 생성하는 UUID이며 진행 중인 스트리밍 대화를 취소할 때 사용 |
sessionTraceId | 응답 생성 과정 조회에 사용하는 고유 ID이며 같은 세션에서 재사용할 수 없음 |
추적 ID를 대화 추가 요청에 미리 지정하면 응답 생성 중에 추적을 조회할 수 있습니다. 생략하면 서버가 생성합니다. 응답 완료 대기 방식에서는 반환한 결과에서, 스트리밍 방식에서는 완료 후 Get Content의 교환 결과에서 생성한 ID를 읽습니다.
취소와 세션 삭제
Cancel Session은 진행 중인 스트리밍 대화 한 차례를 취소합니다. 스트리밍을 시작할 때 전달한 messageId가 필요합니다.
response를 보내면 클라이언트가 제공한 문구로 대화를 세션에 기록합니다. 이 결과의interruptedOutput은true입니다.response를 생략하면 해당 대화를 세션에 추가하지 않습니다.
취소 요청이 스트리밍 연결을 닫아 주지는 않습니다. 클라이언트는 취소를 시작할 때 읽던 스트림을 닫고, 취소와 완료가 경합하면 Get Content로 실제 대화 상태를 확인합니다. 이미 실행한 도구의 변경을 되돌려야 하는 경우에는 해당 도구나 액션의 계약에 따라 별도로 처리합니다.
Delete Session은 세션 자체를 삭제합니다. 삭제하면 더 이상 접근할 수 없고 세션 목록에도 나타나지 않습니다.
세션 목록과 만료
List Sessions는 호출자와 지정 Agent 사이의 세션 중 현재 클라이언트가 생성한 세션만 최근 갱신순으로 반환합니다. 다른 클라이언트와 AIP Chatbot Studio에서 생성한 세션은 포함하지 않습니다. Update Session Title로 식별하기 쉬운 제목을 지정할 수 있으며, 200자를 넘는 제목은 잘라서 저장합니다.
messageCount는 사용자 메시지와 Agent 응답을 모두 셉니다. 완료된 한 차례의 대화 왕복은 두 메시지입니다. estimatedExpiresTime은 예상 만료 시각이며 새 대화 교환을 추가하면 연장됩니다. 만료한 세션에는 접근할 수 없으므로 대화를 이어가려면 새 세션을 만듭니다. 클라이언트가 고정된 만료 기간을 계산하기보다 반환된 시각을 사용합니다.