도구 작성

도구는 LLM이 부를 수 있는 함수입니다. 새 능력을 루프 안에 직접 넣지 말고 도구로 추가하면, 루프는 얇게 유지되고 권한 게이트와 훅이 그 도구에도 그대로 적용됩니다. 도구 하나를 추가하는 작업은 네 단계로 나뉩니다. 정의, 구현, 등록, 권한 분류입니다.

1. 정의를 등록합니다

LLM이 보는 스키마는 core/tools/definitions.json에 모읍니다. 항목은 리스트의 한 객체이고, name(snake_case), description, input_schema(JSON Schema), 그리고 분류 메타데이터인 category와 cost_tier를 가집니다.

{
  "name": "weather_lookup",
  "description": "Look up the current weather for a city.",
  "category": "external",
  "cost_tier": "free",
  "input_schema": {
    "type": "object",
    "properties": {
      "city": { "type": "string", "description": "City name" }
    },
    "required": ["city"]
  }
}

category와 cost_tier의 허용 값은 core/tools/base.py의 VALID_CATEGORIES와 VALID_COST_TIERS(free / cheap / expensive)에 정의되어 있습니다.

2. 핸들러를 구현합니다

도구는 core/tools/base.py의 Tool 프로토콜을 따릅니다. name, description, parameters 프로퍼티와 aexecute() 코루틴 네 가지면 유효한 도구입니다. 덕 타이핑을 사용하므로 클래스를 상속할 필요가 없습니다. 실패는 tool_error()로 구조화된 dict을 돌려줘서 LLM이 분류하고 복구할 수 있게 합니다. 기존 구현은 core/tools/web_tools.py의 WebFetchTool을 참고하세요.

# core/tools/weather_tools.py
from typing import Any

class WeatherLookupTool:
    @property
    def name(self) -> str:
        return "weather_lookup"

    @property
    def description(self) -> str:
        return "Look up the current weather for a city."

    @property
    def parameters(self) -> dict[str, Any]:
        return {
            "type": "object",
            "properties": {
                "city": {"type": "string", "description": "City name"},
            },
            "required": ["city"],
        }

    async def aexecute(self, **kwargs: Any) -> dict[str, Any]:
        city = kwargs["city"]
        if not city:
            from core.tools.base import tool_error
            return tool_error("city is required", error_type="validation")
        # ... fetch and shape ...
        return {"result": {"city": city, "summary": "..."}}

3. 핸들러 맵에 등록합니다

핸들러가 존재한다고 자동으로 호출 대상이 되지는 않습니다. 중립 런타임 조합점은 core/tools/handlers/의 그룹별 빌더를 충돌 검사 후 하나의 불변 플랜으로 묶습니다. 클래스를 인스턴스화해 aexecute를 감싼 클로저를UniqueEntries로 돌려주고, neutral_handler_groups()에 한 번 등록합니다 (core/tools/handlers/single_tool.py의 패턴).

# core/tools/handlers/single_tool.py 패턴
from core.tools.handlers.registration import UniqueEntries

def _build_weather_handlers() -> UniqueEntries[str, Any]:
    from core.tools.weather_tools import WeatherLookupTool
    tool = WeatherLookupTool()

    async def handle_weather_lookup(**kwargs: Any) -> dict[str, Any]:
        return await tool.aexecute(**kwargs)

    return UniqueEntries((("weather_lookup", handle_weather_lookup),))

# core/tools/handlers/__init__.py — neutral_handler_groups()
("weather", _build_weather_handlers()),

definitions.json의 name과 dict 키가 정확히 같아야 합니다. 스키마나 핸들러 한쪽이 빠지면 세션을 시작하기 전compose_tool_plan()이 명시적으로 실패합니다.

4. 권한 등급을 정합니다

권한 분류는 core/agent/safety.py의 frozenset에서 결정됩니다. 읽기 전용 도구는 SAFE_TOOLS에 둡니다. 승인 없이 실행됩니다. 영속 상태(메모리, 파일, 자격증명)를 바꾸면 WRITE_TOOLS에 넣어 사용자 확인을 받게 하고, 시스템 접근이면 DANGEROUS_TOOLS에 넣습니다. 비용이 큰 호출이면 EXPENSIVE_TOOLS dict에 예상 비용을 적어 비용 확인 게이트를 켭니다. 이 set들을 ApprovalWorkflow(core/agent/approval.py)가 읽어서 실행 직전에 HITL 프롬프트를 띄웁니다.

# core/agent/safety.py
SAFE_TOOLS = frozenset({
    ...,
    "weather_lookup",  # read-only — no approval prompt
})

모드별·노드별 추가 차단이 필요하면 core/tools/policy.py의 PolicyChain으로denied_tools / allowed_tools를 거는 6-layer 정책 체인을 사용합니다.

확인

스키마와 핸들러 양쪽이 실제로 연결됐는지 확인합니다.

uv run python -c "
from core.tools.composition import compose_tool_plan
bound, _transient = compose_tool_plan()
print('weather_lookup' in bound.schema_map)
print('weather_lookup' in bound.handlers)
"

둘 다 통과하면 LLM에 스키마가 노출되고 호출이 실행됩니다. 마지막으로 대화형 세션에서 한 번 불러봅니다. 셸 원샷은 지원하지 않습니다.

geode

> 서울 날씨 알려줘

참조: Tool protocol, MCP tools.