Actions

대화 중 AI 에이전트가 할 수 있는 작업을 정의하세요. 실시간 API 데이터로 질문에 답하고, 리드와 시장 조사 데이터를 수집하고, 사용자 지정 작업을 수행할 수 있습니다.

Quickchat AI 에이전트에는 두 종류의 Action이 있습니다.

Quickchat AI Actions는 기본 제공되므로 켜고 설정하기만 하면 됩니다.

• 상담원 연결은 대화를 사람에게 전달합니다.
• 스마트 데이터 수집은 채팅 중 리드와 기타 데이터를 수집합니다.

사용자 지정 Actions는 Quickchat AI 외부와 연결됩니다.

• API Actions는 모든 HTTP 엔드포인트를 호출합니다. 이 페이지에서 설명합니다.
• MCP Actions는 MCP 서버 전체를 한 번에 연결합니다.
• Google Sheets는 클릭 한 번으로 기록용 Action을 설정하는 바로 연결 기능입니다.

모든 Action은 AI Action 변수를 통해 실시간 대화 데이터를 읽을 수 있습니다. Jira 예시에서는 처음부터 끝까지 Action을 만듭니다.

선택적으로 사용할 설정 도구

• Action 실행 조건 확인. Action을 실행하지 않고 제공한 예시 메타데이터로 조건을 평가합니다.

• 예시 MCP 연결 확인. Cloudflare 문서 또는 Microsoft Learn 엔드포인트에 한해 초기화하고 도구 목록을 조회합니다. 로그인하거나 도구를 실행하지 않습니다.

사용자 지정 Actions

사용자 지정 Actions를 사용하면 AI가 대화 중 외부 도구를 호출하여 내부 시스템을 검색하고, 티켓을 만들고, 알림을 보내거나, 지식 베이스에 없는 최신 데이터를 가져올 수 있습니다. Actions 및 MCPs의 사용자 지정 Actions 섹션에 있습니다.

만들려면 + Action 추가를 클릭하세요. 드롭다운에는 다음 옵션이 있습니다.

• API Action: HTTP를 통해 모든 REST 엔드포인트를 호출합니다. 가장 범용적인 옵션으로 URL이 있고 JSON을 받는 서비스에 사용하세요.
• MCP: 클릭 한 번으로 외부 MCP 서버에 연결하고 서버가 제공하는 도구를 AI가 사용하도록 합니다. MCP Actions를 참고하세요.
• HubSpot Action: HubSpot CRM에 대한 사전 구성 연결입니다. API 토큰을 직접 관리하지 않고 연락처, 거래, 티켓을 처리하며 티켓에 비공개 메모를 추가할 수 있습니다.
• Discord Action: 편집 가능한 지원 및 콘텐츠 관리 API Action 템플릿을 설치합니다. 본인의 Discord 앱이 필요합니다. Discord Actions를 참고하세요.
• Google Sheets: 연결한 스프레드시트를 읽고 씁니다.
• Shopify MCP: Shopify Storefront MCP 서버를 통해 Shopify 스토어를 연결합니다. AI가 카탈로그와 스토어 정책을 검색하고, 제품 정보를 읽고, 장바구니를 만들 수 있습니다. 시나리오당 Shopify MCP Action은 하나만 사용할 수 있습니다. 주문 조회는 포함하지 않습니다. 아래 참고 사항을 확인하세요.

참고

+ Action 추가 버튼 옆의 남은 수: N은 플랜에서 활성 상태로 유지할 수 있는 Action 수를 표시합니다. 이와 별개로 에이전트 하나는 플랜과 관계없이 전체 Actions를 최대 15개까지 가질 수 있습니다. 활성 Actions가 더 필요하면 플랜을 업그레이드하거나 문의하세요.

주문 상태는 별도의 Action입니다

Shopify Storefront MCP는 고객용이며 주문 데이터를 제공하지 않습니다. 따라서 이것만 연결한 AI 에이전트는 고객 주문을 조회할 수 없습니다. 주문 상태는 Shopify Admin API를 읽는 별도의 주문 상태 확인 API Action에서 가져옵니다. 이 Action은 Shopify App Store에서 Quickchat 앱을 설치하면 자동으로 설정됩니다. URL을 붙여 넣어 연결한 스토어에는 Admin 접근 권한이 없어 주문을 조회할 수 없습니다. 필요한 경우 App Store를 통해 다시 설치하세요.

사용자 지정 Actions의 작동 방식

1. API Action, MCP, HubSpot Action, Discord Action, Google Sheets, Shopify MCP 중에서 Action 유형을 선택하세요. 연결과 AI에 필요한 지침을 설정하세요.
2. 채팅 중 AI는 보통 Action 설명과 사용 가능한 도구 또는 매개변수 정보를 이용하여 실행 시점을 결정합니다. API Action은 대신 첫 답변 전이나 메타데이터 조건이 처음 일치할 때 자동으로 실행되도록 할 수 있습니다.
3. Quickchat이 호출을 실행합니다. AI가 선택한 Action이나 첫 답변 전에 실행되는 Action의 경우 AI가 응답을 활용할 수 있습니다. 메타데이터로 실행되는 Action은 조용히 작동하며 출력은 채팅에 추가되지 않습니다.
4. 대화에서 사용하기 전에 편집기에서 Action을 테스트하거나 연결하세요.

팁

설명을 AI에 대한 지침으로 작성하세요. 언제 Action을 사용하고, 무엇을 반환하며, 어떤 제약이 있는지 알려 주세요. 예를 들어 “사용자가 주문 번호를 제공할 때만 호출하세요”라고 작성할 수 있습니다.

설명으로 Actions 초안 만들기

1. Actions 및 MCPs에서 + Action 추가 > API Action을 선택하세요.
2. 작업 흐름, 에이전트가 작업해야 하는 시점, 사용할 API(또는 해당 문서 링크), 각 단계에 필요한 정보를 설명하세요. 생성을 클릭하세요.
3. Quickchat은 모두 비활성 상태인 새 API Action 초안을 최대 네 개 준비합니다. 결과에서 중복 생성 대신 기존 Actions를 권장하거나 추가 정보를 요청할 수 있습니다. 초안 생성 시 Actions가 실행되지는 않습니다.
4. 사용하는 기존 Actions, 사전 요구 사항, 다음 단계를 읽으세요. 설정을 완료하고 자리표시자 값을 교체하고 각 Action의 요청, 지침, 실행 조건을 검토하세요. 초안이나 필요한 기존 비활성 Action을 켜기 전에 각 Action을 테스트하세요.

제안된 순서는 의도한 동작을 설명합니다. AI가 선택하는 Actions의 실행 순서를 보장하지는 않습니다. 필수 입력, 저장된 메모리, 실행 조건으로 의존 관계를 표현하세요. Actions를 활성화한 후 대화에서 전체 흐름을 테스트하세요.

API Action 만들기

1. Actions 및 MCPs로 이동하세요.
2. 사용자 지정 Actions에서 + Action 추가를 클릭하고 API Action을 선택한 뒤 직접 만들기를 클릭하세요.
3. 세부 정보를 입력하세요.
   • 이름: 명확하고 내용을 잘 설명하는 이름입니다.
   • 설명: 사용 시점과 매개변수에 포함할 내용입니다.
4. 실행 시점에서 AI가 결정, 첫 답변 전, 메타데이터가 일치할 때 중 하나를 선택하세요.
5. 연결을 설정하세요.
   • API 요청 메서드: HTTP 메서드(GET, POST 등)입니다.
   • API 엔드포인트 URL: 전체 API URL입니다.
   • 헤더: Authorization 또는 content-type: application/json 같은 필수 헤더를 추가하세요.
6. 매개변수를 정의하세요. 각 매개변수의 이름, 위치(쿼리, 본문 또는 헤더), AI가 값을 구성하는 방법을 알려 주는 설명을 작성하세요. 경로 값은 매개변수 위치가 아닙니다. {{placeholder}} 템플릿으로 엔드포인트 URL에 직접 삽입하세요.
7. 요청 테스트를 실행하고 응답을 확인하세요. 그런 다음 완료를 클릭하세요.

팁

모든 값 필드(URL, 헤더, 본문, 쿼리)에서 + AI 데이터 추가 버튼으로 동적 자리표시자를 사용할 수 있습니다. AI 매개변수, 기본 제공 대화 변수({{scenario_id}}, {{language}}, {{country}} 등), 대화 메타데이터({{metadata_*}})를 삽입할 수 있습니다. 전체 참조는 AI Action 변수를 확인하세요.

요청 자체 외에도 API Action에는 알아 두면 좋은 선택적 설정 세 가지가 있습니다. 메모리에 저장, 다음 조건에서만 실행, 응답 필터입니다.

제공한 템플릿과 가상의 예시 값으로 API Action 요청 미리 보기를 사용하세요. 인증 정보가 담긴 헤더는 제외하세요. 미리 보기는 요청을 전송하지 않고 렌더링합니다.

API Action 실행 시점 선택

실행 시점에서 세 가지 모드 중 하나를 선택하세요.

섹션은 기본적으로 접혀 있으며 제목 옆에 현재 모드가 표시됩니다. 모드를 바꾸려면 펼치세요.

• AI가 결정: 기본값입니다. AI가 Action 설명을 읽고 방문자의 요청에 Action이 필요한지 판단합니다. 특정 질문에만 실행하거나 AI가 방문자에게 정보를 수집한 후에 실행해야 할 때 사용하세요.
• 첫 답변 전: 방문자가 첫 메시지를 보낸 후 AI가 첫 답변을 작성하기 전에 Quickchat이 Action을 한 번 실행합니다. 일반 AI 답변에는 응답과 메모리에 저장으로 저장한 값이 전달됩니다. AI는 더 이상 이 Action을 도구로 선택할 수 없으므로 첫 턴에서만 실행되고 이후 대화에서는 다시 실행되지 않습니다. 모든 실제 대화에 필요한 고객 식별, 계정 컨텍스트, 이용 권한 확인 등의 초기 설정에 사용하세요.
• 메타데이터가 일치할 때: Quickchat은 AI 턴마다 Action의 실행 조건을 확인하고 모든 조건이 처음 일치할 때 실행합니다. 같은 턴에서 다른 Action이 메모리에 저장한 값도 즉시 사용할 수 있습니다. AI는 이 Action을 도구로 선택할 수 없으며 응답은 채팅에 추가되지 않습니다. 대화 데이터가 준비되었을 때 자동으로 이루어져야 하는 내부 알림, CRM 갱신, 후속 요청에 사용하세요.

첫 답변 전은 대화 생성이 아니라 방문자의 첫 메시지에 연결됩니다. 채팅을 열거나 환영 메시지를 받기만 해서는 실행되지 않으므로 이탈한 채팅은 요청을 보내지 않습니다. Quickchat은 엔드포인트 호출 전에 실행을 기록하므로 요청이 실패하거나 결과가 불확실해도 같은 대화에서 재시도하지 않습니다.

첫 답변은 요청이 완료될 때까지 기다리므로 이 모드는 지연을 추가할 수 있습니다. 여러 Actions가 이 모드를 사용하면 순차적으로 실행되며 각 요청 시간이 누적됩니다. 필수 메타데이터가 없거나 엔드포인트를 사용할 수 없거나 요청이 실패해도 AI는 답변합니다. Action의 요청 로그를 열어 무슨 일이 있었는지 확인하세요.

AI가 매개변수 값을 선택하기 전에 Action이 실행되므로 사용하는 모든 AI 매개변수에 기본값이 있어야 합니다. 메타데이터와 기본 제공 변수는 URL, 헤더, 쿼리 또는 본문에 직접 삽입할 수 있습니다.

메타데이터가 일치할 때에는 실행 조건이 하나 이상 있어야 하며 모든 AI 매개변수에 기본값이 필요합니다. Quickchat은 엔드포인트 호출 전에 시도를 기록하므로 요청이 전송된 뒤에는 성공, 실패 또는 결과 불확실 여부와 관계없이 같은 대화에서 재시도하지 않습니다. 필요한 값이 아직 없어 요청을 아예 구성할 수 없었다면 기록하지 않으며 이후 턴에서 실행할 수 있습니다. Action은 AI가 턴을 마친 직후 실행되므로 실패해도 AI 답변을 대체하지 않습니다. 답변을 스트리밍하지 않는 채널에서는 요청의 왕복 시간이 방문자의 답변 대기 시간에 더해집니다.

메타데이터가 일치할 때를 선택하면 같은 섹션 안에 실행 조건 편집기가 나타나 트리거와 조건을 함께 관리할 수 있습니다.

이메일 또는 전화번호로 식별

이메일 주소 또는 전화번호를 제공할 수 있는 채널에서는 식별자마다 조회 Action을 하나씩 만드세요. 둘 다 첫 답변 전으로 설정한 후 visitor_email exists 또는 visitor_phone_number exists처럼 해당하는 다음 조건에서만 실행 조건을 추가하세요. Quickchat은 메타데이터가 있는 요청만 전송합니다.

HubSpot Actions

HubSpot Action은 연결된 HubSpot 계정을 사용하는 사전 구성된 편집 가능 API Actions 갤러리를 엽니다.

티켓에 메모 추가 템플릿은 대화에 연결된 HubSpot 티켓에 비공개 메모를 만듭니다. 메모 내용을 대화 메모리에 hubspot_note_body로 저장한 후 템플릿을 추가하고 활성화하세요. 메타데이터가 일치할 때로 미리 설정되어 있으며 hubspot_note_body와 Quickchat 서버가 제공하는 hubspot_ticket_id가 모두 있을 때까지 기다립니다. note_body 매개변수의 기본값을 편집하면 {{metadata_hubspot_note_body}} 앞뒤에 고정 텍스트를 추가할 수 있습니다.

메모는 HubSpot 내부용이며 방문자에게 표시되지 않습니다. 템플릿은 Quickchat 대화당 한 번 요청을 시도합니다. Action의 요청 로그를 열어 전달 여부를 확인하거나 실패한 요청을 조사하세요.

Discord Actions

Discord Action은 사전 구성된 편집 가능 API Actions 갤러리를 엽니다.

• 지원 및 티켓: 지원 티켓 생성은 서버와 텍스트 채널을 선택하도록 요청합니다. 선택적으로 멘션 가능한 지원 역할을 선택할 수 있습니다. 비공개 스레드를 열고, 현재 요청자를 추가하고, 선택한 역할 멘션과 함께 요약을 게시하는 Actions 세 개를 만듭니다.
• 콘텐츠 관리: 멤버 타임아웃, 멤버 내보내기, 멤버 차단, 멤버 차단 해제, 역할 부여, 슬로우 모드 설정, 공지 전송입니다. 각 템플릿은 클릭 한 번으로 설치되며 현재 Discord 요청의 서버, 멤버, 역할 또는 채널을 사용합니다.

Quickchat은 백엔드에서 HTTP 메서드, URL, 헤더, 본문, 매개변수, 설명, 응답 설정, 실행 조건을 만듭니다. 생성된 카드는 일반 HTTP 요청 Actions입니다. 모든 필드를 확인하고 편집할 수 있습니다.

콘텐츠 관리 템플릿 일곱 개 모두 다음 조건에서만 실행에 author_is_admin is true를 포함합니다. Discord가 현재 작성자의 Administrator 권한을 계산하고 Discord 게이트웨이가 그 값을 전달하며 Quickchat은 요청 전송 전에 확인합니다. 공개 채팅과 API 메타데이터로는 이 키를 설정할 수 없습니다. Discord에서 관리자 계정과 비관리자 계정 모두로 관리 Actions를 테스트하세요. AI 미리 보기에는 인증된 Discord 발신자가 제공되지 않습니다.

주의

콘텐츠 관리 Actions는 편집할 수 있습니다. author_is_admin is true 조건을 제거하거나 완화하면 기본으로 제공된 권한 검증 경계가 사라집니다. 내보내기와 차단은 실행 전에 확인을 요청하지 않습니다.

템플릿 자체가 별도 자동화를 추가하지는 않습니다. 에이전트는 관리자가 대화에서 요청할 때만 이를 실행합니다. 대화 간 경고 누적, 스크린샷이나 기타 증거 확인, 예약된 제재 또는 자체 판단에 따른 제재는 없습니다.

봇 자체에도 각 요청에 필요한 Discord 권한이 있어야 합니다.

Action	봇 권한 또는 접근
멤버 타임아웃	Moderate Members
멤버 내보내기	Kick Members
멤버 차단, 멤버 차단 해제	Ban Members
역할 부여	Manage Roles
슬로우 모드 설정	Manage Channels
공지 전송	View Channels 및 Send Messages

Discord는 역할 계층도 적용합니다. 봇이 관리할 멤버와 역할보다 봇의 역할을 위에 두세요. 템플릿은 요청한 관리자에 대해 추가적인 계층 또는 개별 권한 검사를 수행하지 않습니다.

슬로우 모드 설정과 공지 전송은 채널 ID 매개변수를 받습니다. 별도의 고정 대상을 지정하지 않으면 템플릿은 해당 채널이 관리자가 요청한 서버에 속하는지 확인하지 않습니다. 같은 봇이 여러 서버에 속한다면 이 Actions를 편집하여 고정 채널 ID를 사용하거나 서버별로 에이전트와 봇 인증 정보를 분리하세요.

지원 티켓 설치는 기존 Action 기능으로 데이터를 전달합니다.

1. open_support_ticket은 선택한 채널에 비공개 스레드를 만들고 $.id를 추출하여 대화 메모리에 discord_ticket_thread_id로 저장합니다. discord_message is true가 필요하며 선택한 서버에서만, 해당 메모리 키가 아직 없을 때만 실행됩니다.
2. add_ticket_requester는 {{metadata_discord_ticket_thread_id}}와 Discord가 제공한 {{metadata_discord_author_id}}를 읽습니다. discord_message is true가 필요하며 스레드 ID가 존재한 뒤 선택한 서버에서만 실행됩니다.
3. post_in_ticket은 저장된 같은 스레드 ID를 읽고 에이전트의 한 줄 문제 요약을 게시하며 요청자를 멘션합니다. 지원 역할을 선택했다면 그 역할도 멘션합니다. Discord 메시지, 서버, 저장된 스레드에 대한 조건은 동일합니다. Discord allowed_mentions 본문은 요청자와 설정된 경우 해당 역할로 제한됩니다.

설명과 에이전트 프롬프트에서 이 순서로 Actions를 실행하도록 지시해야 합니다. 별도의 작업 흐름 상태, 잠금, 확인, 재시도, 복구, 정합성 조정 또는 재실행 방지 계층은 없습니다. 결과가 불확실하면 Discord가 이미 요청을 완료했을 수 있으므로 재시도 전에 Discord와 Action 로그를 확인하세요.

discord_ticket_thread_id는 자동으로 지워지지 않습니다. 따라서 기본 템플릿은 Quickchat 대화당 티켓 하나를 지원합니다. 다른 티켓을 만들려면 새 Discord 대화나 스레드를 시작하거나 Actions를 편집하여 필요한 메모리 수명 관리를 추가하세요.

지원 티켓의 경우 선택한 티켓 채널에서 봇에 View Channels, Send Messages, Read Message History, Create Private Threads, Send Messages in Threads, Manage Threads 권한을 부여하세요. 역할을 멘션하지 않으려면 역할에 알림(선택 사항)을 역할 알림 안 함으로 두세요. 역할을 선택한다면 멘션 가능해야 하며 해당 역할의 멤버가 비공개 스레드에 접근할 수 있어야 합니다. 멘션 가능한 역할이 없어도 역할 알림 없이 티켓은 정상적으로 열립니다. 갤러리는 텍스트 채널과 멘션 가능한 역할을 나열하지만 모든 채널 권한 재정의를 검증하지는 않습니다.

주의

Discord Actions에는 외부 앱 → Discord → 고급 설정에 있는 자체 Discord 앱 토큰이 필요합니다. 클릭 한 번으로 연결하는 공유 봇만으로는 해당 토큰을 제공할 수 없습니다. Discord를 참고하세요.

갤러리는 설정을 돕는 기능이며 별도 정책 계층이 아닙니다. 생성된 Action을 편집하거나 사용자 지정 Discord API Action을 만들면 활성화 전에 인증 정보, 대상, 매개변수, 응답 노출 범위, 다음 조건에서만 실행 조건을 검토하세요.

메모리에 저장

Action 입력 또는 API 응답의 값을 선택한 키로 대화 메모리에 저장하세요. 이후 Actions가 {{metadata_<key>}}로 재사용할 수 있으며 대화 세부 정보(받은편지함, API, 내보내기)에 표시됩니다.

Action 하나가 후속 Action에 필요한 값을 만들어 낼 때 사용하세요. 조회 Action이 응답에서 customer_id를 저장하면 후속 Action이 {{metadata_customer_id}}를 전송할 수 있어 AI가 값을 복사할 필요가 없습니다.

API Action 편집기에서 메모리에 저장을 열고 행을 추가하세요.

1. 소스를 선택하세요. API 응답은 API의 JSON 응답을 읽으며 새 행의 기본값입니다. Action 입력은 Action에 선언된 입력 매개변수 값을 읽습니다.
2. 저장할 값에서 Action 입력의 경우 드롭다운으로 매개변수를 선택하세요. API 응답의 경우 $.customer_id 같은 JSONPath 표현식을 입력하세요.
3. 메모리 키를 선택하세요. 일반적인 영어 이름, 전화번호, 이메일 입력 이름에는 해당 방문자 키가 제안됩니다. 제안을 유지하거나 직접 키를 입력할 수 있습니다.

받은편지함에 연락처 정보를 저장하려면 Action 입력과 다음 매핑을 사용하세요.

Action 매개변수	메모리 키
Name 또는 Full name	visitor_name
Phone number 또는 Phone	visitor_phone_number
Email 또는 Email address	visitor_email

입력은 Action에 선언되어 있어야 합니다. Action 입력 메모리 규칙으로 저장하면 해당 매개변수를 사용하는 것으로 간주되므로 HTTP 요청에 보내지 않고 메모리용으로 수집할 수 있습니다. 이 방문자 키는 스마트 데이터 수집과 같은 검증을 사용하여 아직 설정되지 않은 받은편지함 연락처 필드와 대화 메타데이터를 채웁니다. 기존 연락처 정보와 담당자가 명시적으로 지운 필드는 유지됩니다. API 응답 규칙은 이 방문자 키에 값을 쓸 수 없습니다. CRM 응답 값에는 customer_id 같은 사용자 지정 키를 사용하세요.

입력은 Action이 필수 입력과 실행 조건 검사를 통과한 후, HTTP 요청 전에 저장됩니다. 따라서 API가 오류를 반환하거나 시간 초과되어도 유효한 연락처 정보가 남습니다. 확인하려면 새 미리 보기 대화에서 Action을 실행하고 받은편지함에서 해당 대화를 여세요. 편집기의 독립적인 API 테스트에는 메모리를 저장할 대화가 없습니다.

메모리 키는 에이전트의 원격 MCP 도구와 공유됩니다. MCP 도구가 이미 같은 키에 저장한다면 저장할 때 메모리 키 필드에 충돌이 표시되므로 다른 키를 선택하세요. 원격 MCP 도구는 계속 결과의 값을 저장합니다.

팁

snake_case 키(영문자, 숫자, 밑줄)를 사용하세요. customer_id 같은 키는 {{metadata_customer_id}}로 참조할 수 있습니다. 공백이나 다른 문장 부호가 있는 키는 자리표시자에 사용할 수 없습니다. 메타데이터 변수의 작동 방식은 대화 메타데이터를 참고하세요.

다음 조건에서만 실행

대화 메타데이터의 조건이 충족될 때만 Action이 실행되도록 제한하세요. 조건은 항상 모델 외부의 서버에서 검사합니다. AI가 결정 또는 첫 답변 전에서는 Quickchat이 요청을 보내기 직전에 확인합니다. 메타데이터가 일치할 때에서는 AI가 Action을 선택하기를 기다리지 않고 AI 턴이 끝난 뒤 조건 자체가 요청을 실행합니다.

멤버 차단, 환불, 레코드 삭제처럼 권한이 필요하거나 되돌릴 수 없는 Actions에 적합합니다. 프롬프트의 “관리자만 할 수 있습니다”라는 문장은 유용한 지침이지만 보안 경계는 아닙니다. 의도적인 사용자는 모델을 설득하거나 프롬프트 인젝션을 시도할 수 있습니다. 실행 조건은 결정적이며 프롬프트 외부에 있으므로 대화 내용과 관계없이 적용됩니다.

• 실행 조건이 경계입니다. 서버에서 평가되며 모델이 읽는 프롬프트의 일부가 아닙니다. 실제로 Action 실행을 막는 요소입니다.
• 프롬프트 규칙은 사용자 경험을 담당합니다. AI가 조용히 멈추는 대신 정중하게 거절하고 이유를 설명하도록 프롬프트에도 지침을 유지하세요.

Action 편집기의 다음 조건에서만 실행 섹션에 조건을 추가하세요. 메타데이터가 일치할 때 Action에서는 이 섹션이 실행 조건으로 표시됩니다. 조건 추가를 클릭하고 메타데이터 키(예: telegram_sender_is_admin)를 선택한 다음 비교 방법을 선택하세요.

조건	메타데이터 값이 다음에 해당하면 통과
참임	참으로 평가됨
거짓임	거짓으로 평가됨
존재함	대화에 존재함
존재하지 않음	존재하지 않음
같음	지정한 값과 일치함
같지 않음	지정한 값과 다름
다음 중 하나임	대소문자와 공백을 포함하여 나열된 값 중 하나와 정확히 일치함
텍스트 포함	지정한 텍스트를 문자 그대로 포함함. 대소문자를 구분함

Action은 모든 조건이 충족될 때만 실행됩니다. 편집기는 행 사이에 AND를 표시합니다. AI가 선택한 Action이 조건 때문에 차단되면 AI는 해당 Action을 사용할 수 없다고 설명할 수 있습니다. 메타데이터가 일치할 때 Action은 조건이 통과할 때까지 조용히 대기합니다.

같은 키의 여러 대안에는 다음 중 하나임을 사용하고 각각을 별도 값으로 입력하세요. 예를 들어 modelName is one of [K-65XR95M2, K-75XR95M2, K-85XR95M2]와 country equals UK를 함께 설정하면 두 행이 모두 통과해야 합니다. 각각 최대 500자인 대안을 50개까지 추가할 수 있습니다. 쉼표는 값의 일부로 그대로 처리됩니다. 같은 키의 서로 다른 값에 대해 같음 행을 여러 개 추가하면 모두 일치할 수 없습니다.

텍스트 포함은 와일드카드나 정규식이 아니라 문자열의 일부가 그대로 포함되는지 확인합니다. XR95M2는 위의 세 모델 외에도 해당 문자열이 포함된 다른 모델 이름과 일치합니다. 이 두 새 조건은 누락된 키, null, 목록, 객체를 허용하지 않습니다. 텍스트 포함은 숫자와 불리언도 허용하지 않습니다. 빈 비교 텍스트는 사용할 수 없습니다. 기존 거짓임, 같지 않음, 존재하지 않음 조건은 누락된 키와 일치할 수 있습니다.

조건이 충족되지 않으면 요청을 보내지 않고 AI가 사용자에게 수행할 수 없다고 알립니다. 아래에서는 요청한 사람만 바꾸었을 때 같은 차단 요청이 비관리자에게는 거부되고 관리자에게는 허용됩니다.

주의

방문자가 영향을 줄 수 있는 값이 아니라 채널에서 검증된 telegram_sender_is_admin 플래그처럼 Quickchat이 설정하는 메타데이터만 권한 조건으로 사용하세요. 각 키의 출처는 대화 메타데이터를 참고하세요.

응답 필터

기본적으로 AI는 전체 API 응답을 봅니다. 응답 필터 섹션에 JSONPath 표현식을 추가하면 특정 부분만 보도록 제한할 수 있습니다.

필터를 사용하는 대표적인 두 가지 이유는 다음과 같습니다.

• 민감한 필드 숨기기. 엔드포인트가 AI에 필요한 것보다 많은 정보를 반환한다면 고객 이메일, 결제 정보 또는 내부 ID를 모델 컨텍스트에서 제외하세요.
• 프롬프트 크기 줄이기. 많은 데이터를 제공하는 API는 큰 페이로드를 반환할 수 있습니다. 중요한 몇몇 필드만 남기면 응답을 작게 유지하고 AI가 집중할 수 있습니다.

JSONPath 표현식을 하나 이상 추가하세요. 필터는 선택한 필드를 값의 목록으로 펼치지 않고 원래의 객체와 배열 안에 유지합니다. 선택한 경로 밖의 필드는 생략됩니다. 예를 들어 다음 두 행을 사용하세요.

• $.customer.name
• $.orders[*].id

API 응답이 다음과 같다면:

{
  "customer": {"name": "Ada", "email": "ada@example.com"},
  "orders": [{"id": 101, "total": 25}, {"id": 102, "total": 40}]
}

AI는 다음 필터링된 응답을 받습니다. customer는 여전히 객체이고 orders는 여전히 객체 배열입니다.

{
  "customer": {"name": "Ada"},
  "orders": [{"id": 101}, {"id": 102}]
}

팁

필터를 실제로 적용하기 전에 응답 테스트 패널에서 AI가 필터링 후 정확히 무엇을 받는지 확인하세요. Action 테스트를 참고하세요.

주의

일치하는 항목이 없는 JSONPath는 AI에 빈 응답을 남깁니다. 필터 없이 시작하여 호출이 작동하는지 확인한 뒤 범위를 좁히세요.

제공한 JSON 응답에서 JSONPath 일치 항목 미리 보기를 사용하세요. 미리 보기는 응답 필터 또는 메모리에 저장 규칙에 사용할 루트, 필드, 배열 인덱스 및 와일드카드 경로를 지원합니다.

Action 상태와 로그 확인

사이드바의 Actions 및 MCPs 옆에 경고가 있다면 확인이 필요한 Action이 있다는 뜻입니다. 페이지를 열고 해당 카드 배지에 마우스를 올리거나 초점을 맞추면 이유를 볼 수 있습니다.

• 실패 발생: 최근 호출이 반복적으로 실패했습니다. 배지에는 실패 횟수와 확인 가능한 경우 최근 오류가 표시됩니다.
• 실행되지 않음: 현재 상태 평가 기간에 실제 실행된 호출 없이 Action이 반복적으로 건너뛰어졌습니다. 대화 값 누락 또는 설정 문제 등 표시된 이유를 확인하세요.
• 다시 연결 필요: MCP 연결의 인증이 끊겨 비활성화되었습니다. 편집을 열고 다시 연결한 뒤 켜세요.

상태는 최근 7일의 실제 대화를 사용하며, 마지막 Action 편집이 더 최근이라면 그 시점부터 평가합니다. 테스트 요청과는 별개입니다. Action을 수정하고 저장한 후 새 대화에서 문제가 해결되었는지 확인하세요. 이전 경고가 사라졌다는 사실만으로 작동을 입증할 수는 없습니다.

실패 발생 또는 실행되지 않음에서 세부 정보 보기를 클릭하면 문제만이 켜진 요청 로그가 열립니다. 로그 보기는 모든 호출이 포함된 로그를 엽니다. 문제 호출과 성공한 호출을 비교하려면 문제만을 끄세요.

건너뛴 대화에는 실제 실행된 호출과 별개로 Action을 실행할 수 없었던 대화가 나열됩니다. 대화 보기로 컨텍스트를 확인하고 더 보기로 이전 항목을 불러오세요. 어떤 대화에서는 성공하고 다른 대화에서는 건너뛸 수 있으므로 경고 배지가 없어도 이 목록이 나타날 수 있습니다.

이유에 {{metadata_visitor_email}} 같은 누락된 값이 표시되면 웹사이트나 채널 메타데이터로 제공하거나 앞선 Action이 메모리에 저장하도록 하세요. 그런 다음 실행 모드를 확인하세요.

• AI가 결정: 필요한 값이 이미 있는 대화에서만 AI에 Action이 제공됩니다.
• 첫 답변 전: 방문자가 첫 메시지를 보낼 때 값이 있어야 합니다.
• 메타데이터가 일치할 때: 필요한 값마다 존재함 조건을 추가하여 Action이 해당 값을 기다리도록 하세요.

대화 값의 출처는 AI Action 변수를 참고하세요.

HTTP 또는 원격 MCP Action에 확인이 필요하면 활동 요약 이메일에도 확인이 필요한 AI Actions 섹션이 포함됩니다. 최대 다섯 개의 Actions와 각 이유, Actions 및 MCPs 링크를 표시하며 그 밖에 확인이 필요한 수를 보여 줍니다. 모두 정상이라면 이 섹션은 생략됩니다.

이메일은 현재 상태를 보여 주므로 일일 요약의 활동 기간보다 더 긴 기간을 포함할 수 있습니다. 수정한 API Action을 저장하면 그 편집 시점부터 상태 평가를 다시 시작합니다. 문제가 있는 MCP 연결을 다시 연결하거나 연결 해제하면 인증 경고가 지워집니다. 기존 요약 이메일 기본 설정과 수신 조건이 적용되며 별도의 알림 이메일은 보내지 않습니다.

권장 사항

• 설명을 명확하게 작성하세요. AI에 Action 사용 시점과 각 매개변수에 포함할 내용을 알려 주세요.
• 권한 범위를 최소화하세요. 엔드포인트에 필요한 헤더와 토큰만 포함하세요. Jira에서는 Atlassian 이메일과 API 토큰에서 만든 Basic 헤더를 사용하세요.
• 배포 전에 테스트하세요. 요청 테스트 패널을 사용하세요. 대상 도구에서 상태 코드와 예시 페이로드가 올바른지 확인하세요.

튜토리얼

• AI 에이전트를 Jira 티켓에 연결하기(공식 참조) 또는 설명이 포함된 블로그 안내
• AI Action으로 Slack 알림 보내기