도구 (Tool) 정의 — 입출력 스키마 계약

도구는 에이전트의 읽기 입구 입니다. 본 레슨은 새 도구 한 개를 어떻게 정의하는지 를 잡습니다. 핵심은 LLM 이 도구를 언제·어떻게 호출할지 를 스키마 한 줄과 설명 한 단락 으로 명시하는 것입니다.

도구 정의의 4 영역

D.Hub 에서 도구는 다음 4 영역으로 구성됩니다.

1. 이름 + 설명

• 이름 — 영문, snake_case. LLM 이 이 이름을 함수처럼 호출합니다.
• 설명 — 1–3 문장. 언제 이 도구를 써야 하는지 를 LLM 이 판단하는 핵심 신호입니다.

좋은 설명은 호출 조건 을 명시합니다.

"고객의 주문 ID 가 주어졌을 때, 그 주문에 대한 enrichment 데이터 (고객 메타, 과거 환불 카운트 포함) 한 행을 반환합니다. 환불 결정을 위해 컨텍스트 수집 단계에서 사용합니다."

나쁜 설명은 기술 동작 만 적습니다.

"enriched_orders 데이터셋의 row 를 fetch."

2. 입력 파라미터 — JSON Schema

도구가 받는 입력은 JSON Schema 로 명시합니다. 예시 (get_enriched_order 도구):

{
  "type": "object",
  "properties": {
    "order_id": {
      "type": "string",
      "description": "주문 고유 식별자 (예: ORD-007)"
    }
  },
  "required": ["order_id"]
}

각 파라미터의 description 도 함수 자체의 설명만큼 중요합니다 — LLM 이 어떤 값을 넘길지 를 description 으로 판단합니다. 입력 형식 (e.g. "ORD-" 접두어 필수) 도 description 에 명시합니다.

3. 출력 스키마 — JSON Schema

출력도 같은 방식으로 명시합니다.

{
  "type": "object",
  "properties": {
    "order_id": {"type": "string"},
    "customer_id": {"type": "string"},
    "total_amount": {"type": "number"},
    "tier": {"type": "string", "enum": ["standard", "silver", "gold", "platinum"]},
    "past_refund_count": {"type": "integer"},
    "past_approval_rate": {"type": "number"}
  }
}

출력 스키마가 명시돼 있으면 LLM 이 후속 추론에서 어떤 필드를 사용할 수 있는지 를 정확히 압니다.

4. 구현 — 코드 노드 또는 외부 호출

실제 도구 동작은 코드 노드 한 개로 구현됩니다 (D.Hub 의 코드 자원). 입력 파라미터를 받아 출력 스키마에 맞는 JSON 을 반환하는 함수 한 개. 코드 노드 작성은 엔지니어 코스 레슨 4 패턴 그대로.

get_enriched_order 구현 예시 (Python, 단순화):

def get_enriched_order(order_id: str) -> dict:
    row = enriched_orders.filter(f"order_id = '{order_id}'").first()
    if row is None:
        return {"error": "order not found"}
    return {
        "order_id": row.order_id,
        "customer_id": row.customer_id,
        "total_amount": row.total_amount,
        "tier": row.tier,
        "past_refund_count": row.past_refund_count,
        "past_approval_rate": row.past_approval_rate,
    }

도구 등록 — 에이전트에 연결

작성한 도구를 에이전트에 연결합니다. 에이전트 빌더 화면 좌측 도구 영역에 + 도구 추가 → 방금 만든 도구를 고릅니다. 한 에이전트에 5–10 개의 도구 가 일반적입니다.

도구 vs 액터 — 한 줄 구분

본 레슨이 다루는 도구 는 부작용 없는 읽기 만 다룹니다. 환불 발사 나 이메일 발송 같은 외부 상태 변경 은 액터 로 분리합니다 (다음 레슨). 한 함수가 읽기 + 쓰기 를 동시에 하면 안전 게이트를 놓기 어렵습니다.

이 레슨에서 익혀야 할 것

• 도구 정의의 4 영역 — 이름 / 입력 스키마 / 출력 스키마 / 구현
• 설명 한 단락 이 LLM 의 도구 선택 을 좌우한다는 점
• 도구 = 읽기, 액터 = 쓰기 의 분업

다음 레슨

액터를 자동 액터 와 인간 검토 액터 로 분리해 HITL 워크플로를 설계합니다.