tanstack

The TanStack adapter integrates agents with TanStack Start for file-based routing and React UI support.

Installation

bun add @regent/tanstack @tanstack/react-start

Basic Usage

import { createAgent } from '@regent/core';
import { http } from '@regent/http';
import { createTanStackRuntime } from '@regent/tanstack';

const agent = await createAgent({
  name: 'my-agent',
  version: '1.0.0',
})
  .use(http())
  .build();

const { runtime, handlers } = await createTanStackRuntime(agent);

API Reference

createTanStackRuntime()

Creates a TanStack-compatible runtime from an AgentRuntime.

async function createTanStackRuntime(
  runtime: AgentRuntime
): Promise<TanStackRuntime>

TanStackRuntime

type TanStackRuntime = {
  runtime: AgentRuntime;
  handlers: TanStackHandlers;
};

Available Handlers

type TanStackHandlers = {
  health: TanStackRequestHandler;
  entrypoints: TanStackRequestHandler;
  manifest: TanStackRequestHandler;
  favicon: TanStackRequestHandler;
  landing?: TanStackRequestHandler;
  invoke: TanStackRouteHandler<{ key: string }>;
  stream: TanStackRouteHandler<{ key: string }>;
  tasks: TanStackRequestHandler;
  getTask: TanStackRouteHandler<{ taskId: string }>;
  listTasks: TanStackRequestHandler;
  cancelTask: TanStackRouteHandler<{ taskId: string }>;
  subscribeTask: TanStackRouteHandler<{ taskId: string }>;
};

Route Setup

Route Structure

/api/agent/health                      - Health check
/api/agent/entrypoints                 - List entrypoints
/api/agent/manifest                    - Agent manifest
/api/agent/entrypoints/{key}/invoke    - Invoke entrypoint
/api/agent/entrypoints/{key}/stream    - Stream entrypoint
/api/agent/tasks                       - Task management
/api/agent/tasks/{taskId}              - Get task
/api/agent/tasks/{taskId}/subscribe    - Subscribe (SSE)

File-Based Route Example

// app/api/agent/health.ts
import { createServerFn } from '@tanstack/react-start';
import { tanstackRuntime } from '../runtime';

export const getHealth = createServerFn()(async () => {
  return tanstackRuntime.handlers.health({
    request: new Request('http://localhost/health'),
  });
});

Payment Middleware

createTanStackPaywall()

Creates payment middleware for agent entrypoints.

function createTanStackPaywall(
  options: CreateTanStackPaywallOptions
): TanStackPaywall

Options

type CreateTanStackPaywallOptions = {
  runtime: RuntimeLike;
  basePath?: string;           // Default: '/api/agent'
  payments?: PaymentsConfig;
  facilitator?: FacilitatorConfig;
  paywall?: PaywallConfig;
};

Return Value

type TanStackPaywall = {
  invoke?: TanStackRequestMiddleware;
  stream?: TanStackRequestMiddleware;
};

Usage

import { createTanStackPaywall } from '@regent/tanstack';

const paywall = createTanStackPaywall({
  runtime: agent,
  basePath: '/api/agent',
  payments: {
    payTo: '0x...',
    facilitatorUrl: 'https://facilitator.example.com',
    network: 'base-sepolia',
  },
});

// Apply in route handlers
if (paywall.invoke) {
  // Use middleware
}

paymentMiddleware()

Low-level payment middleware:

function paymentMiddleware(
  payTo: Address | SolanaAddress,
  routes: RoutesConfig,
  facilitator?: FacilitatorConfig,
  paywall?: PaywallConfig
): TanStackRequestMiddleware

Supported Networks

EVM Networks

• ethereum, base, optimism, arbitrum, polygon

• ethereum-sepolia, base-sepolia, optimism-sepolia, arbitrum-sepolia, polygon-amoy

Solana Networks

• solana, solana-devnet

Integration Example

// app/api/runtime.ts
import { createAgent } from '@regent/core';
import { http } from '@regent/http';
import { createTanStackRuntime, createTanStackPaywall } from '@regent/tanstack';

export const agent = await createAgent({
  name: 'my-agent',
  version: '1.0.0',
})
  .use(http())
  .addEntrypoint({
    key: 'process',
    input: z.object({ prompt: z.string() }),
    handler: async ({ input }) => ({
      output: { result: `Processed: ${input.prompt}` },
    }),
  })
  .build();

export const tanstackRuntime = await createTanStackRuntime(agent);
export const paywall = createTanStackPaywall({ runtime: agent });

// app/api/agent/entrypoints/$key/invoke.ts
import { createServerFn } from '@tanstack/react-start';
import { tanstackRuntime, paywall } from '../../runtime';

export const invokeHandler = createServerFn({ method: 'POST' })(
  async (request: Request, { params }) => {
    return tanstackRuntime.handlers.invoke({
      request,
      params: { key: params.key },
    });
  }
);

Exports

// Runtime
export { createTanStackRuntime, createTanStackHandlers } from '@regent/tanstack';

// Paywall
export { createTanStackPaywall, paymentMiddleware } from '@regent/tanstack';

// Types
export type {
  TanStackRuntime,
  TanStackHandlers,
  TanStackRequestHandler,
  TanStackRouteHandler,
  TanStackPaywall,
  CreateTanStackPaywallOptions,
} from '@regent/tanstack';