@daemoniorum/agent-data

AI agent data extraction library for React applications. Extract structured data from your React components without browser automation (Playwright, Puppeteer).

The Problem

AI agents typically need to:

1. Launch headless browsers (slow, ~2-5s startup)
2. Render full pages to extract content (resource-intensive)
3. Parse HTML/DOM structures (fragile, breaks on UI changes)

The Solution

Components self-register their data via a simple hook. AI agents query this data through a REST API - no browser required.

React Components → useAgentData → Registry → API → AI Agent

Installation

npm install @daemoniorum/agent-data
# or
pnpm add @daemoniorum/agent-data

Quick Start

1. Wrap Your App

import { AgentDataProvider } from '@daemoniorum/agent-data/react'

function App() {
  return (
    <AgentDataProvider>
      <YourApp />
    </AgentDataProvider>
  )
}

2. Register Data in Components

import { useAgentData } from '@daemoniorum/agent-data/react'
import { z } from 'zod'

const TaskSchema = z.object({
  id: z.string(),
  title: z.string(),
  status: z.enum(['pending', 'running', 'completed']),
})

function TaskList({ tasks }) {
  useAgentData({
    id: 'tasks',
    data: tasks,
    zodSchema: z.array(TaskSchema),
    description: 'Active task list',
  })

  return <ul>{tasks.map(t => <TaskItem key={t.id} task={t} />)}</ul>
}

3. Add Server Middleware

import express from 'express'
import { createAgentDataMiddleware } from '@daemoniorum/agent-data/server'
import { globalRegistry } from '@daemoniorum/agent-data/react'

const app = express()

app.use(createAgentDataMiddleware({
  registry: globalRegistry,
  apiKeyValidator: (key) => key === process.env.AGENT_API_KEY,
}))

4. Query from AI Agent

import { AgentDataClient } from '@daemoniorum/agent-data/client'

const client = new AgentDataClient({
  baseUrl: 'https://your-app.com',
  apiKey: process.env.AGENT_API_KEY,
})

// Discover available data
const { sources } = await client.discover()

// Query specific data
const { data } = await client.query({ sourceId: 'tasks' })

// Subscribe to updates
client.subscribe({
  sourceId: 'tasks',
  onUpdate: (update) => console.log('Tasks updated:', update),
})

API Endpoints

| Endpoint | Method | Description | |----------|--------|-------------| | /api/agent-data/discover | GET | List available data sources | | /api/agent-data/query | GET | Query a data source | | /api/agent-data/batch-query | POST | Query multiple sources | | /api/agent-data/schema/:id | GET | Get schema for a source | | /api/agent-data/source/:id | HEAD | Check if source exists | | /api/agent-data/subscribe/:id | SSE | Real-time updates |

Features

| Feature | Description | |---------|-------------| | Zero Browser | AI agents query data via REST API | | Type-Safe | Zod schemas with auto-conversion to JSON Schema | | Real-Time | Server-Sent Events for live updates | | Discoverable | /discover endpoint lists all sources | | Opt-In | Components choose what to expose | | Secure | API key auth, scope-based access control |

Modules

• @daemoniorum/agent-data/react - React hooks and provider
• @daemoniorum/agent-data/server - Express/Fastify middleware
• @daemoniorum/agent-data/client - Agent SDK
• @daemoniorum/agent-data/schema - Schema utilities

Schema Definition

Use Zod schemas for type safety and automatic JSON Schema generation:

import { defineSchema, CommonSchemas } from '@daemoniorum/agent-data/schema'
import { z } from 'zod'

// Define custom schema
const ProductSchema = defineSchema(z.object({
  id: z.string().uuid(),
  name: z.string().min(1).max(200),
  price: z.number().positive(),
  inStock: z.boolean(),
}))

// Use pre-built schemas
const { zodSchema, schema } = CommonSchemas.baseEntity

Security

API Key Authentication

createAgentDataMiddleware({
  registry,
  apiKeyValidator: async (key) => {
    return await validateApiKey(key)
  },
})

Scope-Based Access

// In component
useAgentData({
  id: 'sensitive-data',
  data: sensitiveData,
  scope: 'admin',  // Requires admin scope
})

// In middleware
createAgentDataMiddleware({
  registry,
  scopeValidator: async (scope, apiKey) => {
    const user = await getUserFromApiKey(apiKey)
    return user.scopes.includes(scope)
  },
})

Hide from Discovery

useAgentData({
  id: 'internal-data',
  data: internalData,
  discoverable: false,  // Not listed in /discover
})

Comparison

| Approach | Speed | Resources | Reliability | |----------|-------|-----------|-------------| | Playwright | ~2-5s | High (browser) | Fragile | | HTML Scraping | ~100ms | Low | Very Fragile | | Agent Data | ~10ms | Minimal | Stable |

License

MIT