보내기

메시지 하나가 turn 하나다. 같은 세션의 메시지는 같은 worker, 같은 작업 트리, 같은 Claude Code 대화에서 차례로 돈다. scope는 sessions:write다. SDK 예제는 SDK 설치에서 만든 werft 클라이언트를, HTTP API 예제는 서버 주소 API와 key KEY 셸 변수를 쓴다. 예제의 GATE-SPEC {…} 메시지는 개발용 서버의 fake 모델이 읽는 대본이다(시작).

세션 하나 준비제목 링크 복사

const created = await werft.sessions.create({
  profile_id: "claude-coding-local",
  repository_id: "sample-app",
  message: 'GATE-SPEC {"id":"m1","steps":[],"final":"ready"}',
});
const sessionId = created.session_id;

보내기제목 링크 복사

const sent = await werft.sessions.messages.send(sessionId, {
  message:
    'GATE-SPEC {"id":"m2","steps":[{"tool":"Bash","input":{"command":"ls","description":"list files"}}],"final":"listed"}',
});
console.log(sent);

{
  turn_id: '2',
  receipt_id: '…',
  receipt_status: 'accepted'
}

응답은 202다. 앞 turn이 아직 돌고 있으면 새 turn은 queued로 기다렸다가 차례가 되면 돈다.

• message는 UTF-8 32,768바이트까지다. 넘으면 413이다.
• 한 세션에 쌓아 둘 수 있는 대기 입력은 기본 20개다. 넘으면 429다.
• Idempotency-Key가 필요하다. 응답을 못 받았으면 같은 key와 같은 본문으로 다시 보낸다. turn은 한 번만 생긴다. SDK는 key를 만들어 붙이고 재시도에 같은 key를 쓴다.

결과 읽기제목 링크 복사

import { waitForTurn } from "@werft-ai/sdk";

const turn = await waitForTurn(werft, sessionId, sent.turn_id, {
  signal: AbortSignal.timeout(5 * 60_000),
});
console.log(`turn ${turn.turn_id}: ${turn.status}`);

turn 2: completed

turn이 끝났는지는 이 status로만 판단한다. 다섯 값 중 하나면 끝났다. completed는 엔진이 turn을 정상으로 마쳤다는 뜻이지 요청한 일을 다 했다는 뜻이 아니다. 모델이 도구 하나만 부르고 답을 끝내도, 도구가 오류를 받아도 completed다. 일이 됐는지는 스트리밍의 assistant·tool_result 이벤트를 읽고 판단하고, 덜 됐으면 같은 세션에 다음 메시지를 보낸다.

보낼 수 없을 때제목 링크 복사

SDK에서는 아래 응답이 APIError로 오고, isApiError(error, "SESSION_PAUSED")처럼 가른다. 409는 SDK가 다시 보내지 않는다.

다음 단계제목 링크 복사

• 스트리밍 받기: turn이 도는 동안 진행 보기
• 첨부