跳到主要内容

Server 路由

调用 server.init() 时，服务器适配器会注册这些路由。若已配置，所有路由都会添加 prefix 选项指定的前缀。

Agent
Agent的直接链接

方法路径描述
GET/api/agents列出所有 Agent
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 的查询参数
获取 Agent 的查询参数的直接链接

GET /api/agents/:agentId 接受可选查询参数，用于控制将哪个已存储的配置版本作为覆盖项应用于代码定义的 Agent：

参数类型默认值描述
status'draft' | 'published''published'要解析的已存储版本。draft 返回最新版本，published 返回活跃版本。
versionIdstring无要解析的特定版本 ID。其优先级高于 status。
# 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

生成请求体
生成请求体的直接链接

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

生成响应
生成响应的直接链接

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

Agent 消息路由
Agent 消息路由的直接链接

使用 POST /api/agents/:agentId/send-message 向活跃的 Agent 循环发送用户消息，或唤醒空闲线程。若应在 Mastra 启动后续运行前完成当前运行，请使用 POST /api/agents/:agentId/queue-message。

两个路由均接受相同的请求体：

{
  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 仅适用于以线程为目标的请求，不适用于以运行为目标的请求。

发送消息
发送消息的直接链接

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"
  }'

将消息加入队列
将消息加入队列的直接链接

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"
  }'

两个路由均返回：

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

订阅 Tool 批准路由
订阅 Tool 批准路由的直接链接

当客户端已有活跃的线程订阅时，使用 POST /api/agents/:agentId/send-tool-approval。该路由会恢复运行并返回 JSON 确认信息。恢复后的流分块会通过 POST /api/agents/:agentId/threads/subscribe 传送。

该路由接受以下请求体：

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

该路由返回：

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

Workflow
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 运行数量。该记录以 Mastra 配置中的 Workflow 注册表键为键，服务器可能会将响应缓存数秒：

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

动态 Workflow
动态 Workflow的直接链接

动态 Workflow 定义（beta）是以 JSON 表示的 Workflow，通过 workflowDefinitions 存储域持久化，并在运行中的实例上实时注册。请参阅动态 Workflow。

方法路径描述
GET/api/stored/workflows列出动态 Workflow 定义，可按 status 和 authorId 筛选
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 路由执行。

创建运行请求体
创建运行请求体的直接链接

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

/start-async 的请求体
request-body-for-start-async的直接链接

{
  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 的请求体
流式传输 Workflow 的请求体的直接链接

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

恢复请求体
恢复请求体的直接链接

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

Tool
Tool的直接链接

方法路径描述
GET/api/tools列出所有 Tool
GET/api/tools/:toolId按 ID 获取 Tool
POST/api/tools/:toolId/execute执行 Tool

执行 Tool 请求体
执行 Tool 请求体的直接链接

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

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

创建线程请求体
创建线程请求体的直接链接

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

克隆线程请求体
克隆线程请求体的直接链接

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

克隆线程响应
克隆线程响应的直接链接

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

Vector
Vector的直接链接

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

插入或更新请求体
插入或更新请求体的直接链接

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

查询请求体
查询请求体的直接链接

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

MCP
MCP的直接链接

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

Responses API
Responses API的直接链接

方法路径描述
POST/api/v1/responses通过兼容 OpenAI 的 Responses API 路由创建响应
GET/api/v1/responses/:responseId检索已存储的响应
DELETE/api/v1/responses/:responseId删除已存储的响应

有关完整的请求和响应契约，请参阅 Responses API 参考。

Conversations API
Conversations API的直接链接

方法路径描述
POST/api/v1/conversations创建会话
GET/api/v1/conversations/:conversationId检索会话
DELETE/api/v1/conversations/:conversationId删除会话
GET/api/v1/conversations/:conversationId/items列出会话的已存储项目

有关完整的请求和响应契约，请参阅 Conversations API 参考。

日志
日志的直接链接

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

查询参数
查询参数的直接链接

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

Telemetry
Telemetry的直接链接

方法路径描述
GET/api/telemetry/traces列出 Trace
GET/api/telemetry/traces/:traceId获取 Trace
GET/api/telemetry/traces/:traceId/spans获取 Trace span

常用查询参数
常用查询参数的直接链接

分页
分页的直接链接

大多数列表端点支持：

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

筛选
筛选的直接链接

Workflow 运行支持：

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

错误响应
错误响应的直接链接

所有路由均以此格式返回错误：

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

常见状态码：

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