@veridex/agents-react
A suite of focused hooks that each mirror exactly one runtime concern, plus a <AgentProvider> that holds the connection and run registry.
npm install @veridex/agents-reactProvider
import { AgentProvider } from '@veridex/agents-react';
export default function App({ children }) {
return (
<AgentProvider
endpoint="/api/agent" // your SSE/WS endpoint
getToken={async () => session.accessToken}
>
{children}
</AgentProvider>
);
}The provider negotiates SSE first, falls back to WebSocket. High-frequency events are batched at 30 Hz; consumers see settled state.
Hooks at a glance
| Hook | Mirrors | Use it for |
|---|---|---|
useRun | run lifecycle | Submit input, observe status, stream tokens |
useApprovals | ApprovalManager | Approval inbox; decide |
useTrace | EventBus | Inspector UIs, debugging |
useMemory | MemoryManager | Inspect, promote, revoke memory |
useContextHealth | ContextCompiler | Live utilisation and per-section tokens |
useSkills | skill registry | Toggle skills per run |
useBudget | metrics | Cost dashboards |
useCheckpoint | CheckpointManager | Restore points |
useSandboxStatus | sandbox | Running tools, resource usage |
useAgent | aggregator | Simple cases |
See Hooks Reference for full signatures.
Example: an approval inbox + budget dashboard
import { useApprovals, useBudget } from '@veridex/agents-react';
function Dashboard({ tenantId }: { tenantId: string }) {
const { pending, decide } = useApprovals({ scope: { tenantId } });
const { dollars, tokensIn, tokensOut } = useBudget({ scope: { tenantId, window: 'day' } });
return (
<Grid>
<Card title="Today's spend">${dollars.toFixed(2)} · {tokensIn + tokensOut} tokens</Card>
<Section title="Pending approvals">
{pending.map(req => (
<ApprovalCard key={req.id} request={req}
onAllow={(r) => decide(req.id, { decision: 'allow', reason: r })}
onDeny={(r) => decide(req.id, { decision: 'deny', reason: r })}
/>
))}
</Section>
</Grid>
);
}Principles
- One hook per concern. Compose at the app layer.
- Server-pushed, optimistically rendered. Trace events stream; submissions are optimistic.
- Strict typing. Payloads are the same
TraceEventshape as the server. - No hidden global state. Mount
<MockAgentProvider>in tests.