> Discover all available pages from the documentation index: https://mastra.zisheng.pro/ko/llms.txt # 클라이언트 SDK 클라이언트 SDK 변경 사항은 유틸리티 이름 변경, 업데이트된 페이지 매김, 유형 명명 규칙을 포함한 서버 측 API 업데이트에 맞춰 조정됩니다. ## 변경됨 ### `messages`이제 와 동일합니다`@mastra/core/agent` syntax 이제 `messages` 인수가 `generate`, `stream`, `network` 메서드 호출의 첫 번째 인수이며, 이는 `@mastra/core/agent`의 Node.js 버전과 유사합니다. 마이그레이션하려면 `messages`를 메서드 호출의 첫 번째 인수로 이동하세요. **사용`@mastra/client-js`:** ```diff const agent = client.getAgent('my-agent'); - await agent.generate({ - messages: [...] + await agent.generate([...], { }); - await agent.stream({ - messages: [...] + await agent.stream([...], { }); - await agent.network({ - messages: [...] + await agent.network([...], { }); ``` :::tip\[코드모드] Mastra의 codemod CLI를 사용하여 코드를 자동으로 업데이트할 수 있습니다. ```bash npx @mastra/codemod@latest v1/client-msg-function-args . ``` ::: ### `threadId` 및 `resourceId`를 `memory` 옵션으로 이동 Agent 메서드 호출에서 `threadId`와 `resourceId` 옵션이 제거되었습니다. 대신 Memory 구성을 위한 더 깔끔한 API를 제공하는 `memory` 옵션을 사용하세요. 이는 `@mastra/client-js`와 `@mastra/react` 패키지 모두에 적용됩니다. 마이그레이션하려면 `threadId`와 `resourceId`를 `memory` 옵션 안으로 이동하세요. **사용`@mastra/client-js`:** ```diff const agent = client.getAgent('my-agent'); await agent.generate([...], { - threadId: 'thread-123', - resourceId: 'user-456', + memory: { + thread: 'thread-123', + resource: 'user-456', + }, }); + await agent.stream([...], { - threadId: 'thread-123', - resourceId: 'user-456', + memory: { + thread: 'thread-123', + resource: 'user-456', + }, }); ``` #### 사용`@mastra/react` `useChat` hook `useChat` 후크는 `threadId`를 제공하면 내부적으로 Memory 옵션을 전달합니다. 후크에 내장된 Memory 처리를 사용하고 있다면 컴포넌트 코드를 변경할 필요가 없습니다. 하지만 `sendMessage`에 옵션을 수동으로 전달했다면 그에 맞게 업데이트하세요. ```diff const { sendMessage } = useChat({ agentId: 'my-agent' }); await sendMessage({ message: 'Hello', mode: 'stream', - threadId: 'thread-123', + threadId: 'thread-123', // Still works - internally converted to memory option }); ``` 새 스레드를 생성할 때 `memory` 옵션으로 스레드 메타데이터를 전달할 수도 있습니다. ```typescript await agent.generate([...], { memory: { thread: { id: 'thread-123', title: 'Support conversation', metadata: { category: 'billing' }, }, resource: 'user-456', }, }); ``` ### 클라이언트 SDK 타입을 `Get*`에서 `List*`로 변경 클라이언트 SDK 타입의 명명 패턴이 `Get*`에서 `List*`로 변경되었습니다. 이 변경으로 타입 이름이 메서드 명명 규칙과 일치합니다. 마이그레이션하려면 업데이트 유형을 가져와서 새 이름 지정 패턴을 사용하세요. ```diff - import type { - GetWorkflowRunsParams, - GetWorkflowRunsResponse, - GetMemoryThreadParams, - } from '@mastra/client-js'; + import type { + ListWorkflowRunsParams, + ListWorkflowRunsResponse, + ListMemoryThreadsParams, + } from '@mastra/client-js'; ``` :::tip\[코드모드] Mastra의 codemod CLI를 사용하여 코드를 자동으로 업데이트할 수 있습니다. ```bash npx @mastra/codemod@latest v1/client-sdk-types . ``` ::: ### 페이지네이션 매개변수를 `offset/limit`에서 `page/perPage`로 변경 `offset/limit`을 사용하던 모든 클라이언트 SDK 메서드는 이제 페이지 기반 웹 페이지네이션에 맞춰 `page/perPage`를 사용합니다. 마이그레이션하려면 모든 클라이언트 SDK 메서드 호출에서 페이지 매김 매개변수를 업데이트하세요. 예: ```diff client.memory.listMessages({ threadId: 'thread-123', - offset: 0, - limit: 20, + page: 0, + perPage: 20, }); ``` :::tip\[코드모드] Mastra의 codemod CLI를 사용하여 코드를 자동으로 업데이트할 수 있습니다. ```bash npx @mastra/codemod@latest v1/client-offset-limit . ``` ::: ### `getMemoryThread`매개변수 구조 `getMemoryThread` 메서드의 매개변수 구조가 업데이트되었습니다. 이 변경으로 Memory 메서드 전반에서 API의 일관성이 향상됩니다. 마이그레이션하려면 새 매개변수 구조로 메서드 호출을 업데이트하세요. 구체적인 변경 사항은 업데이트된 API 문서를 확인하세요. ```diff - const thread = await client.getMemoryThread(threadId, agentId); + const thread = await client.getMemoryThread({ threadId, agentId }); ``` :::tip\[코드모드] Mastra의 codemod CLI를 사용하여 코드를 자동으로 업데이트할 수 있습니다. ```bash npx @mastra/codemod@latest v1/client-get-memory-thread . ``` ::: ### Workflow 실행을 위한 통합 `runById` API 이제 `runById()` 메서드는 메타데이터(runId, workflowName, resourceId, createdAt, updatedAt)와 처리된 실행 상태(status, result, error, payload, steps)를 모두 포함하는 통합 `WorkflowState` 객체를 반환합니다. 이전에 분리되어 있던 `runById()`와 `runExecutionResult()` 메서드가 하나로 통합되었습니다. 이 메서드는 성능 최적화를 위한 `fields` 및 `withNestedWorkflows` 매개변수를 포함하는 선택적 옵션 객체도 받습니다. ```diff const workflow = client.getWorkflow('my-workflow'); - // Previously: runById returned raw WorkflowRun with snapshot - const run = await workflow.runById(runId, requestContext); - // Separately: runExecutionResult returned processed execution state - const result = await workflow.runExecutionResult(runId); + // Now: Single method returns unified WorkflowState + const run = await workflow.runById(runId, { + requestContext, // Optional request context + fields: ['status', 'result'], // Optional: request only specific fields + withNestedWorkflows: false, // Optional: skip nested workflow data for performance + }); + // Returns: { runId, workflowName, resourceId, createdAt, updatedAt, status, result, error, payload, steps } ``` ## 제거됨 ### `runExecutionResult`방법과`GetWorkflowRunExecutionResultResponse` type `@mastra/client-js`에서 `runExecutionResult()` 메서드와 `GetWorkflowRunExecutionResultResponse` 타입이 제거되었습니다. `/execution-result` API 엔드포인트도 제거되었습니다. 마이그레이션하려면 대신 `runById()`를 사용하세요. 이제 메타데이터와 처리된 실행 상태를 모두 포함하는 동일한 통합 `WorkflowState`를 반환합니다. ```diff - import type { GetWorkflowRunExecutionResultResponse } from '@mastra/client-js'; - - const workflow = client.getWorkflow('my-workflow'); - const result = await workflow.runExecutionResult(runId); + const workflow = client.getWorkflow('my-workflow'); + const result = await workflow.runById(runId); + // Or with options for performance optimization: + const result = await workflow.runById(runId, { + fields: ['status', 'result'], // Only fetch specific fields + withNestedWorkflows: false, // Skip expensive nested workflow data + }); ``` ### `toAISdkFormat`기능 `@mastra/ai-sdk`에서 `toAISdkFormat()` 함수가 제거되었습니다. 대신 아래에 표시된 스트림 변환 유틸리티를 사용하세요. 마이그레이션하려면 다음을 사용하십시오.`toAISdkStream()` instead. ```diff - import { toAISdkFormat } from '@mastra/ai-sdk'; - const stream = toAISdkFormat(agentStream, { from: 'agent' }); + import { toAISdkStream } from '@mastra/ai-sdk'; + const stream = toAISdkStream(agentStream, { from: 'agent' }); ``` :::tip\[코드모드] Mastra의 codemod CLI를 사용하여 코드를 자동으로 업데이트할 수 있습니다. ```bash npx @mastra/codemod@latest v1/client-to-ai-sdk-format . ``` ::: ### 네트워크 Memory 방법 `@mastra/client-js`에서 네트워크 Memory 메서드가 제거되었습니다. `NetworkMemoryThread` 클래스와 네트워크 Memory 관련 메서드는 더 이상 사용할 수 없습니다. 이 변경은 특수한 네트워크 Memory 기능을 제거하여 Memory API를 단순화합니다. 마이그레이션하려면 네트워크 Memory 대신 일반 Memory API를 사용하세요. ```diff - import { MastraClient } from '@mastra/client-js'; - - const client = new MastraClient({ baseUrl: '...' }); - const networkThread = client.networkMemory.getThread('thread-id'); - const networkThread = client.memory.networkThread('thread-id', 'network-id'); - await networkThread.get(); - await networkThread.getMessages(); + // Use regular memory thread APIs instead + const client = new MastraClient({ baseUrl: '...' }); + const thread = client.memory.getThread('thread-id'); + await thread.get(); + const messages = await thread.listMessages(); ``` ### 시계 관련 유형 `@mastra/client-js`에서 감시 관련 타입이 제거되었습니다. 여기에는 `WorkflowWatchResult`, `WatchEvent` 및 관련 타입이 포함됩니다. 이 변경은 스트리밍을 우선하여 감시 API를 제거한 것을 반영합니다. 마이그레이션하려면 감시 대신 Workflow 스트리밍 API를 사용하세요. ```diff - import type { WorkflowWatchResult, WatchEvent } from '@mastra/client-js'; - - const workflow = client.getWorkflow('my-workflow'); - const run = await workflow.createRun(); - await run.watch((event: WatchEvent) => { - console.log('Event:', event); - }); + const workflow = client.getWorkflow('my-workflow'); + const run = await workflow.createRun(); + const stream = await run.stream({ inputData: { ... } }); + for await (const chunk of stream) { + console.log('Event:', chunk); + } ``` ### 실행 관련 메서드는 Workflow 인스턴스에서 직접 호출할 수 없습니다. 실행 관련 메서드는 Workflow 인스턴스에서 직접 호출할 수 없습니다. 먼저 다음을 사용하여 실행 인스턴스를 만들어야 합니다.`createRun()` method. ```diff - const result = await workflow.start({ runId: '123', inputData: { ... } }); + const run = await workflow.createRun({ runId: '123' }); + const result = await run.start({ inputData: { ... } }); ``` ```diff - const result = await workflow.stream({ runId: '123', inputData: { ... } }); + const run = await workflow.createRun({ runId: '123' }); + const stream = await run.stream({ inputData: { ... } }); ``` ### `streamVNext`, `resumeStreamVNext`, `observeStreamVNext` 메서드 실험적 `streamVNext()`, `resumeStreamVNext()`, `observeStreamVNext()` 메서드가 제거되었습니다. 이제 업데이트된 이벤트 구조와 반환 타입을 사용하는 해당 구현이 표준입니다. 마이그레이션하려면 대신 표준 `stream()`, `resumeStream()`, `observeStream()` 메서드를 사용하세요. ```diff + const run = await workflow.createRun({ runId: '123' }); - const stream = await run.streamVNext({ inputData: { ... } }); + const stream = await run.stream({ inputData: { ... } }); ``` ### 더 이상 사용되지 않는 스트림 엔드포인트 일부 스트림 엔드포인트는 더 이상 사용되지 않으며 제거될 예정입니다. `/api/agents/:agentId/stream/vnext` 엔드포인트는 410 Gone을 반환하며 `/api/agents/:agentId/stream/ui`는 더 이상 사용되지 않습니다. 이 변경으로 표준 스트리밍 엔드포인트를 중심으로 통합됩니다. 마이그레이션하려면 표준 스트림 엔드포인트를 사용하거나 UI 메시지 변환에 `@mastra/ai-sdk`를 사용하세요. ```diff - const response = await fetch('/api/agents/my-agent/stream/vnext', { - method: 'POST', - body: JSON.stringify({ messages: [...] }), - }); + const response = await fetch('/api/agents/my-agent/stream', { + method: 'POST', + body: JSON.stringify({ messages: [...] }), + }); + + // Or use @mastra/ai-sdk for UI message transformations ``` ### 네트워크 Memory API 엔드포인트 `/api/memory/network/*`를 비롯한 네트워크 Memory API 엔드포인트가 제거되었습니다. 이 변경으로 Memory API 범위가 단순해집니다. 마이그레이션하려면 일반 Memory API 엔드포인트를 사용하세요. ```diff - const networkThread = await fetch('/api/memory/network/threads/thread-123'); + const thread = await fetch('/api/memory/threads/thread-123'); ``` ### 평가 관련 클라이언트 SDK 유형 `GetEvalsByAgentIdResponse`, `GetTelemetryResponse`, `GetTelemetryParams`를 비롯한 여러 평가 관련 타입이 클라이언트 SDK에서 제거되었습니다. 이 변경은 레거시 Evals 기능의 제거를 반영합니다. 마이그레이션하려면 레거시 평가 대신 새로운 득점자 API를 사용하세요.