> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getporter.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# REST API와 업무 웹페이지 활용

> REST API와 웹페이지를 도구로 등록해 AI가 호출할 수 있도록 설정합니다.

<Card>
  운영 중인 REST API를 AI가 호출할 수 있는 도구로 등록하고, 사내 업무 시스템이나 별도로 제작한 웹페이지를 채팅에 표시되는 위젯으로 연결할 수 있습니다. MCP 서버를 새로 개발하지 않아도 기존 API와 웹페이지를 AI로 활용할 수 있습니다.
</Card>

<Tip>
  운영 서버와 AI 호출을 분리하고 싶다면 같은 API 서버를 [애플리케이션 플랫폼](/ko/application-deployment)에 별도로 배포해 AI 전용으로 사용할 수 있습니다. 기존 트래픽과 로그를 분리하고, 접근 권한과 호출량도 AI 활용 목적에 맞게 관리할 수 있습니다.
</Tip>

## REST API 도구

### 기본 설정

<Frame>
  <img className="block rounded-md" src="https://files.cloudtype.io/ale-docs/ai/images/ko/tools01.png" />
</Frame>

> `스페이스 설정 > MCP 서버·도구` 페이지에서 웹호출 도구 `추가하기`를 클릭하고, 아래의 기본 설정값을 입력하세요.

<Steps>
  <Step title="Base URL">
    Base URL은 도구로 사용할 API의 공통 주소입니다. 각각의 API 도구를 추가할 때는 이 Base URL 뒤에 붙는 나머지 경로만 입력하면 됩니다. 예를 들어 Base URL을 `https://example.com`으로 설정했다면, 도구의 접속 URL에는 `/api/rooms`처럼 경로만 입력합니다.
  </Step>

  <Step title="인증 방식">
    API 접근을 위한 인증 값을 Access Token 또는 헤더 방식으로 입력할 수 있습니다.

    <Info>
      API가 별도의 인증 없이 호출 가능한 경우에는 `인증 없음`을 선택하세요.
    </Info>
  </Step>

  <Step title="공통 쿼리">
    공통 쿼리는 이 웹호출 도구에 포함된 모든 API 요청에 함께 전달되는 쿼리 파라미터입니다. 예를 들어 모든 요청에 `workspace_id`나 `locale` 같은 값이 항상 필요하다면 공통 쿼리에 추가할 수 있습니다.
  </Step>
</Steps>

### 도구 설정

> 도구 필드 우측의 <Icon icon="plus" iconType="solid" size={15} color="9fa3a5" /> 아이콘을 클릭하고 아래의 설정값을 입력하여 도구를 추가할 수 있습니다.

<Steps>
  <Step title="도구 이름">
    AI가 구분할 수 있는 도구 이름을 입력하세요.
  </Step>

  <Step title="접속 URL">
    Base URL 뒤에 붙는 API 경로를 입력하세요.
  </Step>

  <Step title="메소드">
    도구로 사용하려는 API 메소드를 선택하세요.
  </Step>

  <Step title="헤더와 쿼리">
    필요한 경우 API 호출에 필요한 헤더와 쿼리 파라미터를 입력하세요.
  </Step>

  <Step title="프롬프트">
    AI가 언제 이 도구를 사용해야 하는지 자연어로 설명하세요. 이 내용을 기반으로 AI가 해당 도구의 호출 여부를 판단합니다.
  </Step>

  <Step title="파라미터">
    접속 URL, 쿼리, 요청 본문에서 사용할 동적 값을 정의합니다.
  </Step>
</Steps>

<Tip>
  웹호출 도구에서는 하나의 API 엔드포인트를 하나의 도구로 추가하는 것을 권장합니다. API 목적별로 도구를 나누면 AI가 상황에 맞는 도구를 더 정확하게 선택할 수 있습니다.
</Tip>

### 접근 권한 설정

<Frame>
  <img className="block rounded-md" src="https://files.cloudtype.io/ale-docs/ai/images/ko/tools02.png" />
</Frame>

> 웹호출 도구 설정창의 권한 탭에서 팀원별 접근 권한을 설정할 수 있습니다.

### 활용

<Frame>
  <img className="block rounded-md" src="https://files.cloudtype.io/ale-docs/ai/images/ko/tools03.png" />
</Frame>

> 채팅창에서 추가한 웹호출 도구를 활성화하면, AI로 API를 활용할 수 있습니다.

<Info>
  에이전트 설정 과정에서 추가한 웹호출 도구를 활성화하여 에이전트의 도구로 사용하거나, Slack 등 메신저에서 사용하도록 설정할 수 있습니다.
</Info>

## 웹페이지 위젯 도구

### 위젯 설정

<Frame>
  <img className="block rounded-md" src="https://files.cloudtype.io/ale-docs/ai/images/ko/widget01.png" />
</Frame>

> `스페이스 설정 > 위젯` 페이지에서 `추가하기`를 클릭하고 위젯 설정값을 입력하면 위젯이 추가됩니다.

<div style={{ width: '100%', overflowX: 'auto' }}>
  <table
    style={{
  width: '100%',
  minWidth: '100%',
  tableLayout: 'auto',
  borderCollapse: 'collapse'
}}
  >
    <colgroup>
      <col style={{ width: '20%' }} />

      <col style={{ width: '30%' }} />

      <col style={{ width: '50%' }} />
    </colgroup>

    <thead>
      <tr>
        <th style={{ whiteSpace: 'nowrap', textAlign: 'left', border: '1px solid #d8dee4', padding: '10px 12px' }}>필드</th>
        <th style={{ whiteSpace: 'nowrap', textAlign: 'left', border: '1px solid #d8dee4', padding: '10px 12px' }}>입력값</th>
        <th style={{ textAlign: 'left', border: '1px solid #d8dee4', padding: '10px 12px' }}>설명</th>
      </tr>
    </thead>

    <tbody>
      <tr>
        <td style={{ whiteSpace: 'nowrap', textAlign: 'left', border: '1px solid #d8dee4', padding: '10px 12px' }}>도구 이름</td>
        <td style={{ textAlign: 'left', border: '1px solid #d8dee4', padding: '10px 12px' }}>LLM이 호출할 도구명</td>
        <td style={{ textAlign: 'left', border: '1px solid #d8dee4', padding: '10px 12px' }}>소문자, 숫자, 하이픈, 언더스코어만 사용 가능<br />예: <code>book-a-conference-room</code></td>
      </tr>

      <tr>
        <td style={{ whiteSpace: 'nowrap', textAlign: 'left', border: '1px solid #d8dee4', padding: '10px 12px' }}>제목</td>
        <td style={{ textAlign: 'left', border: '1px solid #d8dee4', padding: '10px 12px' }}>위젯의 표시명</td>
        <td style={{ textAlign: 'left', border: '1px solid #d8dee4', padding: '10px 12px' }}>사용자가 어떤 기능인지 알 수 있는 이름을 입력<br />예: <code>회의실 예약</code></td>
      </tr>

      <tr>
        <td style={{ whiteSpace: 'nowrap', textAlign: 'left', border: '1px solid #d8dee4', padding: '10px 12px' }}>설명</td>
        <td style={{ textAlign: 'left', border: '1px solid #d8dee4', padding: '10px 12px' }}>위젯이 필요한 상황</td>
        <td style={{ textAlign: 'left', border: '1px solid #d8dee4', padding: '10px 12px' }}>사용자가 어떤 요청을 했을 때 위젯을 표시할지 설명<br />예: <code>사용자가 회의실 예약을 필요로 할 때 표시합니다.</code></td>
      </tr>

      <tr>
        <td style={{ whiteSpace: 'nowrap', textAlign: 'left', border: '1px solid #d8dee4', padding: '10px 12px' }}>URL</td>
        <td style={{ textAlign: 'left', border: '1px solid #d8dee4', padding: '10px 12px' }}>웹서비스 주소</td>
        <td style={{ textAlign: 'left', border: '1px solid #d8dee4', padding: '10px 12px' }}>iframe으로 렌더링할 웹서비스 URL을 입력<br />예: <code>[https://example.com](https://example.com)</code></td>
      </tr>

      <tr>
        <td style={{ whiteSpace: 'nowrap', textAlign: 'left', border: '1px solid #d8dee4', padding: '10px 12px' }}>인증</td>
        <td style={{ whiteSpace: 'nowrap', textAlign: 'left', border: '1px solid #d8dee4', padding: '10px 12px' }}><code>인증 없음</code> 또는 <code>토큰</code></td>
        <td style={{ textAlign: 'left', border: '1px solid #d8dee4', padding: '10px 12px' }}>인증에 토큰이 필요한 경우, <code>토큰</code>을 선택하고 아래의 필드에 그 값을 입력</td>
      </tr>

      <tr>
        <td style={{ whiteSpace: 'nowrap', textAlign: 'left', border: '1px solid #d8dee4', padding: '10px 12px' }}>파라미터</td>
        <td style={{ whiteSpace: 'nowrap', textAlign: 'left', border: '1px solid #d8dee4', padding: '10px 12px' }}>JSON 또는 YAML 객체</td>
        <td style={{ textAlign: 'left', border: '1px solid #d8dee4', padding: '10px 12px' }}>iframe 렌더링 시 위젯에 전달할 추가 값을 입력</td>
      </tr>
    </tbody>
  </table>
</div>

### 접근 권한 설정

> 설정창 상단의 권한 탭에서 팀원별로 위젯에 대한 접근 권한을 설정할 수 있습니다.

### 채팅창에서 사용

<Frame>
  <img className="block rounded-md" src="https://files.cloudtype.io/ale-docs/ai/images/ko/widget02.png" />
</Frame>

> 위젯 등록 과정에서 설명 필드에 입력한 내용에 따른 요청으로 채팅창에서 위젯을 호출하여 활용할 수 있습니다.

<Info>
  위젯 도구는 채팅창에서 활성화하는 과정 없이 호출할 수 있습니다.
</Info>