Skip to main content
앱이 실제로 Flow를 부르는 자리입니다. 인증은 그 Flow의 트리거 시크릿만으로 됩니다. 여기선 PAT이 필요 없습니다.

flows.run

옵션:
  • variables 호출 단위로 Flow 변수를 오버라이드. 트리거의 variables 필드와 같은 모양.
  • model이 실행에서만 에이전트 모델을 오버라이드 (워크스페이스 라우팅 · BYOK 존중).
  • idempotencyKey 같은 키로 두 번 보내면 서버가 첫 실행을 그대로 돌려줍니다.
실행 결과 실패는 예외를 던지지 않습니다. SDK가 traceId와 부분 출력을 돌려 주니 로그·재시도·다운그레이드에 쓰세요. 반환값의 .status.failure를 반드시 봅니다. 전송·인증·요청 오류는 예외로 던집니다. 에러 참고.

newTraceRef

서버 응답으로 traceId가 오기 전에 미리 상관 id를 만들어 둡니다.
실행 전에 미리 앱 로그(또는 Slack 메시지)에 참조를 남기고 싶을 때 씁니다.

흔한 패턴

partial이면 다운그레이드

Idempotent 재시도

HTTP 레이어에서 재시도 중이라면(핸들러가 타임아웃했지만 서버가 이미 처리 중일 수 있는 경우), 재시도 때 같은 idempotencyKey를 넘기세요. 서버가 원래 실행의 traceId를 그대로 돌려주고 새로 돌리지 않습니다.

notice를 실패가 아닌 안내로

notices[]는 실행을 제약했지만 실패는 아닌 것들입니다(툴 호출 한도 도달, 리트리벌 결과 0, 출력 잘림). 로그 · 관리자 UI에 노출하되 최종 사용자에게 에러로 띄우지 마세요.

MCP · CLI로 같은 일

SDK 게시 전이라 MCP · CLI로 같은 작업이 됩니다.
둘 다 flows.run과 같은 봉투(traceId · status · outputs · notices · failure)를 돌려줍니다.