콘텐츠로 이동

도구 (Tools) 통합

모델이 실제로 무엇인가를 실행하게 하려면, "어떤 도구가 있고 어떤 인자를 받는지"를 모델에게 알려줘야 합니다. Vercel AI SDK는 그 도구 정의를 tool() 도우미로 만들고 tools 파라미터로 넘겨, 여러 모델에서 같은 도구를 그대로 쓰게 해줍니다. 이 페이지는 소스 문서 AI SDK Core Tool Calling 을 바탕으로 도구 정의와 통합을 설명합니다.

개요

LLM은 생각하고 말만 할 뿐 코드를 실행하지 못합니다. 그래서 캔버스가 다이어그램을 그리거나 뉴런이 실제 행동으로 이어지려면, 모델이 "이 도구를 호출하겠다"는 결정을 내리고 우리 코드가 그 도구를 실행하는 분업이 필요해요. AI SDK는 이 분업에서 도구의 정의·검증·실행을 한곳에 모아 다룹니다. 한 번 정의한 도구를 벤더별 문법 차이 없이 여러 모델에 재사용하는 것이 핵심입니다.

핵심 개념

도구의 네 가지 요소

tool() 도우미로 만드는 도구는 크게 네 부분으로 이뤄집니다.

  • description — 도구가 무엇을 하는지 설명. 모델이 도구를 고를 때 이 설명을 보고 판단해요.
  • inputSchema — 인자 형식을 정의하는 Zod 또는 JSON 스키마. 모델에게 전달되고, 모델의 도구 호출을 검증하는 데도 쓰입니다.
  • execute — 도구 호출의 인자를 받아 실제로 실행하는 비동기 함수. 생략할 수 있는데, 도구 호출을 같은 프로세스에서 실행하지 않고 클라이언트나 큐로 넘길 때는 빼도 됩니다.
  • strict — 공급자가 지원할 때 엄격한 도구 호출을 켜는 선택 옵션.

tool()을 쓰면 execute의 인자 타입을 자동으로 추론해서, 입력과 출력이 타입 안전하게 연결됩니다.

도구 등록과 호출 흐름

tools 파라미터는 도구 이름을 키로, 도구 값을 값으로 갖는 객체입니다. generateText나 streamText에 넘기면, 모델이 필요할 때 그 도구를 호출합니다. 모델이 도구를 쓰는 호출을 tool call, 그 실행 결과를 tool result라고 불러요. 이 둘은 결과 객체에서 toolCalls, toolResults로 확인할 수 있습니다.

동적 설명 (Dynamic Descriptions)

도구 설명은 고정 문자열일 수도, 함수일 수도 있어요. 테넌트·프로젝트·환경 같은 현재 맥락에 따라 모델에게 보낼 설명을 바꿔야 할 때 함수로 정의합니다. 예를 들어 "이 프로젝트에서 셸 명령 실행"처럼 toolsContext의 값을 읽어 설명을 조립하면 됩니다. 설명 함수는 각 생성 단계에서 도구 정의를 모델에 보내기 전에 해석돼요.

검증과 타입 안전

inputSchema는 두 가지 일을 합니다. 하나는 모델에게 인자 형태를 알려주는 것, 다른 하나는 모델이 만든 도구 호출을 검증하는 것이에요. 그래서 잘못된 인자가 execute에 들어가는 걸 막아줍니다. 타입스크립트 환경에서는 InferUITool 같은 타입 도우미로 도구의 입력·출력 타입까지 추론해서 클라이언트와 서버 양쪽의 타입 안전을 보장합니다.

도구 호출이 익숙해지면 "모델이 어떤 일을 실행할지"를 프롬프트 문장 대신 도구 정의로 옮길 수 있어요. 구조화된 스키마로 알려주는 게 말로 지시하는 것보다 모델이 실행 대상을 정확히 고르는 데 더 유리합니다.

실제 적용 (데이터스케쳐스)

  • 캔버스 요소 배치 — moveElement(x, y) 같은 도구를 inputSchema(예: z.object({ x: z.number(), y: z.number() }))로 정의해, 모델이 다이어그램 요소를 어디 놓을지 결정하도록 합니다.
  • 뉴런 (자율 에이전트) 행동 — 상황을 판단한 뒤 다음 행동을 도구로 실행합니다. 도구 호출이 에이전트의 실제 행동 경로예요.
  • 데이터 조회·가공 — 필요한 데이터를 가져오는 함수를 도구로 노출해, 답변을 추측이 아니라 실제 값에 근거하게 합니다.
  • 멀티벤더 재사용 — 도구를 한 번 정의하면 Claude·GPT·Gemini 어느 모델에서도 같은 정의로 작동해, AI SDK가 벤더별 도구 문법 차이를 숨겨줍니다.

더 알아보기