API로 플로우 작성 및 검증

v3 API에서 플로우 에이전트를 만들거나 수정할 때는 flow 필드를 쓰세요. flow는 외부 통합을 위한 공개 그래프 계약이에요. flow_data는 기존 빌더 호환용 필드이고, 둘을 함께 보내면 flow가 우선해요.

GPT-Live, Grok Voice, Gemini Live는 single_prompt 에이전트에서만 지원해요. type: "flow" 에이전트에 gpt_live, grok_voice, gemini_live 런타임을 보내면 거부되고, 기존 Flow 에이전트는 pipeline 런타임을 써요. flow.nodes[].data.llm은 기존 Flow의 노드별 LLM 설정으로 보존할 수 있지만 네이티브 실시간 런타임 기능은 아니에요.

필드 선택

필드	상태	사용 시점
`flow`	권장	새 플로우 만들기, 전체 그래프 교체, API·SDK·MCP 기반 작성
`flow_data`	지원 종료 예정	기존 빌더 형태를 이미 저장하거나 읽는 통합의 호환 유지
둘 다 생략	허용	`type="flow"`로 만들면 서버가 기본 그래프를 만들어요
둘 다 전송	허용	`flow`만 처리하고 `flow_data`는 검증 전에 무시해요

flow와 flow_data는 모두 그래프 전체를 바꿔요. 일부 필드만 보내 그래프를 부분 수정할 수는 없어요.

PATCH /v3/agents/{agent_id}에서 flow 필드를 생략하면 지금 그래프를 유지해요. flow: null은 거부돼요.

그래프 수정과 revision 보호

GET /v3/agents/{agent_id}?version=current 응답의 head_revision과 flow_revision을 읽고, 같은 상태를 기준으로 그래프 전체를 PATCH하세요. 본문 최상위에 두 값을 expected_head_revision, expected_flow_revision으로 넘기세요. REVISION_CONFLICT가 돌아오면 최신 그래프를 자동으로 가져와 다시 저장하지 마세요. 사용자에게 충돌을 알리고, 사용자가 확인한 최신 그래프와 의도한 변경을 병합한 뒤 새 revision으로 다시 요청하세요.

그래프 구조

flow는 nodes와 edges로 이뤄져요.

항목	필수 값	설명
`nodes[].id`	필수	그래프 안에서 유일한 노드 ID
`nodes[].type`	필수	`begin`, `conversation`, `condition`, `api`, `endCall` 같은 노드 타입
`nodes[].position`	필수	캔버스 좌표. 서버가 좌표를 만들지 않아요
`nodes[].data`	선택	노드별 설정. 라우팅 키는 `edges`로 표현해요
`edges[].source`	필수	출발 노드 ID
`edges[].target`	필수	도착 노드 ID
`edges[].condition`	필수	`ai`, `logic`, `fallback` 가운데 하나
`edges[].skip_user_response`	선택	사용자 응답을 기다리지 않고 다음 노드로 이동할지

nodes[].data에 transitions, logicalTransitions, logical_transitions, globalNodeSettings, global_node_settings를 넣지 마세요. 기존 빌더 내부 키라서 flow에서는 edges와 global_node_setting으로 표현해요.

노드별 data 스키마

flow.nodes는 BeginFlowNode, ConversationFlowNode 같은 노드 타입별 스키마로 나뉘어요. nodes[].data도 노드 타입별 엄격한 스키마를 따르고, 문서에 없는 키를 보내면 FLOW_V2_INVALID로 거부돼요. 작성할 때는 nodes[].type에 맞는 v2 data 스키마를 참고하세요. 예를 들어 begin은 BeginFlowNodeData, conversation은 ConversationFlowNodeData, api는 ApiFlowNodeData, transferCall은 TransferCallFlowNodeData를 써요. 스키마 레지스트리에서도 같은 계약을 확인할 수 있어요.

스키마	용도
`/v3/schemas/flow-schema/flow-data`	전체 `flow` 그래프 스키마
`/v3/schemas/flow-schema/node-{type}`	그 노드의 v2 래퍼와 `data` 스키마

위치	이름 규칙
`flow.nodes`, `flow.edges`, `edge.condition`	v3 API 기본 규칙인 snake_case를 써요
`edges[].skip_user_response`	기존 `isSkipUserResponse` 전환을 `edges` 필드로 올린 값이에요
`nodes[].data.global_node_setting`	기존 `globalNodeSettings`를 대체하는 v2 글로벌 노드 표시예요. `conversation`, `sendSms`, `endCall`에서만 허용해요
`nodes[].data`의 일반 노드 설정	snake_case 키를 써요. 예: `first_line_type`, `prompt_type`, `tool_id`, `api_configuration`, `transfer_configuration`

v2 flow는 라우팅과 글로벌 설정을 노드 밖으로 옮겼어요. 기존 빌더(flow_data)에서 nodes[].data 안에 두던 키는 v2에서 아래처럼 자리가 바뀌어요.

기존 빌더(`flow_data`)의 `node.data`	v2 `flow`에서의 표현
`transitions`	`edges`(분기 조건은 `edge.condition`)
`logicalTransitions`, `logical_transitions`	condition 노드 분기는 `edge.condition`의 `logic`
`globalNodeSettings`, `global_node_settings`(복수)	`nodes[].data.global_node_setting`(단수 표시)

nodes[].data에 위 빌더 내부 키를 넣으면 저장이 거부돼요. 각 노드 타입의 정확한 data 필드 목록은 /v3/schemas/flow-schema/node-{type}에서 확인하세요. 노드별로 알아 둘 점은 다음과 같아요.

사전 멘트: prompt_type, prompt, static_sentence(사전 멘트 모드 none, static, dynamic)는 conversation, api, tool, sendSms, transferCall, endCall에서 받아요. transferCall의 warm 위스퍼 멘트는 별도 필드(warm_transfer_prompt, warm_transfer_static_sentence)예요.
transferAgent: agent, preserve_chat_context만 받아요. prompt는 없어요.
conversation의 지식 베이스: knowledge.rag_enabled와 knowledge.knowledge_ids로 설정해요. 최상위 knowledge_ids는 받지 않아요.
extraction의 추출 프롬프트: extraction_configuration.extraction_prompt에 적어요. 최상위 prompt는 받지 않아요.
note: 에디터 주석 노드예요. content, width, height만 받고 name은 받지 않아요. note로 향하거나 note에서 나가는 전환은 저장이 거부돼요.

플로우 에이전트 만들기 예시

curl https://client-api.tryvox.co/v3/agents \
  -H "Authorization: Bearer $VOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "예약 확인 플로우",
    "type": "flow",
    "flow": {
      "nodes": [
        {
          "id": "begin",
          "type": "begin",
          "position": { "x": 0, "y": 0 },
          "data": {
            "name": "시작",
            "first_line_type": "aiFirst"
          }
        },
        {
          "id": "confirm",
          "type": "conversation",
          "position": { "x": 360, "y": 0 },
          "data": {
            "name": "예약 확인",
            "prompt_type": "dynamic",
            "prompt": "예약 정보를 확인하고 변경이 필요한지 물어보세요."
          }
        },
        {
          "id": "end",
          "type": "endCall",
          "position": { "x": 720, "y": 0 },
          "data": {
            "name": "종료",
            "prompt_type": "static",
            "static_sentence": "확인했습니다. 감사합니다."
          }
        }
      ],
      "edges": [
        {
          "source": "begin",
          "target": "confirm",
          "condition": { "type": "fallback" }
        },
        {
          "source": "confirm",
          "target": "end",
          "condition": {
            "type": "ai",
            "prompt": "사용자가 예약 확인을 마쳤을 때"
          }
        }
      ]
    }
  }'

전환 조건

edge.condition은 type으로 구분해요.

ai
logic
fallback

자연어 조건이에요. 사용자의 발화와 지금 대화 맥락을 보고 다음 노드로 이동할지 판단해요.

{
  "type": "ai",
  "prompt": "사용자가 상담원 연결을 요청했을 때"
}

조건 노드에서 변수 값을 비교할 때 써요. equations는 하나 이상이어야 해요.

{
  "type": "logic",
  "operator": "&&",
  "equations": [
    {
      "left": "reservation_status",
      "operator": "equals",
      "right": "confirmed"
    }
  ]
}

같은 source 노드의 다른 조건이 맞지 않을 때 이동하는 기본 경로예요.

{
  "type": "fallback"
}

글로벌 노드

글로벌 노드는 전환이 아니라 노드에 표시해요. node.data.global_node_setting이 있으면 글로벌 노드로 처리해요. global_node_setting은 conversation, sendSms, endCall 노드에서만 허용해요. 다른 노드 타입에 넣으면 저장이 거부돼요. 웹 빌더도 이 세 타입에서만 글로벌 노드를 지원해요.

{
  "id": "human-help",
  "type": "conversation",
  "position": { "x": 360, "y": 240 },
  "data": {
    "name": "상담원 연결 안내",
    "prompt_type": "dynamic",
    "prompt": "상담원 연결 절차를 안내하세요.",
    "global_node_setting": {
      "condition": {
        "type": "ai",
        "prompt": "사용자가 사람 상담원을 원할 때"
      }
    }
  }
}

글로벌 노드의 조건은 ai만 지원해요. logic이나 fallback은 저장할 수 없어요.

저장 검증

flow를 저장할 때는 자동 수정 없이 검증해요. 불완전한 그래프를 서버가 추측해서 고치지 않으니 그래프를 완성해서 보내세요. 같은 flow 그래프를 저장하지 않고 미리 검증하려면 POST /v3/agents/validate-flow를 호출하세요.

curl "https://client-api.tryvox.co/v3/agents/validate-flow?level=all" \
  -H "Authorization: Bearer $VOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "flow": {
      "nodes": [
        {
          "id": "begin",
          "type": "begin",
          "position": { "x": 0, "y": 0 },
          "data": {
            "name": "시작",
            "first_line_type": "aiFirst"
          }
        },
        {
          "id": "end",
          "type": "endCall",
          "position": { "x": 320, "y": 0 },
          "data": {
            "name": "종료"
          }
        }
      ],
      "edges": [
        {
          "source": "begin",
          "target": "end",
          "condition": { "type": "fallback" }
        }
      ]
    }
  }'

응답 필드	의미
`valid`	저장을 막는 치명적 오류가 없으면 `true`
`errors`	저장을 막는 치명적 오류 목록
`advisories`	저장은 되지만 실행 중 동작이 예상과 달라질 수 있는 런타임 주의 항목 목록

validate-flow는 저장하지 않고 검증해서, 형식이 잘못된 flow도 일반 에러 응답 대신 valid=false 엔벨로프로 돌려줘요. 예를 들어 position 누락, 잘못된 condition.type, 지원하지 않는 logic 연산자는 errors[].code = "flow_v2_schema_invalid"로 돌아와요. level 쿼리로 응답에 담을 항목 범위를 정할 수 있어요.

`level`	반환 내용
`critical`	기본값. 저장을 막는 `errors`만 돌려줘요
`runtime`	`advisories`만 돌려줘요. `valid`는 치명적 오류 여부를 계속 반영해요
`all`	`errors`와 `advisories`를 모두 돌려줘요

치명적 오류가 있는 그래프라도 변환할 수 있으면 런타임 주의 항목을 함께 돌려줘요. 그래서 level=runtime에서는 errors가 비어 있어도 valid=false일 수 있어요. level=all에서는 저장을 막는 오류와 런타임 주의 항목을 함께 확인할 수 있어요. 런타임 주의 항목에는 연결되지 않은 skip·fallback 전환, begin에서 도달할 수 있는 종료 노드가 없는 경우가 들어가요. 저장은 막지 않지만 실제 통화에 쓰기 전에 고치세요. 도구, 지식 베이스, 파일, 다른 에이전트 이관처럼 외부 리소스를 참조하는 필드는 값을 보냈다면 실제로 있는지와 워크스페이스 접근 권한을 검증해요. 비어 있는 참조는 작성 중인 초안으로 저장할 수 있지만, 잘못된 ID나 다른 워크스페이스의 ID는 저장이 거부돼요. 런타임 주의 항목이 있는 그래프도 이 참조 검증은 거쳐요.

상황	결과
`nodes` 또는 `edges` 누락	저장 거부
`position` 누락	저장 거부
`begin.data.first_line_type` 누락	저장 거부
`begin` 노드가 0개 또는 2개 이상	저장 거부
`begin` 노드에 `fallback` 전환 없음	저장 거부
`begin`에서 `fallback`이 아닌 조건 사용	저장 거부
`begin`에서 `skip_user_response=true` 사용	저장 거부
전환의 `source` 또는 `target`이 존재하지 않는 노드 ID	저장 거부
노드 ID 또는 전환 ID 중복	저장 거부
`logic` 전환이 조건 노드가 아닌 곳에서 출발	저장 거부
`logic` 조건의 `equations`가 비어 있음	저장 거부
지원하지 않는 `logic` 연산자 사용	저장 거부
`source`별 `fallback` 전환이 2개 이상	저장 거부
같은 `source`에 같은 조건 전환이 2개 이상	저장 거부
`global_node_setting`이 객체가 아니거나 비어 있거나 `ai` 조건이 아님	저장 거부
`conversation`/`sendSms`/`endCall`이 아닌 노드에 `global_node_setting` 포함	저장 거부
`note` 노드에 연결된 전환(`source` 또는 `target`이 note)	저장 거부
`transitions`, `logicalTransitions`, `logical_transitions`, `globalNodeSettings`, `global_node_settings` 포함	저장 거부
문서화되지 않은 `nodes[].data` 최상위 키 포함	저장 거부
제공한 도구, 지식 베이스, 파일, 이관 대상 에이전트 참조가 없거나 접근 불가	저장 거부
`function` 또는 기존 `knowledge` 노드 포함	`flow` 쓰기 거부

오래된 그래프를 조회하면 flow에 보이지 않는 빌더 내부 분기가 있을 수 있어요. 이런 그래프는 flow로 다시 저장할 때 거부될 수 있으니, 기존 빌더 형태를 정리한 뒤 다시 저장하세요.

지원 종료 예정 경로

새 통합에서는 아래 경로를 쓰지 마세요.

flow_data: 기존 빌더 그래프예요. 읽기와 쓰기는 호환용으로만 유지해요.
POST /v3/agents/validate-flow-data: flow_data 전용 검증이에요. flow 검증은 POST /v3/agents/validate-flow를 쓰세요.
POST /v3/agents/autofix-flow-data: flow_data 보정 도구예요.
POST /v3/flow-data/autofix: flow_data 보정 도구예요.
sourceHandle, targetHandle, transitions, logicalTransitions, globalNodeSettings: flow 작성에는 쓰지 않아요.

마이그레이션

조회 코드를 flow로 바꾸기

GET /v3/agents/{agent_id} 응답에서 flow_data 대신 flow를 읽으세요.

작성 코드를 flow로 바꾸기

POST /v3/agents와 PATCH /v3/agents/{agent_id}에서 flow를 보내고 flow_data는 보내지 마세요.

검증 호출 정리하기

validate-flow-data와 autofix-flow-data 호출을 없애세요. 저장 전에 검증하려면 POST /v3/agents/validate-flow를 쓰세요.

빌더 내부 키 없애기

sourceHandle, transitions, globalNodeSettings 같은 내부 키를 없애고 edges[].condition과 global_node_setting으로 바꾸세요.

노드 data 키를 snake_case로 바꾸기

firstLineType, promptType, apiConfiguration 같은 키를 first_line_type, prompt_type, api_configuration으로 바꾸세요.

LLM 작성 체크리스트

LLM이나 MCP 클라이언트가 flow를 직접 작성할 때는 아래 순서로 payload를 조립하세요.

flow_data 대신 flow만 쓰세요.
모든 노드에 id, type, position을 넣으세요.
begin 노드에는 data.first_line_type을 넣고, begin에서 나가는 전환은 fallback 하나로 두세요.
전환은 edges[].condition.type을 ai, logic, fallback 가운데 하나로 표현하세요.
logic 조건은 조건 노드에서만 시작하게 하고, equations를 하나 이상 넣으세요.
node.data에는 snake_case 키만 쓰세요.
node.data에는 transitions, logicalTransitions, globalNodeSettings를 넣지 마세요.
저장하기 전에 POST /v3/agents/validate-flow?level=all을 호출해 errors를 모두 해결하세요.
프롬프트만 수정할 때는 기존 data.builtInTools 값을 유지하세요. 기본 도구 목록을 다시 만들지 마세요.
Flow 에이전트는 pipeline 런타임만 써요. runtime.type에 "gpt_live", "grok_voice", "gemini_live"를 보내지 마세요. 기존 Flow를 수정할 때 flow.nodes[].data.llm 노드별 LLM 설정은 보존하지만 네이티브 실시간 기능으로 해석하지 않아요.

시작하기

구축

배포

발신

모니터링

설정

정책

API로 플로우 작성 및 검증

필드 선택

그래프 수정과 revision 보호

그래프 구조

노드별 data 스키마

플로우 에이전트 만들기 예시

전환 조건

글로벌 노드

저장 검증

지원 종료 예정 경로

마이그레이션

LLM 작성 체크리스트

관련 문서

​필드 선택

​그래프 수정과 revision 보호

​그래프 구조

​노드별 data 스키마

​플로우 에이전트 만들기 예시

​전환 조건

​글로벌 노드

​저장 검증

​지원 종료 예정 경로

​마이그레이션

​LLM 작성 체크리스트

​관련 문서

필드 선택

그래프 수정과 revision 보호

그래프 구조

노드별 data 스키마

플로우 에이전트 만들기 예시

전환 조건

글로벌 노드

저장 검증

지원 종료 예정 경로

마이그레이션

LLM 작성 체크리스트

관련 문서