> Discover all available pages from the documentation index: https://mastra.zisheng.pro/ko/llms.txt

# 웹 검색이 가능한 Agent 구축

웹 검색 Agent를 구축할 때 고려해야 할 두 가지 주요 전략이 있습니다.

1. **LLM의 기본 검색 Tool**: 특정 언어 Model은 즉시 사용 가능한 통합 웹 검색 기능을 제공합니다.
2. **맞춤 검색 Tool 구현**: 쿼리를 처리하고 결과를 검색하기 위해 검색 공급자의 API와 자체 통합을 개발합니다.

## 전제조건

- Node.js`v22.13.0` or later installed
- 지원되는 API 키[Model Provider](https://mastra.zisheng.pro/ko/models)
- 기존 Mastra 프로젝트(다음을 따르세요.[installation guide](https://mastra.zisheng.pro/ko/guides/getting-started/quickstart) to set up a new project)

## 기본 검색 Tool 사용

일부 LLM Provider에는 추가 API 통합 없이 직접 사용할 수 있는 웹 검색 기능이 내장되어 있습니다. OpenAI와 Google의 Model은 모두 생성 중에 Model이 호출할 수 있는 기본 검색 Tool을 제공합니다.

1. 종속성 설치

   **OpenAI**:

   **npm**:

   ```bash
   npm install @ai-sdk/openai
   ```

   **pnpm**:

   ```bash
   pnpm add @ai-sdk/openai
   ```

   **Yarn**:

   ```bash
   yarn add @ai-sdk/openai
   ```

   **Bun**:

   ```bash
   bun add @ai-sdk/openai
   ```

   **Gemini**:

   ```bash
   npm install @ai-sdk/openai
   ```

   **Tab 3**:

   ```bash
   pnpm add @ai-sdk/openai
   ```

   **Tab 4**:

   ```bash
   yarn add @ai-sdk/openai
   ```

   **Tab 5**:

   ```bash
   bun add @ai-sdk/openai
   ```

   **Tab 6**:

   **npm**:

   ```bash
   npm install @ai-sdk/google
   ```

   **pnpm**:

   ```bash
   pnpm add @ai-sdk/google
   ```

   **Yarn**:

   ```bash
   yarn add @ai-sdk/google
   ```

   **Bun**:

   ```bash
   bun add @ai-sdk/google
   ```

   **Tab 7**:

   ```bash
   npm install @ai-sdk/google
   ```

   **Tab 8**:

   ```bash
   pnpm add @ai-sdk/google
   ```

   **Tab 9**:

   ```bash
   yarn add @ai-sdk/google
   ```

   **Tab 10**:

   ```bash
   bun add @ai-sdk/google
   ```

2. 새 파일 만들기`src/mastra/agents/searchAgent.ts` and define your agent:

   **OpenAI**:

   ```ts
   import { Agent } from '@mastra/core/agent'

   export const searchAgent = new Agent({
     id: 'search-agent',
     name: 'Search Agent',
     instructions: 'You are a search agent that can search the web for information.',
     model: 'openai/gpt-5.6-sol',
   })
   ```

   **Gemini**:

   ```ts
   import { Agent } from '@mastra/core/agent'

   export const searchAgent = new Agent({
     id: 'search-agent',
     name: 'Search Agent',
     instructions: 'You are a search agent that can search the web for information.',
     model: 'google/gemini-2.5-flash',
   })
   ```

3. Tool을 설정합니다:

   **OpenAI**:

   ```ts
   import { openai } from '@ai-sdk/openai'
   import { Agent } from '@mastra/core/agent'

   export const searchAgent = new Agent({
     id: 'search-agent',
     name: 'Search Agent',
     instructions: 'You are a search agent that can search the web for information.',
     model: 'openai/gpt-5.6-sol',
     tools: {
       webSearch: openai.tools.webSearch(),
     },
   })
   ```

   **Gemini**:

   ```ts
   import { google } from '@ai-sdk/google'
   import { Agent } from '@mastra/core/agent'

   export const searchAgent = new Agent({
     id: 'search-agent',
     name: 'Search Agent',
     instructions: 'You are a search agent that can search the web for information.',
     model: 'google/gemini-2.5-flash',
     tools: {
       webSearch: google.tools.googleSearch({
         mode: 'MODE_DYNAMIC',
       }),
     },
   })
   ```

4. 당신의`src/mastra/index.ts` file, register the agent:

   ```ts
   import { Mastra } from '@mastra/core'
   import { searchAgent } from './agents/searchAgent'

   export const mastra = new Mastra({
     agents: { searchAgent },
   })
   ```

5. 다음을 사용하여 Agent를 테스트할 수 있습니다.[Studio](https://mastra.zisheng.pro/ko/docs/studio/overview) using the `mastra dev` command:

   ```bash
   mastra dev
   ```

   Studio 내부에서**"Search Agent"** 을 열고 "지난주 AI 뉴스에는 어떤 일이 있었나요?"라고 질문합니다.

## 검색 API 사용

검색 동작을 더 효과적으로 제어하려면 외부 검색 API를 사용자 정의 Tool로 통합할 수 있습니다.[Exa](https://exa.ai/) 는 AI 애플리케이션을 위해 특별히 구축된 검색 엔진으로, 의미론적 검색, 구성 가능한 필터(카테고리, 도메인, 날짜 범위), 전체 페이지 콘텐츠 검색 기능을 제공합니다. 검색 API는 입력 schema, 출력 형식 및 실행 로직을 정의하는 Mastra Tool로 래핑됩니다.

1. 종속성 설치

   **npm**:

   ```bash
   npm install exa-js
   ```

   **pnpm**:

   ```bash
   pnpm add exa-js
   ```

   **Yarn**:

   ```bash
   yarn add exa-js
   ```

   **Bun**:

   ```bash
   bun add exa-js
   ```

2. 새 파일 만들기`src/mastra/agents/searchAgent.ts` and define your agent:

   ```ts
   import { Agent } from '@mastra/core/agent'

   export const searchAgent = new Agent({
     id: 'search-agent',
     name: 'Search Agent',
     instructions: 'You are a search agent that can search the web for information.',
     model: 'openai/gpt-5.6-sol',
   })
   ```

3. Tool 설정

   ```ts
   import { createTool } from '@mastra/core/tools'
   import z from 'zod'
   import Exa from 'exa-js'

   export const exa = new Exa(process.env.EXA_API_KEY)

   export const webSearch = createTool({
     id: 'exa-web-search',
     description: 'Search the web',
     inputSchema: z.object({
       query: z.string().min(1).max(50).describe('The search query'),
     }),
     outputSchema: z.array(
       z.object({
         title: z.string().nullable(),
         url: z.string(),
         content: z.string(),
         publishedDate: z.string().optional(),
       }),
     ),
     execute: async inputData => {
       const { results } = await exa.searchAndContents(inputData.query, {
         livecrawl: 'always',
         numResults: 2,
       })

       return results.map(result => ({
         title: result.title,
         url: result.url,
         content: result.text.slice(0, 500),
         publishedDate: result.publishedDate,
       }))
     },
   })
   ```

4. Agent에 추가

   ```ts
   import { webSearch } from './tools/searchTool'

   export const searchAgent = new Agent({
     id: 'search-agent',
     name: 'Search Agent',
     instructions: 'You are a search agent that can search the web for information.',
     model: 'openai/gpt-5.6-sol',
     tools: {
       webSearch,
     },
   })
   ```

5. 당신의`src/mastra/index.ts` file, register the agent:

   ```ts
   import { Mastra } from '@mastra/core'
   import { searchAgent } from './agents/searchAgent'

   export const mastra = new Mastra({
     agents: { searchAgent },
   })
   ```

6. 다음을 사용하여 Agent를 테스트할 수 있습니다.[Studio](https://mastra.zisheng.pro/ko/docs/studio/overview) using the `mastra dev` command:

   ```bash
   mastra dev
   ```

   Studio 내부에서**"Search Agent"** 을 열고 "지난주 AI 뉴스에는 어떤 일이 있었나요?"라고 질문합니다.