TypeScript 도구 루프는 스키마에서 처리기 타입까지 이어져야 해

등록부를 타입으로 묶어

각 도구의 입력을 Zod 스키마나 TypeScript 인터페이스로 정의하고, 그 타입이 처리기 인자까지 흐르게 만들 수 있어. 이름과 임의 객체만 넘기는 등록부보다 컴파일러가 더 많은 불일치를 잡아 주지. Python에서 실행 중에 드러날 오류 상당수를 빌드할 때 막는 셈이야.

프로토콜은 Python과 같아

도우미 응답의 콘텐츠에는 tool_use 블록이 들어가고, 다음 사용자 턴의 tool_result가 같은 tool_use_id를 돌려줘. 모델이 끝낼 때까지 왕복하는 구조는 같아. TypeScript의 장점은 잘못된 메시지 조립을 타입 단계에서 거부하는 데 있어.

모델 입력도 실행 전에 검증해

도구 정의에는 JSON Schema인 input_schema가 있지만, 모델이 보낸 인자를 곧바로 믿으면 안 돼. 처리기를 부르기 전에 Zod로 해석하고 검증해. 문자열인지 숫자인지 애매한 값을 실제 런타임 계약으로 바꾸는 경계야.

원칙: 검증하지 않은 도구 입력은 모델의 의도를 추측하는 코드야. 스키마를 실행 경계까지 연결해.

Code

Typed registry + Zod validation·typescript

import Anthropic from '@anthropic-ai/sdk';
import { z } from 'zod';

const client = new Anthropic();

// 1. Zod 스키마 — 런타임 validation + TS 타입 한 방.
const weatherInput = z.object({ city: z.string().min(1) });
type WeatherInput = z.infer<typeof weatherInput>;

// 2. Tool name으로 키된 핸들러.
const handlers = {
  get_weather: async (input: WeatherInput) => ({
    city: input.city,
    temp_c: 22,
    condition: 'clear',
  }),
} as const;

// 3. 모델한테 보내는 tool 정의.
const tools: Anthropic.Tool[] = [
  {
    name: 'get_weather',
    description: 'Get current weather for a city.',
    input_schema: {
      type: 'object',
      properties: { city: { type: 'string' } },
      required: ['city'],
    },
  },
];

async function runLoop(userText: string, maxIters = 10): Promise<string> {
  const messages: Anthropic.MessageParam[] = [{ role: 'user', content: userText }];
  for (let i = 0; i < maxIters; i++) {
    const resp = await client.messages.create({
      model: 'claude-sonnet-4-6',
      max_tokens: 1024,
      tools,
      messages,
    });
    messages.push({ role: 'assistant', content: resp.content });

    if (resp.stop_reason !== 'tool_use') {
      const text = resp.content.find(b => b.type === 'text');
      if (text && text.type === 'text') return text.text;
      throw new Error('expected text in final assistant turn');
    }

    const toolUseBlocks = resp.content.filter(b => b.type === 'tool_use');
    const results = await Promise.all(
      toolUseBlocks.map(async b => {
        if (b.type !== 'tool_use') throw new Error('unreachable');
        if (b.name !== 'get_weather') throw new Error(`unknown tool: ${b.name}`);
        const input = weatherInput.parse(b.input); // 런타임 validate
        const out = await handlers.get_weather(input);
        return {
          type: 'tool_result' as const,
          tool_use_id: b.id,
          content: JSON.stringify(out),
        };
      })
    );
    messages.push({ role: 'user', content: results });
  }
  throw new Error('tool loop exceeded maxIters');
}

console.log(await runLoop('What is the weather in Seoul?'));

등록부를 타입으로 묶어

프로토콜은 Python과 같아

모델 입력도 실행 전에 검증해

Code

External links

Exercise

Progress

댓글 0