• LLM 에이전트는 일본 고유의 데이터(성명의 읽기 방식·법인 번호·육요(六曜)·주소 표기)를 그럴듯하게 환각(Hallucination)한다. 대책은 모델의 지능을 높이는 것이 아니라, 확정값을 반환하는 tool을 갖추게 하여 모델에는 '호출 판단'만 맡기는 것이다. - ChatGPT GPTs / Function Calling 통합은 지난 글에서 다루었다. 본 기사는 코드로 에이전트를 구성하는 경우, 즉 Vercel AI SDK / LangChain에 일본 데이터 tool 군을 자체적인 tool 정의 없이 바로 가져다 쓰는 구현 가이드이다. - 사용하는 것은 npm의 shirabe-sdk (v0.2.0)이다. shirabe-sdk/ai와 shirabe-sdk/langchain의 subpath import만으로 주소 정규화·성명 분할·읽기 추정·법인 번호 검증/조회·역법의 7가지 tool이 생성된다. Python도 PyPI의 동일한 이름의 패키지로 동일한 7가지 tool을 제공한다 (LangChain / OpenAI Agents SDK 대응). - tool의 실체는 Shirabe의 REST API이다 (대부분 API 키가 필요 없으며 익명으로 호출 가능). 반환값은 '확정값 + 확신도 + 출처' 구조의 JSON으로, 에이전트가 그대로 답변에 포함할 수 있다.

• Vercel AI SDK / LangChain으로 업무용 에이전트·RAG·자동화 파이프라인을 구축하고 있는 개발자

• 고객 명부·거래처 데이터의 정규화(주소·후리가나·법인 번호)를 LLM에게 맡겼다가 조용한 사고를 인지하신 분

• "tool calling은 알겠는데, tool 정의(schema·description·fetch·출처 관리)를 작성하는 것이 번거롭다"고 느끼는 분

일본 데이터에는 LLM이 구조적으로 틀리기 쉬운 카테고리가 있다.

이것들은 "똑똑한 모델로 바꾸면 해결되는" 종류의 문제가 아니다. **읽기는 원리적으로 비일의적(non-unique)**이고, 법인 번호는 레지스트리 실재 확인이 필요하며, 육요는 결정적인 계산이 필요하고, 주소는 주소 베이스 레지스트리와의 대조가 정답인 형태이기 때문이다.

tool calling은 바로 이를 위한 기제이지만, 실무에서는 다음과 같은 boilerplate(상용구 코드)가 남는다.

• tool마다 zod schema + description을 작성해야 함 (모델이 호출 판단을 틀리지 않도록 영어로 명확하게 작성)
• fetch·에러 핸들링·타임아웃을 작성해야 함
• 응답의 **출처(attribution)**를 누락 없이 전달해야 함
• 게다가 Vercel AI SDK와 LangChain은 tool의 타입이 다르기 때문에 이중으로 작성해야 함

shirabe-sdk는 위의 1~4번을 모두 완료해 두었다. core는 런타임 의존성이 없으며(Node 18+ / Workers / Deno / 브라우저), framework 어댑터는 subpath로 분리되어 있어 사용하는 쪽에서만 optional peer dependency를 추가하면 된다.

# Vercel AI SDK에서 사용할 경우
npm install shirabe-sdk ai zod
# LangChain에서 사용할 경우
...

import { generateText, stepCountIs } from "ai";
import { openai } from "@ai-sdk/openai";
import { shirabeAITools } from "shirabe-sdk/ai";
...

shirabeAITools()는 generateText / streamText의 tools에 그대로 전달할 수 있는 ToolSet을 반환한다. 모델은 prompt에 따라 shirabe_name_reading과 shirabe_calendar를 스스로 선택하여 호출하고, 확정값을 바탕으로 답변한다.

import { ChatOpenAI } from "@langchain/openai";
import { shirabeLangChainTools } from "shirabe-sdk/langchain";
const tools = shirabeLangChainTools();
...

에이전트 루프(Agent Loop) 전체를 맡긴다면 LangGraph의 prebuilt agent에 그대로 전달할 수 있습니다.

import { createReactAgent } from "@langchain/langgraph/prebuilt";
const agent = createReactAgent({
llm: new ChatOpenAI({ model: "gpt-4o" }),
...

LangChain 버전의 각 tool은 결과를 JSON 문자열로 반환합니다 (LangChain의 tool 출력 규약에 맞춰져 있습니다).

Python 측도 PyPI의 shirabe-sdk

v0.2.0에서 동일한 7가지 tool을 사용할 수 있습니다 (import 명은 shirabe이며, core는 표준 라이브러리만 사용).

pip install "shirabe-sdk[langchain]" # LangChain(langchain-core >= 0.3.40)
pip install "shirabe-sdk[openai-agents]" # OpenAI Agents SDK(Python 3.9+)

LangChain (Python). LangGraph의 create_react_agent에도 그대로 전달할 수 있습니다:

from shirabe.langchain import shirabe_langchain_tools
from langchain_openai import ChatOpenAI
tools = shirabe_langchain_tools()
...

OpenAI Agents SDK:

from agents import Agent, Runner
from shirabe.openai_agents import shirabe_openai_agents_tools
agent = Agent(
...

description은 영어로 "언제 호출해야 하는지", "왜 LLM이 스스로 답해서는 안 되는지"까지 작성되어 있어, 모델의 호출 판단이 안정적입니다 (예: shirabe_name_reading은 "Japanese name readings are NOT unique … never assume a single reading"라고 명시).

읽기 추정은 다음과 같이 반환됩니다 (2026-07-17 실행 실측값).

{
"reading": "しょうじゆうこ",
"candidates": [
...

reading은 최빈 읽기이며, candidates는 인명 사전(JMnedict)에 수록된 다른 읽기 전체를 망라합니다. 읽기가 유일하지 않다는 사실을 숨기지 않고 구조화하여 반환하므로, 에이전트는 "가장 유력한 것은 'しょうじゆうこ'이며, 다른 읽기 가능성으로는 이것들이 있습니다"라고 정직하게 답할 수 있습니다 (이 설계의 배경은 이전 기사에 자세히 나와 있습니다).

주소 정규화는 출처와 함께 다음과 같이 반환됩니다.

{
"input": "東京都港区六本木6-10-1",
"result": {
...

tool의 실체는 core의 ShirabeClient이므로, 에이전트를 거칠 필요가 없는 처리(야간 배치 명칭 통합(Name Matching)·CI에서의 스모크 테스트)는 직접 호출하면 됩니다.

import { ShirabeClient } from "shirabe-sdk";
const shirabe = new ShirabeClient(); // 키 없이 시작
const r = await shirabe.nameReading("東海林裕子");
...

옵션은 3 가지만 기억하면 충분하다.

new ShirabeClient({
apiKey: process.env.SHIRABE_API_KEY, // 유료 플랜의 키 (X-API-Key로 전송)
baseUrl: "https://shirabe.dev", // 기본값. 보통 변경할 필요 없음
...

shirabeAITools(options)

/ shirabeLangChainTools(options)

도 동일한 옵션을 받는다.

물론 직접 정의하는 것이 정답인 상황도 있다 (사내 API와 섞어서 하나의 ToolSet으로 구성하거나, tool의 설명문을 자사 도메인 어휘에 맞추는 등). 그 경우에도 이 SDK의 tool-specs 설계(framework에 의존하지 않는 사양 1곳에서 각 어댑터를 생성)는 그대로 참고가 될 것이다.

각 tool이 반환하는 값의 출처는 응답의 attribution에 기계 판독 가능한 형태로 포함되어 있다. **제거하지 말고 그대로 전달(pass-through)**할 것.

• 주소: Address Base Registry (디지털청, CC BY 4.0)
• 성명 분할: IPAdic (BSD 3-Clause)
• 읽기 추정: JMnedict (EDRDG, CC BY-SA 4.0 — 파생 데이터의 재배포에는 ShareAlike 상속이 적용됨)
• 법인 번호: 국세청 법인 번호 공표 사이트의 데이터

에이전트의 답변에 그대로 실으면 귀속 의무를 충족할 수 있는 형태로 되어 있다.

• 일본 고유 데이터(읽기·법인 번호·육요·주소)는 LLM이 단정 짓게 하지 말고, 확정값 tool에 맡기고 모델에는 호출 판단만 시킨다.

• shirabe-sdk/ai (Vercel AI SDK) / shirabe-sdk/langchain를 import 한 줄만 추가하면 해당 tool 군 7개가 생성된다. tool 정의, fetch, 출처 관리를 직접 작성할 필요가 없다. Python (LangChain / OpenAI Agents SDK)도 PyPI의 동일한 이름의 패키지로 동일하게 제공된다.

• 거의 모든 tool이 API 키가 필요 없으므로, npm install로부터 작동하는 에이전트까지 단 몇 분 만에 도달할 수 있다.

• shirabe-sdk (npm)

• 시리즈 기간: #12 법인 번호 선택지 비교 / #13 주소 정규화 선택지 비교 / #14 법인 번호 GPTs/Function Calling 통합 / #16 성명 읽기 추정 통합 가이드

• Shirabe (각 API의 문서·OpenAPI·요금은 각 제품 페이지에서)

• Zenn 버전 (동일 저자): https://zenn.dev/shirabe_dev