워크플로

워크플로는 이름을 붙여 저장한 실행 정의입니다. 프롬프트, 모델, 파일, 연결, 타임아웃, 셸과 웹 설정을 담고 있습니다. 코드에서는 이름으로 워크플로를 시작하고, 실행마다 달라지는 값만 보냅니다.

{
  "workflow": "investigate-payment",
  "input": { "payment_id": "pay_123" },
  "max_cost_micros": 500000
}

저장되는 값과 실행마다 보내는 값

워크플로는 대시보드의 워크플로에서, PUT /v1/workflows/{name}로, 또는 ephemeral workflows save로 저장합니다. 전송 형식은 JSON이며, CLI는 YAML도 읽습니다. 이름은 영문자나 숫자로 시작해야 하고, 영문자, 숫자, _, ., -를 최대 128자까지 쓸 수 있습니다.

저장된 필드 덮어쓰기

실행 요청에 prompt, model, files, connections, timeout_seconds, shell, web 중 하나라도 있으면 해당 실행에 한해 저장된 값을 대체합니다. 파일과 연결은 컬렉션 전체가 교체되며, 저장된 항목과 병합되지 않습니다.

{
  "workflow": "investigate-payment",
  "input": { "payment_id": "pay_123" },
  "connections": {},
  "max_cost_micros": 500000
}

빈 객체나 빈 배열을 보내면 해당 실행에서는 그 컬렉션이 비워집니다. 연결이나 파일 하나만 바꾸려면 실행에 사용할 전체 목록을 보내세요.

참조가 확정되는 시점

워크플로는 파일과 저장된 연결을 이름으로 참조합니다. Ephemeral은 실행을 만들 때 이 이름을 해석하고, 실행은 해석된 결과를 그대로 유지합니다. 파일 이름은 같은 이름으로 가장 최근에 업로드한 파일로 해석되므로,playbook.md의 새 버전을 업로드하면 워크플로를 수정하지 않아도 다음 실행이 읽는 내용이 바뀝니다.

참조한 파일이나 연결이 더 이상 없으면 실행 요청이 400으로 실패하며, 누락된 참조를 알려 줍니다. 대기열에 들어가는 것도, 비용이 청구되는 것도 없습니다.

입력과 출력 설명하기

선택 필드 세 개로 워크플로가 스스로를 설명할 수 있습니다. 사람, 다른 코드, AI 에이전트가 프롬프트를 읽지 않고도 호출하는 방법을 알 수 있습니다. description은 워크플로가 하는 일과 기대하는 입력을 한두 문장으로 설명합니다(최대 500자). input_schema는 실행의 input이 따라야 하는 JSON Schema입니다. output_schema는 실행의 출력이 따라야 하는 JSON Schema입니다. 세 필드는 모두 GET /v1/workflows?detail=true와 MCP list_workflows 도구에서 확인할 수 있으며, 인라인 실행에서도 사용할 수 있습니다.

description: Current weather for a city. Input is a city name.
prompt: Look up the current weather for the city in the input and report it.
web: true
input_schema:
  type: object
  required: [city]
  properties:
    city: { type: string }
output_schema:
  type: object
  required: [city, temperature_c, summary]
  properties:
    city: { type: string }
    temperature_c: { type: number }
    summary: { type: string }

입력은 API, CLI, MCP 도구, 스케줄 중 어디에서 오든 실행을 만들 때 검사합니다. 일치하지 않으면 요청은 400으로 실패하고, 문제마다 경로와 이유를 알려 줍니다(예: input.city: required). 큐에 들어가는 것도 없고 비용도 청구되지 않습니다. 스케줄의 입력은 스케줄을 만들거나 바꿀 때 검사하고, 시작할 때마다 다시 검사합니다. 더 이상 일치하지 않는 시작은 스케줄의 마지막 오류로 기록됩니다.

출력은 output_schema와 일치하는 JSON이어야 합니다. 에이전트에게 스키마를 알려 주고 JSON만으로 응답하도록 요청합니다. 응답이 일치하지 않으면 정확한 오류를 전달하고 수정하도록 요청하며, 최대 두 번까지 반복합니다. 그런 다음 Ephemeral이 출력을 다시 검사합니다. 일치하면 실행은 succeeded로 남고 출력은 코드 블록으로 감싸지 않은 JSON 텍스트입니다. 일치하지 않으면 실행은 failed로 끝나고 error에는 output did not match output_schema: output.temperature_c: got string, want number 같은 내용이 담깁니다. 에이전트가 쓴 내용을 확인할 수 있도록 출력 텍스트는 보존됩니다. 데이터 무보존 실행은 오류에 세부 내용을 남기지 않습니다.

스키마는 JSON Schema draft 2020-12를 사용하며(draft 7 이하를 지정한 $schema도 동작합니다) 각각 최대 32 KiB입니다. #/$defs/address처럼 스키마 안의 정의만 참조할 수 있습니다. 올바르지 않은 스키마는 워크플로를 저장하거나 실행을 만들 때 400으로 거부됩니다.

워크플로 수정

워크플로를 다시 저장하면 기존 내용이 교체됩니다. 버전 기록은 없습니다. 변경 전에 만든 실행은 생성 당시의 정의를 유지합니다. 실행이 정확히 무엇을 사용했는지 보려면 정의를 읽어 보세요.

워크플로를 읽으면 연결 자격 증명과 URL 비밀 값이 제거된 상태로 반환됩니다. 해당 필드를 뺀 채 다시 저장해도 인증 유형이 그대로라면 저장된 자격 증명은 유지됩니다.