04. 통합 카탈로그¶

CALL 노드가 할 수 있는 일의 전체 목록입니다. integration:에 아래 id를 적고, input:에 그 통합이 요구하는 값을 채우면 됩니다.

- id: 노드id
  name: 노드 이름
  type: CALL
  integration: llm_chat      # ← 여기
  input:                     # ← 통합마다 요구하는 항목이 다릅니다
    ...

전체 목록¶

id	이름	분류	연결 필요	하는 일
`http_request`	HTTP 요청	HTTP	없음	아무 HTTP API나 직접 호출
`llm_chat`	LLM Chat	AI	없음 (API 키)	AI에게 요약·분류·작문 시키기
`transform_jmespath`	Transform (JMESPath)	DATA	없음	JSON 데이터 가공·필터링
`dataset`	Dataset	DATA	없음	워크스페이스 데이터셋 읽고 쓰기
`slack_post_message`	Slack 메시지 발송	MESSAGING	Slack 연결	Slack 채널에 메시지 보내기
`httpbin_get`	HTTPBin GET	HTTP	없음	동작 확인용 테스트

연결이 필요 없는 것부터 쓰세요. http_request · llm_chat · transform_jmespath 이 셋만으로 웬만한 자동화는 처음부터 끝까지 만들 수 있습니다. OAuth 연결은 정말 그 서비스가 필요할 때만 하면 됩니다.

최신 목록 확인: 이 카탈로그는 늘어납니다. 지금 워크스페이스에서 쓸 수 있는 목록은 비주얼 에디터의 노드 팔레트에서, 또는 AI 비서를 연결했다면 "쓸 수 있는 통합 알려줘"로 확인할 수 있습니다.

`http_request`¶

아무 HTTP API나 직접 호출합니다. 가장 자유도가 높고, 가장 많이 쓰게 될 통합입니다.

입력¶

항목	필수	설명
`uri`	✅	호출할 주소. 표현식 사용 가능
`method`	✅	`GET` · `POST` · `PUT` · `DELETE` · `PATCH`
`mediaType`		Content-Type. 기본값 `application/json`
`queryParams`		쿼리 스트링 (`?a=1&b=2`)
`body`		요청 본문
`authenticate`		인증 헤더 묶음 (아래 참고)

예제 — 조회¶

- id: fetch-orders
  name: 주문 조회
  type: CALL
  integration: http_request
  timeout: 10s
  input:
    uri: "https://api.example.com/v1/orders"
    method: GET
    queryParams:
      status: "PAID"
      from: "${nodes.trigger.response.body.windowStart}"
    authenticate:
      authMethod: HEADERS
      data:
        Authorization: "Bearer ${secrets.EXAMPLE_API_TOKEN}"

예제 — 전송¶

- id: post-hook
  name: 외부 시스템에 통보
  type: CALL
  integration: http_request
  input:
    uri: "https://hooks.example.com/notify"
    method: POST
    body:
      orderId: "${nodes.trigger.response.body.orderId}"
      status: "confirmed"

출력¶

응답 본문이 그대로 출력됩니다.

${nodes.fetch-orders.response.body.data}          # 응답 본문의 data 필드
${nodes.fetch-orders.response.body.items.0.name}  # 배열 첫 번째 원소의 name

API 키는 반드시 ${secrets.*} 로. YAML에 토큰을 그대로 적으면 워크플로우를 복사·공유할 때 함께 새어나갑니다. → 08. 변수와 시크릿

`llm_chat`¶

AI를 부릅니다. 요약, 분류, 말투 바꾸기, 초안 쓰기 등에 씁니다.

특정 회사에 묶이지 않고 API 형식(계약) 을 고르는 방식입니다. 형식만 맞으면 어느 제공사든 쓸 수 있습니다.

입력¶

항목	필수	설명
`apiContract`	✅	`OPENAI_CHAT` 또는 `ANTHROPIC_MESSAGES`
`model`	✅	모델 id. 예: `gpt-4o-mini`, `claude-sonnet-4-6`
`apiKey`	✅	API 키. *`${secrets.}` 로 넣으세요**
`userPrompt`	✅	AI에게 시킬 내용
`systemPrompt`		역할·규칙 지정
`endpoint`		생략 시 계약별 기본 주소
`maxTokens`		최대 응답 길이. `ANTHROPIC_MESSAGES`는 생략 시 4096으로 전송
`temperature`		0~2. 지정했을 때만 전달됩니다

endpoint를 생략하면 이렇게 갑니다.

`apiContract`	기본 주소
`OPENAI_CHAT`	`https://api.openai.com/v1/chat/completions`
`ANTHROPIC_MESSAGES`	`https://api.anthropic.com/v1/messages`

계약만 호환되면 다른 곳도 됩니다 (Fireworks, Together, 직접 띄운 vLLM 등). endpoint에 주소를 적으세요.

예제¶

- id: summarize
  name: 매출 요약
  type: CALL
  integration: llm_chat
  timeout: 30s
  input:
    apiContract: OPENAI_CHAT
    model: gpt-4o-mini
    apiKey: "${secrets.OPENAI_API_KEY}"
    systemPrompt: "너는 이커머스 운영 담당자다. 숫자를 과장하지 말고 사실만 간결하게 전달한다."
    userPrompt: |
      아래 주문 데이터를 3줄로 요약해줘.
      총 매출과 주문 건수를 반드시 포함하고, 눈에 띄는 변화가 있으면 한 줄 덧붙여.

      데이터: ${nodes.aggregate.response.body.summary}

출력¶

필드	설명
`${nodes.summarize.response.body.content}`	AI가 쓴 텍스트
`${nodes.summarize.response.body.tokenUsage.totalTokens}`	사용 토큰 수
`${nodes.summarize.response.body.tokenUsage.promptTokens}`	입력 토큰
`${nodes.summarize.response.body.tokenUsage.completionTokens}`	출력 토큰

temperature 주의: 최신 Claude 모델 등 일부는 이 값을 받지 않고 400 에러를 냅니다. 필요 없으면 아예 빼세요.

비용은 본인 부담입니다. 이음새는 여러분의 API 키로 대신 호출해줄 뿐이고, 요금은 OpenAI·Anthropic 등에 직접 청구됩니다. 토큰이 걱정되면 maxTokens로 상한을 두세요.

AI 응답으로 분기하고 싶다면 → 06. 흐름 제어의 contains 연산자

`transform_jmespath`¶

JSON 데이터를 원하는 모양으로 바꿉니다. 필요한 필드만 뽑기, 조건에 맞는 것만 거르기, 개수 세기 등.

JMESPath 문법을 씁니다.

입력¶

항목	필수	설명
`expression`	✅	JMESPath 표현식
`data`		변환할 대상. 생략하면 `expression`을 뺀 나머지 `input` 전체

⚠️ 결과는 반드시 객체여야 합니다¶

CALL 노드의 출력은 JSON 객체여야 합니다. 배열이나 숫자를 그대로 내보내면 실패합니다. 중괄호로 감싸세요.

expression: "items[*].id"              # ❌ 배열 → 실패
expression: "{ids: items[*].id}"       # ✅ 객체 → 성공

expression: "length(items)"            # ❌ 숫자 → 실패
expression: "{count: length(items)}"   # ✅ 성공

자주 쓰는 패턴¶

# 특정 필드만 뽑아 배열로
expression: "{ids: data[*].orderId}"

# 조건으로 거르기 (백틱 주의)
expression: "{active: items[?status == `active`]}"

# 개수 세기 + 합계
expression: "{count: length(orders), total: sum(orders[*].amount)}"

# 필드 이름 바꾸기
expression: "{이름: customer.name, 금액: payment.total}"

# 여러 개를 한 번에
expression: "{건수: length(orders), 매출: sum(orders[*].amount), 첫주문: orders[0]}"

예제¶

- id: aggregate
  name: 주문 집계
  type: CALL
  integration: transform_jmespath
  input:
    expression: "{건수: length(@), 매출합계: sum([*].amount)}"
    data: "${nodes.fetch-orders.response.body.data | raw}"

| raw 를 꼭 붙이세요. 배열이나 객체를 다른 노드에 넘길 때 이 표시가 없으면 문자열로 변환되어 버립니다. → 05. 표현식으로 데이터 잇기

출력¶

expression 평가 결과가 그대로 출력됩니다.

${nodes.aggregate.response.body.건수}
${nodes.aggregate.response.body.매출합계}

`dataset`¶

워크스페이스 데이터셋에 행을 읽고 씁니다. 실행 사이에 값을 기억해야 할 때 씁니다 (예: 이미 처리한 주문 번호, 누적 집계).

데이터셋은 미리 만들어 두어야 합니다. → 09. 데이터셋

입력¶

항목	필수	설명
`datasetTitle`	✅	대상 데이터셋 제목 (워크스페이스 안에서 고유)
`operation`	✅	`QUERY` · `INSERT` · `UPDATE` · `DELETE`
`data`	INSERT/UPDATE	저장할 값. 데이터셋 컬럼에 없는 키는 버려집니다
`rowId`	UPDATE/DELETE	대상 행 id
`limit`		QUERY 최대 행 수. 기본 100, 최대 1000
`offset`		QUERY 시작 위치

예제¶

# 읽기
- id: load-log
  type: CALL
  integration: dataset
  input:
    datasetTitle: "처리이력"
    operation: QUERY
    limit: 50

# 쓰기
- id: save-log
  type: CALL
  integration: dataset
  input:
    datasetTitle: "처리이력"
    operation: INSERT
    data:
      주문번호: "${nodes.trigger.response.body.orderId}"
      처리시각: "${nodes.trigger.response.body.windowEnd}"

출력¶

operation	출력 모양	참조 예
`QUERY`	`{ rows: [ {id, ...컬럼}, ... ] }`	`${nodes.load-log.response.body.rows \\| raw}`
`INSERT` / `UPDATE`	`{ id, ...컬럼 }`	`${nodes.save-log.response.body.id}`
`DELETE`	`{ deleted: true, id }`	`${nodes.del.response.body.deleted}`

`slack_post_message`¶

연결된 Slack 워크스페이스의 채널에 메시지를 보냅니다.

사전 준비¶

Connections 화면에서 Slack을 연결합니다. → 07. 연결 관리
메시지를 보낼 채널에 이음새 봇을 초대합니다. 채널에서 /invite @이음새. 이 단계를 빠뜨리면 not_in_channel 에러가 납니다.

입력¶

항목	필수	설명
`channel`	✅	채널 ID (예: `C0123ABCDEF`) 또는 채널명
`text`	✅	메시지 본문

비주얼 에디터에서는 channel을 연결된 Slack의 채널 목록에서 골라서 넣을 수 있습니다.

예제¶

- id: notify
  name: Slack 발송
  type: CALL
  integration: slack_post_message
  input:
    channel: "C0123ABCDEF"
    text: |
      📊 오늘의 매출 요약

      ${nodes.summarize.response.body.content}

출력¶

필드	설명
`${nodes.notify.response.body.ok}`	성공 여부
`${nodes.notify.response.body.channel}`	발송된 채널
`${nodes.notify.response.body.ts}`	메시지 타임스탬프

⚠️ 이 통합은 "실제로 발송"합니다¶

slack_post_message는 부수효과(side effect) 가 있는 통합으로 표시되어 있습니다. AI 비서(MCP)로 실행할 때 이런 워크플로우는 바로 돌지 않고 승인을 한 번 묻습니다. AI가 실수로 고객에게 메시지를 뿌리는 일을 막기 위한 장치입니다.

`httpbin_get`¶

동작 확인용 테스트 통합입니다. 보낸 값을 그대로 돌려주는 httpbin.org를 호출합니다. 인증이 필요 없어서 "워크플로우가 제대로 도는지"만 빠르게 확인할 때 좋습니다.

항목	필수	설명
`query`	✅	되돌려받을 값. URL 안전 문자만 (영문·숫자·`_` `.` `~` `-`)

- id: ping
  name: 동작 확인
  type: CALL
  integration: httpbin_get
  input:
    query: "hello"

출력: ${nodes.ping.response.body.args} · ${nodes.ping.response.body.url} · ${nodes.ping.response.body.origin}

한글이나 공백을 넣으면 저장이 거부됩니다. 테스트 전용이니 실제 자동화에는 쓰지 마세요.

모든 CALL 노드가 함께 쓸 수 있는 옵션¶

통합 종류와 상관없이 CALL 노드에 붙일 수 있습니다.

- id: fetch
  type: CALL
  integration: http_request
  timeout: 10s              # 이 시간 넘으면 실패 처리
  retry-policy:             # 실패하면 다시 시도
    max-attempts: 3
    backoff:
      type: EXPONENTIAL
      initial-delay: 500ms
    retry-on: ["429", "5xx"]
  input:
    ...

자세한 설정은 → 10. 실행과 모니터링

다음 → 05. 표현식으로 데이터 잇기