---
id: pattern-tool-calling
title: "Tool Calling Pattern"
category: "Pattern_AI"
status: "draft"
verification_status: "applied"
canonical_id: ""
aliases: ["Tool Calling", "function calling", "도구 호출 패턴", "action tag"]
duplicate_of: ""
source_trust_level: "A"
confidence_score: 0.88
created_at: 2026-06-13
updated_at: 2026-06-13
review_reason: ""
merge_history: []
tags: ["pattern", "ai", "tool-calling", "function-calling", "platform-independent"]
raw_sources: ["일반 소프트웨어 공학 지식", "ConnectAI/src/agent/actions/* (적용 예)"]
applied_in: ["ConnectAI"]
github_commit: ""
---

# [[Tool Calling Pattern]]

## 🎯 한 줄 통찰 (One-line insight)
Tool Calling 은 "모델이 자연어 대신 구조화된 호출(함수/태그)로 외부 도구를 실행" 하게 해 실제 행동(파일 생성·명령 실행·검색)을 가능케 하며, *모델 출력을 신뢰 경계로 보고 검증·승인* 하는 것이 안전의 핵심이다.

## 🧠 핵심 개념 (Core concepts)
1. 도구 스키마 정의(이름·인자). 2. 모델이 호출 의도를 구조화 출력(JSON function call 또는 `<action>` 태그). 3. 실행기가 파싱→검증→실행→결과 반환. 4. 위험 동작은 승인 게이트.

## 📖 세부 내용 (Details · 패턴 명세)
- **Problem (언제 쓰나):** 모델이 텍스트를 넘어 *행동* 해야 할 때(파일/명령/API/검색).
- **사용 조건:** 도구 인터페이스 명확; 출력 파싱 가능; 권한/검증 체계.
- **장점:** 실제 작업 자동화, 결정론 도구로 환각 보완, 확장성(도구 추가).
- **단점:** 보안 위험(임의 명령), 파싱 실패, 잘못된 인자, 무한 호출.
- **대안:** 사람이 실행, 고정 워크플로(모델 미개입), 제한된 화이트리스트 액션.
- **실패 사례:** 모델 출력을 검증 없이 실행(주입 공격); 경로 미검증으로 임의 파일 접근; 승인 없는 파괴적 명령.

## 💻 코드 패턴 (Code patterns)
```text
output = LLM(system + tools_schema + task)
for call in parseToolCalls(output):       # <create_file>, <run_command> ...
    if !validate(call): skip/log
    if dangerous(call): await approval()  # 승인 게이트
    result = execute(call)                # 실행기로 라우팅
    feed(result -> next turn)
```
적용 예: ConnectAI 의 action tag 실행기(src/agent/actions/*) + 승인 큐(approval) + 경로 검증(security.validatePath). 라우팅은 [[Agent 오케스트레이터 분해]] 참조.

## ⚖️ 모순 및 업데이트 (Contradictions & updates)
"모델이 시키는 대로 실행" 은 위험 — 모델 출력은 *신뢰되지 않은 입력* 으로 다뤄 검증·샌드박스·승인을 거쳐야 한다.

## 🛠️ 적용 사례 (Applied in summary)
ConnectAI action tags + approval gate + validatePath/sanitizeCommand.

## 🔗 지식 그래프 (Knowledge Graph)
- **상위/루트:** [[패턴 카탈로그 인덱스]]
- **관련 개념:** [[Agent Orchestration Pattern]], [[API Client Pattern]], [[Command Pattern]], [[소프트웨어 실패 라이브러리]]
- **참조 맥락:** 작은 모델이 행동하는 에이전트를 만들 때 안전 경계와 함께 참조.

## 📚 출처 (Sources)
- [S1] 일반 function/tool calling 지식
- [S2] ConnectAI/src/agent/actions/*, security.ts — 적용 예

## 📝 변경 이력 (Change history)
- 2026-06-13: 프로젝트 독립 패턴 카드 작성.
