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

> 에이전트가 채팅 중 도구(MCP tool)를 호출할 때 대화창에 나타나는 Tool Call 카드

# Tool call

# Tool Call (도구 호출 표시)

**경로**: 채팅 영역의 에이전트 응답 흐름 중 — 도구가 실행되는 순간 자동 노출

에이전트가 응답을 생성하는 동안 외부 도구(MCP tool)를 호출하면, 해당 호출·결과가 **Tool Call 카드** 로 시각화됩니다. 사용자는 무엇이 실행됐는지·어떤 데이터가 반환됐는지 확인할 수 있습니다.

<Frame>
  <img src="https://mintcdn.com/dnotitia-328335e7/3mgjFAVO5t1rKplH/images/image-26.png?fit=max&auto=format&n=3mgjFAVO5t1rKplH&q=85&s=f9bab2f5420fc79205e6f8b84913dcc5" alt="Image" width="1646" height="392" data-path="images/image-26.png" />
</Frame>

<Frame>
  <img src="https://mintcdn.com/dnotitia-328335e7/3mgjFAVO5t1rKplH/images/image-25.png?fit=max&auto=format&n=3mgjFAVO5t1rKplH&q=85&s=4c55d9836510bc93a89576fa8502ffea" alt="Image" width="2150" height="1632" data-path="images/image-25.png" />
</Frame>

## 카드 구성

| 영역                 | 내용                                                                            |
| ------------------ | ----------------------------------------------------------------------------- |
| **순번**             | 응답 내 호출 순서 (예: `1`, `2`) — 여러 도구 연쇄 호출 시 흐름 파악                                |
| **도구 이름**          | 호출된 MCP 서버 + 도구 이름 (예: `analytics__execute_query`, `temp-files__create_file`) |
| **상태 배지**          | `Running` → `Success` / `Failed`                                              |
| **실행 시간**          | 시작\~완료까지 소요 시간 (예: `1.44ms`)                                                  |
| **Arguments** (입력) | LLM이 도구에 전달한 파라미터 (JSON, 접기/펼치기)                                              |
| **Result** (출력)    | 도구 반환값 — 텍스트·JSON·**파일 카드**·이미지 등                                             |
| **VIEW 버튼**        | 출력이 파일인 경우 **인라인 미리보기** 열기 (PDF·DOCX·HTML·이미지 등)                              |
| **에러 스택**          | 실패 시 에러 메시지와 스택 트레이스                                                          |

## 파일 결과 — Preview & Download

도구 호출 결과가 **파일**(생성·변환·다운로드) 인 경우, Tool Call 카드에 파일 카드가 나타나고 **미리보기와 다운로드** 를 한 자리에서 제공합니다.

| 요소                         | 동작                                                                                      |
| -------------------------- | --------------------------------------------------------------------------------------- |
| **파일명**                    | 예: `goal_achievement_chart.html`, `report.pdf`                                          |
| **파일 크기**                  | 예: `15968 B` / `386.8 KB`                                                               |
| **VIEW** 버튼                | 채팅창 우측/모달로 **인라인 미리보기**                                                                 |
| **Download**               | 로컬 저장                                                                                   |
| `display_in_tool_pane` 플래그 | 도구가 `temp-file-create` 등으로 설정 시 [Temp Files](/agent-chat/toolbar/temp-files) 패널에도 즉시 노출 |

### 미리보기 지원 형식

| 카테고리              | 확장자                                                   | 비고                                               |
| ----------------- | ----------------------------------------------------- | ------------------------------------------------ |
| **문서**            | `.pdf` · `.docx` · `.hwp` · `.hwpx`                   | 페이지 렌더 (Word 는 가능 시 일부 서식만)                      |
| **웹 콘텐츠**         | `.html` · `.htm` · `.xhtml`                           | iframe 렌더 — 차트·스타일 그대로                           |
| **Markdown/Text** | `.md` · `.markdown` · `.txt`                          | 마크다운 렌더                                          |
| **이미지**           | `.png` · `.jpg` · `.jpeg` · `.gif` · `.svg` · `.webp` | 인라인 표시                                           |
| **데이터**           | `.json` · `.csv` · `.tsv`                             | 구조화 뷰어                                           |
| **프레젠테이션**        | `.pptx`                                               | 슬라이드별 프리뷰 이미지 (`render_slide_screenshots` 결과 동일) |

미리보기 불가 형식(예: `.duckdb`, 독점 바이너리) 은 VIEW 버튼이 비활성화되고 **Download** 만 제공됩니다.

<Info>
  **인라인 미리보기의 강점**

  * 대화 밖으로 나가지 않고 **생성 결과 즉시 확인** — 특히 차트·표가 든 HTML/PDF 는 바로 검증 가능
  * 다운로드 전 내용을 확인해 **불필요한 파일 저장 방지**
  * PDF 의 특정 페이지, HTML 의 특정 섹션을 확인한 뒤 후속 지시 (`3페이지 표를 수정해줘`) 가능
</Info>

## 상태 전환

<Steps>
  <Step title="Running (실행 중)">
    * 배지 회전 아이콘
    * 입력 파라미터만 먼저 표시
    * 장시간 걸리는 도구는 중간 진행 메시지도 스트림
  </Step>

  <Step title="Success (성공)">
    * 녹색 체크 배지 + 실행 시간 표시
    * 출력 영역 채워짐 — 큰 응답은 자동으로 접힘
    * 결과 카피 버튼 제공
  </Step>

  <Step title="Failed (실패)">
    * 빨간색 엑스 배지
    * 에러 메시지·스택 표시
    * 에이전트는 오류를 컨텍스트로 받아 재시도하거나 다른 도구 호출
  </Step>
</Steps>

## 대표 사례

<Tabs>
  <Tab title="SQL 실행">
    **도구**: `analytics.execute_query`

    ```json theme={null}
    // 입력
    {
     "sql": "SELECT region, SUM(amount) FROM sales GROUP BY region"
    }
    ```

    출력은 표 형태 텍스트 또는 JSON으로 렌더. 에이전트는 결과를 자연어로 풀어서 재응답.
  </Tab>

  <Tab title="문서 생성">
    **도구**: `pptx.create_presentation`

    입력: 템플릿 이름·제목 출력: 생성된 `.pptx` 파일 링크 (Temp Files 패널에 저장)

    생성된 파일은 [Temp Files](/agent-chat/toolbar/temp-files) 패널에서 다운로드 가능.
  </Tab>

  <Tab title="웹 검색">
    **도구**: `web-search.web_search`

    ```json theme={null}
    // 입력
    { "query": "2026 kubernetes 최신 릴리즈" }
    ```

    출력: 검색 결과 상위 N개의 제목·URL·스니펫.
  </Tab>

  <Tab title="외부 API (사용자 등록)">
    **도구**: `github.get_pull_request` 같은 [Tool Management](/console/agent-ops/agent-tool) 에서 등록한 MCP

    에이전트에 연결된 도구라면 어떤 MCP 서버라도 동일한 Tool Call 카드로 표시됩니다.
  </Tab>
</Tabs>

## 사용자 조작

* **입력/출력 펼치기·접기**: 긴 JSON·텍스트는 기본 접힘
* **복사**: Arguments 또는 Result JSON 을 클립보드에 복사
* **VIEW**: 파일 결과의 **인라인 미리보기** (PDF·DOCX·HTML·이미지·MD 등)
* **Download**: 파일 결과 로컬 저장
* **Temp Files 연동**: 생성된 파일은 [Temp Files](/agent-chat/toolbar/temp-files) 패널에도 실시간 동기화 — 세션 전체 산출물을 한곳에서 관리
* **재실행 (실패 시)**: 에이전트가 자동으로 재시도하거나, 사용자가 메시지에서 다시 요청 가능

## 권한·보안

* **도구 활성화 상태 확인** — [MCP Tools 패널](/agent-chat/toolbar/mcp-tools) 에서 활성 도구만 호출 가능
* **민감 정보**: 입력 파라미터에 비밀값이 있으면 로그에 남을 수 있음 — Tool Call 카드는 기본적으로 내용을 표시하므로 **비밀값은 환경변수 (`system_default` / `vault`)** 로 주입하세요
* **감사 로그**: 호출 이력은 [Events](/internal/system-admin/operations/events) 에 기록됨

<Info>
  도구 호출은 에이전트 응답의 일부로 과금될 수 있습니다. 도구별 과금 정책은 [Billing → AI 모델 가격](/billing#ai-모델-가격-krw--1m-tokens) 참고.
</Info>

<Warning>
  에이전트가 같은 도구를 짧은 시간에 반복 호출하는 경우 Rate Limit이나 [Blocked API Keys](/internal/system-admin/operations/blocked-api-keys) 에 걸릴 수 있습니다. 도구별 호출 빈도를 모니터링하세요.
</Warning>

## 관련 문서

* [MCP Tools 패널](/agent-chat/toolbar/mcp-tools) — 연결된 MCP 서버·도구 활성화
* [Tool Management](/console/agent-ops/agent-tool) — 도구 등록·관리
* [채팅 영역](/agent-chat/ui/chat-area) — Tool Call 카드가 표시되는 컨테이너
* [Flow Studio](/agent-chat/toolbar/flow-studio) — 다단계 워크플로에서 도구 호출 시각화