服务器路由

🌐 Server Routes

当你调用 server.init() 时，服务器适配器会注册这些路由。如果已配置，所有路由都会加上 prefix 选项作为前缀。

🌐 Server adapters register these routes when you call server.init(). All routes are prefixed with the prefix option if configured.

代理

🌐 Agents

方法	路径	描述
GET	/api/agents	列出所有代理
GET	/api/agents/:agentId	根据ID获取代理
POST	/api/agents/:agentId/generate	生成代理响应
POST	/api/agents/:agentId/stream	流式传输代理响应
GET	/api/agents/:agentId/tools	列出代理工具
POST	/api/agents/:agentId/tools/:toolId/execute	执行代理工具

生成请求正文

🌐 Generate request body

{
  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
}

生成回应

🌐 Generate response

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

工作流程

🌐 Workflows

方法	路径	描述
GET	/api/workflows	列出所有工作流
GET	/api/workflows/:workflowId	通过 ID 获取工作流
POST	/api/workflows/:workflowId/create-run	创建新的工作流运行
POST	/api/workflows/:workflowId/start-async	启动工作流并等待结果
POST	/api/workflows/:workflowId/stream	流式执行工作流
POST	/api/workflows/:workflowId/resume	恢复挂起的工作流
POST	/api/workflows/:workflowId/resume-async	异步恢复
GET	/api/workflows/:workflowId/runs	列出工作流运行
GET	/api/workflows/:workflowId/runs/:runId	获取特定运行

创建运行请求主体

🌐 Create run request body

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

启动异步请求体

🌐 Start-async request body

{
  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>;
  };
}

流工作流请求体

🌐 Stream workflow request body

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

恢复请求正文

🌐 Resume request body

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

工具

🌐 Tools

方法	路径	描述
GET	/api/tools	列出所有工具
GET	/api/tools/:toolId	通过ID获取工具
POST	/api/tools/:toolId/execute	执行工具

执行工具请求主体

🌐 Execute tool request body

{
  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	添加消息

创建线程请求主体

🌐 Create thread request body

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

克隆线程请求正文

🌐 Clone thread request body

{
  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
    };
  };
}

克隆线程响应

🌐 Clone thread response

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

向量

🌐 Vectors

方法	路径	描述
POST	/api/vectors/:vectorName/upsert	插入或更新向量
POST	/api/vectors/:vectorName/query	查询向量
POST	/api/vectors/:vectorName/delete	删除向量

Upsert 请求体

🌐 Upsert request body

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

查询请求正文

🌐 Query request body

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

MCP

方法	路径	描述
GET	/api/mcp/servers	列出 MCP 服务器
GET	/api/mcp/servers/:serverId/tools	列出服务器工具
POST	/api/mcp/:serverId	MCP HTTP 传输
GET	/api/mcp/:serverId/sse	MCP SSE 传输

日志

🌐 Logs

方法	路径	描述
GET	/api/logs	列出日志
GET	/api/logs/:runId	按运行 ID 获取日志

查询参数

🌐 Query parameters

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

遥测

🌐 Telemetry

方法	路径	描述
GET	/api/telemetry/traces	列出跟踪
GET	/api/telemetry/traces/:traceId	获取跟踪
GET	/api/telemetry/traces/:traceId/spans	获取跟踪跨度

常用查询参数

🌐 Common query parameters

分页

🌐 Pagination

大多数列表端点支持：

🌐 Most list endpoints support:

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

过滤

🌐 Filtering

工作流运行支持：

🌐 Workflow runs support:

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

错误响应

🌐 Error responses

所有路由都以这种格式返回错误：

🌐 All routes return errors in this format:

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

常见状态码：

🌐 Common status codes:

代码	含义
400	错误请求 - 参数无效
401	未授权 - 缺少/无效的认证
403	禁止访问 - 权限不足
404	未找到 - 资源不存在
500	服务器内部错误

相关

🌐 Related

• createRoute() - 创建自定义路由
• 服务器适配器 - 使用适配器