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

# 채팅경로()

AI SDK 형식을 사용하여 스트리밍 Agent 대화를 위한 채팅 경로 핸들러를 만듭니다. 이 함수는 HTTP를 등록합니다.`POST`메시지를 수락하고, Agent를 실행하고, AI SDK 호환 형식으로 클라이언트에 응답을 다시 스트리밍하는 엔드포인트입니다. 내부에서 사용해야합니다.[커스텀 API 경로](https://mastra.zisheng.pro/ko/docs/server/custom-api-routes).

프레임워크에 구애받지 않는 핸들러가 필요하면 [`handleChatStream()`](https://mastra.zisheng.pro/ko/reference/ai-sdk/handle-chat-stream)을 사용하세요. `chatRoute()`기존 AI SDK v5/기본 동작을 유지합니다. 앱이 AI SDK v6에 대해 입력된 경우 다음을 통과하세요.`version: 'v6'`.

> **연결 끊기 동작:** `chatRoute()`는 들어오는 요청의 `AbortSignal`을 `agent.stream()`에 전달합니다. 클라이언트 연결이 끊어지면 Mastra가 진행 중인 생성을 중단합니다. 연결이 끊어진 후에도 서버가 생성을 계속하고 최종 응답을 유지하게 하려면 `agent.stream()`을 감싸는 [사용자 지정 API 경로](https://mastra.zisheng.pro/ko/docs/server/custom-api-routes)를 만들고 반환된 `MastraModelOutput`에서 `consumeStream()`을 호출하세요.

## 사용예

이 예제는 ID가 `weatherAgent`인 Agent를 사용하는 `/chat` 엔드포인트에 채팅 경로를 설정하는 방법을 보여줍니다.

```typescript
import { Mastra } from '@mastra/core'
import { chatRoute } from '@mastra/ai-sdk'

export const mastra = new Mastra({
  server: {
    apiRoutes: [
      chatRoute({
        path: '/chat',
        agent: 'weatherAgent',
      }),
    ],
  },
})
```

`agentId`를 기반으로 런타임에 정의되는 Agent 라우팅을 사용할 수도 있습니다. URL `/chat/weatherAgent`는 ID가 `weatherAgent`인 Agent로 확인됩니다.

```typescript
import { Mastra } from '@mastra/core'
import { chatRoute } from '@mastra/ai-sdk'

export const mastra = new Mastra({
  server: {
    apiRoutes: [
      chatRoute({
        path: '/chat/:agentId',
      }),
    ],
  },
})
```

## 매개변수

**version** (`'v5' | 'v6'`): 내보낼 AI SDK 스트림 계약을 선택합니다. 기존 기본 동작을 사용하려면 생략하거나 'v5'를 전달하세요. 앱이 AI SDK v6 응답 헬퍼에 맞게 타입이 지정된 경우 'v6'을 전달하세요. (Default: `'v5'`)

**path** (`string`): 경로 패스입니다(예: /chat 또는 /chat/:agentId). 동적 Agent 라우팅에는 :agentId를 포함하세요. (Default: `'/chat/:agentId'`)

**agent** (`string`): 이 채팅 경로에 사용할 Agent의 ID입니다. 패스에 :agentId가 포함되지 않은 경우 필수입니다.

**agentVersion** (`{ versionId: string } | { status?: 'draft' | 'published' }`): 특정 Agent 버전을 선택합니다. 정확한 버전을 대상으로 지정하려면 { versionId: '\<id>' }를 전달하고, 상태로 확인하려면 { status: 'draft' } / { status: 'published' }를 전달하세요. 경로가 호출되면 쿼리 매개변수 ?versionId=\<id> 또는 ?status=draft|published가 이 정적 값보다 우선합니다. Editor가 구성되어 있어야 합니다.

**defaultOptions** (`AgentExecutionOptions`): Agent 실행에 전달되는 기본 옵션입니다. 지침, Memory 구성, maxSteps 및 기타 실행 설정을 포함할 수 있습니다.

**sendStart** (`boolean`): 스트림에서 시작 이벤트를 전송할지 여부입니다. (Default: `true`)

**sendFinish** (`boolean`): 스트림에서 완료 이벤트를 전송할지 여부입니다. (Default: `true`)

**sendReasoning** (`boolean`): 스트림에 추론 단계를 포함할지 여부입니다. (Default: `false`)

**sendSources** (`boolean`): 스트림에 출처 인용을 포함할지 여부입니다. (Default: `false`)

**heartbeatMs** (`number`): 유휴 시간 제한이 있는 인프라에서도 연결을 활성 상태로 유지하기 위한 SSE 하트비트 간격(밀리초)입니다.

## 추가 구성

[`prepareSendMessagesRequest`](https://ai-sdk.dev/docs/reference/ai-sdk-ui/use-chat#transport.default-chat-transport.prepare-send-messages-request)를 사용하면 Agent에 추가 구성을 전달하는 등의 방식으로 채팅 경로에 전송되는 요청을 사용자 지정할 수 있습니다.

```typescript
const { error, status, sendMessage, messages, regenerate, stop } = useChat({
  transport: new DefaultChatTransport({
    api: 'http://localhost:4111/chat',
    prepareSendMessagesRequest({ messages }) {
      return {
        body: {
          messages,
          // Pass memory config
          memory: {
            thread: 'user-1',
            resource: 'user-1',
          },
        },
      }
    },
  }),
})
```