에러 처리

에러 타입

Agent 에러

에러	발생 시점	복구 방법
AgentError	에이전트 일반 실패	stepId에서 컨텍스트 확인
ToolError	도구 실행 중 예외 발생	toolName 확인, handler 수정
MaxStepsError	ReAct 루프가 maxSteps에 도달	maxSteps 증가 또는 작업 단순화

Client 에러

에러	발생 시점	복구 방법
SchiftError	API 호출 실패	status와 code 확인
AuthError	유효하지 않은 API 키 (401)	sch_... 키 확인
QuotaError	사용량 한도 초과 (402)	플랜 업그레이드 또는 리셋 대기

Agent 에러 캐치

import { AgentError, MaxStepsError } from "@schift-io/sdk";

try {
  const result = await agent.run("Complex question");
} catch (err) {
  if (err instanceof MaxStepsError) {
    console.log("Agent took too many steps. Try a simpler question.");
  } else if (err instanceof AgentError) {
    console.log(`Agent error at step ${err.stepId}: ${err.message}`);
  }
}

Max Steps

기본 maxSteps는 10입니다. 에이전트가 더 많은 도구 호출이 필요하면 값을 늘리세요:

const agent = new Agent({
  maxSteps: 25,  // 최대 25번의 ReAct 반복 허용
  ...
});

maxSteps에 도달하면 agent.run()은 에러 메시지를 output으로 반환합니다 (throw하지 않음). result.steps에서 마지막 단계의 타입을 확인하세요:

const result = await agent.run("...");
const lastStep = result.steps[result.steps.length - 1];

if (lastStep.type === "error") {
  console.log("Agent did not reach a final answer");
}

도구 에러 처리

도구 handler의 에러는 캐치되어 LLM에 반환됩니다. 에이전트는 에러를 확인하고 재시도하거나 다른 접근 방식을 사용할 수 있습니다.

const riskyTool: AgentTool = {
  name: "risky_api",
  description: "Call an unreliable API",
  handler: async (args) => {
    try {
      const data = await callUnreliableAPI(args);
      return { success: true, data };
    } catch (err) {
      return {
        success: false,
        data: null,
        error: err.message,
      };
    }
  },
};

API Client 에러

import { SchiftError, AuthError, QuotaError } from "@schift-io/sdk";

try {
  const results = await rag.search("query");
} catch (err) {
  if (err instanceof AuthError) {
    console.log("Check your API key");
  } else if (err instanceof QuotaError) {
    console.log("Quota exceeded -- upgrade your plan");
  } else if (err instanceof SchiftError) {
    console.log(`API error: ${err.status} ${err.code}`);
  }
}