@agentronics/react

React adapter for the Agentronics SDK — <AgentronicsProvider>, useAgentronics() and useAgentContext() to authenticate agents operating your pages.

Version: 0.1.6

Next.js

Two pieces: middleware authenticates every request (signed agents, API agents, crawlers), and the provider authenticates agents operating your pages. Start with the middleware.

1. Install

npm install @agentronics/sdk

2. Middleware

// middleware.ts
import { agentronicsMiddleware } from '@agentronics/sdk/next'
import { staticKeyVerifier } from '@agentronics/sdk/server'

export default agentronicsMiddleware({
  apiKey: { verify: staticKeyVerifier(JSON.parse(process.env.AGENT_KEYS ?? '{}')) },
})

export const config = {
  matcher: ['/((?!_next|.*\\..*).*)'],
  runtime: 'nodejs', // needed for crawler reverse-DNS checks
}

Every request continues to your app — verified agents with their identity attached, everything else exactly as before. Agentronics never blocks.

Already using Clerk (or another auth middleware)?

Compose them — run agent auth first, then your user auth:

// middleware.ts
import { clerkMiddleware } from '@clerk/nextjs/server'
import { NextResponse, type NextRequest } from 'next/server'
import { createAgentAuthHandler } from '@agentronics/sdk/server'

const agentAuth = createAgentAuthHandler()

export default clerkMiddleware(async (auth, req: NextRequest) => {
  const out = await agentAuth(req)
  return NextResponse.next({ request: { headers: out.headers } })
})

3. Use the verified agent

In route handlers and server components:

import { headers } from 'next/headers'
import { readAgentHeaders } from '@agentronics/sdk/server'

const agent = readAgentHeaders(await headers())
// { status: 'verified' | 'unverified' | 'none', id, name, vendor, method }

These headers are only trustworthy on routes behind the middleware — it strips any forged x-agentronics-* header before setting them.

4. In-page agents (optional)

To authenticate WebMCP clients and browser agents operating your pages, mount the provider:

npm install @agentronics/react

// app/agentronics-provider.tsx
'use client'
import type { ReactNode } from 'react'
import { AgentronicsProvider } from '@agentronics/react'

export function AgentronicsProviderRoot({ children }: { children: ReactNode }) {
  return (
    <AgentronicsProvider publishableKey={process.env.NEXT_PUBLIC_AGENTRONICS_KEY!} siteId="my-site">
      {children}
    </AgentronicsProvider>
  )
}

Wrap your root layout with it, then use useAgentronics() to reach the client (client.detect(), client.authenticate()). See WebMCP & browser agents.

5. Send auth logs to the console

import { agentronicsMiddleware } from '@agentronics/sdk/next'
import { toTraceEvent } from '@agentronics/sdk/server'

export default agentronicsMiddleware({
  onResult: ({ result, request }) => {
    const event = toTraceEvent(result, { siteId: 'my-site', request })
    if (event) queueForExport(event) // see "Stream auth events to the console"
  },
})

onResult never delays or affects the request. See Stream auth events to the console.

Vite + React

A single-page app only sees agents that run it, so this guide covers in-page agents. Put the server middleware in front of your API as well to authenticate everything else.

1. Install

npm install @agentronics/sdk @agentronics/react

2. Mount the provider

// src/main.tsx
import { createRoot } from 'react-dom/client'
import { AgentronicsProvider } from '@agentronics/react'
import App from './App'

createRoot(document.getElementById('root')!).render(
  <AgentronicsProvider publishableKey={import.meta.env.VITE_AGENTRONICS_KEY} siteId="my-app">
    <App />
  </AgentronicsProvider>
)

Use a publishable key (agtx_pk_…). A secret key throws at start-up.

3. React to the agent

import { useAgentContext } from '@agentronics/react'

export function AgentBanner() {
  const { identity } = useAgentContext()
  if (!identity) return null
  return identity.trust === 'verified' || identity.trust === 'linked'
    ? <p>Signed in as {identity.vendor}</p>
    : <p>An unverified agent is using this page.</p>
}

useAgentContext() re-renders on detect, declare, authenticate and clear.

4. Authenticate a credential

import { useAgentronics } from '@agentronics/react'

const client = useAgentronics()
await client.authenticate({ extensionToken: tokenFromYourAgentExtension })

Credentials are verified through the auth.verifyToken hook — see WebMCP & browser agents.

Bundle impact

The full SDK is ~25 KB (brotli). If you only need WebMCP detection, import from @agentronics/sdk/lite (≤ 8 KB).

Links

• Documentation
• Dashboard
• Changelog

License

MIT — © Agentronics.