에이전트 API 액션 응답 포맷 - 일반 형태

9 분 읽기가이드 기준일: 2026. 10. 14.노션 원문 보기 ↗

목적

이 문서는 API Action 기능을 통해 챗봇이 외부 서버로부터 답변에 필요한 구조화된 데이터를 응답으로 받기 위한 JSON 권장 규격을 정의합니다.

외부 서버(사용자 백엔드)는 기존처럼 자유로운 JSON 응답을 반환할 수도 있으며, 반드시 이 규격을 따라야 하는 것은 아닙니다.

다만, 외부 서버가 이 문서의 규격에 맞춰 응답을 반환하면 챗봇이 응답 내용을 더 안정적으로 이해할 수 있어, 답변 정확도와 응답 품질 향상에 도움이 됩니다.

이 규격은 시각적인 카드 표시용(sidetalk.card.v1)이 아닌, 챗봇이 API 응답을 이해하고 자연어 답변을 생성하기 위한 일반 API 결과 포맷입니다.

개요

응답 구조 (Top-level)

응답의 최상위에는 스키마 버전, 성공 여부, 실제 데이터가 포함되어야 합니다.

필드	타입	필수	설명
schema	String	예	프로토콜 버전을 식별합니다. "sidetalk.api-result.v1" 고정 값을 사용하세요.
success	Boolean	예	요청 처리 성공 여부입니다.
data	Object	조건부	성공 응답일 때 포함하는 실제 데이터입니다.
summary	String	아니오	응답 내용을 한 줄로 요약한 텍스트입니다. 필수는 아니지만, 챗봇이 내용을 더 빠르게 이해하는 데 도움이 됩니다.
error	Object	조건부	실패 응답일 때 포함하는 오류 정보입니다.
meta	Object	아니오	출처, 페이지 정보, 상태코드 등 부가 정보를 담습니다.

기본 규칙

이 규격은 권장 구조이며, 자유로운 JSON 응답도 사용할 수 있습니다.

다만, 챗봇이 응답을 더 안정적으로 이해할 수 있도록 가능하면 아래 구조를 따르는 것을 권장합니다.

응답 예시는 어디까지나 예시이며, data 내부 구조는 API의 목적에 맞게 자유롭게 설계할 수 있습니다.
가능하면 모든 응답에 schema, success 필드를 포함하는 것을 권장합니다.
success: true 인 경우 data 필드를 포함하는 것을 권장합니다.
success: false 인 경우 error 필드를 포함하는 것을 권장합니다.
summary 는 필수는 아니지만, 포함하면 챗봇이 응답 내용을 더 빠르게 파악하는 데 도움이 됩니다.
meta 는 필요할 때만 포함하면 됩니다.
data 는 정해진 고정 스키마가 있는 것은 아니며, 답변에 필요한 정보만 포함하면 됩니다.
기존의 자유로운 JSON 응답도 계속 사용할 수 있지만, 의미가 명확한 공통 구조를 사용할수록 AI 응답 품질이 더 좋아질 수 있습니다.

즉, 성공 응답은 아래 구조를 권장합니다.

JSON

{
  "schema": "sidetalk.api-result.v1",
  "success": true,
  "data": {}
}

실패 응답은 아래 구조를 권장합니다.

JSON

{
  "schema": "sidetalk.api-result.v1",
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "오류 메시지"
  }
}

하위 객체 명세

1. Error 객체

요청 실패 시 사용하는 공통 객체입니다.

필드	타입	필수	설명
code	String	예	오류 코드입니다. 예: `"NOT_FOUND"`, `"INVALID_PARAMETER"`
message	String	예	오류 내용을 설명하는 텍스트입니다.
detail	String	아니오	보다 상세한 오류 설명입니다.

2. Meta 객체

부가 정보가 필요할 때 사용하는 선택 객체입니다.

필드	타입	필수	설명
source	String	아니오	데이터 출처입니다. 예: `"public_api"`, `"internal_api"`
page	Number	아니오	현재 페이지 번호입니다.
totalCount	Number	아니오	전체 데이터 개수입니다.
statusCode	Number	아니오	원본 API의 HTTP 상태코드입니다.

data 필드 작성 방식

data 는 이 문서에서 고정된 하위 구조를 강제하지 않습니다.

응답 예시는 예시일 뿐이며, 실제로는 API 목적에 맞는 정보만 포함하면 됩니다.

예를 들어 다음과 같은 방식으로 자유롭게 구성할 수 있습니다.

목록 데이터: items, count
단일 데이터: item
상태 정보: status
예약/주문/상품 등 도메인별 핵심 정보
챗봇 답변에 직접 필요한 값들

중요한 점은 data 안에 불필요하게 깊은 중첩 구조를 넣기보다는, 챗봇이 바로 이해할 수 있도록 간단하고 의미가 명확한 필드명으로 구성하는 것입니다.

예:

name
status
address
date
time
count
items

응답 예시 (JSON)

1) 성공 응답 - 목록 데이터

JSON

{
  "schema": "sidetalk.api-result.v1",
  "success": true,
  "summary": "검색 결과 3건",
  "data": {
    "items": [
      {
        "name": "서울지점",
        "status": "영업중",
        "address": "서울특별시 강남구 테헤란로 123"
      },
      {
        "name": "부산지점",
        "status": "영업중",
        "address": "부산광역시 해운대구 센텀로 45"
      },
      {
        "name": "대구지점",
        "status": "휴무",
        "address": "대구광역시 수성구 동대구로 88"
      }
    ],
    "count": 3
  },
  "meta": {
    "source": "public_api",
    "statusCode": 200
  }
}

2) 성공 응답 - 단일 데이터

JSON

{
  "schema": "sidetalk.api-result.v1",
  "success": true,
  "summary": "예약 정보를 찾았습니다.",
  "data": {
    "item": {
      "reservationNo": "RSV-20260702-ABCD12",
      "name": "홍길동",
      "date": "2026-07-05",
      "time": "14:00",
      "status": "예약완료"
    }
  }
}

3) 성공 응답 - 요약 중심 데이터

JSON

{
  "schema": "sidetalk.api-result.v1",
  "success": true,
  "summary": "오늘 주문은 총 2건입니다.",
  "data": {
    "count": 2,
    "items": [
      {
        "orderNo": "20260702-1001",
        "productName": "보물상자 A",
        "status": "배송준비중"
      },
      {
        "orderNo": "20260702-1002",
        "productName": "보물상자 B",
        "status": "배송완료"
      }
    ]
  }
}

4) 실패 응답

JSON

{
  "schema": "sidetalk.api-result.v1",
  "success": false,
  "summary": "예약 정보를 찾을 수 없습니다.",
  "error": {
    "code": "NOT_FOUND",
    "message": "일치하는 예약 정보가 없습니다.",
    "detail": "reservationNo 값에 해당하는 데이터가 존재하지 않습니다."
  },
  "meta": {
    "source": "public_api",
    "statusCode": 404
  }
}

정리

이 문서의 핵심은 외부 서버가 반환하는 응답을 AI가 이해하기 쉬운 공통 구조로 맞추는 것입니다.

반드시 지켜야 하는 기본 구조는 다음과 같습니다.

성공 응답: schema, success, data
실패 응답: schema, success, errors

그리고 summary 는 필수는 아니지만, 챗봇이 응답 내용을 더 빠르게 이해하고 더 자연스럽게 답변하는 데 도움이 되므로 포함을 권장합니다.

data 내부 구조는 고정되어 있지 않으며, API 목적에 맞게 자유롭게 설계할 수 있습니다.

다만, 챗봇이 답변에 바로 활용할 수 있도록 간단하고 명확한 구조로 작성하는 것을 권장합니다.