클라이언트 SDK

클라이언트 SDK 변경 사항은 유틸리티 이름 변경, 업데이트된 페이지 매김, 유형 명명 규칙을 포함한 서버 측 API 업데이트에 맞춰 조정됩니다.

변경됨

messages이제 와 동일합니다@mastra/core/agent syntax

이제 messages 인수가 generate, stream, network 메서드 호출의 첫 번째 인수이며, 이는 @mastra/core/agent의 Node.js 버전과 유사합니다. 마이그레이션하려면 messages를 메서드 호출의 첫 번째 인수로 이동하세요. 사용@mastra/client-js:

  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를 사용하여 코드를 자동으로 업데이트할 수 있습니다.

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:

  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에 옵션을 수동으로 전달했다면 그에 맞게 업데이트하세요.

  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 옵션으로 스레드 메타데이터를 전달할 수도 있습니다.

await agent.generate([...], {
  memory: {
    thread: {
      id: 'thread-123',
      title: 'Support conversation',
      metadata: { category: 'billing' },
    },
    resource: 'user-456',
  },
});

클라이언트 SDK 타입을 Get*에서 List*로 변경

클라이언트 SDK 타입의 명명 패턴이 Get*에서 List*로 변경되었습니다. 이 변경으로 타입 이름이 메서드 명명 규칙과 일치합니다. 마이그레이션하려면 업데이트 유형을 가져와서 새 이름 지정 패턴을 사용하세요.

- import type {
-   GetWorkflowRunsParams,
-   GetWorkflowRunsResponse,
-   GetMemoryThreadParams,
- } from '@mastra/client-js';
+ import type {
+   ListWorkflowRunsParams,
+   ListWorkflowRunsResponse,
+   ListMemoryThreadsParams,
+ } from '@mastra/client-js';

:::tip[코드모드]

Mastra의 codemod CLI를 사용하여 코드를 자동으로 업데이트할 수 있습니다.

npx @mastra/codemod@latest v1/client-sdk-types .

:::

페이지네이션 매개변수를 offset/limit에서 page/perPage로 변경

offset/limit을 사용하던 모든 클라이언트 SDK 메서드는 이제 페이지 기반 웹 페이지네이션에 맞춰 page/perPage를 사용합니다. 마이그레이션하려면 모든 클라이언트 SDK 메서드 호출에서 페이지 매김 매개변수를 업데이트하세요. 예:

  client.memory.listMessages({
    threadId: 'thread-123',
-   offset: 0,
-   limit: 20,
+   page: 0,
+   perPage: 20,
  });

:::tip[코드모드]

Mastra의 codemod CLI를 사용하여 코드를 자동으로 업데이트할 수 있습니다.

npx @mastra/codemod@latest v1/client-offset-limit .

:::

getMemoryThread매개변수 구조

getMemoryThread 메서드의 매개변수 구조가 업데이트되었습니다. 이 변경으로 Memory 메서드 전반에서 API의 일관성이 향상됩니다. 마이그레이션하려면 새 매개변수 구조로 메서드 호출을 업데이트하세요. 구체적인 변경 사항은 업데이트된 API 문서를 확인하세요.

- const thread = await client.getMemoryThread(threadId, agentId);
+ const thread = await client.getMemoryThread({ threadId, agentId });

:::tip[코드모드]

Mastra의 codemod CLI를 사용하여 코드를 자동으로 업데이트할 수 있습니다.

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 매개변수를 포함하는 선택적 옵션 객체도 받습니다.

  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를 반환합니다.

- 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.

- 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를 사용하여 코드를 자동으로 업데이트할 수 있습니다.

npx @mastra/codemod@latest v1/client-to-ai-sdk-format .

:::

네트워크 Memory 방법

@mastra/client-js에서 네트워크 Memory 메서드가 제거되었습니다. NetworkMemoryThread 클래스와 네트워크 Memory 관련 메서드는 더 이상 사용할 수 없습니다. 이 변경은 특수한 네트워크 Memory 기능을 제거하여 Memory API를 단순화합니다. 마이그레이션하려면 네트워크 Memory 대신 일반 Memory API를 사용하세요.

- 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를 사용하세요.

- 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.

- const result = await workflow.start({ runId: '123', inputData: { ... } });
+ const run = await workflow.createRun({ runId: '123' });
+ const result = await run.start({ inputData: { ... } });

- 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() 메서드를 사용하세요.

+ 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를 사용하세요.

- 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 엔드포인트를 사용하세요.

- 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를 사용하세요.