Mastra

TypeScript로 AI 에이전트·워크플로우를 만들고 있다면, 에이전트 코드를 바꾸지 않고도 추적·평가를 시작할 수 있어요. Mastra는 TypeScript로 AI 에이전트·워크플로우를 만드는 프레임워크인데, Confident AI는 confident-trace로 Mastra 애플리케이션을 추적합니다. 모든 에이전트 실행이 Observatory에서 agent → model → tool 전체 계층을 가진 트레이스로 나타나죠.

출처: 문서

본문

개요

Mastra는 TypeScript로 AI 에이전트·워크플로우를 만드는 프레임워크입니다. Confident AI는 OpenTelemetry 네이티브 추적 SDK인 confident-trace로 Mastra 애플리케이션을 추적·평가해요 — 에이전트 코드는 바꾸지 않아도 되죠. 모든 에이전트 실행이 Observatory에서 agent → model → tool 전체 계층을 가진 트레이스로 나타나서, 에이전트가 어떤 도구를 골랐고 각 모델 호출이 얼마나 들었는지 볼 수 있고 결과에 eval을 돌릴 수 있어요.

confident-trace는 Mastra를 다시 계측하지 않고 Mastra 자체의 스팬을 다시 내보내기 때문에, Mastra의 네이티브 샘플링·필터·스팬 프로세서가 모두 export 전에 실행됩니다. Mastra 파이프라인이 통과시키는 것이 곧 Confident AI가 받는 것이에요.

Runtime	Requirements	Setup
Python	Not supported	Mastra is a TypeScript framework
TypeScript	Node.js 22+, `@mastra/core >=1.64.0 <2`, `@mastra/observability >=1.17.5 <2`	Call `init()` and launch your entry point with the preload

자동 계측

EU 리전 사용자는 아래처럼 OTEL 엔드포인트를 EU 버전으로 설정하세요.
export CONFIDENT_OTEL_ENDPOINT="https://eu.otel.confident-ai.com/v1/traces"

의존성 설치

Mastra를 추적하려면 @mastra/observability를 설치하세요. 이것은 confident-trace에 포함되어 있지 않아요.

Mastra 프로젝트에 confident-trace를 추가하세요. tsx는 TypeScript 소스를 직접 실행할 때만 필요합니다.

npm install confident-trace '@mastra/core@>=1.64.0 <2' '@mastra/observability@>=1.17.5 <2'
npm install -D tsx

API 키 설정

Confident AI에서 프로젝트 API 키를 받아 에이전트가 쓰는 프로바이더 키와 함께 환경 변수로 설정하세요.

export CONFIDENT_API_KEY="<your-confident-project-key>"
export OPENAI_API_KEY="<your-openai-key>"

추적 초기화

앱이 시작될 때, Mastra를 만들기 전에 init()을 한 번 호출하세요. preload가 각 Mastra 인스턴스에 Confident exporter를 자동으로 붙여 줍니다 — exporter, observability 구성, 래퍼는 필요 없어요.

import { init } from "confident-trace";
import { Mastra } from "@mastra/core";
import { Agent } from "@mastra/core/agent";

const runtime = init();

const assistant = new Agent({
  id: "assistant",
  name: "Assistant",
  instructions: "You are a helpful assistant.",
  model: "openai/gpt-4.1-mini",
});
const mastra = new Mastra({ agents: { assistant }, logger: false });

try {
  const result = await mastra.getAgent("assistant").generate("How do I make the best coffee?");
  console.log(result.text);
} finally {
  await runtime.shutdown();
}

장기 실행 서버에서는 시작 시 init()을 한 번, 정상 종료 시 활성 에이전트 실행·스트림이 끝난 뒤 runtime.shutdown()을 한 번 호출하세요 — 요청마다 하지 마세요. 한 번 초기화를 참고하세요.

애플리케이션 실행

Node가 Mastra를 로드할 때 SDK가 훅할 수 있도록 엔트리포인트 파일을 confident-trace/register preload로 실행하세요. init()은 export를, preload는 계측을 처리합니다 — 둘 다 필요해요.

# Running TypeScript source directly
node --import tsx --import confident-trace/register src/index.ts

# Running compiled JavaScript
node --import confident-trace/register dist/index.js

완료 ✅. Confident AI의 Observatory 안 트레이스 페이지에서 트레이스와 자식 스팬을 볼 수 있어요.

트레이스가 안 보이면, init()이 new Mastra(...) 전에 실행되고 엔트리포인트가 --import confident-trace/register로 실행됐는지 확인하세요. runtime.getInstrumentationStatus()가 Mastra가 훅됐는지 알려 줘요 — not observed는 Mastra가 아직 로드되지 않았다는 뜻입니다. 자세한 건 트러블슈팅을 참고하세요.

무엇이 포착되나

Mastra 에이전트 실행은 원래 계층이 그대로 보존된 채 내보내져서, 에이전트·워크플로우에서 모델·도구 호출까지의 완전한 경로를 따라갈 수 있어요.

에이전트·워크플로우 실행 — 작업 이름, 타이밍, 상태, 단계 사이의 부모-자식 관계
모델 호출 — 모델 상세, 메시지, 완료 사유, 토큰 사용량
도구 호출 — 도구 이름과 그 입출력
트레이스 상세 — 루트 작업의 이름, 태그, 메타데이터, 입출력
오류 — 실패한 작업이 오류 상태를 유지해서 트레이스에서 실패가 드러나게 함

포착되는 입력, 출력, 메시지는 콘텐츠 정책을 따릅니다.

이 통합은 트레이싱 데이터를 내보냅니다. Mastra 로그, 메트릭, 점수, 피드백은 포함되지 않아요.

트레이스 스팬 속성 설정

호출이 시작되기 전에 아는 속성을 추가하려면 트레이스 컨텍스트를 사용하세요. 추가 스팬은 만들지 않아요. agent.generate()가 시작한 트레이스가 태그, 메타데이터, 사용자 ID, 고객 ID를 상속받습니다.

import { init, traceContext } from "confident-trace";

init();

const agent = mastra.getAgent("assistant");
const result = await traceContext(
  {
    tags: ["support"],
    metadata: { release: "2026-09" },
    userId: "user-42",
    customerId: "customer-7",
  },
  () => agent.generate("Explain OpenTelemetry in one sentence."),
);

각 ID와 함께 선택적 표시 이름을 설정하려면 사용자와 고객을, 지원되는 모든 트레이스 속성과 갱신 동작은 트레이스 컨텍스트를 참고하세요.

다중 턴 계측

Mastra 엔트리포인트 호출 하나가 이미 하나의 대화 턴일 때는 turn()이 필요 없어요 — 통합이 그 턴의 트레이스를 자동으로 만들어 주거든요. 경계를 직접 정의하고 싶을 때, 예를 들어 두 번의 연속 Mastra 호출을 하나의 턴으로 묶고 싶을 때 turn()을 사용하세요. 이후 턴에서 같은 스레드 ID를 재사용해 하나의 대화로 묶으면 돼요.

import { init, turn } from "confident-trace";

init();

const agent = mastra.getAgent("assistant");
const answer = await turn({ name: "support-turn", threadId: "chat-42" }, async () => {
  const context = await agent.generate("Find the relevant account details.");
  return agent.generate(`Summarize these details: ${context.text}`);
});

스레드 입출력, 턴 ID, 사용자 ID는 스레드를 참고하세요.

Mastra 계측 비활성화

특정 통합만 활성화하려면 init()에 통합 식별자 목록을 전달하세요. Mastra의 식별자는 TypeScript에서 "mastra"이고, 이를 빼면 이 통합이 비활성화돼요. 빈 목록은 모든 자동 계측을 비활성화합니다.

import { init } from "confident-trace";
init({ instrumentations: [] });
// Use ["mastra"] to opt in; omit "mastra" to disable it.

이렇게 하면 Confident AI의 자동 계측이 꺼지고, 초기화 이후의 호출은 이 통합으로 계측되지 않아요.

다음 단계

Mastra 에이전트를 추적했으니, 더 깊이 들어가 볼까요.

다중 턴 앱 계측

공유 threadId로 에이전트 실행을 스레드로 묶어, 전체 대화를 보고 평가하세요.

Online Evals

트레이스·스팬·스레드가 Confident AI로 수집되는 실시간으로 평가를 돌려 AI 품질을 모니터링하세요.

더 알아보기

Threads — 에이전트 실행을 스레드로 묶어 평가
Online Evals — 수집되는 트레이스·스팬·스레드를 실시간으로 평가