Grok Build

Grok Build 어댑터는 xAI의 Grok Build 코딩 에이전트를 채팅 백엔드로 실행합니다. HTTP 프로바이더 어댑터와 달리 이는 하니스 어댑터입니다. Grok Build는 자체 에이전트 루프를 실행하고, grok CLI를 샌드박스 내부에서 생성하여 셸 명령, 파일 편집, 검색과 같은 자체 도구를 실행합니다. 각 chat() 호출은 하나의 완전한 하니스 턴을 실행하며, 하니스의 도구 활동은 UI에서 렌더링할 수 있는 이미 해결된 도구 호출 이벤트로 스트리밍됩니다.

샌드박스가 필요합니다. grok-build는 requires: [SandboxCapability]를 선언하므로, withSandbox(...) 미들웨어로 샌드박스를 제공하지 않으면 chat()이 호출 지점에서 오류를 발생시킵니다. 샌드박스(노트북, Docker 컨테이너 또는 클라우드 VM)는 에이전트가 실행되는 파일 시스템 및 안전 경계입니다. 자세한 내용은 샌드박스 개요를 참고하세요.

설치

npm install @tanstack/ai-grok-build @tanstack/ai-sandbox

샌드박스 프로바이더(예: @tanstack/ai-sandbox-docker)와 샌드박스 이미지 내부에서 사용할 수 있는 grok CLI도 필요합니다.

인증

노트북에는 이미 grok login이 설정되어 있을 수 있습니다. CI 러너에는 XAI_API_KEY만 있을 수 있습니다. 두 환경 모두 같은 샌드박스 프로바이더를 사용할 수 있습니다. 기본 authMode는 'api-key'입니다. grok login을 사용하려면 'host'로 설정하세요. 하니스 인증을 참고하세요.

import { grokBuildText } from "@tanstack/ai-grok-build"

grokBuildText("composer-2.5")
grokBuildText("composer-2.5", { authMode: "host" })

'api-key' (기본값): XAI_API_KEY를 주입하고 이를 사용해 인증합니다.
'host': ACP authenticate를 건너뜁니다. grok login을 사용합니다. 해당 프로세스에는 XAI_API_KEY를 주입하지 않습니다.

두 모드는 모델을 약간 다른 id로 나열합니다. 어댑터가 짧은 별칭을 매핑합니다 (모델 참고).

기본 사용법

import { chat } from '@tanstack/ai'
import { grokBuildText } from '@tanstack/ai-grok-build'
import {
  createSecrets,
  defineSandbox,
  defineWorkspace,
  githubRepo,
  withSandbox,
} from '@tanstack/ai-sandbox'
import { dockerSandbox } from '@tanstack/ai-sandbox-docker'
import { messages, threadId } from './chat-context'

const sandbox = defineSandbox({
  id: 'grok-build-agent',
  provider: dockerSandbox({ image: 'node:22' }),
  workspace: defineWorkspace({
    source: githubRepo({ repo: 'owner/app' }),
    setup: ['corepack enable', 'pnpm install'],
    secrets: createSecrets({ XAI_API_KEY: process.env.XAI_API_KEY ?? '' }),
  }),
})

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

모델

Grok Build는 백엔드가 지원하는 모든 xAI 모델 id를 허용합니다. 알려진 id에는 자동 완성이 제공되지만 모든 문자열을 사용할 수 있습니다.

모델 id	설명
`grok-build`	짧은 별칭입니다. grok.com 브라우저 로그인 시 CLI가 이 이름으로 나열합니다.
`grok-build-0.1`	`XAI_API_KEY`로 인증할 때 CLI가 나열하는 정규화된 id입니다.
`composer-2.5`	Grok Build 하니스를 통해서도 실행할 수 있습니다.

이 중 하나를 grokBuildText(...)에 전달하세요. 어댑터가 grok-build를 CLI의 grok-build-0.1로 자동 확인하므로 두 인증 모드에서 같은 코드가 작동합니다.

구성

어댑터 구성(grokBuildText의 두 번째 인수):

옵션	설명
`cwd`	샌드박스 내부의 작업 디렉터리입니다. 기본값은 `/workspace`입니다.
`grokExecutable`	샌드박스 내부 `grok` 실행 파일의 경로/이름입니다. 기본값은 `grok`입니다.
`env`	샌드박스 내부 `grok` 프로세스에 전달할 추가 환경 변수입니다.
`emitDiff`	실행 후 작업 트리의 `git diff`와 함께 `file.changed` CUSTOM 이벤트를 내보냅니다. 기본값은 `true`입니다.
`protocol`	하니스 와이어 프로토콜입니다: `'acp'` 또는 `'streaming-json'`입니다. 기본값은 `'acp'`입니다. 프로토콜을 설정하지 않은 내구성 있는 샌드박스 실행에서는 저널링할 수 있도록 `'streaming-json'`을 사용합니다.
`authMode`	`'api-key'`(기본값)는 `XAI_API_KEY`를 사용합니다. `'host'`는 `grok login`을 사용합니다. 하니스 인증을 참고하세요.
`authMethodId`	명시적인 ACP 인증 방법입니다. `authMode`보다 우선합니다.
`extraArgs`	그대로 추가할 원시 CLI 플래그입니다(고급 기능).

호출별 재정의는 modelOptions를 통해 지정합니다.

`modelOptions`	설명
`sessionId`	기존 Grok Build 세션을 재개합니다(아래 참고).
`cwd`	호출별 하니스 작업 디렉터리 재정의입니다.
`maxTurns`	호출별 하니스 턴 수 제한입니다.
`protocol`	호출별 하니스 와이어 프로토콜 재정의입니다.
`authMode`	호출별 `'host'` 또는 `'api-key'`입니다. 기본값은 `'api-key'`입니다.
`authMethodId`	호출별 ACP 인증 방법입니다. `authMode`보다 우선합니다.

상태 저장 세션

Grok Build 세션은 상태를 저장합니다. 하니스는 턴 사이에 작업 컨텍스트(읽은 파일, 실행한 명령, 도달한 결론)를 유지합니다. 어댑터는 새로 실행할 때마다 세션 id를 grok-build.session-id라는 사용자 지정 스트림 이벤트로 노출하므로, 재개하려면 modelOptions.sessionId를 통해 다시 전달하세요. 재개할 때는 최신 사용자 메시지만 전송합니다. 하니스가 이전 컨텍스트를 이미 보유하고 있기 때문입니다.

import { chat, chatParamsFromRequest, toServerSentEventsResponse } from '@tanstack/ai'
import { grokBuildText } from '@tanstack/ai-grok-build'
import { withSandbox } from '@tanstack/ai-sandbox'
import { sandbox } from './sandbox'

export async function POST(request: Request) {
  const params = await chatParamsFromRequest(request)
  const sessionId =
    typeof params.forwardedProps.sessionId === 'string'
      ? params.forwardedProps.sessionId
      : undefined

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

  return toServerSentEventsResponse(stream)
}

도구

이 어댑터를 통해 두 종류의 도구가 전달됩니다.

내장 하니스 도구는 Grok Build 자체가 실행하며(셸, 파일 편집, 검색), 결과가 이미 첨부된 도구 호출 이벤트로 다시 스트리밍됩니다. 코드가 이를 실행하지는 않습니다.
TanStack 도구는 인증된 MCP 도구 프록시를 통해 하니스 내부로 연결됩니다. toolDefinition().server()로 정의하고 chat({ tools })에 전달하세요. 도구 호출 이벤트는 등록한 이름으로 돌아옵니다. 하니스는 샌드박스에서 실행되므로, 프로바이더 (로컬/Docker와 클라우드)에 따라 브리지가 호스트에 도달하는 방법은 샌드박스 도구를 참고하세요.

클라이언트 측 도구와 승인 게이트 도구는 지원되지 않습니다. 하니스는 실행 중인 프로세스 내부에서 도구를 실행하므로 HTTP 왕복 중에 일시 중지할 수 없습니다. 서버 execute()가 없거나 needsApproval로 표시된 도구는 즉시 실패합니다. 이러한 도구는 일반 프로바이더 어댑터로 실행하세요.

내구성 있는 실행

내구성 있는 샌드박스 실행(withSandbox에 runs와 durability를 전달하는 경우)은 에이전트 출력을 저널링하므로 이후 요청이 실행을 이어받을 수 있습니다. ACP는 저널링하지 않습니다. 내구성이 연결되어 있고 protocol을 설정하지 않으면 어댑터는 'streaming-json'을 사용합니다.

해당 호출에서 ACP를 사용하려는 경우에만 protocol: 'acp'로 설정하세요. 내구성이 연결된 새 ACP 실행은 경고를 기록합니다. ACP에 연결하면 DurableAttachNotSupportedError.

헤드리스 NDJSON 플래그

자동 승인을 사용하는 'streaming-json' 경로에서 어댑터는 --always-approve --no-plan --no-auto-update를 추가합니다. 이러한 플래그는 Plan Mode와 CLI 업데이트 확인이 헤드리스 실행을 차단하지 않도록 합니다.

구조화된 출력

chat()에 outputSchema를 전달하세요. Grok Build에는 네이티브 스키마 플래그가 없습니다. 어댑터는 프롬프트에 JSON Schema를 추가하고(ACP 및 streaming-json), 마지막 어시스턴트 텍스트를 파싱합니다. 도구 활동은 계속 스트리밍됩니다. 객체는 structured-output.complete로 도착합니다.

import { chat } from "@tanstack/ai"
import { grokBuildText } from "@tanstack/ai-grok-build"
import { defineSandbox, withSandbox } from "@tanstack/ai-sandbox"
import { dockerSandbox } from "@tanstack/ai-sandbox-docker"
import { z } from "zod"

const Report = z.object({
  summary: z.string(),
  filesChanged: z.array(z.string()),
})

const sandbox = defineSandbox({
  id: "repo-report",
  provider: dockerSandbox({ image: "node:22" }),
})

const report = await chat({
  adapter: grokBuildText("grok-build"),
  messages: [{ role: "user", content: "Review this repo." }],
  outputSchema: Report,
  middleware: [withSandbox(sandbox)],
})

report.summary

이 경로는 마지막 어시스턴트 메시지에서 JSON을 파싱합니다. 추출만 하는 작업이라면 @tanstack/ai-grok을 사용하세요.

클라이언트에서는 같은 스키마를 useChat에 전달하고 final을 읽으세요. partial은 끝날 때까지 비어 있습니다.

import { fetchServerSentEvents, useChat } from "@tanstack/ai-react"
import { z } from "zod"

const Report = z.object({
  summary: z.string(),
  filesChanged: z.array(z.string()),
})

function ReportView() {
  const { final, isLoading } = useChat({
    connection: fetchServerSentEvents("/api/repo-report"),
    outputSchema: Report,
  })

  if (isLoading) return <p>The agent is inspecting the repo.</p>
  if (!final) return null
  return <p>{final.summary}</p>
}

클라이언트를 포함한 전체 안내: 하니스 에이전트.

제한사항

샌드박스가 필요합니다. 항상 withSandbox(...) 아래에서 실행하세요. 샌드박스 개요를 참고하세요.
서버 전용(Node)입니다. 하니스는 샌드박스에서 grok CLI를 생성합니다.
하니스가 에이전트 루프를 소유합니다. TanStack의 에이전트 루프 전략과 반복별 미들웨어는 하니스 턴 내부에 적용되지 않습니다.
샘플링 제어가 없습니다. 여기에는 temperature 방식의 옵션이 존재하지 않습니다.
콜드 스타트가 있습니다. 각 호출은 전체 하니스 턴을 실행하므로 HTTP 어댑터보다 첫 토큰 지연 시간이 더 길 수 있습니다.

설치​

인증​

기본 사용법​

모델​

구성​

상태 저장 세션​

도구​

내구성 있는 실행​

헤드리스 NDJSON 플래그​

구조화된 출력​

제한사항​

설치

인증