Deep Agents Harness

Deep Agents harness 어댑터는 HarnessAgent 를 LangGraph 기반 에이전트 런타임인 Deep Agents 에 연결해요. 이 어댑터는 sandbox 안에서 deepagents 패키지를 구동하고 streamEvents 출력을 sandbox에 노출된 WebSocket을 통해 호스트로 다시 스트리밍하는 Node 브리지를 실행해요.

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

출처: 문서

본문

설정 (Setup)

어댑터는 첫 번째 세션이 시작될 때 pnpm 을 통해 sandbox 안에서 브리지의 Node 의존성(deepagents 패키지와 LangChain)을 부트스트랩해요.

Import

import { deepAgents, createDeepAgents } from '@ai-sdk/harness-deepagents';

deepAgents 는 기본 설정을 가진 createDeepAgents() 와 동일해요.

기본 사용법

import { HarnessAgent } from '@ai-sdk/harness/agent';
import { deepAgents } from '@ai-sdk/harness-deepagents';
import { createVercelNetworkSandboxSession } from '@ai-sdk/sandbox-vercel';

const agent = new HarnessAgent({
  harness: deepAgents,
  model: 'anthropic/claude-sonnet-4-6',
});

const sandboxSession = await createVercelNetworkSandboxSession({
  runtime: 'node24',
  ports: [4000],
  template: await agent.getSandboxTemplate(),
});
const session = await agent.createSession({ sandboxSession });

let exitCode = 0;
try {
  const result = await agent.stream({
    session,
    prompt: 'Analyze this codebase and suggest improvements.',
  });

  for await (const part of result.stream) {
    if (part.type === 'text-delta') {
      process.stdout.write(part.text);
    }
  }
} catch (err) {
  exitCode = 1;
  console.error(err);
} finally {
  await session.destroy();
  await sandboxSession.destroy();
  process.exit(exitCode);
}

이 에이전트를 사용하려면 환경 변수에 Vercel Sandbox용 VERCEL_OIDC_TOKEN 과, 모델 프로바이더용으로 인증 섹션에 나열된 변수 중 하나가 포함되어야 해요.

어댑터 설정

createDeepAgents() 를 사용해 런타임을 설정하세요:

const harness = createDeepAgents({ recursionLimit: 100 });

설정:

auth: 인증 모드(auto, anthropic, ai-gateway) 또는 격리된 인증 환경.
credentialForwarding: harness 어댑터가 자격 증명을 sandbox 프로세스로 전달하기 직전에 각 자격 증명을 사용자 정의하는 선택적 동기/비동기 콜백. 전달될 자격 증명 값(실제 자격 증명 또는 마스킹된 값)과 이를 노출하는 데 사용되는 환경 변수 이름을 받아요. 이 콜백은 sandbox 프로세스로 전달되는 값만 제어해요. harness 어댑터가 호스트 프로세스에서 발견/읽기/접근할 수 있는 자격 증명을 제한하지는 않아요.
mcpServers: 서버 이름 키로 된 MCP 서버 정의.
port: 브리지 포트 오버라이드.
recursionLimit: 턴당 최대 LangGraph super-step 수. 생략하면 Deep Agents 기본값이 적용돼요.
startupTimeoutMs: 브리지가 시작될 때까지 기다리는 최대 시간.
reconnect: 설정된 브리지 WebSocket 연결이 끊긴 후 재연결 타이밍. maxElapsedMs 는 연결 설정과 백오프 지연을 포함한 총 재시도 창을 제어하며 기본값은 30초. initialDelayMs 는 기본 50밀리초, maxDelayMs 는 기본 2초. 이 재시도는 지수 백오프를 사용하며 startupTimeoutMs 와는 별개예요. sandbox, 브리지 프로세스, 또는 브리지 엔드포인트가 영구적으로 사용 불가하면 복구할 수 없어요.
mintBridgeToken: sandbox ID를 받아 브리지 인증 토큰을 반환하는 동기 함수. 기본적으로 어댑터는 무작위 32바이트 토큰을 생성해요. 커스텀 구현은 적절히 비밀인 토큰을 반환해야 해요.

구조화된 출력 (Structured Output)

Deep Agents는 스키마 기반 HarnessAgent 구조화된 출력 을 지원해요. 어댑터는 턴마다 LangChain tool 전략을 적용하고 그래프의 검증된 structuredResponse 를 JSON 텍스트로 반환해요.

인증 (Authentication)

Deep Agents는 항상 Anthropic 클라이언트를 구동해요. Anthropic이 아닌 모델은 AI Gateway의 Anthropic 호환 엔드포인트를 통해 도달하며, 이는 tool 호출을 포함해 어떤 모델(Gemini, OpenAI 등)로든 변환해요.

auth 설정은 호스트 환경에서 자격 증명을 어떻게 해석하는지 선택해요:

auto (기본값): 사용 가능하면 AI Gateway 자격 증명을 사용하고, 그다음 Anthropic 자격 증명으로 폴백.
anthropic: Anthropic 자격 증명 사용.
ai-gateway: AI Gateway 자격 증명 사용.

sandbox가 덧셈 요청 변환(additive request transformations)을 지원하면 브리지는 자리표시자를 받고 어댑터는 일치하는 아웃바운드 요청에 자격 증명을 주입해요. 그 기능이 없는 sandbox는 직접 자격 증명 전달을 유지해요.

지원되는 환경 변수:

AI_GATEWAY_API_KEY
VERCEL_OIDC_TOKEN
AI_GATEWAY_BASE_URL
ANTHROPIC_API_KEY
ANTHROPIC_AUTH_TOKEN
ANTHROPIC_BASE_URL

Anthropic이 아닌 모델을 실행하려면 ai-gateway 를 선택하세요:

const harness = createDeepAgents({ auth: 'ai-gateway' });
const agent = new HarnessAgent({
  harness,
  model: 'google/gemini-2.5-flash',
  sandbox,
});

process.env 를 읽지 않고 프로그래밍 방식으로 해석된 자격 증명을 사용하려면 인증 환경을 전달하세요:

const harness = createDeepAgents({
  auth: { ANTHROPIC_API_KEY: await resolveAnthropicToken() },
});

제공된 레코드는 인증 발견을 위해 호스트 환경을 대체해요. 인식된 인증 변수만 전달돼요.

Sandbox

Deep Agents는 노출된 포트가 하나 이상 있는 네트워크 sandbox를 필요로 해요. 예: @ai-sdk/sandbox-vercel:

const sandboxSession = await createVercelNetworkSandboxSession({
  runtime: 'node24',
  ports: [4000],
  template: await agent.getSandboxTemplate(),
});

Skills

세션에 전달된 Skills는 sandbox의 $HOME/.agents/skills/ 아래에 네이티브 Deep Agents skill 폴더로 구체화돼요(작업 디렉터리 밖이므로 클론된 코드와 충돌하지 않음). 그리고 Deep Agents의 skills 옵션으로 로드되므로 에이전트가 온디맨드로 로드하고 skill 파일 참조가 해석돼요. <workDir>/.agents/skills/ 아래에 이미 있는 Skills(클론된 저장소 등)도 발견돼요.

내장 Tool (Built-in Tools)

어댑터는 agent.tools 를 통해 다음 Deep Agents 내장 기능을 노출해요:

read
write
edit
bash
grep
glob
ls
task
write_todos

알려진 제한 사항

중지된 세션의 대화 재개는 지원되지 않아요 — session.stop() 후 Deep Agents의 인메모리 대화 상태(LangGraph MemorySaver)는 사라져요. sandbox 워크스페이스만 스냅샷을 통해 지속돼요. 크로스 프로세스 핸드오프에는 session.detach() 를, 라이브 브리지를 계속 실행하면서 턴 연속에는 session.suspendTurn() 을 사용하세요.
수동 압축(Manual compaction)은 지원되지 않아요.

더 알아보기 (Learn more)

전체 사이트맵

Deep Agents Harness