flows.run
variables호출 단위로 Flow 변수를 오버라이드. 트리거의variables필드와 같은 모양.model이 실행에서만 에이전트 모델을 오버라이드 (워크스페이스 라우팅 · BYOK 존중).idempotencyKey같은 키로 두 번 보내면 서버가 첫 실행을 그대로 돌려줍니다.
traceId와 부분 출력을 돌려 주니 로그·재시도·다운그레이드에 쓰세요. 반환값의 .status와 .failure를 반드시 봅니다. 전송·인증·요청 오류는 예외로 던집니다. 에러 참고.
newTraceRef
서버 응답으로 traceId가 오기 전에 미리 상관 id를 만들어 둡니다.
흔한 패턴
partial이면 다운그레이드
Idempotent 재시도
HTTP 레이어에서 재시도 중이라면(핸들러가 타임아웃했지만 서버가 이미 처리 중일 수 있는 경우), 재시도 때 같은idempotencyKey를 넘기세요. 서버가 원래 실행의 traceId를 그대로 돌려주고 새로 돌리지 않습니다.
notice를 실패가 아닌 안내로
notices[]는 실행을 제약했지만 실패는 아닌 것들입니다(툴 호출 한도 도달, 리트리벌 결과 0, 출력 잘림). 로그 · 관리자 UI에 노출하되 최종 사용자에게 에러로 띄우지 마세요.
MCP · CLI로 같은 일
SDK 게시 전이라 MCP · CLI로 같은 작업이 됩니다.flows.run과 같은 봉투(traceId · status · outputs · notices · failure)를 돌려줍니다.