프롬프트 엔지니어링 팁

프롬프트 엔지니어링 팁

프롬프트는 LLM 호출의 품질을 좌우하는 뼈대예요. AI SDK에서 프롬프트를 잘 다루려면 도구를 쓸 때의 프롬프트 규칙, Zod 스키마와 LLM 입력의 매핑, 그리고 디버깅을 위한 요청·경고 확인 방법을 함께 알아야 해요. 여기서는 원하는 결과를 안정적으로 뽑는 팁을 정리해 볼게요.

출처: 공식문서

본문

도구용 프롬프트

도구를 포함한 프롬프트는 도구의 수와 복잡성이 늘어날수록 좋은 결과를 얻기 까다로워져요. 다음 규칙을 지키는 걸 권장해요.

  • 도구 호출에 강한 모델을 쓰세요. 예컨대 gpt-5나 gpt-4.1 같은 모델이 좋아요. 약한 모델은 도구를 정확하게 호출하는 데 어려움을 겪어요.
  • 도구 수를 적게 유지하세요. 대략 5개 이하가 좋아요.
  • 도구 파라미터의 복잡성을 낮추세요. 중첩·옵션이 많은 복잡한 Zod 스키마, 유니언 등은 모델이 다루기 어려워요.
  • 의미 있는 이름을 쓰세요. 도구·파라미터·프로퍼티 이름에 정보가 많을수록 모델이 요구를 이해하기 쉬워요.
  • .describe("...")로 힌트를 주세요. Zod 스키마 프로퍼티에 특정 프로퍼티가 무엇을 위한 건지 설명을 달면 도움이 돼요.
  • 도구 간 의존성과 출력이 불분명하다면, 도구의 description 필드로 실행 결과의 출력에 대한 정보를 제공하세요.
  • 예시를 포함하세요. 도구 호출의 입·출력 예시를 프롬프트에 넣으면 모델이 도구 사용법을 이해하는 데 도움돼요. 도구는 JSON 객체로 동작하므로 예시도 JSON으로 써야 해요.

요점은 모델에 필요한 모든 정보를 명확하게 주는 거예요.

도구·구조화 데이터 스키마

Zod 스키마에서 LLM 입력(보통 JSON 스키마)으로의 매핑은 일대일이 아니라 항상 직관적이진 않아요.

Zod 날짜 — Zod는 JavaScript Date 객체를 기대하지만, 모델은 날짜를 문자열로 반환해요. z.string().datetime()이나 z.string().date()로 날짜 형식을 지정·검증하고, Zod transformer로 문자열을 Date 객체로 변환하면 돼요.

const result = await generateText({
  model: "xai/grok-4.6",
  output: Output.object({
    schema: z.object({
      events: z.array(
        z.object({
          event: z.string(),
          date: z
            .string()
            .date()
            .transform(value => new Date(value)),
        }),
      ),
    }),
  }),
  prompt: 'List 5 important events from the year 2000.',
});

옵션 파라미터 — 엄격한 스키마 검증을 쓰는 일부 프로바이더(특히 OpenAI 구조화 출력의 strict 모드)에서 옵션 파라미터와 호환성 문제가 생길 수 있어요. 최대 호환성을 위해 옵션 파라미터는 .optional() 대신 .nullable() 을 쓰는 게 좋아요.

// This may fail with strict schema validation
const failingTool = tool({
  description: 'Execute a command',
  inputSchema: z.object({
    command: z.string(),
    workdir: z.string().optional(), // This can cause errors
    timeout: z.string().optional(),
  }),
});

// This works with strict schema validation
const workingTool = tool({
  description: 'Execute a command',
  inputSchema: z.object({
    command: z.string(),
    workdir: z.string().nullable(), // Use nullable instead
    timeout: z.string().nullable(),
  }),
});

온도 설정 — 도구 호출과 객체 생성에서는 결정적이고 일관된 결과를 위해 temperature: 0을 권장해요. 낮은 온도는 모델 출력의 무작위성을 줄이는데, 특정 형식의 구조화 데이터를 생성해야 하거나, 올바른 파라미터로 정밀한 도구 호출을 해야 하거나, 엄격한 스키마를 일관되게 따라야 할 때 특히 중요해요.

디버깅

경고 확인 — 모든 프로바이더가 모든 AI SDK 기능을 지원하진 않아요. 프로바이더는 지원하지 않는 기능에 예외를 던지거나 경고를 반환해요. 프롬프트·도구·설정이 프로바이더에 올바르게 처리되는지 확인하려면 호출 경고를 검사하면 돼요.

const result = await generateText({
  model: "xai/grok-4.6",
  prompt: 'Hello, world!',
});

console.log(result.warnings);

요청 메시지 확인 — 마지막 스텝에서 모델로 보낸 입력 메시지를 보려면 request.messages를 써요. 스텝 결과에 이 메시지들을 포함하려면 include: { requestMessages: true }로 설정하고 result.finalStep.request.messages로 접근해요.

HTTP 요청 본문 확인 — OpenAI처럼 본문을 노출하는 모델이라면 원시 HTTP 요청 본문을 검사할 수 있어요. 프로바이더별로 정확히 어떤 페이로드가 전송되는지 볼 수 있죠. 요청 본문은 응답의 finalStep.request.body 프로퍼티로 접근할 수 있어요.

더 알아보기