Workflow 앱 API

Workflow 앱 API

Workflow 앱은 workflow 모드로 돌아요. 호출마다 게시된 워크플로를 한 번 실행하고 그 출력을 반환하죠. 호출 사이에 대화 상태가 없으니, 각 실행은 이전 실행과 독립적이에요.

출처: 공식문서

인증, 베이스 URL, 엔드 유저 데이터를 스코프하는 `user` 필드는 [Get Started](/en/api-reference/guides/get-started)와 [End User Identity](/en/api-reference/guides/end-user-identity)에서 다뤄요.

워크플로 실행하기

  • Run Workflow: 제공한 입력 변수로 앱의 현재 게시된 워크플로를 실행해요.

    스트리밍 모드는 노드가 실행되는 대로 이벤트를 실시간 전달하고, blocking 모드는 실행이 끝나면 반환돼요.

  • Run Workflow by ID: 대신 특정 게시 버전을 실행합니다. 이전 실행 응답이나 실행 상세 조회에서 얻은 workflow_id로 식별해요.

실행 따라가고 제어하기

어떤 모드로 돌리든 응답에는 ID 둘이 실려요. task_id는 활성 상태인 실행을 제어하고, workflow_run_id는 이후에 남는 영구 레코드를 식별하죠.

  • Stop Workflow Task: task_id로 활성 실행을 취소해요. 스트리밍 모드에서만 동작합니다. blocking 호출은 반환될 때쯤 이미 끝났으니까요.

  • Stream Workflow Events: 연결이 끊기거나 일시정지된 뒤 workflow_run_id에서 실행의 이벤트 스트림을 재개해요.

    include_state_snapshot=true를 넘기면 이미 실행된 노드의 상태를 먼저 재생하고, continue_on_pause=true를 넘기면 여러 번의 Human Input 일시정지에 걸쳐 열려 있어요.

Human Input 위해 멈추기

실행이 전달 방식이 웹 앱인 Human Input 노드에 도달하면, 일시정지를 API로 완료하면 돼요:

  1. 일시정지 신호 듣기 — 실행의 이벤트 스트림이 form_token과 workflow_run_id를 실은 human_input_required를 내보내고, workflow_paused 이벤트로 끝납니다.
  2. 폼 가져오기 — form_token으로 Get Human Input Form을 호출해 폼 내용을 불러와요.
  3. 응답 제출하기 — Submit Human Input Form으로 수신자의 입력을 보냅니다. 제출하면 실행이 재개돼요.
  4. 스트림 재개하기 — 멈춘 스트림의 workflow_run_id로 Stream Workflow Events 새 스트림을 열고, 남은 이벤트를 따라 실행이 끝날 때까지 내려가요.

파일 첨부 제출과 전체 이벤트 시퀀스는 Human Input Flow 가이드를 보세요.

지난 실행 조사하기

  • Get Workflow Run Detail: workflow_run_id로 실행의 상태와 출력을 확인해요.
  • List Workflow Logs: 노드별 실행 로그가 아니라 실행 레벨 요약(상태, 토큰 사용량, 스텝 수, 시간)을 보여주고, 키워드·상태·날짜 범위·트리거한 주체로 필터할 수 있어요.

노드 레벨 이벤트가 필요하면 로그 대신 실행을 스트리밍하세요. 시작할 실행은 스트리밍 모드로 Run Workflow를, 이미 진행 중인 실행은 Stream Workflow Events를 호출하면 돼요.

파일 다루기

  • Upload File: 이미지·문서·오디오·비디오 파일을 업로드한 뒤, 워크플로 실행 때 반환된 id를 파일 타입 입력 변수의 upload_file_id로 넘겨요. 파일은 업로드한 엔드 유저에게 스코프됩니다.
  • Get End User Info: 엔드 유저 ID(Upload File 응답의 created_by 같은 것)로 세부 정보를 조회해요.

음성을 텍스트로, 텍스트를 음성으로

  • Convert Audio to Text: 업로드한 오디오(MP3·M4A·WAV·AMR·MPGA, 최대 30MB)를 받아쓰기해, 엔드 유저가 입력 값을 타이핑 대신 말로 제공하게 해줘요.
  • Convert Text to Audio: 워크플로의 텍스트 출력을 다시 음성으로 합성해요.

앱 정보와 설정 가져오기

  • Get App Info: 앱의 이름, 설명, 태그, 모드.
  • Get App Parameters: 호출이 inputs로 보내는 필드(이름·타입·기본값)와 앱의 기능 스위치—요청이나 클라이언트 UI를 만들 때의 기반이 돼요.
  • Get App Meta: 도구 아이콘과 그 밖의 설정 메타데이터.
  • Get App WebApp Settings: 웹 앱의 사이트 설정, 테마, 커스터마이즈 옵션.

더 알아보기 (Learn more)