AI 에이전트 도구 사용: 함수 호출, 스키마, 안전한 실행
AI 에이전트 도구 사용은 LLM이 외부 함수 — 웹 검색, 데이터베이스 쿼리, API 호출, 파일 작업 — 의 실행을 요청하는 메커니즘으로, 구조화된 도구 호출 JSON을 출력하면 런타임이 이를 인터셉트하고 JSON 스키마에 대해 검증한 후 실행하여 도구 결과를 반환한다. LLM은 아무것도 실행하지 않는다; 요청만 한다. 런타임은 실행 전에 스키마 검증, ACL 검사, 단계 예산을 적용한다. tau-bench(2025)는 인수 구성 오류가 도구 사용의 최대 실패 모드임을 보여준다.
AI 에이전트 도구 사용은 대규모 언어 모델이 외부 함수 — 웹 검색, 데이터베이스 쿼리, API 호출, 파일 작업 또는 커스텀 비즈니스 로직 — 의 실행을 요청하는 메커니즘으로, 출력에 구조화된 도구 호출을 출력하면 런타임이 이를 인터셉트하고 JSON 스키마 정의에 대해 검증하고 실행하여 다음 컨텍스트 턴에 도구 결과로 반환한다.
도구 호출 작동 방식: 요청-실행-반환 루프
도구 호출 생명주기
모든 도구 호출은 프레임워크나 프로바이더에 관계없이 동일한 5단계 루프를 따른다:
- 컨텍스트 설정 — 에이전트는 작업과 이용 가능한 도구 목록을 받는다. 각 도구는 이름, 자연어 설명, 파라미터의 JSON 스키마 정의로 설명된다.
- LLM 결정 — 모델은 출력에 도구 호출 블록을 출력한다: 함수 이름과 선언된 스키마에 맞는 JSON 인수 객체.
- 런타임 인터셉트 — 프레임워크는 실행 전에 도구 호출을 인터셉트한다. 인수는 스키마에 대해 검증된다. 에이전트의 ACL이 확인된다: 이 에이전트가 이 도구를 호출할 권한이 있는가?
- 실행 — 검증과 권한 검사가 통과되면 런타임이 함수를 실행하고 출력을 수집한다.
- 컨텍스트 주입 — 도구 결과가 도구 결과 턴으로 대화 컨텍스트에 다시 주입된다. LLM은 이 풍부해진 컨텍스트에서 추론을 계속한다.
핵심 아키텍처적 사실: LLM은 아무것도 실행하지 않는다. 요청만 한다. 파일 쓰기, API 호출, 이메일 전송 등 모든 안전하지 않은 작업은 런타임에 의해 제어된다.
프로바이더 형식 차이: OpenAI vs Anthropic vs Google
세 가지 주요 LLM 프로바이더는 도구 사용을 네이티브로 지원하지만 JSON 형식이 다르다:
OpenAI(openai/openai-python, 30,941 스타, Apache-2.0): 도구 정의는 JSON 스키마 객체 배열로 tools 파라미터에 들어간다. 모델은 어시스턴트 메시지의 tool_calls 필드에 도구 호출을 반환한다. 클라이언트는 role: "tool" 메시지로 도구 결과를 보내 돌려준다. Responses API(2025년 3월)는 서버 사이드에서 실행되는 내장 도구(web_search, file_search, computer_use)를 추가했다.
Anthropic(anthropic-sdk-python, 3,595 스타, MIT): 도구 정의는 최상위 tools 파라미터에 들어간다. 모델은 어시스턴트 턴 내에 tool_use 콘텐츠 블록을 반환한다. 클라이언트는 이 블록들을 파싱하고 다음 휴먼 턴에 tool_result 콘텐츠 블록을 반환해야 한다.
Google Gemini: 도구 정의는 tools 파라미터 내에 functionDeclarations를 사용한다. 모델은 functionCall 파트를 반환하고; 클라이언트는 functionResponse 파트를 보낸다. Gemini는 ANY 모드와 AUTO 모드의 tool_config를 지원한다.
형식은 의미적으로 동등하지만 구문적으로 충분히 달라서 한 프로바이더의 규칙을 하드코딩하면 모델을 교체할 때 실패한다.
실제로 도구를 실행하는 주체 (그리고 왜 보안에 중요한가)
LLM은 도구를 실행할 수 없다. 요청만 할 수 있다. 런타임이 모든 도구 실행 전에 ACL 게이트를 적용하면, 어떤 LLM 출력도 권한 검사를 우회할 수 없다. 모델은 어떤 인수로든 delete_all_records()를 요청할 수 있지만, 에이전트의 권한 매트릭스에 해당 도구가 포함되지 않으면 런타임이 실행 전에 요청을 거부한다.
LLM이 올바르게 사용하는 도구 스키마 정의
tau-bench(ServiceNow Research, 2025)는 GPT-4o가 리테일 도구 사용 작업에서 44% pass@1을 기록함을 측정했다. 가장 큰 실패 카테고리는 도구 선택이 아니라 — 모델은 올바른 도구를 선택했다 — 인수 구성이었다. 스키마 품질이 신뢰성의 주요 레버다.
도구 정의를 위한 JSON 스키마 구조
최소한의 유효한 도구 스키마에는 4개의 필드가 필요하다:
{
"name": "search_web",
"description": "최신 정보를 위해 공개 웹을 검색한다. 작업이 훈련 컷오프 이후의 사실, 실시간 데이터 또는 훈련 데이터에 없는 소스를 필요로 할 때 사용한다.",
"parameters": {
"type": "object",
"properties": {
"query": {
"type": "string",
"description": "검색 쿼리. 구체적이고 목표 지향적인 용어를 사용한다. 완전한 문장이 아닌."
},
"max_results": {
"type": "integer",
"description": "반환할 최대 결과 수. 기본값 5, 최대 20.",
"default": 5
}
},
"required": ["query"]
}
}
required 배열이 중요하다: required에 없는 파라미터는 선택적이다. 자주 생략되는 필수 파라미터는 스키마 설명 문제를 나타낸다.
인수 오류를 줄이는 설명 작성
인수 구성 정확도를 향상시키는 도구 설명의 세 가지 규칙:
- 동사-명사 쌍으로 이름 짓기:
search_web,create_ticket,read_file. 유사한 도구 간의 모호성을 피한다. - 설명에서 명확화하기: 두 도구가 유사해 보이면 각각을 언제 사용할지 명시적으로 기술한다.
- 예시로 파라미터 설명하기:
"검색 쿼리. 예: 'LangGraph v0.2 병렬 도구 호출'"은 정확도에서"쿼리 문자열"을 능가한다.
일반적인 스키마 실수와 수정 방법
| 실수 | 효과 | 수정 |
|---|---|---|
범주형 값에 무제한 "type": "string" | 모델이 잘못된 값을 만들어낸다 | "enum": ["option_a", "option_b"] 사용 |
파라미터에 description 없음 | 모델이 인수 의미론을 추측한다 | 예시가 포함된 명시적 설명 작성 |
모든 파라미터가 required에 있음 | 선택적 필드가 알 수 없을 때 모델이 호출을 거부한다 | 진짜 필수 파라미터만 나열 |
모호한 도구 이름 (process, handle) | 모델이 유사한 도구를 구별할 수 없다 | 동사-명사 사용: submit_form, parse_date |
required 배열 없음 | JSON 스키마가 유효하지 않음 | 비어있어도([]) 항상 required 포함 |
엄격 모드: 정확한 스키마 준수 적용
OpenAI의 구조화된 출력 엄격 모드(도구 정의에 "strict": true)는 모델의 출력 JSON이 선언된 스키마와 정확히 일치함을 보장하여 인수 구성 오류 카테고리 전체를 제거한다.
병렬 및 순차 도구 호출
병렬 도구 호출을 사용하는 경우
OpenAI의 Responses API(2025년 3월)는 병렬 도구 호출을 기본값으로 만들었다. 단일 LLM 턴에서 모델은 여러 도구 실행을 동시에 요청할 수 있다. 독립적인 도구의 경우, 병렬 디스패치는 N번의 순차적 턴에서 하나의 동시 배치로 라운드트립을 줄인다.
예: 리서치 에이전트가 현재 주가, 최근 뉴스, 회사의 SEC 제출 서류가 필요하다. 세 가지 모두 독립적이다. 순차: 3개 LLM 턴 x 10초 = 30초. 병렬: 1개 LLM 턴 + max(도구 지연) 약 10초.
전제 조건: 도구가 진정으로 독립적이어야 한다. 도구 B가 도구 A의 출력을 인수로 필요로 하면 순차적이어야 한다.
의존적 작업을 위한 순차 도구 호출
도구 체이닝은 순차 실행을 필요로 한다. 패턴: search_web(쿼리) → fetch_page(검색 결과의 URL) → extract_data(페이지 콘텐츠) → summarize(추출된 데이터).
상태 있는 리소스와의 동시성 위험
상태 있는 리소스에 대한 병렬 도구 호출은 순서 보장이 필요하다. 규칙: 도구가 읽기 전용이거나 독립적인 리소스에 쓰는 경우 병렬 디스패치는 안전하다.
도구 출력 파싱 및 오류 복구
도구 호출은 실패한다. 외부 API가 503을 반환한다. 데이터베이스 쿼리가 타임아웃된다. 잘 설계된 도구 사용 구현은 복구 가능한 오류에 대해 인간 개입 없이 실패를 처리한다.
도구 출력 검증
HTTP 200을 반환하는 도구가 올바르고 유용한 결과를 반환하는 도구와 같지 않다. 에이전트의 컨텍스트에 주입하기 전에 예상 스키마에 대해 출력을 검증한다.
재시도 전략: 언제 어떻게 재호출할까
다양한 실패 모드에 대한 세 가지 재시도 패턴:
- 일시적 실패 재시도 (네트워크 타임아웃, 속도 제한): 짧은 백오프 후 동일한 인수로 동일한 도구를 재호출한다.
- 인수 명확화 재시도: 인수가 거부된 이유를 설명하는 구조화된 오류를 LLM에 반환한다.
- 폴백 도구: 도구 A가 N번 재시도 후 실패하면 동등한 기능을 가진 도구 B로 라우팅한다.
오케스트레이터에 도구 실패 보고
복구 불가능한 오류는 오케스트레이터에 보고되어야 한다. 멀티 에이전트 파이프라인의 경우 오케스트레이터는 구조화된 실패 신호가 필요하다. AI 에이전트 오케스트레이션 패턴에서 이것이 에스컬레이션 경로이다.
도구 권한 범위 지정 및 보안
최소 권한 도구 할당
각 에이전트는 특정 작업에 필요한 도구만 보유해야 한다. 프롬프트 인젝션에 성공한 에이전트의 폭발 반경은 허용된 도구 집합에 의해 제한된다. OWASP LLM Top 10 v1.1(2025)은 LLM 애플리케이션의 최대 위험으로 프롬프트 인젝션(LLM01)을 나열한다.
실행 전 입력 검증
도구 호출 인수를 두 계층에서 검증한다: 스키마 검증과 의미론적 검증. fetch_page 도구는 SSRF를 방지하기 위해 file:// 또는 localhost URL이 있는 인수를 거부해야 한다.
도구 수준 공격 벡터의 전체 분류는 AI 에이전트 보안 위협 모델을 참조.
되돌릴 수 없는 작업: 휴먼인더루프 게이트
되돌릴 수 없는 부작용이 있는 도구 호출 — 이메일 전송, 레코드 삭제, 자금 이체, 콘텐츠 게시 — 은 실행 전에 명시적인 인간 확인 게이트 또는 멱등성 검사가 필요하다.
OpenLegion의 관점: 도구 레지스트리와 ACL 게이트
모든 주요 LLM 프로바이더는 서로 다른 도구 호출 API를 가지고 있다. 올바른 추상화: 도구를 한 번 정의하고 프레임워크가 호출 시 올바른 프로바이더 규칙으로 변환하도록 한다.
OpenLegion의 도구 레지스트리는 이 추상화를 구현한다. search_web을 한 번 정의한다. 메시는 설정된 모델에 따라 OpenAI tools, Anthropic tools 또는 Gemini functionDeclarations로 변환한다. ACL 게이트는 선택 사항이 아니다. 모든 도구 호출 — 내장형, MCP, 커스텀 — 은 실행 전에 에이전트별 권한 매트릭스를 통과한다.
| 차원 | OpenLegion | LangChain / LangGraph | OpenAI Agents SDK | CrewAI | Anthropic 직접 |
|---|---|---|---|---|---|
| 도구 정의 형식 | 단일 스키마, 프로바이더 변환 | 프로바이더별 래퍼 필요 | OpenAI 형식만 | CrewAI 도구 데코레이터 | Anthropic tool_use 형식만 |
| 프로바이더 추상화 | 예 — GPT-4o, Claude, Gemini 통합 | 부분적 — LangChain 통합 경유 | 아니오 — OpenAI 모델만 | 부분적 | 아니오 — Anthropic만 |
| ACL 적용 | 에이전트별 권한 매트릭스, 구조적 | 내장 없음 | 내장 없음 | 내장 없음 | 내장 없음 |
| 병렬 도구 호출 | 지원 | 지원(프로바이더 의존) | 예 — Responses API 기본값 | 지원 | 예 — Claude 지원 |
| 내장 도구 | 브라우저, 파일, HTTP, 쉘, 이미지 생성 | LangChain 커뮤니티 도구 경유 | web_search, file_search, computer_use | 내장 없음 | 내장 없음 |
| MCP 통합 | 네이티브 — 동일한 ACL/예산 파이프라인 | LangChain MCP 어댑터 경유 | 실험적 | 네이티브 아님 | 네이티브 아님 |
MCP 사양, 서버 아키텍처, 서버별 권한 요구 사항은 Model Context Protocol 가이드를 참조.
내장 도구 vs MCP 도구 vs 커스텀 도구
내장 런타임 도구
내장 도구는 런타임에 의해 미리 강화된다: 브라우저 자동화, 파일 작업, HTTP 요청, 쉘 명령, 이미지 생성. 내장 도구를 먼저 사용한다.
MCP 도구 서버
MCP 도구는 stdio 또는 HTTP를 통한 JSON-RPC로 도구를 노출하는 Model Context Protocol 서버에 의해 제공된다. MCP 도구는 명시적 샌드박싱과 서버별 권한 범위 지정이 필요하다.
커스텀 도구 등록
커스텀 도구는 에이전트의 도구 레지스트리에 작성하고 등록하는 Python(또는 TypeScript) 함수이다. 완전한 유연성을 제공한다; 트레이드오프는 검증, 오류 처리, 멱등성, 보안 제어를 직접 소유해야 한다는 것이다.
자주 묻는 질문
AI 에이전트 도구 사용이란 무엇인가요?
AI 에이전트 도구 사용은 대규모 언어 모델이 외부 함수 — 웹 검색, API 호출, 데이터베이스 쿼리, 파일 작업 — 의 실행을 요청하는 메커니즘으로, 런타임이 인터셉트, 검증, 실행하는 구조화된 도구 호출 JSON을 출력한다. LLM은 직접 아무것도 실행하지 않는다; 무엇을 호출할지와 어떤 인수를 사용할지를 설명할 뿐이다.
AI 에이전트에서 함수 호출은 어떻게 작동하나요?
함수 호출은 요청-실행-반환 루프로 작동한다: 에이전트는 작업과 이용 가능한 도구 목록을 받는다; LLM은 함수를 명명하고 인수를 제공하는 도구 호출을 출력한다; 런타임은 그 인수를 검증하고 함수를 실행하며 결과를 컨텍스트에 도구 결과로 주입한다.
AI 에이전트를 위한 좋은 도구 스키마란 무엇인가요?
좋은 도구 스키마는 동사-명사 이름(search_web, create_ticket), 언제 사용할지를 모호함 없이 명시하는 설명, 가능하면 열거형을 사용하는 강타입 파라미터, 필수 파라미터를 나열하는 required 배열을 사용한다. tau-bench(2025)는 잘못된 인수 구성이 가장 일반적인 실패 모드임을 보여준다.
병렬 도구 호출이란 무엇이고 언제 사용해야 하나요?
병렬 도구 호출은 에이전트가 단일 LLM 턴에서 여러 도구 실행을 요청할 수 있게 하며 런타임이 동시에 디스패치한다. 도구가 독립적일 때 — 출력이 서로 의존하지 않고 공유 상태 있는 리소스에 쓰지 않을 때 — 병렬 호출을 사용한다.
AI 에이전트에서 도구 호출 루프를 어떻게 방지하나요?
도구 호출 루프는 에이전트가 최종 답변에 수렴하지 않고 계속 도구를 호출할 때 발생한다. 유일하게 신뢰할 수 있는 방지책은 인프라 수준에서 적용되는 단계 예산: 오케스트레이터가 적용하는 에이전트 실행당 도구 호출의 엄격한 최대값.
AI 에이전트 도구 사용의 보안 위험은 무엇인가요?
주요 위험은 도구 결과 인젝션이다: 에이전트가 에이전트의 동작을 재지정할 수 있는 공격자 제어 콘텐츠를 반환하는 도구를 호출할 때. OWASP LLM Top 10 v1.1(2025)은 LLM 애플리케이션의 최대 위험으로 프롬프트 인젝션을 나열한다. 완화책으로는 출력 새니타이징, 최소 권한 도구 할당, 되돌릴 수 없는 작업을 위한 휴먼인더루프 게이트가 있다.
내장 도구, MCP 도구, 커스텀 도구의 차이점은 무엇인가요?
내장 도구는 이미 ACL 적용이 적용된 에이전트 런타임에 의해 제공된다. MCP 도구는 JSON-RPC로 외부 기능을 노출하는 Model Context Protocol 서버에 의해 제공된다; 샌드박싱과 서버별 권한 범위 지정이 필요하다. 커스텀 도구는 작성하고 등록하는 함수로, 완전한 유연성이 있지만 검증과 보안에 대한 책임이 있다.
다양한 LLM 프로바이더는 도구 사용을 어떻게 구현하나요?
OpenAI는 tools 파라미터, 어시스턴트 응답의 tool_calls, role: "tool" 결과 메시지로 도구 사용을 구현한다. Anthropic은 다음 휴먼 턴의 tool_result 블록과 함께 tool_use 콘텐츠 블록을 사용한다. Google Gemini는 응답에 functionCall 파트, 후속 턴에 functionResponse 파트와 함께 functionDeclarations를 사용한다. 세 형식은 의미적으로 동등하지만 구문적으로 다르다.
도구를 한 번 정의하고, 어디서나 안전하게 실행하세요
tau-bench(2025)는 GPT-4o를 도구 사용 작업에서 44% pass@1로 놓으며, 인수 구성을 지배적인 실패 카테고리로 꼽는다. 동사-명사 이름, 타입 있는 열거형, 파라미터 예시가 있는 정확한 스키마가 그 격차의 대부분을 좁힌다.
에이전틱 워크플로우 패턴과 AI 에이전트 평가 벤치마크는 이 페이지에서 다루는 기초를 확장한다.