하네스

하네스 어댑터는 샌드박스 실행을 구성하는 두 번째 축입니다. 어떤 코딩 에이전트를 실행할지 결정하고 해당 에이전트의 작업을 chat() 스트림 청크로 변환합니다. 프로바이더는 에이전트가 어디서 실행되는지 결정하고, 하네스는 무엇이 실행되는지 결정합니다. 둘 다 동일한 chat() + withSandbox() 연결 뒤에 있으므로 프로바이더나 workspace를 변경하지 않고 하네스를 교체할 수 있습니다.

모든 하네스 어댑터는 requires: [SandboxCapability]를 선언하므로 withSandbox(...)를 통해 샌드박스를 제공하지 않으면 chat()이 호출 위치에서 즉시 실패합니다.

기본 제공 하네스 어댑터

각 에이전트에는 모델별 메타데이터가 엄선된 전용 패키지가 있습니다. 어댑터를 chat({ adapter })에 전달하면 모든 프로바이더에서 실행할 수 있습니다.

하네스	패키지	어댑터	인증
Grok Build	`@tanstack/ai-grok-build`	`grokBuildText`	기본값은 `'api-key'` (`XAI_API_KEY`)입니다. `'host'`는 `grok login`을 사용합니다.
Claude Code	`@tanstack/ai-claude-code`	`claudeCodeText`	기본값은 `'api-key'` (`ANTHROPIC_API_KEY`)입니다. `'host'`는 `claude login`을 사용합니다.
Codex	`@tanstack/ai-codex`	`codexText`	기본값은 `'api-key'` (`CODEX_API_KEY`)입니다. `'host'`는 `codex login`을 사용합니다.
OpenCode	`@tanstack/ai-opencode`	`opencodeText`	프로세스 환경의 `OPENAI_API_KEY`를 사용합니다. `authMode` 플래그는 없습니다.
ACP-Compatible	`@tanstack/ai-acp`	`acpCompatible` / `acpCompatibleText`	기본값인 `'api-key'`는 `authMethodId`를 사용합니다. `'host'`는 ACP `authenticate`를 건너뜁니다.

프로바이더는 에이전트가 실행되는 위치이며 로그인 방식이 아닙니다. 기본 authMode는 'api-key'입니다. 머신에 이미 CLI 로그인이 있으면 'host'로 설정합니다. 하네스 인증을 참조하세요.

import { chat } from '@tanstack/ai'
import { grokBuildText } from '@tanstack/ai-grok-build'
import { withSandbox } from '@tanstack/ai-sandbox'
import { sandbox } from './sandbox'
import { messages } from './chat-context'

const stream = chat({
  adapter: grokBuildText('grok-build'),
  messages,
  middleware: [withSandbox(sandbox)],
})

하네스의 타입 지정 보고서

에이전트가 저장소를 검사한 후 타입이 지정된 객체를 받으려면 동일한 chat() 호출에 outputSchema를 전달합니다. 전용 어댑터와 acpCompatible는 이를 준수합니다. 하네스 에이전트를 참조하세요.

하네스 출력을 저널로 보낼 수 있습니다

grokBuildText, claudeCodeText, codexText는 에이전트의 표준 출력(stdout) 파이프를 계속 유지하는 대신 샌드박스 내부의 추가 전용 NDJSON 파일 (/tmp/tanstack-runs/<runId>.ndjson)로 리디렉션하고 이를 추적할 수 있습니다. 따라서 호스트가 끊겨도 에이전트에 신호를 보낼 수 없으며, 이후의 리더가 실행을 바이트 0부터 재생할 수 있습니다.

이는 영속 실행에서만 수행됩니다. 저널링은 선택 사항이며, withSandbox에 runs와 durability를 모두 전달해야 활성화됩니다(위 스니펫 참조). 일반 withSandbox(sandbox)는 저널을 기록하지 않고 이전과 동일하게 파이프로 스트리밍합니다. 두 옵션을 모두 전달하고 runId를 전달하세요. 저널 경로는 이 값에서 파생됩니다(호출자가 runId를 제공하지 않은 영속 실행은 재계산할 수 없는 ID를 만들지 않고 DurableRunIdRequiredError를 발생시킵니다).

import {
  chat,
  chatParamsFromRequest,
  memoryStream,
  toServerSentEventsResponse,
} from '@tanstack/ai'
import { codexText } from '@tanstack/ai-codex'
import { memoryPersistence } from '@tanstack/ai-persistence'
import { withSandbox } from '@tanstack/ai-sandbox'
import { sandbox } from './sandbox'

// Single-process stand-ins; ./takeover has the multi-replica wiring.
const persistence = memoryPersistence()
const { runs } = persistence.stores

export async function POST(request: Request) {
  const { messages, threadId, runId } = await chatParamsFromRequest(request)
  const adapter = memoryStream(request)
  const stream = chat({
    adapter: codexText('gpt-5.3-codex'),
    messages,
    threadId,
    runId, // makes the run's journal findable again
    // BOTH stores, or there is no journal: this is the whole opt-in.
    middleware: [withSandbox(sandbox, { runs, durability: { adapter } })],
  })
  return toServerSentEventsResponse(stream, { durability: { adapter } })
}

ID는 실행마다 고유해야 합니다. 저널은 추가되므로 같은 ID를 재사용하면 리더가 이전 실행의 종료 센티널에서 멈춥니다. 선택 사항을 활성화하지 않았을 때의 동작과 이미 전달된 로그에 대한 재생을 포함한 자세한 내용은 실행 저널에 있습니다.

opencodeText와 acpCompatible 하네스는 표준 출력(stdout)에서 NDJSON을 전혀 읽지 않으므로 실행이 영속적이어도 저널이 없습니다.

모든 ACP 에이전트 (`acpCompatible`)

많은 코딩 에이전트가 Agent Client Protocol (ACP)을 지원하며, pi, gemini --acp 및 수십 개의 다른 에이전트도 포함됩니다. 전용 패키지가 없는 에이전트에는 @tanstack/ai-acp의 acpCompatible가 openaiCompatible의 하네스 버전에 해당하는 어댑터를 즉시 구성합니다. 실행 방법을 한 번 구성한 후 기본 제공 어댑터처럼 모든 프로바이더에서 실행할 수 있습니다.

import { acpCompatible } from '@tanstack/ai-acp'

const pi = acpCompatible({
  name: 'pi',
  models: ['pi-fast', 'pi-pro'],
  command: ({ model, harnessCwd }) => `pi --acp -m ${model} --cwd ${harnessCwd}`,
  authMethodId: 'pi-api-key',
})

전체 구성(타입 지정 모델, 호출별 modelOptions, WebSocket 전송, 권한 및 프로토콜 지원 범위)은 ACP 호환 하네스 가이드를 참조하세요. 연결할 수 있는 에이전트는 공식 ACP 에이전트 목록 및 **ACP 레지스트리**를 참조하세요.

다음 단계

하네스 인증: 호스트 로그인 또는 API 키를 선택합니다. 샌드박스 유형이 이를 결정하지는 않습니다.
Provider: 하네스가 실행되는 위치입니다(로컬, Docker, Daytona, Vercel, Sprites).
실행 저널: 실행을 시작한 호스트가 없어져도 실행 출력이 유지되는 방식입니다.
인계 및 분리된 실행: 연결 해제 시 분리하고 연결 재개를 지원하기 위해 하네스 어댑터가 구현하는 세 가지 내보내기를 설명합니다.
도구: 앱 자체 도구를 샌드박스 내부 에이전트에 연결합니다.
이벤트 및 파일 훅: 에이전트의 편집과 활동을 UI로 스트리밍합니다.

기본 제공 하네스 어댑터​

하네스의 타입 지정 보고서​

하네스 출력을 저널로 보낼 수 있습니다​

모든 ACP 에이전트 (acpCompatible)​

다음 단계​

기본 제공 하네스 어댑터

하네스의 타입 지정 보고서

하네스 출력을 저널로 보낼 수 있습니다

모든 ACP 에이전트 (`acpCompatible`)

다음 단계