Parlanteer

Customer-service agent presets and focused-context tooling for Mastra.

Parlanteer helps teams spawn production-shaped support agents faster in Mastra. It gives you a structured customer-service corpus, focused-context matching, relationship resolution, mock support tools, and a thin agent factory that returns a normal Mastra Agent.

Mastra remains the runtime. Parlanteer is the support-agent layer on top.

Why Parlanteer

Mastra already gives you strong agent infrastructure: model routing, tools, memory, storage, workflows, streaming, telemetry, and deployment. Parlanteer does not try to replace any of that.

Parlanteer focuses on the repetitive customer-service setup around the agent:

• support policy and behavioral guidance
• glossary terms and service language
• support journeys such as order status, returns, and escalation
• canned responses
• tool associations
• focused context for each turn
• tool coverage checks before production rollout

The result is a Mastra-native way to move from "blank agent" to "usable support agent" without building a new runtime.

Status

Parlanteer is currently an early production-shaped SDK with a mock customer-service preset. The preset is realistic enough for local development and product shaping, but the included tools are mock implementations.

For production use, replace the mock tools with your own Mastra tools and let Mastra own persistence, memory, storage, traces, and deployment.

Install

Inside this repository:

pnpm install

Add Parlanteer to a Mastra project:

pnpm add parlanteer @mastra/core

Mastra apps should continue to install and configure their own Mastra runtime, model provider packages, storage providers, and deployment setup.

Parlanteer follows the installed Mastra runtime requirement and expects Node >=22.13.0.

Quick Start

Create a support agent from the customer-service preset:

import { parlanteerPresets } from "parlanteer";

export const supportAgent = parlanteerPresets.customerService.createAgent({
  id: "support-agent",
  name: "Support Agent",
  model: "openrouter/openai/gpt-5",
  instructions: "Represent the brand clearly and keep answers concise.",
});

Register it like any other Mastra agent:

import { Mastra } from "@mastra/core";
import { supportAgent } from "./agents/support-agent";

export const mastra = new Mastra({
  agents: {
    supportAgent,
  },
});

The returned value is a normal Mastra Agent. You can still use Mastra memory, storage, tools, workflows, processors, streams, and deployment around it.

Bring Real Tools

The mock preset includes example tools for order lookup, return creation, and ticket escalation. In a real support stack, provide production Mastra tools with the same names:

import { createParlanteerAgent, parlanteerPresets } from "parlanteer";
import { createReturn, escalateTicket, lookupOrder } from "./tools";

export const supportAgent = createParlanteerAgent({
  id: "support-agent",
  name: "Support Agent",
  model: "openrouter/openai/gpt-5",
  corpus: parlanteerPresets.customerService.corpus,
  tools: {
    lookupOrder,
    createReturn,
    escalateTicket,
  },
  parlanteer: {
    mode: "both",
    toolCoverage: "error",
  },
});

toolCoverage: "error" checks that every tool referenced by the corpus is present in the Mastra tools map.

Customize The Corpus

Use the preset as a base, then add brand-specific support policy:

import { parlanteerPresets } from "parlanteer";

const corpus = parlanteerPresets.customerService.createCorpus({
  profile: {
    name: "Acme Support",
    metadata: {
      brand: "Acme",
      supportTier: "consumer",
    },
  },
  extend: {
    guidelines: [
      {
        id: "guid_acme_voice",
        action: "use Acme's warm, direct support voice",
        matcher: "always",
        criticality: "medium",
        priority: 20,
        track: true,
        enabled: true,
        labels: ["brand"],
        tags: ["brand"],
        metadata: {},
      },
    ],
  },
});

Use extend when you want preset defaults plus your own policy. Use replace when you want to own a full corpus bucket such as guidelines, tools, or toolAssociations.

Load Policy From Your App

Parlanteer accepts either a static corpus or a corpus provider function. That lets your application keep ownership of policy loading:

import { createParlanteerAgent } from "parlanteer";
import { loadSupportCorpus } from "./support-policy";
import { tools } from "./tools";

export const supportAgent = createParlanteerAgent({
  id: "support-agent",
  name: "Support Agent",
  model: "openrouter/openai/gpt-5",
  corpus: async () => loadSupportCorpus(),
  tools,
});

The loader can read from files, a CMS, Mastra storage, Postgres, or another application-owned source. Parlanteer does not create database tables or own conversation state.

Use Mastra Memory And Storage

Configure durable state through Mastra:

import { Mastra } from "@mastra/core";

export const mastra = new Mastra({
  storage,
  agents: {
    supportAgent,
  },
});

When calling the agent directly, use Mastra memory identifiers:

await supportAgent.generate("Where is my order?", {
  memory: {
    thread: "conversation-123",
    resource: "customer-456",
  },
});

Parlanteer should not add a separate session store. Postgres, LibSQL, MongoDB, Redis, and other durable stores should remain Mastra storage providers or application-owned infrastructure.

What Parlanteer Adds

• createParlanteerAgent, a thin factory that returns a Mastra Agent
• parlanteerPresets.customerService, a mock but production-shaped support preset
• focused-context matching for each turn
• relationship resolution for policy dependencies and exclusions
• automatic context injection through a Mastra input processor
• an optional focusContext inspection tool
• tool coverage checks for corpus/tool mismatches
• pure helpers for custom integrations

What Mastra Owns

• agent runtime
• model routing
• tool execution
• memory
• storage
• threads and resources
• workflows
• streaming
• telemetry
• deployment

Parlanteer works best when it stays small: support-agent presets, policy structure, focused context, and Mastra adapters.

Repository Layout

src/parlanteer/
  agent.ts                  thin Mastra agent factory
  domain.ts                 corpus schemas and types
  matching.ts               focused-context evaluator
  relationships.ts          policy relationship resolver
  adapters/mastra.ts        Mastra tool/context adapter
  presets/customer-service.ts
                             mock support preset and mock tools

src/mastra/
  index.ts                  local Mastra app registration
  agents/parlanteer-agent.ts
                             demo agent using the preset
  tools/focus-context-tool.ts
                             optional inspection tool example

docs/
  architecture.md           ownership boundary and runtime shape
  quickstart.md             fuller setup walkthrough
  api.md                    public SDK surface
  corpus-authoring.md       support policy authoring guide
  recipes.md                real integration paths
  production-readiness.md   rollout checklist
  validation.md             validation commands

The local parlant/ and parlant-chat-react/ directories, when present, are ignored source-reference material only. They are not connected packages and are not part of the runtime.

Development

pnpm dev
pnpm check
pnpm build:pkg
pnpm build
pnpm pack:dry-run

pnpm dev starts Mastra Studio for local testing. pnpm check runs TypeScript and Mastra linting. pnpm build:pkg emits the npm package into dist/. pnpm build runs the Mastra build. pnpm pack:dry-run shows the exact npm tarball contents before publication.

Before committing:

pnpm check
pnpm build:pkg
pnpm build
pnpm pack:dry-run
git status --short --ignored

Expected ignored local/runtime folders include .env, .mastra/, .pnpm-store/, node_modules/, parlant/, and parlant-chat-react/.

Documentation

• Architecture
• Quickstart
• API Reference
• Corpus Authoring
• Integration Recipes
• Production Readiness
• Validation

Publishing

The package is configured for public npm publishing as parlanteer.

Before publishing, validate the package:

pnpm check
pnpm build:pkg
pnpm pack:dry-run

Then log in and publish:

npm login --cache ./.npm-cache
npm publish --access public --cache ./.npm-cache

If npm asks for a two-factor code:

npm publish --access public --cache ./.npm-cache --otp 123456

The local .npm-cache/ path avoids relying on global npm cache permissions.

Relationship To Parlant

Parlanteer is Parlant-inspired, but it is not a vendored Parlant runtime and it does not connect directly to the local Parlant source references. The goal is to bring structured support-agent behavior into Mastra as a small, composable wrapper.

Credit and thanks go to emcie-co/parlant and emcie-co/parlant-chat-react. See ACKNOWLEDGEMENTS.md and NOTICE for attribution details.