코딩 에이전트 시작하기

코딩 에이전트 시작하기

이 페이지에서는 코딩 에이전트(예: Claude Code, Codex, OpenCode, Cursor 또는 기타 AI 지원 개발 환경) 안에서 작업할 때 AI SDK를 최대한 활용하는 방법을 설명해요.

출처: 문서

본문

AI SDK 스킬 설치하기

코딩 에이전트에게 AI SDK에 대한 깊은 지식을 제공하는 가장 빠른 방법은 공식 AI SDK 스킬을 설치하는 거예요. 스킬은 가벼운 마크다운 파일로, 필요할 때 에이전트의 컨텍스트에 특화된 지침을 불러와요. 그래서 에이전트가 SDK 사용법을 정확히 알게 되고, 직접 설명할 필요가 없어요.

npx skills add를 사용해서 AI SDK 스킬을 설치하세요:

npx skills add vercel/ai

이 명령은 해당 에이전트의 스킬 디렉터리(예: .claude/skills, .codex/skills)에 스킬을 설치해요. 에이전트를 두 개 이상 선택하면 CLI가 심링크를 만들어 각 에이전트가 스킬을 찾을 수 있게 해줘요. -a를 사용하면 에이전트를 직접 지정할 수 있어요. 예를 들어 -a amp는 범용 .agents/skills 디렉터리에 설치해요. 비대화형 설치에는 -y를 사용해요.

설치가 완료되면 Agent Skills 형식을 지원하는 모든 에이전트가 AI SDK 작업을 할 때 스킬을 자동으로 발견하고 불러와요.

Agent Skills는 **점진적 공개(progressive disclosure)** 방식을 사용해요. 에이전트는 시작할 때 스킬의 이름과 설명만 불러와요. 전체 지침은 작업이 필요할 때만 컨텍스트에 불러오므로 에이전트가 빠르고 집중된 상태를 유지할 수 있어요.

node_modules의 문서와 소스 코드

ai 패키지를 설치하면 AI SDK 전체 문서와 소스 코드가 이미 node_modules 안에 로컬로 준비돼 있어요. 코딩 에이전트는 인터넷 연결 없이도 이 파일들을 직접 읽을 수 있어요.

아직 설치하지 않았다면 ai 패키지를 설치하세요:

설치가 끝나면 에이전트는 다음과 같은 경로에서 번들로 제공되는 소스 코드와 문서를 참조할 수 있어요:

node_modules/ai/src/              # Full source code organized by module
node_modules/ai/docs/             # Official documentation with examples

즉, 에이전트가 설치된 패키지에서 정확한 API 시그니처, 구현 코드, 사용 예제를 직접 찾아볼 수 있어요. 그래서 프로젝트에 실제로 설치된 SDK 버전을 항상 사용하게 돼요.

DevTools 설치하기

AI SDK DevTools는 개발 중에 AI SDK 호출을 전체적으로 들여다볼 수 있게 해줘요. LLM 요청, 응답, 도구 호출, 토큰 사용량, 다단계 상호작용을 캡처해서 로컬 웹 UI에 표시해요.

AI SDK DevTools는 실험적인 기능이며 로컬 개발 전용이에요. 프로덕션 환경에서는 사용하지 마세요.

DevTools 패키지를 설치하세요:

통합 등록하기

모든 AI SDK 호출을 캡처하도록 DevToolsTelemetry를 전역으로 등록하세요:

import { registerTelemetry } from 'ai';
import { DevToolsTelemetry } from '@ai-sdk/devtools';

registerTelemetry(DevToolsTelemetry());

통합을 등록하면 모든 AI SDK 호출에 대해 텔레메트리가 자동으로 활성화돼요:

import { generateText } from 'ai';

const result = await generateText({
  model: openai('gpt-6-astra'),
  prompt: 'What cities are in the United States?',
});

뷰어 실행하기

별도의 터미널에서 DevTools 뷰어를 시작하세요:

npx @ai-sdk/devtools@latest

http://localhost:4983을 열면 AI SDK 상호작용을 실시간으로 확인할 수 있어요.

도구 호출과 출력 확인하기

DevTools는 모든 호출에 대해 다음 항목을 캡처하고 표시해요:

  • 입력 파라미터와 프롬프트 — LLM에 전송된 전체 입력
  • 출력 콘텐츠와 도구 호출 — 생성된 텍스트와 도구 호출
  • 토큰 사용량과 소요 시간 — 단계별 리소스 소비와 지연 시간
  • 원시 프로바이더 데이터 — 전체 요청 및 응답 페이로드

다단계 에이전트 상호작용의 경우 DevTools는 모든 것을 런(run)(전체 상호작용)과 스텝(step)(그 안의 개별 LLM 호출)으로 묶어서 보여줘요. 에이전트가 정확히 무엇을 했고 왜 그랬는지 쉽게 추적할 수 있어요.

개발 중에 코드에서 도구 결과를 직접 로그로 남길 수도 있어요:

import { streamText, tool, isStepCount } from 'ai';
import { z } from 'zod';

const result = streamText({
  model,
  prompt: "What's the weather in New York in celsius?",
  tools: {
    weather: tool({
      description: 'Get the weather in a location (fahrenheit)',
      inputSchema: z.object({
        location: z.string().describe('The location to get the weather for'),
      }),
      execute: async ({ location }) => ({
        location,
        temperature: Math.round(Math.random() * (90 - 32) + 32),
      }),
    }),
  },
  stopWhen: isStepCount(5),
  onStepEnd: async ({ toolResults }) => {
    if (toolResults.length) {
      console.log(JSON.stringify(toolResults, null, 2));
    }
  },
});

onStepEnd 콜백은 각 LLM 스텝이 끝난 후 실행되며 도구 결과를 터미널에 출력해요. DevTools UI를 열지 않고 빠르게 디버깅할 때 유용해요.

DevTools는 모든 AI 상호작용을 로컬 `.devtools/generations.json` 파일에 저장해요. 민감한 상호작용 데이터가 커밋되지 않도록 `.gitignore`에 `.devtools`를 자동으로 추가해요.

다음 단계는?

내비게이션

전체 사이트맵

더 알아보기 (Learn more)