@agentlair/mastra

AgentLair integration for Mastra — telemetry hooks, AAT verification, and Proof of Principal Authorization (PoPA) enrollment for AI agents.

Zero required runtime dependencies. No @mastra/core version pinning.

Install

npm install @agentlair/mastra
# or
bun add @agentlair/mastra

Quick start

import { createAgentLairPlugin } from '@agentlair/mastra';
import { Agent } from '@mastra/core/agent';

const agentlair = createAgentLairPlugin({
  apiKey: process.env.AGENTLAIR_API_KEY!,  // al_live_...
  agentId: 'my-mastra-agent',
});

const agent = new Agent({ ... });

// Wrap generate calls
agentlair.onGenerateStart({ model: 'gpt-4o', toolCount: 3 });
const result = await agent.generate('Summarise last week's invoices');
agentlair.onGenerateFinish({
  text: result.text,
  finishReason: 'stop',
  usage: result.usage,
});

await agentlair.shutdown(); // flush before process exit

Get your API key at agentlair.dev.

What gets captured

| Hook | AgentLair event | Category | Data | |---|---|---|---| | onGenerateStart | generate_start | session | model, tool count, message count | | onGenerateFinish | generate_finish | session | token usage, finish reason, error | | onToolCallStart | {toolName} | tool | tool name, call ID | | onToolCallFinish | {toolName}_complete | tool | duration, success/failure, error |

Events are batched and flushed every 5 seconds. Buffer auto-flushes at 50 events.

AAT verification

Verify that incoming requests carry a valid AgentLair Agent Authentication Token:

const request = new Request('https://my-service.com/api/run', {
  headers: { Authorization: 'Bearer <agent_aat>' },
});

const token = request.headers.get('Authorization')?.replace('Bearer ', '') ?? '';
const agent = await agentlair.verifyAat(token, {
  audience: 'https://my-service.com',
});

if (!agent) {
  return new Response('Unauthorized', { status: 401 });
}

console.log(`Verified agent: ${agent.name} (${agent.agentId})`);
console.log(`Scopes: ${agent.scopes.join(', ')}`);

verifyAat uses EdDSA/Ed25519 via the Web Crypto API — no external JWT library needed.

PoPA enrollment

Record that a human principal has explicitly delegated authority to an agent:

const enrollment = await agentlair.enrollPoPA({
  principalId: 'user_hakon',
  scopes: ['write:invoices', 'read:accounts'],
  description: 'Authorized to process invoices on behalf of Håkon',
  expiresAt: '2026-06-01T00:00:00Z',
});

console.log(`PoPA enrollment: ${enrollment.enrollmentId}`);

Tool call tracking

Instrument individual tool calls to capture timing and failure rates:

const tools = {
  web_search: async (args) => {
    const callId = crypto.randomUUID();
    agentlair.onToolCallStart({ toolCallId: callId, toolName: 'web_search', args });

    try {
      const result = await doSearch(args.query);
      agentlair.onToolCallFinish({ toolCallId: callId, toolName: 'web_search', result });
      return result;
    } catch (err) {
      agentlair.onToolCallFinish({ toolCallId: callId, toolName: 'web_search', error: err });
      throw err;
    }
  },
};

Configuration

const agentlair = createAgentLairPlugin({
  // Required
  apiKey: 'al_live_...',       // Your AgentLair API key
  agentId: 'my-agent',         // Agent identifier for event attribution

  // Optional
  baseUrl: 'https://agentlair.dev',  // API base URL
  flushInterval: 5000,               // Batch flush interval (ms)
  maxBufferSize: 50,                 // Force-flush threshold (events)
  sessionId: 'custom-session-id',    // Group events by session
  timeout: 3000,                     // Request timeout (ms)
  captureInputs: false,              // Log input metadata (message count)
  captureOutputs: false,             // Log output metadata (response length)
  onError: (err) => console.error(err),  // Error handler (swallowed by default)
});

Standalone vs. upstream PR

This package ships the integration independently of Mastra PR #16032 (@mastra/auth-agentlair). You can adopt AgentLair telemetry today without waiting for the PR to merge.

When @mastra/auth-agentlair lands in the official Mastra release, it will provide deeper framework integration (Mastra Studio UI, native auth provider). This package remains the zero-dependency starting point.

Behavioral trust

Events submitted through this adapter feed AgentLair's trust engine. Your agent's trust profile reflects:

• Consistency of tool usage patterns over time
• Transparency of decision trails
• Reliability under observed conditions

Trust scores are available via the AgentLair API and can gate access to other agents and services.

License

Apache-2.0