LangChain

Scope-enforced tools and automatic audit logging for LangChain agents.

Install

npm install @grantex/langchain @grantex/sdk @langchain/core

Scope-Enforced Tools

Wrap any tool function with createGrantexTool to enforce Grantex scope authorization before execution:

import { createGrantexTool } from '@grantex/langchain';

const tool = createGrantexTool({
  name: 'read_calendar',
  description: 'Read upcoming calendar events',
  grantToken,                     // JWT from Grantex token exchange
  requiredScope: 'calendar:read', // must be in token's scp claim
  func: async (input) => {
    return JSON.stringify(await getCalendarEvents(input));
  },
});

// Use with any LangChain agent
const agent = createToolCallingAgent({ llm, tools: [tool], prompt });

The scope check is offline — it reads the scp claim from the JWT directly, no network call needed. If the token doesn’t include the required scope, the tool throws before your function runs.

Audit Logging

Attach GrantexAuditHandler as a LangChain callback to automatically log every tool invocation to the Grantex audit trail:

import { Grantex } from '@grantex/sdk';
import { GrantexAuditHandler } from '@grantex/langchain';

const client = new Grantex({ apiKey: process.env.GRANTEX_API_KEY });

const auditHandler = new GrantexAuditHandler({
  client,
  agentId: 'ag_01ABC...',
  grantToken,
});

const result = await agentExecutor.invoke(
  { input: 'What meetings do I have today?' },
  { callbacks: [auditHandler] },
);

Each tool call logs:

• tool:<toolName> with status: 'success' on success
• tool:error with status: 'failure' on error

API Reference

createGrantexTool(options)

Creates a LangChain DynamicTool with Grantex scope enforcement.

Option	Type	Description
name	string	Tool name shown to the LLM
description	string	Tool description shown to the LLM
grantToken	string	Grantex JWT from token exchange
requiredScope	string	Scope required to invoke this tool
func	(input: string) => Promise<string>	Tool implementation

GrantexAuditHandler

LangChain callback handler that writes tool invocations to the Grantex audit trail.

Option	Type	Description
client	Grantex	Authenticated SDK client
agentId	string	Agent ID for audit attribution
grantToken	string	JWT (grant ID extracted from grnt or jti claim)

Requirements

• Node.js 18+
• @grantex/sdk >= 0.1.0
• @langchain/core >= 0.3.0