채팅: 스트리밍 턴 시작

POST /v1/chat/stream

Agent 턴을 시작하고 session id를 즉시 반환합니다. 턴은 백그라운드에서 실행됩니다. LLM 델타, 도구 호출, 도구 결과, 최종 어시스턴트 메시지는 /v1/stream의 다중화 WebSocket으로 전달됩니다. channel은 chat이며 key는 반환된 session_id입니다. 다시 연결하면 세션별 시퀀스 버퍼에서 이어서 수신합니다.

요청 본문

{ "message": "analyze BTC momentum", "session_id": "chat_...", "attachments": [ { "key": "file_ab12", "filename": "chart.png", "media_type": "image/png", "size": 48213, "kind": "image" } ], "model": "claude-sonnet-4-5", "reasoning_effort": "high" }

응답 본문

{ "session_id": "chat_...", "kind": "chat", "is_new": true }

참고

message를 제외한 모든 필드는 선택 사항입니다. 완료된 제공자 연결 오류 턴을 resume: true로 계속하거나, 기능 설정 후 capability_continuation으로 작업을 계속할 때는 message를 생략할 수 있습니다. session_id는 기존 대화를 계속하며, 생략하면 새 세션이 시작됩니다. 이때 session_kind가 화면 유형을 선택하고 기본값은 "chat"입니다. retry: true는 중복 턴을 추가하지 않고 세션의 최신 턴을 교체합니다. resume: true에는 기존 session_id가 필요합니다. 완료된 도구 결과를 유지하고 마지막 영구 저장 경계부터 실행을 계속하며, 화면에 표시되는 사용자 메시지 행을 추가하지 않습니다.

메시지 식별자와 일회성 스킬: client_message_id는 클라이언트가 생성한 공백이 아닌 문자를 포함하는 문자열(최대 200자)이며 사용자 메시지와 함께 저장됩니다. retry: true에서는 원본 메시지의 client_message_id를 retry_target으로 보냅니다. 기존 메시지는 u-<row id>도 사용할 수 있습니다. 최신 영구 저장 사용자 턴이 대상과 일치할 때만 해당 턴을 철회합니다. 저장되지 않았거나 후속 메시지로 대체된 대상은 기존 기록을 삭제하지 않습니다. retry_target을 생략하면 최신 턴을 교체하는 기존 동작을 유지합니다. turn_skill_overrides: { include: string[], exclude: string[] }는 해당 메시지에만 적용하고 메타데이터의 skill_overrides에 저장하며 세션 기본값을 변경하지 않습니다. 같은 스킬로 재시도하려면 원래 설정을 다시 보내야 합니다. 다음 일반 메시지는 이 설정을 상속하지 않습니다.

capability_continuation: { "tool_call_id": "..." }에는 기존 session_id와 가장 최근에 종료된 턴의 도구 결과에 포함된 재개 가능한 기능 설정 요구 사항이 필요합니다. 기능이 설치되어 있고 요청된 서비스를 사용할 준비가 되어 있어야 합니다. 계속 실행할 때 대화 기록과 도구 결과를 유지하며, 화면에 표시되는 사용자 메시지 행을 추가하지 않습니다. 중복 콜백, 새 작업으로 대체된 콜백, 완료되지 않은 설정에는 409를 반환합니다. retry: true 또는 resume: true와 함께 사용하지 마세요. 계속 실행할 때 원래 Plan/Deep 모드도 유지하며, 중단된 작업에도 409를 반환합니다. parent_session_id 또는 Plan 승인 계속 실행과 함께 사용할 수 없습니다. connector_continuation은 이전 클라이언트를 위한 별칭이며 동일한 기능 검사를 수행합니다. 계속 실행 필드는 하나만 지정하세요.

첨부 파일: 먼저 POST /v1/files(multipart)로 파일을 업로드해 key를 얻은 후 여기서 참조합니다. 각 항목은 { key, filename, media_type, size, kind } 형식입니다. kind는 "image" | "pdf" | "spreadsheet" | "text" | "office"를 지원하며 일반 "file" 유형은 거부합니다. 턴당 최대 8개, 이미지당 5 MiB, 기타 파일당 20 MiB까지 허용합니다. 음성 입력은 voice_input_key에 원본 녹음의 FileStore key를 지정합니다(POST /v1/voice/transcribe?persist로 업로드). 기록에서 음성을 재생할 수 있으며, 전사 텍스트는 message에 넣습니다.

턴별 모델 지정: model은 이번 턴의 모델만 변경합니다. 배포 기본값(PUT /v1/llm/default-model)이나 동시 접속 클라이언트에는 영향을 주지 않습니다. 모델은 현재 연결된 제공자가 지원해야 합니다. GET /v1/llm/available-models를 참조하세요. 연결 전환이 필요한 모델은 400으로 거부합니다. reasoning_effort는 이번 턴의 추론 수준을 재정의하며, 실제 모델이 지원하는 값이어야 합니다. 잘못된 값은 턴 시작 전에 400을 반환합니다.

턴 중간 조정 이벤트: POST /v1/chat/interject를 통해 큐에 넣은 메시지가 실행 중인 턴에 주입되면 user_interjection 이벤트({ "message": "...", "ts_ms": 1747000000000 })가 발생합니다. 최종 done 이벤트 데이터에는 두 개의 선택 필드가 있습니다. POST /v1/chat/interrupt로 턴을 중지했을 때의 interrupted: true와 주입하기에 너무 늦게 도착한 메시지를 나열하는 pending_interjections: string[]입니다. 클라이언트는 후자를 일반 메시지로 다시 전송합니다. 헤드리스 호출자는 선택적 본문 필드 surface("web" | "cli", 기본 "web")와 prompt_mode("full" | "minimal", 기본 "full")로 시스템 프롬프트를 조정할 수 있습니다. cli는 사용자 정의 URI 와이어 프로토콜을 생략하고, minimal은 스킬 카탈로그, 날짜, 작업 디렉터리를 유지하면서 주입 컨텍스트에서 개인화를 제거한 간결한 골격(정체성, 스킬/도구 동작, 기본 Markdown)을 마운트합니다.

WebSocket channel, 구독, 시퀀스 번호, 재생 및 제어 프레임은 다중화 WebSocket을 참조하세요.