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

# Hono 프로젝트에 Mastra 통합

이 가이드에서는 Mastra와 Hono를 사용하여 Tool 호출 AI Agent를 구축합니다. 사용하여[Hono server adapter](https://mastra.zisheng.pro/ko/reference/server/hono-adapter), 라우팅을 직접 작성하거나 별도의 Mastra 서버를 실행하지 않고도 Agent를 HTTP 엔드포인트로 노출할 수 있습니다.

## 시작하기 전에

- 지원되는 [Model Provider](https://mastra.zisheng.pro/ko/models)의 API 키가 필요합니다. 선호하는 Provider가 없다면 [OpenAI](https://mastra.zisheng.pro/ko/models/providers/openai)를 사용하세요.
- Node.js `v22.13.0` 이상 설치

## 새 Hono 앱 만들기(선택 사항)

이미 Hono 앱이 있다면 다음 단계로 건너뛰세요.

다음 명령을 실행하여 [새 Hono 앱을 생성](https://hono.dev/docs/getting-started/basic)합니다.

**npm**:

```bash
npm create hono@latest mastra-hono -- --template nodejs --install --pm npm
```

**pnpm**:

```bash
pnpm create hono mastra-hono --template nodejs --install --pm npm
```

**Yarn**:

```bash
yarn create hono mastra-hono --template nodejs --install --pm npm
```

**Bun**:

```bash
bunx create-hono mastra-hono --template nodejs --install --pm npm
```

이 명령은 `mastra-hono`라는 프로젝트를 생성하지만 원하는 이름으로 바꿀 수 있습니다.

## 마스트라 초기화

Hono 프로젝트 디렉터리로 이동합니다.

```bash
cd mastra-hono
```

[`mastra init`](https://mastra.zisheng.pro/ko/reference/cli/mastra)을 실행합니다. 메시지가 표시되면 Provider(예: OpenAI)를 선택하고 키를 입력합니다.

**npm**:

```bash
npx mastra@latest init
```

**pnpm**:

```bash
pnpm dlx mastra@latest init
```

**Yarn**:

```bash
yarn dlx mastra@latest init
```

**Bun**:

```bash
bun x mastra@latest init
```

그러면 예제 날씨 Agent와 다음 파일을 포함하는 `src/mastra` 폴더가 생성됩니다.

- `index.ts`- Memory를 포함한 마스트라 구성
- `tools/weather-tool.ts`- 특정 위치의 날씨를 가져오는 Tool
- `agents/weather-agent.ts`- Tool을 사용하는 Prompt가 있는 기상 요원

나중에 `src/mastra/index.ts` 파일을 Hono 서버 어댑터에 전달합니다.

## 서버 어댑터 추가

Hono 서버 어댑터 패키지를 설치합니다.

**npm**:

```bash
npm install @mastra/hono@latest
```

**pnpm**:

```bash
pnpm add @mastra/hono@latest
```

**Yarn**:

```bash
yarn add @mastra/hono@latest
```

**Bun**:

```bash
bun add @mastra/hono@latest
```

`src/index.ts`에서 Hono 진입점 파일을 열고 필요한 import 및 초기화 코드를 추가합니다.

```typescript
import { serve } from '@hono/node-server'
import { Hono } from 'hono'
import { type HonoBindings, type HonoVariables, MastraServer } from '@mastra/hono'
import { mastra } from './mastra/index.js'

const app = new Hono<{ Bindings: HonoBindings; Variables: HonoVariables }>()
const server = new MastraServer({ app, mastra })

await server.init()

app.get('/', c => {
  return c.text('Hello Hono!')
})

serve(
  {
    fetch: app.fetch,
    port: 3000,
  },
  info => {
    console.log(`Server is running on http://localhost:${info.port}`)
  },
)
```

⁠`MastraServer`는 기존 Hono `app`과 루트 ⁠`mastra` 인스턴스로 초기화됩니다. `⁠init()`을 호출하면 Mastra 미들웨어가 등록되고 사용 가능한 모든 Mastra 엔드포인트가 노출됩니다.

## Agent 테스트

기본적으로 Mastra 엔드포인트는 `/api` 하위 경로에 위치하며 Agent/Workflow ID를 사용합니다. `mastra init`으로 생성된 기본 `weather-agent`는 `/api/agents/weather-agent`에서 사용할 수 있습니다. Hono 서버를 시작합니다:

**npm**:

```bash
npm run dev
```

**pnpm**:

```bash
pnpm run dev
```

**Yarn**:

```bash
yarn dev
```

**Bun**:

```bash
bun run dev
```

별도의 터미널 창에서 `curl`을 사용하여 날씨 Agent에게 질문합니다.

```bash
curl -X POST http://localhost:3000/api/agents/weather-agent/generate -H "Content-Type: application/json" -d "{\"messages\":[{\"role\":\"user\",\"content\":\"What is the weather like in Seoul?\"}]}"
```

## 다음 단계

Hono를 사용하여 Mastra Agent를 구축한 것을 축하합니다! 🎉

여기에서 자신만의 Tool와 논리를 사용하여 프로젝트를 확장할 수 있습니다.

- [Agent](https://mastra.zisheng.pro/ko/docs/agents/overview)에 관해 자세히 알아보기

- Agent에 고유한 기능을 제공하는 [Tool](https://mastra.zisheng.pro/ko/docs/agents/using-tools) 추가하기

- Agent에 사람과 같은 [Memory](https://mastra.zisheng.pro/ko/docs/memory/overview) 추가하기 준비가 되면 Mastra가 Hono와 통합되는 방법에 대해 자세히 읽어보세요.

- [서버 어댑터](https://mastra.zisheng.pro/ko/docs/server/server-adapters)