@grantex/autogen

@grantex/autogen

AutoGen / OpenAI function-calling integration for the Grantex delegated authorization protocol.

Adds scope-enforced functions, a function registry, and audit logging for any agent using OpenAI-style function calling.

Homepage | Docs | Sign Up Free | GitHub

Install

npm install @grantex/autogen @grantex/sdk

Quick Start

Scope-Enforced Functions

Create OpenAI function-calling tool definitions with built-in Grantex scope checks:

import { createGrantexFunction } from '@grantex/autogen';

const readCalendar = createGrantexFunction({
  name: 'read_calendar',
  description: 'Read upcoming calendar events',
  parameters: {
    type: 'object',
    properties: {
      date: { type: 'string', description: 'Date in YYYY-MM-DD format' },
    },
    required: ['date'],
  },
  grantToken,                     // JWT from Grantex token exchange
  requiredScope: 'calendar:read', // must be in token's scp claim
  func: async (args) => {
    return await getCalendarEvents(args.date);
  },
});

// Pass definition to the LLM
const response = await openai.chat.completions.create({
  model: 'gpt-4',
  tools: [readCalendar.definition],
  messages,
});

// Execute when the LLM selects the tool
const result = await readCalendar.execute({ date: '2026-03-01' });

Function Registry

Use GrantexFunctionRegistry to manage multiple functions and dispatch tool calls by name:

import { createGrantexFunction, GrantexFunctionRegistry } from '@grantex/autogen';

const registry = new GrantexFunctionRegistry();
registry.register(readCalendar);
registry.register(sendEmail);

// Pass all definitions to the LLM
const response = await openai.chat.completions.create({
  tools: registry.definitions,
  messages,
});

// Dispatch the tool call
const toolCall = response.choices[0].message.tool_calls[0];
const result = await registry.execute(toolCall.function.name, JSON.parse(toolCall.function.arguments));

Audit Logging

Wrap any function with withAuditLogging to log every invocation to the Grantex audit trail:

import { Grantex } from '@grantex/sdk';
import { withAuditLogging } from '@grantex/autogen';

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

const audited = withAuditLogging(readCalendar, client, {
  agentId: 'ag_01ABC...',
  grantId: 'grnt_01XYZ...',
});

// Use audited.execute() — logs success/failure automatically

API Reference

createGrantexFunction(options)

Creates a Grantex-authorized function with an OpenAI tool definition and scope-enforced executor.

Option	Type	Description
name	string	Function name (matches ^[a-zA-Z0-9_-]+$)
description	string	Description shown to the LLM
parameters	JsonSchema	JSON Schema for function arguments
grantToken	string	Grantex JWT from token exchange
requiredScope	string	Scope required to invoke this function
func	(args: T) => Promise<unknown>	Function implementation

Returns { definition, execute }.

GrantexFunctionRegistry

Method	Description
register(fn)	Register a function (chainable)
definitions	All registered OpenAI tool definitions
execute(name, args)	Execute a function by name

withAuditLogging(fn, client, options)

Wraps a GrantexFunction with audit logging.

Option	Type	Description
agentId	string	Agent ID for audit attribution
grantId	string	Grant ID for the session

Requirements

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

Links

• Grantex Protocol
• TypeScript SDK
• Spec

Grantex Ecosystem

This package is part of the Grantex ecosystem. See also:

• @grantex/sdk — Core TypeScript SDK
• grantex — Python SDK
• @grantex/langchain — LangChain integration
• @grantex/vercel-ai — Vercel AI SDK integration
• @grantex/mcp — MCP server for Claude Desktop / Cursor / Windsurf

License

Apache 2.0