AI SDK Harnesses

AI SDK Harnesses

AI SDK harness 추상화는 단일 AI SDK 표면을 통해 검증된 에이전트 harness를 실행하게 해줘요. harness는 완전한 에이전트 런타임이에요. 예: Claude Code, Codex, Pi. 모델 호출보다 큰 기능(워크스페이스 접근, 내장 코딩 tools, 네이티브 세션 상태, 압축(compaction), 권한 흐름, 런타임별 설정)을 소유해요. 또한 모든 AI SDK 에이전트 harness는 sandbox에서 동작해 호스트 환경을 안전하게 유지해요.

AI SDK harness 추상화는 프로바이더/모델 추상화와는 별개예요. 프로바이더는 generateText 나 streamText 같은 AI SDK Core 함수에 모델을 노출해요. Harness는 에이전트 런타임을 HarnessAgent 에 노출해요.

harness를 사용한다고 해서 커스터마이징을 포기하는 것은 아니에요. HarnessAgent 를 사용하면 각 harness를 강력하게 만드는 런타임 동작을 보존하면서 자신만의 지시, skills, AI SDK tools, 권한 설정, sandbox 설정 훅, 어댑터별 설정을 제공할 수 있어요.

두 추상화는 분리되어 있지만 가능하면 호환 프리미티브를 사용해요. harness 출력은 AI SDK 스트림 및 응답 유형으로 투영되므로, AI SDK 모델 스트림을 소비하는 표면은 harness 스트림도 소비할 수 있어요. 예를 들어 HarnessAgent 스트림을 toUIMessageStream 에 전달하고 useChat 으로 렌더링할 수 있어요. API는 AI SDK 사용자에게 익숙하게 느껴지도록 설계됐지만, harness 런타임은 저수준 언어 모델과는 다른 개념을 가져요. 설정은 AI SDK 패턴에 맞는 곳에서는 그 패턴을 따르고, harness 런타임이 다른 동작을 하는 곳에서는 달라져요.

Harness 패키지는 **실험적**이에요. 이 초기 API가 더 다듬어지면서 릴리스 사이에 호환성이 깨지는 변경이 있을 수 있어요.

출처: 문서

본문

언제 Harness를 쓰나 (When to Use a Harness)

기존 에이전트 런타임이 작업을 주도하길 원할 때 harness를 사용하세요:

  • sandboxed 워크스페이스를 검사하고 수정할 수 있는 코딩 에이전트.
  • 자체 내장 tools와 권한 모델을 가진 에이전트 런타임.
  • 런타임이 대화 기록을 소유하는 다중 턴 세션.
  • tool 루프로 다시 만들기보다 네이티브 harness 동작을 보존해야 하는 워크플로.

모델 호출, tool 루프, 모델 설정, 구조화된 출력 또는 커스텀 에이전트 아키텍처를 직접 제어하길 원할 때는 프로바이더와 모델을 사용하세요.

핵심 개념 (Core Concepts)

Harness에는 네 가지 주요 요소가 있어요:

  • HarnessAgent: 애플리케이션 코드에서 사용하는 AI SDK 에이전트 구현.
  • Harness 어댑터: @ai-sdk/harness-claude-code 같은 런타임에 연결하는 패키지.
  • Sandbox 프로바이더: harness가 실행되는 격리된 파일시스템 및 프로세스 환경.
  • Session: harness 실행을 위한 라이브 대화 및 워크스페이스 상태.

호환 스트림 (Compatible Streams)

HarnessAgent.generate() 는 AI SDK GenerateTextResult 를 반환해요. HarnessAgent.stream() 은 AI SDK StreamTextResult 를 반환해요.

즉 다음 익숙한 필드를 소비할 수 있어요:

  • result.text
  • result.stream
  • result.steps
  • result.usage
  • result.responseMessages

Harness 특화 이벤트는 호환 스트림 파트로 변환돼요. 텍스트, 추론, tool 호출, tool 결과, 사용량, 종료 이유는 가능하면 동일한 AI SDK 형태를 사용해요. 워크스페이스 파일 변경과 압축처럼 일등석 AI SDK 파트가 없는 이벤트는 동적 프로바이더 실행 tool 파트로 표면화돼요.

세션이 중요하다 (Sessions Matter)

언어 모델 호출과 달리 harness 세션은 상태를 소유해요. 세션은 harness 런타임, sandbox, 작업 디렉터리, 네이티브 대화 기록, 보류 중인 승인을 담아요.

턴을 실행하기 전에 세션을 만드세요:

const session = await agent.createSession();

try {
  const result = await agent.generate({
    session,
    prompt: 'Inspect the repository and summarize the test setup.',
  });

  console.log(result.text);
} finally {
  await session.destroy();
}

서버 라우트의 경우 안정적인 sessionId 를 사용하고 session.detach() 또는 session.stop() 이 반환한 재개(resume) 상태를 지속하세요.

다음 단계 (Next Steps)

더 알아보기 (Learn more)

전체 사이트맵