서버 개요

Mastra는 Agent, Workflow 및 기타 기능을 API 엔드포인트로 노출하는 HTTP 서버로 실행됩니다. 서버는 요청 라우팅, 미들웨어 실행, 인증 및 스트리밍 응답을 처리합니다.

정보

이 페이지에서는 Mastra 생성자에 전달하는 server 구성 옵션을 다룹니다. 자체 HTTP 서버(Hono, Express 등)로 Mastra를 실행하려면 서버 어댑터를 참조하세요.

서버 기능

• 미들웨어: 인증, 로깅, CORS 또는 요청별 컨텍스트 주입에 대한 요청을 차단합니다.
• 사용자 정의 API 경로: Mastra 인스턴스에 액세스할 수 있는 자체 HTTP 엔드포인트로 서버를 확장합니다.
• 요청 컨텍스트: 런타임 조건에 따라 Agent, Tool 및 Workflow에 요청별 값을 전달합니다.
• 서버 어댑터: 생성된 서버 대신 Express, Hono 또는 자체 HTTP 서버를 사용하여 Mastra를 실행합니다.
• 맞춤형 어댑터: 공식적으로 지원되지 않는 프레임워크용 빌드 어댑터입니다.
• 마스트라 클라이언트 SDK: 브라우저 또는 서버 환경에서 Agent, Workflow 및 Tool을 호출하기 위한 유형이 안전한 클라이언트입니다.
• A2A: A2A Agent 카드, 작업 스트림, 푸시 알림을 통해 Agent를 노출합니다.
• 입증: JWT, Clerk, Supabase, Firebase, Auth0 또는 WorkOS를 사용하여 엔드포인트를 보호합니다.

구성

Mastra 생성자에 server 객체를 전달하여 서버를 구성합니다.

src/mastra/index.ts

import { Mastra } from '@mastra/core'

export const mastra = new Mastra({
  server: {
    port: 3000, // Defaults to PORT env var or 4111
    host: '0.0.0.0', // Defaults to MASTRA_HOST env var or 'localhost'
  },
})

사용 가능한 전체 서버 옵션 목록은 구성 레퍼런스를 참조하세요.

서버 배포

Mastra 서버는 Node.js 호환 환경에 배포할 수 있습니다. Mastra 플랫폼 또는 자체 인프라를 사용하여 프로덕션에 배포하세요. 자세한 방법은 배포 문서를 참조하세요.

서버 아키텍처

Mastra는 기반 HTTP 서버 프레임워크로 Hono를 사용합니다. mastra build를 사용하여 Mastra 애플리케이션을 빌드하면 .mastra 디렉터리에 Hono 기반 HTTP 서버가 생성됩니다. 서버는 다음을 제공합니다.

• 등록된 모든 Agent 및 Workflow에 대한 API 엔드포인트
• 맞춤형 API 경로 및 미들웨어
• 공급자 간 인증
• 런타임 구성을 위한 요청 컨텍스트
• 안전한 응답을 위한 스트림 데이터 수정

REST API

사용 가능한 모든 엔드포인트는 http://localhost:4111/api/openapi.json의 OpenAPI 사양에서 살펴볼 수 있으며, 여기에는 각 엔드포인트와 요청 및 응답 스키마가 자세히 설명되어 있습니다. API를 대화형으로 살펴보려면 http://localhost:4111/swagger-ui의 Swagger UI를 방문하세요. 여기에서 엔드포인트를 살펴보고 브라우저에서 직접 테스트할 수 있습니다.

노트

OpenAPI 및 Swagger 엔드포인트는 프로덕션에서 기본적으로 비활성화됩니다. 활성화하려면 server.build.openAPIDocs와 server.build.swaggerUI를 각각 true로 설정하세요.

OpenAI 응답 API

Mastra는 Mastra Agent를 응답 API로 사용할 수 있는 OpenAI 호환 응답 및 대화 경로를 공개합니다. 이러한 경로는 Mastra Agent, Memory 및 스토리지에 대한 Agent 지원 어댑터이므로 요청은 원시 공급자 프록시로 작동하는 대신 선택한 Mastra Agent를 통해 실행됩니다.

이러한 API는 현재 실험적입니다.

요청을 처리할 Mastra Agent를 선택하려면 agent_id를 사용합니다. 최초 요청은 Agent를 직접 대상으로 하며, 저장된 후속 턴은 previous_response_id를 사용하여 이어갈 수 있습니다. model을 전달해 단일 요청에 한해 Agent에 구성된 Model을 재정의할 수도 있습니다. model을 생략하면 Mastra는 Agent에 이미 구성된 Model을 사용합니다. 응답 경로는 스트리밍, 함수 호출(Tool), previous_response_id를 통한 저장된 대화 이어가기, conversation_id를 통한 대화 스레드, providerOptions를 통한 Provider별 옵션 전달, text.format을 통한 JSON 출력을 지원합니다. 전체 요청 및 응답 규약은 Responses API 레퍼런스와 Conversations API 레퍼런스를 참조하세요. 전체 HTTP 경로 목록은 서버 경로를 참조하세요.

스트림 데이터 수정

스트리밍 Agent 응답 시 HTTP 계층은 시스템 Prompt, Tool 정의, API 키 및 각 청크의 유사한 데이터를 클라이언트에 보내기 전에 수정합니다. 이는 기본적으로 활성화되어 있습니다.

이 동작은 서버 어댑터를 사용할 때만 구성할 수 있습니다. 서버 어댑터에서도 스트림 데이터 수정은 기본적으로 활성화됩니다.

타입스크립트 구성

Mastra에는 최신 Node.js와 호환되는 module 및 moduleResolution 설정이 필요합니다. CommonJS 또는 node 같은 레거시 옵션은 지원되지 않습니다.

tsconfig.json

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ES2022",
    "moduleResolution": "bundler",
    "esModuleInterop": true,
    "forceConsistentCasingInFileNames": true,
    "strict": true,
    "skipLibCheck": true,
    "noEmit": true,
    "outDir": "dist"
  },
  "include": ["src/**/*"]
}

다음 단계

• 추가하다middleware
• 만들다custom API routes
• 추가하다authentication
• 배포서버를 프로덕션으로