# Mastra

This guide shows how to integrate the [Scorable SDK](https://github.com/root-signals/rs-sdk) as a [custom scorer](https://mastra.ai/docs/scorers/custom-scorers) for evaluating your Mastra agents.

## Setting Up the Scorable Client

```typescript
// npm install @root-signals/scorable
import { Scorable } from "@root-signals/scorable";

const scorableClient = new Scorable({
  apiKey: process.env.SCORABLE_API_KEY!,
});
```

## Creating a Scorable Scorer

Use `createScorer` from `mastra` to define a custom scorer that calls Scorable's evaluator API:

```typescript
import { createScorer } from "@mastra/core/scores";
import { Scorable } from "@root-signals/scorable";

const scorableClient = new Scorable({
  apiKey: process.env.SCORABLE_API_KEY!,
});

export const helpfulnessScorer = createScorer({
  name: "Helpfulness",
  description: "Helpfulness of the assistant's response",
})
  .preprocess(({ run }) => {
    const userText = (run.input?.inputMessages?.[0]?.content as string) || "";
    const assistantText = (run.output?.[0]?.content as string) || "";
    return { userText, assistantText };
  })
  .analyze(async ({ results }) => {
    const response = results.preprocessStepResult.assistantText;
    const request = results.preprocessStepResult.userText;
    const scoreResult = await scorableClient.evaluators.executeByName(
      "Helpfulness",
      {
        request: request,
        response: response,
      }
    );
    return scoreResult;
  })
  .generateScore(({ results }) => {
    const scoreResult = results.analyzeStepResult
    return scoreResult.score ?? 0;
  })
  .generateReason(({ results }) => {
    return results.analyzeStepResult?.justification ?? "N/A";
  });
```

## Integrating with an Agent

Attach the scorer to your agent configuration:

```typescript
import { Agent } from "@mastra/core/agent";
import { weatherTool } from "../tools/weather-tool";
import { helpfulnessScorer } from "../scorers/weather-scorer";

export const weatherAgent = new Agent({
  name: "Weather Agent",
  instructions: `
      You are a helpful weather assistant that provides accurate weather information.
      Your primary function is to help users get weather details for specific locations.
  `,
  model: "openai/gpt-5.2",
  tools: { weatherTool },
  scorers: {
    helpfulness: {
      scorer: helpfulnessScorer,
      sampling: {
        type: "ratio",
        rate: 1,
      },
    },
  },
});
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.scorable.ai/integrations/mastra.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.