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

# 마운트AgentControllerOnMastra()

:::실험적

`@mastra/code-sdk` 패키지는 실험 단계이며 마이너 버전에서 호환성을 깨는 변경이 발생할 수 있습니다. :::

`mountAgentControllerOnMastra()` 함수는 Mastra Code Agent 컨트롤러([`mastracode`](https://www.npmjs.com/package/mastracode) CLI의 기반이 되는 코딩 Agent로, 모드, Tool, Memory 및 스레드 관리 기능 포함)를 빌드하고 서버가 소유한 [Mastra](https://mastra.zisheng.pro/ko/reference/core/mastra-class) 인스턴스에 등록합니다. 이 함수를 사용하면 자체 UI(웹 앱, 편집기, 봇)에서 Mastra Code Agent를 제공할 수 있습니다. 각 클라이언트는 반환된 [`AgentController`](https://mastra.zisheng.pro/ko/reference/agent-controller/agent-controller-class)를 통해 격리된 자체 세션을 생성하거나 재개합니다. `Mastra` 인스턴스를 직접 구성하려면(예: 배포 가능한 엔트리 파일에서) 동일한 패키지의 `prepareAgentControllerMount()`를 사용하세요. 이 함수는 생성자 인수와 `finalize()` 콜백을 반환합니다.

## 사용예

```typescript
import { mountAgentControllerOnMastra } from '@mastra/code-sdk'

const { mastra, controller } = await mountAgentControllerOnMastra({
  cwd: process.cwd(),
})

// Each client drives its own session
const session = await controller.createSession({ resourceId: 'user-123' })
```

이미 다른 프리미티브를 호스팅하는 Mastra 인스턴스에 컨트롤러를 마운트하려면 기존 `mastra`를 전달하세요.

```typescript
import { Mastra } from '@mastra/core/mastra'
import { mountAgentControllerOnMastra } from '@mastra/code-sdk'

const mastra = new Mastra({/* ... */})

const { controller } = await mountAgentControllerOnMastra({ mastra })
```

## 매개변수

**cwd** (`string`): 프로젝트 감지에 사용할 작업 디렉터리입니다. (Default: `process.cwd()`)

**mastra** (`Mastra`): 마운트할 기존 Mastra 인스턴스입니다. 생략하면 컨트롤러 스토리지를 소유하는 Mastra가 생성됩니다.

**controllerId** (`string`): Mastra 인스턴스에 컨트롤러를 등록할 ID입니다.

**modes** (`AgentControllerMode[]`): Agent 모드(Model ID, 색상, 존재하는 모드)를 재정의합니다. (Default: `build/plan/fast`)

**subagents** (`AgentControllerSubagent[]`): 하위 Agent 정의를 재정의하거나 확장합니다. (Default: `explore/plan/execute`)

**extraTools** (`Record<string, ToolAction> | (ctx) => Record<string, ToolAction>`): 동적 Tool 집합에 병합할 추가 Tool입니다.

**postToolObserver** (`(context: ToolAfterHookContext) => void | Promise<void>`): Tool을 교체하거나 후크 관리자 동작을 변경하지 않고 완료된 Tool 호출을 관찰합니다. 관찰자 오류는 기록되며 성공한 Tool 호출을 실패로 처리하지 않습니다.

**inputProcessors** (`InputProcessor[]`): Mastra Code의 필수 안전 및 호환성 프로세서 앞에 추가되는 무상태 입력 프로세서입니다. 사용자 정의 프로세서는 파이프라인을 확장하지만 기본 제공 프로세서를 대체할 수 없습니다.

**disabledTools** (`string[]`): Model에 노출하기 전에 동적 Tool 집합에서 제거할 Tool입니다.

**storage** (`StorageConfig`): 자동 감지된 기본값 대신 사용할 사용자 정의 스토리지 구성입니다.

**workspace** (`AgentControllerConfig["workspace"]`): Workspace를 재정의합니다. (Default: `감지된 프로젝트를 기반으로 하는 로컬 파일 시스템 + 로컬 Sandbox`)

**configDir** (`string`): 모든 프로젝트 수준 및 전역 구성 경로(MCP, 후크, 명령, 데이터베이스, Skill, Agent 지침)에 사용되는 구성 디렉터리 이름을 재정의합니다. (Default: `'.mastracode'`)

**mcpServers** (`Record<string, McpServerConfig>`): 파일 기반 구성과 병합되며 이를 재정의하는 프로그래밍 방식의 MCP 서버 구성입니다.

**buildApiRoutes** (`(deps: { controller, authStorage }) => ApiRoute[]`): 생성된 Mastra에 등록할 추가 API 경로입니다. mastra가 제공되면 무시됩니다.

**buildServerConfig** (`(deps: { controller, authStorage }) => ServerConfig`): 생성된 Mastra에 통합할 추가 서버 구성(미들웨어, CORS)입니다. mastra가 제공되면 무시됩니다.

## 보고

**mastra** (`Mastra`): 컨트롤러가 마운트된 Mastra 인스턴스입니다(생성되었거나 전달된 인스턴스).

**controller** (`AgentController`): 초기화된 Mastra Code Agent 컨트롤러입니다. controller.createSession()으로 세션을 생성하세요.

**authStorage** (`AuthStorage`): 기본 제공 Model 게이트웨이에서 사용하는 자격 증명 스토리지입니다.

## 관련된

- [AgentController 클래스](https://mastra.zisheng.pro/ko/reference/agent-controller/agent-controller-class)
- [세션 클래스](https://mastra.zisheng.pro/ko/reference/agent-controller/session)