퀵스타트

퀵스타트 (Quickstart)

몇 분 만에 첫 deep agent를 만들어 보세요.

이 가이드는 파일 시스템 도구와 서브에이전트 기능을 갖춘 첫 deep agent를 만드는 과정을 안내합니다. 리서치를 수행하고 보고서를 작성하는 리서치 에이전트를 만들게 됩니다.

<Prompt description="Deep Agents 리서치 퀵스타트 만들기" icon="sparkles" actions={["copy"]}> 이 작업 디렉터리에 Deep Agents 퀵스타트를 따라 리서치 에이전트를 만드세요.

Step 1: 가이드 읽기

이 프로젝트가 Python을 쓰는지 TypeScript/JavaScript를 쓰는지 판단하세요. 일치하는 페이지를 가져와 따르세요. 패키지 이름, 모델 문자열, 검색 도구 설정, 그리고 코드의 진실의 원천으로 취급하세요:

Step 2: 의존성 설치

이 프로젝트에서 이미 사용 중인 패키지 매니저로 deepagents(그리고 TypeScript에서는 langchain / @langchain/core)를 설치하세요. 사용자가 Google, OpenAI, Anthropic 기본 제공 프로바이더 검색 도구를 사용하지 않는 경우에만 Tavily를 추가하세요.

Step 3: 모델 자격 증명 구성

지원되는 프로바이더 API 키(예: GOOGLE_API_KEY, OPENAI_API_KEY, 또는 ANTHROPIC_API_KEY)가 있는지 확인하세요. 설정된 것이 없으면 사용자에게 어떤 프로바이더를 쓸지 물어보고, 키를 만들어 셸이나 .env 파일에 설정하는 동안 멈춰 기다리세요. API 키를 지어내거나 하드코딩하거나 커밋하지 마세요. Tavily가 필요하면 같은 방식으로 TAVILY_API_KEY를 설정하라고 요청하세요.

Step 4: 리서치 에이전트 구현

퀵스타트 단계를 순서대로 따르세요:

  1. 인터넷 검색 도구를 만드세요(선택한 모델이 지원하면 프로바이더 기본 제공 검색 도구를 우선하고, 그렇지 않으면 Tavily를 사용하세요).
  2. 검색 도구, 가이드의 provider:model 문자열(또는 초기화된 모델), 그리고 페이지에 나온 리서치 시스템 프롬프트와 함께 create_deep_agent를 호출하세요.
  3. 선택적으로 사용자가 직접 LANGSMITH_TRACING=true와 LANGSMITH_API_KEY를 설정하게 해 LangSmith 추적을 활성화하세요.
  4. 가이드의 샘플 리서치 질의로 에이전트를 실행하고 최종 응답을 출력하세요.

규칙

  • 이 퀵스타트 범위에 머무르세요. Managed Deep Agents 배포, 평가, 또는 무관한 프레임워크를 추가하지 마세요.
  • 가능하면 프로바이더 기본 제공 웹 검색을 우선하세요. Tavily는 필요할 때만 사용하세요.
  • 비밀, 프로바이더 선택, 또는 프로젝트 관례가 불분명하면 추측 대신 물어보세요.
**AI 코딩 어시스턴트를 쓰고 있나요?**

  • LangChain Docs MCP 서버를 설치해 에이전트에게 최신 LangChain 문서와 예시에 접근할 수 있게 하세요.

    <Prompt description="LangChain docs MCP 서버 연결" icon="plug" actions={["copy"]}> 두 LangChain 문서 MCP 서버를 내 코딩 에이전트에 연결해서 최신 LangChain, LangGraph, LangSmith 문서와 API 레퍼런스를 조회할 수 있게 해줘.

    추가할 서버:

* `docs-langchain`: [https://docs.langchain.com/mcp](https://docs.langchain.com/mcp)
* `reference-langchain`: [https://reference.langchain.com/mcp](https://reference.langchain.com/mcp)

내가 쓰는 에이전트나 편집기를 판단하세요(Claude Code, Cursor, Codex CLI, Claude Desktop, Deep Agents Code, VS Code, Antigravity, 또는 다른 MCP 호환 클라이언트). [https://docs.langchain.com/use-these-docs.md](https://docs.langchain.com/use-these-docs.md)의 일치하는 설정을 사용하세요:

* Claude Code: 각 서버에 `claude mcp add --transport http`(기본적으로 프로젝트 범위; 전역 접근을 요청할 때만 `--scope user` 사용).
* Codex CLI: 각 서버 URL로 `codex mcp add`.
* Cursor, Deep Agents Code, VS Code, 또는 Antigravity: 그 페이지에 내 클라이언트용으로 나온 필드 이름을 사용해 두 항목을 MCP 설정 JSON에 병합.
* Claude Desktop: Settings > Connectors 아래에 두 URL을 모두 추가.

대체 MCP URL을 지어내지 마세요. 구성한 뒤 두 서버가 모두 나열되고 접근 가능한지 확인하세요.

  • LangChain Skills을 설치해 LangChain 생태계 작업에서 에이전트 성능을 높이세요.

    <Prompt description="LangChain Skills 설치" icon="puzzle" actions={["copy"]}> 내 코딩 에이전트에 LangChain Skills를 설치해서 LangChain, LangGraph, Deep Agents 작업을 더 잘 수행하게 해줘.

    [https://github.com/langchain-ai/langchain-skills](https://github.com/langchain-ai/langchain-skills)의 Agent Skills 설치 프로그램을 사용하세요:

```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
npx skills add langchain-ai/langchain-skills --skill '*' --yes
```

대신 전역 설치를 요청하면 다음을 사용하세요:

```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
npx skills add langchain-ai/langchain-skills --skill '*' --yes --global
```

내가 쓰는 에이전트나 편집기를 판단하세요. Claude Code를 쓰면서 플러그인 경로를 선호하면 그 저장소 README의 마켓플레이스 설치를 따르세요(`/plugin marketplace add` 후 `/plugin install`). 대체 스킬 패키지 이름이나 설치 URL을 지어내지 마세요. 설치한 뒤 스킬이 에이전트에 사용 가능한지 확인하세요.

사전 요구 사항 (Prerequisites)

시작하기 전에 모델 프로바이더의 API 키(예: Gemini, Anthropic, OpenAI)가 있는지 확인하세요.

Deep Agents에는 [도구 호출](/oss/javascript/langchain/models#tool-calling)을 지원하는 모델이 필요합니다. 모델 구성 방법은 [customization](/oss/javascript/deepagents/customization#model)을 참조하세요.

Step 1: 의존성 설치

```bash npm theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} npm install deepagents langchain @langchain/core ``` 
yarn add deepagents langchain @langchain/core

pnpm add deepagents langchain @langchain/core
Google, OpenAI, Anthropic은 모두 기본 제공 웹 검색 도구를 제공합니다. 추가 패키지나 API 키가 필요 없습니다. 다른 프로바이더를 쓰거나 검색에 [Tavily](https://tavily.com/)를 선호한다면 Tavily 패키지도 설치하세요: 
npm install @langchain/tavily

Step 2: API 키 설정

```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} export GOOGLE_API_KEY="your-api-key" ``` ```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} export OPENAI_API_KEY="your-api-key" ``` ```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} export ANTHROPIC_API_KEY="your-api-key" ``` ```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} export OPENROUTER_API_KEY="your-api-key" export TAVILY_API_KEY="your-tavily-api-key" ``` ```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} export FIREWORKS_API_KEY="your-api-key" export TAVILY_API_KEY="your-tavily-api-key" ``` ```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} export BASETEN_API_KEY="your-api-key" export TAVILY_API_KEY="your-tavily-api-key" ``` ```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} # Local: Ollama must be running on your machine # Cloud: Set your Ollama API key for hosted inference export OLLAMA_API_KEY="your-api-key" export TAVILY_API_KEY="your-tavily-api-key" ``` ```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} # Set the API key for your provider export _API_KEY="your-api-key" export TAVILY_API_KEY="your-tavily-api-key" ``` 
Deep Agents는 모든 [LangChain 채팅 모델](/oss/javascript/deepagents/models#supported-models)과 함께 작동합니다. 프로바이더의 API 키를 설정하세요.
**LangSmith Gateway 사용**

LangSmith Gateway는 대부분의 주요 프로바이더를 LangSmith를 통해 라우팅합니다. 자체 프로바이더 키를 가져오거나, Gateway Credits을 사용해 프로바이더 키 없이 모델에 접근할 수 있습니다.

Step 3: 검색 도구 만들기

Google, OpenAI, Anthropic은 서버 측에서 실행되는 기본 제공 웹 검색 도구를 제공합니다. 추가 패키지나 API 키가 필요 없습니다. 프로바이더 도구 딕셔너리를 create_deep_agent에 직접 전달하세요.

```ts Google theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} import { createDeepAgent } from "deepagents"; 
  // Google's built-in search — no extra install or API key needed
  const internetSearch = { google_search: {} };
  ```

  ```ts OpenAI theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  import { createDeepAgent } from "deepagents";

  // OpenAI's built-in web search — no extra install or API key needed
  const internetSearch = { type: "web_search_preview" };
  ```

  ```ts Anthropic theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  import { createDeepAgent } from "deepagents";

  // Anthropic's built-in web search — no extra install or API key needed
  const internetSearch = { type: "web_search_20250305", name: "web_search" };
  ```
</CodeGroup>
```ts theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} import { tool } from "langchain"; import { TavilySearch } from "@langchain/tavily"; import { z } from "zod"; 
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: proces...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)
        .describe("Maximum number of results to return"),
      topic: z
        .enum(["general", "news", "finance"])
        .optional()
        .default("general")
        .describe("Search topic category"),
      includeRawContent: z
        .boolean()
        .optional()
        .default(false)
        .describe("Whether to include raw content"),
    }),
  },
);
```

Step 4: deep agent 만들기

검색 도구와 모델을 create_deep_agent에 전달하세요. provider:model 형식의 model 문자열이나 초기화된 모델 인스턴스를 전달하세요. 모든 프로바이더는 지원 모델을, 테스트된 권장 사항은 제안 모델을 참조하세요.

```ts Google theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} import { createDeepAgent } from "deepagents";

// System prompt to steer the agent to be an expert researcher const researchInstructions = `You are an expert researcher. Your job is to conduct thorough research and then write a polished report.

You have access to an internet search tool as your primary means of gathering information.

`internet_search`

Use this to run an internet search for a given query. You can specify the max number of results to return, the topic, and whether raw content should be included. `;

const agent = createDeepAgent({ model: "google-genai:gemini-3.6-flash", tools: [internetSearch], systemPrompt: researchInstructions, });


```ts OpenAI theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
import { createDeepAgent } from "deepagents";

// System prompt to steer the agent to be an expert researcher
const researchInstructions = `You are an expert researcher. Your job is to conduct thorough research and then write a polished report.

You have access to an internet search tool as your primary means of gathering information.

## \`internet_search\`

Use this to run an internet search for a given query. You can specify the max number of results to return, the topic, and whether raw content should be included.
`;

const agent = createDeepAgent({
  model: "openai:gpt-5.5",
  tools: [internetSearch],
  systemPrompt: researchInstructions,
});

import { createDeepAgent } from "deepagents";

// System prompt to steer the agent to be an expert researcher
const researchInstructions = `You are an expert researcher. Your job is to conduct thorough research and then write a polished report.

You have access to an internet search tool as your primary means of gathering information.

## \`internet_search\`

Use this to run an internet search for a given query. You can specify the max number of results to return, the topic, and whether raw content should be included.
`;

const agent = createDeepAgent({
  model: "anthropic:claude-sonnet-5",
  tools: [internetSearch],
  systemPrompt: researchInstructions,
});

import { createDeepAgent } from "deepagents";

// System prompt to steer the agent to be an expert researcher
const researchInstructions = `You are an expert researcher. Your job is to conduct thorough research and then write a polished report.

You have access to an internet search tool as your primary means of gathering information.

## \`internet_search\`

Use this to run an internet search for a given query. You can specify the max number of results to return, the topic, and whether raw content should be included.
`;

const agent = createDeepAgent({
  model: "openrouter:z-ai/glm-5.2",
  tools: [internetSearch],
  systemPrompt: researchInstructions,
});

import { createDeepAgent } from "deepagents";

// System prompt to steer the agent to be an expert researcher
const researchInstructions = `You are an expert researcher. Your job is to conduct thorough research and then write a polished report.

You have access to an internet search tool as your primary means of gathering information.

## \`internet_search\`

Use this to run an internet search for a given query. You can specify the max number of results to return, the topic, and whether raw content should be included.
`;

const agent = createDeepAgent({
  model: "fireworks:accounts/fireworks/models/glm-5p2",
  tools: [internetSearch],
  systemPrompt: researchInstructions,
});

import { createDeepAgent } from "deepagents";

// System prompt to steer the agent to be an expert researcher
const researchInstructions = `You are an expert researcher. Your job is to conduct thorough research and then write a polished report.

You have access to an internet search tool as your primary means of gathering information.

## \`internet_search\`

Use this to run an internet search for a given query. You can specify the max number of results to return, the topic, and whether raw content should be included.
`;

const agent = createDeepAgent({
  model: "baseten:zai-org/GLM-5.2",
  tools: [internetSearch],
  systemPrompt: researchInstructions,
});

import { createDeepAgent } from "deepagents";

// System prompt to steer the agent to be an expert researcher
const researchInstructions = `You are an expert researcher. Your job is to conduct thorough research and then write a polished report.

You have access to an internet search tool as your primary means of gathering information.

## \`internet_search\`

Use this to run an internet search for a given query. You can specify the max number of results to return, the topic, and whether raw content should be included.
`;

const agent = createDeepAgent({
  model: "ollama:north-mini-code-1.0",
  tools: [internetSearch],
  systemPrompt: researchInstructions,
});

Step 5: LangSmith 추적 설정

LangSmith는 에이전트 실행에 대한 가시성을 제공해서 도구 호출, 서브에이전트 위임, LLM 응답을 볼 수 있게 해줍니다.

smith.langchain.com에서 가입하고 API 키를 만든 뒤 다음 환경 변수를 설정하세요:

export LANGSMITH_TRACING=true
export LANGSMITH_API_KEY="your-langsmith-api-key"

Step 6: 에이전트 실행

const result = await agent.invoke({
  messages: [{ role: "user", content: "What is langgraph?" }],
});

// Print the agent's response
console.log(result.messages[result.messages.length - 1].content);

어떻게 작동하나요? (How does it work?)

deep agent는 자동으로:

  1. 리서치를 수행하면서 internet_search 도구를 호출해 정보를 수집합니다.
  2. 컨텍스트를 관리하면서 파일 시스템 도구(write_file, read_file)를 사용해 큰 검색 결과를 오프로드합니다.
  3. 필요에 따라 서브에이전트를 생성해서 복잡한 하위 작업을 특화된 서브에이전트에 위임합니다.
  4. 보고서를 종합해서 발견한 내용을 일관된 응답으로 정리합니다.

write_todos로 구조화된 작업 계획을 추가하려면 TodoListMiddleware로 옵트인하세요. 작업 계획을 참조하세요.

예시 (Examples)

Deep Agents로 만들 수 있는 에이전트, 패턴, 애플리케이션은 Examples를 참조하세요.

스트리밍 (Streaming)

Deep Agents에는 LangGraph를 사용한 에이전트 실행의 실시간 업데이트를 위한 내장 스트리밍이 있습니다. 이를 통해 출력을 점진적으로 관찰하고 에이전트와 서브에이전트 작업(도구 호출, 도구 결과, LLM 응답 등)을 검토하고 디버깅할 수 있습니다.

다음 단계 (Next steps)

이제 첫 deep agent를 만들었으니:

  • 에이전트 커스터마이즈하기: 커스텀 시스템 프롬프트, 도구, 서브에이전트를 포함한 커스터마이즈 옵션을 배워보세요.
  • 장기 메모리 추가하기: 대화를 넘어 지속되는 영구 메모리를 활성화하세요.
  • 프로덕션에 배포하기: Managed Deep Agents를 사용해 LangSmith에서 deep agent를 만들고, 실행하고, 운영하세요.
  • 테스트하고 평가하기: LangSmith 평가를 사용해 자동 테스트를 실행하고 데이터셋 대비 에이전트 성능을 측정하세요.

더 알아보기