# 런타임 AI

## Content

Forguncy의 런타임 AI 기능은 개발자가 지능형 인터랙션 기능을 포함한 업무 애플리케이션을 빠르게 구축할 수 있도록 지원하며, 다음 설계 원칙을 따릅니다.

* **빠르고 효율적:** 프롬프트 편집기, 이벤트 메커니즘, 함수 호출을 통해 기존 시스템의 업무 로직과 빠르고 매끄럽게 연결됩니다.
* **개인화 커스터마이징:** 범용 AI 기능을 제공하는 동시에 다양한 업무 시나리오에 맞는 깊이 있는 커스터마이징도 지원합니다.

***

### AI 설정

#### 왜 여기서 또 AI 모델을 설정해야 하나요?

디자이너의 [옵션] > [일반 설정]에서 이미 AI 모델을 등록하셨다면, "그건 이미 했는데 왜 또 설정하나?"라는 생각이 드실 수 있어요.
포건시에는 AI를 사용하는 두 가지 상황이 있고, 이 둘은 서로 완전히 별개로 동작합니다.

|  | 디자인 시 AI 설정 | 런타임 AI 설정 (이 문서) |
| --- | ----------- | ---------------- |
| **사용 주체** | 개발자(설계자) 본인 | 완성된 애플리케이션을 사용하는 최종 사용자 |
| **사용 시점** | 앱을 만드는 동안(디자이너 화면에서) | 완성된 앱을 실제로 실행했을 때 |
| **예시** | "이 화면을 자동으로 만들어줘" 같은 개발 보조 기능 | 앱 안에 넣은 AI 챗봇, AI 자동 응답 등 실제 업무 기능 |

즉, 디자이너에서 설정한 AI는 **개발자가 앱을 만들 때 도움을 받는 용도**이고, 여기서 설정하는 AI는 **완성된 앱을 실제로 쓰는 사람들에게 보여줄 AI 기능**입니다. 둘은 별개의 연락처를 등록하는 것과 같아서, 같은 API 키를 다시 입력해야 하더라도 설정 자체는 따로 해주셔야 합니다.

> 💡 아직 "AI 모델"이 무엇이고 API 키가 왜 필요한지 잘 모르시겠다면, [설계단계에서의 AI](https://doc.forguncy.co.kr/forguncy/v12/docs/ai/ai-in-designer) 문서의 "AI 모델 추가하기" 섹션을 먼저 읽어보시는 것을 추천합니다. 포건시와 AI 서비스가 어떻게 연결되는지 기본 개념을 설명합니다.

#### 설정 관리

**1\. 설정 화면 위치**
런타임 AI 모델은 디자인 시 AI 설정과 **다른 탭**에 있습니다. 아래 경로로 이동하세요.

1. 포건시 빌더 [파일]을 클릭한 후, 좌측 메뉴에서 [옵션]을 클릭합니다.
2. **[응용 프로그램 설정]** 탭으로 이동합니다. (디자인 시 설정은 "일반 설정" 탭에 있었지만, 런타임 설정은 여기 있습니다.)
3. 화면을 아래로 스크롤하면 **"런타임 기능을 위한 AI 모델"** 영역이 있습니다. 여기서 [AI 모델 추가...]를 클릭합니다. 
4. 설정 창이 열리면, 디자인 시 설정과 동일한 항목을 입력합니다.

![image](https://gcdocumentsitekrblob.blob.core.windows.net/document-site-files/images/4f96589d-8403-419e-b2a1-4f6776199cb9/image-20260819.bad2a3.png?width=800)
**2\. 설정 파라미터**
여기서 설정하는 항목은 디자인 시 AI 설정과 동일한 정보입니다. 준비물도 같습니다 — 사용할 AI 서비스(OpenAI, Azure OpenAI 등)를 정하고, 해당 서비스에서 발급받은 API 키가 필요합니다.

| 항목 | 설명 |
| --- | --- |
| **설정 이름** | 이 설정을 구분하기 위한 별칭입니다. 여러 개를 등록했을 때 알아보기 쉽게 짓습니다. |
| **API Host** | 사용할 AI 서비스의 접속 주소입니다. (예: `https://api.openai.com/v1`) |
| **API Key** | AI 서비스에서 발급받은 인증 키입니다. 비밀번호처럼 취급해야 합니다. |
| **API Model Name** | 사용할 AI 모델의 정확한 이름입니다. (예: `gpt-5`) |
| **고급 파라미터** (선택) | 최대 출력 토큰 수(Max Tokens), 샘플링 온도(Temperature), 핵 샘플링(Top\_P) 등 세부 옵션입니다. 처음에는 기본값을 두어도 무방합니다. |

**3\. 설정 작업**

* 설정은 프로젝트 파일과 함께 저장됩니다.
* 기본 모델을 지정할 수 있으며, 여러 개를 등록해 두고 필요할 때 다른 설정으로 전환할 수 있습니다.
* JSON 가져오기/내보내기를 지원하여 설정 마이그레이션이 편리합니다.
* 애플리케이션을 실제 서비스로 배포한 뒤에는, 디자이너를 열지 않고도 **관리 콘솔**에서 이 설정 값(API 키 등)을 변경할 수 있습니다. 예를 들어 API 키를 재발급했거나 다른 AI 서비스로 바꾸고 싶을 때 유용합니다.

> **주의:** 런타임 설정과 디자인 시 설정은 서로 독립적입니다. 위 표에서 설명한 것처럼 한쪽을 설정했다고 해서 다른 쪽에도 자동으로 반영되지 않으니, 실제 사용자에게 AI 기능을 제공하려면 이 런타임 AI 설정을 반드시 별도로 완료해야 합니다.

***

### 핵심 기능

#### AI 어시스턴트 명령

**기능 특징:**

1. **다중 위치 지원:** 페이지 측과 서버 측 모두에서 사용 가능합니다.
2. **파라미터 설정:**
    * 모델 선택
    * 시스템/사용자 프롬프트 편집
    * 함수 정의 목록(Function Calling)
    * 입출력 설정

**특화 기능: 구조화된 데이터 출력**
기본적으로 대규모 모델은 순수 텍스트 형태로 결과를 반환합니다. 개발 요구를 충족시키기 위해 다음 두 가지 결과 유형 옵션을 제공합니다.

1. **텍스트** — 원본 텍스트 출력(기본 모드)
2. **JSON 자동 추출** — 응답 내 JSON 구조 조각을 식별하고 추출하여 JSON 텍스트를 직접 반환

이 기능은 JSON 데이터 처리 과정을 간소화하여, 개발자가 별도의 파싱 로직을 작성하지 않고도 구조화된 데이터를 얻을 수 있도록 합니다.
**대표적인 활용 예시:**
반환 결과 유형: 텍스트

```auto
사용자 프롬프트: "[%AiUserInput%]을 영어로 번역해줘"
입력: "안녕하세요" → LLM 출력: "Hello"
실제 출력: "Hello"
```

반환 결과 유형: JSON 문자열 추출 시도

```auto
사용자 프롬프트: "[%AiUserInput%]을 몇 가지 나열하고 JSON 목록으로 출력해줘"
입력: "과일" → LLM 출력: "네, 과일 몇 가지를 나열했습니다. ```json["사과","바나나","배"]```"
실제 출력: ["사과","바나나","배"]
```

***

#### AI 대화 셀

**설정 흐름:**

1. 런타임 AI 모델을 설정합니다. (위 "AI 설정" 참고)
2. 셀 유형을 \*\*"AI 대화 셀"\*\*로 설정합니다.
3. 페이지를 실행하여 인터랙션을 진행합니다.

**핵심 설정 항목:**

| 설정 항목 | 설명 |
| ----- | --- |
| AI 모델 선택 | 설정된 모델 간 전환 |
| 데이터 소스 바인딩 | 업무 데이터 테이블과 연결 |
| 시스템 프롬프트 | AI의 역할과 작업을 정의 |
| 사용자 프롬프트 | 입력 템플릿 설정 |
| 함수 정의(Function Calling) | AI가 실행 가능한 명령 확장 |

**고급 기능:**

* **이벤트 응답:** 새 대화 생성, 메시지 추가 시 명령을 트리거
* **화면 커스터마이징:** 타이틀바, 타임스탬프 등 표시 제어
* **인터랙션 작업:** 메시지 관리, 대화 초기화 등

**특화 기능: 카드 메시지**
AI 대화 셀은 **"컴포넌트 메시지 추가"** 작업을 통해 Forguncy 컴포넌트(예: 컴포넌트 페이지에 배치된 데이터 테이블, 차트, 폼 등)를 구조화된 카드 형태로 대화 흐름에 삽입할 수 있어 다음을 구현합니다.

* **시각적 데이터 표현:** 동적 업무 데이터를 직접 표시
* **인터랙티브 응답:** 컴포넌트 이벤트와 결합하여 유연한 인터랙션을 구현

**대표적인 활용 시나리오:**

1. 오프닝: 커스텀 오프닝 이미지-텍스트 카드
2. 주문 조회: AI 텍스트 답변 + 주문 상세 카드
3. 보고서 분석: 분석 결론 + 동적 차트 카드

***

### 주의사항

1. **데이터 보안:** AI 인터랙션은 데이터 전송을 포함할 수 있으므로 민감한 정보 전송을 피해야 합니다. API 키는 비밀번호와 동일하게 취급하여 외부에 노출되지 않도록 주의하세요.
2. **성능 최적화:** 복잡한 함수는 응답 속도에 영향을 줄 수 있습니다.
3. **결과 검증:** 핵심 업무 결정에는 사람의 확인 단계를 추가하는 것을 권장합니다.
4. **모델 한계:** 출력 품질과 Function Calling은 선택한 모델의 능력에 따라 제한됩니다.