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

# 서버 경로

서버 어댑터는 호출할 때 이러한 경로를 등록합니다.`server.init()`. 모든 경로에는`prefix`옵션이 구성된 경우.

## Agent

| 방법     | 경로                                           | 설명                                  |
| ------ | -------------------------------------------- | ----------------------------------- |
| `GET`  | `/api/agents`                                | List all agents                     |
| `GET`  | `/api/agents/:agentId`                       | ID로 Agent 가져오기(버전 쿼리 매개변수 지원)       |
| `POST` | `/api/agents/:agentId/generate`              | Agent 응답 생성                         |
| `POST` | `/api/agents/:agentId/stream`                | 스트림 Agent 응답                        |
| `POST` | `/api/agents/:agentId/send-message`          | 활성 또는 유휴 스레드에 사용자 메시지 보내기           |
| `POST` | `/api/agents/:agentId/queue-message`         | 다음 스레드 차례를 위해 사용자 메시지 대기열에 넣기       |
| `POST` | `/api/agents/:agentId/signals`               | 활성 스레드나 유휴 스레드에 하위 수준 신호 보내기        |
| `POST` | `/api/agents/:agentId/threads/subscribe`     | 스레드 스트림 구독                          |
| `POST` | `/api/agents/:agentId/send-tool-approval`    | Tool 호출을 승인 또는 거부하고 스레드 구독을 통해 재개   |
| `POST` | `/api/agents/:agentId/resume-stream`         | 사용자 정의 데이터를 사용하여 일시중단된 Agent 스트림 재개 |
| `GET`  | `/api/agents/:agentId/tools`                 | Agent Tool 나열                       |
| `POST` | `/api/agents/:agentId/tools/:toolId/execute` | Agent Tool 실행                       |

### Agent 쿼리 매개변수 가져오기

`GET /api/agents/:agentId`코드 정의 Agent에 대한 재정의로 적용되는 저장된 구성 버전을 제어하기 위해 선택적 쿼리 매개 변수를 허용합니다.

| 매개변수        | 유형                       | 기본값           | 설명                                                            |
| ----------- | ------------------------ | ------------- | ------------------------------------------------------------- |
| `status`    | `'draft' \| 'published'` | `'published'` | 확인할 저장 버전입니다. `draft`는 최신 버전을 반환하고 `published`는 활성 버전을 반환합니다. |
| `versionId` | `string`                 | 없음            | 확인할 특정 버전 ID입니다. `status`보다 우선합니다.                            |

```bash
# Get agent with active published overrides (default)
GET /api/agents/my-agent

# Get agent with latest draft overrides
GET /api/agents/my-agent?status=draft

# Get agent with a specific version's overrides
GET /api/agents/my-agent?versionId=abc123
```

### 요청 본문 생성

```typescript
{
  messages: CoreMessage[] | string;       // Required
  instructions?: string;                   // System instructions
  system?: string;                         // System prompt
  context?: CoreMessage[];                 // Additional context
  memory?: { key: string } | boolean;      // Memory config
  resourceId?: string;                     // Resource identifier
  threadId?: string;                       // Thread identifier
  runId?: string;                          // Run identifier
  maxSteps?: number;                       // Max tool steps
  activeTools?: string[];                  // Tools to enable
  toolChoice?: ToolChoice;                 // Tool selection mode
  requestContext?: Record<string, unknown>; // Request context
  output?: ZodSchema;                      // Structured output schema
}
```

### 응답 생성

```typescript
{
  text: string;
  toolCalls?: ToolCall[];
  finishReason: string;
  usage?: {
    promptTokens: number;
    completionTokens: number;
  };
}
```

### Agent 메시지 경로

활성 Agent 루프에 사용자 메시지를 보내거나 유휴 스레드를 깨우려면 `POST /api/agents/:agentId/send-message`를 사용하세요. Mastra가 후속 실행을 시작하기 전에 활성 실행이 완료되어야 한다면 `POST /api/agents/:agentId/queue-message`를 사용하세요. 두 경로 모두 동일한 요청 본문을 허용합니다.

```typescript
{
  message: string | Array<TextPart | FilePart> | {
    contents: string | Array<TextPart | FilePart>;
    attributes?: Record<string, JSONValue>;
    metadata?: Record<string, unknown>;
    providerOptions?: ProviderMetadata;
  };
  runId?: string;
  resourceId?: string;
  threadId?: string;
  ifActive?: {
    behavior?: 'deliver' | 'persist' | 'discard';
    attributes?: Record<string, string | number | boolean>;
  };
  ifIdle?: {
    behavior?: 'wake' | 'persist' | 'discard';
    streamOptions?: Omit<AgentExecutionOptions, 'messages'>;
    attributes?: Record<string, string | number | boolean>;
  };
}
```

`runId`를 생략하면 `resourceId`와 `threadId`가 필요합니다. `ifIdle`은 실행 대상 요청이 아니라 스레드 대상 요청에만 적용됩니다.

#### 메시지 보내기

```bash
curl -X POST http://localhost:4111/api/agents/supportAgent/send-message \
  -H 'Content-Type: application/json' \
  -d '{
    "message": {
      "contents": "Show the shorter version.",
      "attributes": { "sentFrom": "web" }
    },
    "resourceId": "user_123",
    "threadId": "thread_456"
  }'
```

#### 메시지 대기열에 넣기

```bash
curl -X POST http://localhost:4111/api/agents/supportAgent/queue-message \
  -H 'Content-Type: application/json' \
  -d '{
    "message": "Also check whether the tests need updates.",
    "resourceId": "user_123",
    "threadId": "thread_456"
  }'
```

두 경로 모두 다음을 반환합니다.

```typescript
{
  accepted: true;
  runId: string;
  signal?: CreatedAgentSignal;
}
```

### 구독 Tool 승인 경로

클라이언트에 이미 활성 스레드 구독이 있다면 `POST /api/agents/:agentId/send-tool-approval`을 사용하세요. 이 경로는 실행을 재개하고 JSON 확인 응답을 반환합니다. 재개된 스트림 청크는 `POST /api/agents/:agentId/threads/subscribe`를 통해 전달됩니다. 경로는 다음 요청 본문을 수락합니다.

```typescript
{
  resourceId: string;
  threadId: string;
  toolCallId: string;
  approved: boolean;
  requestContext?: Record<string, unknown>;
}
```

경로는 다음을 반환합니다.

```typescript
{
  accepted: true;
  runId: string;
  toolCallId?: string;
}
```

## Workflow

| 메서드    | 경로                                        | 설명                                 |
| ------ | ----------------------------------------- | ---------------------------------- |
| `GET`  | `/api/workflows`                          | 모든 Workflow 나열                     |
| `GET`  | `/api/workflows/run-counts`               | Workflow별 실행 중이거나 일시 중단된 실행 수 가져오기 |
| `GET`  | `/api/workflows/:workflowId`              | ID로 Workflow 가져오기                  |
| `POST` | `/api/workflows/:workflowId/create-run`   | 새 Workflow 실행 생성                   |
| `POST` | `/api/workflows/:workflowId/start-async`  | Workflow를 시작하고 결과 대기               |
| `POST` | `/api/workflows/:workflowId/stream`       | Workflow 실행 스트리밍                   |
| `POST` | `/api/workflows/:workflowId/resume`       | 일시 중단된 Workflow 재개                 |
| `POST` | `/api/workflows/:workflowId/resume-async` | 비동기식으로 재개                          |
| `GET`  | `/api/workflows/:workflowId/runs`         | Workflow 실행 나열                     |
| `GET`  | `/api/workflows/:workflowId/runs/:runId`  | 특정 실행 가져오기                         |

### 실행 횟수 응답

`/api/workflows/run-counts` 엔드포인트는 등록된 모든 Workflow의 `running` 및 [`suspended`](https://mastra.zisheng.pro/ko/docs/workflows/suspend-and-resume) 실행 수를 반환합니다. 레코드의 키는 Mastra 구성에 있는 Workflow의 레지스트리 키이며, 서버는 응답을 몇 초 동안 캐시할 수 있습니다.

```typescript
{
  [workflowRegistryKey: string]: {
    running: number;
    suspended: number;
  };
}
```

### 동적 Workflow

동적 Workflow 정의(베타)는 JSON으로 표현되고 `workflowDefinitions` 저장소 도메인에 저장되며 실행 중인 인스턴스에 실시간으로 등록됩니다. [동적 Workflow](https://mastra.zisheng.pro/ko/docs/workflows/dynamic-workflows)를 참조하세요.

| 메서드                                                                                                                                                             | 경로                                         | 설명                                                |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------ | ------------------------------------------------- |
| `GET`                                                                                                                                                           | `/api/stored/workflows`                    | `status`와 `authorId`로 필터링할 수 있는 동적 Workflow 정의 나열 |
| `GET`                                                                                                                                                           | `/api/stored/workflows/:dynamicWorkflowId` | ID로 동적 Workflow 정의 가져오기                           |
| `POST`                                                                                                                                                          | `/api/stored/workflows`                    | 정의를 업서트하고(선택적 도우미 `dependencies` 포함) 실시간으로 등록     |
| `DELETE`                                                                                                                                                        | `/api/stored/workflows/:dynamicWorkflowId` | 동적 Workflow 정의를 삭제하고 실시간 Workflow 등록 해제           |
| 인증된 서버에서 읽기 경로에는 `stored-workflows:read` 권한이 필요하고 쓰기 경로에는 `stored-workflows:write` 권한이 필요합니다. 등록된 동적 Workflow는 위의 일반 `/api/workflows/:workflowId` 경로를 통해 실행됩니다. |                                            |                                                   |

### 실행 요청 본문 만들기

```typescript
{
  resourceId?: string;     // Associate run with a resource (e.g., user ID)
  disableScorers?: boolean; // Disable scorers for this run
}
```

### 요청 본문`/start-async`

```typescript
{
  resourceId?: string;     // Associate run with a resource (e.g., user ID)
  inputData?: unknown;
  initialState?: unknown;
  requestContext?: Record<string, unknown>;
  tracingOptions?: {
    spanName?: string;
    attributes?: Record<string, unknown>;
  };
}
```

### 스트림 Workflow 요청 본문

```typescript
{
  resourceId?: string;     // Associate run with a resource (e.g., user ID)
  inputData?: unknown;
  initialState?: unknown;
  requestContext?: Record<string, unknown>;
  closeOnSuspend?: boolean;
}
```

### 이력서 요청 본문

```typescript
{
  step?: string | string[];
  resumeData?: unknown;
  requestContext?: Record<string, unknown>;
}
```

## Tool

| 메서드    | 경로                           | 설명            |
| ------ | ---------------------------- | ------------- |
| `GET`  | `/api/tools`                 | 모든 Tool 나열    |
| `GET`  | `/api/tools/:toolId`         | ID로 Tool 가져오기 |
| `POST` | `/api/tools/:toolId/execute` | Tool 실행       |

### Tool 요청 본문 실행

```typescript
{
  data: unknown;  // Tool input data
  requestContext?: Record<string, unknown>;
}
```

## Memory

| 메서드      | 경로                                       | 설명           |
| -------- | ---------------------------------------- | ------------ |
| `GET`    | `/api/memory/threads`                    | 스레드 나열       |
| `GET`    | `/api/memory/threads/:threadId`          | 스레드 가져오기     |
| `POST`   | `/api/memory/threads`                    | 스레드 생성       |
| `DELETE` | `/api/memory/threads/:threadId`          | 스레드 삭제       |
| `POST`   | `/api/memory/threads/:threadId/clone`    | 스레드 복제       |
| `GET`    | `/api/memory/threads/:threadId/messages` | 스레드 메시지 가져오기 |
| `POST`   | `/api/memory/threads/:threadId/messages` | 메시지 추가       |

### 스레드 요청 본문 만들기

```typescript
{
  resourceId: string;
  title?: string;
  metadata?: Record<string, unknown>;
}
```

### 복제 스레드 요청 본문

```typescript
{
  newThreadId?: string;           // Custom ID for cloned thread
  resourceId?: string;            // Override resource ID
  title?: string;                 // Custom title for clone
  metadata?: Record<string, unknown>;  // Additional metadata
  options?: {
    messageLimit?: number;        // Max messages to clone
    messageFilter?: {
      startDate?: Date;           // Clone messages after this date
      endDate?: Date;             // Clone messages before this date
      messageIds?: string[];      // Clone specific messages
    };
  };
}
```

### 클론 스레드 응답

```typescript
{
  thread: {
    id: string;
    resourceId: string;
    title: string;
    createdAt: Date;
    updatedAt: Date;
    metadata: {
      clone: {
        sourceThreadId: string;
        clonedAt: Date;
        lastMessageId?: string;
      };
      // ... other metadata
    };
  };
  clonedMessages: MastraDBMessage[];
}
```

## 벡터

| 방법     | 경로                                | 설명             |
| ------ | --------------------------------- | -------------- |
| `POST` | `/api/vectors/:vectorName/upsert` | Upsert vectors |
| `POST` | `/api/vectors/:vectorName/query`  | Query vectors  |
| `POST` | `/api/vectors/:vectorName/delete` | Delete vectors |

### 요청 본문 업데이트

```typescript
{
  vectors: Array<{
    id: string
    values: number[]
    metadata?: Record<string, unknown>
  }>
}
```

### 쿼리 요청 본문

```typescript
{
  vector: number[];
  topK?: number;
  filter?: Record<string, unknown>;
  includeMetadata?: boolean;
}
```

## MCP

| 방법     | 경로                                 | 설명                 |
| ------ | ---------------------------------- | ------------------ |
| `GET`  | `/api/mcp/servers`                 | List MCP servers   |
| `GET`  | `/api/mcp/servers/:serverId/tools` | List server tools  |
| `POST` | `/api/mcp/:serverId`               | MCP HTTP transport |
| `GET`  | `/api/mcp/:serverId/sse`           | MCP SSE transport  |

## 응답 API

| 메서드                                                                                                              | 경로                              | 설명                                   |
| ---------------------------------------------------------------------------------------------------------------- | ------------------------------- | ------------------------------------ |
| `POST`                                                                                                           | `/api/v1/responses`             | OpenAI 호환 Responses API 경로를 통해 응답 생성 |
| `GET`                                                                                                            | `/api/v1/responses/:responseId` | 저장된 응답 조회                            |
| `DELETE`                                                                                                         | `/api/v1/responses/:responseId` | 저장된 응답 삭제                            |
| 전체 요청 및 응답 계약은 다음을 참조하세요.[Responses API reference](https://mastra.zisheng.pro/ko/reference/client-js/responses). |                                 |                                      |

## 대화 API

| 메서드                                                                                                                      | 경로                                            | 설명            |
| ------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------- | ------------- |
| `POST`                                                                                                                   | `/api/v1/conversations`                       | 대화 생성         |
| `GET`                                                                                                                    | `/api/v1/conversations/:conversationId`       | 대화 조회         |
| `DELETE`                                                                                                                 | `/api/v1/conversations/:conversationId`       | 대화 삭제         |
| `GET`                                                                                                                    | `/api/v1/conversations/:conversationId/items` | 대화에 저장된 항목 나열 |
| 전체 요청 및 응답 계약은 다음을 참조하세요.[Conversations API reference](https://mastra.zisheng.pro/ko/reference/client-js/conversations). |                                               |               |

## 로그

| 메서드   | 경로                 | 설명             |
| ----- | ------------------ | -------------- |
| `GET` | `/api/logs`        | 로그 나열          |
| `GET` | `/api/logs/:runId` | 실행 ID로 로그 가져오기 |

### 쿼리 매개변수

```typescript
{
  page?: number;
  perPage?: number;
  transportId?: string;
}
```

## 원격 측정

| 방법    | 경로                                     | 설명              |
| ----- | -------------------------------------- | --------------- |
| `GET` | `/api/telemetry/traces`                | List traces     |
| `GET` | `/api/telemetry/traces/:traceId`       | Get trace       |
| `GET` | `/api/telemetry/traces/:traceId/spans` | Get trace spans |

## 일반적인 쿼리 매개변수

### 쪽수 매기기

대부분의 목록 끝점은 다음을 지원합니다.

```typescript
{
  page?: number;   // Page number (0-indexed)
  perPage?: number; // Items per page (default: 10)
}
```

### 필터링

Workflow 실행 지원:

```typescript
{
  fromDate?: string;  // ISO date string
  toDate?: string;    // ISO date string
  status?: string;    // Run status filter
  resourceId?: string; // Filter by resource
}
```

## 오류 응답

모든 경로는 다음 형식으로 오류를 반환합니다.

```typescript
{
  error: string;      // Error message
  details?: unknown;  // Additional details
}
```

일반적인 상태 코드:

| 코드  | 의미                       |
| --- | ------------------------ |
| 400 | 잘못된 요청 - 잘못된 매개변수        |
| 401 | 승인되지 않음 - 인증 누락/잘못       |
| 403 | 금지됨 - 권한 부족              |
| 404 | 찾을 수 없음 - 리소스가 존재하지 않습니다 |
| 500 | 내부 서버 오류                 |

## 관련된

- [경로 생성()](https://mastra.zisheng.pro/ko/reference/server/create-route): 커스텀 경로 생성
- [서버 어댑터](https://mastra.zisheng.pro/ko/docs/server/server-adapters): 어댑터 사용