> For the complete documentation index, see [llms.txt](https://help.genesis.autify.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.genesis.autify.com/features-ko/workflow/ai-agent-block.md).

# AI 에이전트 블록

이 문서에서는 Autify Genesis의 AI 에이전트 블록의 설정과 조작 방법을 설명합니다. AI 에이전트 블록은 LLM(대규모 언어 모델)을 사용하여 텍스트나 구조화된 데이터를 생성하는 워크플로의 기본 단위입니다.

## 기본 설정

블록을 클릭하면 오른쪽 인스펙터에 **세부 정보** 탭이 표시됩니다. 다음 항목을 설정합니다.

| 설정 항목        | 내용                                                                                                       |
| ------------ | -------------------------------------------------------------------------------------------------------- |
| 이름           | 블록의 표시 이름. 캔버스 위나 인스펙터에 표시됩니다                                                                            |
| 설명           | 블록의 역할이나 처리 내용의 보충 설명                                                                                    |
| 프롬프트         | AI 에이전트에게 실행시킬 내용을 기술합니다. 사용자 입력이나 명시적으로 설정한 입력은 `{{변수명}}`으로 참조할 수 있으며, 연결한 상위 블록의 출력은 자동으로 컨텍스트로 전달됩니다. |
| 출력을 아티팩트로 저장 | 활성화하면 이 블록의 출력이 다운로드 가능한 아티팩트로 저장됩니다.                                                                    |
| 검토 필수        | 활성화하면 이 블록의 실행 후에 처리가 일시 중지되어 수동 승인을 기다립니다.                                                              |
| 모델           | 사용할 AI 모델을 선택합니다. 프로바이더별로 여러 모델 중에서 선택할 수 있습니다.                                                          |

## 프롬프트 작성법

프롬프트에서는 사용자 입력을 `{{변수명}}`으로 참조하는 방법과, 연결한 상위 블록의 출력을 자동 컨텍스트로 사용하는 방법이 있습니다.

### 사용자 입력을 변수로 참조하기

프롬프트 안에서 `{{변수명}}` 형식을 사용하면, 워크플로 실행 시의 사용자 입력이나 이 블록에 명시적으로 설정한 입력을 참조할 수 있습니다.

변수를 삽입하려면 프롬프트 편집기 상단의 **{} 변수**를 클릭하여 변수 삽입 메뉴를 여십시오. 변수 메뉴에는 설정 내용에 따라 다음 종류가 표시됩니다.

| 변수 종류 | 내용                          | 참조 형식 예              |
| ----- | --------------------------- | -------------------- |
| 입력    | 이 블록에 정의된 입력 변수             | `{{input_key}}`      |
| 컨텍스트  | 워크플로 실행 시에 사용자가 지정하는 사용자 입력 | `{{my_input}}`       |
| 블록 출력 | 명시적으로 입력으로 추가한 다른 블록의 출력    | `{{previous_block}}` |

다른 블록의 출력을 자동 컨텍스트로 사용하기만 한다면 변수를 삽입하지 않아도 됩니다.

{% hint style="warning" %}
프롬프트 안에서 참조하는 변수가 블록의 입력에 정의되어 있지 않은 경우, 검증 오류가 발생합니다. 변수 삽입 메뉴를 사용하면 사용 가능한 변수의 선택 화면이 표시됩니다.
{% endhint %}

### 연결한 상위 블록의 출력 참조하기

캔버스에서 이 블록에 연결한 상위 블록의 출력은 실행 시에 자동으로 컨텍스트로 전달됩니다. 상위 출력을 사용하기 위해 매번 `{{변수명}}`을 수동으로 삽입할 필요는 없습니다.

연결이 있는 경우, 프롬프트란 아래에 사용 가능한 연결 블록 수와 블록 이름이 표시됩니다. 여기에 표시된 블록의 출력을 전제로 프롬프트를 작성합니다.

### 파일·폴더·스킬 참조하기

워크스페이스 안의 파일, 폴더, 스킬을 프롬프트에 직접 삽입하여 실행 시 컨텍스트로 사용할 수 있습니다.

#### 파일 및 폴더

1. 프롬프트 편집기 상단의 **파일 추가**를 클릭하여 파일 브라우저를 엽니다.
2. 파일을 검색하거나 폴더를 따라가며 삽입할 파일이나 폴더를 선택합니다.
3. 선택한 항목을 추가하면 프롬프트에 참조가 삽입됩니다.
4. 특정 버전의 파일을 참조하려면 프롬프트에서 `@`를 입력하고 파일 이름 옆의 메뉴에서 대상 버전을 선택하십시오.

폴더를 참조하면, 그 폴더 안의 파일도 AI 에이전트가 실행 시 확인할 수 있습니다.

#### 스킬

스킬은 워크스페이스에 업로드한 `SKILL.md` 파일이나 연결한 코드베이스에서 찾아낸 재사용 가능한 지시 세트입니다.

1. 프롬프트 편집기 상단의 **스킬 추가**를 클릭하거나, 프롬프트 안에서 새 토큰의 시작에 `/`를 입력하십시오.
2. 사용할 스킬을 검색하십시오.
3. 목록에서 스킬을 선택하십시오.
4. 프롬프트에 `/skill-name`으로 삽입됩니다.

워크스페이스의 스킬 모드가 **자동**인 경우, AI 에이전트가 관련 스킬을 자동으로 선택할 수도 있습니다. `/skill-name`을 명시하면 해당 프롬프트에는 항상 그 스킬이 적용됩니다.

### 프롬프트 다듬기

프롬프트 편집기 오른쪽 위의 **AI로 프롬프트 다듬기**를 클릭하면 AI에 의한 프롬프트 개선 기능을 사용할 수 있습니다.

| 작업          | 내용                                    |
| ----------- | ------------------------------------- |
| 자동 개선       | 언어를 간결하게 하고 단계를 명확히 합니다               |
| 실행 가능하게 만들기 | 명확한 출력·수용 기준·제약 조건을 포함한 형식으로 다시 작성합니다 |
| 사용자 지정 지시   | 개선하고 싶은 내용을 자유롭게 기술하면 AI가 프롬프트를 조정합니다 |

![프롬프트 다듬기 화면](/files/nhdgh46zuHo0iV1F6nyF)

## 모델 선택

**모델** 드롭다운에서 작업 내용에 적합한 모델을 선택합니다. 사용 가능한 모델의 자세한 내용은 [AI 모델](/features-ko/ai-feature/ai-models.md) 참조.

## 아티팩트로 저장하기

**출력을 아티팩트로 저장**을 활성화하면 이 블록의 출력이 다운로드 가능한 파일로 저장됩니다.

1. 인스펙터의 **출력을 아티팩트로 저장** 토글을 켜십시오.
2. **아티팩트 제목**에 파일 이름을 입력하십시오(생략한 경우 자동으로 명명됩니다).
3. **아티팩트 형식**에서 **Markdown**·**JSON**·**HTML** 중 하나를 선택하십시오.
4. **재실행 시**에서 재실행할 때 아티팩트를 어떻게 업데이트할지 선택하십시오.

   | 동작     | 내용                                                |
   | ------ | ------------------------------------------------- |
   | 다시 생성  | 실행할 때마다 새 아티팩트를 처음부터 작성합니다. 각 실행이 독립적인 경우에 적합합니다. |
   | 제자리 편집 | 기존 아티팩트의 최신 버전에 정밀한 편집만 적용합니다.                    |

**구조화된 출력**을 활성화한 경우, 아티팩트 형식은 **JSON**으로 고정됩니다.

{% hint style="info" %}
저장된 아티팩트는 워크플로 실행 완료 후에 실행 세부 정보 화면에서 접근하여 다운로드할 수 있습니다. HTML 아티팩트는 실행 상세 화면과 파일 상세 화면에서 렌더링된 결과를 바로 미리 볼 수 있습니다. **제자리 편집**으로 생성된 버전에는 추가·삭제 행 수를 표시하는 **편집 내용** 칩에서 이전 버전과의 차이 패널을 열 수 있습니다. 차이 패널 안의 행을 클릭하면 현재 본문의 해당 위치로 이동합니다.
{% endhint %}

## 검토 기능 사용하기

**검토 필수**를 활성화하면 이 블록의 실행 후에 처리가 일시 중지되어 사람에 의한 검토를 기다립니다. 자세한 내용은 "워크플로 작성·편집"의 [검토 기능](https://help.genesis.autify.com/features-ko/workflow/pages/3Zc0vsWHZYv07Zk12HFM#검토-기능) 참조.

## 고급 옵션

인스펙터 안의 **고급 옵션**을 펼치면 다음 고급 설정을 사용할 수 있습니다.

![고급 옵션 화면](/files/FOWVMvKxe9UYILpUnNMW)

### 구조화된 출력

**구조화된 출력**을 활성화하면 AI 에이전트의 출력 형식을 JSON Schema로 정의할 수 있습니다. 후속 블록이 이 블록의 출력을 사용하는 경우 특정 필드에 접근하기 쉬워집니다.

스키마는 2가지 방법으로 정의할 수 있습니다.

| 편집 모드   | 내용                            |
| ------- | ----------------------------- |
| 스키마 편집기 | 필드를 하나씩 추가·삭제·설정하는 UI 디자이너 모드 |
| JSON    | JSON Schema를 직접 입력하는 텍스트 모드   |

스키마 편집기에서는 각 필드에 다음을 설정합니다.

| 설정 항목     | 내용                                                |
| --------- | ------------------------------------------------- |
| 필드 이름     | 출력 JSON의 프로퍼티 이름                                  |
| 스키마 유형    | string / number / boolean / array / object 중에서 선택 |
| 설명(선택 사항) | AI 에이전트에 대한 보충 설명. 적절한 값을 생성하는 데 활용할 수 있습니다       |
| 필수        | 이 필드를 필수로 할지 여부 설정                                |

**스키마 조정**을 클릭하면 개선하고 싶은 내용을 자연어로 입력하기만 해도 AI가 스키마를 자동 조정합니다.

{% hint style="warning" %}
구조화된 출력을 활성화한 경우, 스키마에 필드가 하나도 정의되어 있지 않으면 검증 오류가 됩니다.
{% endhint %}

### 사고 강도

지원되는 추론 모델에서는 **사고 강도**로 AI 에이전트 블록이 내부적으로 수행하는 추론량을 조절할 수 있습니다. **기본값**으로 두면 모델의 권장 설정이 사용됩니다. 복잡한 작업에서는 높이고, 더 빠른 응답이 필요한 단순한 작업에서는 낮춰 조절할 수 있습니다.

선택한 모델이 **사고 강도**를 지원하지 않는 경우, 이 항목은 사용할 수 없습니다.

### 도구

**도구**에서는 AI 에이전트가 실행 중에 사용할 수 있는 빌트인 도구를 개별적으로 선택합니다. 활성화한 도구는 에이전트가 필요하다고 판단했을 때 자동으로 호출됩니다.

활성화 중인 도구는 캔버스 위의 블록에 아이콘으로 나열됩니다. 오른쪽 아래의 **+** 버튼을 클릭하면, 인스펙터를 열지 않고 **도구** 탭과 같은 내용을 팝오버에서 추가·삭제할 수 있습니다.

GitHub·Slack·Aximo 등의 외부 서비스 연동이 설정되어 있는 경우, 해당하는 도구는 **도구** 탭에는 표시되지 않으며, 워크플로 실행 시에 자동으로 AI 에이전트에서 사용할 수 있습니다. 도구 전체의 종류와 이용 조건은 [도구](/features-ko/ai-feature/tools.md) 참조.

### MCP 서버

**MCP 서버**에서는 워크스페이스에 등록된 외부 MCP(Model Context Protocol) 연결을 추가하여 AI 에이전트의 기능을 확장할 수 있습니다. 외부 MCP 연결 등록 방법은 [워크스페이스 설정](/features-ko/settings/workspace-settings/workspace-configuration.md) 참조.

## 문제 해결

### 모델 오류

| 상황                                | 원인                           | 해결 방법         |
| --------------------------------- | ---------------------------- | ------------- |
| "선택한 모델 "{model}"을(를) 사용할 수 없습니다" | 선택한 모델이 활성화된 프로바이더에서 제공되지 않음 | 다른 모델을 선택하십시오 |

### 구조화된 출력 오류

| 상황                          | 원인                                       | 해결 방법                                 |
| --------------------------- | ---------------------------------------- | ------------------------------------- |
| 구조화된 출력이 활성화되어 있는데 실행할 수 없음 | 스키마에 필드가 하나도 정의되어 있지 않음                  | 스키마 편집기에서 필드를 추가하거나 구조화된 출력을 비활성화하십시오 |
| "JSON 스키마가 올바르지 않습니다"       | JSON 편집 모드에서 입력한 내용이 올바른 JSON Schema가 아님 | JSON 구문을 확인하여 수정하십시오                  |

### 프롬프트 오류

| 상황                                  | 원인                                     | 해결 방법                                               |
| ----------------------------------- | -------------------------------------- | --------------------------------------------------- |
| "프롬프트에서 사용 중인 변수가 입력에 정의되어 있지 않습니다" | 프롬프트 안의 `{{변수명}}`에 대응하는 입력이 설정되어 있지 않음 | 변수 삽입 메뉴에서 변수를 다시 삽입하거나, **입력** 탭에서 대응하는 입력을 추가하십시오 |

### MCP 서버 오류

| 상황                                    | 원인                                    | 해결 방법                       |
| ------------------------------------- | ------------------------------------- | --------------------------- |
| "이 워크스페이스에 존재하지 않는 MCP 연결을 사용하고 있습니다" | 블록에서 참조하는 MCP 연결이 삭제되었거나 다른 워크스페이스의 것 | MCP 서버 설정에서 연결을 다시 추가하십시오   |
| 연결 확인이 "오류"가 됨                        | MCP 서버가 응답하지 않거나 인증 정보가 올바르지 않음       | URL과 인증 정보를 확인하고 연결을 편집하십시오 |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://help.genesis.autify.com/features-ko/workflow/ai-agent-block.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.