@mastractl/agent

AgentSpec types, declarative tool/MCP wiring, and BYO Mastra Agent adapter for mastractl.

⚠ Alpha — API surface may change between 0.7.x releases.

Install

npm install @mastractl/agent

What's in here

• AgentSpec / AgentSpecSchema — declarative agent definition: model, role, instructions, customTools[], mcpClients[], budget.
• MCPClientSpec — transport variants: http, stdio, managed (resolves from the company MCP registry at hire-time).
• CustomToolSpec — HTTP tool definition with optional bearer auth and approval gate.
• createMastractlAgentAdapter — wrap a fully-custom @mastra/core Agent with tenancy enforcement and register it via the mastractl API.

Usage — declarative AgentSpec

import type { AgentSpec } from "@mastractl/agent";

const spec: AgentSpec = {
  id: "triage-bot",
  name: "Triage Bot",
  role: "Triage incoming GitHub issues against Linear",
  instructions: "...",
  model: { provider: "openrouter", id: "anthropic/claude-haiku-4-5" },
  budget: { monthlyCents: 500 },
  mcpClients: [
    { name: "linear", transport: { kind: "managed" } },
  ],
};

Usage — BYO Mastra Agent

import { createMastractlAgentAdapter } from "@mastractl/agent";
import { Agent } from "@mastra/core/agent";

const myAgent = new Agent({ /* your custom config */ });
const adapter = createMastractlAgentAdapter(myAgent, {
  id: "my-custom-agent",
  companyId: "<cid>",
});
// register via @mastractl/client
await mastractl.agents.registerCustom("<cid>", { config: adapter.config, agentRef: { module: "./my-agent.js" } });

Part of the mastractl SDK

| Package | Purpose | |---|---| | @mastractl/shared | Error primitives | | @mastractl/agent | AgentSpec types + BYO adapter (this package) | | @mastractl/client | Typed REST client |

Requires a running mastractl server.