API 요청 액션 매뉴얼
AI 에이전트에 대한 기본 설명은 아래 매뉴얼을 참고해주세요.
API 요청 액션이란?
API 요청 액션은 외부 시스템에 정보를 요청하고, 응답 결과에 따라 필요한 작업을 수행하는 기능입니다.
외부 시스템에서 반환하는 응답은 자유로운 JSON 형식으로도 사용할 수 있지만, 사이드톡 매뉴얼에 안내된 권장 형식에 맞춰 반환하면 챗봇이 응답 내용을 더 안정적으로 이해할 수 있어 답변 정확도와 응답 품질 향상에 도움이 됩니다.
요청 방식을 선택하면 설정 탭에서 해당 방식에 맞는 입력 폼이 표시됩니다.
이전 액션 데이터 참조하기
에이전트 실행 중 수집한 데이터(입력폼, API 응답, 테이블 조회 결과 등)는 요청 키 또는 값에 아래 형식으로 삽입할 수 있습니다.
{{$action[n].json.변수명}}구성 설명
$action[n]: 에이전트 실행 중 n번째로 실행된 액션의 결과.json: 해당 액션에서 저장된 JSON 데이터 객체.변수명: 그 JSON 객체 안에서 참조하려는 필드명
즉,
{{$action[n].json.변수명}}는- “n번째 액션에서 얻은 JSON 데이터 안의 특정 값” 을 의미합니다.
여기서
n은 에이전트의 실행 순서를 의미합니다.예를 들어, 첫 번째로 실행된 액션의 값을 참조하려면 아래와 같이 입력할 수 있습니다.
{{$action[1].json.변수명}}예시
첫 번째 액션의 응답이 아래와 같다고 가정해보겠습니다.
JSON
{
"schema": "sidetalk.api-result.v1",
"success": true,
"summary": "검색 결과 1건",
"data": {
"items": [
{
"name": "서울지점",
"status": "영업중"
}
],
"count": 1
}
}이 경우 아래와 같이 값을 참조할 수 있습니다.
{{$action[1].json.schema}}:sidetalk.api-result.v1{{$action[1].json.summary}}:검색 결과 1건{{$action[1].json.success}}:true{{$action[1].json.data.count}}:1{{$action[1].json.data.items[0].name}}:서울 지점
API 응답 형식 안내
API 응답 형식은 사용 목적에 따라 아래 문서를 참고해주세요.
1. 일반 응답 형식
일반적인 데이터 응답을 받아 챗봇이 자연어 답변을 생성하도록 하려면 아래 문서를 참고해주세요.
2. 카드 응답 형식
텍스트 카드, 이미지 카드, 리스트 카드 등 시각적인 카드 형태로 바로 표시하려면 아래 문서를 참고해주세요.
참고사항
- 일반 응답 형식은 카드 UI로 직접 표시되지 않으며, 챗봇이 응답 내용을 해석해 자연어 답변을 생성할 때 사용됩니다.
- 카드 응답 형식은 응답이 반환되는 즉시 카드 형태로 표시됩니다.
- API 응답에 필요한 데이터는 가능한 한 의미가 명확한 구조로 정리해 반환하는 것을 권장합니다.