클라이언트 설정과 오류

SDK 설치에서 만든 클라이언트의 나머지 설정과, 호출이 실패했을 때 SDK가 하는 일을 다룬다. 기능별 메서드는 세션, 메시지, 승인과 push 문서에 있다.

클라이언트 옵션제목 링크 복사

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

const werft = new Werft({
  baseUrl: "https://werft.example.com",
  apiKey: process.env.WERFT_API_KEY,
  maxRetries: 2,
  timeoutMs: 60_000,
});

승인용 key 따로 쓰기제목 링크 복사

workspace의 key(개인·에이전트)는 자기가 시작한 세션의 요청을 승인하지 못한다. 승인에는 다른 key나 사람이 필요하다. withOptions는 설정을 이어받은 두 번째 클라이언트를 만든다.

const approver = werft.withOptions({
  apiKey: process.env.WERFT_APPROVER_API_KEY,
});

에이전트 key는 profile_id와 repository_id 대신 자기 에이전트의 agent_release_id로 세션을 만든다. 에이전트 key에는 sessions:read, sessions:write, sessions:control, 승인자 key에는 sessions:read, sessions:approve가 필요하고, 세션의 공유 범위에 승인자가 들어 있어야 한다. 설정과 실제 출력은 샘플 README에 있다.

오류제목 링크 복사

서버 오류는 APIError이고 isApiError(error, code)로 가른다.

import { isApiError } from "@werft-ai/sdk";
import { werft } from "./werft.ts";

const sessionId = process.argv[2] ?? "";
const { revision } = await werft.sessions.get(sessionId);
try {
  await werft.sessions.pause(sessionId, { expected_revision: revision + 1 });
} catch (error) {
  if (isApiError(error, "REVISION_CONFLICT"))
    console.log(`${error.status} ${error.code}`);
  else throw error;
}

409 REVISION_CONFLICT

오류 코드 목록은 HTTP API 레퍼런스의 각 operation에 있다.

재시도와 Idempotency-Key제목 링크 복사

• 다시 보내는 경우: 오류 본문이 retryable: true일 때(429 포함), 프록시가 낸 502·504, 응답을 읽지 못한 연결 실패와 시도 timeout. 프록시 502·504(API 오류 본문이 없는 것)와 연결 실패·timeout은 GET과 Idempotency-Key가 있는 명령만 다시 보낸다. key가 없는 openPullRequest·commentPullRequest는 서버가 이미 실행했을 수 있어 이 경우에는 다시 보내지 않는다. 오류 본문에 retryable: true가 있으면 명령 종류와 관계없이 다시 보낸다.
• 다시 보내지 않는 경우: 409 전부, 500, retryable: true가 아닌 그 밖의 4xx.
• Retry-After가 있으면 그만큼 기다린다. maxRetryDelayMs를 넘으면 기다리지 않고 실패한다.
• sessions.create와 messages.send처럼 Idempotency-Key가 필요한 명령은 SDK가 호출마다 key를 하나 만들고, 그 호출의 재시도에 같은 key를 보낸다. 프로세스를 다시 띄운 뒤 같은 명령을 이어서 재시도하려면 오류의 idempotencyKey를 저장해 두고 { idempotencyKey }로 넘긴다.
• expected_revision은 호출하는 쪽이 넘긴다. SDK는 대신 읽어 채우지 않는다.

SDK가 감싸는 API제목 링크 복사

sessions.list와 turns.list는 await하면 첫 페이지, for await하면 모든 항목을 준다. 필드 이름은 HTTP API와 같은 snake_case다. 에이전트·멤버·key 관리처럼 웹 로그인으로만 부르는 API는 감싸지 않는다. limits.get은 로그인한 workspace owner만 읽으므로 API key로 부르면 403이다.

저장소의 예제제목 링크 복사

examples에는 유즈케이스별 샘플이 있다. key와 카탈로그 확인, 세션 목록, 이벤트 스트림 이어 받기, 재시도와 Idempotency-Key, 질문·권한 요청 답변, 세션 제어와 복구, 막힌 close, push 승인과 PR을 다루고, 어떤 SDK API를 어느 샘플이 쓰는지 표로 정리했다. 저장소 checkout의 루트에서 bun install 뒤에 돌린다.

승인 샘플의 인증 모드제목 링크 복사

이 절은 일반 SDK 클라이언트 전체가 아니라 세션 종료 승인 샘플의 인증 모드와 실행 입력이다. 샘플은 서버 주소와 사용자별 key를 받는다. 정해진 기본 서버는 없으므로 baseUrl 또는 WERFT_BASE_URL을 반드시 지정한다.

샘플은 FAKE 모델 전용이다. API key를 소스나 로그에 넣지 않고 실행 환경으로 전달한다.

사용자 key와 에이전트 key를 공유하지 않는다. 에이전트 key는 고정된 agent release로 실행하고, 승인은 자기가 시작한 세션과 다른 key나 사람이 수행한다. 실행 권한 회수와 key 폐기는 첫 owner와 key를 따른다.

다음 단계제목 링크 복사

• 시작: 세션 생성 요청의 필드와 오류
• 스트리밍 받기: 이벤트 종류와 재연결