AI 에이전트 도구 사용 패턴

AI 에이전트

규칙

• 도구를 설명이 포함된 타입 함수로 정의 — 모델이 호출할 도구를 선택합니다
• 도구 스키마: { name, description, parameters: zodSchema, execute: async (args) => result }
• 다단계 루프: 메시지 전송 → 모델이 도구 호출 반환 → 도구 실행 → 결과를 다시 주입 → 완료될 때까지 반복
• 무한 루프 방지를 위한 maxSteps 제한 — 복잡성에 따라 기본 5-10단계
• Zod를 사용한 구조화된 출력: generateObject({ schema: z.object({...}) })로 보장된 형태 사용
• 재시도 로직: 도구 실행을 try/catch로 감싸고 일시적 오류에 대해 지수 백오프로 2-3회 재시도
• 에이전트 오케스트레이션: 복잡한 작업을 집중된 도구 세트를 가진 하위 에이전트로 분할, 코디네이터 에이전트가 위임
• 모델에 피드백하기 전에 항상 도구 결과 검증 — 신뢰할 수 없는 데이터 정리
• 에이전트 추론에 실시간 가시성을 위해 streamText와 onToolCall 사용

패턴

// 도구 정의
const tools = {
  searchDatabase: tool({
    description: "제품 데이터베이스 검색",
    parameters: z.object({ query: z.string(), limit: z.number().default(10) }),
    execute: async ({ query, limit }) => db.products.search(query, limit),
  }),
};

// 에이전트 루프
const result = await generateText({
  model,
  tools,
  maxSteps: 10,
  messages,
});

피해야 할 사항

• 에이전트에 제한 없는 도구 접근 권한 부여 — 작업에 맞게 도구 범위 지정
• maxSteps 누락 — 에이전트가 영원히 루프할 수 있음
• 검증 없이 도구 출력 신뢰 — 결과에 따라 조치하기 전에 항상 확인
• 모놀리식 에이전트 — 20개 이상의 도구를 가진 하나의 에이전트보다 집중된 하위 에이전트 선호