워크플로 · Ephemeral 문서

실행 정의를 이름으로 저장하고 POST /v1/runs로 시작합니다. 이 페이지의 모든 엔드포인트는 member 키와 admin 키로 사용할 수 있습니다. 저장된 필드와 덮어쓰기가 어떻게 결합되는지는 워크플로를 참고하세요.

워크플로 저장

PUT/v1/workflows/{name}

워크플로를 만들거나, 같은 이름이 있으면 교체합니다. 이름은 영문자나 숫자로 시작하며, 영문자, 숫자, _, ., -를 최대 128자까지 쓸 수 있습니다.

본문

promptstring필수

작업 내용. 최대 128 KiB.

modelstring

모델 ID. 생략하면 각 실행이 생성되는 시점의 기본 모델을 사용합니다.

filesarray

실행 요청과 같은 파일 항목. 이름은 각 실행이 만들어질 때 해석됩니다.

connectionsobject

에이전트에게 보이는 이름을 키로 하는 연결. {"ref": "<saved name>"} 항목을 권장합니다.

descriptionstring

워크플로가 하는 일과 기대하는 입력. 최대 500자.

input_schemaobject

각 실행의 input이 따라야 하는 JSON Schema. 일치하지 않는 실행은 400으로 거부됩니다. 입력과 출력 설명하기를 참고하세요.

output_schemaobject

각 실행의 출력이 따라야 하는 JSON Schema. 출력은 JSON이 되며, 출력이 일치하지 않는 실행은 실패합니다. 입력과 출력 설명하기를 참고하세요.

timeout_secondsinteger

1~3600. 생략하면 실행은 300을 사용합니다.

shellboolean

생략하면 실행은 true를 사용합니다.

webboolean | object

워크플로 실행의 웹 액세스. true이거나 allow와 search를 가진 객체입니다. 생략하면 꺼짐입니다.

워크플로에는 input, max_cost_micros, callback을 담을 수 없습니다. 이 값은 실행마다 지정합니다. 응답은 {"name": "investigate-payment"}입니다.

curl -X PUT $EPHEMERAL_URL/v1/workflows/investigate-payment \
  -H "Authorization: Bearer $EPHEMERAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Find out why this payment failed. Follow the playbook.",
    "model": "anthropic/claude-haiku-5.5",
    "files": [{ "file": "playbook.md" }],
    "connections": { "payments": { "ref": "payments-api", "allowed_methods": ["GET"] } },
    "timeout_seconds": 120,
    "shell": false
  }'

워크플로 시작

POST /v1/runs에 워크플로 이름과 이번 실행의 입력, 예산을 보냅니다. 함께 보내는 정의 필드는 이번 실행에 한해 저장된 값을 대체합니다. files와 connections는 컬렉션 전체를 교체합니다.

터미널

curl $EPHEMERAL_URL/v1/runs \
  -H "Authorization: Bearer $EPHEMERAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"workflow":"investigate-payment","input":{"payment_id":"pay_123"},"max_cost_micros":500000}'

워크플로가 없으면 요청이 400과 메시지 saved workflow not found로 실패합니다.

워크플로 목록

GET/v1/workflows

조직의 워크플로를 알파벳순으로, 각각 name이 있는 객체로 반환합니다. ?detail=true를 붙이면 description, input_schema, output_schema가 있는 워크플로는 그 값도 함께 포함됩니다. 전체 정의를 보려면 이름으로 워크플로를 조회하세요.

JSON

[{ "name": "investigate-payment" }, { "name": "weekly-report" }]

?detail=true를 붙이면 에이전트가 각 워크플로가 무엇을 기대하고 무엇을 반환하는지 확인할 수 있습니다.

JSON

[
  {
    "name": "weather",
    "description": "Current weather for a city. Input is a city name.",
    "input_schema": { "type": "object", "required": ["city"], "properties": { "city": { "type": "string" } } },
    "output_schema": { "type": "object", "required": ["city", "temperature_c", "summary"] }
  },
  { "name": "weekly-report" }
]

워크플로 조회

GET/v1/workflows/{name}

저장된 정의를 반환합니다. 인라인 연결의 자격 증명은 제거되고, URL의 쿼리 값은 가려집니다.

워크플로를 수정하려면 조회해서 변경한 뒤 PUT으로 다시 저장하세요. 연결의 인증 유형이 그대로라면, 비워 둔 자격 증명 필드는 저장된 값을 유지합니다.

워크플로 삭제

DELETE/v1/workflows/{name}

워크플로를 삭제하고 204 No Content를 반환합니다. 이미 해당 워크플로를 사용한 실행에는 영향이 없습니다.

워크플로에는 버전이 없습니다. 저장하거나 삭제하면 그 이름을 지정하는 다음 실행부터 적용됩니다.