에이전트가 저장하고 포크하도록 하기

에이전트가 버전을 표시하거나 새로운 방향을 열도록 할 수 있습니다. 라우트는 이미 threadId와 runId를 알고 있습니다. createSnapshotTools는 이러한 값을 chat()에 펼쳐 넣는 호스트 도구로 변환합니다.

모델은 이 스레드의 레이블이나 체크포인트 ID를 전달할 수 있습니다. 스레드 ID는 전달할 수 없습니다. 팩토리가 새 스레드 ID를 매번 생성합니다.

import { chat } from '@tanstack/ai'
import { grokBuildText } from '@tanstack/ai-grok-build'
import { withPersistence } from '@tanstack/ai-persistence'
import { createSnapshotTools, withSandbox } from '@tanstack/ai-sandbox'
import { instances, sandbox, snapshots } from './sandbox-server'

export function POST(threadId: string, runId: string) {
  return chat({
    threadId,
    runId,
    adapter: grokBuildText('composer-2.5'),
    messages: [{ role: 'user', content: 'Save this, then try a dark theme.' }],
    tools: [
      ...createSnapshotTools(snapshots, {
        threadId,
        runId,
        createThreadId: () => crypto.randomUUID(),
        onForked({ destinationThreadId }) {
          void destinationThreadId
        },
      }),
    ],
    middleware: [
      withPersistence(snapshots.persistence),
      withSandbox(sandbox, { instances, snapshots }),
    ],
  })
}

도구는 서버에서 실행됩니다. 샌드박스 채팅에서는 호스트로 다시 브리지됩니다. 도구를 참조하십시오.

각 도구의 기능

save_sandbox_snapshot: 연결된 스레드의 현재 샌드박스를 저장합니다. 모델은 label만 전달합니다.
fork_sandbox_snapshot: 체크포인트 하나를 새로운 빈 스레드로 복사합니다. 모델은 checkpointId를 전달할 수 있습니다. 해당 ID를 생략하면 도구가 최신 체크포인트를 복사합니다. createThreadId()가 대상 스레드 ID를 설정합니다.
read_sandbox_snapshot_artifact: 이 스레드의 체크포인트에 대한 아티팩트 메타데이터를 반환합니다. 파일 바이트는 반환하지 않습니다. 바이트는 동결된 파일 보내기에서 제공합니다.

onForked는 포크가 성공한 후 실행됩니다. 새 브랜치가 즉시 작동하도록 하려면 해당 콜백에서 destinationThreadId로 chat()을 시작합니다.

저장 및 포크 실행 시점

save_sandbox_snapshot은 이 스레드의 기록기 리스를 가져옵니다. 이 chat()이 이미 portable snapshots를 통해 해당 리스를 보유하고 있으면 저장이 SANDBOX_SNAPSHOT_WRITER_CONFLICT와 함께 실패합니다. 플래너 스레드에서 저장하거나 이 실행이 끝난 후 저장하십시오.

fork_sandbox_snapshot은 새 스레드의 기록기 리스를 가져옵니다. 이 실행 중에도 포크가 성공할 수 있습니다. 저장된 체크포인트를 복사하며, 에이전트가 아직 작성 중인 파일은 복사하지 않습니다.

snapshots 객체를 생성하려면 다시 로드한 후에도 파일 유지를 참조하십시오. 직접 호출하는 라우트는 이름이 지정된 버전 저장 및 버전에서 브랜치 생성을 참조하십시오.

각 도구의 기능​

저장 및 포크 실행 시점​

각 도구의 기능

저장 및 포크 실행 시점