Deep Agents

Model

모델 문자열 또는 초기화된 모델 인스턴스를 전달하세요.

const agent = createDeepAgent({ model: "gpt-5.4" });
const agent = createDeepAgent({
  model: new ChatAnthropic({
    model: "claude-sonnet-4-6",
    maxRetries: 10, // Increase for unreliable networks (default: 6)
    timeout: 120_000, // Increase timeout for slow connections
  }),
});

Tools

계획 수립, 파일 관리 및 하위 에이전트 생성에 필요한 내장 도구 외에도 사용자 지정 도구를 제공할 수 있습니다.

const internetSearch = tool(
  async ({
    query,
    maxResults = 5,
    topic = "general",
    includeRawContent = false,
  }: {
    query: string;
    maxResults?: number;
    topic?: "general" | "news" | "finance";
    includeRawContent?: boolean;
  }) => {
    const tavilySearch = new TavilySearch({
      maxResults,
      tavilyApiKey: process.env.TAVILY_API_KEY,
      includeRawContent,
      topic,
    });
    return await tavilySearch._call({ query });
  },
  {
    name: "internet_search",
    description: "Run a web search",
    schema: z.object({
      query: z.string().describe("The search query"),
      maxResults: z.number().optional().default(5),
      topic: z
        .enum(["general", "news", "finance"])
        .optional()
        .default("general"),
      includeRawContent: z.boolean().optional().default(false),
    }),
  },
);

const agent = createDeepAgent({
  tools: [internetSearch],
});

System Prompt

Deep Agents에는 기본 시스템 프롬프트가 내장되어 있습니다. 기본 시스템 프롬프트에는 내장 계획 도구, 파일 시스템 도구 및 하위 에이전트 사용에 대한 자세한 지침이 포함되어 있습니다. 미들웨어가 파일 시스템 도구와 같은 특수 도구를 추가하면 해당 도구가 시스템 프롬프트에 추가됩니다.

const researchInstructions =
  `You are an expert researcher. ` + `Your job is to conduct thorough research, and then ` + `write a polished report.`;

const agent = createDeepAgent({
  systemPrompt: researchInstructions,
});

Middlewares

기본적으로 Deep Agent는 다음과 같은 미들웨어에 접근할 수 있습니다.

  • TodoListMiddleware: 에이전트 작업 및 업무 구성을 위한 할 일 목록을 추적하고 관리합니다.
  • FilesystemMiddleware: 디렉터리 읽기, 쓰기 및 탐색과 같은 파일 시스템 작업을 처리합니다.
  • SubAgentMiddleware: 전문 에이전트에게 작업을 위임하기 위해 하위 에이전트를 생성하고 조정합니다.
  • SummarizationMiddleware: 대화가 길어질 경우 컨텍스트 제한을 준수하도록 메시지 기록을 요약합니다.
  • AnthropicPromptCachingMiddleware: Anthropic 모델을 사용할 때 중복 토큰 처리를 자동으로 줄입니다.
  • PatchToolCallsMiddleware: 도구 호출이 결과를 받기 전에 중단되거나 취소될 경우 메시지 기록을 자동으로 수정합니다.

메모리, 스킬 또는 휴먼 인 더 루프를 사용하는 경우 다음 미들웨어도 포함됩니다.

  • MemoryMiddleware: memory 인수가 제공되면 세션 간에 대화 컨텍스트를 유지하고 검색합니다.
  • SkillsMiddleware: skills 인수가 제공되면 사용자 지정 스킬을 활성화합니다. 제공됨
  • HumanInTheLoopMiddleware: interruptOn 인수가 제공될 때 지정된 지점에서 사람의 승인 또는 입력을 위해 일시 ​​중지합니다.

사전 구축된 미들웨어

LangChain은 재시도, 대체 기능, 개인 식별 정보(PII) 감지 등 다양한 기능을 추가할 수 있는 사전 구축된 미들웨어를 제공합니다. 자세한 내용은 사전 구축된 미들웨어를 참조하세요.

deepagents 패키지는 동일한 워크플로를 위한 createSummarizationMiddleware도 제공합니다. 자세한 내용은 요약을 참조하세요.

공급자별 미들웨어 특정 LLM 공급자에 최적화된 공급자별 미들웨어는 공식 통합커뮤니티 통합을 참조하세요.

custom middleware

let callCount = 0;

const logToolCallsMiddleware = createMiddleware({
  name: "LogToolCallsMiddleware",
  wrapToolCall: async (request, handler) => {
    // Intercept and log every tool call - demonstrates cross-cutting concern
    callCount += 1;
    const toolName = request.toolCall.name;

    console.log(`[Middleware] Tool call #${callCount}: ${toolName}`);
    console.log(`[Middleware] Arguments: ${JSON.stringify(request.toolCall.args)}`);

    // Execute the tool call
    const result = await handler(request);

    // Log the result
    console.log(`[Middleware] Tool call #${callCount} completed`);

    return result;
  },
});

Subagents

세부적인 작업을 분리하고 컨텍스트 과부하를 방지하려면 하위 에이전트를 사용

const researchSubagent: SubAgent = {
  name: "research-agent",
  description: "Used to research more in depth questions",
  systemPrompt: "You are a great researcher",
  tools: [internetSearch],
  model: "openai:gpt-5.2",  // Optional override, defaults to main agent model
};
const subagents = [researchSubagent];

const agent = createDeepAgent({
  model: "claude-sonnet-4-6",
  subagents,
});

Backends

  • StateBacnend: 랭그래프 상태에 저장되는 임시 파일 시스템 백엔드입니다. 이 파일 시스템은 단일 스레드에 대해서만 유지됩니다.
  • FileSystemBackend: 호스트에서 직접 셸 실행이 가능한 파일 시스템입니다. 파일 시스템 도구와 명령 실행 도구를 제공합니다.
  • LocalShellBackend: 로컬 머신의 파일 시스템입니다.
  • StoreBackend: 스레드 간에 유지되는 장기 저장소를 제공하는 파일 시스템입니다.
  • CompositeBackend: 파일 시스템에서 서로 다른 백엔드를 가리키도록 다양한 경로를 지정할 수 있는 유연한 백엔드입니다.
// By default we provide a StateBackend
const agent = createDeepAgent();

// Under the hood, it looks like
const agent2 = createDeepAgent({
  backend: new StateBackend(),
});

// filesystem backend
const agent3 = createDeepAgent({
  backend: new FilesystemBackend({ rootDir: ".", virtualMode: true }),
});

// localshell backend
const agent4 = createDeepAgent({
  backend: new LocalShellBackend({ workingDirectory: "." }),
});

// store backend
const agent5 = createDeepAgent({
  backend: new StoreBackend({ workingDirectory: "." }),
  store: new InMemoryStore(),
});

// composite backend
const store = new InMemoryStore();
const agent6 = createDeepAgent({
  backend: new CompositeBackend(
    new StateBackend(),
    {
      "/memories/": new StoreBackend(),
    }
  ),
  store,
});

Backend Sandboxes

샌드박스는 에이전트 코드를 자체 파일 시스템과 셸 명령 실행 도구를 갖춘 격리된 환경에서 실행하는 특수 백엔드입니다. 딥 에이전트가 로컬 머신을 변경하지 않고 파일을 작성하고, 종속성을 설치하고, 명령을 실행하도록 하려면 샌드박스 백엔드를 사용하십시오. 샌드박스는 딥 에이전트를 생성할 때 백엔드에 샌드박스 백엔드를 전달하여 구성합니다.

// Create and initialize the sandbox
const sandbox = await DenoSandbox.create({
  memoryMb: 1024,
  lifetime: "10m",
});

try {
  const agent = createDeepAgent({
    model: new ChatAnthropic({ model: "claude-opus-4-6" }),
    systemPrompt: "You are a JavaScript coding assistant with sandbox access.",
    backend: sandbox,
  });

  const result = await agent.invoke({
    messages: [
      {
        role: "user",
        content: "Create a simple HTTP server using Deno.serve and test it with curl",
      },
    ],
  });
} finally {
  await sandbox.close();
}

Human-in-the-loop

일부 도구 작업은 민감한 정보를 포함하므로 실행 전에 사람의 승인이 필요할 수 있습니다. 각 도구에 대한 승인 절차를 구성할 수 있습니다.

// Checkpointer is REQUIRED for human-in-the-loop
const checkpointer = new MemorySaver();

const agent = createDeepAgent({
  model: "claude-sonnet-4-6",
  tools: [deleteFile, readFile, sendEmail],
  interruptOn: {
    delete_file: true, // Default: approve, edit, reject
    read_file: false, // No interrupts needed
    send_email: { allowedDecisions: ["approve", "reject"] }, // No editing
  },
  checkpointer, // Required!
});

Skills

스킬을 사용하면 딥 에이전트에 새로운 기능과 전문 지식을 제공할 수 있습니다. 도구는 일반적으로 기본 파일 시스템 작업이나 계획과 같은 하위 수준 기능을 다루는 반면, 스킬에는 작업 완료 방법에 대한 자세한 지침, 참조 정보 및 템플릿과 같은 기타 자산이 포함될 수 있습니다. 이러한 파일은 에이전트가 현재 프롬프트에 스킬이 유용하다고 판단했을 때만 로드됩니다. 이러한 점진적 공개 방식을 통해 에이전트가 시작 시 고려해야 하는 토큰 및 컨텍스트의 양이 줄어듭니다.

const agent = await createDeepAgent({
  checkpointer,
  // IMPORTANT: deepagents skill source paths are virtual (POSIX) paths relative to the backend root.
  skills: ["/skills/"],
});

Memory

AGENTS.md 파일을 사용하여 딥 에이전트에 추가적인 컨텍스트를 제공할 수 있습니다. 딥 에이전트를 생성할 때 메모리 매개변수에 하나 이상의 파일 경로를 전달할 수 있습니다.

const agent = await createDeepAgent({
  memory: ["/AGENTS.md"],
  checkpointer: checkpointer,
});

Structured output

createDeepAgent() 호출 시 responseFormat 인수로 원하는 구조화된 출력 스키마를 전달할 수 있습니다. 모델이 구조화된 데이터를 생성하면, 해당 데이터는 캡처, 유효성 검사를 거쳐 에이전트 상태의 'structuredResponse' 키에 반환됩니다.

const weatherReportSchema = z.object({
  location: z.string().describe("The location for this weather report"),
  temperature: z.number().describe("Current temperature in Celsius"),
  condition: z.string().describe("Current weather condition (e.g., sunny, cloudy, rainy)"),
  humidity: z.number().describe("Humidity percentage"),
  windSpeed: z.number().describe("Wind speed in km/h"),
  forecast: z.string().describe("Brief forecast for the next 24 hours"),
});

const agent = await createDeepAgent({
  responseFormat: weatherReportSchema,
  tools: [internetSearch],
});

MCP

import { MultiServerMCPClient } from "@langchain/mcp-adapters";

const client = new MultiServerMCPClient({
  "Framelink MCP for Figma": {
    command: "npx",
    args: ["-y", "figma-developer-mcp", "--figma-api-key=", "--stdio"],
  },
});

const tools = await client.getTools();